{"id":36954661,"url":"https://github.com/orneryd/nornicdb","last_synced_at":"2026-04-01T17:03:42.252Z","repository":{"id":328021636,"uuid":"1111263109","full_name":"orneryd/NornicDB","owner":"orneryd","description":"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.","archived":false,"fork":false,"pushed_at":"2026-02-28T17:23:12.000Z","size":40215,"stargazers_count":177,"open_issues_count":1,"forks_count":10,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-28T18:55:46.703Z","etag":null,"topics":["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"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/orneryd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security/README.md","support":"docs/support/reply-user-config-gpu-embeddings-ui.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-06T15:46:33.000Z","updated_at":"2026-02-28T17:23:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/orneryd/NornicDB","commit_stats":null,"previous_names":["orneryd/nornicdb"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/orneryd/NornicDB","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orneryd%2FNornicDB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orneryd%2FNornicDB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orneryd%2FNornicDB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orneryd%2FNornicDB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/orneryd","download_url":"https://codeload.github.com/orneryd/NornicDB/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orneryd%2FNornicDB/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30226784,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T19:01:10.287Z","status":"ssl_error","status_checked_at":"2026-03-07T18:59:58.103Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-01-13T13:00:25.056Z","updated_at":"2026-04-01T17:03:42.229Z","avatar_url":"https://github.com/orneryd.png","language":"Go","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/orneryd/NornicDB/refs/heads/main/docs/assets/logos/nornicdb-logo.svg\" alt=\"NornicDB Logo\" width=\"200\"/\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eNornicDB\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eThe Graph Database That Learns\u003c/strong\u003e\u003cbr/\u003e\n  Neo4j-compatible • GPU-accelerated • Memory that evolves\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/version-1.0.36-success\" alt=\"Version 1.0.36\"\u003e\n  \u003ca href=\"https://coveralls.io/github/orneryd/NornicDB?branch=main\"\u003e\u003cimg src=\"https://coveralls.io/repos/github/orneryd/NornicDB/badge.svg?branch=main\" alt=\"Coveralls Report\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://hub.docker.com/u/timothyswt\"\u003e\u003cimg src=\"https://img.shields.io/badge/docker-ready-blue?logo=docker\" alt=\"Docker\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://neo4j.com/\"\u003e\u003cimg src=\"https://img.shields.io/badge/neo4j-compatible-008CC1?logo=neo4j\" alt=\"Neo4j Compatible\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/qdrant/qdrant\"\u003e\u003cimg src=\"https://img.shields.io/badge/qdrant-compatible-008CC1?logo=qdrant\" alt=\"Qdrant Compatible Compatible\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://go.dev/\"\u003e\u003cimg src=\"https://img.shields.io/badge/go-%3E%3D1.26-00ADD8?logo=go\" alt=\"Go Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://goreportcard.com/report/github.com/orneryd/nornicdb\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/orneryd/nornicdb\" alt=\"Go Report Card\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://discord.gg/yszYHrxp4N\"\u003e\u003cimg src=\"https://img.shields.io/badge/discord-community-00ADD8?logo=discord\" alt=\"Discord Community Server\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e •\n  \u003ca href=\"#what-nornicdb-is\"\u003eWhat It Is\u003c/a\u003e •\n  \u003ca href=\"#why-nornicdb-is-different\"\u003eWhy NornicDB\u003c/a\u003e •\n  \u003ca href=\"#performance-snapshot\"\u003eBenchmarks\u003c/a\u003e •\n  \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e •\n  \u003ca href=\"#documentation\"\u003eDocs\u003c/a\u003e •\n  \u003ca href=\"#comparison\"\u003eComparison\u003c/a\u003e •\n  \u003ca href=\"#contributors\"\u003eContributors\u003c/a\u003e\n\u003c/p\u003e\n\n## Try It With One Command\n\n```bash\n# arm64 / Apple Silicon\ndocker run -d --name nornicdb -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data timothyswt/nornicdb-arm64-metal-bge:latest\n\n# amd64 / CPU only\ndocker run -d --name nornicdb -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data timothyswt/nornicdb-amd64-cpu-bge:latest\n```\n\nOpen [http://localhost:7474](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`.\n\n---\n\n## What NornicDB Is\n\nNornicDB 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.\n\nIt 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.\n\n## Why NornicDB Is Different\n\n- **Neo4j-compatible by default**: Bolt + Cypher support for existing drivers and applications.\n- **Built for AI-native workloads**: vector search, memory decay, and auto-relationships are first-class features.\n- **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.\n- **Protocol flexibility without splitting the system**: REST, GraphQL, Bolt/Cypher, Qdrant-compatible gRPC, and additive Nornic gRPC live on the same platform.\n- **Hardware-accelerated execution**: Metal/CUDA/Vulkan pathways for high-throughput graph + semantic workloads.\n- **Operational flexibility**: full images (models included), BYOM images, and headless API-only deployments.\n\n## Production Deployment Patterns\n\nNornicDB 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.\n\n- **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.\n- **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)\n\n## Transactional Guarantees \u0026 Isolation\n\nNornicDB 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.\n\n- **Repeatable reads within a transaction**: transactions see their own buffered writes, but not commits that land after their read snapshot.\n- **Conflict detection at commit**: concurrent graph mutations against the same logical state fail with a normalized `ErrConflict` instead of silently overwriting newer data.\n- **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`.\n- **Search remains current-state focused**: current search paths are intentionally separate from historical MVCC state.\n\nSee [transaction implementation details](docs/user-guides/transactions.md), [historical reads and MVCC retention](docs/user-guides/historical-reads-mvcc-retention.md), and the [canonical graph ledger guide](docs/user-guides/canonical-graph-ledger.md).\n\n### What Recent Deep-Dives Show\n\n- **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.\n- **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.\n- **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.\n- **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.\n- **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.\n\nRead more:\n\n- [Cypher parser modes and execution trade-offs](docs/architecture/cypher-parser-modes.md)\n- [How we sped up HNSW construction 2.7x](https://dev.to/orneryd/how-i-sped-up-hnsw-construction-27x-2jhn)\n\n## Performance Snapshot\n\n**LDBC Social Network Benchmark** (M3 Max, 64GB):\n\n| Query Type                    | NornicDB      | Neo4j       | Speedup |\n| ----------------------------- | ------------- | ----------- | ------- |\n| **Message content lookup**    | 6,389 ops/sec | 518 ops/sec | **12x** |\n| **Recent messages (friends)** | 2,769 ops/sec | 108 ops/sec | **25x** |\n| **Avg friends per city**      | 4,713 ops/sec | 91 ops/sec  | **52x** |\n| **Tag co-occurrence**         | 2,076 ops/sec | 65 ops/sec  | **32x** |\n\n\u003e See [full benchmark results](docs/performance/benchmarks-vs-neo4j.md) for complete methodology and additional workloads.\n\n### Hybrid Retrieval Benchmarks\n\nHybrid 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.\n\n**Local benchmark** (67,280 nodes, 40,921 edges, 67,298 embeddings, HNSW CPU-only index):\n\n| Workload       | Transport |   Throughput |    Mean |     P50 |     P95 |     P99 |     Max |\n| -------------- | --------- | -----------: | ------: | ------: | ------: | ------: | ------: |\n| Vector only    | HTTP      | 19,342 req/s |  511 us |  470 us |  750 us |  869 us | 1.02 ms |\n| Vector only    | Bolt      | 22,309 req/s |  444 us |  428 us |  629 us |  814 us |  968 us |\n| Vector + 1 hop | HTTP      | 11,523 req/s |  859 us |  699 us | 1.54 ms | 3.46 ms | 4.71 ms |\n| Vector + 1 hop | Bolt      |  7,977 req/s | 1.24 ms | 1.10 ms | 1.97 ms | 4.91 ms | 6.14 ms |\n\nBolt is now ahead on both throughput and tail latency for this vector-only path.\n\n**Remote benchmark** (GCP, 8 vCPU, 32 GB RAM):\n\n- Vector only: ~110.7 ms P50\n- Vector + 1 hop: ~112.9 ms P50\n- The delta between local and remote matched network RTT closely enough that end-to-end latency was network-bound rather than compute-bound.\n\nThis 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.\n\nSee the [hybrid retrieval benchmark write-up](docs/performance/hybrid-query-benchmarks.md) for methodology, caveats, and reproduction queries, and see [Graph-RAG: NornicDB vs Typical](docs/architecture/graph-rag-nornicdb-comparison.md) for the architectural implications.\n\n## Quick Start\n\n### Docker (Recommended)\n\n```bash\n# Apple Silicon (includes bge-m3 embedding model)\ndocker run -d --name nornicdb \\\n  -p 7474:7474 -p 7687:7687 \\\n  -v nornicdb-data:/data \\\n  timothyswt/nornicdb-arm64-metal-bge:latest  # Apple Silicon\n  # timothyswt/nornicdb-amd64-cuda-bge:latest  # NVIDIA GPU\n```\n\nOpen [http://localhost:7474](http://localhost:7474) for the admin UI.\n\nNeed a different image/profile (Heimdall, BYOM, CPU-only, Vulkan, headless)?\n\n- [Docker image quick reference](docs/getting-started/image-quick-reference.md)\n- [Docker images section](#docker-images)\n- [Quick start guide](docs/getting-started/quick-start.md)\n\n### From Source\n\n```bash\ngit clone https://github.com/orneryd/NornicDB.git\ncd NornicDB\ngo build -o nornicdb ./cmd/nornicdb\n./nornicdb serve\n```\n\n### Connect\n\nUse any Neo4j driver — Python, JavaScript, Go, Java, .NET:\n\n```python\nfrom neo4j import GraphDatabase\n\ndriver = GraphDatabase.driver(\"bolt://localhost:7687\")\nwith driver.session() as session:\n    session.run(\"CREATE (n:Memory {content: 'Hello NornicDB'})\")\n```\n\n## Why Switch from Neo4j?\n\n- **12x-52x faster** on published LDBC workloads (same hardware comparisons).\n- **Native graph + vector** in one engine (no separate vector sidecar required).\n- **GPU acceleration paths** (Metal/CUDA/Vulkan) for semantic + graph workloads.\n- **Drop-in compatibility** via Bolt + Cypher for existing applications.\n- **Canonical graph ledger model** for temporal validity, tritemporal fact modeling, as-of reads, and audit-oriented mutation tracking.\n\n## Why Switch from Qdrant?\n\n- **Graph + vector in one engine**: combine semantic retrieval with native graph traversal and Cypher queries.\n- **Qdrant gRPC compatibility preserved**: keep Qdrant-style gRPC workflows while adding graph-native capabilities.\n- **Hybrid retrieval built in**: vector + BM25 fusion and optional reranking in the same query pipeline.\n- **Canonical truth modeling**: versioned facts, temporal validity windows, tritemporal facts, and as-of reads for governance-heavy use cases.\n- **Protocol flexibility**: use REST, GraphQL, Bolt/Cypher, Qdrant-compatible gRPC, and additive Nornic gRPC on one platform.\n\n## Features\n\n### 🔌 Neo4j Compatible\n\nDrop-in replacement for Neo4j. Your existing code works unchanged.\n\n- **Bolt Protocol** — Use official Neo4j drivers\n- **Cypher Queries** — Full query language support\n- **Schema Management** — Constraints, indexes, vector indexes\n- **Qdrant gRPC API Compatible** — Works with Qdrant-style gRPC vector workflows\n\n### 🧠 Intelligent Memory\n\nMemory that behaves like human cognition.\n\n| Memory Tier    | Half-Life | Use Case               |\n| -------------- | --------- | ---------------------- |\n| **Episodic**   | 7 days    | Chat context, sessions |\n| **Semantic**   | 69 days   | Facts, decisions       |\n| **Procedural** | 693 days  | Skills, patterns       |\n\n```cypher\n// Find memories that are still strong\nMATCH (m:Memory) WHERE m.decayScore \u003e 0.5\nRETURN m.title ORDER BY m.decayScore DESC\n```\n\n### 🔗 Auto-Relationships\n\nNornicDB weaves connections automatically:\n\n- **Embedding Similarity** — Related concepts link together\n- **Co-access Patterns** — Frequently queried pairs connect\n- **Temporal Proximity** — Same-session nodes associate\n- **Transitive Inference** — A→B + B→C suggests A→C\n\n### 🎯 Vector Search\n\nNative semantic search with GPU acceleration and hybrid retrieval support.\n\n\u003e 📖 Deep dive: [Vector Search Guide](docs/user-guides/vector-search.md) and [Qdrant gRPC Endpoint](docs/user-guides/qdrant-grpc.md).\n\n**Cypher (Neo4j-compatible):**\n\n```cypher\nCALL db.index.vector.queryNodes('embeddings', 10, 'machine learning guide')\nYIELD node, score\nRETURN node.content, score\n```\n\n**Hybrid search (REST):**\n\n```bash\ncurl -X POST http://localhost:7474/nornicdb/search \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"machine learning\", \"limit\": 10}'\n```\n\nMore API entry points:\n\n- **GraphQL** hybrid search: `POST /graphql` with `search(query, options)`\n- **gRPC** (Qdrant-compatible): `Points.Search` / `Points.Query(Document.text)`\n- **Nornic native gRPC**: `NornicSearch/SearchText` (additive client)\n- See `docs/user-guides/nornic-search-grpc.md` for additive proto setup without forking Qdrant drivers.\n\n### 🤖 Heimdall AI Assistant\n\nBuilt-in AI that understands your database.\n\n```bash\n# Enable Heimdall\nNORNICDB_HEIMDALL_ENABLED=true ./nornicdb serve\n```\n\n**Natural Language Queries:**\n\n- \"Get the database status\"\n- \"Show me system metrics\"\n- \"Run health check\"\n\n**Plugin System:**\n\n- Create custom actions the AI can execute\n- Lifecycle hooks (PrePrompt, PreExecute, PostExecute)\n- Database event monitoring for autonomous actions\n- Inline notifications with proper ordering\n\nSee [Heimdall AI Assistant Guide](docs/user-guides/heimdall-ai-assistant.md) and [Plugin Development](docs/user-guides/heimdall-plugins.md).\n\n### 🧩 APOC Functions\n\n950+ built-in functions for text, math, collections, and more. Plus a plugin system for custom extensions.\n\n```cypher\n// Text processing\nRETURN apoc.text.camelCase('hello world')  // \"helloWorld\"\nRETURN apoc.text.slugify('Hello World!')   // \"hello-world\"\n\n// Machine learning\nRETURN apoc.ml.sigmoid(0)                  // 0.5\nRETURN apoc.ml.cosineSimilarity([1,0], [0,1])  // 0.0\n\n// Collections\nRETURN apoc.coll.sum([1, 2, 3, 4, 5])      // 15\n```\n\nDrop custom `.so` plugins into `/app/plugins/` for automatic loading. See the [APOC Plugin Guide](docs/features/plugin-system.md).\n\n## Docker Images\n\nAll images available at [Docker Hub](https://hub.docker.com/u/timothyswt).\n\n### ARM64 (Apple Silicon)\n\n| Image                                          | Size   | Description                           |\n| ---------------------------------------------- | ------ | ------------------------------------- |\n| `timothyswt/nornicdb-arm64-metal-bge-heimdall` | 1.1 GB | **Full** - Embeddings + AI Assistant  |\n| `timothyswt/nornicdb-arm64-metal-bge`          | 586 MB | **Standard** - With BGE-M3 embeddings |\n| `timothyswt/nornicdb-arm64-metal`              | 148 MB | **Minimal** - Core database, BYOM     |\n| `timothyswt/nornicdb-arm64-metal-headless`     | 148 MB | **Headless** - API only, no UI        |\n\n### AMD64 (Linux/Intel)\n\n| Image                                     | Size    | Description                          |\n| ----------------------------------------- | ------- | ------------------------------------ |\n| `timothyswt/nornicdb-amd64-cuda-bge`      | ~4.5 GB | **GPU + Embeddings** - CUDA + BGE-M3 |\n| `timothyswt/nornicdb-amd64-cuda`          | ~3 GB   | **GPU** - CUDA acceleration, BYOM    |\n| `timothyswt/nornicdb-amd64-cuda-headless` | ~2.9 GB | **GPU Headless** - API only          |\n| `timothyswt/nornicdb-amd64-cpu`           | ~500 MB | **CPU** - No GPU required            |\n| `timothyswt/nornicdb-amd64-cpu-headless`  | ~500 MB | **CPU Headless** - API only          |\n\n**BYOM** = Bring Your Own Model (mount at `/app/models`)\n\n```bash\n# With your own model\ndocker run -d -p 7474:7474 -p 7687:7687 \\\n  -v /path/to/models:/app/models \\\n  timothyswt/nornicdb-arm64-metal:latest\n\n# Headless mode (API only, no web UI)\ndocker run -d -p 7474:7474 -p 7687:7687 \\\n  -v nornicdb-data:/data \\\n  timothyswt/nornicdb-arm64-metal-headless:latest\n```\n\n### Headless Mode\n\nFor 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.\n\n**Runtime flag:**\n\n```bash\nnornicdb serve --headless\n```\n\n**Environment variable:**\n\n```bash\nNORNICDB_HEADLESS=true nornicdb serve\n```\n\n**Build without UI (smaller binary):**\n\n```bash\n# Native build\nmake build-headless\n\n# Docker build\ndocker build --build-arg HEADLESS=true -f docker/Dockerfile.arm64-metal .\n```\n\n## Configuration\n\n```yaml\n# nornicdb.yaml\nserver:\n  bolt_port: 7687\n  http_port: 7474\n  host: localhost\n\ndatabase:\n  data_dir: ./data\n  async_writes_enabled: true\n  async_flush_interval: 50ms\n  async_max_node_cache_size: 50000\n  async_max_edge_cache_size: 100000\n\nembedding:\n  enabled: true\n  provider: local # or ollama, openai\n  model: bge-m3.gguf\n  url: \"\"\n  dimensions: 1024\n\nembedding_worker:\n  chunk_size: 8192\n  chunk_overlap: 50\n\nmemory:\n  decay_enabled: true\n  decay_interval: 1h\n  auto_links_enabled: true\n  auto_links_similarity_threshold: 0.82\n```\n\n## Use Cases\n\n- **AI Agent Memory** — Persistent, queryable memory for LLM agents\n- **Knowledge Graphs** — Auto-organizing knowledge bases\n- **RAG Systems** — Vector + graph retrieval in one database\n- **Graph-RAG for LLM Inference** — Simplify retrieval pipelines by combining graph traversal, hybrid search, and provenance in one engine\n- **Session Context** — Decaying conversation history\n- **Research Tools** — Connect papers, notes, and insights\n- **Canonical Truth Stores** — Versioned facts, temporal validity, and append-only mutation history in a graph model\n- **Financial Systems** — Loan/risk state reconstruction with as-of reads and audit receipts\n- **Compliance \u0026 RegTech** — KYC/AML state changes, policy/rule versioning, and non-overlapping validity enforcement\n- **Audit Platforms** — Correlate graph mutations to WAL sequence ranges and receipt hashes\n- **AI Governance \u0026 Lineage** — Track model assertions, overrides, and fact provenance over time\n\n## Documentation\n\nStart with the docs hub for role/task navigation, then use the issue index for symptom-first troubleshooting:\n\n- Public documentation site: [https://orneryd.github.io/NornicDB/](https://orneryd.github.io/NornicDB/)\n- [Documentation Hub](docs/README.md)\n- [Issue Index](docs/ISSUES-INDEX.md)\n\n| Guide                                                                         | Description                    |\n| ----------------------------------------------------------------------------- | ------------------------------ |\n| [Getting Started](docs/getting-started/README.md)                             | Installation \u0026 quick start     |\n| [Docker Image Quick Reference](docs/getting-started/image-quick-reference.md) | Full runtime image matrix      |\n| [API Reference](docs/api-reference/README.md)                                 | Cypher functions \u0026 procedures  |\n| [User Guides](docs/user-guides/README.md)                                     | Complete examples \u0026 patterns   |\n| [Performance](docs/performance/README.md)                                     | Benchmarks vs Neo4j            |\n| [Neo4j Migration](docs/neo4j-migration/README.md)                             | Compatibility \u0026 feature parity |\n| [Architecture](docs/architecture/README.md)                                   | System design \u0026 internals      |\n| [Docker Guide](docker/README.md)                                              | Build \u0026 deployment             |\n| [Development](docs/development/README.md)                                     | Contributing \u0026 development     |\n\nAdditional deep dives referenced above:\n\n- [Hybrid query benchmarks](docs/performance/hybrid-query-benchmarks.md)\n- [Canonical graph ledger](docs/user-guides/canonical-graph-ledger.md)\n- [Historical reads and MVCC retention](docs/user-guides/historical-reads-mvcc-retention.md)\n- [Cypher parser modes](docs/architecture/cypher-parser-modes.md)\n\n## Star History\n\n\u003ca href=\"https://www.star-history.com/?repos=orneryd%2FNornicDB\u0026type=date\u0026legend=top-left\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/image?repos=orneryd/NornicDB\u0026type=date\u0026theme=dark\u0026legend=top-left\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/image?repos=orneryd/NornicDB\u0026type=date\u0026legend=top-left\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/image?repos=orneryd/NornicDB\u0026type=date\u0026legend=top-left\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n## Comparison\n\n| Platform     | Category                          | Query Language Support (and protocol)                                              | Native Vector Search     | Canonical Graph + Temporal Ledger Pattern                     | Queryable Mutation Log + Receipts                    | Embedded/Self-Hosted Focus |\n| ------------ | --------------------------------- | ---------------------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------- | ---------------------------------------------------- | -------------------------- |\n| **NornicDB** | Graph + Vector + Canonical Ledger | **Cypher via Bolt**; also HTTP/GraphQL and gRPC (Qdrant-compatible + NornicSearch) | **Yes**                  | **Yes**                                                       | **Yes**                                              | **Yes**                    |\n| Neo4j        | Graph DB                          | Cypher via Bolt/HTTP                                                               | Yes                      | Partial (manual modeling)                                     | Partial (logs exist, not first-class receipts model) | Server-first               |\n| Memgraph     | Graph DB                          | openCypher via Bolt/HTTP                                                           | Partial/varies by setup  | Partial (manual)                                              | Partial (manual/integration)                         | Server-first               |\n| TigerGraph   | Graph analytics DB                | GSQL via REST++/native endpoints                                                   | Partial/extension-driven | Partial (manual)                                              | Partial (manual/integration)                         | Server-first               |\n| Qdrant       | Vector DB                         | Qdrant query/filter API via gRPC/REST                                              | Yes                      | No (not graph-native)                                         | No                                                   | Server-first               |\n| Weaviate     | Vector DB                         | GraphQL + REST APIs                                                                | Yes                      | Partial (knowledge graph features, not Cypher property graph) | No                                                   | Server-first               |\n| Amazon QLDB  | Ledger DB                         | PartiQL via AWS API/SDK                                                            | No                       | Partial (ledger + temporal history, not graph-native)         | Yes (ledger-native)                                  | Managed service            |\n\n\u003e Snapshot is capability-oriented and high-level; exact behavior depends on edition/configuration and workload design.\n\n## Building\n\n### Native Binary\n\n```bash\n# Basic build\nmake build\n\n# Headless (no UI)\nmake build-headless\n\n# With local LLM support\nmake build-localllm\n```\n\n### Docker Images\n\n```bash\n# Download models for Heimdall builds (automatic if missing)\nmake download-models        # BGE-M3 + qwen3-0.6b (~750MB)\nmake check-models          # Verify models present\n\n# ARM64 (Apple Silicon)\nmake build-arm64-metal                  # Base (BYOM)\nmake build-arm64-metal-bge              # With BGE embeddings\nmake build-arm64-metal-bge-heimdall     # With BGE + Heimdall AI\nmake build-arm64-metal-headless         # Headless (no UI)\n\n# AMD64 CUDA (NVIDIA GPU)\nmake build-amd64-cuda                   # Base (BYOM)\nmake build-amd64-cuda-bge               # With BGE embeddings\nmake build-amd64-cuda-bge-heimdall      # With BGE + Heimdall AI\nmake build-amd64-cuda-headless          # Headless (no UI)\n\n# AMD64 CPU-only\nmake build-amd64-cpu                    # Minimal\nmake build-amd64-cpu-headless           # Minimal headless\n\n# Build all variants for your architecture\nmake build-all\n\n# Deploy to registry\nmake deploy-all             # Build + push all variants\n```\n\n### Cross-Compilation\n\n```bash\n# Build for other platforms from macOS\nmake cross-linux-amd64     # Linux x86_64\nmake cross-linux-arm64     # Linux ARM64\nmake cross-rpi             # Raspberry Pi 4/5\nmake cross-windows         # Windows (CPU-only)\nmake cross-all             # All platforms\n```\n\n## Roadmap\n\n### Completed\n\n- [x] Neo4j Bolt protocol\n- [x] Cypher query engine (52 functions)\n- [x] Memory decay system\n- [x] GPU acceleration (Metal, CUDA)\n- [x] Vector \u0026 full-text search\n- [x] Auto-relationship engine\n- [x] HNSW vector index\n- [x] Metadata/Property Indexing\n- [x] SIMD Implementation\n- [x] Clustering support\n- [x] Sharding (Composite DB + Remote Constituents)\n- [x] Data Explorer UI (Browser query editor, semantic search, node details)\n\n### Planned (from `docs/plans`)\n\n- [ ] GPU-assisted HNSW construction with CPU-serving persistence parity (`docs/plans/gpu-hnsw-construction-plan.md`)\n- [ ] Neo4j-compatible end-to-end streaming execution + wrapper driver/ORM (`docs/plans/neo4j-compatible-streaming-driver-and-server-plan.md`)\n- [ ] GDPR compliance hardening: user-data detection, relationship export/delete/anonymization, and audit-log coverage (`docs/plans/gdpr-compliance-fixes.md`)\n- [ ] UI enhancement backlog (search/config/admin UX improvements) (`docs/plans/ui-enhancements.md`)\n\n## Contributors\n\nSpecial thanks to everyone who helps make NornicDB better. See [CONTRIBUTORS.md](CONTRIBUTORS.md) for a list of community contributors.\n\n## License\n\nMIT License — Originally part of the [Mimir](https://github.com/orneryd/mimir) project, now maintained as a standalone repository.\n\nPatent rights are handled via a defensive non-assertion grant in [PATENTS.md](PATENTS.md). This keeps the project open for broad use (including commercial use) while adding patent retaliation protection.\n\nSee [NOTICES.md](NOTICES.md) for third-party license information, including bundled AI models (BGE-M3, Qwen2.5) and dependencies.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eWeaving your data's destiny\u003c/em\u003e\n\u003c/p\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forneryd%2Fnornicdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forneryd%2Fnornicdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forneryd%2Fnornicdb/lists"}