# How to Query the Codebase-Memory-MCP Graph: MCP Tools and Cypher Syntax Guide

> Query the Codebase-Memory-MCP graph with MCP tools and Cypher syntax. Explore your codebase structure and semantics using built-in search query and trace path commands.

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

---

**Query the Codebase-Memory-MCP graph using built-in MCP tools like `search_graph`, `query_graph`, and `trace_path` via JSON-RPC or the bundled CLI, which execute read-only operations against an SQLite-backed knowledge graph storing your codebase's structure and semantics.**

Codebase-Memory-MCP constructs a full-text, structural, and semantic representation of your source tree in an SQLite-backed knowledge graph. According to the DeusData/codebase-memory-mcp source code, you can query this graph through the MCP JSON-RPC interface or the bundled CLI using specialized tools that support both structured filtering and OpenCypher-compatible traversals.

## Query Interface Options

The graph exposes two primary interfaces for querying: the **MCP JSON-RPC protocol** for automated agent integration, and a **command-line interface (CLI)** for handcrafted exploration. Both interfaces invoke the same underlying tools implemented in `src/mcp/` within the C source tree.

The CLI wrapper forwards arguments as JSON payloads to the local server, making it easy to experiment locally before integrating with automated workflows. All queries are purely read-only; the server never modifies your source files.

## Core Query Tools

The system provides seven primary tools for graph interaction, each exposed as both an MCP method and a CLI sub-command.

### search_graph

The `search_graph` tool performs structured filtering on node labels, name patterns, file scopes, and degree ranges. Use this to locate specific symbols before running deeper analysis.

```bash
codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*", "label": "Function"}'

```

### query_graph

The `query_graph` tool executes OpenCypher-compatible read-only queries against the graph. This supports arbitrary graph traversals, aggregations, and pattern matches using the subset documented in the README section *Supported Cypher*.

```bash
codebase-memory-mcp cli query_graph '{
    "query": "MATCH (f:Function)<-[:CALLS]-() RETURN f.name, count(*) AS callers ORDER BY callers DESC LIMIT 5"
}'

```

### trace_path

The `trace_path` tool performs breadth-first traversal of call-graph edges in inbound, outbound, or bidirectional directions. This discovers callers or callees of a symbol up to a specified depth.

```bash
codebase-memory-mcp cli trace_path '{"function_name":"processOrder","direction":"inbound","max_depth":3}'

```

### detect_changes

The `detect_changes` tool maps a Git diff onto affected graph symbols and assigns risk scores, enabling quick assessment of a change's blast radius.

```bash
codebase-memory-mcp cli detect_changes '{"repo_path":"/path/to/repo"}'

```

### get_architecture

The `get_architecture` tool returns a high-level overview including languages, packages, routes, and hotspots, serving as an entry point for exploratory analysis.

### search_code

The `search_code` tool provides graph-augmented grep functionality over indexed files, combining text search with graph awareness (e.g., limiting searches to specific folders).

### get_code_snippet

The `get_code_snippet` tool retrieves source code for a node using its qualified name (`project.path.to.node`), which you obtain from `search_graph` results.

```bash
FUNC=$(codebase-memory-mcp cli search_graph '{"name_pattern":"^handleLogin$","label":"Function"}' | jq -r .results[0].qualified_name)
codebase-memory-mcp cli get_code_snippet "{\"qualified_name\":\"$FUNC\"}"

```

## Practical Query Patterns

Follow this three-step workflow for effective graph exploration:

1. **Identify the target node** using `search_graph` or `list_projects`.
2. **Resolve the qualified name** from the search results (format: `project.path.to.node`).
3. **Execute analysis** using `trace_path` for call chains, `query_graph` for custom Cypher, or `get_code_snippet` to view source.

**Finding exported HTTP routes:**

```bash
codebase-memory-mcp cli search_graph '{"label":"Route","property_filter":{"http_method":"GET"}}'

```

**Python integration example:**

```python
import json
import subprocess
import shlex

def mcp_call(method, params):
    cmd = f"codebase-memory-mcp cli {method} '{json.dumps(params)}'"
    out = subprocess.check_output(shlex.split(cmd))
    return json.loads(out)

# Find a class

results = mcp_call("search_graph", {"label":"Class","name_pattern":"^UserService$"})
qualified = results["results"][0]["qualified_name"]

# Retrieve source

snippet = mcp_call("get_code_snippet", {"qualified_name": qualified})
print(snippet["code"])

```

## Graph Schema and Persistence

The graph schema is discoverable via the `get_graph_schema` tool, which lists all node labels and edge types. Invoke this once to understand available properties before constructing complex queries.

The graph persists in `~/.cache/codebase-memory-mcp/` as an SQLite database managed by the `src/store/` implementation. The system maintains an in-memory representation that flushes periodically to disk, ensuring fast query execution while maintaining durability.

The OpenCypher parser and executor reside in `src/cypher/`, processing read-only queries against the SQLite backend without exposing modification capabilities.

## Summary

- **Query the Codebase-Memory-MCP graph** using seven built-in tools: `search_graph`, `query_graph`, `trace_path`, `detect_changes`, `get_architecture`, `search_code`, and `get_code_snippet`.
- **Choose your interface**: Use JSON-RPC for agent automation or the CLI for manual exploration, both invoking the same C implementation in `src/mcp/`.
- **Leverage OpenCypher**: Run arbitrary graph traversals via `query_graph` using the supported Cypher subset.
- **Trace dependencies**: Follow call chains bidirectionally with `trace_path` to understand code relationships.
- **Assess impact**: Map Git diffs to graph symbols using `detect_changes` to evaluate change risk.
- **Retrieve context**: Combine `search_graph` with `get_code_snippet` to locate symbols and inspect their implementation.

## Frequently Asked Questions

### What query languages does Codebase-Memory-MCP support?

Codebase-Memory-MCP supports a read-only subset of **OpenCypher** through the `query_graph` tool, as implemented in `src/cypher/`. For structured searches without custom graph traversals, use the `search_graph` tool with JSON parameter filters.

### Where is the graph data stored?

The knowledge graph persists in `~/.cache/codebase-memory-mcp/` as an SQLite database. The `src/store/` layer manages this persistence, maintaining an in-memory cache that flushes to disk periodically while ensuring all queries remain read-only operations against your source code.

### Can I modify the graph through queries?

No. All query tools are strictly **read-only**. The `query_graph` tool explicitly supports only OpenCypher read operations, and no MCP tools expose write capabilities to the graph structure. The system indexes your codebase but never modifies source files.

### How do I find the qualified name for a code snippet query?

First run `search_graph` with a name pattern and label filter, then extract the `qualified_name` field from the results. The qualified name follows the format `project.path.to.node` and serves as the unique identifier for `get_code_snippet` and `trace_path` operations.