Giving Claude Code Persistent Project Memory With MCP

CLAUDE.md gives Claude Code static instructions you write by hand and it reloads at the start of every session — it never learns anything new on its own. To get real persistent memory, where Claude remembers facts it picked up mid-conversation and recalls them weeks later, you connect Claude Code to an MCP context-store server. open-context is one: it adds save_context and recall_context tools backed by a local database, so Claude can write memory itself instead of waiting for you to write it for it.

Why CLAUDE.md alone isn't memory

Claude Code's memory system, as Anthropic's own docs describe it, is a hierarchy of CLAUDE.md files: an optional enterprise policy file, a project-level ./CLAUDE.md for team-shared instructions, and a user-level ~/.claude/CLAUDE.md for personal preferences. All of them load automatically when Claude Code launches, with files higher in the hierarchy taking precedence.

That's genuinely useful — it's how a team encodes "run npm test before committing" or "we use conventional commits" once and has every session respect it. But it's still a file you write. Claude doesn't add a line to CLAUDE.md mid-conversation because it learned your deploy process changed last Tuesday. Ask it to remember something new and, without another layer, that fact is gone the moment the session ends.

What an MCP context-store server adds

The Model Context Protocol is the open standard Anthropic introduced for connecting Claude to external tools and data over a simple JSON-RPC interface. open-context uses it to expose six memory tools: save_context, recall_context, list_contexts, search_contexts, update_context, and delete_context. Instead of a file Claude re-reads, these are calls Claude makes — the same way it calls a file-editing or shell tool — whenever something worth keeping comes up.

Say "remember that we're deprecating the v1 endpoint in favor of v2" mid-session, and Claude calls save_context with tags like ["decision", "api"]. Start a brand-new session next week and ask "what did we decide about the v1 endpoint?" — Claude calls recall_context and gets it back, verbatim, with no re-explaining required.

Connecting open-context to Claude Code

The MCP server ships in the same repo as the CLI and web UI. Two setup paths, both edits to ~/.claude/settings.json:

Local Node.js build

npm run build

{
  "mcpServers": {
    "open-context": {
      "command": "node",
      "args": ["/path/to/opencontext/dist/mcp/index.js"]
    }
  }
}

Docker (no local dependencies)

{
  "mcpServers": {
    "open-context": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "opencontext-data:/root/.opencontext",
               "adityakarnam/open-context:latest", "node", "dist/mcp/index.js"]
    }
  }
}

Restart Claude Code and the six tools are available immediately — no manual invocation needed, Claude picks them up from the trigger phrases in each tool's description ("remember this", "what did I say about...", and so on).

Scoping memory to one project with bubbles

A single flat pile of saved context works fine at first, then gets noisy once you're using Claude Code across several repos. open-context's bubbles solve the same problem CLAUDE.md solves for instructions — per-project scope — but for memory Claude accumulates on its own. Claude calls create_bubble once for a project, then passes that bubbleId on future save_context calls so recall stays scoped to the right codebase instead of surfacing notes from an unrelated project. See Organize Claude's MCP Memory by Project With Bubbles for the full walkthrough.

Where the memory actually lives

By default, open-context writes to a JSON file at ~/.opencontext/contexts.json — no setup required. Set OPENCONTEXT_DB_URL and the exact same six tools read and write to SQLite, Postgres, MongoDB, Redis, or ten other supported backends instead, with identical behavior. Nothing about how Claude calls the tools changes; only where the bytes land does. If you're deciding between a file and a real database for a team setup, the MCP persistent memory setup guide covers the tradeoffs in more depth.

Use both, not one instead of the other

CLAUDE.md and an MCP context store aren't competing options — they cover different jobs. CLAUDE.md is for instructions you always want followed: conventions, commands, house rules, checked into git so the whole team gets them. An MCP memory server is for facts that accumulate as you work — decisions made mid-session, context that would otherwise live only in your own memory of the conversation. Wire up both, and Claude Code starts every session with your team's rules already loaded and a growing, queryable record of everything it's learned since.

FAQ

Does open-context replace CLAUDE.md?

No. CLAUDE.md stays useful for instructions you want Claude to follow every session — coding conventions, commands, house rules. open-context's MCP server adds a second, complementary layer: memory Claude writes and recalls itself as facts come up, instead of memory you have to hand-write in advance.

Do I need Docker to connect open-context to Claude Code?

No. You can run the MCP server directly with Node.js after npm run build, or in dev mode with npx tsx and no build step at all. Docker is the recommended path because it bundles the server with zero local dependencies, but it isn't required.

Can I keep memory separate for different projects?

Yes. open-context's bubble tools (create_bubble, list_bubbles, get_bubble) let Claude group contexts under a named project workspace, so recall_context and search_contexts can be scoped to just that project instead of everything you've ever saved.

Where does the memory actually get stored?

By default, a local JSON file at ~/.opencontext/contexts.json. Set OPENCONTEXT_DB_URL to move it into SQLite, Postgres, MongoDB, Redis, or one of open-context's other 15 supported database backends, with identical tool behavior either way.

Does this only work with Claude Code, or Claude Desktop too?

Both. The MCP server runs the same stdio process either way — Claude Code reads its config from ~/.claude/settings.json and Claude Desktop from claude_desktop_config.json, but the server and its tools are identical.