Mnemebrain for
Claude Code CLI
via MCP

Claude Code is a terminal-based AI coding assistant. It can read and edit your files, run commands, and reason about your codebase. But by default, it forgets everything when you close the session — your project conventions, architectural decisions, resolved issues, all gone.

Mnemebrain solves this through MCP — the Model Context Protocol, an open standard that lets Claude Code connect to external tools and services. Once connected, Claude Code can call Mnemebrain's 13 memory tools directly, mid-session, to store and retrieve beliefs without any extra prompting from you.

All of this runs entirely on your machine. Nothing leaves your computer unless you configure it to.

The backend is Mnemebrain Lite — the open-source belief memory engine. Install it with pip:

pip install mnemebrain-lite

Once installed, start the server:

mnemebrain-lite serve

You'll see:

INFO     MnemeBrain Lite starting...
INFO     Storage: ./mnemebrain.db
INFO     Uvicorn running on http://localhost:8000

Leave this terminal open. The Mnemebrain backend must be running whenever you use Claude Code with memory. Open a second terminal for all the following steps.

The Mnemebrain MCP server is a separate package that translates MCP protocol calls into Mnemebrain API calls. Clone it from GitHub:

# Clone the MCP server repository
git clone https://github.com/mnemebrain/mnemebrain-mcp.git

# Move into the directory
cd mnemebrain-mcp

# Install dependencies with uv
uv sync

The uv sync command reads the project's pyproject.toml and installs everything it needs into an isolated virtual environment automatically — no manual pip installs, no conflicts.

Note down the full path to this directory — you'll need it in the next step. You can get it with:

# macOS / Linux
pwd

# Example output:
/Users/yourname/mnemebrain-mcp

Claude Code manages MCP servers via claude mcp add. Run this command, replacing /path/to/mnemebrain-mcp with the actual path you noted in Step 3:

claude mcp add \
  --scope user \
  mnemebrain \
  -- uv --directory /path/to/mnemebrain-mcp run mnemebrain-mcp

That's one command (split across lines for readability). Let's break it down:

If you prefer, you can also register it by directly editing Claude Code's config file at ~/.claude.json (macOS/Linux) or %APPDATA%\Claude\claude.json (Windows). Add this inside the "mcpServers" object:

{
  "mcpServers": {
    "mnemebrain": {
      "type":    "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mnemebrain-mcp",  // ← your actual path
        "run",
        "mnemebrain-mcp"
      ],
      "env": {
        "MNEMEBRAIN_URL": "http://localhost:8000"
      }
    }
  }
}

The MNEMEBRAIN_URL environment variable tells the MCP server where the Mnemebrain backend is running. The default (http://localhost:8000) is correct if you started it in Step 2 without changing the port.

Make sure the Mnemebrain backend is still running (Step 2), then open Claude Code in any directory:

claude

Once Claude Code starts, type the /mcp command to check MCP server status:

/mcp

You should see:

MCP Server Status

  ● mnemebrain: connected
    Tools: believe, retract, explain, revise, search,
           list_beliefs, frame_open, frame_add,
           frame_scratchpad, frame_context,
           frame_commit, frame_close, health

If you see disconnected — double-check that the Mnemebrain backend is running in another terminal (mnemebrain-lite serve) and that the path in your config is correct.

Once connected, Claude Code can use all 13 Mnemebrain tools automatically. Here are the most useful patterns:

Store a project-level belief:

Remember that this project uses PostgreSQL 15, SQLAlchemy 2.0,
and all database migrations must go through Alembic. Never use
raw SQL in application code.

Claude will call believe to store three structured beliefs with evidence pointers back to your instruction. Next session, they'll be there.

Query what Claude remembers:

What do you know about this project's database setup?

Claude calls search semantically — not a keyword match, but a conceptual search — and surfaces the most confident, relevant beliefs.

Update a belief when things change:

We've migrated to Prisma. SQLAlchemy is no longer used in this project.

Mnemebrain detects the contradiction with the stored SQLAlchemy belief, creates an ATTACKS edge, and revises confidence automatically. The old belief is kept for history; the new one takes precedence.

Ask Claude to explain its reasoning:

Why did you choose to use Alembic for this migration?

Claude calls explain, which returns the full justification chain — what evidence supported the belief, what the confidence was, and whether any evidence ever attacked it.

Contradiction detection — what makes Mnemebrain different from simple memory:

Most retrieval-based memory systems cannot represent contradictions explicitly — they silently overwrite the old fact, and you'd never know a conflict existed. Mnemebrain creates an ATTACKS edge between the conflicting beliefs, flags the truth state as BOTH, and lets you — or the agent — decide what to do with the conflict.

Here's the full list of tools Claude Code now has access to:

Claude Code supports three scopes for MCP server configuration. Choose the right one for your situation:

claude mcp add --scope user mnemebrain \
  -- uv --directory /path/to/mnemebrain-mcp run mnemebrain-mcp

claude mcp add --scope project mnemebrain \
  -- uv --directory /path/to/mnemebrain-mcp run mnemebrain-mcp

With --scope project, Claude Code writes the server definition into a .mcp.json file in your current directory. Commit that file to git, and every teammate who pulls it gets the same MCP server configuration automatically.

Useful management commands:

# List all registered MCP servers
claude mcp list

# Check details for a specific server
claude mcp get mnemebrain

# Remove a server
claude mcp remove mnemebrain

# Check server status from inside Claude Code
/mcp

Proof check — run this to confirm everything end-to-end:

Use the Mnemebrain health tool to confirm the backend is running,
then store a test belief: "This is a working memory test", retrieve
it, and tell me the confidence score.

If all four checks pass, Mnemebrain is fully integrated with Claude Code. Every future session will have access to accumulated beliefs — your project conventions, architectural decisions, resolved bugs — ready to retrieve and reason over.