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

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.

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.

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.

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.

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.

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:

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

Python integration example:

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.

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