# DeusData codebase-memory-mcp Architecture: Multi-Pass Indexing, Hybrid LSP, and Zero-Dependency Design

> Explore the DeusData codebase-memory-mcp architecture: a zero-dependency C engine featuring multi-pass indexing, hybrid LSP, and an in-process MCP server for a compressed, queryable SQLite code graph.

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

---

**DeusData codebase-memory-mcp is a single-static-binary, zero-dependency C engine that implements a multi-pass indexing pipeline, an in-process MCP (Model Context Protocol) server, 158 vendored tree-sitter grammars, and a hybrid LSP type resolver to build a queryable, compressed SQLite code graph.**

The architecture of DeusData codebase-memory-mcp prioritizes portability and performance through a self-contained design that requires no external runtimes, Docker containers, or API keys. Every component—from file discovery to 3-D visualization—compiles into one platform-specific binary (macOS, Linux, Windows) that embeds a complete code-intelligence stack. The system exposes fourteen JSON-RPC tools through the MCP protocol, making it compatible with AI agents while maintaining a purely local, privacy-preserving workflow.

## Core Architectural Layers

The codebase organizes functionality into discrete layers that communicate through plain C structures and an in-memory SQLite buffer that persists to `~/.cache/codebase-memory-mcp/graph.db.zst`.

### Entry Point and CLI Interface

