THE SIGNAL BRIEF
AGENTS · HARNESS · MEMORY · CLAUDE-CODE

Claude Code has six kinds of memory. My session used none of them

November 8, 2026

For a full day, a Claude Code cloud session helped me write this series. By the evening it knew my blog's structure, my verification rules, the people and projects involved, and how I like my LinkedIn posts. Then I looked for what it had remembered. The answer was nothing. No memory folder, no memory file, no memory event in the transcript.1

The only thing that carried knowledge from the morning to the evening was the compaction summary (a coming post in this series covers how compaction works), and it carried one thing wrong: it turned a habit of mine into a standing rule.2

So this post is about what memory would have done. Claude Code 2.1.319 has more of it than the docs suggest, and its instructions to the model are some of the most carefully written text in the binary.

A note before you read. I wrote this draft from the inside: the binary, the docs, the transcript of my own session. I was not planning to publish it today. Then I found Anthropic's research post on the same subject, "The components of agent memory".3 It is dated November 6; I wrote my draft on November 7 without knowing it existed, and read it the day after. I find the pairing curious. On one side, what you can learn by reading the code an agent runs on. On the other, what its makers choose to explain. Where the two agree, you can trust the picture more. Where they differ, you learn something about the product. It is a new way to learn how a tool works, and to learn to use Claude Code better. I kept the draft as it was and added what the research post changes, at the end.

Why my session had no memory

The binary answers in one line of logic. Auto memory resolves to "off" when the session runs remotely (CLAUDE_CODE_REMOTE is set) unless a memory folder has been provided for it.4 My cloud session had the remote flag and no memory folder. Memory was not broken. It was off by design.

That is a defensible default. A cloud container is thrown away when the session ends; a memory folder written there would vanish with it, or worse, would need somewhere to live that the user never chose. But nothing in the session told me memory was off, and the compaction summary quietly played its role.

Six layers

Reading the docs and the binary together, I count six layers of memory.

CLAUDE.md, written by you. Three scopes: your user file, the project's, and a local one you keep out of git. The docs are honest about its status: "Claude treats them as context, not enforced configuration."5 And it is delivered "as a user message after the system prompt, not as part of the system prompt itself."6

Organization-managed memory. "CLAUDE.md-style instructions injected as organization-managed memory", accepted only from managed or policy settings.7

Auto memory, written by Claude. Notes "Claude writes itself based on your corrections and preferences".8 An index, MEMORY.md, of which "The first 200 lines [...] or the first 25KB, whichever comes first, are loaded at the start of every conversation."9 The topic files behind it are read on demand. By default it lives in your home directory, per project, and a checked-in project setting cannot move it: that setting is "Ignored if set in projectSettings (checked-in .claude/settings.json) for security."10 A repository you clone cannot redirect where Claude writes about you.

Team memory. A second folder next to the private one, for what the whole team should know.11

Agent memory. Each subagent type can have its own memory, at user, project or local scope.12 The main conversation's auto memory "isn't loaded into subagents".13

Memory stores. The newest layer, and the least documented. In the binary, the SDK calls an Anthropic API, /v1/memory_stores, under a beta dated agent-memory-2026-07-22.14 A store has an id, a description, a read-only or writable flag and an index document. The CLI keeps local memory files and the remote store in sync, with conflict rules: "memory deleted locally but changed remotely; restoring the remote version."15 The sandbox even ships a filesystem backend for it, so a store can be mounted as a folder.16

And in Cowork, a seventh source joins: a snapshot of "the user's claude.ai memory that the client showed its model" is written into the transcript.17

Four types, and who gets to see them

When auto memory is on, Claude gets instructions about what a memory is. There are four types, and each comes with a scope rule, private or team:18

  • user: your role, goals and knowledge. "always private".
  • feedback: "Guidance the user has given you about how to approach work". Private by default; team "only when the guidance is clearly a project-wide convention that every contributor should follow".
  • project: what is going on, "not otherwise derivable from the code or git history". "private or team, but strongly bias toward team".
  • reference: "pointers to where information can be found in external systems". "usually team".

The scope rules are the interesting part. They encode a privacy model in prose: what is about you stays yours, what is about the work leans shared.

What it refuses to remember

