capture what a session learned without asking it to

[ayushcodes10]

The measurement

From 2026-08-23 to 2026-09-02 the session-start briefing told every session in every project:

N memory file(s) are queued but not yet recorded as facts. Run echo-memory pending, read each, and write_episode what it states.

In that window 16 memory files were written across eigen and dugout. The capture hook noticed all 16. None became facts in the session that wrote them — they were ingested by hand, ten days late, from a different project.

The instruction was correct, specific, and lost 16 times out of 16. It was competing with Claude Code's own file-based memory, which is a permanent system-prompt section present on every turn, while this was one reminder at session start among several hundred registered tools. Everything that worked in that window was a hook.

What changed

Stop hook — scripts/session-stop-hook.sh, cli/stop_gate.py. Returns {"decision": "block"} when this project still owes the graph, handing the agent the file list as its next instruction. It fires at the one moment the agent still holds the context to say what it learned and is no longer mid-task. Bounded three ways so it doesn't become the hook people disable:

• once per session (stop_hook_active), so a nudge never becomes a loop
• scoped to the current project — eigen's backlog can't hold an echo-mem session open
• silent when the queue is clean, which is the steady state

echo-memory reconcile — reads the filesystem instead of trusting that the hook fired. Three eigen files were found holding content the queue had never seen; nothing detected it, because a queue only knows what it was told. Runs from SessionStart and again inside the stop gate, so a missed capture self-heals. Deliberately the same scope as the capture hook — if the two disagreed, the sweep would either keep reopening files the hook ignores or keep missing files it queues.

echo-memory install-hooks — registers all five hooks in one command instead of four JSON blocks merged by hand. That shape half-completes silently, and a machine missing one hook is indistinguishable from a machine missing none. Entries are matched by marker and by script name, so the first run on an existing machine upgrades the hand-merged hooks rather than doubling them (every hook firing twice, every file noticed twice).

Migration 0009 — read_event has carried group_id since it shipped one day ago, which is the same string for every Claude Code session in every repo. Asked "did the eigen sessions read memory?", the table had no answer: 12 rows, all identically labelled. It now records project and session_id, both nullable, because an unattributed read is worth more than an exception between the user and the agent.

Testing

• 387 existing tests pass; 26 added
• migration 0009 verified to apply and reverse from a fresh process — the standalone path that let 0007 pass CI while broken
• gate tests cover the real bug shape: a file ingested, then edited by a session whose hook didn't fire

Scope

The Stop gate only reaches clients that support hooks, so it helps Claude Code and not Claude Desktop. That limit is real and unchanged by this PR.