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

> Explore the four-layer codebase memory MCP structure. Learn how DeusData transforms repositories into a knowledge graph via JSON-RPC.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: deep-dive
- Published: 2026-07-26

---

**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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/build.sh)** — Compiles the static C binary and bundles vendored tree-sitter grammars.
- **[`install.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/install.sh)** / **`install.ps1`** — Platform-specific installers that configure agent environments.
- **[`pkg/pypi/src/codebase_memory_mcp/_cli.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/pypi/src/codebase_memory_mcp/_cli.py)** — Implements the CLI front-end mapping flags to JSON-RPC calls.
- **[`graph-ui/index.html`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/index.html)** — Entry point for the 3-D visualization interface.
- **[`docs/CONFIGURATION.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md)** — Documents environment variables and per-project settings.
- **[`docs/cbmignore.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/cbmignore.md)** — Defines hierarchical ignore rules respected by the indexer.
- **[`THIRD_PARTY.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/THIRD_PARTY.md)** — Lists all vendored dependencies including grammars and embedding models.

## Practical Usage Examples

Install and operate the tool using these commands:

```bash

# 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.