How to Query the Codebase Memory in DeusData codebase-memory-mcp: A Complete Guide

To query the codebase memory in codebase-memory-mcp, invoke the query_graph tool via the MCP server with a Cypher query string, project name, and optional parameters for formatting and result limits.

The codebase-memory-mcp repository by DeusData provides a Model Context Protocol (MCP) server that indexes codebases into a graph database, enabling complex queries via the query_graph tool. This guide explains how to query the codebase memory using Cypher syntax through the CLI, HTTP API, or any MCP-compatible client.

Understanding the query_graph Tool

The query_graph tool serves as the primary interface for executing Cypher-style graph queries against indexed projects. When the MCP server receives a request for this tool, it dispatches to the handle_query_graph() function defined in src/mcp/mcp.c (lines 13-32).

This function validates the incoming JSON payload, extracts parameters, and delegates execution to cbm_cypher_execute(). The server then formats results as either a human-readable TOON table by default, or a legacy JSON object when explicitly requested via the format parameter.

Required Parameters and Optional Flags

Every query_graph request must include specific fields in the JSON payload:

• project: The name of the indexed project (required unless querying the missed graph).
• query: The Cypher query string to execute (required).
• max_rows (optional): Integer limiting the number of rows returned.
• graph (optional): Set to "missed" to query the shadow graph containing files not fully indexed.
• format (optional): Set to "json" for JSON output; omit or use any other value for TOON tables.

How to Execute Cypher Queries

CLI Invocation with Default TOON Output

Invoke query_graph from the terminal to receive formatted tables:

codebase-memory-mcp query_graph \
  '{"project":"myapp","query":"MATCH (a)-[r:HTTP_CALLS]->(b) RETURN a.name,b.name,r.url_path LIMIT 20"}'

The CLI returns a human-readable table with columns corresponding to your RETURN clause.

CLI with JSON Output Format

Add "format":"json" to parse results programmatically:

codebase-memory-mcp query_graph \
  '{"project":"myapp","query":"MATCH (f:Function) WHERE f.name =~ \".*Handler.*\" RETURN f.name,f.file_path","format":"json"}'

HTTP API Requests

Send POST requests to the HTTP server (default port 9749) as implemented in src/ui/http_server.c:

POST /codebase-memory-mcp/query_graph HTTP/1.1
Host: localhost:9749
Content-Type: application/json

{
  "project": "myapp",
  "query": "MATCH (a)-[r:CALLS]->(b) WHERE a.name = 'main' RETURN b.name"
}

Querying the Missed Graph

Target the missed graph to find files excluded from full indexing:

codebase-memory-mcp query_graph \
  '{"project":"myapp","query":"MATCH (f:File) RETURN f.path","graph":"missed"}'

The code automatically rewrites the project name to the shadow project <project>::missed (see src/mcp/mcp.c, lines 20-26).

Practical Cypher Query Examples

The built-in skill documentation in src/cli/cli.c (lines 83-89) provides ready-to-use query templates:

MATCH (a)-[r:HTTP_CALLS]->(b) RETURN a.name, b.name, r.url_path LIMIT 20

MATCH (f:Function) WHERE f.name =~ '.*Handler.*' RETURN f.name, f.file_path

MATCH (a)-[r:CALLS]->(b) WHERE a.name = 'main' RETURN b.name

These examples demonstrate filtering by relationship types (CALLS, HTTP_CALLS), regex matching on function names, and traversing call hierarchies.

Summary

• query_graph in src/mcp/mcp.c serves as the central dispatcher for codebase memory queries.
• Provide a project name and Cypher query string in the JSON payload.
• Use "format":"json" for machine-readable output; omit for human-readable TOON tables.
• Query the "missed" graph to inspect files not fully indexed by the pipeline.
• Reference src/cli/cli.c for validated Cypher patterns and available edge types.

Frequently Asked Questions

What is the default output format for query_graph?

By default, query_graph returns a TOON-style table format suitable for terminal display. According to src/mcp/mcp.c (lines 71-73), the server only switches to JSON when the format parameter is explicitly set to "json".

How do I discover available node labels and relationship types?

Run the get_graph_schema tool before writing queries. This returns the complete graph schema including node labels like Function and File, plus edge types such as CALLS and HTTP_CALLS defined in the pipeline internals.

Can I query across multiple projects simultaneously?

No, each query_graph call targets a single project specified in the project field. To query multiple codebases, issue separate requests for each project name returned by the list_projects command.

What happens if my Cypher query returns empty results?

When queries return zero rows, src/mcp/mcp.c (lines 92-96) automatically appends a helpful hint suggesting you run get_graph_schema() to verify available labels and relationships, ensuring you use valid graph topology in your queries.

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