# Codebase Memory MCP Example Usage: CLI Commands and Core Architecture

> Explore codebase memory MCP example usage with CLI commands and core architecture. Index, search, and trace code relationships with this zero-dependency engine.

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

---

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

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

```bash

# 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)](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:

```bash
codebase-memory-mcp list_projects

```

This outputs each project name with node and edge counts, as defined in the [MCP Tools documentation](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#list_projects).

## Structural Search Examples

### Pattern-Based Search

Find all functions matching a regex pattern:

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

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

```bash

# 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)](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/cbm.c) and [README.md - trace_path](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#trace_path)

## Semantic Search

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

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

```

*Source:* [README.md - Semantic search](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#semantic-search)

## Graph Visualization UI

Launch the optional 3-D visualization interface:

```bash
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)](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)](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)](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)](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)](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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/cbm.c), CLI commands in [`cli.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/cli.c), and type resolution in [`hybrid_lsp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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)](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)](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.