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
Memory Layer defines the following canonical types (the exact set the CLI, service, and search accept — kept in sync with the MemoryType enum by a parity test). You rarely need to set a type by hand: capture and curation classify most memories for you.
| Type | Use it for | Good canonical text says |
|---|---|---|
architecture | System structure, boundaries, and how components fit together | The component, its responsibility, and how it relates to the rest of the system. |
convention | Project conventions, style rules, and expected patterns | The rule, where it applies, and why it exists. |
decision | Architecture or process decisions | The selected choice, rejected alternatives if relevant, and rationale. |
incident | Outages, regressions, and their diagnosis and fix | What broke, the root cause, and how it was resolved. |
debugging | Non-obvious debugging findings and root-cause analyses | The symptom, the underlying cause, and the reasoning that connected them. |
environment | Environment, tooling, and local/CI setup facts | The setting, its value or constraint, and where it takes effect. |
domain_fact | Stable project facts — commands, routes, config locations, workflow rules | The fact, its scope, and the source of truth. |
documentation | Docs, screenshots, diagrams, public-site, or README work | What content changed and which audience it serves. |
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. |
implementation | Durable facts about how something is built | The mechanism, the key files or symbols, and the constraints that hold. |
refactor | Code reshaping without intended behavior change | What moved or changed structurally, what behavior should remain unchanged, and which old memories may need updates. |
user | Facts about the user — role, expertise, working preferences | What was learned about the person and how it should shape future work. |
feedback | A user correction or a confirmed approach | The preference or rule, and the context where it applies. |
project | Ongoing goals, deadlines, and initiatives not derivable from the code | The goal or constraint, and the motivation behind it. |
reference | External or internal reference material worth retrieving | The linked material and why it is useful. |
insight | A consolidated meta-memory synthesized from a cluster of related memories | The unifying concept plus the tensions, gaps, and implications the cluster reveals. See Consolidation. |
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.