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

> Explore codebase-memory-mcp usage examples with CLI commands and knowledge graph queries. This zero-dependency engine indexes repositories for structural search and semantic analysis.

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

---

**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.

```bash
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)](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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#indexing-pipeline) command triggers the parsing pipeline implemented in [[`src/cli/cli.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.c).

```bash

# 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)](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)](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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#list_projects) tool, which displays project names alongside node and edge counts.

```bash
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#cli-usage) to locate specific AST nodes using regex patterns and labels.

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

### Cypher-Like Graph Queries

For complex traversals, use [`query_graph`](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#query_graph) with OpenCypher syntax.

```bash
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#trace_path) tool performs BFS traversal of `CALLS` edges to map dependency chains.

```bash

# 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.

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

```bash
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)](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)](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)](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)](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)](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)](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)](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)](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)](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.