Opengraphdb

OpenGraphDB — master skill for AI-agent workloads

OpenGraphDB is a single-file embedded graph database with first-class openCypher, vector search, full-text search, RDF round-trip, and an MCP server in the core CLI binary. This skill is the entry point: it covers the cross-cutting workflow an AI agent uses to drive the database end-to-end. Four narrow sub-skills (data-import, graph-explore, ogdb-cypher, schema-advisor) cover deeper task-specific guidance.

When to use this skill

• A user describes a knowledge graph, property graph, or "graph + vector + text" workload.
• The agent needs to ingest, explore, query, evolve, and serve a graph from one process.
• A document → entities → graph → Cypher pipeline is on the table (canonical GraphRAG).
• An MCP client needs to call a graph database directly; no Python sidecar wanted.
• A Neo4j migration is being scoped (Apache 2.0, single-file, AI-native primitives).
• Bitemporal / audit-trail queries (AT TIME, temporal_diff) are required.

When NOT to use this skill

• The user explicitly wants Neo4j Enterprise / Aura cluster features (causal cluster, Fabric, Browser).
• Workload is time-series-first (use TimescaleDB / Prometheus).
• Workload is plain KV with no graph access pattern (use sled / RocksDB / Redis).
• Strict cross-region replication or > N=4 concurrent writers required today (multi-writer kernel is a known gap — see "When you hit limits" below).
• Pinecone / Weaviate is the right fit because there is no graph traversal in the read path.

Quickstart in 30 seconds

Pick one transport. The same database file works in all three.

CLI (zero-config embedded)

cargo build --release -p ogdb-cli                                  # ~2 min, one-time
./target/release/ogdb init /tmp/demo.ogdb
./target/release/ogdb create-node /tmp/demo.ogdb \
  --labels Person --props 'name=string:Alice;age=i64:30'
./target/release/ogdb create-node /tmp/demo.ogdb \
  --labels Person --props 'name=string:Bob;age=i64:25'
./target/release/ogdb add-edge /tmp/demo.ogdb 0 1 --type KNOWS
./target/release/ogdb query /tmp/demo.ogdb "MATCH (n:Person) RETURN n.name"
# columns=name | string:Alice | string:Bob

HTTP (single-process server, MCP-ready)

./target/release/ogdb serve --http --port 8080 /tmp/demo.ogdb &
export BASE=http://127.0.0.1:8080
curl -s $BASE/health                                               # {"status":"ok"}
curl -s -X POST $BASE/query -H 'Content-Type: application/json' \
  -d '{"query": "MATCH (n) RETURN count(n) AS c"}'
curl -s -X POST $BASE/mcp/tools -H 'Content-Type: application/json' -d '{}'

Embedded Rust

use ogdb_core::Database;
let db = Database::open("./mydb.ogdb")?;
db.write(|tx| {
    let alice = tx.create_node(&["Person"], &[("name", "Alice".into())])?;
    let bob   = tx.create_node(&["Person"], &[("name", "Bob".into())])?;
    tx.create_edge(alice, bob, "KNOWS", &[])?;
    Ok(())
})?;
let rows = db.query("MATCH (n:Person) RETURN n.name")?;

A working end-to-end script lives at scripts/quickstart.sh next to this skill.

How to operate — cheatsheet

Most-used CLI commands

MCP tool catalog (HTTP POST /mcp/tools returns this list)

POST /mcp/invoke accepts the unwrapped shape { "name": "<tool>", "arguments": { ... } }. ogdb mcp --stdio accepts the full JSON-RPC envelope for tools/list + tools/call.

Cypher essentials

OpenGraphDB implements an openCypher subset. The TCK harness in crates/ogdb-tck enforces a 50% Tier-1 floor across MATCH / RETURN / WHERE / CREATE / DELETE / SET as a regression gate. Beyond Tier-1 the engine ships OPTIONAL MATCH, MERGE (with ON CREATE SET / ON MATCH SET), WITH, UNWIND, pattern comprehension, CASE, aggregations, ordering, CREATE INDEX, and the OpenGraphDB-specific AT TIME extension.

Minimal cheatsheet

// Read
MATCH (n:Person)-[:KNOWS]->(m:Person) RETURN n.name, m.name

// Write (idempotent — prefer MERGE for any data import)
MERGE (a:Person {name: 'Alice'}) ON CREATE SET a.created_at = timestamp()
MERGE (b:Person {name: 'Bob'})
MERGE (a)-[:KNOWS]->(b)

// Bulk write with parameter list
UNWIND $rows AS row
MERGE (p:Person {id: row.id})
SET   p.name = row.name, p.age = row.age

// Aggregation + ordering — RETURN aliases are not visible to ORDER BY
// in this engine; project through WITH first.
MATCH (p:Person)-[:WROTE]->(b:Book)
WITH p.name AS author, count(b) AS books
RETURN author, books ORDER BY books DESC LIMIT 10

