Samyama Graph

A Rust-native graph-vector database for GraphRAG, knowledge graphs, and billion-edge analytics.

The graph database that queried 1 billion edges for $2.50

💬 Join the Samyama OSS community on WhatsApp — questions, help, and updates.

What is Samyama Graph?

Samyama Graph is a Rust-native graph-vector database that lets developers store, query, search, and analyze connected data in one system.

It brings together graph traversal, OpenCypher-style querying, vector search, graph algorithms, and Redis-compatible access, making it useful for GraphRAG, knowledge graphs, AI agent memory, and large-scale relationship analytics.

Quickstart

Option 1 — Run with Docker Compose

Step 1 — Prerequisites

• ✅ Docker Desktop installed and running — Watch setup video →
• ✅ No account or credentials needed — the image is public on GitHub Container Registry (latest is the newest release; pin a version such as :1.8.0 for a reproducible setup)

Step 2 — Pull the Docker image

docker pull ghcr.io/samyama-ai/samyama-graph:latest

Step 3 — Docker Compose setup

Create a clean folder, then create docker-compose.yml inside it.

Linux & Mac:

mkdir -p samyama-graph
cd samyama-graph
touch docker-compose.yml

Windows (PowerShell):

mkdir C:\samyama-graph
cd C:\samyama-graph
notepad docker-compose.yml

ℹ️ Replace <your-openai-api-key> with your actual key. Generate one at platform.openai.com/api-keys.

version: "3.9"
services:
  samyama-graph:
    image: ghcr.io/samyama-ai/samyama-graph:latest
    container_name: samyama-graph
    restart: unless-stopped
    ports:
      - "6379:6379"
      - "8080:8080"
    environment:
      EMBED_ENABLED: "true"
      EMBED_PROVIDER: openai
      EMBED_MODEL: text-embedding-3-small
      EMBED_API_KEY: <your-openai-api-key>
      EMBED_DIMENSION: 1024
    volumes:
      - samyama-data:/app/samyama_data
    networks:
      - samyama-network
networks:
  samyama-network:
    driver: bridge
volumes:
  samyama-data:

Step 4 — Start the server

docker compose up -d

Server will be available at http://localhost:8080

Step 5 — Verify it's running

docker ps
docker logs -f samyama-graph

You should see samyama-graph with status Up.

Step 6 — Run your first query

curl -X POST http://localhost:8080/api/query \
  -H 'content-type: application/json' \
  -d '{"query":"CREATE (a:Person {name: \"Alice\"})-[:KNOWS]->(b:Person {name: \"Bob\"}) RETURN a.name, b.name","graph":"default"}'

{"columns":["a.name","b.name"],"edges":[],"nodes":[],"records":[["Alice","Bob"]]}

Then read it back:

curl -X POST http://localhost:8080/api/query \
  -H 'content-type: application/json' \
  -d '{"query":"MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN a.name, b.name","graph":"default"}'

