NornicDB

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.

Production Deployment Patterns

NornicDB is currently in production at a Fortune 100 company (awaiting legal approval to say who). The current deployment patterns are not theoretical migration slides; they are active stack consolidation projects.

• Parallel workload systems: replacing a Neo4j + Qdrant + OpenAI stack with a single Docker deployment to manage and track tasks and dependencies of LLM swarms and automated graph-rag retreival pipleines and the pipelines themselves. Performance timing varies on application structure and load. However, distribution is broad enough that I am actively and reliably hitting edge cases in production to cover those cases and hit a broad bradth of queries-in-production.
• LLM translation quality systems: replacing a Mongo Atlas plus Azure embeddings pipeline stack with a single Docker deployment to improve the quality and speed of LLM-generated translations. (Mongo Atlas aggregation queries replaced with node labels + edges dropping vector search + aggregation query time from ~1s to ~1.6ms)

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):

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):

Bolt is now ahead on both throughput and tail latency for this vector-only path.

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.

// 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)

AMD64 (Linux/Intel)

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:

• Public documentation site: https://orneryd.github.io/NornicDB/
• Documentation Hub
• Issue Index

Additional deep dives referenced above:

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

Star History

Comparison

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.