The section I keep rereading is "What NOT to save in memory":19

  • code patterns, conventions, architecture, file paths: "these can be derived by reading the current project state";
  • git history: "git log / git blame are authoritative";
  • debugging recipes: "the fix is in the code; the commit message has the context";
  • anything already in CLAUDE.md;
  • ephemeral task details.

Then: "These exclusions apply even when the user explicitly asks you to save. If they ask you to save a PR list or activity summary, ask what was surprising or non-obvious about it". That, the prompt says, is the part worth keeping.19

This is a strong design choice. Memory is reserved for what cannot be recomputed. Everything that can be read again from the repository is read again. It is the same principle that makes compaction work: drop what can be recovered, keep what cannot.

It is also a product choice the user cannot see. Asking it to remember does not mean it will. I think the rule is right, and I think it should be visible in the interface, not only in a prompt.

A memory is a claim about the past

The instruction I would copy into any harness is "Before recommending from memory":20

A memory that names a specific function, file, or flag is a claim that it existed when the memory was written. It may have been renamed, removed, or never merged.

Then the procedure: check the file exists, grep for the flag, verify before the user acts. And one line that should be on a poster: ""The memory says X exists" is not the same as "X exists now.""20

Memory is treated as evidence with a date, not as truth. That is exactly what my session's compaction summary lacked when it stated "Respond in French" as a rule.

When to look, and when to forget

Two more rules frame the use of memory.21

  • "You MUST access memory when the user explicitly asks you to check, recall, or remember", and check it "always before telling the user you do not have something".
  • If the user says to ignore memory: "Do not apply remembered facts, cite, compare against, or mention memory content."

The second rule is easy to underestimate. Forgetting on request is not deletion; it is a promise about behavior in this conversation, and the prompt states it with the same precision as the rest.

What I could not see

The binary also mentions background consolidation, called "auto-dream", a synthesize recall mode beside the file-backed select mode, and a scan capped at 200 memories, index first, then newest first.22 I did not see any of them run. And I could not tell whether the API's memory stores and claude.ai's memory are one system or two.

What Anthropic's research post adds

Reading "The components of agent memory" after the draft, three things lined up, one did not.

Auto-dream has a name and a purpose. The post calls it dreaming: agents reflect on their logs "to fix mistakes or produce new notes and representations".23 Dreaming checks notes against the original transcripts, builds wikis, and promotes the most useful notes to the top of the hierarchy.24 The setting I found in the binary, "Enable background memory consolidation (auto-dream)", is that idea shipped in the CLI.

The index is the top of a hierarchy. The post describes the same rule as the docs, "It loads only the first 200 lines or 25 KB of MEMORY.md", and explains why: the injected layer has to stay small, so it works as an index and the rest is read when needed.25

Compaction is not memory. The post's definition of memory "excludes" compaction, "summaries written by Claude that replace its older turns".26 That is exactly what happened in my session: the compaction summary filled the role of memory, and got one thing wrong.

The examples are worth the read. Playing Pokémon Red, Claude Sonnet 3.7 "wrote 413 memory files across 225 folders and earned one badge"; Claude Fable 5 "wrote nine files in two folders, plus a single top-level file called global.md, and earned four badges."27 Less memory, better memory.

Where it does not line up. The post's advice is to "tell Claude what memory is for, but not how to use it". When the researchers set a fixed rule, "record only failures", Opus 5 and Opus 4.7 "lost much of the performance boost that memory gave them".28 With frontier models, Anthropic says it typically gives "simple guidance to create memory notes when a person asks them to or when something is clearly worth remembering".29

Claude Code 2.1.319 is more prescriptive: four types with scope rules, and a list of exclusions that apply "even when the user explicitly asks you to save".19 One reading: the CLI's rules are about privacy and redundancy, not about what is salient, so they do not contradict the research. Another: the product is stricter than the lab's own findings. The binary holds two versions of the types block, so this may already be moving.

Next to the other harnesses

  • Harness² treats memory as one of eight harness components, LongTermMEMORY.md, always loaded and counted against its prose budget.30
  • Hermes Agent advertises "Agent-curated memory with periodic nudges" and full-text search over past sessions.31
  • OpenClaw makes memory "a special plugin slot where only one memory plugin can be active at a time".32

Claude Code is the only one of these where the rules about what not to remember are as detailed as the rules about what to remember.

