Codebase Memory MCP Example Usage: CLI Commands and Core Architecture

Codebase Memory MCP is a local, zero-dependency code-intelligence engine that exposes 15 MCP tools via CLI commands for indexing, searching, and tracing code relationships within a persistent knowledge graph.

The DeusData/codebase-memory-mcp repository implements a complete local code-intelligence system that auto-configures with agents like Claude Code, Codex CLI, and VS Code. This guide demonstrates practical codebase memory MCP example usage patterns, from initial repository indexing to advanced Cypher graph queries, using the command-line interface and core engine components.

Quick Start: Installation

The one-liner install script downloads the binary and auto-registers the tool with detected agents:

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

Source: [scripts/setup.sh](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/setup.sh)

Indexing Your First Repository

Before querying, you must parse the source into a knowledge graph. The engine uses Tree-Sitter (158 bundled grammars) to construct an AST, applies hybrid-LSP type resolution, and persists the result as a ZSTD-compressed SQLite database under ~/.cache/codebase-memory-mcp/:

# Index the current working directory

codebase-memory-mcp index_repository --repo-path $(pwd)

The indexing pipeline, implemented in [src/cli/cli.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.c), performs incremental updates on subsequent runs, only processing changed files.

Listing Available Projects

Verify indexed projects and their statistics:

codebase-memory-mcp list_projects

This outputs each project name with node and edge counts, as defined in the MCP Tools documentation.

Structural Search Examples

Pattern-Based Search

Find all functions matching a regex pattern:

codebase-memory-mcp cli search_graph \
  --project my-project \
  --name-pattern '.*Handler.*' \
  --label Function

Returns JSON containing file paths, line numbers, and symbol names.

Ad-Hoc Graph Queries

Execute read-only OpenCypher queries directly against the stored graph:

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

Source: README.md - query_graph

Tracing Code Paths

The trace_path tool performs BFS traversal of CALLS edges for impact analysis, implemented in the graph engine:

# Trace both callers and callees of ProcessOrder with depth 2

codebase-memory-mcp cli trace_path \
  --project my-project \
  --function-name ProcessOrder \
  --direction both \
  --depth 2

Source: [internal/cbm/cbm.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/cbm.c) and README.md - trace_path

Semantic Search

Using bundled nomic-embed-code embeddings (no external API keys):

codebase-memory-mcp semantic_query \
  --project my-project \
  --query "upload file to S3"

Source: README.md - Semantic search

Graph Visualization UI

Launch the optional 3-D visualization interface:

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

Then navigate to http://localhost:9749. The UI build configuration is defined in [graph-ui/vite.config.ts](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/vite.config.ts).

Core Architecture and Key Files

Understanding these source files clarifies the data flow:

File	Purpose	Implementation Details
[internal/cbm/cbm.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/cbm.c)	Core graph engine	AST construction, node/edge mutations, LZ4 compression, SQLite persistence
[internal/cbm/hybrid_lsp.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/hybrid_lsp.c)	Type resolution	Hybrid LSP integration for Python, TypeScript/JSX, PHP, and 9 other semantic languages
[src/cli/cli.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.c)	CLI frontend	Command routing, JSON-RPC interface, incremental indexing logic
[docs/CONFIGURATION.md](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md)	Runtime configuration	Environment variables and per-project settings

The hybrid LSP layer provides deep semantic analysis without requiring running language servers, making the system truly zero-dependency.

Summary

• Zero-dependency operation: Runs entirely offline using bundled Tree-Sitter grammars and local embeddings—no Docker, no API keys.
• Two-phase workflow: First index_repository to build the compressed graph, then query using search_graph, trace_path, or query_graph.
• Hybrid semantic support: Combines structural regex search with vector-based semantic search via nomic-embed-code.
• Agent integration: The installer auto-detects Claude Code, Codex CLI, VS Code, and other agents, injecting the correct MCP configuration.
• Core implementation: Graph logic resides in cbm.c, CLI commands in cli.c, and type resolution in hybrid_lsp.c.

Frequently Asked Questions

How do I install Codebase Memory MCP without an existing AI agent?

You can run the standalone CLI independently of any agent. Simply execute the install script to download the binary, then use codebase-memory-mcp cli <command> to index and query repositories directly from your terminal without connecting to Claude Code or other agents.

What is the difference between search_graph and semantic_query?

search_graph performs exact pattern matching and label filtering on the AST nodes stored in the SQLite database. semantic_query converts natural language into vector embeddings using the bundled nomic-embed-code model and performs similarity search across the codebase, finding conceptually related code regardless of naming conventions.

How does the tool handle incremental updates to large repositories?

When you re-run index_repository on an already-indexed project, the system detects changed files based on content hashes and updates only the modified nodes and edges. This incremental logic is implemented in [src/cli/cli.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.c), avoiding full rebuilds of the knowledge graph.

Where is the graph data physically stored?

All indexed project data persists under ~/.cache/codebase-memory-mcp/ as ZSTD-compressed SQLite snapshots. The [internal/cbm/cbm.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/cbm.c) module manages the compression using LZ4 for active working sets and ZSTD for long-term persistence, minimizing disk usage while maintaining fast query performance.

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