The program begins in [[`src/main.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c), which parses command-line arguments and branches between two modes: starting the persistent MCP server or executing a one-shot CLI command. The CLI layer in [[`src/cli/cli.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.c) handles installation workflows, auto-detects eleven supported agents (such as Claude Desktop, Cursor, and Windsurf), and manages pre-tool hooks for repository-wide operations.

```bash

# Install and register with all detected agents

codebase-memory-mcp cli install

```

### MCP Server Layer

[[`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c) implements the JSON-RPC server that exposes fourteen tools including `index_repository`, `search_graph`, `trace_path`, and `query_graph`. This layer auto-detects connected agents and maintains the protocol state while translating incoming requests into calls against the underlying C graph engine.

### Multi-Pass Pipeline Architecture

The heart of the DeusData codebase-memory-mcp architecture sits in `src/pipeline/*.c`. [[`src/pipeline/pipeline.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/pipeline/pipeline.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/pipeline/pipeline.c) orchestrates a series of passes that transform raw source files into a structured knowledge graph:

1. **Discovery pass** – yields file paths from the repository root.
2. **Syntax pass** – validates file types and encoding.
3. **Tree-sitter parse** – builds ASTs for supported languages.
4. **Hybrid LSP resolution** – refines call sites with type information.
5. **Graph construction** – populates node and edge tables.

Specialized passes such as [[`src/pipeline/pass_definitions.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/pipeline/pass_definitions.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/pipeline/pass_definitions.c) extract symbols (functions, classes, structs), while [[`src/pipeline/pass_calls.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/pipeline/pass_calls.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/pipeline/pass_calls.c) builds `CALLS` relationships between them.

### Discovery and Ignore Handling

[[`src/discover/discover.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/discover/discover.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/discover/discover.c) walks the file system using platform-specific APIs, respecting `.gitignore`, `.cbmignore`, and default ignore patterns to exclude build artifacts and dependencies. It streams file paths to the pipeline without loading the entire directory tree into memory.

### Tree-Sitter Front-End (158 Languages)

The engine embeds **158 vendored tree-sitter grammars** compiled directly into the binary under `internal/cbm/vendored/grammars/*`. This provides fast, deterministic syntactic analysis without external parser installations. Each grammar feeds into a unified AST traversal interface used by subsequent pipeline passes.

### Hybrid LSP Type Resolution

Rather than requiring a full Language Server Protocol process, [[`src/pipeline/pass_lsp_cross.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/pipeline/pass_lsp_cross.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/pipeline/pass_lsp_cross.c) implements a **hybrid LSP** in pure C for nine languages: Python, TypeScript/JavaScript, PHP, C#, Go, C/C++, Java, Kotlin, and Rust. This resolver refines raw call edges with import-aware, generic-aware, and inheritance-aware logic, producing precise `CALLS` relationships even across file and language boundaries.

### Graph Storage and Cypher Engine

[[`src/store/store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.c) manages an in-memory SQLite database with LZ4 compression that stores nodes (functions, classes, routes, etc.) and edges (calls, imports, HTTP routes). A read-only openCypher implementation in [[`src/cypher/cypher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.c) parses graph queries, plans execution, and traverses the SQLite-backed graph.

```bash

# Query for all functions called by 'main'

codebase-memory-mcp cli query_graph \
  '{"query":"MATCH (f:Function)-[:CALLS]->(g) WHERE f.name=\"main\" RETURN g.name"}'

```

### Background Watcher and Incremental Updates

[[`src/watcher/watcher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/watcher/watcher.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/watcher/watcher.c) runs a background thread monitoring git state and file-system changes. When a diff is detected, it triggers selective re-indexing of only affected files and their transitive dependencies, updating the compressed graph without a full rebuild.

### Optional 3-D UI Layer

When compiled with UI support, [[`src/ui/http_server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/http_server.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/http_server.c) launches an embedded HTTP server on `localhost:9749`, while [[`src/ui/layout3d.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/layout3d.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/layout3d.c) computes WebGL-compatible graph layouts. This allows browser-based exploration of the knowledge graph alongside the MCP server.

```bash

# Launch the WebGL visualizer

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

```

## Data Flow Through the System

The DeusData codebase-memory-mcp architecture processes repositories through a strictly ordered pipeline:

1. **File Discovery** – [`discover.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/discover.c) streams paths while applying ignore rules.
2. **Syntactic Analysis** – Tree-sitter parsers generate ASTs for each supported file.
3. **Semantic Resolution** – Hybrid LSP passes refine call sites with type and import data.
4. **Graph Population** – Pipeline passes write nodes and edges to a temporary [`graph_buffer.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph_buffer.c) structure.
5. **Persistence** – The buffer flushes to a Zstandard-compressed SQLite file at `~/.cache/codebase-memory-mcp/graph.db.zst`.
6. **Query Serving** – The MCP server loads the persisted graph and serves JSON-RPC requests against it.
7. **Incremental Sync** – The watcher daemon updates the graph in response to git commits or file saves.

All stages operate within the same process space, eliminating inter-process communication overhead and removing runtime dependencies on Node.js, Python, or JVM-based language servers.

## Installation and Usage Examples

The PyPI package provides a Python shim in [[`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)](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/pypi/src/codebase_memory_mcp/_cli.py) that downloads the appropriate platform binary and forwards CLI arguments.

```bash

# Install via PyPI (downloads platform binary)

pip install codebase-memory-mcp

# Index a local repository

codebase-memory-mcp cli index_repository '{"repo_path": "/path/to/project"}'

# Search for HTTP route handlers in Python

codebase-memory-mcp cli search_graph '{"label":"Route","language":"python"}'

# Trace inbound callers to a specific function

codebase-memory-mcp cli trace_path \
  '{"function_name":"process_order","direction":"inbound"}'

```

## Summary

- **DeusData codebase-memory-mcp** compiles into a single static binary with zero external dependencies, embedding 158 tree-sitter grammars and a hybrid LSP resolver.
- The **multi-pass pipeline** ([`src/pipeline/pipeline.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/pipeline/pipeline.c)) orchestrates discovery, parsing, type resolution, and graph construction.
- **Hybrid LSP** ([`pass_lsp_cross.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pass_lsp_cross.c)) provides cross-language, import-aware semantic analysis for nine major languages without external language servers.
- **Graph storage** uses LZ4-compressed SQLite ([`src/store/store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.c)) persisted to the user's cache directory.
- ** Incremental indexing** via [`src/watcher/watcher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/watcher/watcher.c) keeps the graph synchronized with git changes.
- The **MCP server** ([`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c)) exposes fourteen JSON-RPC tools for AI agent integration.
- An optional **3-D UI** ([`src/ui/layout3d.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/layout3d.c)) provides WebGL visualization of the code graph.

## Frequently Asked Questions

### What makes DeusData codebase-memory-mcp different from other code-intelligence tools?

Unlike tools that rely on external language servers or containerized runtimes, DeusData codebase-memory-mcp ships as a single static C binary that embeds all grammars and type resolvers. According to the source code in [`src/pipeline/pass_lsp_cross.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/pipeline/pass_lsp_cross.c), it implements a custom "hybrid LSP" layer that resolves types and imports natively without spawning separate processes, achieving zero-dependency operation while supporting 158 languages through vendored tree-sitter grammars.

### How does the incremental indexing work?

The architecture uses [`src/watcher/watcher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/watcher/watcher.c) to monitor the file system and git state. When changes are detected, the watcher invalidates only affected nodes in the graph buffer and re-runs the minimal set of pipeline passes (discovery, parse, and LSP resolution) for modified files. This incremental approach avoids full-repository rescans, as implemented in the pipeline orchestration logic of [`src/pipeline/pipeline.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/pipeline/pipeline.c).

### Can I query the code graph using standard graph query languages?

Yes. The [[`src/cypher/cypher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.c) module implements a read-only subset of openCypher. You can execute queries via the `query_graph` MCP tool or CLI command, performing pattern matches against nodes (functions, classes, routes) and relationships (calls, imports, HTTP endpoints) stored in the compressed SQLite backend.

### Is the 3-D UI required to use the tool?

No. The 3-D visualization layer in [`src/ui/http_server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/http_server.c) and [`src/ui/layout3d.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/layout3d.c) is an optional compile-time component. The core MCP server, CLI, and graph engine function entirely without it, making the tool suitable for headless CI/CD environments and remote development servers where browser-based visualization is unnecessary.