Codebase-Memory-MCP Usage Examples: CLI Commands and Knowledge Graph Queries

codebase-memory-mcp provides a local, zero-dependency engine that indexes repositories into a persistent knowledge graph and exposes 15 MCP tools for structural search, call tracing, and semantic queries via command-line interface.

The DeusData/codebase-memory-mcp repository delivers a self-contained binary that constructs a semantic understanding of your codebase without requiring external APIs or Docker containers. By parsing source files with Tree-Sitter across 158 bundled grammars and enriching them with hybrid-LSP type resolution for 12 languages, the tool creates a compressed graph database stored in ~/.cache/codebase-memory-mcp/ that supports both precise structural queries and vector-based semantic search.

Installing Codebase-Memory-MCP

Install the binary using the official one-liner, which automatically registers the tool with detected coding agents such as Claude Code, Codex CLI, and VS Code.

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

This command downloads the platform-specific binary and configures MCP integration for supported agents. The installer script source resides in [scripts/setup.sh](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/setup.sh).

Indexing a Repository

Before querying code, you must parse the source into the knowledge graph. The index_repository command triggers the parsing pipeline implemented in [src/cli/cli.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.c).

# Index current directory into ~/.cache/codebase-memory-mcp/graph.db.zst

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

The engine performs incremental updates on subsequent runs, only processing changed files. During indexing, [internal/cbm/cbm.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/cbm.c) constructs the AST and graph structure, while [internal/cbm/hybrid_lsp.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/hybrid_lsp.c) resolves types for supported languages including Python, TypeScript, and PHP.

Listing Indexed Projects

Verify available knowledge graphs with the list_projects tool, which displays project names alongside node and edge counts.

codebase-memory-mcp list_projects

This command queries the SQLite backend to show all persisted graph snapshots in your local cache directory.

Searching the Knowledge Graph

Structural Pattern Matching

Use search_graph to locate specific AST nodes using regex patterns and labels.

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

This returns a JSON array of matching nodes including file paths and line numbers. The query executes against the in-memory graph built by the Tree-Sitter parser in [internal/cbm/cbm.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/cbm.c).

Cypher-Like Graph Queries

For complex traversals, use query_graph with OpenCypher syntax.

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

This executes read-only Cypher queries against the persisted graph, enabling custom dependency analysis without writing additional code.

Tracing Code Dependencies

The trace_path tool performs BFS traversal of CALLS edges to map dependency chains.

# Find callers and callees of ProcessOrder up to depth 2

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

This command leverages the graph structure created during indexing to perform impact analysis, showing exactly which functions interact with your target code.

Semantic Vector Search

Beyond structural queries, the engine supports natural language search using bundled embeddings.

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

This uses the local nomic-embed-code model to find semantically similar code segments without transmitting data to external services.

Visualizing the Graph

Launch the optional 3-D visualization interface to explore the knowledge graph interactively.

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

Then navigate to http://localhost:9749 to browse the graph. The UI build configuration resides 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 helps extend or debug the codebase-memory-mcp usage patterns:

• [README.md](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md) – Central documentation covering quick-start, CLI examples, and the multi-agent support matrix.
• [internal/cbm/cbm.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/cbm.c) – Core engine implementing AST construction, graph mutation, and LZ4/ZSTD compression for the SQLite backend.
• [internal/cbm/hybrid_lsp.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/hybrid_lsp.c) – Implements hybrid-LSP semantic analysis for 12 programming languages, enriching Tree-Sitter output with type information.
• [src/cli/cli.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.c) – CLI front-end mapping subcommands like search_graph and trace_path to the underlying engine.
• [docs/CONFIGURATION.md](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md) – Complete reference for runtime environment variables and per-project configuration options.

Summary

• codebase-memory-mcp operates entirely locally with no API keys, building a compressed knowledge graph in ~/.cache/codebase-memory-mcp/.
• Use index_repository to parse code with Tree-Sitter and hybrid-LSP enrichment.
• Query the graph using search_graph for pattern matching, trace_path for dependency traversal, or query_graph for custom Cypher queries.
• Perform natural language code search with semantic_query using bundled embeddings.
• The CLI interface in [src/cli/cli.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.c) provides the primary interaction point, while [internal/cbm/cbm.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/cbm.c) powers the graph engine.

Frequently Asked Questions

How does codebase-memory-mcp differ from other code search tools?

Unlike cloud-based solutions, codebase-memory-mcp runs entirely on your local machine using a zero-dependency binary. It persists knowledge graphs as ZSTD-compressed SQLite databases and requires no Docker containers or external API keys, ensuring your source code never leaves your environment.

Can I use codebase-memory-mcp with my existing IDE or coding agent?

Yes. The installation script auto-detects supported agents including Claude Code, Codex CLI, and VS Code, injecting the necessary MCP configuration automatically. The tool exposes 15 MCP tools via JSON-RPC, allowing any compatible agent to query the knowledge graph directly.

What programming languages are fully supported for semantic analysis?

The engine parses 158 languages using Tree-Sitter grammars, with deep semantic enrichment available for 12 languages including Python, TypeScript/JSX, JavaScript, PHP, Go, Rust, C, C++, Java, Ruby, and C#. Hybrid-LSP resolution in [internal/cbm/hybrid_lsp.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/hybrid_lsp.c) provides type information for these specific languages.

Where is the knowledge graph stored and how much space does it require?

Graphs are stored as ZSTD-compressed snapshots in ~/.cache/codebase-memory-mcp/. The LZ4-compressed SQLite database format typically requires significantly less space than the original source code while maintaining millisecond query performance for repositories up to millions of lines of code.

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