# Contributing to codebase-memory-mcp: Expected Directory Structure Guide

> Learn the expected directory structure for contributing to DeusData codebase-memory-mcp. Find out where to place C code, UI components, and documentation to ensure smooth integration.

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

---

**The codebase-memory-mcp repository organizes source code, documentation, and build artifacts into distinct top-level directories, requiring contributors to place new C code in `internal/cbm/`, UI components in `graph-ui/src/`, and documentation in `docs/` while following existing naming conventions.**

The **codebase-memory-mcp** project by DeusData follows a modular layout that separates the core C implementation, TypeScript frontend, documentation, and build configuration. Understanding this directory structure is essential for contributors who want to add new language grammars, improve the visualization UI, or extend the testing infrastructure. This guide walks through the repository layout as defined in the [`CONTRIBUTING.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/CONTRIBUTING.md) and source tree, ensuring your changes integrate cleanly with the existing build system.

## Top-Level Directory Overview

At the root of the repository, you'll find configuration files and entry points that govern the build process and project metadata:

- **`Makefile.cbm`** – Primary build entry point for the C-based "cbm" component, defining compilation targets and test runners.
- **`flake.nix`** and **`flake.lock`** – Nix flakes for reproducible development environments, ensuring consistent dependencies across machines.
- **[`install.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/install.sh)** and **`install.ps1`** – Convenience scripts for installing the binary on Unix-like systems and Windows respectively.
- **[`glama.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/glama.json)** – Configuration for the Glama static analysis tool.
- **[`CONTRIBUTING.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/CONTRIBUTING.md)** – Detailed contributor guidelines covering fork workflows, coding standards, and testing requirements.
- **`docs/`** – Human-readable documentation including HTML pages, configuration guides, and evaluation plans.
- **[`server.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/server.json)** – Example configuration for running a server instance of the tool.

## Core Implementation in `internal/cbm/`

The heart of the project lives in `internal/cbm/`, which contains the **Codebase Memory MCP** library implementation. This directory houses C source files and headers that handle parsing, extraction, and graph generation.

Key files in this directory include:

- **[`cbm.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/cbm.c)** and **[`cbm.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/cbm.h)** – Core library entry points and public API definitions.
- **`grammar_*.c`** files – Tree-sitter grammar implementations for supported programming languages.
- **`extract_*.c`** files – Extraction utilities that parse source code into graph structures.

When contributing new language support, create files following the existing naming convention (e.g., [`grammar_foolang.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/grammar_foolang.c) and [`grammar_foolang.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/grammar_foolang.h) for a hypothetical "FooLang") and update the `Makefile.cbm` to include the new compilation units.

## Frontend Visualization with `graph-ui/`

The **`graph-ui/`** directory contains a **Vite-based TypeScript** application for visualizing code-graph queries. This is an isolated frontend module that builds independently from the C core.

Key configuration files here include:

- **[`vite.config.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/vite.config.ts)** – Build configuration for the development server and production bundling.
- **[`tsconfig.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tsconfig.json)** – TypeScript compiler settings.
- **`src/`** – React components and UI logic for the graph visualization interface.

New UI components should be added to `graph-ui/src/` following the existing React/TypeScript patterns, with styles and tests co-located according to the project's frontend conventions.

## Documentation and Testing Infrastructure

Documentation resides exclusively in the **`docs/`** directory, which contains markdown guides, HTML index files, and screenshots. The **[`CONFIGURATION.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/CONFIGURATION.md)** and **[`EVALUATION_PLAN.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/EVALUATION_PLAN.md)** files live here, alongside [`index.html`](https://github.com/DeusData/codebase-memory-mcp/blob/main/index.html) for the GitHub Pages site.

For testing, the **`test-infrastructure/`** directory provides **Docker-based** integration testing. It contains:

- **[`docker-compose.yml`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docker-compose.yml)** – Service definitions for reproducible test environments.
- Dockerfiles for setting up isolated test runners.
- Helper scripts for executing the full test suite.

The **`pkg/`** directory houses packaging artifacts, including the Python wrapper for the binary located in `pkg/pypi/` with its own [`README.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md) and [`setup.cfg`](https://github.com/DeusData/codebase-memory-mcp/blob/main/setup.cfg).

## Contribution Workflow and Build Commands

To contribute effectively, use the Nix-based development environment for consistency. The repository supports a standardized workflow for building, testing, and submitting changes.

First, clone the repository and enter the development shell:

```bash
git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
nix develop

```

Build the project and run tests using the Makefile:

```bash
make build
make test

```

When adding a new grammar for language support:

1. Create the source files in `internal/cbm/`:

```bash
touch internal/cbm/grammar_newlang.c
touch internal/cbm/grammar_newlang.h

```

2. Add the new files to the `Makefile.cbm`, following the pattern of existing `grammar_*.c` entries.

3. Verify compilation:

```bash
make build

```

Submit your changes by creating a feature branch, committing with descriptive messages, and opening a Pull Request that references any relevant issues:

```bash
git checkout -b feature/add-newlang-grammar
git add internal/cbm/grammar_newlang.c internal/cbm/grammar_newlang.h Makefile.cbm
git commit -m "Add Tree-sitter grammar for NewLang"
git push origin feature/add-newlang-grammar

```

## Summary

- **Source code** belongs in `internal/cbm/` for C implementations and `graph-ui/src/` for TypeScript UI components.
- **Documentation** updates go in the `docs/` directory to ensure GitHub Pages compatibility.
- **Build configuration** is centralized in `Makefile.cbm` and `flake.nix`, which must be updated when adding new dependencies or source files.
- **Testing** relies on Docker environments in `test-infrastructure/` to maintain reproducible CI results.
- **New contributions** should follow existing file naming conventions (e.g., `grammar_<language>.c`) and be validated with `make test` before submitting PRs.

## Frequently Asked Questions

### Where should I place new C code when contributing to codebase-memory-mcp?

Place new C source files and headers in the `internal/cbm/` directory, following the existing naming pattern such as `grammar_<language>.c` for language parsers or `extract_<feature>.c` for extraction utilities. You must also register these files in the `Makefile.cbm` to ensure they compile with the rest of the project.

### How do I set up a development environment for codebase-memory-mcp?

Use the provided Nix flake for a reproducible development environment by running `nix develop` in the repository root after cloning. Alternatively, you can use the [`install.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/install.sh) (Unix) or `install.ps1` (Windows) scripts for direct binary installation, though Nix is recommended for active development to match the CI environment.

### What is the purpose of the `graph-ui/` directory?

The `graph-ui/` directory contains a standalone Vite-based TypeScript frontend for visualizing code graphs generated by the C core. It operates independently with its own build system (configured via [`vite.config.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/vite.config.ts) and [`tsconfig.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tsconfig.json)), allowing contributors to work on UI features without compiling the C components.

### How are tests organized in the codebase-memory-mcp repository?

Integration and system tests are housed in `test-infrastructure/` using Docker Compose to ensure consistent, isolated test environments across different machines. While unit tests for C code may be added within this directory or a dedicated tests folder, the Docker-based setup guarantees that CI runs match local test results, preventing "works on my machine" issues.