# Autonomous Memory When the local 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. Disabled by default. Enable the local summary pipeline via `/settings` or `config.yml`: ```yaml memory: backend: local ``` ## Usage ### What gets injected At session start, if a consolidated summary or manually captured lesson exists for the current project, it is injected into the system prompt as a **Memory Guidance** block. The summary and lessons share `memories.summaryInjectionTokenLimit`. - 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. ### 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/learned.md` | Lessons captured by the `learn` tool | | `memory://root/skills//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 | ### Capturing lessons Enable `autolearn.enabled` to make the `learn` tool available: ```yaml autolearn: enabled: true ``` With the local backend active, `learn` saves explicit durable lessons to the project's `learned.md`. Lessons are newest-first, deduplicated, secret-redacted, capped at 100 entries, and injected starting with the next session; a `learn` call does not mutate the active session's prompt-cache prefix. Each lesson's content is capped at 2,000 characters and optional context at 400 characters. Structured memory search, `recall`, `retain`, `reflect`, and `memory_edit` are not available for the local backend. ## 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 generated outputs written to disk: - `MEMORY.md` — a curated long-term memory document - `memory_summary.md` — the compact text injected at session start - `skills/` — reusable procedural playbooks, each in its own subdirectory The separately maintained `learned.md` is not overwritten by consolidation. 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 | — | | `stage_one_input.md` | User-turn template wrapping session content | `{{thread_id}}`, `{{response_items_json}}` | | `consolidation_system.md` | System prompt for cross-session consolidation | — | | `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.threadScanLimit` | `300` | Maximum recent session records scanned at startup | | `memories.maxRawMemoriesForGlobal` | `200` | Maximum per-session extractions supplied to global consolidation | | `memories.stage1Concurrency` | `8` | Concurrent per-session extraction jobs | | `memories.stage1LeaseSeconds` | `120` | Extraction job lease duration | | `memories.stage1RetryDelaySeconds` | `120` | Delay before a failed extraction becomes claimable again | | `memories.phase2LeaseSeconds` | `180` | Consolidation lease duration | | `memories.phase2RetryDelaySeconds` | `180` | Delay before failed consolidation is retried | | `memories.phase2HeartbeatSeconds` | `30` | Consolidation lease heartbeat interval | | `memories.rolloutPayloadPercent` | `0.7` | Fraction of the selected model's context budget available to rollout payloads | | `memories.phase1InputTokenLimit` | `4000` | Per-session extraction input cap | | `memories.fallbackTokenLimit` | `16000` | Model token budget used when the model has no finite declared context window | | `memories.summaryInjectionTokenLimit` | `5000` | Shared approximate token cap for the summary and captured lessons injected into the system prompt | ## Key files - `packages/coding-agent/src/memories/index.ts` — pipeline orchestration, injection, clear/enqueue entry points (the `/memory` command routes here via `packages/coding-agent/src/memory-backend/local-backend.ts`) - `packages/coding-agent/src/memories/storage.ts` — SQLite-backed job queue and thread registry - `packages/coding-agent/src/prompts/memories/` — memory prompt templates - `packages/coding-agent/src/internal-urls/memory-protocol.ts` — `memory://` URL handler