agent-memory

agent-memory

Purpose: turn the policy in src/core/rules/memory.md into mechanical recipes the agent can execute. The rule answers when and what; this skill answers how — the exact tool signatures, what is automatic vs explicit, and what the return envelopes look like. Every signature here is verified against src/core/thinking_os/server.py; a CI drift-guard test fails if any drifts.

Read when: recalling from memory (cos_search, cos_details, cos_timeline, cos_learn_suggest), running the learning loop (cos_learn_extract / cos_learn_validate), or understanding how observations get captured.

Skip when: the query target is current code (use graph-explorer) or current docs (use cos_doc_search per search). Memory is the third-priority retrieval layer.

The mental model — writes are automatic, you mostly READ

The single most important fact: you do not hand-author observations. Memory is written automatically by PostToolUse capture hooks — every Write/Edit/MultiEdit derives a sanitized, deduped, impact-scored observation (capture.py), and separate hooks capture tool failures and session events. Confidence on learned patterns is system-computed by brain-inspired LTP/LTD formulas, not a number you set. The agent's job is to read memory in the Orient phase and reinforce patterns via the learn loop. There is no freeform record(title, body, confidence) tool — by design.

The Decision Gate — before any memory call

Question                                  → Layer + Tool
─────────────────────────────────────────────────────────
"Where is function X defined?"            → graph    cos_graph_query
"What does spec Y say?"                   → docs     cos_doc_search
"What's in flight / blocked?"             → tasks    cos_task_board
"Have I seen this pattern before?"        → memory   cos_search
"Why did we choose approach Z?"           → memory   cos_search (memory_type=decision)
"Which patterns apply to my task?"        → memory   cos_learn_suggest(domain=, complexity=)
"What changed in the last N days?"        → memory   cos_timeline(days=N)
"How does X work / who calls X / rename"  → graph    cos_graph_* (graph/code FIRST)
"Not sure which layer"                    → default to graph/code; memory only for cross-session recall