Hook memory (/tmp/specs, ,agent-memory)

Ephemeral session memory: inject context at start, record tool events to a crash-safe worklog, bind sessions to named topic buckets. Shared hooks deploy to ~/.agents/hooks/; harness adapters differ — see Runtime recall wiring.

Piece	Role
session_context.py	Session start: topic index/spec, worklog tail
worklog_dispatcher.sh → worklog_recorder.py	Post-tool: async JSONL append
perturn_recall.py + correction_detector.py	Per-prompt: topic binding, bounded reinforcement, correction capture; root-only filtered KB staging
/tmp/specs/<workspace>/	Specs, worklogs, bindings (outside chezmoi/worktrees)
,agent-memory	Standalone ~/lib/,agent-memory/ control plane
spec_mirror.py	Reboot survival → ~/.local/state/agent-specs/

Topic lifecycle

Shared branches (main, master, dev, develop, trunk) with no session binding: session start injects a ### Topic Buckets index (newest first). Agent binds when exactly one bucket matches, creates when none match, asks when several match. Add summary: <one-line> to specs for scannability.

Feature/topic worktrees keep current continuity instead of the bucket index.

,agent-memory commands

Command	Effect
status [--session-id <id>]	Selected topic; --json adds session_key for adapters
select <topic> --session-id <id>	Bind session; flush pre-bind session-* events into topic worklog; print clean-room context; never changes another session's bucket
select <topic> --create --session-id <id>	New bucket + bind
note <kind> "<text>" [--ref <anchor>]	Structured worklog entry (capsule kinds + question/decision); surfaces in ,ai-kb harvest
merge <src> <dest> [--dry-run]	Fold duplicate: flush queues, merge worklogs (200-line cap), rewrite bindings, delete source .no_context
use <topic>	Legacy workspace pointer (rejects current)
wipe-current [--session-id <id>]	Delete spec/worklog/sentinel; default branch → latest session-*

Harvest and corrections

,ai-kb harvest --session-id <id> mines the bound worklog for durable candidates (notes, failure→fix, recurring errors, repeated commands). Flushes pending queues first; exits nonzero if pending/error state remains. Never writes capsules — see AI knowledge base.

It also carries the probe-budget hint: ,probe fail appends to <spec_dir>/<session_key>.probe-ledger.jsonl (failures only, chained onto the failing command), and 3+ fails among the last 8 entries recorded within 30 minutes inject a "re-read the source" note on the next prompt. Shell-recorded probes land under the ad-hoc key, which the reader consumes as a fallback under the same 30-minute window. The pi/omp ai-kb-recall.ts mirrors implement the same consumer, and Antigravity receives the note through the premise-nudge PreInvocation drain.

Clean session / clean-room

Disable hook-injected task context with AGENT_HOOK_CONTEXT=0, _no_session_context (workspace), or <topic>.no_context. Pi/OMP check this on every turn, including fallback and compaction paths; removing the flag restores current-topic injection. Worklog capture and native SOP loading remain active.

Rule	Why
Oversized specs omitted with pointer	No partial memory
Whole recent worklog entries only	No half-events
Worklog trim during queue flush	Bounded injection, no lost writes
Per-session bindings	Parallel sessions join or isolate safely
Review topics clean-room by default	Reduce re-review bias

Review topics (review* name or PR in first target:): strip prior verified facts/findings/verdict and worklog tail before size check. Plain and Markdown ATX conclusion headings receive the same treatment. Text over bound is omitted wholesale, never truncated. Worklog bounds include the omission notice; an oversized row is omitted intact and the source file remains unchanged.

session_context.py and ,agent-memory select apply the same clean-room rules independently (mirrored code — change both together).

Design contract

Hooks observe and inject; they never re-prompt. No hook on stop. Evidence anchoring and durable-learning capture are SOP habits (~/AGENTS.md §2–§4), not hook-enforced.

Internals

State layout under /tmp/specs/<workspace>/:

_active_topic.txt
.session-topic-<session-id>.txt
<topic>.txt / <topic>.worklog.jsonl
.worklog-queue-v1/<session-key>/  .worklog-locks-v1/

Contract	Behavior
Ordering	Atomic sequence files and stable worklog_id/session_key/worklog_seq make replay idempotent; activity and target locks keep harvest complete and shared-topic logs ordered
Bounds	At most 256 pending events or 1 MiB per session; each worklog retains 200 complete JSONL records
Lifecycle	The tool-call recorder flushes synchronously with no idle wait; the background flusher exits after 80 ms idle or two seconds total; seven-day cleanup covers drained queue/error state plus stale session-* worklogs and .recall-seen-*/.recall-candidates-*/.recall-staged-*/.recall-pointed-*/.recall-warm-* files
Failure behavior	Tool calls fail open; startup warns about queue errors; harvest refuses pending/error state
Copilot subagents	COPILOT_AGENT_SESSION_ID routes writes to the parent session key; startup/read injection remains isolated
Durable memory	Automatic filtered root retrieval/staging; one admission pointer per binding. Corrections feed notes; verified learning is persisted in a final batch. Leaves do not orchestrate memory.
Reboot survival	spec_mirror.py mirrors named topics and _active_topic.txt to ~/.local/state/agent-specs/, restores missing topic files without overwriting live edits, and excludes current/session-*. Removing a live topic’s .no_context retires its mirrored flag; losing the whole topic restores its flag with the topic. Wipe/merge forget topic copies, and explicit --reset-active also removes the mirrored selection

Sources and verification

• executable_,agent-memory launches ~/lib/,agent-memory/. Its three modules render the canonical scripts/agent_memory.py, spec_mirror.py, and worklog_queue.py; deployed use requires neither the repository nor CHEZMOI_SOURCE_DIR.
• exact_hooks/, scripts/spec_mirror.py

python3 scripts/tests/test_agent_hooks.py
python3 -m unittest discover -s scripts -t scripts -k test_recall_worklog
python3 -m unittest discover -s scripts -t scripts -k test_agent_memory
,agent-memory status --session-id <id>

Staged workflow integration

Startup and per-turn retrieval stage complete filtered candidates without injecting capsule bodies. The root owns admission and the final durable-learning batch; correction hints retain structured notes without triggering convergence or a per-correction scribe.

The active topic also holds compact stage handoffs and terminal packet IDs. Reuse completed memory results after compaction; do not relaunch them. The existing fast-depth and context-disable controls still suppress retrieval. No-delegation sessions retain recall and learning through the skill's inline fallback.