NornicDB

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

🐳 Get Started in 30 Seconds

# Apple Silicon (M1/M2/M3) with bge-m3 embedding model + heimdall
docker pull timothyswt/nornicdb-arm64-metal-bge-heimdall:latest
docker run -d -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data \
  timothyswt/nornicdb-arm64-metal-bge-heimdall


# Apple Silicon (M1/M2/M3) with bge-m3 embedding model
docker pull timothyswt/nornicdb-arm64-metal-bge:latest
docker run -d -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data \
  timothyswt/nornicdb-arm64-metal-bge

# Apple Silicon (M1/M2/M3) BYOM
docker pull timothyswt/nornicdb-arm64-metal:latest
docker run -d -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data \
  timothyswt/nornicdb-arm64-metal

# Apple Silicon (M1/M2/M3) BYOM + no UI 
docker pull timothyswt/nornicdb-arm64-metal-headless:latest
docker run -d -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data \
  timothyswt/nornicdb-arm64-headless

# NVIDIA GPU (Windows/Linux) with bge-m3 embedding model + heimdall
docker pull timothyswt/nornicdb-amd64-cuda-bge-heimdall:latest
docker run --gpus all -d -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data \
  timothyswt/nornicdb-amd64-cuda-bge-heimdall

# NVIDIA GPU (Windows/Linux) with bge-m3 embedding model
docker pull timothyswt/nornicdb-amd64-cuda-bge:latest
docker run --gpus all -d --gpus all -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data \
  timothyswt/nornicdb-amd64-cuda-bge

# NVIDIA GPU (Windows/Linux) BYOM
docker pull timothyswt/nornicdb-amd64-cuda:latest
docker run --gpus all -d --gpus all -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data \
  timothyswt/nornicdb-amd64-cuda

# CPU Only (Windows/Linux) BYOM
docker pull timothyswt/nornicdb-amd64-cpu:latest
docker run -d -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data \
  timothyswt/nornicdb-amd64-cpu

# CPU Only (Windows/Linux) BYOM + no UI
docker pull timothyswt/nornicdb-amd64-headless:latest
docker run -d --gpus all -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data \
  timothyswt/nornicdb-amd64-cpu-headless

docker pull timothyswt/nornicdb-amd64-vulkan:latest
docker run --gpus all -d -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data \
  timothyswt/nornicdb-amd64-vulkan:latest

docker pull timothyswt/nornicdb-amd64-vulkan-bge:latest
docker run --gpus all -d -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data \
  timothyswt/nornicdb-amd64-vulkan-bge:latest

docker pull timothyswt/nornicdb-amd64-vulkan-headless:latest
docker run --gpus all -d -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data \
  timothyswt/nornicdb-amd64-vulkan-headless:latest

Open http://localhost:7474 — Admin UI with AI assistant ready to query your data.

Build It Yourself! — NornicDB

Below are copy-pastable commands and prerequisites to build NornicDB for the supported targets (Docker images, local binaries, cross-compiles and Raspberry Pi). These instructions reflect the Makefile targets in this repository.

Prerequisites

Go 1.23+ (for builds and cross-compilation)
Docker (for image builds)
curl (for model downloads)
GNU make
For localllm / BGE (local embeddings): a working llama.cpp build — see scripts/build-llama.sh
For CUDA builds on Linux/Windows: NVIDIA drivers + CUDA Toolkit (12.x recommended)
For Vulkan builds on Linux: Vulkan runtime & drivers for your GPU (AMD/NVIDIA/Intel)
On macOS (Apple Silicon): Docker + --platform linux/arm64 is used for arm64 images (Metal GPU acceleration implemented in the image)
Optional: gh CLI if you want to create GitHub releases

Model files:

BGE: models/bge-m3.gguf (Makefile target make download-bge will download it)
Qwen: models/qwen2.5-0.5b-instruct.gguf (Makefile target make download-qwen will download it)

Common Make flags

Force no cache: NO_CACHE=1
Set registry (default timothyswt): REGISTRY=yourdockerid
Set tag version (default latest): VERSION=1.0.6

DIY INSTRUCTIONS

What is NornicDB?

NornicDB is a high-performance graph database designed for AI agents and knowledge systems. It speaks Neo4j's language (Bolt protocol + Cypher) so you can switch with zero code changes, while adding intelligent features that traditional databases lack.

NornicDB automatically discovers and manages relationships in your data, weaving connections that let meaning emerge from your knowledge graph.

Quick Start

Docker (Recommended)

# Ready to go - includes 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

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'})")

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

🧠 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

⚡ Performance

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

Northwind Benchmark (M3 Max vs Neo4j, same hardware):

Operation	NornicDB	Neo4j	Speedup
Index lookup	7,623 ops/sec	2,143 ops/sec	3.6x
Count nodes	5,253 ops/sec	798 ops/sec	6.6x
Write: node	5,578 ops/sec	1,690 ops/sec	3.3x
Write: edge	6,626 ops/sec	1,611 ops/sec	4.1x

