fluree · bplatz · Jul 5, 2026 · Jun 30, 2026 · Jun 30, 2026 · Jul 5, 2026
diff --git a/.cursor/mcp.json b/.cursor/mcp.json
diff --git a/.cursor/rules/fluree_rules.md b/.cursor/rules/fluree_rules.md
diff --git a/.gitignore b/.gitignore
@@ -40,3 +40,6 @@ __pycache__/
 # Internal analysis scratch — not part of the published docs
 BI_QUERY_ANALYSIS.md
 SEPARATION_PLAN.md
+
+# Cursor editor config — local only
+/.cursor/
diff --git a/docs/README.md b/docs/README.md
@@ -2,11 +2,11 @@
 
 A semantic graph database with time travel, branching, and verifiable data — built on W3C standards.
 
-Fluree DB is a single binary that stores your data as an RDF knowledge graph, queryable with SPARQL or JSON-LD Query, with every commit immutably recorded so you can travel back to any prior state. It supports git-style branching and merging, signed and policy-gated transactions, SHACL validation, OWL/RDFS reasoning, and full-text and vector search — over local files, S3, or IPFS — without bolting on external services.
+Fluree DB is a single binary that stores your data as an RDF knowledge graph, queryable with SPARQL, JSON-LD Query, or Cypher, with every commit immutably recorded so you can travel back to any prior state. It supports git-style branching and merging, signed and policy-gated transactions, SHACL validation, OWL/RDFS reasoning, and full-text and vector search — over local files, S3, or IPFS — without bolting on external services.
 
 ## What you get
 
-- **Semantic by default.** Your data is RDF. IRIs, JSON-LD `@context`, named graphs, and typed values are first-class. Queries are SPARQL 1.1 or the equivalent JSON-LD Query, both compiling to the same execution engine.
+- **Semantic by default.** Your data is RDF. IRIs, JSON-LD `@context`, named graphs, and typed values are first-class. Queries are SPARQL 1.1, the equivalent JSON-LD Query, or openCypher — all compiling to the same execution engine.
 - **Property graphs and statement-level metadata.** Attach properties to a *relationship*, not just a node — `role` and `since` on a `worksFor` edge, `source` and `confidence` on a claim — with RDF 1.2 / SPARQL 1.2 edge annotations. Labeled-property-graph edges, parallel relationships between the same two nodes, and RDF-star provenance all live on one surface, and plain triple queries are left undisturbed. See [Edge annotations](concepts/edge-annotations.md).
 - **Time travel.** Every transaction is a commit on an immutable chain. Query the state of the graph at any past moment with a single `t` parameter — no snapshots to restore, no separate audit log to consult.
 - **Branching and merging.** Create a branch off any commit, transact against it in isolation, then merge it back. Useful for staging changes, running what-if analyses, or maintaining environment-specific overlays.
@@ -22,7 +22,7 @@ Fluree DB is a single binary that stores your data as an RDF knowledge graph, qu
 - **New to Fluree?** → [Getting started](getting-started/)
 - **Run the server** → [Quickstart: run the server](getting-started/quickstart-server.md)
 - **Create a ledger and write data** → [Quickstart: create a ledger](getting-started/quickstart-ledger.md) → [Quickstart: write data](getting-started/quickstart-write.md)
-- **Query data** → [Quickstart: query (JSON-LD + SPARQL)](getting-started/quickstart-query.md)
+- **Query data** → [Quickstart: query (JSON-LD, SPARQL, Cypher)](getting-started/quickstart-query.md)
 - **End-to-end walkthrough** → [Tutorial: search, time travel, branching, policies](getting-started/tutorial-end-to-end.md)
 - **Coming from SQL?** → [Fluree for SQL developers](getting-started/fluree-for-sql-developers.md)
 - **Embedding in Rust?** → [Using Fluree as a Rust library](getting-started/rust-api.md)
@@ -33,7 +33,7 @@ Fluree DB is a single binary that stores your data as an RDF knowledge graph, qu
 - [Guides (cookbooks)](guides/) — query patterns, search, time travel, branching, policies, SHACL, edge annotations — task-oriented recipes
 - [CLI reference](cli/) — every `fluree` command, flag by flag
 - [HTTP API](api/) — endpoints, headers, signed requests, error model
