DeusData codebase-memory-mcp Project Structure: Foundation to Frontend Architecture

The DeusData codebase-memory-mcp repository implements a three-tier foundation→core→extensions architecture, cleanly separating foundational C libraries, tree-sitter extraction engines, SQLite-backed graph storage, MCP server implementation, and an optional React-based frontend across distinct top-level directories.

The codebase-memory-mcp project by DeusData is a high-performance code intelligence engine that indexes repositories into queryable graph structures exposed via the Model Context Protocol (MCP). Understanding its project structure is essential for developers extending language support, integrating the storage backend, or deploying the optional web-based visualizer.

Top-Level Directory Layout

The repository organizes functionality into seven primary directories that mirror the system's runtime architecture:

• src/ – Core implementation containing foundation libraries, the indexing pipeline, MCP server, CLI, and UI stubs. The main entry point is [src/main.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c).
• internal/cbm/ – Re-used extraction logic, tree-sitter runtime, and low-level helpers imported from the original MCP project, with [internal/cbm/cbm.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/cbm.c) serving as the primary interface.
• tests/ – Comprehensive unit and integration tests covering foundations, extraction, storage, and security, entry at [tests/test_main.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_main.c).
• scripts/ – Build automation, CI utilities, security audit scripts, and UI embedding tools such as [scripts/build.sh](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/build.sh).
• graph-ui/ – React-based frontend source code for the optional 3-D graph visualizer, defined by [graph-ui/package.json](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/package.json).
• docs/ – Human-readable documentation, configuration guides, and benchmark data including [docs/CONFIGURATION.md](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md).
• Root configuration – README.md, Makefile.cbm, and package manifests defining build metadata and licensing.

Core Architecture Layers

The src/ directory implements a layered architecture where lower-level modules provide services to higher-level orchestration components.

Foundation Layer (src/foundation/)

The foundation layer provides reusable utilities used throughout the codebase. Key components include arena allocators, hash tables, string interning, logging subsystems, and platform abstractions.

For example, [src/foundation/arena.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/foundation/arena.c) implements memory management primitives that eliminate frequent malloc overhead during graph construction.

Extraction and LSP Layer (internal/cbm/)

Located outside the main src/ tree to denote its shared heritage, the internal/cbm/ directory contains the language extraction engine. It houses tree-sitter runtime integration and hybrid LSP resolvers for semantic type resolution across 10+ languages.

Key files include:

• [internal/cbm/extract_calls.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/extract_calls.c) – Parses function call relationships using tree-sitter grammars.
• [internal/cbm/lsp_all.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/lsp_all.c) – Orchestrates language server protocol integration with language-specific modules in internal/cbm/lsp/.

This layer interfaces with 158 bundled Tree-sitter grammars stored as vendored dependencies.

Indexing Pipeline (src/pipeline/)

The pipeline orchestrates the indexing workflow, coordinating parsing, symbol discovery, graph construction, and incremental updates. The main entry point at [src/pipeline/pipeline.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/pipeline/pipeline.c) manages the flow from raw source files to structured graph data.

Storage and Graph Buffer (src/store/ and src/graph_buffer/)

Two complementary storage systems persist and cache the code graph:

• src/store/ – Implements a SQLite-backed persistent graph with FTS5 full-text search capabilities ([src/store/store.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.c)).
• src/graph_buffer/ – Provides an in-memory representation optimized for fast traversal during query execution.

MCP Server and Daemon (src/mcp/, src/daemon/, src/watcher/)

The service layer exposes functionality via the Model Context Protocol:

• src/mcp/mcp.c – Implements the JSON-RPC interface exposing 15 tools including search, trace, architecture analysis, and Cypher query endpoints.
• src/daemon/daemon.c – Manages background indexing, shared cache coordination, and inter-process communication.
• src/watcher/ – Monitors file-system changes to trigger incremental re-indexing.

Command-Line Interface (src/cli/)

For one-shot operations without daemon overhead, [src/cli/cli.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.c) provides a standalone command-line interface that directly invokes the pipeline and store layers.

Optional Web UI (src/ui/ and graph-ui/)

When built with the --ui flag, the binary embeds a React frontend:

• graph-ui/ – Contains the Node.js/React source code and static assets.
• src/ui/embedded_stub.c – Acts as a build-time placeholder that gets replaced by compiled static assets during the embedding process.

Build System and Vendored Dependencies

The Makefile.cbm at the repository root defines three primary build targets:

