# Main Components of codebase-memory-mcp: Architecture of the Knowledge Graph Engine

> Explore the main components of codebase-memory-mcp, a static-analysis engine. Discover its indexing pipeline, SQLite graph store, and query toolkit for AI coding agents.

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

---

**codebase-memory-mcp** is a static-analysis engine that converts entire source repositories into persistent knowledge graphs through three integrated layers: an indexing pipeline with 158 Tree-Sitter grammars, a compressed SQLite graph store, and a comprehensive query toolkit for AI coding agents.

The `codebase-memory-mcp` repository from DeusData implements a high-performance static analysis system designed specifically for AI-assisted coding workflows. Unlike traditional code search tools, this Model Context Protocol (MCP) server constructs a persistent, queryable knowledge graph that captures deep semantic and structural relationships across 12+ programming languages. Understanding the **main components of codebase-memory-mcp** reveals how it achieves sub-millisecond query performance while remaining completely local and offline-capable.

## The Three Core Layers of codebase-memory-mcp

### 1. The Indexing Pipeline

The indexing layer transforms raw source code into a structured graph using a **RAM-first design** that maximizes throughput while minimizing disk I/O.

- **Multi-language parsing** – The system ships with **158 vendored Tree-Sitter grammars** (enumerated in [`opencode.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/opencode.json)) providing robust parsing for diverse language constructs without external dependencies.
- **Hybrid LSP resolution** – A lightweight Language Server Protocol implementation resolves imports, type information, and cross-service links for 12+ languages including Python, TypeScript/JS/TSX, PHP, C#, Go, C/C++, Java, Kotlin, Rust, and Perl.
- **Compression pipeline** – During indexing, data resides in an in-memory SQLite database with **LZ4 compression**, then serializes to a **zstd-compressed snapshot** (`.codebase-memory/graph.db.zst`) handled by [`internal/cbm/zstd_store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.c) and [`internal/cbm/zstd_store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.h).
- **Entry points** – The `index_repository` CLI command triggers one-shot indexing, while the background watcher ([`src/watcher/watcher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/watcher/watcher.c)) monitors filesystem changes for continuous updates.

### 2. The Persistent Knowledge Graph

At the heart of the system lies a richly-typed graph database that persists across agent sessions via a coordination daemon.

**Node types** represent structural entities:
- **Project, Package, Folder, File** – Container hierarchies
- **Module, Class, Function, Method** – Code entities
- **Interface, Enum, Type** – Type system elements
- **Route, Resource** – Service endpoints

**Edge relationships** capture semantic connections:
- `CALLS`, `IMPORTS`, `DEFINES`, `IMPLEMENTS` – Standard code relationships
- `HTTP_CALLS`, `ASYNC_CALLS`, `EMITS`, `LISTENS_ON` – Service communication patterns
- `DATA_FLOWS`, `SIMILAR_TO`, `SEMANTICALLY_RELATED` – Semantic associations

