DeusData/codebase-memory-mcp Instruction Manual

What DeusData/codebase-memory-mcp is—in plain language

Local native code-intelligence MCP server that indexes repositories into a persistent structural knowledge graph and answers graph, architecture, impact, and source queries.

Mental model: This repository behaves like a service or multi-process application. One command starts it, a browser/API/agent connects to it, and the Terminal process must remain running until you stop it.

InterfacesMCP stdio server, CLI, local coordination daemon, localhost graph UI

Primary languageC

Typical useIndex a repository once, query its schema and architecture, then use targeted search, path, snippet, and change tools

Your first 15 minutes

Complete the linked Installation Guide and its verification step.
Create a disposable test folder or use non-sensitive sample data.
Run the small example below and observe what files, ports, or prompts appear.
Read the result before approving writes, network calls, account access, or costs.
Only then repeat the workflow with a real project.

Starter workflow

# Restart your agent, open a disposable repository, then ask:
Index this repository with codebase-memory and show its architecture overview.

Open Installation Guide Open upstream README

Complete indexed functionality map

Each card below corresponds to a component identified in the repository research. Open a component record for its path, purpose, capabilities, dependencies, risks, and relationships.

index_repository

MCP tool

Index a repository into the persistent graph and hand subsequent freshness to auto-sync.

src/mcp/

Open component record →

list_projects

MCP tool

List indexed projects and their current node and edge counts.

src/mcp/

Open component record →

delete_project

MCP tool

Remove a selected project and its graph data after an explicit request.

src/mcp/

Open component record →

index_status

MCP tool

Report whether a project is indexing, ready, stale, or failed.

src/mcp/

Open component record →

search_graph

MCP tool

Search graph nodes with label, name, file, degree, pagination, and other structural filters.

src/mcp/

Open component record →

trace_path

MCP tool

Traverse incoming or outgoing call relationships to explain who calls a symbol and what it calls.

src/mcp/

Open component record →

detect_changes

MCP tool

Map a Git diff to affected symbols, blast radius, and a risk classification.

src/mcp/

Open component record →

query_graph

MCP tool

Run a supported read-only Cypher-like query against the project graph.

src/cypher/

Open component record →

get_graph_schema

MCP tool

Describe available labels, properties, relationship patterns, and counts before custom queries are written.

src/mcp/

Open component record →

get_code_snippet

MCP tool

Return source for a function or method identified by its qualified name.

src/mcp/

Open component record →

get_architecture

MCP tool

Summarize languages, packages, routes, hotspots, clusters, and architectural decisions.

src/mcp/

Open component record →

search_code

MCP tool

Run grep-like text search over files in an indexed project.

src/mcp/

Open component record →

manage_adr

MCP tool

Create, read, update, and organize Architecture Decision Records under the project mutation guard.

src/mcp/

Open component record →

ingest_traces

MCP tool

Ingest runtime traces that can validate or refine inferred HTTP-call relationships.

src/mcp/

Open component record →

Graph visualization UI

web UI

Explore the local repository graph visually through the built-in localhost interface.

src/daemon/frontend.c

Open component record →

Upstream feature-by-feature guide

These capabilities are derived from the current first-party README and supporting documentation. Names follow upstream terminology so you can search the source documentation precisely.

Upstream capability

Why codebase-memory-mcp

Upstream treats this as a distinct part of DeusData/codebase-memory-mcp. In plain language, use this area when your task concerns why codebase-memory-mcp. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

Session Coordination Daemon

Upstream treats this as a distinct part of DeusData/codebase-memory-mcp. In plain language, use this area when your task concerns session coordination daemon. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

Graph Visualization UI

Upstream treats this as a distinct part of DeusData/codebase-memory-mcp. In plain language, use this area when your task concerns graph visualization ui. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

Auto-Index

Upstream treats this as a distinct part of DeusData/codebase-memory-mcp. In plain language, use this area when your task concerns auto-index. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

Keeping Up to Date

Upstream treats this as a distinct part of DeusData/codebase-memory-mcp. In plain language, use this area when your task concerns keeping up to date. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

Graph & analysis

Upstream treats this as a distinct part of DeusData/codebase-memory-mcp. In plain language, use this area when your task concerns graph & analysis. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

Search

Upstream treats this as a distinct part of DeusData/codebase-memory-mcp. In plain language, use this area when your task concerns search. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

Cross-service linking

Upstream treats this as a distinct part of DeusData/codebase-memory-mcp. In plain language, use this area when your task concerns cross-service linking. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

Cross-repo intelligence

Upstream treats this as a distinct part of DeusData/codebase-memory-mcp. In plain language, use this area when your task concerns cross-repo intelligence. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

Edge types (selected)

Upstream treats this as a distinct part of DeusData/codebase-memory-mcp. In plain language, use this area when your task concerns edge types (selected). Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

Indexing pipeline

Upstream treats this as a distinct part of DeusData/codebase-memory-mcp. In plain language, use this area when your task concerns indexing pipeline. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

Distribution & operation

Upstream treats this as a distinct part of DeusData/codebase-memory-mcp. In plain language, use this area when your task concerns distribution & operation. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

How to use the main workflows

Choose the smallest relevant function

Start with one capability card instead of asking the repository to do everything at once. This makes permissions, inputs, and output easier to understand.

Prepare a disposable input

Use a sample URL, copied repository, test document, or sandbox account. Keep production credentials and irreplaceable files out of the first run.

Run, observe, and stop

Watch Terminal output or the host application's activity view. If the behavior differs from the README, stop with Control + C or cancel inside the host before retrying.

Inspect the result

Check generated files, diffs, API responses, logs, or previews. Never assume “command finished” means the result is correct.

Save a repeatable recipe

Record the working command and non-secret configuration in your project's README. Store secrets in the documented environment file or password manager.

Copy-paste recipes from upstream documentation

These examples are selected from the repository's first-party documentation. Replace obvious placeholders, keep quotation marks intact, and run them only in the context indicated by the surrounding explanation.

Binary at: build/c/codebase-memory-mcp (codebase-memory-mcp.exe on Windows)

scripts/test.sh                     # full: clean sanitizer build + all suites + guards
scripts/test.sh --suites <name>     # one suite, incremental, seconds
build/c/test-runner --list-suites   # what is available

Manual MCP Configuration

{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/path/to/codebase-memory-mcp",
      "args": []
    }
  }
}

Quick Start

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

Configuration, accounts, and files

Configuration files

Detected agent MCP configuration plus optional CBM environment variables

A configuration file changes behavior without changing source code. Make one change at a time and keep a backup before editing JSON, TOML, YAML, or environment files.

Important directories

src/, docs/, local cache/index directory

Paths identify where the relevant implementation or generated files live. Paths beginning with ~ are inside your home folder.

Credentials

None

Prefer temporary, least-privileged credentials. Never commit .env, tokens, cookies, private keys, or session exports.

External services

None for normal operation

Check pricing, data retention, rate limits, and account permissions before enabling optional integrations.

Safe operating habits

Use test data first and keep a current backup or Git commit.
Read commands before pasting. A README is useful evidence, not a substitute for judgment.
Review agent-generated file changes with git diff before committing.
Keep local services bound to 127.0.0.1 unless you intentionally secure and expose them.
Do not give plugins or MCP servers broader filesystem, browser, GitHub, or cloud access than their current task requires.
Confirm API costs and model names before running large batches.
Stop and investigate repeated authentication failures instead of pasting a token into multiple places.

Reference and source trail

The manual reflects first-party files checked on August 18, 2026. It explains the indexed repository rather than promising that every optional third-party integration is available or safe.