coulomb/agentic-resources
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Implement AGENTIC-WP-0011 kaizen correlation follow-up

Browse Source 
Add bidirectional doc links (PRD §9.1, README, DESIGN §11), session-close
HELIX_* env convention, stable digest JSON contract, and digest_lookup CLI
for read-only correlate lookups. All tasks done; 163 tests green.
This commit is contained in:
Bernd Worsch
2026-06-19 20:27:00 +02:00
parent 292b656952
commit 01d2affc3b
6 changed files with 279 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
docs/DESIGN-session-memory.md
View File

@@ -394,10 +394,65 @@ into Helix Forge.
**Related kaizen-agentic docs:** [ADR-004 project metrics convention](https://gitea.coulomb.social/coulomb/kaizen-agentic/src/branch/main/docs/adr/ADR-004-project-metrics-convention.md),
[wiki/EcosystemIntegration.md](https://gitea.coulomb.social/coulomb/kaizen-agentic/src/branch/main/wiki/EcosystemIntegration.md).
### 11.1 Session-close env export (dual-layer agents)
Agents that run **both** Helix Forge capture and kaizen `metrics record` should
export the following **after** the ingest sweep has written the session digest
(`python -m session_memory.ingest` or an equivalent Stop/SessionEnd hook). Names
match kaizen-agentic ADR-004 — do not invent parallel aliases.
| Variable | Source in Helix Forge | Purpose |
|----------|----------------------|---------|
| `HELIX_SESSION_UID` | `Session.session_uid` | Primary correlation key → `helix_session_uid` |
| `HELIX_REPO` | `digest.repo` | Project/repo scoping |
| `HELIX_FLAVOR` | `digest.flavor` | Agent runtime (`claude` / `codex` / `grok`) |
| `HELIX_TOKENS` | `digest.cost.input_tokens + digest.cost.output_tokens` | Token rollup → `tokens` |
| `HELIX_INFRA_OVERHEAD_SHARE` | infra bucket share over `tool_histogram` (see `measure.metrics.session_metrics`) | MCP/plumbing overhead → `infra_overhead_share` |
Example (after digest exists):
```bash
export HELIX_SESSION_UID="claude:abc-123"
export HELIX_REPO="agentic-resources"
export HELIX_FLAVOR="claude"
export HELIX_TOKENS=125000
export HELIX_INFRA_OVERHEAD_SHARE=0.117
# optional — lets kaizen correlate without guessing the store location:
export HELIX_STORE_DB="$(pwd)/session_memory/.store/mem.db"
kaizen-agentic metrics record # merges HELIX_* when present
```
### 11.2 Digest store location and read API
- **`HELIX_STORE_DB`** — absolute path to the SQLite file holding Tier 2 digests.
Defaults to `config.toml` `[store].db_path` (`session_memory/.store/mem.db` relative
to the repo root). Export as an absolute path when setting the variable on session
close so `metrics correlate` works across hosts and working directories.
- **Thin CLI** — `python -m session_memory.digest_lookup <session_uid> [--json]`
prints one digest without running ingest. Exit `0` on hit, `1` when missing.
- **Programmatic** — `Store.get_digest(session_uid)` returns the JSON blob written
by `build_digest` / `analyze`.
**Stable digest JSON shape** (fields consumers may rely on):
| Field | Type | Notes |
|-------|------|-------|
| `session_uid` | string | Normalized uid (`<flavor>:<native-id>`) |
| `flavor`, `repo`, `domain` | string | Session attribution |
| `model` | string | Model id when known |
| `started_at`, `ended_at` | string | ISO timestamps |
| `outcome` | string | `success` / `fail` / `abandoned` / `unknown` |
| `cost` | object | `input_tokens`, `output_tokens`, `cache_tokens`, `wall_clock_s`, `turns`, `retries` |
| `tool_histogram` | object | Tool name → call count |
| `event_count`, `kind_counts`, `markers` | object/int | Compact activity summary |
| `first_prompt`, `last_assistant` | string | Short text snippets |
| `error_snippets` | array | `{fingerprint, sample, count, tool}` entries |
| `schema_version` | int | Digest schema version |
---
*Next step: [AGENTIC-WP-0002] implements Phase 0 — the schema, the Claude
collector, the Tier1/Tier2 store, and the budget-based eviction sweep.*
*Implemented:* Phases 0–4, weekly retro ([AGENTIC-WP-0002]–[AGENTIC-WP-0010]);
kaizen correlation follow-up ([AGENTIC-WP-0011]).
## Sources

28
docs/PRD-helix-forge.md
View File

@@ -5,7 +5,7 @@
**Status:** Draft v0.1
**Author:** Claude (drafted with Bernd Worsch)
**Created:** 2026-06-06
**Updated:** 2026-06-06
**Updated:** 2026-06-19
---
@@ -223,6 +223,32 @@ record:
- The hub remains a **read model**; Helix Forge writes its durable artifacts as files
and lets the hub index them.
### 9.1 Downstream: kaizen-agentic project metrics correlation
Helix Forge is a **fleet-level** producer of normalized session digests. The
**kaizen-agentic** framework is a **project-scoped** consumer of optional
correlation fields on its execution metrics (ADR-004). The two layers link
**by reference** — kaizen-agentic does not re-implement JSONL ingestion or write
into the Helix Forge store.
| Layer | Owner | What it stores |
|-------|-------|----------------|
| Fleet | agentic-resources (`session_memory`) | Per-session digests in the local SQLite store |
| Project | kaizen-agentic | `.kaizen/metrics/<agent>/executions.jsonl` |
**Canonical spec in this repo:** [DESIGN-session-memory.md §11](DESIGN-session-memory.md#11-project-metrics-correlation-kaizen-agentic)
(session-close env export, digest read path, stable JSON shape).
**Authoritative cross-repo contract (kaizen-agentic):**
[Helix Forge Correlation Contract](https://gitea.coulomb.social/coulomb/kaizen-agentic/src/branch/main/docs/integrations/helix-forge-correlation.md).
Field mapping: `Session.session_uid` → `helix_session_uid`; digest token totals →
`tokens`; MCP/tool overhead share → `infra_overhead_share`.
**Read path for consumers:** `HELIX_STORE_DB` points at the digest SQLite file
(default `session_memory/.store/mem.db`); `python -m session_memory.digest_lookup
<uid> --json` or `kaizen-agentic metrics correlate <uid>` performs a read-only
lookup. No ingestion code belongs in kaizen-agentic.
## 10. Success Metrics
| Metric | Meaning | Target (directional, v1) |