Claude Code Memory MCP: Configuring Persistent Agent Memory

The Operational Cost of Memory Resets

When developers use Claude Code for non-trivial refactoring or multi-day feature development, the loss of context between runs creates friction. Every time a new CLI session starts, the model begins with zero recollection of why specific architectural tradeoffs were made an hour earlier. If you instructed the agent to avoid mutating legacy database schemas or explained that payment processing routes require custom headers, that knowledge disappears when the shell closes.

Developers often compensate by manually re-typing context, copying text blocks into prompt buffers, or stuffing extensive prompt preambles into shell scripts. This manual repetition drains engineering hours and introduces inconsistencies. A persistent memory server turns the terminal agent into a compounding collaborator that recalls prior mistakes, honors established conventions, and maintains project continuity across restarts.

Context Window Ceilings Versus External Persistence

A language model context window represents active working RAM rather than a permanent database. While modern models offer sizable context windows, filling them with static documentation, project history, and code dumps degrades reasoning performance and increases latency.

External persistence decouples memory storage from memory activation. Instead of carrying tens of thousands of tokens of historical notes into every prompt turn, Claude Code queries an external server only when relevant facts are required. This approach keeps the active context window lean, preserves room for complex reasoning, and prevents context exhaustion during long development tasks.

Manual Rules in CLAUDE.md and AGENTS.md

The foundational memory layer consists of Markdown instruction files stored directly inside the repository. A project CLAUDE.md file (or AGENTS.md) lives in the root directory or inside .claude/. You write and maintain this file to define build commands, code formatting rules, testing procedures, and architectural constraints.

Claude Code also supports a cascading hierarchy:

• Managed policy: System-wide guidelines set at /Library/Application Support/ClaudeCode/CLAUDE.md on macOS or /etc/claude-code/CLAUDE.md on Linux.
• User instructions: Global preferences located at ~/.claude/CLAUDE.md that apply across every project on your workstation.
• Project instructions: Repository-level rules committed to git in ./CLAUDE.md or ./.claude/CLAUDE.md.
• Local instructions: Private overrides stored in ./CLAUDE.local.md, which remain git-ignored for developer-specific configurations.

Anthropic recommends keeping project rule files concise to maintain high model adherence. Bloated rule files consume excessive context on every turn, and files larger than 4 MiB are skipped entirely by the CLI.

Auto Memory Mechanics and Index Ceilings

Auto Memory allows Claude Code to capture knowledge organically during interaction without requiring manual file edits. When you correct an erroneous assumption, confirm an architectural pattern, or mention a project quirk, Claude writes notes into an internal directory located at ~/.claude/projects/<project>/memory/.

This directory maintains an index file named MEMORY.md alongside individual topic files categorized into user roles, feedback, project milestones, and external references.

Anthropic documents that Claude Code automatically loads the first 200 lines or 25KB of its project memory index at the start of every session, according to the official Claude Code memory documentation. Content beyond that threshold is omitted from the initial prompt payload. When Claude needs details beyond the index lines, it must issue explicit file read operations to load individual topic notes.

Developers can inspect, edit, or purge these notes at any time using the /memory command inside an active session. Setting CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 disables the automatic note-taking mechanism entirely.

Local Project Configuration via .mcp.json

To share an MCP server configuration with teammates through source control, declare it inside a .mcp.json file in your repository root. Claude Code reads this file automatically upon launch.

Here is an example configuration for a project .mcp.json:

{
  "mcpServers": {
    "project-memory": {
      "command": "node",
      "args": ["./scripts/memory-server.js"]
    }
  }
}

For remote servers using Streamable HTTP, define the server type and target endpoint:

