Memory layers

An agent session starts blank. Everything Command Center "remembers" is remembered because something wrote it down — and the platform gives that writing-down a deliberate structure: a set of memory layers, ordered by reach. A fact lives in the layer whose reach matches the fact's reach, and no wider.

This page gives you the map. You will not manage most of it by hand; you will notice its effects — agents that stop re-discovering the same things, sessions that pick up where the last one left off, a fleet that gets sharper over time.

The rule that organizes everything

Match the fact to the layer. A finding useful only for the current task stays in the session and is forgotten. A fact about you or your project that every future session needs goes to the main session's own memory. A pattern one specialist agent keeps rediscovering goes into that agent's private notebook. A finding any agent might need goes into the shared, searchable store. A reference document worth querying goes into the knowledge base. Plans and mission state live with the mission.

Wrong-layer writes create noise; missing writes lose knowledge. The platform's memory protocol exists to prevent both — agents follow it automatically.

The layers you will actually notice

Session memory is the agent's working context — fast, free, and forgotten when the conversation ends. The practical lesson: never expect an agent to remember across runs unless a longer-lived layer captured the fact.

Auto-memory is the main session's durable memory about you and your project: your preferences, stable project facts, pointers to key files. It is a lean Markdown index plus topic files, loaded at the start of every session. Only the main, human-driven session writes here, which keeps it clean. This is why you rarely have to re-explain how you like to work.

Per-agent memory gives individual specialists a private notebook. An auditor accumulates the bug classes it keeps finding; a research agent accumulates method lessons. Each agent's notebook rides along across its runs, so the fleet improves without you re-teaching it.

Where these two live — the one split worth knowing

They look alike in the Memory view and they sit in different places on disk.

Per-agent notebooks live in your workspace, under .claude/agent-memory/, one folder per agent. Copy the workspace and they come with it.

Auto-memory does not. The agent CLI keeps its per-project memory under your user home, in its own per-project folder keyed to the workspace path — Command Center reads and writes it there through a separate, narrowly-scoped path rather than through the ordinary workspace file access. Two consequences follow, and both are practical:

• It does not travel with the workspace. Copying or moving the folder carries your documents, agent notebooks, protocols and identity; auto-memory stays behind on the machine that wrote it. Take it deliberately if you want it.
• It is keyed to the workspace path. Move the workspace and the main session starts from a clean auto-memory for the new location. Nothing is lost — the old files are still there under the old key — but they are no longer the ones being loaded.

Shared agent memory is the fleet's collective store — structured findings, decisions, and patterns any agent can write and every future agent can search. It is searchable two ways: by keyword (exact names, paths, error strings) and by meaning (semantic search), with a combined mode as the default. A no-match query returns nothing rather than noise. You can browse and curate this store yourself in the Memory view.

The knowledge base is where reference documents live — ingested into the knowledge graph so agents can find and traverse them. It is a large enough subject to have its own page.

Plans and mission state persist with the work itself: mission folders, operation briefs, and the blackboard files hold multi-step state until the work completes. Two agents running in parallel cannot read each other's minds — they coordinate through these shared, written layers, never implicitly.

Mostly files, deliberately

Most of the memory system is plain Markdown on disk — auto-memory, per-agent notebooks, plans, and the blackboard are all files you can open, read, and edit. All of them sit in your workspace except auto-memory, which sits beside the agent CLI's own per-project state as described above. Only two layers are databases, and both are local: the shared store (a local search index) and the knowledge graph. Nothing leaves your machine.

Cost follows the same shape. Browsing and keyword search of shared memory work with no extra key at all. Semantic (by-meaning) search and new semantic writes use an optional Google Gemini embedding key that you bring — a single, cheap dependency that upgrades retrieval quality, not a requirement for the system to function. See BYO Claude & keys for the full cost picture.

Why this matters to you

• Less repetition. Preferences and project facts persist where every session finds them.
• Compounding agents. Specialists keep private lessons; the fleet shares confirmed findings.
• Inspectable memory. You can read what the system believes — most of it in a text editor, the shared store in the Memory view — and correct it by editing or curating.

Where to go next

• The knowledge graph (Cortex) — the document-and-entity layer of memory
• Your workspace & documents — the file tree the memory layers live in
• Memory infrastructure — the deeper reference for each layer