-- [Query](query/) — JSON-LD Query, SPARQL, output formats, CONSTRUCT, explain plans, reasoning
+- [Query](query/) — JSON-LD Query, SPARQL, Cypher, output formats, CONSTRUCT, explain plans, reasoning
 - [Transactions](transactions/) — insert, upsert, update, conditional updates, signed transactions
 - [Security and policy](security/) — authentication, encryption, commit signing, policy model
 - [Indexing and search](indexing-and-search/) — background indexing, BM25, vector search, geospatial

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -103,7 +103,7 @@
 - [Query](query/README.md)
   - [JSON-LD Query](query/jsonld-query.md)
   - [SPARQL](query/sparql.md)
-  - [Cypher (openCypher subset)](query/cypher.md)
+  - [Cypher (openCypher)](query/cypher.md)
   - [Output formats (JSON-LD / SPARQL JSON / typed JSON / Agent JSON)](query/output-formats.md)
   - [Datasets, FROM/FROM NAMED, and multi-graph execution](query/datasets.md)
   - [CONSTRUCT](query/construct.md)

diff --git a/docs/api/endpoints.md b/docs/api/endpoints.md
@@ -45,7 +45,7 @@ This endpoint is intended for debugging and operator support. See also [Admin, h
 
 ### POST /update
 
-Submit an **update** transaction (WHERE/DELETE/INSERT JSON-LD or SPARQL UPDATE) to write data to a ledger.
+Submit an **update** transaction (WHERE/DELETE/INSERT JSON-LD, SPARQL UPDATE, or Cypher `CREATE`/`MERGE`/`SET`/`DELETE`) to write data to a ledger.
 
 **URL:**
 ```
@@ -71,6 +71,17 @@ Content-Type: application/sparql-update
 Accept: application/json
 ```
 
+For Cypher writes (`CREATE`/`MERGE`/`SET`/`DELETE`):
+```http
+Content-Type: application/cypher
+Accept: application/json
+```
+
+Note: Cypher targets a ledger directly and must use the path form
+(`POST /update/{ledger-id}`); it has no `FROM`/dataset clause. The body may be
+raw Cypher or the JSON envelope `{"cypher": "...", "params": {...}}`. See the
+[Cypher reference](../query/cypher.md) for details.
+
 Note: Turtle/TriG are not accepted on `/update`. Use `/insert` (Turtle) or `/upsert` (Turtle/TriG).
 
 **Request Body (JSON-LD):**
@@ -1207,6 +1218,16 @@ FROM <txn-meta>
 WHERE { ?commit f:t ?t }'
 ```
 
+Cypher (`Content-Type: application/cypher` — ledger-scoped only, no `FROM`/dataset clause):
+
+```bash
+curl -X POST "http://localhost:8090/v1/fluree/query/mydb:main" \
+  -H "Content-Type: application/cypher" \
+  --data 'MATCH (p:Person) RETURN p.name'
+```
+
+Cypher responses default to `cypher-json`; request RDF JSON-LD with `Accept: application/ld+json`. The body may be raw Cypher or the JSON envelope `{"cypher": "...", "params": {...}}`. See the [Cypher reference](../query/cypher.md).
+
 ### History Queries via POST /query
 
 Query the history of entities using the standard `/query` endpoint with `from` and `to` keys specifying the time range.
@@ -2805,7 +2826,7 @@ This section summarizes the contract that third-party server implementations (e.
 |----------|-------------|
 | `GET /info/{ledger}` | `info`, `push`, `pull`, `clone` |
 | `GET /show/{ledger}?commit=<ref>` | `show --remote` |
-| `POST /query/{ledger}` | `query` (JSON-LD and SPARQL) |
+| `POST /query/{ledger}` | `query` (JSON-LD, SPARQL, and Cypher) |
 | `POST /insert/{ledger}` | `insert` |
 | `POST /upsert/{ledger}` | `upsert` |
 | `GET /exists/{ledger}` | `clone` (pre-create check) |

diff --git a/docs/api/overview.md b/docs/api/overview.md
@@ -82,7 +82,7 @@ defaults to `/v1/fluree`.
 ### Transaction Endpoints
 
 **POST /update**
-- Submit update transactions (WHERE/DELETE/INSERT JSON-LD or SPARQL UPDATE)
+- Submit update transactions (WHERE/DELETE/INSERT JSON-LD, SPARQL UPDATE, or Cypher `CREATE`/`MERGE`/`SET`/`DELETE`)
 - Parameters: `ledger`, `context`
 - Returns: Transaction receipt with commit info
 
@@ -92,7 +92,7 @@ defaults to `/v1/fluree`.
 ### Query Endpoints
 
 **POST /query**
-- Execute queries (JSON-LD Query or SPARQL)
+- Execute queries (JSON-LD Query, SPARQL, or Cypher — Cypher on the ledger-scoped `/query/{ledger}` route with `Content-Type: application/cypher`)
 - Parameters: None (ledger specified in query body)
 - Returns: Query results
 - Supports history queries via time range in `from` clause (see [Time Travel](../concepts/time-travel.md))

diff --git a/docs/cli/README.md b/docs/cli/README.md
@@ -148,7 +148,9 @@ Input is resolved in this priority order: `-e` flag > positional inline > `-f` f
 The CLI auto-detects data format based on content:
 - Lines starting with `@prefix` or `@base` → Turtle
 - Content starting with `{` or `[` → JSON-LD
+- Leading `MATCH`/`MERGE`/`CREATE (`/`DETACH`, or a `.cypher`/`.cyp`/`.cql` file → Cypher
+- SPARQL query/update keywords (`SELECT`/`INSERT`/`DELETE`/`PREFIX`) → SPARQL
 - Files with `.ttl` extension → Turtle
 - Files with `.json` or `.jsonld` extension → JSON-LD
 
-You can override with `--format turtle` or `--format jsonld`.
+You can override with `--format turtle`, `--format jsonld`, `--format sparql`, or `--format cypher` (see the per-command docs for the exact set each accepts).
diff --git a/docs/cli/query.md b/docs/cli/query.md
@@ -26,10 +26,11 @@ the positional auto-detection (e.g. `fluree query --ledger mydb:main 'SELECT …
 | `-l, --ledger <LEDGER>` | Ledger name (defaults to active ledger); explicit alternative to the positional ledger argument |
 | `-e, --expr <EXPR>` | Inline query expression (alternative to positional) |
 | `-f, --file <FILE>` | Read query from a file |
-| `--format <FORMAT>` | Output format: `json`, `typed-json`, `table`, `csv`, `tsv`, or `ndjson` (default: `table`) |
+| `--format <FORMAT>` | Output format: `json`, `jsonld`, `typed-json`, `cypher-json`, `table`, `csv`, `tsv`, or `ndjson` (default: `table`; Cypher defaults to `cypher-json`) |
 | `--envelope` | With `--format ndjson`, emit the full streaming record protocol verbatim instead of bare binding objects |
 | `--sparql` | Force SPARQL query format |
 | `--jsonld` | Force JSON-LD query format |
+| `--cypher` | Force openCypher query format (local ledgers only) |
 | `--at <TIME>` | Query at a specific point in time |
 | `--normalize-arrays` | Always wrap multi-value properties in arrays (graph-crawl JSON-LD queries only) |
 | `--bench` | Benchmark mode: time execution only and print the first 5 rows as a table (no full-result JSON formatting) |
@@ -38,7 +39,7 @@ the positional auto-detection (e.g. `fluree query --ledger mydb:main 'SELECT …
 
 ## Description
 
-Executes a query against a ledger. Supports both SPARQL and JSON-LD query formats.
+Executes a query against a ledger. Supports SPARQL, JSON-LD, and openCypher query formats.
 
 ## Query Formats
 
@@ -54,10 +55,28 @@ fluree query 'SELECT ?name WHERE { ?s <http://example.org/name> ?name }'
 fluree query '{"select": ["?name"], "where": {"http://example.org/name": "?name"}}'
 ```
 
+### Cypher
+
+openCypher reads run on **local ledgers only** (the HTTP Cypher route is not yet
+wired through `--remote`). Results default to `cypher-json` (a Neo4j-compatible
+envelope); pass `--format jsonld` for the RDF JSON-LD form.
+
+```bash
+fluree query mydb:main -e 'MATCH (p:Person) RETURN p.name' --cypher
+fluree query mydb:main -f find-people.cypher
+```
+
 Format is auto-detected if not specified:
+- Force with `--sparql`, `--jsonld`, or `--cypher`; a `.cypher`/`.cyp`/`.cql`
+  file extension also forces Cypher.
+- Leading `MATCH`/`MERGE`/`UNWIND`/`OPTIONAL`/`DETACH`/`CREATE`, or a
+  `{"cypher": "..."}` envelope → Cypher
 - Contains `SELECT`, `CONSTRUCT`, `ASK`, or `DESCRIBE` → SPARQL
 - Otherwise → JSON-LD
 
+For Cypher writes (`CREATE`/`MERGE`/`SET`/`DELETE`), use [`fluree update`](update.md)
+with `--format cypher` (or a `.cypher` file).
+
 ## Output Formats
 
 ### JSON (default)

diff --git a/docs/cli/update.md b/docs/cli/update.md
@@ -24,7 +24,7 @@ fluree update [LEDGER] [DATA] [OPTIONS]
 | `-e, --expr <EXPR>` | Inline data expression (alternative to positional) |
 | `-f, --file <FILE>` | Read data from a file |
 | `-m, --message <MSG>` | Commit message |
-| `--format <FORMAT>` | Data format: `jsonld` or `sparql` (auto-detected if omitted) |
+| `--format <FORMAT>` | Data format: `jsonld`, `sparql`, or `cypher` (auto-detected if omitted) |
 | `--remote <NAME>` | Execute against a remote server (by remote name) |
 | `--direct` | Bypass auto-routing through a local server (global flag; see note on SPARQL UPDATE below) |
 
@@ -42,6 +42,7 @@ Executes a WHERE/DELETE/INSERT transaction against a ledger. Unlike `insert` (wh
 
 - **JSON-LD** (default): transaction body with `where`, `delete`, and/or `insert` keys
 - **SPARQL UPDATE**: standard `INSERT DATA`, `DELETE DATA`, `DELETE/INSERT WHERE` syntax
+- **Cypher**: openCypher writes (`CREATE`/`MERGE`/`SET`/`REMOVE`/`DELETE`). Force with `--format cypher`, a `.cypher`/`.cyp`/`.cql` file, or a `{"cypher": "..."}` envelope. See the [Cypher reference](../query/cypher.md) and [cookbook](../guides/cookbook-cypher.md).
 
 ### SPARQL UPDATE Note
 
@@ -133,11 +134,14 @@ The format is auto-detected using this priority:
 2. **File extension** (when using `-f` or a positional file path):
    - `.json`, `.jsonld` → JSON-LD
    - `.rq`, `.ru`, `.sparql` → SPARQL UPDATE
+   - `.cypher`, `.cyp`, `.cql` → Cypher
 3. **Content sniffing**:
+   - A `{"cypher": "...", "params": {...}}` envelope → Cypher
    - Valid JSON (full parse, not just first character) → JSON-LD
+   - Starts with `MATCH `, `MERGE `, `DETACH `, or `CREATE (` → Cypher
    - Starts with `INSERT`, `DELETE`, `PREFIX`, or `BASE` → SPARQL UPDATE
 
-Override with `--format jsonld` or `--format sparql`.
+Override with `--format jsonld`, `--format sparql`, or `--format cypher`.
 
 ## Comparison with Insert and Upsert
 

diff --git a/docs/concepts/README.md b/docs/concepts/README.md
@@ -78,7 +78,7 @@ Fluree combines several architectural concepts:
 - **Temporal Database**: Every transaction is timestamped, enabling complete historical access
 - **Multi-Graph Support**: Data can be partitioned across named graphs
 - **JSON-LD Integration**: Native support for JSON-LD with full IRI expansion/compaction
-- **SPARQL & JSON-LD Query**: Support for both SPARQL and Fluree's native JSON-LD Query language
+- **SPARQL, JSON-LD Query & Cypher**: Query the same data through SPARQL, Fluree's native JSON-LD Query, or openCypher
 
 ## Key Differentiators
 

diff --git a/docs/getting-started/quickstart-query.md b/docs/getting-started/quickstart-query.md
@@ -1,6 +1,6 @@
 # Quickstart: Query Data
 
-This guide introduces you to querying data in Fluree using both JSON-LD Query and SPARQL.
+This guide introduces you to querying data in Fluree using JSON-LD Query, SPARQL, and Cypher.
 
 ## Prerequisites
 
@@ -9,12 +9,13 @@ This guide introduces you to querying data in Fluree using both JSON-LD Query an
 
 ## Query Languages
 
-Fluree supports two query languages:
+Fluree supports three query languages:
 
 - **JSON-LD Query**: Fluree's native JSON-based query language
 - **SPARQL**: W3C standard RDF query language
+- **Cypher**: openCypher for property-graph reads and writes
 
-Both provide access to the same data and features.
+All three run against the same data and engine. This guide focuses on JSON-LD Query and SPARQL; see [Cypher](#cypher) below and the [Cypher reference](../query/cypher.md) for the property-graph surface.
 
 ## JSON-LD Query
 
@@ -220,6 +221,23 @@ curl -X POST http://localhost:8090/v1/fluree/query \
   '
 ```
 
+## Cypher
+
+Cypher targets a ledger directly (no `FROM`/dataset clause) — send the statement
+with `Content-Type: application/cypher` to the ledger-scoped query endpoint:
+
+```bash
+curl -X POST http://localhost:8090/v1/fluree/query/mydb:main \
+  -H "Content-Type: application/cypher" \
+  --data 'MATCH (person:Person) RETURN person.name'
+```
+
+Results default to `cypher-json` (a Neo4j-compatible tabular envelope); request
+RDF JSON-LD with `Accept: application/ld+json`. Cypher is read/write — `CREATE` /
+`MERGE` / `SET` / `DELETE` statements go to the ledger-scoped `/update` endpoint.
+See the [Cypher reference](../query/cypher.md) and the
+[Cypher cookbook](../guides/cookbook-cypher.md) for the full surface.
+
 ## Time Travel Queries
 
 Query historical data using time specifiers.
@@ -638,7 +656,7 @@ Empty result set (not an error):
 
 Now that you can query data:
 
-1. **Learn Advanced Queries**: Explore [JSON-LD Query](../query/jsonld-query.md) and [SPARQL](../query/sparql.md) documentation
+1. **Learn Advanced Queries**: Explore [JSON-LD Query](../query/jsonld-query.md), [SPARQL](../query/sparql.md), and [Cypher](../query/cypher.md) documentation
 2. **Understand Time Travel**: Deep dive into [Time Travel](../concepts/time-travel.md)
 3. **Optimize Queries**: Read about [Explain Plans](../query/explain.md)
 4. **Multi-Graph Queries**: Learn about [Datasets](../query/datasets.md)
@@ -647,6 +665,7 @@ Now that you can query data:
 
 - [JSON-LD Query](../query/jsonld-query.md) - Complete JSON-LD query reference
 - [SPARQL](../query/sparql.md) - Complete SPARQL reference
+- [Cypher](../query/cypher.md) - openCypher reads and writes
 - [Output Formats](../query/output-formats.md) - Result format options
 - [Time Travel](../concepts/time-travel.md) - Historical queries
 - [Graph Crawl](../query/graph-crawl.md) - Graph traversal
diff --git a/docs/getting-started/quickstart-write.md b/docs/getting-started/quickstart-write.md
@@ -11,6 +11,8 @@ This guide shows you how to write data to Fluree using three main patterns: inse
 
 Fluree stores data as RDF triples (subject-predicate-object). Transactions are submitted as JSON-LD documents that get converted to triples internally.
 
+This guide uses JSON-LD. The same writes can also be expressed in **SPARQL UPDATE** or **openCypher** (`CREATE`/`MERGE`/`SET`/`DELETE`) — all three land in the same ledger. See the [Cypher reference](../query/cypher.md) for the property-graph write surface.
+
 ### Basic Transaction Structure
 
 ```json
@@ -480,4 +482,5 @@ Now that you can write data:
 - [Insert](../transactions/insert.md) - Detailed insert documentation
 - [Upsert](../transactions/upsert.md) - Detailed upsert documentation
 - [Update](../transactions/update-where-delete-insert.md) - Detailed update documentation
+- [Cypher](../query/cypher.md) - openCypher reads and writes
 - [Data Types](../concepts/datatypes.md) - Comprehensive type system guide