# Supported Cypher Clauses in Codebase-Memory-MCP: Complete Reference Guide

> Explore supported Cypher clauses in Codebase-Memory-MCP. Discover 25+ clauses including MATCH, WHERE, RETURN, and UNION for efficient codebase querying. Refer to the complete reference guide.

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

---

**Codebase-Memory-MCP implements a read-only subset of the Neo4j Cypher language supporting 25+ clauses including `MATCH`, `WHERE`, `RETURN`, `UNION`, and aggregate functions, with all token definitions centralized in [`src/cypher/cypher.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.h).**

Codebase-Memory-MCP is an open-source graph memory system designed for static code analysis. It ships with a lightweight, in-process Cypher query engine that parses and executes read-only queries against an embedded graph store. The supported subset focuses on safe, analytical operations while deliberately excluding data-modifying commands.

## Core Query Structure Clauses

The engine recognizes fundamental Cypher building blocks defined as token types in [`src/cypher/cypher.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.h).

### Pattern Matching and Filtering

- **`MATCH`** – `TOK_MATCH` (line 23) initiates pattern-matching expressions against the graph.
- **`WHERE`** – `TOK_WHERE` (line 24) filters matched elements using boolean predicates.
- **`WITH`** – `TOK_WITH` (line 36) enables sub-queries and variable passing between query parts, supporting read-only pipelines.

### Projection and Results

- **`RETURN`** – `TOK_RETURN` (line 25) projects selected expressions or columns from the match.
- **`AS`** – `TOK_AS` (line 31) renames expressions (e.g., `COUNT(g) AS cnt`).
- **`DISTINCT`** – `TOK_DISTINCT` (line 32) removes duplicate rows from result projections.

## Sorting, Pagination, and Set Operations

### Ordering and Limits

- **`ORDER BY`** – Implemented via `TOK_ORDER` (line 26) and `TOK_BY` (line 27) to sort result sets.
- **`ASC` / `DESC`** – `TOK_ASC` (line 38) and `TOK_DESC` (line 39) specify sorting directions.
- **`LIMIT`** – `TOK_LIMIT` (line 28) caps the number of returned rows.
- **`SKIP`** – `TOK_SKIP` (line 46) offsets the result set for pagination.

### Advanced Result Handling

- **`UNION`** – `TOK_UNION` (line 47) combines results from two `MATCH` blocks (read-only only).
- **`UNWIND`** – `TOK_UNWIND` (line 48) expands a list into individual rows.

## Boolean Logic and Conditional Expressions

### Logical Operators

- **`AND`** – `TOK_AND` (line 29) for boolean conjunction inside `WHERE` clauses.
- **`OR`** – `TOK_OR` (line 30) for boolean disjunction.
- **`NOT`** – `TOK_NOT` (line 37) for predicate negation.
- **`XOR`** – `TOK_XOR` (line 45) for exclusive-or logical operations.

### Conditional Logic

- **`CASE` … `WHEN` … `THEN` … `ELSE` … `END`** – Implemented via `TOK_CASE` (line 63) through `TOK_END` (line 68), enabling conditional expressions within `RETURN` or `WHERE` clauses.

## Predicates and Functions

### String and Comparison Predicates

- **`CONTAINS`** – `TOK_CONTAINS` (line 34) performs substring searches (e.g., `x CONTAINS "foo"`).
- **`STARTS WITH`** – Built from `TOK_STARTS` (line 35) combined with `WITH` for string prefix matching.
- **`IN`** – `TOK_IN` (line 42) tests membership in lists (e.g., `x IN [1,2,3]`).
- **`IS NULL`** – Uses `TOK_IS` (line 43) paired with `TOK_NULL_KW` (line 44) for null checks.

### Aggregate Functions

The engine treats aggregate functions as keywords tokenized in [`src/cypher/cypher.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.h):

- **`COUNT`** – `TOK_COUNT` (line 33)
- **`SUM`** – `TOK_SUM`
- **`AVG`** – `TOK_AVG`
- **`MIN`** – `TOK_MIN_KW`
- **`MAX`** – `TOK_MAX_KW`
- **`collect`** – `TOK_COLLECT`

### String Transformation Functions

- **`toLower`** – `TOK_TOLOWER`
- **`toUpper`** – `TOK_TOUPPER`
- **`toString`** – `TOK_TOSTRING`

## Query Engine Architecture

The Cypher implementation operates in four distinct stages defined in [`src/cypher/cypher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.c):