Cross-Platform (CUDA on Windows i9-9900KF + RTX 2080 Ti):

Operation	Throughput
Orders by customer	4,252 ops/sec
Products out of stock	4,174 ops/sec
Find category	4,071 ops/sec

Additional advantages:

Memory footprint: 100-500 MB vs 1-4 GB for Neo4j
Cold start: <1s vs 10-30s for Neo4j

See full benchmark results for detailed comparisons.

🎯 Vector Search

Native semantic search with GPU acceleration. NornicDB automatically indexes all node embeddings - no manual index creation required.

📖 Deep Dive: See Vector Search Guide for internal index architecture, user-defined indexes, and the embedding lookup order.

Option 1: Vector Array (Neo4j Compatible)

Provide your own embeddings - works identically to Neo4j:

// Query with a pre-computed embedding vector
CALL db.index.vector.queryNodes(
  'embeddings',            // Index name (created via createNodeIndex)
  10,                      // Number of results
  [0.1, 0.2, 0.3, ...]     // Your query vector
) YIELD node, score
RETURN node.content, score

Option 2: String Query (NornicDB Enhanced)

Let NornicDB handle embedding generation automatically:

// Query with natural language - NornicDB generates the embedding
CALL db.index.vector.queryNodes(
  'embeddings',              // Index name
  10,                        // Number of results
  'machine learning guide'   // Natural language query (auto-embedded)
) YIELD node, score
RETURN node.content, score

💡 Note: String queries require an embedder to be configured. When enabled, NornicDB automatically generates embeddings server-side using the configured model (Ollama, OpenAI, or local GGUF).

Option 3: REST API (Hybrid Search)

Use the REST endpoint for combined vector + BM25 search:

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

🤖 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
  data_dir: ./data

embeddings:
  provider: local # or ollama, openai
  model: bge-m3
  dimensions: 1024

decay:
  enabled: true
  recalculate_interval: 1h

auto_links:
  enabled: true
  similarity_threshold: 0.82

# === Async Write Settings ===
# These control the async write-behind cache for better throughput
async_writes:
  enabled: true                    # Enable async writes (default: true)
  flush_interval: 50ms            # How often to flush pending writes
  max_node_cache_size: 50000      # Max nodes to buffer before forcing flush
  max_edge_cache_size: 100000     # Max edges to buffer before forcing flush

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
Session Context — Decaying conversation history
Research Tools — Connect papers, notes, and insights

Documentation

Guide	Description
Getting Started	Installation & quick start
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

Comparison

Feature	Neo4j	NornicDB
Protocol	Bolt ✓	Bolt ✓
Query Language	Cypher ✓	Cypher ✓
Memory Decay	Manual	Automatic
Auto-Relationships	No	Built-in
Vector Search	Plugin	Native
GPU Acceleration	No	Metal/CUDA
Embedded Mode	No	Yes
License	GPL	MIT

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 + Qwen2.5-0.5B (~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

License

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

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

Weaving your data's destiny

Name		Name	Last commit message	Last commit date
Latest commit History 336 Commits
.agents		.agents
.github		.github
apoc		apoc
cmd		cmd
docker		docker
docs		docs
lib		lib
macos		macos
models		models
neural		neural
pkg		pkg
plugins		plugins
scripts		scripts
testing		testing
ui		ui
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
DIY.md		DIY.md
LICENSE		LICENSE
Makefile		Makefile
NOTICES.md		NOTICES.md
README.md		README.md
build-cuda.bat		build-cuda.bat
build.bat		build.bat
build.ps1		build.ps1
build.sh		build.sh
docker-compose.amd64.yml		docker-compose.amd64.yml
docker-compose.arm64.yml		docker-compose.arm64.yml
docker-compose.yml		docker-compose.yml
env.local		env.local
go.mod		go.mod
go.sum		go.sum
mkdocs.yml		mkdocs.yml
neo4j_import.py		neo4j_import.py
nornicdb.example.yaml		nornicdb.example.yaml

License

orneryd/NornicDB

Folders and files

Latest commit

History

Repository files navigation

NornicDB

🐳 Get Started in 30 Seconds

Build It Yourself! — NornicDB

Prerequisites

Common Make flags

DIY INSTRUCTIONS

What is NornicDB?

Quick Start

Docker (Recommended)

From Source

Connect

Features

🔌 Neo4j Compatible

🧠 Intelligent Memory

🔗 Auto-Relationships

⚡ Performance

🎯 Vector Search

🤖 Heimdall AI Assistant

🧩 APOC Functions

Docker Images

ARM64 (Apple Silicon)

AMD64 (Linux/Intel)

Headless Mode

Configuration

Use Cases

Documentation

Comparison

Building

Native Binary

Docker Images

Cross-Compilation

Roadmap

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 12

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages