Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/orneryd/nornicdb

NornicDB is a high-performance graph + vector database built for AI agents and knowledge systems. It speaks Neo4j's (Bolt + Cypher) and qdrant's (gRPC) languages so you can use Nornic with zero code changes, while adding intelligent features including a graphql endpoint, air-gapped embeddings, GPU accelerated search, and other intelligent features.
https://github.com/orneryd/nornicdb

bolt cypher cypher-query-language database embedded-systems enterprise-solutions golang graph-rag graphql hnsw local-llm mcp-server memoryos neo4j openai-api qdrant-vector-database tlp vector-database vector-search

Last synced: about 2 months ago
JSON representation

NornicDB is a high-performance graph + vector database built for AI agents and knowledge systems. It speaks Neo4j's (Bolt + Cypher) and qdrant's (gRPC) languages so you can use Nornic with zero code changes, while adding intelligent features including a graphql endpoint, air-gapped embeddings, GPU accelerated search, and other intelligent features.

Awesome Lists containing this project

README 

          


  NornicDB Logo




NornicDB





  The Graph Database That Learns


  Neo4j-compatible • GPU-accelerated • Memory that evolves






  Version 1.0.0

  GitHub

  Docker

  Neo4j Compatible

  Go Version

  License






  Quick Start •

  Features •

  Docker •

  Docs




---



## 🐳 Get Started in 30 Seconds



```bash

# 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-cpu-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](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](DIY.md)



---



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



```bash

# 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



```bash

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:



```python

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       |



```cypher

// 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](docs/performance/benchmarks-vs-neo4j.md) 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](docs/user-guides/vector-search.md) 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:



```cypher

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



```cypher

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



```bash

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.



```bash

# 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](docs/user-guides/heimdall-ai-assistant.md) and [Plugin Development](docs/user-guides/heimdall-plugins.md).



### 🧩 APOC Functions



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



```cypher

// 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](docs/features/plugin-system.md).



## Docker Images



All images available at [Docker Hub](https://hub.docker.com/u/timothyswt).



### 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`)



```bash

# 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:**



```bash

nornicdb serve --headless

```



**Environment variable:**



```bash

NORNICDB_HEADLESS=true nornicdb serve

```



**Build without UI (smaller binary):**



```bash

# Native build

make build-headless



# Docker build

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

```



## Configuration



```yaml

# 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](docs/getting-started/README.md)                          | Installation & quick start     |

| [API Reference](docs/api-reference/README.md)                              | Cypher functions & procedures  |

| [User Guides](docs/user-guides/README.md)                                  | Complete examples & patterns   |

| [Performance](docs/performance/README.md)                                  | Benchmarks vs Neo4j            |

| [Neo4j Migration](docs/neo4j-migration/README.md)                          | Compatibility & feature parity |

| [Architecture](docs/architecture/README.md)                                | System design & internals      |

| [Docker Guide](docker/README.md)                                           | Build & deployment             |

| [Development](docs/development/README.md)                                  | 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



```bash

# Basic build

make build



# Headless (no UI)

make build-headless



# With local LLM support

make build-localllm

```



### Docker Images



```bash

# 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



```bash

# 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



- [x] Neo4j Bolt protocol

- [x] Cypher query engine (52 functions)

- [x] Memory decay system

- [x] GPU acceleration (Metal, CUDA)

- [x] Vector & full-text search

- [X] Auto-relationship engine

- [X] HNSW vector index

- [x] Metadata/Property Indexing

- [x] SIMD Implementation

- [x] Clustering support



## License



MIT License — Originally part of the [Mimir](https://github.com/orneryd/mimir) project, now maintained as a standalone repository.



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



---





  Weaving your data's destiny