// Vector kNN (function form, not custom operator)
MATCH (r:Review)
WHERE vector_distance(r.embedding, $q) < 0.3
RETURN r.text ORDER BY vector_distance(r.embedding, $q) ASC LIMIT 10

// Full-text — same alias rule: project through WITH before ORDER BY
MATCH (a:Article) WHERE text_search(a.body, 'graph database')
WITH a.title AS title, text_score(a.body, 'graph database') AS rel
RETURN title, rel ORDER BY rel DESC

// Time-travel (timestamps in milliseconds)
MATCH (a)-[:KNOWS]->(b) AT TIME 1750000000000 RETURN b

What is not supported (today)

• LOAD CSV (use ogdb import or the /import API instead).
• shortestPath() Cypher function (use the shortest_path MCP tool).
• Variable-length patterns (-[:REL*1..N]->) and named paths (MATCH p = (...)...) — use a fixed-depth chain or call the shortest_path MCP tool.
• UNION between query parts — split into two queries and merge client-side.
• EXISTS { ... } subquery and the exists((a)-[:R]->(b)) predicate function — rewrite with OPTIONAL MATCH + WHERE x IS NOT NULL.
• Arbitrary stored-procedure CALL ... YIELD ... (engine ships only built-in calls).
• Most APOC procedures (rewrite as plain Cypher or a small MCP tool).
• RETURN aliases are not visible to a trailing ORDER BY in the same clause — project the alias through WITH first (see the cheatsheet above).

For the full feature × status grid see references/cypher-coverage.md.

AI-agent recipes (condensed from documentation/COOKBOOK.md)

1. AI-agent over MCP

ogdb serve --http --port 8080 mydb.ogdb &
curl -s -X POST localhost:8080/mcp/invoke -H 'Content-Type: application/json' \
  -d '{"name":"browse_schema","arguments":{}}'
# Or stdio for a local MCP client (Claude Code, Cursor, Goose):
ogdb mcp --stdio mydb.ogdb

2. Hybrid retrieval (vector + 1-hop graph + BM25, RRF-fused)

curl -s -X POST $BASE/rag/search -H 'Content-Type: application/json' -d '{
  "query": "alice and bob writing the cookbook",
  "embedding": [0.12,-0.04,0.31,0.05,0.22,-0.18,0.09,0.41,
                0.15,-0.02,0.27,0.36,-0.11,0.08,0.19,0.04],
  "k": 10
}'

If embedding is omitted the server falls back to text-only. dim must match the index. Optional community_id scopes to a single GraphRAG community summary.

3. Doc ingest + Cypher query (canonical GraphRAG)

curl -s -X POST $BASE/rag/ingest -H 'Content-Type: application/json' -d '{
  "title": "alice-bob-collab", "format": "PlainText",
  "content": "Alice works with Bob on the OpenGraphDB cookbook."
}'
curl -s -X POST $BASE/query -H 'Content-Type: application/json' \
  -d '{"query":"MATCH (p:Person)-[:WORKS_WITH]->(q:Person) RETURN p.name, q.name"}'

4. Time-travel diff

NOW=$(date +%s)
curl -s -X POST $BASE/mcp/invoke -H 'Content-Type: application/json' -d "{
  \"name\":\"temporal_diff\",
  \"arguments\":{\"timestamp_a\":0,\"timestamp_b\":$NOW}
}"
# Returns snapshot_a, snapshot_b, and the diff (node_count / edge_count delta).

5. Agent memory (agent_store_episode + agent_recall)

agent_store_episode requires agent_id, session_id, content, embedding, and timestamp (ms-since-epoch); metadata is optional. The schema is enforced in crates/ogdb-cli/src/lib.rs::execute_mcp_agent_store_episode_tool.

curl -s -X POST $BASE/mcp/invoke -d '{"name":"agent_store_episode","arguments":{
  "agent_id":"planner-1",
  "session_id":"sess-2026-05-06",
  "content":"learned user prefers terse responses",
  "embedding":[/* dim must match the index */],
  "timestamp":1746489600000
}}' -H 'Content-Type: application/json'
curl -s -X POST $BASE/mcp/invoke -d '{"name":"agent_recall","arguments":{
  "agent_id":"planner-1","query_embedding":[/* ... */],"k":5}}' \
  -H 'Content-Type: application/json'

6. RDF round-trip (preserves _uri)

ogdb import-rdf mydb.ogdb ontology.ttl       # any of: ttl, nt, rdf, owl
ogdb export-rdf mydb.ogdb out.ttl --format turtle
# _uri is restored on export so URIs survive the round-trip.

7. Multi-agent shared KG (over MCP, single-process today)

