Memory types
Memory types make search and curation more precise. A type describes why a memory exists and how agents should use it, not just what words appear in the canonical text.
Type reference
| Type | Use it for | Good canonical text says |
|---|---|---|
task | Completed implementation, debugging, release, migration, or operational work | What was done, where, why it matters, and how it was verified. |
plan | Approved implementation plans and active work checkpoints | The intended work, constraints, status, and remaining checklist items. |
fact | Stable project facts, commands, routes, config locations, or workflow rules | The fact, scope, and source of truth. |
decision | Architecture or process decisions | The selected choice, rejected alternatives if relevant, and rationale. |
feedback | User preference or correction | The preference and the context where it should apply. |
reference | External or internal reference material worth retrieving | The linked material and why it is useful. |
documentation | Docs, screenshots, diagrams, public-site, or README work | What content changed and which audience it serves. |
refactor | Code reshaping without intended behavior change | What moved or changed structurally, what behavior should remain unchanged, and which old memories may need updates. |
What makes a memory good
A good memory is short, inspectable, and useful without reading the original chat. It should include:
- a durable claim
- the project or subsystem scope
- evidence such as files, commits, commands, tests, or user prompts
- confidence when the fact may drift
- enough context for a future agent to act safely
Weak memories usually record activity without meaning, for example “looked at runtime.rs” or “ran tests”. Strong memories explain the durable outcome, for example “CLI command parsing moved into support modules; runtime.rs now keeps shared command types and dispatch helpers.”
Refactor memories
Refactor memories are for structural code changes that intentionally avoid functional changes. They matter because old memories often cite old file paths, module names, or code ownership boundaries.
When a refactor memory is captured, curation should look for existing memories that mention affected paths, symbols, modules, or ownership boundaries. Those memories should be updated, invalidated, or replaced if the refactor changes how a future agent should navigate the codebase.
Examples:
| Refactor | Memory impact |
|---|---|
| Split a large CLI command file into modules | Update memories that say the old file owns all command logic. |
| Move service handlers behind repository interfaces | Update architecture memories about direct DB access. |
| Rename a TUI app state module | Update instructions that point agents to the old module. |
| Extract web controller hooks | Preserve behavior claims, but update code navigation facts. |
Replacement proposals
When a new memory appears to supersede an older one, Memory Layer can create a proposal instead of overwriting automatically. The Review tab and memory proposals command show the target memory, candidate replacement, reason, policy, and evidence so a human can approve or reject it.
Approve when the candidate is clearer, more current, and better supported. Reject when the old memory remains valid or the candidate is too speculative.