1. **Lexing** – `cbm_lex()` tokenizes the raw query string into the token types defined in [`src/cypher/cypher.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.h).
2. **Parsing** – `cbm_cypher_parse()` constructs an abstract syntax tree (AST) from the token stream, enforcing grammar rules such as mandatory `MATCH` and `RETURN` sequences.
3. **Planning** – The AST transforms into an execution plan that traverses the in-memory graph store (`cbm_store_t`).
4. **Execution** – `cbm_cypher_execute()` runs the plan and produces a `cbm_cypher_result_t` iterable by the caller.

The test suite in [`tests/test_cypher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_cypher.c) validates each clause individually through tests like `TEST(cypher_parse_where_regex)` and `TEST(cypher_exec_return_order_limit)`.

## Practical Query Examples

### Basic Pattern Matching

```c
cbm_cypher_result_t r = {0};
int rc = cbm_cypher_execute(store,
    "MATCH (f:Function) RETURN f.name, f.qualified_name",
    "example", 0, &r);

```

### Filtering with Regular Expressions and String Predicates

```c
rc = cbm_cypher_execute(store,
    "MATCH (f:Function) "
    "WHERE f.name =~ \".*Order.*\" "
    "  AND f.path CONTAINS \"src/\" "
    "RETURN f.name",
    "example", 0, &r);

```

### Aggregation with Sorting and Pagination

```c
rc = cbm_cypher_execute(store,
    "MATCH (f)-[:CALLS]->(g) "
    "RETURN f.name, COUNT(g) AS cnt "
    "ORDER BY cnt DESC "
    "SKIP 10 LIMIT 5",
    "example", 0, &r);

```

### Combining Results with UNION

```c
rc = cbm_cypher_execute(store,
    "MATCH (n) RETURN n.name "
    "UNION "
    "MATCH (m) RETURN m.name",
    "example", 0, &r);

```

### Expanding Lists with UNWIND

```c
rc = cbm_cypher_execute(store,
    "UNWIND [1,2,3] AS x RETURN x",
    "example", 0, &r);

```

## Limitations and Unsupported Clauses

While the lexer recognizes keywords such as `CREATE`, `DELETE`, and `MERGE` for syntax completeness, these write-operation clauses are deliberately unsupported. Attempting to use them triggers a parse error, ensuring the engine remains safe for read-only analytical workloads against the immutable code graph.

## Summary

- **Codebase-Memory-MCP** supports a read-only subset of Cypher defined in [`src/cypher/cypher.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.h) with 25+ token types including `MATCH`, `WHERE`, `RETURN`, and aggregate functions.
- The query pipeline implements four stages—lexing (`cbm_lex`), parsing (`cbm_cypher_parse`), planning, and execution (`cbm_cypher_execute`).
- **Sorting and pagination** are supported via `ORDER BY`, `LIMIT`, and `SKIP` tokens.
- **Set operations** `UNION` and `UNWIND` enable complex result combinations and list expansions.
- Write clauses (`CREATE`, `DELETE`, `MERGE`) are recognized but explicitly rejected to maintain read-only safety.

## Frequently Asked Questions

### Does Codebase-Memory-MCP support write operations like CREATE or DELETE?

No. While the lexer tokenizes keywords such as `CREATE`, `DELETE`, and `MERGE`, the parser explicitly rejects them to maintain a read-only safety model. This design prevents accidental modification of the in-process graph store during static analysis operations.

### How does the engine handle pagination in Cypher queries?

Pagination combines the `SKIP` and `LIMIT` clauses. `TOK_SKIP` (defined at line 46 in [`src/cypher/cypher.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.h)) offsets the result set, while `TOK_LIMIT` (line 28) caps the number of rows returned. For example, `SKIP 10 LIMIT 5` returns rows 11 through 15.

### What aggregate functions are available in Codebase-Memory-MCP?

The engine supports `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, and `collect`, each defined as distinct token types (`TOK_COUNT`, `TOK_SUM`, `TOK_AVG`, `TOK_MIN_KW`, `TOK_MAX_KW`, `TOK_COLLECT`). These functions operate within `RETURN` clauses to compute grouped aggregations across matched patterns.

### Is the Cypher implementation compatible with Neo4j?

Codebase-Memory-MCP implements a subset of Neo4j Cypher focused on read-only graph traversal. Queries using supported clauses like `MATCH`, `WHERE`, `RETURN`, and `UNION` will execute identically, but data-modifying statements and advanced Neo4j-specific extensions are not supported.