# What Cypher Query Subset Does Codebase-Memory-MCP Support?

> Discover the Cypher query subset supported by Codebase-Memory-MCP. Learn which read-only operations like MATCH, WHERE, and RETURN are available, and which write operations are excluded.

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

---

**Codebase-Memory-MCP supports a read-only subset of the OpenCypher language that includes MATCH, WHERE, RETURN, aggregations, functions, and UNION, but excludes all write operations like CREATE, DELETE, MERGE, and SET.**

Codebase-Memory-MCP ships with a built-in Cypher query engine that translates a specific Cypher query subset into SQL for its internal SQLite graph store. This implementation focuses exclusively on read-only graph traversals and analytical operations, making it ideal for querying codebases without risk of mutation.

## Core Supported Clauses

The parser recognizes standard read clauses defined in the keyword table in [`src/cypher/cypher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.c) (lines 36-45). These include:

- **MATCH** – Pattern matching for nodes and relationships
- **WHERE** – Filtering conditions
- **RETURN** – Output projection
- **WITH** – Subquery result passing
- **ORDER BY** – Result sorting
- **SKIP** and **LIMIT** – Pagination control
- **DISTINCT** – Duplicate elimination

## Pattern Matching and Traversal

The engine supports comprehensive graph traversal patterns. Node syntax follows `(var:Label {props})`, parsed by the `parse_node` function (lines 44-55). Relationship patterns include directional arrows (`->`, `<-`, `-[]-`) and variable-length hops.

Variable-length traversals use the syntax `-[:TYPE*min..max]->` with a configurable maximum depth. The `CYP_MAX_DEPTH` constant defaults to 10 hops. Implementation details reside in `parse_rel` and `parse_hop_range` (lines 96-110).

Label alternation (`:A|B|C`) is supported and stored as pipe-separated strings, handled in lines 58-81.

## Filtering and Predicates

The `WHERE` clause supports complex boolean logic through `parse_condition_expr` (lines 108-139). Available operators include:

- **Boolean operators**: `AND`, `OR`, `XOR`, `NOT`
- **Comparison operators**: `=`, `<>`, `=~`, `>`, `<`, `>=`, `<=`
- **String operators**: `CONTAINS`, `STARTS WITH`, `ENDS WITH`
- **List operator**: `IN`
- **Null checks**: `IS NULL`, `IS NOT NULL`
- **Label tests**: `n:Label`
- **Existence checks**: `EXISTS { (v)-[:TYPE]->() }`

Comparison operators are processed in `parse_comparison_op` (lines 90-119).

## Aggregations and Functions

Aggregate functions are detected via `is_aggregate_tok` and parsed in `parse_aggregate_item` (lines 191-199, 271-285). Supported aggregates include:

- **COUNT**, **SUM**, **AVG**, **MIN**, **MAX**
- **COLLECT** (with optional `DISTINCT`)

Scalar and introspection functions available through `scalar_func_canonical` (lines 133-140) and `parse_named_func_item` (lines 181-190) include:

- `labels()`, `type()`, `id()`, `keys()`, `properties()`
- `toInteger()`, `toFloat()`, `toBoolean()`
- `size()`, `length()`, `trim()`, `ltrim()`, `rtrim()`, `reverse()`
- `toLower()`, `toUpper()`, `toString()`

Multi-argument functions like `coalesce()`, `substring()`, `replace()`, `left()`, and `right()` are handled via `multiarg_func_canonical` (lines 144-151) and `parse_multiarg_func_item` (lines 239-260).

## Result Shaping and Composition

The `RETURN` clause supports `AS` aliasing, implemented in `parse_return_item` (lines 240-250). Result ordering uses `ORDER BY … ASC/DESC`.

**UNION** and **UNION ALL** combine multiple query results (parsed around line 1810 in `parse_post_where`), though nested UNION recursion is not supported.

**CASE** expressions follow the standard `CASE WHEN … THEN … ELSE … END` pattern, implemented in `parse_case_expr` (lines 224-260).

## Practical Query Examples

```cypher
-- Simple match with label alternation and property filter
MATCH (f:Function|Method {language: "Go"})
WHERE f.name CONTAINS "parse"
RETURN f.name AS function, f.file, f.line
ORDER BY f.line ASC
LIMIT 20

```

```cypher
-- Variable-length path (up to 5 hops) with direction
MATCH (src:File)-[:IMPORT*1..5]->(dst:File)
WHERE src.path STARTS WITH "/src/"
RETURN src.path, dst.path

```

```cypher
-- Aggregate + CASE
MATCH (c:Class)-[:HAS_METHOD]->(m:Method)
WHERE c.package = "github.com/DeusData"
RETURN c.name,
       COUNT(m) AS method_count,
       CASE WHEN COUNT(m) > 10 THEN "Large" ELSE "Small" END AS size
ORDER BY method_count DESC

```

```cypher
-- UNION of two independent queries
MATCH (p:Project {name: "MCP"})
RETURN p.name, "project" AS type
UNION
MATCH (l:Language {name: "C"})
RETURN l.name, "language" AS type

```

## Explicitly Unsupported Features

Write operations are tokenized but rejected with "unsupported Cypher feature" errors via `unsupported_clause_error` (lines 196-225). These include:

- **Write clauses**: `CREATE`, `DELETE`, `MERGE`, `SET`, `REMOVE`, `DETACH`
- **Procedural**: `CALL`, `UNWIND`, `FOREACH`
- **Schema commands**: `DROP`, `CONSTRAINT`
- **Sub-queries** and nested structures
- **List indexing** (`[…]`) and map literals

## Implementation Architecture

The Cypher engine is implemented across these key files:

- [`src/cypher/cypher.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.h) – Token definitions and public API
- [`src/cypher/cypher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.c) – Lexer, parser, and executor (~300+ lines) containing functions like `parse_node`, `parse_condition_expr`, and `parse_aggregate_item`
- [`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c) – CLI entry point exposing the `query_graph` tool (lines 370-395)
- [`src/cli/cli.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.c) – Help text with Cypher examples (lines 461-521)

## Summary

- Codebase-Memory-MCP implements a **read-only Cypher subset** for querying code graphs stored in SQLite.
- Supported features include `MATCH` with variable-length paths, `WHERE` with complex predicates, aggregations, scalar/multi-arg functions, `CASE` expressions, and `UNION`.
- All write operations (`CREATE`, `DELETE`, `MERGE`, `SET`) are explicitly blocked by the `unsupported_clause_error` handler.
- The parser is defined in [`src/cypher/cypher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.c) with strict validation ensuring only analytical queries execute.