Note on -->: the published 1.1.0 image cannot parse the bare arrow form (MATCH (a)-->(b)); write -[]-> or name the relationship type until a newer image is published (#1038).

Step 7 — Samyama Visualizer

Visualize your imported graph data using the Samyama cloud visualizer at https://graph.samyama.cloud/

1. Open https://graph.samyama.cloud/ in your browser.
2. Sign up for a new account, or sign in if you already have one.
3. From the left sidebar, click Home.
4. In the connection field, enter your local graph server URL: http://localhost:8080.
5. Click Connect — the status will change to Connected.

curl -X POST http://localhost:8080/api/tenants \
  -H "Content-Type: application/json" \
  -d '{"id": "dbms-research", "name": "dbms-research"}'

curl.exe -X POST http://localhost:8080/api/tenants `
  -H "Content-Type: application/json" `
  -d '{"id": "dbms-research", "name": "dbms-research"}'

curl -X POST http://localhost:8080/api/snapshot/import \
  -F "file=@./samyama-graph/dbms-research.sgsnap" \
  -F "tenant_id=dbms-research"

curl.exe -X POST http://localhost:8080/api/snapshot/import `
  -F "file=@C:\samyama-graph\dbms-research.sgsnap" `
  -F "tenant_id=dbms-research"

Step 8 — Stop / reset

Stop the server:

docker compose down

Reset all data (⚠️ deletes volume):

docker compose down -v

⚠️ This deletes all graph data stored in the Docker volume.

Option 2 — Build from source

System packages. zstd-sys generates its bindings with bindgen, which needs libclang. Without it the build fails part-way through with a misleading 'stddef.h' file not found.

# Debian / Ubuntu
sudo apt-get install -y build-essential cmake pkg-config libssl-dev clang libclang-dev

# Fedora / RHEL
sudo dnf install -y gcc gcc-c++ cmake pkgconf-pkg-config openssl-devel clang clang-devel

# macOS — the Xcode Command Line Tools already provide clang
xcode-select --install

Then, with a stable Rust toolchain from rustup:

# Build from source
git clone https://github.com/samyama-ai/samyama-graph && cd samyama-graph
cargo build --release
./target/release/samyama    # RESP on :6379, HTTP on :8080

# Connect with any Redis client
redis-cli -p 6379
GRAPH.QUERY mydb "CREATE (a:Person {name: 'Alice'})-[:KNOWS]->(b:Person {name: 'Bob'})"
GRAPH.QUERY mydb "MATCH (a)-[:KNOWS]->(b) RETURN a.name, b.name"

What can you build with Samyama Graph?

Samyama Graph is useful when your application needs both connected-data reasoning and semantic retrieval.

You can use it to build:

• GraphRAG systems that combine vector search with graph traversal
• Knowledge graph applications for enterprise, research, healthcare, and operations data
• AI agent memory where entities, tools, actions, and context are stored as a graph
• Biomedical and clinical graphs across papers, trials, pathways, drugs, and conditions
• Fraud and investigation graphs for relationship discovery and pattern analysis
• Infrastructure and dependency graphs for impact analysis and root-cause exploration
• Large-scale graph analytics using built-in graph algorithms

We loaded the entire PubMed corpus — every article published since 1966 — plus ClinicalTrials.gov, Reactome pathways, and DrugBank into one graph. Then we asked:

"What drugs are most tested in cancer clinical trials?"

MATCH (m:MeSHTerm)<-[:ANNOTATED_WITH]-(a:Article)
      -[:REFERENCED_IN]->(t:ClinicalTrial)-[:TESTS]->(i:Intervention)
WHERE m.name = 'Neoplasms'
RETURN i.name, count(DISTINCT t) AS trials
ORDER BY trials DESC LIMIT 5

5.2 seconds. One query. Four databases. 74 million nodes. 1 billion edges. A single machine.

See all 100 benchmark queries →

⭐ Find this useful? A GitHub star helps more developers discover Samyama Graph.

Demo

Cricket KG — 36K nodes, 1.4M edges, live graph simulation

Click for full demo (1:56)

Infrastructure failure-propagation

One query family — reachability, criticality, N-1 contingency — runs identically across infrastructure domains. Both demos use real CC BY 4.0 data.

Power Grid — IEEE 14-bus system (pglib-opf): degree centrality → connectivity → N-1 line contingency.

Telecom — GÉANT 2012 pan-European backbone (Internet Topology Zoo): 40 PoPs across 37 countries; N-1 link contingency exposes 8 single points of failure.

Case Studies — prove it yourself

case_studies/ lets anyone who clones this repo download a real public knowledge graph, import it, run showcase Cypher (and vector search), and render the session as a narrated GIF — one command, no database to install. Every showcase query is gated to return real rows before any GIF is recorded (see the Definition of Done).

cargo build --release && pip install rich requests
cd case_studies/cricket && ./run.sh          # fetch snapshot → import → validate → demo
RECORD=1 ./run.sh                            # also (re)generate demo.gif

Each snapshot is small enough to run on a laptop; every query returns real rows. GIFs can't pause in a browser, so each domain also ships its demo.cast — replay it pausably (space) with asciinema play case_studies/<domain>/demo.cast.

surveillance + health-determinants + health-systems federate by Country.iso_code into a public-health trifecta. Browse the catalogue →

Why Samyama Graph?

If your data has relationships, you need a graph database. If your graph database can't handle a billion edges on a single machine, you need Samyama.

The 30-Second Tour

Cypher queries — MATCH, CREATE, MERGE, aggregations, path finding, 30+ functions. 99.9% of the openCypher TCK's evaluated scenarios pass (3,845 of 3,847, at 98.7% coverage of the 3,897-scenario corpus, measured 2026-09-15), and neither of the two remaining failures is a wrong answer — both raise; on the same corpus and comparator Neo4j 5 scores 79.5%. That is conformance only — not performance or scale — and the competitor figure is a fixed baseline from one run. See docs/CYPHER_COMPATIBILITY.md for a per-feature matrix verified by an executable probe, and docs/BENCHMARKS.md for the full accounting.

MATCH (a:Person)-[:KNOWS*1..3]->(b:Person)
WHERE a.name = 'Alice'
RETURN b.name, length(shortestPath(a, b))

Graph algorithms — PageRank, WCC, SCC, BFS, Dijkstra, LCC, CDLP, Triangle Count. All rayon-parallelized.

CALL pagerank('social') YIELD nodeId, score
RETURN nodeId, score ORDER BY score DESC LIMIT 10

Vector search — HNSW indexing for semantic search and Graph RAG.

CREATE VECTOR INDEX paper_idx FOR (p:Paper) ON (p.embedding) OPTIONS {dimensions: 384, similarity: 'cosine'}

CALL vector.search('Paper', 'embedding', [0.1, 0.2, 0.3], 10) YIELD node, score

Natural language — Ask questions in English. The LLM translates to Cypher.

NLQ "Who are Alice's friends of friends that work at Google?"
→ MATCH (a:Person {name:'Alice'})-[:KNOWS]->()-[:KNOWS]->(fof)-[:WORKS_AT]->(c:Company {name:'Google'}) RETURN fof.name

AI agents — Auto-generated MCP servers from your graph schema.

pip install samyama[mcp]
samyama-mcp-serve --demo cricket    # Instant AI agent tools for any graph

Out to pandas — Any read query as Arrow or Parquet, straight into a dataframe, with no intermediate file.

curl -X POST http://localhost:8080/api/query/export \
  -H 'content-type: application/json' \
  -d '{"query":"MATCH (d:Doc) RETURN d.id, d.title, d.embedding","format":"parquet"}' \
  -o result.parquet

import pandas as pd
pd.read_parquet("result.parquet")

"format":"arrow" streams the Arrow IPC format instead. Column types come from the values in the result — integers stay Int64, a vector arrives as List<Float64> — and temporal values leave as ISO-8601 text, because Arrow carries one time zone per column while Cypher carries one per value.

Benchmarks

Run them: cargo bench --bench <name> (benches/). The vector, optimization, and micro/MVCC suites are self-contained; LDBC needs a data download.

HIER (benchmarks/hier/) is a category for subsumption and hierarchical roll-up over time, geography and ontology — the workload the LDBC and FinBench suites do not contain. Every query is checked against an unindexed run of the same question, so a speedup is only reported alongside an identical answer. Latest: 108/108 agree; roll-up is flat at 15–20 ns from a 1-node subtree to a 137,257-node one. Against Neo4j on an identical graph it is 94× faster across the 58 queries expressible on both, with no class losing — though without the index Samyama is 1.6× slower than Neo4j, so the index is the differentiator rather than the engine. That 94× is the ratio of the two medians over the 58 queries, which is not an average speedup and should not be read as one; the geometric mean of the per-query ratios is 88×. Both are recomputed from the committed per-query timings by CH-BENCH-HIER, measured 2026-08-14 on a host that no longer exists.

Scale: 74M Nodes, 1 Billion Edges

Loaded in 31 minutes from snapshots. 96 of 100 queries return real data across all four KGs. Full results →

Cross-KG Query Highlights

LDBC suites

Run in-tree by the conformance harness, not audited by anyone: LDBC certification is a formal third-party process and we have not been through it. Every row below is a measurement from samyama-graph-competitor-benchmarks on 2026-08-28, and the suite that produced it is named so the number can be re-derived or refuted.

One of those is not clean, and saying so is the point of publishing them: three FinBench queries are pinned to ids the generated data does not guarantee, so they answer nothing while reporting OK (#918).

Concurrent performance

Not published, because it is not measured. The numbers that stood here were added in April 2026 with no benchmark, log, host or date behind them, and no benchmark in this repository produces them (#919). An unfounded number is worse than an absent one: it invites a reader to plan around it.

CH-PERF-CONC (PERF-17 — 64 concurrent clients, p99 ≤ 3× single-client p50) is the suite that will answer this, and the figure returns here when it does.

Examples

Run them all in one command: ./scripts/run_all_examples.sh --batch builds every example, starts a server, and runs each in turn with a pass/fail summary (the orchestrator for the examples/ directory).

Domain Knowledge Graphs

19 demo examples + 11 data loaders in examples/; optimization/use-case demos: grid_dispatch_demo, amr_stewardship_demo, healthcare_allocation_demo, wildfire_evac_demo, pca_demo, sdk_demo, …

Data Loaders

Related Repositories

samyama-graph is the engine. Per-domain KGs and companion projects live separately and can be loaded into it:

• KGs: pubmed-kg (66M / 1B), clinicaltrials-kg (7.8M / 27M), druginteractions-kg (245K / 388K), pathways-kg (119K / 835K), cricket-kg (36K / 1.4M), imdb-kg (1.94M / 2.63M), football-kg (16K / 12K), assetops-kg (13K / 13K), powergrid-kg (pglib-opf — infrastructure), telecom-kg (Internet Topology Zoo — infrastructure)
• Benchmarks: biomedqa — 40-question pharmacology benchmark across three KGs
• Companions: graphrag-rs — doc-to-KG + MCP server; optimization_algorithms — PyPI rao-algorithms package (PyO3 bindings over crates/samyama-optimization/)

Architecture

samyama
├── graph/         Property graph model (Node, Edge, GraphStore, CSR adjacency)
├── query/         OpenCypher engine
│   ├── cypher.pest    PEG grammar
│   ├── executor/      Volcano iterator + WCO LeapFrog TrieJoin
│   └── planner.rs     Cost-based graph-native query planner
├── protocol/      RESP3 server (Redis-compatible, Tokio async)
├── persistence/   RocksDB + WAL + multi-tenancy
├── vector/        HNSW vector index
├── snapshot/      Portable .sgsnap v2 (CSR + ColumnStore)
├── raft/          Distributed consensus (openraft)
└── nlq/           Natural language → Cypher (OpenAI, Gemini, Ollama, Claude)

Companion crates:

• samyama-graph-algorithms — PageRank, BFS, Dijkstra, WCC, SCC, LCC, CDLP, Triangle Count (all rayon-parallelized)
• samyama-optimization — 15+ metaheuristic solvers (Jaya, Rao, GWO, NSGA-II, TLBO)
• samyama-sdk — Rust SDK with embedded and remote clients

Documentation

Enterprise Edition

Everything above is open source (Apache 2.0). Samyama Enterprise adds:

• GPU acceleration (wgpu + CUDA)
• OpenTelemetry OTLP metrics
• Prometheus + Grafana monitoring
• Backup & disaster recovery
• ADMIN commands + audit trail
• Ed25519 signed license tokens

Contact us →

Contributing

Contributions are welcome — bug reports, docs, tests, and code. See CONTRIBUTING.md for development setup, build/test commands, and the pull request workflow. Good first areas are listed there.

• 🐛 Found a bug or have an idea? Open an issue.
• 💬 Questions or general discussion? Join the community chat.

License

Apache License 2.0 — use it in production, contribute back if you'd like.

Samyama (Sanskrit: संयम) — the union of focused query, sustained analysis, and unified insight.