Use when the user wants to query, traverse, build, or evolve a graph database; embedded or HTTP-served; Cypher syntax, vector similarity, full-text, RDF round-trip, time-travel, GraphRAG, or an MCP tool catalog. Trigger on phrases like "graph database", "knowledge graph", "Cypher query", "MCP graph", "GraphRAG", "vector + graph", "property graph", "RDF", "time-travel queries", "Neo4j alternative", "embedded graph", "single-file graph", "Memgraph alternative", "Kuzu alternative", "graph + vector + text", or any task framed as "agent owns the graph end-to-end". Use even when the user does not name OpenGraphDB, if the workload pattern matches load entities + relationships, then query by traversal, similarity, or time. Skip when the workload is a Neo4j cluster (causal cluster, Fabric), a time-series DB, plain key-value, or a managed vector DB where graph traversal is not part of the access pattern.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
The command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
File Explorer
13 files
Showing SKILL.md
SKILL.md
Source instructions · Read-only preview
name
opengraphdb
description
Use when the user wants to query, traverse, build, or evolve a graph database; embedded or HTTP-served; Cypher syntax, vector similarity, full-text, RDF round-trip, time-travel, GraphRAG, or an MCP tool catalog. Trigger on phrases like "graph database", "knowledge graph", "Cypher query", "MCP graph", "GraphRAG", "vector + graph", "property graph", "RDF", "time-travel queries", "Neo4j alternative", "embedded graph", "single-file graph", "Memgraph alternative", "Kuzu alternative", "graph + vector + text", or any task framed as "agent owns the graph end-to-end". Use even when the user does not name OpenGraphDB, if the workload pattern matches load entities + relationships, then query by traversal, similarity, or time. Skip when the workload is a Neo4j cluster (causal cluster, Fabric), a time-series DB, plain key-value, or a managed vector DB where graph traversal is not part of the access pattern.
license
Apache-2.0
compatibility
Requires OpenGraphDB >= 0.4.0. Tested with Claude Code, Cursor, Continue.dev, Aider, Goose, Codex via MCP (stdio + HTTP). Engine binary ships ogdb mcp --stdio for local clients and ogdb serve --http for shared agents.
Single-file embedded graph database. First-class openCypher, vector kNN,
full-text, RDF round-trip, MCP server in the core CLI. Apache 2.0, no JVM,
no sidecar.
This skill covers the cross-cutting workflow an agent uses to drive the
database end-to-end. Four narrow sub-skills (data-import, graph-explore,
ogdb-cypher, schema-advisor) handle deeper task-specific work.
When to use
Building or evolving a property graph the agent owns end-to-end.
Cypher generation, exploration, or schema design against OpenGraphDB.
Hybrid retrieval in one round-trip: vector kNN + 1-hop graph + full-text.
GraphRAG: ingest documents, query back with Cypher.
Bitemporal / time-travel queries (AT TIME, temporal_diff).
Wiring an MCP-aware client (Claude Code, Cursor, Goose, Codex) to a
single-file graph.
Migrating from Neo4j / Memgraph / Kuzu where AGPL licensing, JVM weight,
or sidecar overhead is the friction.
When NOT to use
The user wants Neo4j Enterprise / Aura cluster features (causal cluster,
Fabric, Browser).
Workload is time-series-first (TimescaleDB / Prometheus).
Workload is plain KV with no traversal in the read path (sled / RocksDB).
Strict cross-region replication or > N=4 concurrent writers needed today
(multi-writer kernel is a known gap; see "Limits" below).
Quickstart in 30 seconds
Same database file works in all three transports. Pick one.
Extract subgraph around a starting node (depth configurable).
shortest_path
Pre-built shortest-path; faster than Cypher pattern.
vector_search
Semantic similarity via the HNSW index.
text_search
Full-text via the tantivy index.
temporal_diff
Compare graph state across two timestamps.
import_rdf / export_rdf
Round-trip RDF preserving _uri per node.
agent_store_episode / agent_recall
Agent-memory primitives.
rag_build_summaries / rag_retrieve
GraphRAG community summaries + retrieval.
list_datasets
Show available datasets in the database.
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: 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 a 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).
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 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-ins).
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).
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 "Limits").
Performance, with honest framing
OpenGraphDB 0.5.1 baseline (i9-10920X, Linux, N=5 release-build median, cold
cache, 1 warmup discarded). Live source of truth: documentation/BENCHMARKS.md.
The strict scorecard (post cycle-17 verdict tone-down): 1 verified
WIN, 2 caveated WIN, 2 losses, 6 novel-or-directional. The verified row
clears a published spec threshold apples-to-apples; caveated rows clear a
competitive bar but carry a documented asterisk. Use the verified row as a
trust anchor, the caveated rows as directional, and the novel rows as
"feasibility, not benchmark".
✅ caveated; clears competitive bar by orders of magnitude — boost is a synthetic Σ neighbour_id, not a learned dot-product
Read the full 14-row scorecard with apples-to-apples notes, losses, and
deferred apples-to-apples runs at references/benchmarks-snapshot.md.
For the trust-anchor view (verified-only and caveated-only rows with the
exact published-comparison framing), see references/benchmarks-verified.md.
Limits
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 in BENCHMARKS §4.1.
Single-writer kernel. Concurrent writers serialize. The published
concurrent_rate is per-DB-per-thread, mechanical. Workaround: shard
per-agent or queue writes through a coordinator. Multi-writer MVCC
tracked in 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 a
user-facing latency-SLA flow until profiled.
Cypher coverage is a subset. No LOAD CSV, no shortestPath(),
limited CALL/YIELD. Most APOC code does not port. See
references/cypher-coverage.md for the
authoritative grid.
No external openCypher TCK pass-rate 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
HTTP /query 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.
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 and stdio accept different envelopes. HTTP /mcp/invoke
takes {name, arguments}; stdio takes the full JSON-RPC tools/call
envelope.
User describes a domain and wants a graph schema. Covers eight modeling best practices, six anti-patterns, index selection, RDF mapping with _uri preservation.
This master skill covers the cross-cutting workflow. Descend into a
sub-skill only when the task is dominated by one of the four narrow
concerns.
