NornicDB

The Graph Database That Learns
Neo4j-compatible • GPU-accelerated • Memory that evolves

Quick Start • What It Is • Why NornicDB • Benchmarks • Features • Docs • Comparison • Contributors

Try It With One Command

# arm64 / Apple Silicon
docker run -d --name nornicdb -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data timothyswt/nornicdb-arm64-metal-bge:latest

# amd64 / CPU only
docker run -d --name nornicdb -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data timothyswt/nornicdb-amd64-cpu-bge:latest

Open http://localhost:7474 for the admin UI. For NVIDIA CUDA hosts, use timothyswt/nornicdb-amd64-cuda-bge:latest. For Vulkan hosts, use timothyswt/nornicdb-amd64-vulkan-bge:latest.

---

What NornicDB Is

NornicDB is a graph database for workloads that need graph traversal, vector retrieval, and historical truth in the same system. It speaks Neo4j's language through Bolt and Cypher, exposes REST, GraphQL, and gRPC interfaces, and can preserve Qdrant-style client workflows where that helps migration.

It is built for knowledge systems, agent memory, Graph-RAG, and canonical truth stores where semantic search is only part of the query. The design goal is not to bolt a vector store onto a graph database. The design goal is one execution path for graph, vector, temporal, and audit-oriented workloads.

Why NornicDB Is Different

• Neo4j-compatible by default: Bolt + Cypher support for existing drivers and applications.
• Built for AI-native workloads: vector search, memory decay, and auto-relationships are first-class features.
• Graph, vector, and ledger semantics in one engine: hybrid retrieval, graph traversal, canonical graph ledger modeling, tritemporal facts, as-of reads, txlog queries, and receipts do not require a second database.
• Protocol flexibility without splitting the system: REST, GraphQL, Bolt/Cypher, Qdrant-compatible gRPC, and additive Nornic gRPC live on the same platform.
• Hardware-accelerated execution: Metal/CUDA/Vulkan pathways for high-throughput graph + semantic workloads.
• Operational flexibility: full images (models included), BYOM images, and headless API-only deployments.

Transactional Guarantees & Isolation

NornicDB implements Snapshot Isolation at the storage layer. Each transaction is anchored to a specific MVCC version, so point reads, label scans, and snapshot-visible graph traversals resolve against the same committed view of the graph.

• Repeatable reads within a transaction: transactions see their own buffered writes, but not commits that land after their read snapshot.
• Conflict detection at commit: concurrent graph mutations against the same logical state fail with a normalized ErrConflict instead of silently overwriting newer data.
• Explicit historical reads: MVCC pruning preserves the current head and a retained floor per logical key; requests below that retained floor fail safely with ErrNotFound.
• Search remains current-state focused: current search paths are intentionally separate from historical MVCC state.

See transaction implementation details, historical reads and MVCC retention, and the canonical graph ledger guide.

What Recent Deep-Dives Show

• Hybrid execution model (streaming fast paths + general engine): NornicDB uses shape-specialized streaming executors for common traversal/aggregation patterns while retaining a general Cypher path for coverage and correctness.
• Runtime parser mode switching: the default nornic parser is optimized for low-overhead hot-path routing, while antlr mode prioritizes strict parsing and diagnostics when debugging and validation matter more than throughput.
• Measured parser-path deltas on benchmark suites: internal Northwind comparisons show large overhead differences on certain query shapes when full parse-tree paths are used, which is why the production default remains the custom parser path.
• HNSW build acceleration from insertion-order optimization: BM25-seeded insertion order reduced a 1M embedding build from ~27 minutes to ~10 minutes (~2.7x) in published tests by reducing traversal waste during construction, without changing core quality knobs.
• Shared seed strategy across indexing stages: the same lexical seed extraction supports HNSW insertion ordering and improves k-means centroid initialization spread for vector pipeline efficiency.

Read more:

• Cypher parser modes and execution trade-offs
• How we sped up HNSW construction 2.7x

Performance Snapshot