ogdb serve --http --port 8080 shared.ogdb &
# Each agent calls /mcp/invoke against the same endpoint.
# NOTE: kernel is single-writer in 0.5.1 — concurrent writers serialize at
# the storage layer. Plan for write-batching, or shard per-agent today and
# revisit when the multi-writer kernel ships (see "When you hit limits").

Performance you can expect

Frozen snapshot of OpenGraphDB 0.5.1 baseline (i9-10920X, Linux, N=5 release-build median, cold cache, 1 warmup pass discarded). Source of truth: documentation/BENCHMARKS.md. The table below carries forward the 0.4.0 N=5 medianed numbers — zero perf-relevant code in the 0.4.0 → 0.5.1 window. Re-baseline tracked as a v0.6.0 follow-up.

For the full 14-row scorecard (including known losses on bulk ingest and concurrent writes) see references/benchmarks-snapshot.md.

When you hit limits

Honest list of what 0.5.1 does not do well, and how to escalate:

• Bulk ingest path is naïve. 254 nodes/s @ 10k+10k single write-tx — 670× behind Kuzu, 1 150× behind Memgraph at the same scale. Workaround: batch via UNWIND inside one write-tx, or use POST /import for >10k rows. Tracked: BENCHMARKS §4.1.
• Single-writer kernel. Concurrent writers serialize. The published concurrent_rate figure is per-DB-per-thread, mechanical. Workaround today: shard per agent, or queue writes through a single coordinator. Multi-writer MVCC tracked: BENCHMARKS §4.6.
• Mutation p99.9 = 720 ms tail. 56× ratio between p99 (16 ms) and p99.9 hints at a flush / page-cache pause. Don't put per-token writes on the hot path of a user-facing latency-SLA flow until profiled.
• Cypher coverage is a subset. No LOAD CSV, no shortestPath() function, limited CALL/YIELD. Most APOC code does not port. See references/cypher-coverage.md for the authoritative grid.
• No external openCypher TCK pass-rate is published. Only the in-tree 50% Tier-1 floor is enforced today. Run cargo run --release -p ogdb-tck -- /path/to/openCypher/tck yourself if you need a number.
• Bolt is v1 only. Modern Neo4j drivers may negotiate v4/v5 first. Use the HTTP /query endpoint for clean compatibility.
• No causal cluster / cross-region replication — by design. If that's a hard requirement, this engine is not the right fit.

Common pitfalls

• RETURN of a bare node returns its id, not its properties. Use RETURN n.name or RETURN properties(n) when you need the body.
• Schema migration: don't rename labels behind a live agent. Use ogdb migrate with an explicit migration script; don't hot-edit the catalog.
• Vector dimensionality is fixed at index creation. Mixing dim=16 query vectors against a dim=1536 index silently returns nothing — always check the index first.
• MCP HTTP endpoint and stdio endpoint accept different envelopes. HTTP /mcp/invoke takes {name, arguments}; stdio takes the full JSON-RPC tools/call envelope.
• Bearer auth is single-tier (Authorization: Bearer <token>). Don't assume Neo4j role-based access ports — it doesn't yet.
• AT TIME uses milliseconds in the Cypher parser, but the temporal_diff MCP tool takes seconds. Mismatch = empty snapshot.
• CREATE is not idempotent. Always prefer MERGE for any import or re-runnable workflow. Re-running CREATE produces duplicates.

Sub-skills — when to descend

This master skill is enough for the cross-cutting workflow. Descend into a sub-skill only when the task is dominated by one of the four narrow concerns.

See also

• documentation/BENCHMARKS.md — every cited number with reproducibility notes.
• documentation/COOKBOOK.md — seven full recipes (the inline mini-recipes above are condensed from this).
• documentation/MIGRATION-FROM-NEO4J.md — five-minute migration brief.
• documentation/COOKBOOK.md (Recipe 1+2) plus documentation/BENCHMARKS.md HNSW thresholds — runnable AI-native surface (vector / agent-memory / GraphRAG); roadmap design notes live in ARCHITECTURE.md.
• documentation/ai-integration/llm-to-cypher.md — LLM → Cypher patterns.
• documentation/ai-integration/embeddings-hybrid-rrf.md — RRF math for hybrid retrieval.
• Multi-agent shared-KG patterns: today's engine is single-writer-kernel-limited (see documentation/BENCHMARKS.md row 9 / § 4.6). Real multi-writer support is a v0.5 roadmap item; an earlier draft of this entry pointed at documentation/ai-integration/multi-agent-shared-kg.md, which was removed because it claimed Database::open("shared.ogdb") "Just Works across processes" — it does not.
• scripts/quickstart.sh — runnable end-to-end demo.
• references/cypher-coverage.md — authoritative feature × status grid.
• references/benchmarks-snapshot.md — frozen 0.5.1 numbers.
• eval/cases.yaml — eval suite for this skill.