# Key Directories in the DeusData/codebase-memory-mcp Repository: A Structural Breakdown

> Explore the DeusData/codebase-memory-mcp repository structure. Understand the purpose of key directories like internal graph-ui scripts tests test-infrastructure and docs for efficient development.

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

---

**The DeusData/codebase-memory-mcp repository organizes its source code into six primary top-level directories: `internal/` for the core C engine, `graph-ui/` for the 3D visualization interface, `scripts/` for build automation, `tests/` for C unit tests, `test-infrastructure/` for Docker-based CI, and `docs/` for documentation and guides.**

The repository follows a strict separation-of-concerns architecture, grouping the **MCP (Model Context Protocol) engine**, web interface, testing infrastructure, and automation tooling into distinct locations. This structure supports the project's goal of parsing source code via tree-sitter, building compressed knowledge graphs, and serving them through both JSON-RPC tools and an optional 3D visualizer.

## Core Engine: The `internal/` Directory

The **`internal/`** directory houses the **core C implementation** of the MCP engine. This is the heart of the system, responsible for parsing source files using vendored tree-sitter grammars, constructing the knowledge graph, and executing Cypher queries against the graph database.

Key components stored here include:
- **Tree-sitter grammars** for multi-language parsing
- **Index pipeline** for ingesting repositories
- **Cypher executor** for graph queries
- **File watcher** for real-time updates
- **ZSTD-compressed SQLite store** implementation

Representative files include [`internal/cbm/zstd_store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.c), which implements the low-level compressed storage layer, and [`src/main.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c) (located within `internal/`), which serves as the entry point for the engine. According to the DeusData source code, this directory compiles into a static binary that provides the `codebase-memory-mcp` command-line interface.

## Visualization Layer: The `graph-ui/` Directory

The **`graph-ui/`** directory contains a **Vite-based Single Page Application (SPA)** that provides an optional 3D graph visualizer. This frontend connects to the same SQLite graph database used by the core engine and renders interactive 3D views of code relationships.