LDBC Social Network Benchmark (M3 Max, 64GB):

Query Type	NornicDB	Neo4j	Speedup
Message content lookup	6,389 ops/sec	518 ops/sec	12x
Recent messages (friends)	2,769 ops/sec	108 ops/sec	25x
Avg friends per city	4,713 ops/sec	91 ops/sec	52x
Tag co-occurrence	2,076 ops/sec	65 ops/sec	32x

See full benchmark results for complete methodology and additional workloads.

Hybrid Retrieval Benchmarks

Hybrid retrieval is where NornicDB is materially different from vector-only stacks: the query shape is vector search followed by graph expansion in the same engine.

Local benchmark (67,280 nodes, 40,921 edges, 67,298 embeddings, HNSW CPU-only index):

Workload	Transport	Throughput	Mean	P50	P95	P99	Max
Vector only	HTTP	14,950 req/s	663 us	627 us	969 us	2.18 ms	2.73 ms
Vector only	Bolt	8,802 req/s	1.13 ms	983 us	1.77 ms	4.50 ms	5.15 ms
Vector + 1 hop	HTTP	11,523 req/s	859 us	699 us	1.54 ms	3.46 ms	4.71 ms
Vector + 1 hop	Bolt	7,977 req/s	1.24 ms	1.10 ms	1.97 ms	4.91 ms	6.14 ms

Remote benchmark (GCP, 8 vCPU, 32 GB RAM):

• Vector only: ~110.7 ms P50
• Vector + 1 hop: ~112.9 ms P50
• The delta between local and remote matched network RTT closely enough that end-to-end latency was network-bound rather than compute-bound.

This is the practical point: once vector search plus one-hop traversal stays in low single-digit milliseconds locally, the bottleneck shifts from retrieval logic to deployment topology.

See the hybrid retrieval benchmark write-up for methodology, caveats, and reproduction queries, and see Graph-RAG: NornicDB vs Typical for the architectural implications.

Quick Start

Docker (Recommended)

# Apple Silicon (includes bge-m3 embedding model)
docker run -d --name nornicdb \
  -p 7474:7474 -p 7687:7687 \
  -v nornicdb-data:/data \
  timothyswt/nornicdb-arm64-metal-bge:latest  # Apple Silicon
  # timothyswt/nornicdb-amd64-cuda-bge:latest  # NVIDIA GPU

Open http://localhost:7474 for the admin UI.

Need a different image/profile (Heimdall, BYOM, CPU-only, Vulkan, headless)?

• Docker image quick reference
• Docker images section
• Quick start guide

From Source

git clone https://github.com/orneryd/NornicDB.git
cd NornicDB
go build -o nornicdb ./cmd/nornicdb
./nornicdb serve

Connect

Use any Neo4j driver — Python, JavaScript, Go, Java, .NET:

from neo4j import GraphDatabase

driver = GraphDatabase.driver("bolt://localhost:7687")
with driver.session() as session:
    session.run("CREATE (n:Memory {content: 'Hello NornicDB'})")

Why Switch from Neo4j?

• 12x-52x faster on published LDBC workloads (same hardware comparisons).
• Native graph + vector in one engine (no separate vector sidecar required).
• GPU acceleration paths (Metal/CUDA/Vulkan) for semantic + graph workloads.
• Drop-in compatibility via Bolt + Cypher for existing applications.
• Canonical graph ledger model for temporal validity, tritemporal fact modeling, as-of reads, and audit-oriented mutation tracking.

Why Switch from Qdrant?

• Graph + vector in one engine: combine semantic retrieval with native graph traversal and Cypher queries.
• Qdrant gRPC compatibility preserved: keep Qdrant-style gRPC workflows while adding graph-native capabilities.
• Hybrid retrieval built in: vector + BM25 fusion and optional reranking in the same query pipeline.
• Canonical truth modeling: versioned facts, temporal validity windows, tritemporal facts, and as-of reads for governance-heavy use cases.
• Protocol flexibility: use REST, GraphQL, Bolt/Cypher, Qdrant-compatible gRPC, and additive Nornic gRPC on one platform.