The graph automatically **shares state across all agent sessions** through the coordination daemon, with logs written to `${CBM_CACHE_DIR}/logs/` as documented in [`docs/SECURITY.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/SECURITY.md).

### 3. The Query and Analysis Toolkit

The MCP exposes graph operations through specialized tools that reduce token consumption by approximately 99% compared to file-by-file greps.

**Structural search tools**:
- `search_graph` – Query nodes by label (e.g., `Function`, `Class`) with regex name patterns, degree limits, and pagination
- `search_code` – Text-based code search within indexed content

**Call-graph analysis**:
- `trace_path` – BFS traversal up or down the call stack (inbound/outbound/both) with configurable depth limits
- Dead-code detection and Louvain community detection for architectural clustering

**Semantic capabilities**:
- **Vector search** using the bundled `nomic-embed-code` model (no external API required)
- **Impact analysis** via `detect_changes`, which maps git diffs to affected symbols and classifies blast-radius risk

**Architecture intelligence**:
- `get_architecture` – Returns languages, packages, entry points, routes, hotspots, and clusters in a single call
- `manage_adr` – CRUD operations for Architecture Decision Records
- `query_graph` – Read-only openCypher subset for custom graph traversals

**Operational features**:
- `auto_watch` flag enables automatic re-indexing via the background watcher
- Optional **3D interactive UI** (`--ui=true --port=9749`) for visual graph exploration

## Key Implementation Files

Understanding the codebase structure requires examining these critical paths:

- **[`src/watcher/watcher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/watcher/watcher.c)** – Implements the filesystem watcher that triggers incremental re-indexing when source files change.
- **[`internal/cbm/zstd_store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.c)** – Contains the compression and decompression logic for the persisted graph database.
- **[`opencode.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/opencode.json)** – Manifest of the 158 Tree-Sitter grammars compiled into the binary.
- **[`server.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/server.json)** – Defines the JSON-RPC schema for MCP client communication.
- **[`docs/CONFIGURATION.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md)** – Documents runtime options including `auto-index`, `auto-watch`, and environment variables.
- **[`docs/cbmignore.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/cbmignore.md)** – Specifies the `.cbmignore` hierarchy controlling exclusion patterns during indexing.

## Practical Usage Examples

### Index a repository

```bash
codebase-memory-mcp cli index_repository --repo-path /absolute/path/to/my/project

```

### Search for handler functions

```bash
codebase-memory-mcp cli search_graph \
  --project my-project \
  --label Function \
  --name-pattern '.*Handler.*' \
  --limit 20

```

### Trace call chains

```bash
codebase-memory-mcp cli trace_path \
  --project my-project \
  --function-name Search \
  --direction both \
  --depth 5

```

### Execute Cypher-like queries

```bash
codebase-memory-mcp cli query_graph \
  --project my-project \
  --query "MATCH (f:Function) RETURN f.name, size((f)<-[:CALLS]-()) AS callers ORDER BY callers DESC LIMIT 5"

```

### Detect impact of changes

```bash
git diff HEAD | codebase-memory-mcp cli detect_changes --project my-project

```

### Launch the visualizer

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

```

## Summary

- **Three-layer architecture** – Indexing pipeline, persistent knowledge graph, and query toolkit work in concert to provide sub-millisecond structural queries.
- **Language-agnostic parsing** – 158 Tree-Sitter grammars and Hybrid LSP support for 12+ languages enable deep cross-language analysis.
- **Efficient storage** – RAM-first processing with LZ4 and zstd compression via [`internal/cbm/zstd_store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.c) minimizes disk footprint while maximizing reload speed.
- **Local-first operation** – Bundled embedding models and SQLite persistence require no external APIs, cloud keys, or Docker containers.
- **AI-optimized interface** – MCP tools like `trace_path`, `detect_changes`, and `query_graph` dramatically reduce token usage for coding agents.

## Frequently Asked Questions

### What languages does codebase-memory-mcp support?

The system supports Python, TypeScript/JavaScript/TSX, PHP, C#, Go, C/C++, Java, Kotlin, Rust, and Perl through its Hybrid LSP implementation. Parsing relies on 158 vendored Tree-Sitter grammars defined in [`opencode.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/opencode.json), enabling robust static analysis without external language servers.

### How does the graph storage work?

codebase-memory-mcp uses a **RAM-first design** where the knowledge graph resides in an in-memory SQLite database with LZ4 compression during the indexing phase. Upon completion, the system writes a zstd-compressed snapshot to `.codebase-memory/graph.db.zst` using the compression utilities in [`internal/cbm/zstd_store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.c). This compressed SQLite file persists across sessions and loads rapidly when agents reconnect.

### What is the difference between structural and semantic search?

**Structural search** (via `search_graph`) queries the explicit graph topology—finding nodes by type (Function, Class) and traversing defined edges (CALLS, IMPORTS). **Semantic search** uses the bundled `nomic-embed-code` model to compute vector embeddings of code snippets, enabling similarity searches based on meaning rather than syntax, all processed locally without API calls.

### Can the system automatically update when code changes?

Yes. When enabled via the `auto_watch` flag, the background watcher implemented in [`src/watcher/watcher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/watcher/watcher.c) monitors the repository for filesystem events and triggers incremental re-indexing. This ensures the knowledge graph remains synchronized with the working directory without manual intervention.