# How the MCP SearchGraph Tool Works: Query Syntax and Graph Traversal

> Discover how the MCP SearchGraph tool uses O(log N) lookups and advanced query syntax to efficiently search your codebase graph supporting exact fuzzy glob regex and relationship traversal.

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

---

**The MCP SearchGraph tool performs O(log N) lookups against a compressed directed graph of your codebase, supporting exact identifiers, Levenshtein fuzzy matching, glob path filtering, regex content search, and relationship traversal via a unified CLI interface.**

The `codebase-memory-mcp` repository from DeusData ships with a built-in **SearchGraph** engine that indexes your repository into a structured representation of entities and their relationships. When the MCP daemon initializes, it scans the codebase and persists a compact binary graph using zstd compression, enabling high-performance queries without loading the entire source tree into memory.

## Architecture of the SearchGraph Engine

### Graph Structure and Storage Model

The engine constructs a **directed graph** where nodes represent logical entities—files, classes, functions, variables, imports, and test cases—and edges encode semantic relationships such as `contains`, `inherits`, `calls`, `imports`, and `references`. 

This graph is persisted using the native **CBM (Codebase Memory) store**, implemented in [`internal/cbm/zstd_store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.c) and [`zstd_store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/zstd_store.h). The compact binary format allows the engine to perform lookups in **O(log N)** time by walking compressed adjacency lists rather than parsing raw source files.

### Query Execution Pipeline

When you invoke `mcp searchgraph`, the CLI entry point in [`pkg/pypi/src/codebase_memory_mcp/_cli.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/pypi/src/codebase_memory_mcp/_cli.py) parses the subcommand arguments and forwards them to the **GraphEngine** class defined in [`graph-ui/src/lib/graphEngine.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/lib/graphEngine.ts). The engine walks the in-memory graph structure, applies filters against node attributes and edge traversals, and streams matching node IDs back to the CLI, which formats them as human-readable tables or JSON payloads when using the `--format json` flag.

## MCP SearchGraph Query Capabilities

### Exact and Fuzzy Name Matching

Use `name:<identifier>` to perform case-sensitive exact matches against canonical node names:

```bash
mcp searchgraph name:process_data

```

For approximate matches when spelling is uncertain, use `fuzzy:<pattern>` to execute a **Levenshtein-distance** calculation:

```bash
mcp searchgraph fuzzy:auth

```

This returns identifiers like `authenticate`, `auth_token`, or `AuthProvider` even with minor typos.

### Path and Content Filtering

Scope queries to specific directory trees using glob patterns with `path:<glob>`:

```bash
mcp searchgraph path:src/**/*.py

```

Search the literal source text attached to nodes using `regex:<expr>`:

```bash
mcp searchgraph regex:"TODO:"

```

### Type Constraints

Restrict results to specific entity categories using `type:<node-type>`, supporting values such as `file`, `class`, `function`, `variable`, or `test`:

```bash
mcp searchgraph type:test path:tests/**/*.py

```

### Relationship Traversal

Traverse the graph via edges using the `from:<id> -> <edge-type>` syntax. This follows directional relationships originating from a known node (identified by name or ID):

```bash
mcp searchgraph name:render_page -> calls

```

This example traverses incoming `calls` edges to identify all functions that invoke `render_page`.

### Boolean Composition

The engine **AND-combines** multiple constraints when separated by spaces, returning only nodes satisfying every clause:

```bash
mcp searchgraph type:function name:get_ path:api/ regex:"async def"

```

## Practical Query Examples

| Goal | Command |
|------|---------|
| Find all callers of a specific function | ```bash<br>mcp searchgraph name:validate_token -> calls<br>``` |
| Locate TODO comments in Python files | ```bash<br>mcp searchgraph regex:"TODO:" path:**/*.py<br>``` |
| Export function definitions as JSON for downstream tooling | ```bash<br>mcp searchgraph type:function name:handler --format json > handlers.json<br>``` |
| Find inheritance relationships | ```bash<br>mcp searchgraph name:BaseController -> inherits<br>``` |

## Summary

- The **SearchGraph** engine maintains a directed graph in [`internal/cbm/zstd_store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.c) with **O(log N)** lookup performance via compressed binary storage.
- Seven query primitives are supported: **exact name**, **fuzzy matching**, **path globbing**, **regex content search**, **type filtering**, **relationship traversal**, and **boolean AND-composition**.
- The command-line interface is implemented in [`pkg/pypi/src/codebase_memory_mcp/_cli.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/pypi/src/codebase_memory_mcp/_cli.py), while graph traversal logic resides in [`graph-ui/src/lib/graphEngine.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/lib/graphEngine.ts).
- Results can be streamed as human-readable tables or serialized JSON using the `--format json` flag.

## Frequently Asked Questions

### What storage backend powers MCP SearchGraph lookups?

The graph is stored using the **CBM (Codebase Memory) store**, implemented in [`internal/cbm/zstd_store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.c) and [`zstd_store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/zstd_store.h). This backend uses zstd compression to serialize the graph into a compact binary format, enabling O(log N) lookups without requiring the entire codebase to remain in memory.

### How does relationship traversal syntax work?

Use the arrow operator (`->`) to traverse edges from a starting node. The syntax `from:<id> -> <edge-type>` (often written as `name:<name> -> <type>`) follows edges of the specified type—such as `calls`, `imports`, or `inherits`—to find connected nodes. You can start from any node identified by its canonical name or internal ID.

### Can I combine multiple query filters?

Yes. The SearchGraph engine **AND-combines** all constraints when you separate them with spaces in a single command. For example, `mcp searchgraph type:function path:src/ regex:"def "` returns only function nodes located under `src/` that contain the pattern `def ` in their source text.

### Where are the UI components for SearchGraph implemented?

The web interface components are located in the `graph-ui/src/components/` directory. **[`SearchBar.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/SearchBar.tsx)** builds the query string from user input, while **[`ResultTable.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/ResultTable.tsx)** renders the stream of matches returned by the GraphEngine backend in a sortable, interactive table.