NornicDB README

NornicDB

Graph, vector, and historical truth in one database
Neo4j-compatible • Hybrid graph + vector retrieval • Historical reads via MVCC
Achieving Psygnosis for AI

Multi-arch support: CPU | CUDA | Metal | Vulkan

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

Quick Start

# Homebrew
brew tap orneryd/nornicdb && brew install nornicdb && brew services start nornicdb

# 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.

Note: Docker on macOS does not expose Metal acceleration. The Apple Silicon image still runs, but GPU acceleration on macOS requires a native install from the releases page or a local build.

Writing queries? Start with the Hot-Path Cypher Cookbook — proven query shapes that route through the executor's specialized fast paths.

🤖 Building with Claude / agents? The docs/skills/ directory contains agent-ready skill files for every Cypher surface: query shapes, decay/promotion policies, managed embeddings, vector & hybrid search, and RAG procedures. Drop them into .claude/skills/ to make agents fluent in NornicDB.

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.

The architecture draws from research in Temporal GraphRAG, agent memory systems, event-sourced decision memory, and persistence semantics for AI agents. These ideas appear in NornicDB as graph-native support for temporal facts, canonical knowledge versioning, replayable history, policy-driven memory retention, and audit-friendly retrieval.

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.

Deployment Patterns

NornicDB is being used in internal production deployments for stack-consolidation workloads where graph traversal, vector retrieval, and auditability need to live in the same system.

• Agent and Graph-RAG systems: replacing a Neo4j + Qdrant + embeddings stack with a single deployment for task tracking, dependency graphs, and retrieval pipelines.
• Translation and evaluation workflows: replacing a document store plus embeddings pipeline with a single deployment for graph-native retrieval and faster aggregation paths.

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.

Performance Snapshot

Northwind benchmark (48,000 products and 48,000 orders; 30 measured iterations per query after 5 warmups):

All seed counts and per-query result fingerprints matched between NornicDB and Neo4j. See the full Northwind benchmark report for per-query latency, correctness, power, memory, and storage results.

BEIR Retrieval Quality

The reproducible BEIR SciFact evaluation uses the official 300-query test qrels. With exact hybrid RRF retrieval and the native BGE-M3 reranker, NornicDB recorded:

These scores are configuration-specific rather than an official leaderboard placement. See the BEIR retrieval benchmark for the protocol, baselines, confidence intervals, and published-reference context.

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

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 point is: 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.

🔬 Academic Validation: UCLouvain Case Study

NornicDB is currently being utilized by researchers at UCLouvain to map large-scale Cyber-Physical Systems (CPS).

In benchmarks performing Automata Learning (L*)—a high-iteration logic process where an LLM acts as a "Deterministic Teacher" or Oracle—NornicDB outperformed industry-standard graph databases by a significant margin:

• Efficiency: 2.2x Faster than Neo4j in total execution time for formal logic mapping.
• Throughput: Successfully handled 1,443 state-transition queries in ~32 seconds (Avg 22.69ms per full reasoning loop).

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.
• Scannerless recursive-descent (SRD) parser by default: the nornic parser scans the raw query text with no lexer and no parse tree — clause boundaries and precedence are found by scanning for top-level keywords and operators — so hot-path routing is allocation-free. The antlr parser remains for strict parsing and diagnostics.
• Shared Cypher 5 / 25 grammar: LET, FILTER, and FOR reading clauses execute in the existing pipeline with an optional CYPHER 5 / CYPHER 25 header. The SRD parser accepts them without a header; the ANTLR parser requires CYPHER 25 for them and parses the header itself.
• 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

More Setup Options

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?

• 99.8% lower overall mean query latency on the current 48k-product / 48k-order Northwind comparison (413.40x ratio), with matching result fingerprints.
• Measured retrieval quality on the official 300-query BEIR SciFact test set, including 0.72292 nDCG@10 with native BGE-M3 reranking.
• 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.

🚚 Migrating? Neo4j → NornicDB skill · runnable Python/Go/Node scripts in scripts/migration/neo4j/.

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.

🚚 Migrating? Qdrant → NornicDB skill · gRPC surface skill · runnable Python/Go/Node scripts in scripts/migration/qdrant/.

Features

Retention Policies

Retention policy enforcement is available, but it is disabled by default and must be explicitly enabled. When retention is off, NornicDB does not create the retention manager and does not start the retention sweep background worker. When enabled, retention supports label-aware policy evaluation, legal holds, GDPR erasure tracking, and admin APIs.

See Retention Policies and Configuration.

🔌 Neo4j Compatible

Designed to work with existing Neo4j drivers and Bolt/Cypher workflows, with minimal or no application changes for supported query shapes.

