Core Components of DeusData Codebase-Memory-MCP: Technical Architecture Guide

The core components of DeusData codebase-memory-mcp comprise a static C binary embedding an MCP JSON-RPC server, SQLite graph database, Tree-Sitter parsing engine with Hybrid LSP resolution, background file watcher, optional WebGL UI server, and a Python installation shim that together deliver zero-dependency code intelligence.

The DeusData codebase-memory-mcp is engineered as a self-contained static binary designed to provide AI coding agents with deep semantic understanding of repositories without requiring external language servers or complex runtime environments. By packaging 158 Tree-Sitter grammars, LZ4 compression, and SQLite persistence into a single executable, the system achieves sub-millisecond query latency while indexing 28 million lines of code in approximately three minutes. Understanding these architectural layers reveals how the platform maintains IDE-grade code resolution while remaining deployable via a simple pip install.

Binary Entry Point and MCP Server

The foundation rests on [src/main.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c), which serves as the universal entry point that initializes the MCP JSON-RPC server, command-line interface, and optional UI modes. This minimal C bootstrap configures the runtime and dispatches incoming requests to the appropriate subsystem.

The [src/mcp/](https://github.com/DeusData/codebase-memory-mcp/tree/main/src/mcp) directory implements the Model Context Protocol interface, exposing 14 JSON-RPC tools including index_repository, search_graph, trace_path, and query_graph. These handlers translate agent requests into optimized SQL or graph traversals, returning structured data about symbols, dependencies, and call relationships. Communication occurs over STDIO, ensuring compatibility with any MCP-compliant client from Claude Code to VS Code extensions and OpenCode.

Graph Storage Engine

Persistent knowledge representation is managed by [src/store/](https://github.com/DeusData/codebase-memory-mcp/tree/main/src/store), which abstracts SQLite databases located at ~/.cache/codebase-memory-mcp/<project>/graph.db. This layer stores heterogeneous nodes (representing Project, File, Function, Route, and other entities) and edges (capturing CALLS, IMPORTS, HTTP_CALLS, and semantic relationships).

The storage engine employs LZ4 compression and specialized indexing to execute complex graph queries in under one millisecond. All persistence operations are exposed through a C API consumed by both the indexing pipeline and the MCP server, ensuring atomic writes and crash-safe durability.

Indexing Pipeline and Language Analysis

The multi-pass pipeline in [src/pipeline/](https://github.com/DeusData/codebase-memory-mcp/tree/main/src/pipeline) orchestrates the transformation of source code into queryable knowledge graphs through three integrated subsystems:

Tree-Sitter Front-End

The [internal/cbm/](https://github.com/DeusData/codebase-memory-mcp/tree/main/internal/cbm) component contains vendored grammars for 158 programming languages compiled directly into the binary. Language-specific parsers (such as grammar_python.c and grammar_cpp.c) generate concrete syntax trees that feed the initial extraction of definitions and call sites.

Hybrid LSP Layer

Located in [src/hybrid_lsp/](https://github.com/DeusData/codebase-memory-mcp/tree/main/src/hybrid_lsp), this layer contains language-specific C implementations that enrich syntactic ASTs with semantic type information. Unlike traditional Language Server Protocol implementations that spawn separate processes, this hybrid resolver analyzes imports, generics, inheritance, and standard library symbols internally. It produces semantic CALLS and IMPORTS edges that accurately distinguish between function definitions and actual invocations, providing AI agents with precise dependency graphs without the latency of external language servers.

Discovery and Graph Construction

The discover module respects .gitignore and .cbmignore patterns while walking repositories to identify parseable files. Parsed ASTs flow through the Hybrid LSP resolver, then stream into an in-memory SQLite database that is atomically persisted to disk upon indexing completion.

Background Services and Visualization

File Watcher and Auto-Indexer

The [src/watcher/](https://github.com/DeusData/codebase-memory-mcp/tree/main/src/watcher) component implements a background daemon that polls Git for changes and incrementally re-indexes only affected files. This ensures the knowledge graph remains synchronized with the working directory without requiring full repository rebuilds.

WebGL UI Server

When invoked with the --ui flag, the binary activates [src/ui/](https://github.com/DeusData/codebase-memory-mcp/tree/main/src/ui), which hosts a 3-D WebGL graph visualizer accessible at localhost:9749. This optional component renders the code graph interactively, complementing the programmatic MCP interface used by AI agents.

Distribution and Installation Layer

Python Shim and CLI Wrapper

The [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) script serves as the primary distribution mechanism. This shim performs three critical functions: detecting the host platform and architecture, downloading the appropriate static binary via _download(), and verifying its integrity using _verify_checksum() before execution. The [pkg/pypi/src/codebase_memory_mcp/__init__.py](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/pypi/src/codebase_memory_mcp/__init__.py) exposes __version__ and the main entry point, enabling pip install codebase-memory-mcp while maintaining the performance characteristics of compiled C.

Build and Configuration Infrastructure

Installation automation is provided by [scripts/install.sh](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/install.sh) and [scripts/build.sh](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/build.sh), which handle platform detection, binary verification, and agent integration. Runtime behavior is controlled through the codebase-memory-mcp config command and environment variables that manage cache locations, logging verbosity, and worker thread counts.

Practical Usage Examples

Installing via Shell Script

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

This invocation leverages the Python shim to download the correct platform binary and verify its SHA-256 checksum before installation.

Indexing a Repository

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

The index_repository tool triggers the full discovery → parsing → Hybrid LSP pipeline, persisting results to ~/.cache/codebase-memory-mcp/<project>/graph.db.

Searching Function Definitions

codebase-memory-mcp cli search_graph '{"label":"Function","name_pattern":"^handle_.*"}'

This queries the SQLite backing store for nodes with the Function label matching the glob pattern, returning JSON arrays containing node identifiers, file paths, and line numbers.

Tracing Call Paths

codebase-memory-mcp cli trace_path '{"function_name":"process_order","direction":"both","depth":3}'

The MCP server executes a breadth-first search on CALLS edges, traversing inbound and outbound relationships up to the specified depth to generate dependency subgraphs for context-aware AI assistance.

Executing Cypher Queries

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

The built-in Cypher executor (implemented in src/cypher/) parses openCypher-style graph queries and compiles them into optimized SQL for execution against the underlying SQLite store.

Using the Python API

from codebase_memory_mcp import main

# Executes the platform-specific binary with automatic download

main()

The Python wrapper ensures the correct architecture-specific binary is available via _download() before execution, providing seamless cross-platform distribution.

Summary

• Single Static Binary: The system compiles into one file containing SQLite, LZ4, 158 Tree-Sitter grammars, and the MCP server, eliminating external runtime dependencies.
• Hybrid LSP Architecture: Language-specific resolvers in src/hybrid_lsp/ provide semantic analysis without spawning separate language server processes, maintaining sub-millisecond query latency.
• SQLite Graph Store: Persistent storage in ~/.cache/codebase-memory-mcp/ uses compressed SQLite with custom indexes to support complex graph queries on repositories containing millions of lines.
• Multi-Pass Pipeline: Indexing flows from file discovery through Tree-Sitter parsing to Hybrid LSP resolution before writing semantic nodes and edges to the graph database.
• MCP Protocol Integration: Fourteen JSON-RPC tools expose graph operations to any MCP-compliant AI agent, using STDIO transport for universal compatibility.
• Incremental Updates: The file watcher daemon polls Git state and re-indexes only modified files, keeping the knowledge graph synchronized with minimal overhead.
• Python Distribution Layer: The _cli.py shim downloads platform-specific binaries and verifies checksums, enabling pip install convenience with C-level execution performance.

Frequently Asked Questions

What makes the DeusData codebase-memory-mcp different from traditional language servers?

Traditional language servers require external runtime environments (Node.js, Python, or JVM) and maintain volatile in-memory state. The DeusData codebase-memory-mcp compiles everything into a static binary with embedded SQLite persistence, indexing 28 million lines of code in approximately three minutes and answering queries in under one millisecond without external dependencies. Its Hybrid LSP layer performs semantic resolution internally rather than delegating to separate language-specific servers.

How does the Python wrapper work if the core system is written in C?

The Python package in pkg/pypi/src/codebase_memory_mcp/_cli.py acts as a thin shim that detects the host operating system and architecture, downloads the appropriate pre-compiled binary from GitHub releases, verifies its SHA-256 checksum using _verify_checksum(), and then replaces the Python process with the binary via exec(). This provides the convenience of pip install while ensuring users run the compiled C implementation for maximum performance.

Where is the knowledge graph data stored between sessions?

All graph data persists in SQLite databases located at ~/.cache/codebase-memory-mcp/<project_name>/graph.db. The src/store/ component manages these files using LZ4 compression for space efficiency. The optional background watcher monitors Git state and incrementally updates these databases when files change, ensuring AI agents always query current repository states.

Can I query the code graph using familiar graph database syntax?

Yes, the system includes a Cypher query executor in src/cypher/ that supports openCypher-style syntax. You can execute complex pattern matches like MATCH (f:Function)-[:CALLS]->(g:Function) WHERE f.name = "main" RETURN g.name through the query_graph MCP tool. The engine parses these queries and translates them into optimized SQLite operations against the underlying graph schema.

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