How Is Codebase Memory MCP Structured? A Deep Dive into the DeusData Architecture

Codebase Memory MCP is structured as a four-layer architecture comprising a static binary, coordination daemon, indexing pipeline, and query layer that transforms repositories into a persistent knowledge graph accessible via JSON-RPC.

Codebase Memory MCP (CBM) is an open-source tool developed by DeusData that converts source repositories into persistent knowledge graphs for AI-assisted development. Unlike traditional code search tools, it employs a tightly-integrated stack with an embedded SQLite engine and tree-sitter parsing to enable fast, local graph queries without external services. Understanding how codebase memory MCP is structured reveals why it can index complex codebases while maintaining sub-second query performance through its deterministic, layered design.

The Four-Layer Architecture

The architecture divides responsibilities into distinct layers that operate from the filesystem level up to the RPC interface.

Static Binary Layer

At the foundation sits a single self-contained executable built by scripts/build.sh and distributed as codebase-memory-mcp-<os>-<arch>.tar.gz. This binary bundles the entire runtime: an embedded SQLite engine, LZ4 compression libraries, and all 158 vendored tree-sitter grammars. Because it carries no external dependencies, the binary can index repositories immediately after installation without downloading additional language parsers.

Coordination Daemon Layer

A long-running coordination daemon owns all shared resources including graph files, file-watchers, and the optional UI server. The daemon enforces an exact-build admission barrier, ensuring that only one version of the binary operates on a cache root at a time to prevent database corruption. When activated, the daemon creates ${CBM_CACHE_DIR} (defaulting to ~/.cache/codebase-memory-mcp) and writes operational logs to ${CBM_CACHE_DIR}/logs.

Indexing Pipeline Layer

The indexing pipeline reads every file in the repository, parses it with tree-sitter, and resolves imports and types using a Hybrid LSP implementation. This layer supports 12 languages (Python, TypeScript/JS/TSX, PHP, C#, Go, C/C++, Java, Kotlin, Rust, and Perl) to generate semantic edges like CALLS, IMPORTS, and HTTP_CALLS. The pipeline uses a RAM-first strategy: data remains in memory compressed with LZ4 and flushes once at the end to graph.db.zst, a ZSTD-compressed SQLite database.

Query Layer and MCP Tools

The top layer exposes 15 graph-focused commands (e.g., search_graph, trace_path, get_architecture, detect_changes) via a JSON-RPC server. These same tools are accessible through a one-shot CLI interface (codebase-memory-mcp cli …). If launched with the --ui flag, the daemon also serves an embedded 3-D web interface on localhost:9749, reading directly from the same graph database.

How the Components Interact

The system follows a deterministic lifecycle from installation to query execution:

1. Installation — Users run scripts/setup.sh (or the PowerShell equivalent), which places the static binary in $PATH and writes configuration entries into agent config files (Claude Code, Codex, VS Code).

2. Daemon Startup — When the first client issues an MCP request, the binary spawns the coordination daemon (if not already running). The daemon opens the project-specific SQLite database and begins watching files.

3. Indexing — The index_repository command triggers the indexing pipeline, which builds the graph and writes it to graph.db.zst. Incremental updates occur automatically via the daemon’s background watcher (auto-index).

4. Query Execution — Client agents send JSON-RPC calls to the daemon. The daemon executes corresponding SQLite queries or Cypher-like traversals, returning compact JSON payloads.

5. Optional Visualization — With the UI enabled, developers can inspect the knowledge graph interactively at http://localhost:9749.

Core Data Model and Technical Implementation

Hybrid LSP Integration

Beyond syntactic AST parsing, CBM performs lightweight semantic type resolution through its Hybrid LSP implementation. This enables accurate relationship mapping across language boundaries, distinguishing between simple text matches and actual symbol references.

Graph Schema and Persistence

The graph data model defines nodes such as Project, Package, File, Class, Function, and Route. Edges capture relationships including CALLS, IMPORTS, DEFINES, HTTP_CALLS, EMITS, and LISTENS_ON. The database persists under ${CBM_CACHE_DIR}, and teams can share ZSTD-compressed snapshots located at .codebase-memory/graph.db.zst to skip re-indexing on new machines.

Key Implementation Files

The following source files define the architecture:

• scripts/build.sh — Compiles the static C binary and bundles vendored tree-sitter grammars.
• install.sh / install.ps1 — Platform-specific installers that configure agent environments.
• pkg/pypi/src/codebase_memory_mcp/_cli.py — Implements the CLI front-end mapping flags to JSON-RPC calls.
• graph-ui/index.html — Entry point for the 3-D visualization interface.
• docs/CONFIGURATION.md — Documents environment variables and per-project settings.
• docs/cbmignore.md — Defines hierarchical ignore rules respected by the indexer.
• THIRD_PARTY.md — Lists all vendored dependencies including grammars and embedding models.

Practical Usage Examples

Install and operate the tool using these commands:

# Install the binary (macOS / Linux)

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

# Index a repository

codebase-memory-mcp cli index_repository --repo-path /absolute/path/to/repo

# Search for functions containing "Handler"

codebase-memory-mcp cli search_graph --project my-project \
    --label Function --name-pattern '.*Handler.*' --json | jq '.results[].qualified_name'

# Trace call paths for a specific function

codebase-memory-mcp cli trace_path --project my-project \
    --function-name Search --direction both --json | jq '.paths'

# Generate architecture overview

codebase-memory-mcp cli get_architecture --project my-project --json | jq '.languages,.packages'

# Launch the interactive UI

codebase-memory-mcp --ui=true --port=9749

All operations execute locally; no API keys or external network services are required.

Summary

• Four-layer architecture: static binary, coordination daemon, indexing pipeline, and MCP query layer.
• Self-contained distribution: Built by scripts/build.sh with 158 vendored grammars and LZ4 compression.
• Persistent storage: Uses ${CBM_CACHE_DIR} (default ~/.cache/codebase-memory-mcp) for ZSTD-compressed SQLite databases.
• Rich tool surface: Exposes 15 graph commands via JSON-RPC with an optional localhost:9749 visualization UI.
• Multi-language support: Hybrid LSP implementation provides semantic resolution for 12 programming languages.

Frequently Asked Questions

What is the role of the coordination daemon in codebase memory MCP?

The coordination daemon is a long-running background process that manages shared resources such as the graph database file, file-system watchers, and the optional web UI. It enforces an exact-build admission barrier to ensure that only one version of the binary accesses a cache root simultaneously, preventing corruption and ensuring consistency across client sessions.

Where does codebase memory MCP store its graph database?

The tool stores its data under the ${CBM_CACHE_DIR} environment variable, which defaults to ~/.cache/codebase-memory-mcp. Within this directory, the compressed SQLite database resides at graph.db.zst. Teams can export and share this ZSTD-compressed artifact to avoid re-indexing the same repository on different machines.

How does the indexing pipeline handle large repositories?

The indexing pipeline uses a RAM-first architecture where parsed data stays in memory compressed with LZ4 until the entire repository is processed. It flushes the final graph to disk once at completion, minimizing I/O overhead. Incremental updates are supported via the daemon’s auto-index feature, which watches for file changes and updates the graph without full re-indexing.

Which programming languages does codebase memory MCP support?

CBM supports 12 languages through its Hybrid LSP integration: Python, TypeScript, JavaScript, TSX, PHP, C#, Go, C, C++, Java, Kotlin, Rust, and Perl. The parser leverages 158 vendored tree-sitter grammars to construct accurate abstract syntax trees and resolve semantic relationships like imports, function calls, and HTTP route definitions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}