How Claude Code’s Folder‑Based Memory Boosts Performance by 39%

Background

Earlier discussions of agent long‑term memory focused on vector stores, embedding retrieval, and complex retrievers that were unstable in production. Anthropic’s Claude Code replaces that approach with a simple folder of markdown files.

Performance Gains

Anthropic’s context‑management blog reports a controlled experiment of 100 web‑search rounds. Combining the memory tool with context editing improved performance by 39 % over the baseline; context editing alone contributed a 29 % boost. Token consumption dropped by 84 %.

The gains were achieved without RAG tuning, vector stores, or graph databases. Claude reads and writes markdown files via ordinary tool calls (read, write, delete) on the client side; storage backend remains the developer’s responsibility.

Engineering Benefits of File‑Based Memory

Storing memory as files makes it searchable with grep, diffable, version‑controlled with git, and portable across machines by copying the directory.

In practice, noisy retrieval from vector stores is often a bigger pain point than inability to retrieve. Teams frequently need deterministic rules rather than fuzzy top‑10 matches.

CLAUDE.md: User‑Written Memory

Claude Code uses two memory layers: a user‑authored CLAUDE.md and an auto‑generated memory layer. CLAUDE.md defines four scopes loaded in a fixed order from the filesystem root to the current directory, from public to private:

Managed policy : /Library/Application Support/ClaudeCode/CLAUDE.md – visible to the whole machine.

User : ~/.claude/CLAUDE.md – visible only to the individual.

Project : ./CLAUDE.md or ./.claude/CLAUDE.md – shared within the team (git).

Local : ./CLAUDE.local.md – private to the user (git‑ignored).

When Claude starts, it walks up the directory tree, concatenating each CLAUDE.md into the context. The local file always follows the project file, giving higher priority to nearer scopes.

The documentation recommends keeping each CLAUDE.md under 200 lines; longer files cause noticeable drops in Claude’s compliance.

Advanced users can place per‑topic rule files under .claude/rules/ with optional YAML front‑matter and glob patterns, and import other files using the @import syntax (up to four levels deep).

Auto Memory: Claude‑Generated Notes

Since version 2.1.59, auto memory is enabled by default. Its directory layout is:

~/.claude/projects/<project>/memory/

MEMORY.md

– index file, always loaded (first 200 lines or 25 KB, FIFO). debugging.md, api-conventions.md, … – topic files loaded on demand.

The MEMORY.md truncation rule applies only to that entry file; other topic files are not limited. CLAUDE.md is loaded in full, but longer files reduce Claude’s obedience.

Three Counter‑Intuitive Design Choices

CLAUDE.md is not a system prompt – it is sent as a user message after the system prompt, so its content is advisory rather than a hard constraint.

Files, not a database – all auto memory is plain markdown, allowing instant inspection, editing, or deletion without opaque state machines.

Loading order protects local overrides – later files can override earlier ones, but conflicts are resolved arbitrarily, reflecting honest behavior.

Minimal Setup Workflow

Run /init to scan the codebase and generate a starter ./CLAUDE.md. Setting CLAUDE_CODE_NEW_INIT=1 triggers an interactive multi‑step flow for skills and hooks.

Populate the project‑level ./CLAUDE.md (under 200 lines) with team conventions, build commands, testing scripts, and naming rules. Add personal preferences to ~/.claude/CLAUDE.md.

Keep auto memory enabled and periodically run /memory to review what Claude has stored. Delete or edit spurious entries, such as temporary debugging workarounds that were inadvertently turned into permanent rules.

Running /compact reinjects the root CLAUDE.md but leaves nested files untouched until Claude accesses their directories again.

Conclusion

The 39 % performance boost demonstrates that a plain folder of markdown files with deterministic loading order and clear truncation limits can replace complex vector stores, graph databases, and additional middleware for agent long‑term memory.

Future challenges include scaling to multi‑agent collaboration, cross‑repo memory, and enterprise‑grade auditability, where the current limits (200 lines / 25 KB) may need to be revisited.

Reference: https://claude.com/blog/context-management