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

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), 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) handles installation workflows, auto-detects eleven supported agents (such as Claude Desktop, Cursor, and Windsurf), and manages pre-tool hooks for repository-wide operations.

# 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) 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) 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) 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) 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) 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) 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) 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) parses graph queries, plans execution, and traverses the SQLite-backed graph.

# 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) 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) 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) computes WebGL-compatible graph layouts. This allows browser-based exploration of the knowledge graph alongside the MCP server.

# 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 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 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) that downloads the appropriate platform binary and forwards CLI arguments.

# 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) orchestrates discovery, parsing, type resolution, and graph construction.
• Hybrid LSP (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) persisted to the user's cache directory.
• ** Incremental indexing** via src/watcher/watcher.c keeps the graph synchronized with git changes.
• The MCP server (src/mcp/mcp.c) exposes fourteen JSON-RPC tools for AI agent integration.
• An optional 3-D UI (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, 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 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.

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) 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 and 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.

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