| name | memory |
| description | Memory-MCP integration for o9k. Use at session start (load the project briefing), when the user references past work ('the bug we had', 'where did we leave off'), before compaction or /clear (flush state), and when deciding what deserves persisting. Works with TIM (npm tim-cli) or hmem (npm hmem-mcp); hooks pick TIM when both are present. |
memory — Sessions Never Start From Zero
A memory MCP turns the most expensive part of every session — re-establishing
context — into one cheap call. Supported backends:
Both follow the same token discipline below. Choose (or switch) via
/o9k-init. Custom MCPs can be wired manually; o9k-memory hooks only
auto-drive TIM and hmem.
No memory MCP configured? Point the user at /o9k-init (or
npm i -g tim-cli && tim init / npm i -g hmem-mcp && hmem init), then
continue without memory features.
Session start — briefing, not history
- Call the project-loading tool (
load_project or equivalent) ONCE.
- Budget: the injected briefing must stay in the low hundreds of tokens —
summaries and IDs, never full entries or raw history.
- Everything deeper is on-demand: drill into an entry only when the current
task needs it (progressive disclosure — you pay for what you read).
During the session
- User references the past without an ID ("letzte Woche", "the schema we
chose", "that auth bug") → search memory BEFORE asking the user or grepping
the repo. Prefer dispatching the search (see
dispatch) so candidate entries
never load into the main context.
- Something durable happened — a decision with a reason, a lesson from a
failure, an error and its fix, a milestone → write it now, compactly:
one-line summary on top, detail below. Do not transcribe the conversation.
- Don't duplicate: search before writing; extend the existing entry instead
of creating a twin.
Before context dies — the flush
Approaching compaction, /clear, or session end:
- Persist open state: what was done, what's in progress, the exact next step.
- Persist anything said-but-not-saved that survives the "will a future session
need this?" test.
- THEN allow compaction/clear. Compaction summaries are lossy; memory is not.
What memory replaces (arbitration)
With a memory MCP active: project context does NOT belong in an ever-growing
CLAUDE.md, plans do NOT get pasted into every session, and "catch-up" re-reads
of the codebase are a bug, not diligence. CLAUDE.md keeps only durable rules;
state lives in memory (or in beads, if installed — see using-o9k arbitration).