1. cbm – Production binary with static linking of all core modules.
2. cbm-with-ui – Production binary including embedded frontend assets.
3. test-runner – Test harness compiled with address and undefined-behavior sanitizers.

The build system manages vendored dependencies including mimalloc, SQLite, LZ4, ZSTD, yyjson, tre, and 158 Tree-sitter grammar shims. Build orchestration scripts in [scripts/build.sh](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/build.sh) handle platform-specific compilation and UI asset embedding via scripts/embed-frontend.sh.

Practical Usage Examples

The project structure supports multiple interaction patterns:

Running One-Shot Queries via CLI

# Index a repository (produces a persistent SQLite graph)

codebase-memory-mcp cli index_repository --repo-path /path/to/project

# Execute a Cypher-style query against the indexed project

codebase-memory-mcp cli query_graph \
  --project my-project \
  --query 'MATCH (f:Function) WHERE f.name =~ ".*handler.*" RETURN f.name LIMIT 5'

The CLI driver in src/cli/cli.c parses these flags and forwards requests to the internal pipeline (src/pipeline/) and store (src/store/).

Embedding the UI in Custom Builds

# Build with UI assets (requires Node.js)

make -f Makefile.cbm cbm-with-ui

This invokes the frontend target in scripts/build.sh, which runs npm ci inside graph-ui/, builds the React bundle, and converts static files into C objects (src/ui/embedded_assets.c) linked via the embed target.

Programmatic Daemon Access

/* Minimal example of initializing the MCP daemon from C */
#include "internal/cbm/cbm.h"

int main(void) {
    // Initialise the daemon (creates shared cache, starts watcher)
    cbm_daemon_start();

    // Index a repository
    cbm_index_repository("/path/to/repo");

    // Perform a simple graph query
    cbm_query_graph("MATCH (f:Function) RETURN f.name LIMIT 10");

    return 0;
}

The daemon functions reside in src/daemon/ and are exported via src/mcp/mcp.c.

Summary

• DeusData codebase-memory-mcp organizes code into src/ (core), internal/cbm/ (extraction), tests/ (validation), scripts/ (build), graph-ui/ (frontend), and docs/ (guides).
• The architecture follows a foundation→core→extensions pattern, with src/foundation/ providing utilities consumed by the pipeline, store, and MCP server layers.
• Tree-sitter integration lives in internal/cbm/ alongside LSP resolvers supporting 10+ languages via 158 bundled grammars.
• Storage splits between SQLite persistence (src/store/) and in-memory graph buffers (src/graph_buffer/) for query performance.
• Service interfaces include a JSON-RPC MCP server (src/mcp/), background daemon (src/daemon/), file watcher (src/watcher/), and standalone CLI (src/cli/).
• Build system (Makefile.cbm) produces static binaries with optional UI embedding, managing vendored dependencies like mimalloc and SQLite.

Frequently Asked Questions

What is the purpose of the internal/cbm/ directory?

The internal/cbm/ directory contains extraction logic and tree-sitter runtime components reused from the original MCP project. It houses the hybrid LSP resolvers in [internal/cbm/lsp_all.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/lsp_all.c) and extraction utilities like [extract_calls.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/extract_calls.c) that parse source files using 158 bundled tree-sitter grammars. This separation isolates language-specific parsing logic from the core engine implementation in src/.

How does the project structure support multiple programming languages?

Language support is implemented through the extraction layer in internal/cbm/, which utilizes tree-sitter grammars vendored in dedicated sub-directories. The lsp_all.c module and its lsp/*.c counterparts provide semantic type resolution for over 10 languages, while the pipeline in src/pipeline/ treats language extraction as a generic interface, allowing new grammars to be added without modifying core storage or server code.

Can I use codebase-memory-mcp without running the daemon?

Yes. The src/cli/ directory provides a one-shot command-line interface via [src/cli/cli.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.c) that executes tools directly without spawning the background daemon. This is suitable for CI pipelines or single queries where persistent caching and file watching are unnecessary, though it bypasses the incremental indexing benefits provided by [src/daemon/daemon.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/daemon/daemon.c) and src/watcher/.

Where are UI assets located and how are they embedded?

The React frontend source resides in graph-ui/, with [graph-ui/package.json](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/package.json) defining its dependencies. During builds with the cbm-with-ui target, scripts/build.sh compiles the React application and scripts/embed-frontend.sh converts the static files into C source code at src/ui/embedded_assets.c. The binary links these assets via [src/ui/embedded_stub.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/embedded_stub.c), serving them through the embedded HTTP server when the UI mode is enabled.

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