• Bolt Protocol — Use official Neo4j drivers
• Cypher Queries — Full query language support
• Cypher 25 — LET, FILTER and FOR reading clauses with the optional CYPHER 5 / CYPHER 25 header
• Schema Management — Constraints, indexes (single- and multi-property), vector indexes
• Qdrant gRPC API Compatible — Works with Qdrant-style gRPC vector workflows

🤖 Agent skill: Bolt Client — connection defaults, retry classification, MERGE under concurrent writers, batch sizing.

🧠 Knowledge-Layer Scoring

Profile-driven decay and promotion scoring with the Ebbinghaus-Roynard four-layer decomposition. The engine does not hardcode cognitive tiers. Operators model their own labels and lifecycle rules using Cypher DDL.

Typical deployments map the four-layer decomposition onto labels such as:

• Knowledge: durable fact labels using NO DECAY or neutral profiles
• Memory: episodic/session labels using bounded half-life decay
• Wisdom: stable directive labels using conservative decay plus promotion rules
• Evidence/links: edge types with their own decay and suppression behavior

Those categories are conventions, not built-in engine classes. NornicDB provides the authoring and diagnostics surface:

• CREATE/ALTER/DROP/SHOW DECAY PROFILE
• CREATE/ALTER/DROP/SHOW PROMOTION PROFILE
• CREATE/ALTER/DROP/SHOW PROMOTION POLICY
• decayScore(entity), decay(entity), policy(entity), reveal(entity)
• CALL kp.info|profiles|policies|resolve|deindexStatus()

CREATE DECAY PROFILE working_memory OPTIONS {
  halfLifeSeconds: 604800,
  function: 'exponential',
  visibilityThreshold: 0.10
}

CREATE DECAY PROFILE session_retention
FOR (n:SessionRecord)
APPLY {
  DECAY PROFILE 'working_memory'
  n.tenantId NO DECAY
}

MATCH (n:SessionRecord) WHERE decayScore(n) > 0.5
RETURN n ORDER BY decayScore(n) DESC

📖 Deep dive: Knowledge-Layer Policies, Decay Profiles, Promotion Policies, and Ebbinghaus-Roynard Bootstrap.

🤖 Agent skills: Knowledge Policies · Decay Tuning · Promotion Policies

🔗 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.

🤖 Agent skills: Vector & Full-Text Search · Managed Embeddings · RAG Procedures

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 server-only use cases, NornicDB supports headless mode, which disables embedded UI assets, SPA/bootstrap routes, and browser IDEs while keeping core APIs available.

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

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
• Configurable RBAC and oAuth support
• Cypher query engine (52 functions)
• Cypher 25 shared grammar foundation — LET, FILTER, FOR reading clauses and the CYPHER 5 / CYPHER 25 header
• Correctly-rounded math — musl libm ports for exp/log/pow and trigonometry
• MCP database pinning — /mcp/{database} targets one database for every tool call
• Memory decay system
• GPU acceleration (Metal, CUDA)
• Vector & full-text search
• Auto-relationship engine
• HNSW vector index
• Metadata/Property Indexing (single- and multi-property)
• SIMD Implementation
• Clustering support
• Sharding (Composite DB + Remote Constituents)
• Data Explorer UI (Browser query editor, semantic search, node details)
• GDPR Compliance
• per-DB Search Index Overrides for BM2 and HNSW as independently levers for deferred or skipped construction (docs/plans/okf-admin-import-export-plan.md)
• Bulk Import Tool
• Cross-platform GPU-assisted HNSW construction with CPU-serving persistence parity (docs/plans/archive/gpu-hnsw-construction-plan.md)
• Production message localization (message catalog, all core phases complete) ()

Planned (from docs/plans)

• Neo4j-compatible end-to-end streaming execution + wrapper driver/ORM (docs/plans/neo4j-compatible-streaming-driver-and-server-plan.md)
• UI enhancement backlog (search/config/admin UX improvements) (docs/plans/ui-enhancements.md)
• Fine-grained RBAC: security administration commands and graph privileges, including property-based rules (#935)
• User impersonation: IMPERSONATE privilege and Bolt imp_user (#936)
• Change Data Capture: txLogEnrichment, db.cdc.* procedures and change events (#937)
• Query API v2 (typed JSON transactions, bookmarks, impersonated user)
• Full Cypher 25 conformance beyond the shared grammar foundation (docs/plans/cypher-convergence-plan.md)

Contributors

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

License

MIT License — See LICENSE.md for details.

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.

Psygnosis is a play on words or portmanteau meaning “mind" + "knowledge” in greek