# Best Practices for DeusData codebase-memory-mcp: Complete Setup and Optimization Guide

> Master DeusData codebase-memory-mcp with our setup and optimization guide. Learn best practices for efficient indexing and querying to boost performance and reduce token usage.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: best-practices
- Published: 2026-07-19

---

**Use the official one-line installer, enable auto-indexing with sensible file limits, and prefer structural graph queries over text search to maximize performance and minimize token usage when working with DeusData codebase-memory-mcp.**

**DeusData codebase-memory-mcp** is a high-performance, zero-dependency code-intelligence engine that transforms your repository into a persistent knowledge graph. This tool integrates with LLM-powered coding agents via MCP (Model-Controlled-Program) hooks to provide structural code understanding without requiring API keys or remote services.

## Core Architecture Concepts

Understanding how codebase-memory-mcp processes your code helps you optimize its configuration. The engine operates through a **RAM-first pipeline** that combines fast syntactic parsing with semantic type resolution.

### Tree-Sitter Parsing and Hybrid LSP

The indexing process runs in two distinct stages. First, **tree-sitter parsing** extracts abstract syntax trees (ASTs) for 158 vendored languages. Second, the **Hybrid LSP**—a lightweight C implementation—resolves types and refines call-site edges with semantic information (e.g., converting `user.profile.display_name()` to `Profile.display_name`).

According to the source in `src/pipeline/`, this dual-stage approach feeds into an in-memory SQLite database with LZ4 compression, ultimately persisting to `~/.cache/codebase-memory-mcp/`【/cache/repos/github.com/DeusData/codebase-memory-mcp/main/README.md#L29-L32】.

### Static Binary Design

