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

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 and 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 parses the subcommand arguments and forwards them to the GraphEngine class defined in 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:

mcp searchgraph name:process_data

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

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

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

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

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:

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

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:

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 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, while graph traversal logic resides in 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 and 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 builds the query string from user input, while ResultTable.tsx renders the stream of matches returned by the GraphEngine backend in a sortable, interactive table.

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