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

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, which implements the low-level compressed storage layer, and 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 – Build configuration for the development server
• 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 – Orchestrates compilation using Makefile.cbm to produce the static binary at build/c/codebase-memory-mcp
• scripts/lint.sh – Runs code quality checks
• setup.sh – Development environment initialization

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

# 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 – Validates import resolution across multiple languages
• tests/test_git_context.c – Tests Git integration and context extraction

Run the test suite using the same Makefile infrastructure:

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 – 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, 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 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 to compile the static binary
• 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:

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

To run the optional UI server:

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, Makefile.cbm, 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 that verify engine functionality, while test-infrastructure/ provides Docker containers and CI configuration files such as 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 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 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.

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