How to Debug Codebase Memory MCP: A Complete Troubleshooting Guide

Enable verbose logging with codebase-memory-mcp config set log_level debug and inspect ${CBM_CACHE_DIR}/logs/cbm-daemon.log to trace parsing, extraction, and daemon coordination issues in real-time.

Codebase Memory MCP (maintained at DeusData/codebase-memory-mcp) is a pure-C knowledge-graph engine that persists repository structure using Tree-Sitter parsers. Because the entire pipeline runs locally, you can effectively debug codebase memory MCP by inspecting three distinct architectural layers and their associated log outputs.

Understanding the Three-Layer Debug Architecture

The system processes code through three sequential stages. When you debug codebase memory MCP, isolate failures by identifying which layer produces the error.

Parsing Layer (Tree-Sitter Grammars)

The engine uses vendored Tree-Sitter grammars located in internal/cbm/grammar_*.c to produce ASTs for 158 languages. If a specific language fails to parse, examine the tree_sitter_*_language() definitions in the corresponding grammar file (e.g., internal/cbm/grammar_c.c for C, internal/cbm/grammar_python.c for Python).

Extraction Layer (AST Walking)

After parsing, the system walks ASTs to emit graph nodes and edges. The key files are internal/cbm/extract_calls.c (emits CALLS edges) and internal/cbm/extract_defs.c (creates definition nodes). Insert temporary debug prints here to trace specific symbol extractions.

Coordination Daemon (cbm-daemon)

The background process watches files, schedules re-indexing, and serves the GraphQL/JSON-RPC interface. Entry points reside in internal/cbm/cbm.c, specifically the main() function leading to cbm_server_start(). Daemon logs write to ${CBM_CACHE_DIR}/logs/cbm-daemon.log.

Enable Verbose Logging to Debug Codebase Memory MCP

Start troubleshooting by activating the built-in debug channel:

codebase-memory-mcp config set log_level debug

This command configures the daemon to write detailed messages to ${CBM_CACHE_DIR}/logs/cbm-daemon.log. The log captures timestamps, file-watch events, and nanosecond performance counters (total_parse_ns, total_extract_ns) declared as _Atomic variables in internal/cbm/cbm.c.

Inspect Daemon Logs and Performance Metrics

Typical log entries follow this structure:

[2026-07-26T12:34:56.123Z] INFO  cbm-daemon: watching /my/project/src/main.c
[2026-07-26T12:35:01.456Z] DEBUG cbm-daemon: parse_time_ns=12345 extract_time_ns=6789 file=/my/project/src/main.c

• INFO lines indicate file-system activity and daemon state changes.
• DEBUG lines expose per-file parsing and extraction timings.

If the daemon fails to start, check cbm-daemon.log for early-initialization messages related to auto_index configuration conflicts.

Run One-Shot Indexing for Isolated Debugging

Bypass the daemon to debug a single file directly:

codebase-memory-mcp index /path/to/repo --verbose

The --verbose flag streams debug lines to stdout instead of the log file, making it easier to correlate output with specific source files.

Visual Debugging with the Graph UI

When running with the UI flag (codebase-memory-mcp --ui=true), open http://localhost:9749 to visualize the knowledge graph. The interface highlights nodes that failed to resolve (e.g., missing CALLS edges). Hovering over a node reveals underlying AST node IDs, which you can cross-reference with source locations in internal/cbm/extract_*.c.

Deep Dive Into Grammar and Extraction Code

For language-specific indexing failures, locate the grammar file in internal/cbm/grammar_*.c, then trace the extraction pipeline in the corresponding extract_*.c files. Add temporary debug output to print TSNode types:

/* Example debug print in internal/cbm/extract_calls.c */
static void extract_call_edge(CBMContext *ctx, TSNode node) {
    const char *name = ts_node_string(node);
    fprintf(stderr, "[debug] extract_call_edge: node=%s\n", name);
    /* existing logic … */
}

Rebuild the binary after modifying these files to apply changes immediately.

Verify Graph Consistency

Run the diagnostic command to detect structural issues:

codebase-memory-mcp diagnose --check-orphans --check-cycles

This checks for dangling edges and orphan nodes (code with no incoming CALLS edges) or cycles that violate the expected DAG structure of the call graph.

Re-index Single Files After Fixes

After patching a grammar bug, re-index only the affected file without rebuilding the entire graph:

codebase-memory-mcp index-file /path/to/file.c

This command uses the same extraction path as the daemon, ensuring your modifications to extract_*.c reflect immediately.

Common Pitfalls and Resolutions

Symptom	Likely Cause	Fix
Missing nodes for a language	Grammar not compiled into the binary.	Re-run make to embed the language, or add the missing grammar to vendored/ and re-compile.
Undefined edge types	extract_calls.c failed to emit a CALLS edge due to type-resolution failure.	Insert debug prints around extract_call_edge() and verify the TSNode resolves to a function identifier.
Daemon fails to start	Version conflict in ${CBM_CACHE_DIR} (multiple MCP processes).	Delete ${CBM_CACHE_DIR}/logs/daemon-conflicts.ndjson and restart.
Excessive parse time	Large file with complex includes or pathological grammar.	Enable incremental parsing: codebase-memory-mcp config set incremental true.

Summary

To effectively debug codebase memory MCP, remember these key techniques:

• Enable debug logging via config set log_level debug and monitor ${CBM_CACHE_DIR}/logs/cbm-daemon.log for atomic performance counters.
• Use one-shot indexing with --verbose to isolate file-specific issues without daemon overhead.
• Inspect internal/cbm/grammar_*.c for parsing errors and internal/cbm/extract_*.c for extraction logic bugs.
• Validate graph integrity using the diagnose command to find orphans and cycles.
• Re-index individual files with index-file after applying source code fixes.

Frequently Asked Questions

Where are the debug logs stored in Codebase Memory MCP?

The daemon writes debug logs to ${CBM_CACHE_DIR}/logs/cbm-daemon.log, where CBM_CACHE_DIR defaults to a system cache directory (typically ~/.cache/codebase-memory-mcp on Linux). These logs contain nanosecond-precision timing data from the _Atomic counters defined in internal/cbm/cbm.c.

How do I enable debug mode for the MCP daemon?

Run codebase-memory-mcp config set log_level debug before starting the daemon. This persists the setting and causes cbm-daemon to emit DEBUG level entries showing parse times, extraction times, and file-watch events. For immediate stdout output without the daemon, use codebase-memory-mcp index /path --verbose.

What should I do if specific languages are not being indexed?

First, verify the language grammar exists in internal/cbm/grammar_*.c (e.g., grammar_go.c for Go). If present, check internal/cbm/extract_defs.c to ensure the extraction logic handles that language's node types. Re-compile the binary after adding missing grammars to the vendored/ directory.

How can I fix slow parsing performance in large repositories?

Enable incremental parsing to reuse previous AST trees: codebase-memory-mcp config set incremental true. If specific files cause pathological parse times, check for excessive macro expansion or include depth in the corresponding internal/cbm/grammar_*.c implementation, or exclude the files via configuration.

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