How to Contribute to the DeusData codebase-memory-mcp Project

Fork the repository, build the C binary using scripts/build.sh, validate changes with scripts/test.sh and scripts/lint.sh, sign off your commits per the DCO, and submit a pull request following the conventional commit format specified in CONTRIBUTING.md.

The codebase-memory-mcp project is a high-performance knowledge-graph engine written in pure C that creates structural representations of codebases using vendored tree-sitter grammars. Before modifying the indexing pipeline or MCP server logic, contributors should understand the repository's layered architecture and the specific quality gates enforced by the maintainers.

Understanding the Repository Architecture

The codebase is organized into distinct layers that separate low-level utilities from high-level protocol handling. When contributing, target the appropriate layer based on your change:

• Foundations (src/foundation/arena.c): Arena allocator, hash tables, and platform abstractions.
• Discovery (src/discover/discover.c): Git repository discovery, .gitignore parsing, and language detection.
• Tree-sitter Extraction (internal/cbm/lang_specs.c): 64 bundled grammars, AST walkers, and language specifications.
• Pipeline (src/pipeline/pass_definitions.c): Multi-pass indexing for definitions, calls, imports, HTTP routes, and infrastructure scanning.
• Store (src/store/store.c): SQLite-backed graph persistence with FTS5 full-text indexing.
• MCP Server (src/mcp/mcp.c): JSON-RPC 2.0 entry point exposing 15 tools for search, trace, and architecture queries.
• CLI & UI (src/cli/cli.c, graph-ui/package.json): Command-line wrappers and optional 3D graph visualization (React/Three.js).

Setting Up the Development Environment

To build codebase-memory-mcp locally, you need a C compiler, make, and zlib. The optional 3D UI requires Node.js 22 or later.

1. Fork and clone the repository:

git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp

2. Build the native binary:

scripts/build.sh

This produces the executable at build/c/codebase-memory-mcp. Verify your baseline by running the full test suite:

scripts/test.sh

The test harness compiles with AddressSanitizer (ASan) and UndefinedBehaviorSanitizer (UBSan), executing approximately 2040 test cases.

Step-by-Step Contribution Workflow

Follow the complete guidelines in CONTRIBUTING.md while executing these steps:

1. Create a feature branch using conventional commit prefixes (e.g., feat(pipeline): or fix(store):).
2. Modify the appropriate layer based on the architecture table above.
3. Add or update tests in tests/ using the TEST() macro (e.g., add cases in tests/test_pipeline.c).
4. Run quality checks before committing:

scripts/lint.sh
make -f Makefile.cbm security

5. Sign off your commits to satisfy the Developer Certificate of Origin (DCO):

git commit -s -m "feat: add Rust generic resolution"

6. Push and open a Pull Request that references a pre-opened issue. The CI pipeline automatically runs all checks, and maintainers review designs that touch public APIs or indexing logic.

Extending Language and Infrastructure Support

When improving language extraction (e.g., enhancing Python type inference) or adding infrastructure detectors, modify both the specification and the pipeline pass.

Adding a New Infrastructure Detector

Edit src/pipeline/pass_infrascan.c to implement detection logic:

/* src/pipeline/pass_infrascan.c */
static bool cbm_is_helm_chart(const char *path) {
    return ends_with(path, ".helm.yaml");
}

/* Register the new pass in pipeline.c */
register_pass("helm_scan", cbm_is_helm_chart, extract_helm_chart);

Add a corresponding unit test in tests/test_pipeline.c:

TEST(infra_is_helm_chart) {
    ASSERT_TRUE(cbm_is_helm_chart("deployment.helm.yaml"));
    ASSERT_FALSE(cbm_is_helm_chart("main.c"));
}

For language grammar changes, update internal/cbm/lang_specs.c and adjust the corresponding extractor in src/pipeline/ (e.g., pass_semantic.c). Always validate against a real repository after running scripts/test.sh.

Summary

• Clone and build using scripts/build.sh after installing C compiler dependencies.
• Target the correct layer: Foundation, Discovery, Pipeline, Store, or MCP Server based on your feature.
• Validate thoroughly by running scripts/test.sh (ASan/UBSan), scripts/lint.sh, and make -f Makefile.cbm security.
• Follow DCO requirements by signing off all commits (git commit -s).
• Reference CONTRIBUTING.md for the full policy on commit messages and pull request procedures.

Frequently Asked Questions

Do I need to know C to contribute to codebase-memory-mcp?

Core engine contributions require C, as the indexing pipeline, SQLite storage layer, and MCP server are implemented in pure C. However, the optional 3D graph UI in graph-ui/package.json uses React and Three.js, allowing JavaScript/TypeScript contributors to improve visualization features without modifying the C backend.

How do I add support for a new programming language?

Edit internal/cbm/lang_specs.c to register the tree-sitter grammar and language metadata, then implement or extend the AST walker in the appropriate src/pipeline/ file (such as pass_semantic.c). Add regression tests in tests/test_pipeline.c and verify the extraction against real repositories before submitting.

What testing is required before submitting a pull request?

You must run scripts/test.sh, which builds with AddressSanitizer and UndefinedBehaviorSanitizer and executes approximately 2040 test cases. Additionally, execute scripts/lint.sh for static analysis and make -f Makefile.cbm security for security auditing. All commits must be signed off (git commit -s) to comply with the DCO.

How do I configure the MCP server for local development?

Build the binary and enable auto-indexing:

./build/c/codebase-memory-mcp config set auto_index true

Restart your coding agent and trigger "Index this project" to populate the SQLite graph store. The server exposes 15 tools via JSON-RPC 2.0 from src/mcp/mcp.c, which you can test against local repositories to verify your changes.

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