Codebase Memory MCP: Give Coding Agents a Map and a Memory

For relationship-heavy recall beyond code structure, the Neo4j agent memory guide shows how to pair a graph with readable authority and test drift.

Codebase memory MCP can stop a coding agent from rediscovering repository structure through repeated grep-and-read loops. A structural server indexes functions, classes, imports, routes, and call edges, then exposes focused queries over the Model Context Protocol. That is useful memory—but it is memory of what the code is, not why the team made it that way.

A production setup therefore needs two layers: a generated code map for fast navigation, plus readable project knowledge for decisions, constraints, and runbooks. The second layer should be files you can read, edit, version, and self-host—not only embeddings or graph nodes hidden behind a service. Meshnote supplies that agent-agnostic markdown layer over MCP.

What the leading pages cover

The current leading results focus on DeusData's codebase-memory-mcp. Its repository and product page explain the local Tree-sitter pipeline, SQLite graph, hybrid type resolution, structural and semantic search, call tracing, architecture summaries, diff impact analysis, and incremental updates. AI Builder Club adds a hands-on Claude Code walkthrough, hook-based adoption, and measured monorepo token counts.

The 2026 Codebase-Memory preprint gives the strongest independent-looking methodology available from the project authors: across 31 repositories, its MCP agent reached 0.83 answer quality versus 0.92 for file exploration while using about 1,000 versus 10,000 tokens per question and 2.3 versus 4.8 tool calls. Treat those as results for the evaluated release and workload, not universal savings. The paper evaluated version 0.5.5 with 66 languages and 14 tools; the current project advertises a larger surface, showing why version-specific claims matter.

What those top pages do not provide is a two-layer acceptance test that catches both a stale structural map and stale human rationale. That is the gap this guide fills.

A code graph is not the whole project memory

A graph can answer “what calls ProcessOrder?” because the relationship can be derived from source. It cannot reliably answer “why did we keep the outbox after moving to managed queues?” unless that rationale was explicitly recorded. Even an architecture-decision feature tied to one graph tool does not automatically become the shared, portable source used by every agent and teammate.

Layer	Best at	Weak at	Refresh model
Code graph MCP	Symbols, callers, routes, dependency paths, blast radius	Intent, operational exceptions, historical reasoning	Regenerate from source
Serena	LSP-backed symbol navigation, references, and targeted edits	Cross-tool team knowledge unless separately maintained	Language-server state
Mem0	Extracting and retrieving conversational facts across sessions	A human-readable project source of truth by default	Write and retrieval pipeline
Readable markdown memory	Decisions, runbooks, constraints, provenance, corrections	Automatically reconstructing every live call edge	Explicit reviewed edits

These approaches are complementary. Letta is strong when agent state and memory belong to one stateful runtime; Zep emphasizes temporal and graph-oriented conversational context; native ChatGPT or Claude memory reduces repeated personal briefing. None should be assumed to replace a repository-derived code graph or a team-owned engineering wiki. For the broader storage trade-off, see vector memory versus readable memory.

Working dual-MCP setup for Claude Code

First install the structural server on macOS or Linux using the publisher's current installer. Inspect remote install scripts before running them in a sensitive environment:

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
codebase-memory-mcp --version

The installer detects supported clients and configures them. Restart Claude Code, open the repository, and ask: Index this project, check index coverage, then show the architecture. The server's current tools include index_repository, check_index_coverage, get_architecture, search_graph, trace_path, and detect_changes. Use search_graph to discover qualified names before requesting a snippet.

Then add readable project memory as a second server. In Claude Code's MCP configuration, keep the local structural process and the remote memory endpoint side by side:

{
  "mcpServers": {
    "codebase-memory": {
      "command": "codebase-memory-mcp",
      "args": []
    },
    "meshnote": {
      "type": "url",
      "url": "https://meshnote.io/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_MESHNOTE_API_KEY>"
      }
    }
  }
}

Store that token only in your local user configuration, never in a repository. Restart the client, list both servers' tools, and confirm that search_wiki reads the intended project before allowing writes. The Claude Code persistent memory guide covers the client boundary in more detail.

The map-and-reason acceptance test

Run this six-step test on a non-production branch. It validates the division of responsibility rather than merely proving that two servers connect.

Choose a known boundary. Pick a load-bearing function whose callers you understand and an architecture decision explaining one constraint around it.
Verify structure. Ask the graph server for architecture, locate the qualified symbol, trace inbound and outbound paths, and retrieve one focused snippet. Compare at least one edge with source.
Verify rationale. Search the wiki for the decision. The page should state the decision, reason, scope, owner or source, and review date—not just restate code.
Create drift. Rename or move one caller on the test branch. Wait for incremental indexing, call check_index_coverage, and trace again. The old path must disappear and the new path must be present.
Correct the decision. Update the markdown page to reflect a deliberately changed constraint. Read it back, confirm the prior version is available in history, and ensure a second MCP client retrieves the correction.
Test failure behavior. Stop the graph server and deny the wiki token separately. The agent must report each layer unavailable; it must not convert missing evidence into “no callers” or “no decision.”

This test finds two dangerous false positives: a successful query against an old index and an empty result caused by authorization. Both can look like valid absence unless your workflow checks freshness and errors explicitly. For a broader operational gate, adapt the correction, isolation, provenance, deletion, restart, and export checks in the MCP memory server shortlist.

Routing rules that keep context small

Use the graph first for structure: callers, implementations, routes, dependency paths, and changed-symbol impact.
Use exact text search for literals, configuration keys, generated behavior, and framework conventions the static graph may not model.
Use readable memory for “why,” deployment sequencing, known hazards, ownership, and lessons that are not derivable from current code.
Confirm critical graph answers in source before editing. Static analysis can miss reflection, generated code, dependency injection, event wiring, and runtime registration.
Promote durable discoveries to memory selectively. Do not dump transcripts or every graph result into the wiki.

That hybrid is more honest than calling any single index “the memory.” A code map should be disposable and reconstructable from the repository. Engineering rationale should be durable, reviewable, and portable across tools. Meshnote keeps that second category in linked markdown while your preferred graph or LSP server handles live code intelligence.

When to choose each approach

Choose codebase-memory-mcp when repo-scale structural questions and local graph queries dominate. Choose Serena when LSP-quality symbol operations and targeted edits are central. Add Mem0, Zep, Letta, or native assistant memory when the application needs conversational personalization or runtime-specific state. Add a readable wiki when several agents or people must agree on decisions that outlive any one client.

The result is not duplicate storage. It is a clean authority boundary: source code owns executable truth, the generated graph accelerates navigation, and reviewed markdown owns project rationale. If that matches your workflow, Start syncing — $8/mo.