Unlike traditional language servers, codebase-memory-mcp ships as a **single static binary**包含 all vendored tree-sitter grammars and the Hybrid LSP engine. The entry point in [`src/main.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c) parses CLI arguments, starts the MCP JSON-RPC server, and optionally launches the UI thread on port 9749【/cache/repos/github.com/DeusData/codebase-memory-mcp/main/README.md#L33-L36】.

## Installation and Agent Integration

### One-Line Installation

Begin with the verified installer to ensure binary integrity against published SHA-256 checksums:

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

```

This command downloads the platform-specific archive (macOS, Linux, or Windows) and verifies cryptographic signatures before installation【/cache/repos/github.com/DeusData/codebase-memory-mcp/main/README.md#L44-L52】.

### Auto-Configure All Agents

Run the auto-configuration once per machine to populate MCP configuration files for supported agents including Claude Code, Codex CLI, Gemini CLI, Zed, and OpenCode:

```bash
codebase-memory-mcp install

```

This command creates [`.mcp.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.mcp.json) files, skill definitions, and pre-tool hooks in your agent configuration directories, enabling seamless graph queries from your IDE or terminal【/cache/repos/github.com/DeusData/codebase-memory-mcp/main/README.md#L31-L38】.

## Configuration Best Practices

### Enable Smart Auto-Indexing

Configure automatic indexing to eliminate manual steps while preventing memory exhaustion on large repositories:

```bash
codebase-memory-mcp config set auto_index true
codebase-memory-mcp config set auto_index_limit 50000

```

The `auto_index_limit` parameter (default 50,000 files) prevents the incremental watcher from attempting to process repositories exceeding your available RAM【/cache/repos/github.com/DeusData/codebase-memory-mcp/main/README.md#L110-L117】.

### Graph Persistence Strategy

Decide whether to commit the compressed graph artifact based on your team's workflow:

- **Commit `.codebase-memory/graph.db.zst`** when you want teammates to share a pre-built graph snapshot, eliminating re-indexing time for large repositories
- **Add to `.gitignore`** for rapidly changing codebases to avoid merge conflicts

The compression logic resides in [`internal/cbm/zstd_store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.c), which handles zstandard compression of the SQLite database【/cache/repos/github.com/DeusData/codebase-memory-mcp/main/README.md#L94-L101】.

### Diagnostic Monitoring

Enable detailed logging when troubleshooting performance issues:

```bash
export CBM_DIAGNOSTICS=1

```

This environment variable causes the engine to dump JSON diagnostics to `/tmp` for offline analysis of parsing bottlenecks or LSP resolution failures【/cache/repos/github.com/DeusData/codebase-memory-mcp/main/README.md#L38-L45】.

## Query Optimization Strategies

### Prefer Structural Over Text Search

**Always use graph queries** instead of full-text greps. Structural queries like `search_graph`, `trace_path`, and `query_graph` execute in milliseconds and reduce LLM token consumption by over 99% compared to sending raw file contents to your agent.

To find functions matching a pattern:

```bash
codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*", "label": "Function"}'

```

This returns qualified names and metadata without loading file contents into the context window【/cache/repos/github.com/DeusData/codebase-memory-mcp/main/README.md#L65-L68】.

### Leverage Hybrid LSP Resolution

For languages supported by the Hybrid LSP (Python, TypeScript/JavaScript, PHP, C#, Go, C/C++, Java, Kotlin, Rust), use call-graph tracing to understand dependencies:

```bash
codebase-memory-mcp cli trace_path '{"function_name": "processOrder", "direction": "both"}'

```

This command shows both callers and callees with near-IDE-level accuracy, as the Hybrid LSP resolves method calls through the type system implemented in the pipeline【/cache/repos/github.com/DeusData/codebase-memory-mcp/main/README.md#L86-L90】.

### Advanced Cypher Analytics

For complex analysis like community detection or dead-code identification, use the built-in openCypher subset against the graph model (nodes: `Project`, `File`, `Function`; edges: `CALLS`, `IMPORTS`, `HTTP_CALLS`):

```bash
codebase-memory-mcp cli query_graph '{"query":"MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = \"main\" RETURN g.name"}'

```

The query executor provides clear error messages for unsupported Cypher features while maintaining read-only safety guarantees【/cache/repos/github.com/DeusData/codebase-memory-mcp/main/README.md#L14-L22】.

## Optional Graph Visualization

Launch the 3-D visualization server to explore your codebase structure interactively:

```bash
codebase-memory-mcp --ui=true --port=9749

```

The embedded HTTP server defined in [`src/ui/httpd.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/httpd.c) serves the visualization interface at `localhost:9749`, displaying node relationships and clustering patterns without requiring external visualization tools【/cache/repos/github.com/DeusData/codebase-memory-mcp/main/README.md#L49-L53】.

## Summary

- **Install via verified one-liner** to ensure SLSA-Level-3 compliant binaries with SHA-256 verification
- **Run `codebase-memory-mcp install` once** to auto-configure all supported MCP agents (Claude, Codex, Gemini, Zed, etc.)
- **Enable auto-indexing with limits** (50,000 files recommended) to balance convenience against memory usage
- **Commit graph artifacts** only for stable repositories to share snapshots with teammates
- **Use structural queries** (`search_graph`, `trace_path`, `query_graph`) instead of text search to minimize token usage
- **Enable diagnostics** (`CBM_DIAGNOSTICS=1`) when debugging performance in `src/pipeline/` or `src/mcp/` components
- **Update regularly** via `codebase-memory-mcp update` to receive new language support and security patches for the Hybrid LSP

## Frequently Asked Questions

### How does codebase-memory-mcp handle large repositories without running out of memory?

The engine uses a **RAM-first pipeline** with configurable limits. Set `auto_index_limit` to cap the number of files processed (recommended: 50000), and the system compresses data using LZ4 before writing to the SQLite backing store in `~/.cache/codebase-memory-mcp/`. For repositories exceeding this limit, manually index specific subdirectories or increase the limit based on your available system RAM【/cache/repos/github.com/DeusData/codebase-memory-mcp/main/README.md#L110-L115】.

### Which programming languages support semantic type resolution?

The **Hybrid LSP** provides semantic analysis for Python, TypeScript/JavaScript, PHP, C#, Go, C, C++, Java, Kotlin, and Rust. For these languages, the engine resolves call sites to specific method definitions (e.g., linking `user.profile.display_name()` to the actual `Profile.display_name` implementation). Other languages receive syntactic AST edges from the tree-sitter parsers but lack type-resolution accuracy【/cache/repos/github.com/DeusData/codebase-memory-mcp/main/README.md#L88-L100】.

### Can I use codebase-memory-mcp without an internet connection?

Yes. Once installed, codebase-memory-mcp operates entirely locally with **zero API keys** or external dependencies. The static binary includes all 158 tree-sitter grammars and the Hybrid LSP engine. Graph queries, indexing, and the 3-D UI ([`src/ui/httpd.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/httpd.c)) run offline using only local CPU and memory resources【/cache/repos/github.com/DeusData/codebase-memory-mcp/main/README.md#L33-L36】.

### How do I integrate this with my existing editor or agent?

Run `codebase-memory-mcp install` to automatically detect and configure Claude Code, Codex CLI, Gemini CLI, Zed, OpenCode, and other MCP-compatible agents. This populates the necessary [`.mcp.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.mcp.json) configuration files and installs skill definitions in each agent's configuration directory. If your agent isn't auto-detected, manually configure it to connect to the MCP server started by [`src/main.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c) on the default JSON-RPC interface【/cache/repos/github.com/DeusData/codebase-memory-mcp/main/README.md#L31-L38】.