Key files here include:
- [`vite.config.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/vite.config.ts) – Build configuration for the development server
- [`index.html`](https://github.com/DeusData/codebase-memory-mcp/blob/main/index.html) – Entry point for the SPA

When running with `--ui=true`, the engine serves this interface at `http://localhost:9749`, allowing developers to explore codebases visually. The UI backend code that supports this functionality also resides within the `internal/` directory, while the frontend assets live here in `graph-ui/`.

## Build and Automation: The `scripts/` Directory

The **`scripts/`** directory contains convenience **shell and PowerShell scripts** for development workflows. These automate the compilation, linting, security auditing, and release processes for the C engine.

Critical scripts include:
- [`scripts/build.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/build.sh) – Orchestrates compilation using `Makefile.cbm` to produce the static binary at `build/c/codebase-memory-mcp`
- [`scripts/lint.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/lint.sh) – Runs code quality checks
- [`setup.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/setup.sh) – Development environment initialization

To build from source, developers invoke these scripts rather than calling the Makefile directly:

```bash

# Build the static binary (uses Makefile.cbm internally)

scripts/build.sh

# Build with UI support

scripts/build.sh --with-ui

```

## Testing Infrastructure

The repository maintains rigorous testing standards through two distinct directories: one for the C test suite and another for the Docker-based test harness.

### Unit and Integration Tests (`tests/`)

The **`tests/`** directory contains **low-level C unit and integration tests** that verify the correctness of the parsing engine, graph construction algorithms, and LSP features. These tests focus specifically on the C implementation found in `internal/`.

Key test files include:
- [`tests/test_grammar_imports.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_grammar_imports.c) – Validates import resolution across multiple languages
- [`tests/test_git_context.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_git_context.c) – Tests Git integration and context extraction

Run the test suite using the same Makefile infrastructure:

```bash
cd tests
make test

```

### Docker-Based CI (`test-infrastructure/`)

The **`test-infrastructure/`** directory provides a **Docker-based test harness** and continuous integration helpers. This includes container configurations for isolated testing environments and CI pipeline definitions.

Files here include:
- [`docker-compose.yml`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docker-compose.yml) – Orchestrates test services
- `Dockerfile` – Container definition for the build environment

## Documentation and Root Configuration

The **`docs/`** directory contains human-readable documentation, configuration guides, and screenshots that are rendered on GitHub Pages. This includes [`docs/CONFIGURATION.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md), which provides a full description of all MCP server configuration options, and `graph-ui-screenshot.png` for visual reference.

In the repository root, several critical files complement the directory structure:
- **[`install.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/install.sh)** and **`install.ps1`** – Platform-specific installers (POSIX and Windows) that handle binary downloads, checksum verification, and placement
- **`Makefile.cbm`** – Build orchestration file used by [`scripts/build.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/build.sh) to compile the static binary
- **[`server.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/server.json)** – Default MCP server configuration specifying ports, logging levels, and runtime defaults
- **`.clang-format`** and **`.clang-tidy`** – C code style and static analysis configuration

## How the Components Interact

The architectural relationship between these directories follows a clear data flow:

1. The **`internal/`** engine parses source repositories using tree-sitter grammars and writes to a ZSTD-compressed SQLite graph store
2. The **`graph-ui/`** frontend reads from this same SQLite database to render interactive 3D visualizations
3. **`scripts/`** automation ensures both components build correctly and pass quality checks
4. **`tests/`** validates that parsing and graph construction remain correct across updates

To index a repository using the compiled engine:

```bash
codebase-memory-mcp index_repository '{"repo_path":"/path/to/my/project"}'

```

To run the optional UI server:

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

```

## Summary

- **`internal/`** contains the core C MCP engine with tree-sitter parsing, Cypher execution, and ZSTD storage
- **`graph-ui/`** hosts the Vite-based 3D visualization frontend that connects to the graph database
- **`scripts/`** provides shell automation for building, linting, and releasing the static binary
- **`tests/`** holds C unit tests for grammar imports, git context, and graph construction
- **`test-infrastructure/`** configures Docker-based CI environments for isolated testing
- **`docs/`** and root files ([`install.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/install.sh), `Makefile.cbm`, [`server.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/server.json)) provide documentation, installation, and build orchestration

## Frequently Asked Questions

### What is the difference between the `tests/` and `test-infrastructure/` directories?

The **`tests/`** directory contains actual C code test files like [`tests/test_grammar_imports.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_grammar_imports.c) that verify engine functionality, while **`test-infrastructure/`** provides Docker containers and CI configuration files such as [`docker-compose.yml`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docker-compose.yml) to run those tests in isolated environments. The former holds test logic; the latter holds the runtime environment for executing that logic.

### How does the `internal/` directory relate to the `graph-ui/` visualization?

The **`internal/`** directory contains the engine that builds and queries the compressed SQLite graph database, including the UI backend code. The **`graph-ui/`** directory contains only the client-side frontend assets. When you run `codebase-memory-mcp --ui=true`, the engine serves the built assets from `graph-ui/` while reading graph data that `internal/` maintains.

### What is the purpose of `Makefile.cbm` in the root directory?

The **`Makefile.cbm`** serves as the low-level build orchestration file for compiling the static C binary. It is invoked by **[`scripts/build.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/build.sh)** rather than called directly by developers. This separation allows the scripts to handle environment setup, dependency checking, and conditional UI compilation while the Makefile manages the actual compiler flags and linking steps.

### Where is the MCP server configuration stored by default?

Default MCP server settings—including ports, logging levels, and runtime defaults—are stored in **[`server.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/server.json)** at the repository root. This JSON file is referenced by the installation scripts and the engine itself when initializing a new server instance. User-specific overrides can be provided at runtime or through environment variables.