## Frequently Asked Questions

### Does Codebase-Memory-MCP support CREATE or DELETE statements?

No. The engine explicitly rejects all write-oriented clauses including `CREATE`, `DELETE`, `MERGE`, `SET`, `REMOVE`, and `DETACH`. Attempting to use these triggers an "unsupported Cypher feature" error from the `unsupported_clause_error` function in [`src/cypher/cypher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.c).

### What is the maximum depth for variable-length path queries?

The default maximum depth is 10 hops, controlled by the `CYP_MAX_DEPTH` constant. You can specify ranges like `*1..5` in relationship patterns, which are parsed by `parse_hop_range` in [`src/cypher/cypher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.c) (lines 96-110).

### Can I use sub-queries or UNWIND in my Cypher queries?

No. Sub-queries, `UNWIND`, and `FOREACH` are not supported. The parser only handles single-statement read queries and will reject any nested query structures or list unwinding operations according to the implementation in [`src/cypher/cypher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.c).

### Which string functions are available in the supported Cypher subset?

The engine supports `CONTAINS`, `STARTS WITH`, `ENDS WITH`, `toLower()`, `toUpper()`, `toString()`, `trim()`, `ltrim()`, `rtrim()`, `reverse()`, `substring()`, `replace()`, `left()`, and `right()`. These are handled in `parse_string_func_item` and `parse_multiarg_func_item` within [`src/cypher/cypher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.c).