Features

🔌 Neo4j Compatible

Drop-in replacement for Neo4j. Your existing code works unchanged.

• Bolt Protocol — Use official Neo4j drivers
• Cypher Queries — Full query language support
• Schema Management — Constraints, indexes, vector indexes
• Qdrant gRPC API Compatible — Works with Qdrant-style gRPC vector workflows

🧠 Intelligent Memory

Memory that behaves like human cognition.

Memory Tier	Half-Life	Use Case
Episodic	7 days	Chat context, sessions
Semantic	69 days	Facts, decisions
Procedural	693 days	Skills, patterns

// Find memories that are still strong
MATCH (m:Memory) WHERE m.decayScore > 0.5
RETURN m.title ORDER BY m.decayScore DESC

🔗 Auto-Relationships

NornicDB weaves connections automatically:

• Embedding Similarity — Related concepts link together
• Co-access Patterns — Frequently queried pairs connect
• Temporal Proximity — Same-session nodes associate
• Transitive Inference — A→B + B→C suggests A→C

🎯 Vector Search

Native semantic search with GPU acceleration and hybrid retrieval support.

📖 Deep dive: Vector Search Guide and Qdrant gRPC Endpoint.

Cypher (Neo4j-compatible):

CALL db.index.vector.queryNodes('embeddings', 10, 'machine learning guide')
YIELD node, score
RETURN node.content, score

Hybrid search (REST):

curl -X POST http://localhost:7474/nornicdb/search \
  -H "Content-Type: application/json" \
  -d '{"query": "machine learning", "limit": 10}'

More API entry points:

• GraphQL hybrid search: POST /graphql with search(query, options)
• gRPC (Qdrant-compatible): Points.Search / Points.Query(Document.text)
• Nornic native gRPC: NornicSearch/SearchText (additive client)
• See docs/user-guides/nornic-search-grpc.md for additive proto setup without forking Qdrant drivers.

🤖 Heimdall AI Assistant

Built-in AI that understands your database.

# Enable Heimdall
NORNICDB_HEIMDALL_ENABLED=true ./nornicdb serve

Natural Language Queries:

• "Get the database status"
• "Show me system metrics"
• "Run health check"

Plugin System:

• Create custom actions the AI can execute
• Lifecycle hooks (PrePrompt, PreExecute, PostExecute)
• Database event monitoring for autonomous actions
• Inline notifications with proper ordering

See Heimdall AI Assistant Guide and Plugin Development.

🧩 APOC Functions

950+ built-in functions for text, math, collections, and more. Plus a plugin system for custom extensions.

// Text processing
RETURN apoc.text.camelCase('hello world')  // "helloWorld"
RETURN apoc.text.slugify('Hello World!')   // "hello-world"

// Machine learning
RETURN apoc.ml.sigmoid(0)                  // 0.5
RETURN apoc.ml.cosineSimilarity([1,0], [0,1])  // 0.0

// Collections
RETURN apoc.coll.sum([1, 2, 3, 4, 5])      // 15

Drop custom .so plugins into /app/plugins/ for automatic loading. See the APOC Plugin Guide.

Docker Images

All images available at Docker Hub.

ARM64 (Apple Silicon)

Image	Size	Description
timothyswt/nornicdb-arm64-metal-bge-heimdall	1.1 GB	Full - Embeddings + AI Assistant
timothyswt/nornicdb-arm64-metal-bge	586 MB	Standard - With BGE-M3 embeddings
timothyswt/nornicdb-arm64-metal	148 MB	Minimal - Core database, BYOM
timothyswt/nornicdb-arm64-metal-headless	148 MB	Headless - API only, no UI

AMD64 (Linux/Intel)