Takeaways for your own harness

  • Decide where memory is off, and say so. A cloud session without memory is fine. A user who does not know is not.
  • Remember only what cannot be recomputed. Code, history and fixes live in the repository.
  • Type memories and give each type a scope. Private by default for what is about the person.
  • Date every memory and verify before acting on it. A memory is a claim about the past.
  • Keep the user's own words. A habit observed is not an instruction given.
  • Make "forget this" a behavior, not only a deletion.

Why there is also a video

I have noticed that LinkedIn articles and posts are not always read to the end, or at all. So for this one I am trying something else as well: a vertical video. Same facts, same sources, fewer footnotes.

Sources

  1. research/harness-internals/memory/README.md, section 3. ↩
  2. research/harness-internals/compaction/session-case-2026-11-07.md, "Hand checks". ↩
  3. research/public-docs/components-of-agent-memory.md (Anthropic, "The components of agent memory", dated Nov 6, 2026; fetched Nov 8, 2026). ↩
  4. research/harness-internals/memory/binary-index-2.1.319.md, row "Auto-memory off in remote sessions unless a memory dir is given" (Claude Code 2.1.319 binary). ↩
  5. research/public-docs/memory.md, line 14. ↩
  6. research/public-docs/memory.md, line 68. ↩
  7. research/harness-internals/memory/schema-descriptions-2.1.319.md; binary-index-2.1.319.md, row "Organization-managed memory". ↩
  8. research/public-docs/memory.md, line 10. ↩
  9. research/public-docs/memory.md, line 58. ↩
  10. research/harness-internals/memory/schema-descriptions-2.1.319.md (description of the auto-memory directory setting). ↩
  11. research/harness-internals/memory/binary-index-2.1.319.md, row "Team memory folder". ↩
  12. research/harness-internals/memory/schema-descriptions-2.1.319.md (agent memory scopes). ↩
  13. research/public-docs/memory.md, line 62. ↩
  14. research/harness-internals/memory/binary-index-2.1.319.md, rows "Memory stores API (beta)" and "Memory store listing tool input". ↩
  15. research/harness-internals/memory/binary-index-2.1.319.md, row "Memory store sync conflict handling". ↩
  16. research/claude-filesystem/rclone-backends.md, "rclone-memory". ↩
  17. research/harness-internals/memory/schema-descriptions-2.1.319.md (the claude.ai memory snapshot). ↩
  18. research/harness-internals/memory/prompts-2.1.319.md, "Types of memory" (variable Qn). ↩
  19. research/harness-internals/memory/prompts-2.1.319.md, "What NOT to save in memory". ↩
  20. research/harness-internals/memory/prompts-2.1.319.md, "Before recommending from memory". ↩
  21. research/harness-internals/memory/prompts-2.1.319.md, "When to access memories". ↩
  22. research/harness-internals/memory/schema-descriptions-2.1.319.md; binary-index-2.1.319.md, rows "Background consolidation (auto-dream)", "Recall modes" and "Memory scan limit and order". ↩
  23. research/public-docs/components-of-agent-memory.md, line 12. ↩
  24. research/public-docs/components-of-agent-memory.md, lines 54 to 88. ↩
  25. research/public-docs/components-of-agent-memory.md, line 86. ↩
  26. research/public-docs/components-of-agent-memory.md, line 17. ↩
  27. research/public-docs/components-of-agent-memory.md, lines 36 and 37. ↩
  28. research/public-docs/components-of-agent-memory.md, lines 46 to 48. ↩
  29. research/public-docs/components-of-agent-memory.md, line 52. ↩
  30. research/harness-comparison/google-research-harness2/harness2/substrate/opencode.py, lines 44 to 51. ↩
  31. research/harness-comparison/nousresearch-hermes-agent/README.md, line 26. ↩
  32. research/harness-comparison/openclaw-openclaw/VISION.md, line 117. ↩

What I could not verify

  • Auto memory, team memory, agent memory and memory stores were not seen running: this session had none of them.
  • When auto-dream runs and what it changes on disk (Anthropic's post describes dreaming, not the CLI's schedule), and what the synthesize recall mode sends to the model.
  • Whether the API's memory stores and claude.ai's memory are the same system.
  • Whether Cowork turns auto memory on by default.