# Claude Code Memory MCP: Configuring Persistent Agent Memory

Claude Code terminal sessions initialize with a fresh context window, requiring external mechanisms to persist project knowledge and architecture decisions. Connecting a Model Context Protocol memory server bridges this gap without bloating prompt tokens. Learn how native auto-memory works, how to configure external MCP memory servers, and how remote indexed workspaces preserve project context across terminal restarts.

Source: https://fast.io/resources/claude-code-memory-mcp/
Author: [Derek Labian](https://fast.io/authors/derek-labian/)
Last reviewed: 2026-11-07

## Why Terminal Coding Agents Lose Working Context

Anthropic documents that standard chat conversations accept up to 20 files at up to 500MB each, while Claude Projects enforces a 30MB per-file ceiling with an unlimited file count bounded only by the model context window, according to [Anthropic's official file upload documentation](https://support.claude.com/en/articles/8241126-upload-files-to-claude). In terminal-based developer environments like Claude Code, however, working memory does not depend on file upload widgets. Each terminal session initializes with a fresh context window, meaning local scratchpad notes, architectural decisions, and previous debug cycles vanish the moment a developer exits the CLI or resets the prompt.

Claude Code Memory MCP is a Model Context Protocol integration that enables Claude Code to persist project context, user preferences, and architectural decisions across terminal sessions.

Without external persistence, an agent operating in the shell repeats identical discovery steps during every invocation. It scans the directory tree, checks dependencies, re-reads configuration files, and queries the user for conventions already established in previous discussions. MCP memory servers eliminate repetitive project re-indexing across terminal restarts by providing structured, queryable data stores that survive session termination.

### 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.

## How Claude Code Manages Native Project Memory

Before installing external protocols, developers need to understand how Claude Code handles memory out of the box. Anthropic engineered two primary native mechanisms to carry instructions across sessions: manual configuration files like `CLAUDE.md` and an automated note-taking system termed Auto Memory. Both systems load automatically at the start of every conversation, giving the model baseline guidance before you type your first prompt.

Claude treats these files as context rather than strictly enforced configuration rules. While effective for basic repository conventions, each mechanism operates under strict size constraints designed to protect prompt budgets. Understanding how these native systems function enables teams to identify when local configuration is sufficient and when external MCP architecture becomes necessary for long-term project stability.

### 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](https://code.claude.com/docs/en/memory). 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.

## Steps to Configure an MCP Memory Server in Claude Code

The Model Context Protocol (MCP) provides an open standard for connecting AI clients to external data sources and custom tools. By configuring an MCP memory server, you provide Claude Code with dedicated tools to create, retrieve, update, and search knowledge graphs or persistent key-value entities. This integration extends the agent beyond static Markdown files into active, dynamic state management.

Installing an MCP server into Claude Code takes place directly through the CLI or via project-level configuration files. Developers can choose between local processes running over standard input and output or distributed remote services communicating over Streamable HTTP.

Follow these steps to install and configure an MCP memory server in Claude Code:

1. Confirm your Claude Code installation by running `claude --version` in your terminal to ensure you are on a current release.
2. Select your transport architecture: choose standard I/O (stdio) for local executable scripts running on your machine, or Streamable HTTP for remote servers and distributed cloud endpoints.
3. Add the server using the `claude mcp add` command:
  

```bash
   claude mcp add memory-server -- npx -y @modelcontextprotocol/server-memory
  

```
   For remote Streamable HTTP servers requiring authentication, specify the transport flag:
  

```bash
   claude mcp add --transport http remote-memory https://mcp.example.com/mcp
  

```
4. Start Claude Code in your project directory and type `/mcp` to open the interactive configuration panel. Verify that the memory server status shows connected and review the exposed tools.
5. If the memory server requires environment variables or authentication tokens, supply them in your local settings file or enter them when prompted by the `/mcp` manager.
6. Verify persistence by instructing Claude to record an architectural decision, exit the terminal session, restart Claude Code, and query the stored fact.

### 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`:
```json
{
  "mcpServers": {
    "project-memory": {
      "command": "node",
      "args": ["./scripts/memory-server.js"]
    }
  }
}
```

For remote servers using Streamable HTTP, define the server type and target endpoint:
```json
{
  "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.

## Why Local Memory Bottlenecks Prompt Budgets and Compaction

While basic local memory servers and native markdown files solve initial continuity hurdles, they introduce architectural bottlenecks when development scales across long coding sessions. Developers frequently discover that naive memory systems either flood prompt context with repetitive entity lists or drop critical knowledge during extended execution cycles.

Understanding how context compaction operates inside Claude Code clarifies why local memory files require careful boundaries. Without selective indexing and external retrieval, local memory can degrade prompt performance rather than improve it. Managing this balance ensures that the agent maintains access to necessary context without crowding out working code buffers. When an agent repeatedly re-reads unstructured notes, token budgets deplete rapidly, leaving less room for active file edits, stack traces, and multi-turn refactoring loops.

### 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.

## Connecting Claude Code to Remote Workspace Memory via Fast.io MCP

Solving the persistence challenge for professional teams requires moving beyond local machine files. The modern solution couples Claude Code with an intelligent external workspace that handles document storage, automatic indexing, and fine-grained retrieval over the network.

Fast.io provides shared cloud workspaces built for human and agent collaboration. Instead of forcing Claude Code to absorb entire codebases, architectural specifications, and design documents into its local context window or depending on fragile local JSON stores, the documentation corpus resides in a central Fast.io workspace. The agent accesses this external memory through Streamable HTTP without consuming prompt tokens on unneeded facts, keeping working memory focused strictly on immediate implementation tasks.

### 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:
```bash
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](https://mcp.fast.io/docs) for full endpoint options.

You can also define this connection in your project's `.mcp.json` file:
```json
{
  "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.

| Plan | Monthly Billing | Annual Billing | Storage | Workspaces | Monthly Credits | Max Upload |
| :- | :- | :- | :- | :- | :- | :- |
| Starter | $9.99/mo | $99 | 250 GB | 5 | 100,000 | 25 GB |
| Business | $49.99/mo | $499 | 5 TB | 50 | 600,000 | 50 GB |
| Enterprise | $199.99/mo | $1,999 | 25 TB | 200 | 3,000,000 | 100 GB |
| Add-ons | $1/extra seat | - | 1.5¢/GB/mo | - | $10/100k credits | 4¢/GB bandwidth |

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

## Architectural Best Practices for Persistent Agent Memory

To maintain clean, scalable development environments, engineering teams should implement a tiered memory architecture rather than relying on a single mechanism. Combining local rule files with remote indexed workspaces prevents prompt pollution while preserving long-term architectural continuity.

By segmenting knowledge across distinct layers based on volatility and scope, you ensure high model adherence while keeping prompt token consumption predictable. This separation of concerns keeps terminal sessions fast, responsive, and grounded in current system specifications. Adopting clear lifecycle policies prevents documentation drift and keeps autonomous agents aligned with team goals. Treating agent memory as an engineered hierarchy rather than an unstructured scratchpad enables teams to scale autonomous coding workflows across repositories without manual prompt interventions.

### 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.

## Frequently asked questions

### How do I give Claude Code persistent memory?

You can provide Claude Code persistent memory using native instruction files (CLAUDE.md), the built-in Auto Memory feature, or an external Model Context Protocol (MCP) server. Auto Memory automatically records learnings and preferences into ~/.claude/projects/<project>/memory/MEMORY.md across sessions. For structured, team-wide persistence, you can connect an MCP memory server or an indexed cloud workspace using claude mcp add.

### What is the memory MCP server for Claude Code?

A memory MCP server is a service implementing the Model Context Protocol that provides Claude Code with tools to store, update, and search persistent data outside the terminal context window. Memory servers can run locally via standard I/O (stdio) using graph databases or SQLite, or remotely over Streamable HTTP. Remote workspace servers like Fast.io index documents and architectural records, allowing Claude Code to retrieve relevant facts on demand.

### How do I configure MCP servers in Claude Code?

Configure MCP servers in Claude Code by running claude mcp add <name> -- <command> [args] for local stdio servers, or claude mcp add --transport http <name> <url> for remote HTTP endpoints. You can also declare servers in a .mcp.json file in your repository root under the mcpServers key. Inside an active Claude Code session, type /mcp to inspect connected servers, manage permissions, and authenticate.

### What is the difference between CLAUDE.md and Auto Memory in Claude Code?

CLAUDE.md is a manual Markdown file maintained by developers in the repository root or .claude/ directory, containing explicit build commands, style rules, and coding standards. Auto Memory is an automated system where Claude Code writes its own notes based on developer feedback and corrections. Auto Memory notes are stored locally in the developer's home directory (~/.claude/projects/) and load up to 200 lines or 25KB into each session.

### What happens to Claude Code memory when context compaction triggers?

When a session approaches context capacity (typically around 95% capacity), Claude Code compacts conversation history into a structured summary to free up tokens. Project-root CLAUDE.md files and the MEMORY.md auto-memory index are re-read from disk and re-injected automatically. However, temporary conversational memory, raw tool outputs, and unsaved inline observations are compressed into the summary, which can result in fine detail loss.

### How does Fast.io MCP differ from a local file-based memory server?

Local memory servers store information in workstation-bound SQLite databases or JSON files, making them inaccessible across multiple machines, cloud containers, or team members. Fast.io MCP connects Claude Code to a centralized cloud workspace over Streamable HTTP. Documents and architectural records are indexed automatically with Intelligence Mode for semantic and full-text retrieval, providing multi-agent coordination, per-file version history, and a detailed activity log of changes.

## Sources

- [Claude Help Center: Upload files to Claude](https://support.claude.com/en/articles/8241126-upload-files-to-claude): Anthropic restricts individual files uploaded to Claude Projects to 30MB each, while direct chat conversations accept up to 20 files at up to 500MB each, with project file counts unlimited provided cumulative text fits within the model context window.
- [Anthropic Claude Code Documentation: How Claude remembers your project](https://code.claude.com/docs/en/memory): Claude Code automatically loads the first 200 lines or 25KB of its project memory index at the start of every session, while sessions compact context automatically when approaching 95% capacity.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli. MCP setup is at https://mcp.fast.io/docs: Claude and most MCP clients connect to https://mcp.fast.io/mcp/tools, ChatGPT to https://mcp.fast.io/mcp/operations, and coding agents to https://mcp.fast.io/mcp/code.