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

> Explore the DeusData codebase-memory-mcp project structure. Learn how its three-tier architecture separates C libraries, extraction engines, graph storage, server, and frontend for a robust foundation.

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

---

**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)](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)](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)](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)](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)](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)](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md).
- **Root configuration** – [`README.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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)](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)](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)](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)](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)](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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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)](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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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)](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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/embed-frontend.sh).

## Practical Usage Examples

The project structure supports multiple interaction patterns:

### Running One-Shot Queries via CLI

```bash

# 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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

```bash

# Build with UI assets (requires Node.js)

make -f Makefile.cbm cbm-with-ui

```

This invokes the `frontend` target in [`scripts/build.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/embedded_assets.c)) linked via the `embed` target.

### Programmatic Daemon Access

```c
/* 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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)](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/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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)](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)](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)](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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/build.sh) compiles the React application and [`scripts/embed-frontend.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/embed-frontend.sh) converts the static files into C source code at [`src/ui/embedded_assets.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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)](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.