Image	Size	Description
timothyswt/nornicdb-amd64-cuda-bge	~4.5 GB	GPU + Embeddings - CUDA + BGE-M3
timothyswt/nornicdb-amd64-cuda	~3 GB	GPU - CUDA acceleration, BYOM
timothyswt/nornicdb-amd64-cuda-headless	~2.9 GB	GPU Headless - API only
timothyswt/nornicdb-amd64-cpu	~500 MB	CPU - No GPU required
timothyswt/nornicdb-amd64-cpu-headless	~500 MB	CPU Headless - API only

BYOM = Bring Your Own Model (mount at /app/models)

# With your own model
docker run -d -p 7474:7474 -p 7687:7687 \
  -v /path/to/models:/app/models \
  timothyswt/nornicdb-arm64-metal:latest

# Headless mode (API only, no web UI)
docker run -d -p 7474:7474 -p 7687:7687 \
  -v nornicdb-data:/data \
  timothyswt/nornicdb-arm64-metal-headless:latest

Headless Mode

For embedded deployments, microservices, or API-only use cases, NornicDB supports headless mode which disables the web UI for a smaller binary and reduced attack surface.

Runtime flag:

nornicdb serve --headless

Environment variable:

NORNICDB_HEADLESS=true nornicdb serve

Build without UI (smaller binary):

# Native build
make build-headless

# Docker build
docker build --build-arg HEADLESS=true -f docker/Dockerfile.arm64-metal .

Configuration

# nornicdb.yaml
server:
  bolt_port: 7687
  http_port: 7474
  host: localhost

database:
  data_dir: ./data
  async_writes_enabled: true
  async_flush_interval: 50ms
  async_max_node_cache_size: 50000
  async_max_edge_cache_size: 100000

embedding:
  enabled: true
  provider: local # or ollama, openai
  model: bge-m3.gguf
  url: ""
  dimensions: 1024

embedding_worker:
  chunk_size: 8192
  chunk_overlap: 50

memory:
  decay_enabled: true
  decay_interval: 1h
  auto_links_enabled: true
  auto_links_similarity_threshold: 0.82

Use Cases

• AI Agent Memory — Persistent, queryable memory for LLM agents
• Knowledge Graphs — Auto-organizing knowledge bases
• RAG Systems — Vector + graph retrieval in one database
• Graph-RAG for LLM Inference — Simplify retrieval pipelines by combining graph traversal, hybrid search, and provenance in one engine
• Session Context — Decaying conversation history
• Research Tools — Connect papers, notes, and insights
• Canonical Truth Stores — Versioned facts, temporal validity, and append-only mutation history in a graph model
• Financial Systems — Loan/risk state reconstruction with as-of reads and audit receipts
• Compliance & RegTech — KYC/AML state changes, policy/rule versioning, and non-overlapping validity enforcement
• Audit Platforms — Correlate graph mutations to WAL sequence ranges and receipt hashes
• AI Governance & Lineage — Track model assertions, overrides, and fact provenance over time

Documentation

Start with the docs hub for role/task navigation, then use the issue index for symptom-first troubleshooting:

• Documentation Hub
• Issue Index

Guide	Description
Getting Started	Installation & quick start
Docker Image Quick Reference	Full runtime image matrix
API Reference	Cypher functions & procedures
User Guides	Complete examples & patterns
Performance	Benchmarks vs Neo4j
Neo4j Migration	Compatibility & feature parity
Architecture	System design & internals
Docker Guide	Build & deployment
Development	Contributing & development

Additional deep dives referenced above:

• Hybrid query benchmarks
• Canonical graph ledger
• Historical reads and MVCC retention
• Cypher parser modes

Star History

Comparison

