# How to Debug Codebase Memory MCP: A Complete Troubleshooting Guide

> Debug codebase memory MCP issues effectively. Enable debug logging and monitor daemon logs for real-time troubleshooting of parsing, extraction, and coordination problems. Get your code running smoothly.

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

---

**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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/grammar_c.c) for C, [`internal/cbm/grammar_python.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/extract_calls.c) (emits `CALLS` edges) and [`internal/cbm/extract_defs.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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:

```bash
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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:

```bash
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:

```c
/* 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:

```bash
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:

```bash
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/grammar_go.c) for Go). If present, check [`internal/cbm/extract_defs.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.