Autonomous Memory
When a memory backend is enabled, the agent automatically extracts durable knowledge from past sessions and injects a compact summary into future sessions for the same project. Over time it builds a project-scoped memory store, technical decisions, recurring workflows, pitfalls, that carries forward without manual effort.
Backends
memory.backend selects the subsystem (default off):
| Value | What it is |
|---|---|
off | No memory subsystem runs. |
local | Local rollout-summarisation pipeline described on this page (MEMORY.md / memory_summary.md / generated skills). |
mnemopi | Local SQLite recall/retain backend with optional embeddings; the agent uses the recall, retain, and reflect tools. mnemopi.* settings tune it. |
hindsight | Vectorize Hindsight remote memory service. |
The rest of this page documents the local pipeline. Enable it via /settings or config.yml:
memory:
backend: local
Usage
What gets injected
At session start, if a memory summary exists for the current project, it is injected into the system prompt as a Memory Guidance block. The agent is instructed to:
- Treat memory as heuristic context: useful for process and prior decisions, not authoritative on current repo state.
- Cite the memory artifact path when memory changes the plan, and pair it with current-repo evidence before acting.
- Prefer repo state and user instruction when they conflict with memory; treat conflicting memory as stale.
A backend contributes in two places, and which one it uses matters for what a session costs you:
- The system prompt contains the guidance that does not change while the session runs. The provider caches the prompt as the prefix of every request, so this text is paid for once.
- The context tail carries whatever changes as you work: memories recalled for the current question, and the mental-model block when it reloads. These arrive as a message alongside your prompt.
The split exists because changing the system prompt mid-session invalidates the provider’s cache prefix, and the next request re-reads the whole conversation at the uncached rate. Writing a recalled memory into the prompt made every recall cost a full re-read of everything before it. The model sees the same text in the same order either way.
A block is sent once. If a reload finds the same memories, nothing is sent, so the context does not grow by a copy of your memories every turn.
/memory view shows both halves together, so what you read there is what the model gets.
Reading memory artifacts
The agent can read memory files directly using memory:// URLs with the read tool:
| URL | Content |
|---|---|
memory://root | Compact summary injected at startup |
memory://root/MEMORY.md | Full long-term memory document |
memory://root/skills/<name>/SKILL.md | A generated skill playbook |
/memory slash command
| Subcommand | Effect |
|---|---|
view | Show the current backend injection payload |
stats | Show backend-specific memory statistics, when supported |
diagnose | Show backend-specific diagnostics, when supported |
clear / reset | Delete active backend memory data/artifacts |
enqueue / rebuild | Force consolidation/retention work for the active backend |
mm list | List mental models on the active bank |
mm show <id> | Show one mental model |
mm refresh [id] | Refresh auto-refresh models bank-wide, or one model by id |
mm history <id> | Diff the change history of a mental model |
mm seed | Create any built-in mental models that are missing |
mm delete <id> | Delete a mental model from the bank |
mm reload | Re-pull the cached <mental_models> block |
How it works
Local summary memories are built by a background pipeline that runs at startup; /memory enqueue marks consolidation work that the next startup picks up. The pipeline is skipped for subagents and for sessions that are not persisted to a session file.
Phase 1, per-session extraction: For each past session that has changed since it was last processed, a model reads the session history and extracts durable signal: technical decisions, constraints, resolved failures, recurring workflows. Sessions that are too recent, too old, currently active, or beyond the configured scan/age limits are skipped. Each extraction produces a raw memory block and a short synopsis for that session.
Phase 2, consolidation: After extraction, a second model pass reads all per-session extractions and produces three outputs written to disk:
MEMORY.md: a curated long-term memory documentmemory_summary.md: the compact text injected at session startskills/: reusable procedural playbooks, each in its own subdirectory
Phase 2 uses a lease and heartbeat to prevent double-running when multiple processes start simultaneously. Stale skill directories from prior runs are pruned automatically.
Consolidated output is redacted for common secret/token patterns before MEMORY.md, memory_summary.md, or generated skills are written to disk.
Extraction behavior
Memory extraction and consolidation behavior is driven by static prompt files in packages/coding-agent/src/prompts/memories/.
| File | Purpose | Variables |
|---|---|---|
stage_one_system.md | System prompt for per-session extraction | n/a |
stage_one_input.md | User-turn template wrapping session content | {{thread_id}}, {{response_items_json}} |
consolidation_system.md | System prompt for cross-session consolidation | n/a |
consolidation.md | User-turn prompt for cross-session consolidation | {{raw_memories}}, {{rollout_summaries}} |
read-path.md | Memory guidance injected into live sessions | {{memory_summary}}, {{learned}} |
Model selection
Memory piggybacks on the model role system.
| Phase | Role | Purpose |
|---|---|---|
| Phase 1 (extraction) | default | Per-session knowledge extraction |
| Phase 2 (consolidation) | smol (falls back to default, then current/first registry model) | Cross-session synthesis |
If the requested memory role is not configured, memory model resolution falls back to the default role, then the active session model, then the first model in the registry.
Configuration
| Setting | Default | Description |
|---|---|---|
memory.backend | off | Select local for this pipeline; legacy memories.enabled: true is migrated to memory.backend: local when no explicit backend is set |
memories.maxRolloutAgeDays | 30 | Sessions older than this are not processed |
memories.minRolloutIdleHours | 12 | Sessions active more recently than this are skipped |
memories.maxRolloutsPerStartup | 64 | Cap on sessions processed in a single startup |
memories.summaryInjectionTokenLimit | 5000 | Max tokens of the summary injected into the system prompt |
Additional tuning knobs (concurrency, lease durations, token budgets) are available in config for advanced use.
Key files
packages/coding-agent/src/memories/index.ts: pipeline orchestration, injection, clear/enqueue entry points (the/memorycommand routes here viapackages/coding-agent/src/memory-backend/local-backend.ts)packages/coding-agent/src/memories/storage.ts: SQLite-backed job queue and thread registrypackages/coding-agent/src/prompts/memories/: memory prompt templatespackages/coding-agent/src/internal-urls/memory-protocol.ts:memory://URL handler