Platform	Category	Query Language Support (and protocol)	Native Vector Search	Canonical Graph + Temporal Ledger Pattern	Queryable Mutation Log + Receipts	Embedded/Self-Hosted Focus
NornicDB	Graph + Vector + Canonical Ledger	Cypher via Bolt; also HTTP/GraphQL and gRPC (Qdrant-compatible + NornicSearch)	Yes	Yes	Yes	Yes
Neo4j	Graph DB	Cypher via Bolt/HTTP	Yes	Partial (manual modeling)	Partial (logs exist, not first-class receipts model)	Server-first
Memgraph	Graph DB	openCypher via Bolt/HTTP	Partial/varies by setup	Partial (manual)	Partial (manual/integration)	Server-first
TigerGraph	Graph analytics DB	GSQL via REST++/native endpoints	Partial/extension-driven	Partial (manual)	Partial (manual/integration)	Server-first
Qdrant	Vector DB	Qdrant query/filter API via gRPC/REST	Yes	No (not graph-native)	No	Server-first
Weaviate	Vector DB	GraphQL + REST APIs	Yes	Partial (knowledge graph features, not Cypher property graph)	No	Server-first
Amazon QLDB	Ledger DB	PartiQL via AWS API/SDK	No	Partial (ledger + temporal history, not graph-native)	Yes (ledger-native)	Managed service

Snapshot is capability-oriented and high-level; exact behavior depends on edition/configuration and workload design.

Building

Native Binary

# Basic build
make build

# Headless (no UI)
make build-headless

# With local LLM support
make build-localllm

Docker Images

# Download models for Heimdall builds (automatic if missing)
make download-models        # BGE-M3 + qwen3-0.6b (~750MB)
make check-models          # Verify models present

# ARM64 (Apple Silicon)
make build-arm64-metal                  # Base (BYOM)
make build-arm64-metal-bge              # With BGE embeddings
make build-arm64-metal-bge-heimdall     # With BGE + Heimdall AI
make build-arm64-metal-headless         # Headless (no UI)

# AMD64 CUDA (NVIDIA GPU)
make build-amd64-cuda                   # Base (BYOM)
make build-amd64-cuda-bge               # With BGE embeddings
make build-amd64-cuda-bge-heimdall      # With BGE + Heimdall AI
make build-amd64-cuda-headless          # Headless (no UI)

# AMD64 CPU-only
make build-amd64-cpu                    # Minimal
make build-amd64-cpu-headless           # Minimal headless

# Build all variants for your architecture
make build-all

# Deploy to registry
make deploy-all             # Build + push all variants

Cross-Compilation

# Build for other platforms from macOS
make cross-linux-amd64     # Linux x86_64
make cross-linux-arm64     # Linux ARM64
make cross-rpi             # Raspberry Pi 4/5
make cross-windows         # Windows (CPU-only)
make cross-all             # All platforms

Roadmap

Completed

• Neo4j Bolt protocol
• Cypher query engine (52 functions)
• Memory decay system
• GPU acceleration (Metal, CUDA)
• Vector & full-text search
• Auto-relationship engine
• HNSW vector index
• Metadata/Property Indexing
• SIMD Implementation
• Clustering support
• Sharding (Composite DB + Remote Constituents)
• Data Explorer UI (Browser query editor, semantic search, node details)

Planned (from docs/plans)

• GPU-assisted HNSW construction with CPU-serving persistence parity (docs/plans/gpu-hnsw-construction-plan.md)
• Neo4j-compatible end-to-end streaming execution + wrapper driver/ORM (docs/plans/neo4j-compatible-streaming-driver-and-server-plan.md)
• GDPR compliance hardening: user-data detection, relationship export/delete/anonymization, and audit-log coverage (docs/plans/gdpr-compliance-fixes.md)
• UI enhancement backlog (search/config/admin UX improvements) (docs/plans/ui-enhancements.md)

Contributors

Special thanks to everyone who helps make NornicDB better. See CONTRIBUTORS.md for a list of community contributors.

License

MIT License — Originally part of the Mimir project, now maintained as a standalone repository.

Patent rights are handled via a defensive non-assertion grant in PATENTS.md. This keeps the project open for broad use (including commercial use) while adding patent retaliation protection.

See NOTICES.md for third-party license information, including bundled AI models (BGE-M3, Qwen2.5) and dependencies.

---

Weaving your data's destiny