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

> Easily query codebase memory in DeusData codebase-memory-mcp using the query_graph tool. Get your answers faster with this complete guide.

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

---

**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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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:

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

```bash
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/http_server.c)**:

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

```bash
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c)**, lines 20-26).

## Practical Cypher Query Examples

The built-in skill documentation in **[`src/cli/cli.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.c)** (lines 83-89) provides ready-to-use query templates:

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

```

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

```

```cypher
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.