LLM Wiki — Synaptic Lattice

Claude Code Memory

Properties1
tagsprompt-engineering, claude-code, memory

Leitura de 4 min

Claude Code Memory

Definition

Claude Code has two complementary memory systems — CLAUDE.md (instructions you write) and auto memory (notes Claude writes from your corrections) — both loaded at the start of every conversation and treated as context, not enforced configuration.

Key Points

  • CLAUDE.md vs auto memory: CLAUDE.md = explicit instructions, scoped project/user/org, loaded every session; auto memory = machine-generated notes from corrections/preferences, per-repository (shared across worktrees).
  • CLAUDE.md hierarchy (load order, broadest→most specific): managed policy (C:\Program Files\ClaudeCode\CLAUDE.md on Windows, cannot be excluded) → user ~/.claude/CLAUDE.md → project ./CLAUDE.md or ./.claude/CLAUDE.md → local ./CLAUDE.local.md (gitignored).
  • Modular rules: .claude/rules/ holds topic files discovered recursively, scoped via paths YAML frontmatter (glob, brace expansion, 1,000-pattern / 4MiB budget); supports symlinks; user-level ~/.claude/rules/ load before project rules.
  • AGENTS.md: Claude reads CLAUDE.md, not AGENTS.md; import via @AGENTS.md or symlink (ln -s AGENTS.md CLAUDE.md; Windows needs admin/Developer Mode, so use import). The cross-tool AGENTS.md format follows command-first, closure-defined patterns (see agents-md-patterns).
  • Auto memory: on by default; stores MEMORY.md index + topic files in ~/.claude/projects/<project>/memory/; first 200 lines / 25KB loaded per session (writes past limit error); Claude reads topic files on demand; toggle via /memory, autoMemoryEnabled, or CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.
  • Token/context: target under 200 lines per CLAUDE.md; imports load at launch (don’t reduce context); path-scoped rules save context; HTML comments stripped; CLAUDE.md loads in full regardless of length (only MEMORY.md is capped).

Implications

Memory is a context-budget resource, not a configuration store. Keeping CLAUDE.md under ~200 lines and pushing workflow detail to on-demand skills (per token-usage-reduction) bounds the fixed cost every session pays. Auto memory’s 200-line/25KB cap on MEMORY.md is the token-visible limit; the tool itself is the compiler that turns corrections into a durable, machine-local index. Path-scoped rules are the surgical lever for large monorepos.

Field Report — 6-Month Tuning Setup (2026-04-24)

Independent field report treating the project root file as a hot cache, not a vector database: keep it under 500 tokens on purpose, under 200 lines, imperative (“every line must actually change behavior”), with layout / build-and-test / canonical-conventions / guardrails / before-PR sections. The worked example pins the canonical answer prompt (prompts/v4.md frozen v3.md for regression evals), validates all LLM outputs through pydantic models, and forces retrieval to return Chunk objects with stable citation_id. Path-scoped rule files carry file-specific behavior with YAML frontmatter loaded only on matching globs — three or four short rule files beat one large root file, with token savings compounding every turn. Practical caveat from the same report: while paths: is the documented schema key, current versions sometimes silently ignore it (known bug), so globs: or CSV format works more reliably. Vendor-adjacent cost claims to treat as unverified: cache hit rates dropping past ~500 tokens in the author’s own workloads, and the Opus 4.7 tokenizer mapping existing prompts to roughly 1.0–1.35x more tokens.

Implications: this confirms the page’s standing guidance (concise root file, path-scoped rules as the surgical lever) with a production-shaped template teams can copy, and adds the paths:-vs-globs: failure mode to watch for when rules are silently ignored. The 5-level hierarchy framing (home preferences, project root, path-scoped rules, local uncommitted overrides, per-session auto-memory writes) coexists with the documented load order above — both positions are dated, not contradictory.

Open Questions

  • How auto memory’s per-repo sharing behaves across worktrees in practice.
  • Whether the 200-line / 25KB MEMORY.md cap is configurable.
  • Whether the paths: frontmatter bug is fixed in current Claude Code versions, and whether the Opus 4.7 tokenizer multiplier reproduces outside the author’s workloads.

token-usage-reduction — why keeping memory files small matters claude-code-system-prompt — the agent these memory files configure anthropic-tool-use-api — how instructions become tool-driving context

Sources

  • raw/external/code-claude-com-memory-09a26217.md
  • raw/external/freedium-mirror-cfd-i-spent-6-months-tuning-claude-code-here-a23e1587.md

Visão de gráfico

Backlinks