Memory

This page is the operating reference for the memory system. For the conceptual tour — why the layers exist and what each one is for — start with Memory layers. Here the questions are practical: what exactly persists where on your disk, what an entry in the shared store looks like, how search behaves, and which curation moves are yours.

The organizing rule carries over from the concept page: a fact lives in the layer whose reach matches the fact's reach. Session-only knowledge stays in the session. Facts about you and your project go to auto-memory. A specialist's recurring lessons go to its own notebook. Fleet-wide findings go to the shared store. Reference documents go to the knowledge base. Plans and mission state live with the work.

What persists where

Paths are relative to your install root. Four of the six layers are plain Markdown you can open in any editor; only the shared store and the knowledge graph are databases, and both are local files and processes on your machine.

Auto-memory — the index and its topic files

Auto-memory is the main session's durable memory about you and your project. It ships as a scaffold at .claude/memory/MEMORY.md with a worked example you replace with your own content.

The design is index plus topic files, and the discipline matters because the index is loaded into context at the start of every session:

• MEMORY.md holds one line per memory — a pointer: the topic file's name, linked, followed by a one-line hook. Detail never lives in the index; it lives in the linked topic file, read on demand.
• Entries are grouped by topic (about you and the project · durable feedback on how to work · current-state pointers), not chronologically.
• The index has a hard size budget. When an entry grows into content, the fix is always the same: move the detail into a topic file and leave a one-line pointer behind.

Each topic file carries a small frontmatter block — a name, a one-line description (this is what a future session reads to decide relevance), and a type of user, feedback, project, or reference.

Update rules the main session follows, and that you can apply when editing by hand:

• A fact changed → edit the existing topic file in place.
• A genuinely new domain → create a new topic file and add one index line.
• A file went obsolete → update it to current state and note the date — rather than deleting it blind.
• The fact already lives in the operating contract (CLAUDE.md) → it does not belong here; duplicating it creates two sources of truth that drift.

Only the main, human-driven session writes this layer. Agents you dispatch cannot — which is what keeps "facts about you" clean.

Per-agent memory — the specialists' notebooks

Agents whose definitions carry a memory grant get their own folder under .claude/agent-memory/<agent>/, created the first time they write. The shape is identical to auto-memory — a lean MEMORY.md index plus topic files — but the content is that agent's craft: confirmed patterns (verified across more than one run), recurring issues kept as checklists, anti-patterns, and sets of files it has learned to check together.

Two rules keep this layer honest: one-off findings do not belong here (they go to the shared store), and a resolved recurring issue is marked resolved with a date rather than deleted — the resolution is itself knowledge.

The shared store — the fleet's collective memory

The shared agent-memory store is a local SQLite database that every agent can write to and search. It is the answer to a structural fact: two agents running in parallel cannot read each other's minds, so anything one learns that another might need must be written somewhere both can reach.

What an entry is

An entry is a structured record, not a note:

• content — the full finding, ideally with file-and-line references
• summary — one line, used when the entry is surfaced in future sessions
• entry type — one of pattern, finding, decision, bug_fix, audit_result, architecture, security
• domain and tags — filterable facets; tags are free-form
• file references — the paths (with line numbers) the finding is about
• project stamp — which project the entry belongs to (configurable; see the configuration reference)
• lineage — if the entry superseded an older one, the chain is kept

The three search modes

memory_search runs in one of three modes:

Semantic results are relevance-gated: a query with no genuine match returns nothing rather than a page of nearest-but-wrong entries. Matches carry a 0-to-1 relevance score so agents (and you, in the Memory view) can judge match strength, not just rank order.

The key in question is the Gemini key you bring — it powers embedding for writes and meaning-based search. Without it, keyword search, browsing, and metadata edits still work. The full cost picture is in BYO Claude & keys.

The write discipline and the curation verbs

The store is many-writer, so the platform enforces a discipline that keeps it signal rather than pile:

1. Search before writing. Every agent checks for an existing entry on the topic before adding one.
2. memory_add only when nothing covers the finding.
3. memory_supersede when a fact genuinely evolved — the old entry is marked superseded and chained to its replacement, never deleted. It disappears from search but keeps the history.
4. memory_update when the fact is right but a field is wrong — a correction in place, same entry, no lineage.
5. memory_delete removes an entry outright — junk, duplicates, test writes. This verb is curator-only: yours and the hygiene routine's, not the general fleet's.

Alongside search, agents use memory_recent (the latest live entries) and memory_tag_search (exact tag lookup) — reading recent and searching the task topic at session start is the habit that makes the whole layer pay off.

Curating from the Memory view

The Memory view is your window onto the shared store: browse and filter by type, domain, tag, and source; search in any of the three modes; inspect an entry's full content and its supersession chain; and correct, delete, or re-stamp entries. There is deliberately no "add entry" button — agents author this store; you curate it.

A shipped routine, memory-hygiene, supports the same job on a schedule: it scans for near-duplicate clusters and stale entries and proposes consolidations. It never merges or deletes on its own — recommendations only, you decide.

Durability — what happens if a store breaks

The shared store is the one memory layer that would be costly to lose, so it runs on the platform's standard durability machinery:

• Boot integrity check. Every start runs a corruption check. A corrupt file is quarantined — renamed aside, never deleted — and a fresh store is created so the system keeps working while the old file remains recoverable.
• Rolling online backups. Snapshots are taken safely while the store is in use (at boot when due, and periodically), pruned to a rolling window — the shared store keeps 14.
• Staged restore. Restoring a backup never overwrites a live database. You stage the restore; it is adopted the next time the owning process starts, and the replaced file is kept aside.

The Data Layer view (under Settings) lists every local store the platform owns — size, tier, backup count, last backup — and is where you toggle auto-backup, change retention, and stage or cancel restores. The file layers of memory need none of this: they are plain Markdown, and your normal backup or version-control habits cover them.

Where to go next

• Memory layers — the conceptual tour of the same system
• Knowledge graph — the document-and-graph layer at the same depth as this page
• Doctrine — the protocol that governs which layer holds which fact