Claude Code Memory: CLAUDE.md, Auto Memory & Persistent MCP

Claude Code now carries useful context across sessions through two native mechanisms: human-authored CLAUDE.md instructions and Claude-authored auto memory. Start there. External MCP memory is useful later, when knowledge must be shared, browsable, editable, or portable beyond one repository and one tool. This guide explains the native stack first, shows where each layer fits, and gives you a deterministic way to test persistent memory without pretending that every project needs another database.

How Claude Code memory works in 2026

Anthropic’s current Claude Code memory documentation describes instructions and auto memory as separate systems. Instructions tell Claude how to work. Auto memory lets Claude record useful project facts it learns. Meshnote over MCP is an optional third layer for knowledge that must cross repository or tool boundaries.

These layers complement one another. A build command belongs in instructions. A flaky-test workaround Claude discovered can belong in auto memory. An architecture decision that Claude Code, Cursor, Codex, another device, and a teammate must all find belongs in a shared knowledge layer.

Configure CLAUDE.md without turning it into a dump

CLAUDE.md is persistent context you maintain deliberately. Claude Code supports managed policy, user instructions, project instructions, and local project instructions. A managed file lets an organization distribute policy. A user-level file applies personal preferences across projects. A project can use ./CLAUDE.md or ./.claude/CLAUDE.md for versioned team guidance. ./CLAUDE.local.md is for local, uncommitted preferences.

Keep the project file short enough to review. Put universally relevant facts in the main file and move path-specific guidance into .claude/rules/. A rule can target files or directories, so frontend conventions do not need to consume context during a database task. Prefer commands and boundaries over a history lesson.

# Project commands
npm run build
npm test -- --runInBand

# Architecture boundary
The API layer may call application services, never database adapters directly.

# Non-obvious convention
Database migrations are additive; do not edit a migration after it reaches main.

This example gives Claude a runnable build, a runnable test, one architecture boundary, and one convention a newcomer could not safely guess. Delete instructions that merely restate the code. Split large topics into imported or path-scoped files instead of growing one universal prompt.

Instructions are context, not enforcement. If a command must run or an operation must be blocked mechanically, use tests, permissions, CI, or Claude Code hooks. A sentence saying “always run tests” can guide an agent; it cannot guarantee that the command executed.

Use auto memory for learned project facts

Auto memory is Claude-authored. It is not Claude appending to CLAUDE.md. Claude Code keeps an auto-memory directory per repository, and worktrees for the same repository share that memory. Its index is MEMORY.md; Claude can also create topic files and link them from that index.

At startup, Claude Code currently loads only the first 200 lines or 25 KB of MEMORY.md, whichever limit is reached first. Topic files are not all loaded automatically; Claude reads them when needed. That makes the index a map, not a warehouse. Put concise, durable facts near the top and move detail into clearly named topic files.

Use /memory to inspect or edit memory sources. Good entries include a verified package-manager command, the location of generated code, or the reason a recurring test requires a particular setup. Rules that must remain stable still belong in CLAUDE.md. Review auto memory periodically, remove stale facts, and correct claims that no longer match the repository.

Where native Claude Code memory stops

Native memory is a strong default, with intentional scope choices:

• Repository boundary: auto memory is per repository by default, not a universal company notebook.
• Claude surface: the experience is designed for Claude Code rather than every agent tool your team may use.
• Startup budget: instructions and the auto-memory index consume limited context, so selection still matters.
• No shared cross-agent team wiki: native files do not automatically become one browsable knowledge base for unrelated tools and projects.
• Maintenance and audit: people still need to review what is current, superseded, duplicated, or too sensitive to retain.

These are not defects. They keep the native system close to the coding context. Add another layer only when your actual workflow crosses those boundaries. Teams comparing deployment and storage trade-offs can use the self-hosted agent memory guide.

Add shared, readable memory over MCP

Use a shared layer when one named decision must be available to multiple repositories, agents, devices, or teammates, and when a person must be able to inspect and edit the source. Meshnote stores that knowledge as markdown pages with [[wikilinks]] and exposes agent operations over MCP. Configure Claude Code with a bearer token from your account; keep the real key outside source control:

{
  "mcpServers": {
    "meshnote": {
      "type": "url",
      "url": "https://meshnote.io/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_MESHNOTE_API_KEY>"
      }
    }
  }
}

Restart Claude Code after changing MCP configuration. Then perform an authenticated connection check: list the available Meshnote tools and call search_wiki inside the intended project. Confirm the response comes from that project before writing anything. A token or authorization error is a connection failure, not an empty search result.

The core tools have deliberately readable jobs: search_wiki finds candidate pages, read_page returns the source and its version, write_page creates or updates a page, and get_backlinks shows which pages refer to it. The result is cross-session recall and cross-tool memory without hiding the source text behind a retrieval API.

A two-session test for persistent memory

Test the workflow with one named fact instead of asking whether the agent “remembers.” In Session A, search before writing. Create or update a page called Checkout idempotency decision with one exact constraint: “Every checkout request must reuse the client-generated idempotency key for 24 hours.” Read the page back and confirm the title, source text, project, and version.

Close Claude Code completely and restart it. In Session B, ask Claude to search for the checkout idempotency decision, quote the source page, and state the exact 24-hour constraint without giving it the answer again. Successful recall means the second session retrieved the named source and reproduced the constraint accurately. The detailed Claude memory MCP guide covers remote setup and a longer restart acceptance test.

If the test fails, check the project selection first. Then look for a stale or duplicate page, confirm your start-of-task rule tells Claude to search before acting, and verify token/auth status. Do not create a replacement page until you know whether the original is merely hard to find.

Choose the smallest memory layer that solves the problem

Vector and API systems such as Mem0, Zep, and Letta solve different retrieval and state problems; they are not interchangeable with a reviewed instruction file or a readable wiki. Use the Mem0 alternative comparison for the vendor-level decision, and the MCP memory server architecture guide for protocol, storage, and acceptance-test detail.

Keep memory coherent, not just persistent

Persistence can preserve both a good decision and an obsolete one. Run a small weekly maintenance loop: search before every write; update the authoritative page rather than creating a near-duplicate; link decisions to affected systems; mark or remove superseded facts; and use optimistic, concurrency-safe writes where the system supports them. When a read returns a version token, pass that token into the update so another writer cannot be silently overwritten.

This is how you limit context drift: not by claiming the memory layer never becomes stale, but by making its sources visible and its correction path explicit. Backlinks help reveal which systems depend on a decision. Named pages make duplicates easier to spot. Human review remains part of the system.

Start with one repository, then expand only if needed

Begin with a concise project CLAUDE.md, path-specific rules, and reviewed auto memory. Add MCP memory only after you can name the knowledge that must cross a repository, Claude Code, or one person’s machine. That native-first sequence keeps the system understandable while leaving a clear path to shared, readable knowledge.

Need the same readable memory across Claude Code, Cursor, Codex, and your team? Start syncing with Meshnote — $8/month.

Related reading

• Remote Claude setup and restart testing: Claude memory MCP guide.
• Protocol and storage detail: MCP memory server architecture.
• Vendor-level options: Mem0 alternative comparison.
• Deployment trade-offs: self-hosted agent memory.
• Adjacent OpenAI workflow: Codex CLI memory.
• Adjacent editor workflow: Cursor agent memory.
• Browse all agent memory guides.