{
  "mcpServers": {
    "team-memory": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

When team members clone the repository and launch Claude Code, the CLI detects .mcp.json and prompts them to approve the declared tools. This setup ensures that everyone on the team benefits from the same memory infrastructure.

Tool Verification and Interactive Management

Once configured, verify that Claude Code recognizes the memory capabilities by running the /mcp command in your terminal session. The interface displays all active servers, their transport types, and the individual tool definitions exposed to the model.

Typical memory servers expose tools such as create_entities, read_graph, search_nodes, or add_observations. When Claude Code encounters complex problems, it calls these tools autonomously to store facts or pull relevant historical data into the current prompt buffer.

Context Compaction at High Token Capacity

Claude Code compacts context automatically when sessions exceed ~95% capacity. As a session approaches this ceiling, the CLI triggers a compaction pass that summarizes historical message turns, clears raw tool execution traces, and re-injects foundational project context.

During compaction:

• Project-root CLAUDE.md files and unscoped rules are re-read from disk and re-injected.
• The primary MEMORY.md index is reloaded from disk.
• Recent file modifications (up to five files) are re-referenced.
• Temporary conversation history, intermediate tool arguments, and inline memory tool responses are condensed into a single synthetic summary block.

If an agent relies on unstructured local memory servers that dump large chunks of data directly into conversation turns, that context is subject to summarization loss during compaction. Subtle architectural requirements, exact interface signatures, and specific edge-case fixes can be diluted or dropped entirely when the conversation history is summarized.

Machine Isolation and Multi-Agent Knowledge Silos

Native Auto Memory and local file-based memory servers store their state on the local workstation, typically under ~/.claude/projects/ or inside local SQLite files. This creates three distinct operational problems:

• Single-machine lock-in: Work conducted on a desktop workstation does not transfer to a laptop, a remote development container, or a cloud CI runner.
• Multi-agent blindness: If you run multiple coding agents, such as pairing Claude Code with Cursor, Codex, or headless background scripts, each agent maintains an isolated, disconnected memory silo. One agent remains blind to the modifications and discoveries made by another.
• Prompt token inflation: Naive memory servers often append large entity lists to every prompt turn. As your knowledge base grows, injecting broad memory dumps consumes valuable token allowance, drives up API operational costs, and crowds out source code analysis.

Workspace Storage and Intelligence Indexing

In a Fast.io workspace, files are not merely stored as static blobs. When Intelligence Mode is enabled on a workspace, files are automatically indexed for hybrid search, combining full-text indexing, semantic search, and metadata filtering.

Engineering teams can populate the workspace directly through file uploads or by connecting existing document repositories. Cloud Sync connects Google Drive, Dropbox, Box, and OneDrive folders to a workspace, one-way or two-way, on a schedule or on demand. When product requirement documents, API contracts, or system architecture diagrams update in Google Drive or OneDrive, the synchronized Fast.io workspace re-indexes the new content automatically without local disk input/output operations.

Configuring Fast.io MCP over Streamable HTTP

Claude Code connects directly to Fast.io using the remote Model Context Protocol endpoint designed specifically for coding agents.

Fast.io hosts its MCP service over Streamable HTTP, avoiding local node process overhead or fragile daemon bridges. For coding agents operating in IDEs and terminals, Fast.io serves tools at https://mcp.fast.io/mcp/code.

To connect Claude Code to Fast.io, run the following command in your terminal:

claude mcp add --transport http fast-io https://mcp.fast.io/mcp/code

Next, launch Claude Code and run /mcp to initiate the OAuth browser authentication flow. A browser window opens displaying the Review Permissions screen, where you select Read Only or Read & Write permissions and choose which organizations and workspaces Claude Code can access. Consult the Fast.io MCP setup documentation for full endpoint options.

You can also define this connection in your project's .mcp.json file:

{
  "mcpServers": {
    "fast-io": {
      "type": "http",
      "url": "https://mcp.fast.io/mcp/code"
    }
  }
}

For coding agents connected at /mcp/code, Fast.io provides a consolidated MCP toolset including search, execute, execute_manage, and how-to. When Claude Code needs to recall an architectural decision or check an API schema, it calls the search tool to execute semantic and keyword queries across workspace documents, receiving precise text passages with citations instead of unmanageable document dumps. Reads stay on execute or search, while file modifications pass through execute_manage.

Team Coordination, Versioning, and Activity Logs

Connecting Claude Code to a shared workspace transforms agent memory from an isolated local cache into a collaborative team asset.

Every file inside Fast.io maintains per-file version history. When an agent creates or updates an architectural decision record, previous iterations remain preserved and auditable. Multiple agents and human developers can interact with the same workspace without overwriting historical work. Advisory file leases can be acquired and released via MCP actions (lock-acquire and lock-release on storage_manage, lock-status on storage), allowing agents to coordinate edits transparently.

Fast.io also maintains a detailed activity log of changes, recording file uploads, modifications, deletions, permission changes, and share creations across all organization members and agents. Teams can see exactly which agent updated a specification and when.

Monthly plans start with a 14-day free trial that requires a credit card. Review pricing for plan comparisons and quota details.

Implementing a Three-Tier Memory Hierarchy

Structure your agent memory across three distinct operational tiers:

• Tier 1: Static Operational Rules (CLAUDE.md). Keep this file concise, focusing on core commands and project layout. Restrict its contents to non-negotiable guidelines: test commands, linting scripts, file organization paths, and formatting requirements.
• Tier 2: Dynamic Local Ergonomics (Auto Memory). Let Claude Code maintain its local MEMORY.md index for personal developer feedback, stylistic preferences, and session-specific workflow shortcuts. Periodically review and prune these entries with /memory.
• Tier 3: Shared Organizational Knowledge (Fast.io MCP Workspace). Store system specifications, OpenAPI schemas, architectural decision records, compliance guidelines, and domain glossaries in an indexed external workspace. Agents query this tier on demand via MCP search tools rather than loading documents into the prompt buffer.

Memory Hygiene and Conflict Prevention

Memory systems degrade if obsolete instructions accumulate over time. When two instructions contradict each other, large language models pick between them arbitrarily.

To maintain memory hygiene:

• Run regular audits: In Claude Code v2.1.283 or later, run /doctor prompt-audit to evaluate your CLAUDE.md, rules, and skills for contradictions, stale file paths, and obsolete command references.
• Prune Auto Memory: Open /memory every few weeks to delete outdated feedback notes that no longer reflect your current codebase architecture.
• Scope project rules: For monorepos or multi-service repositories, use .claude/rules/ with paths: YAML frontmatter to load instructions only when Claude works on matching files, saving prompt context.