DOCSEARCHbyAlgolia
Submit Docs

NornicDB Documentation

repository·main·Indexed 21 days ago

https://github.com/orneryd/nornicdb

NornicDB is a high-performance, AI-native graph database integrating graph traversal, vector retrieval, and temporal/historical data via MVCC. It features over 850 Neo4j-compatible APOC functions, GPU-accelerated K-Means clustering for semantic search, and support for custom .so plugins. The ecosystem includes a local OAuth 2.0 provider for authentication testing and a Swagger UI test server for OpenAPI specification validation.

Tokens
377.4K
Snippets
920
Records
1.5K
Agent score
73%

What's inside NornicDB

  1. Overview of the NornicDB Bolt Protocol Server

    main
    The NornicDB Bolt Protocol Server is a Neo4j-compatible implementation of the Bolt protocol. It allows any standard Neo4j driver (Python, JS, Go, Java, etc.) to connect to NornicDB without any modifications. The server handles the Bolt protocol handshake, authentication, session management, and result streaming using the PackStream serialization format.

  2. Overview of NornicDB Consumer Skills

    main

    NornicDB Consumer Skills are structured, agent-friendly documentation files designed to teach AI agents (like Claude Code) how to use NornicDB features via its Cypher API. Unlike internal architecture docs, these skills focus exclusively on the consumer-facing surface: Cypher statements, CALL procedures, and integration patterns.

    Key areas covered by the skills include:

    • Cypher Queries: Point lookups, batch retrieval, pagination, search, traversal, and batched UNWIND/MERGE writes.
    • Client Drivers: Using Bolt clients (e.g., neo4j-go-driver/v5) and the Qdrant-compatible gRPC surface.
    • Migrations: Moving from Qdrant or Neo4j 5 to NornicDB.
    • Knowledge Management: DDL for decay profiles, promotion policies, and managed embeddings.
    • Search & RAG: Vector/full-text indexing and RAG procedures like db.retrieve and db.rerank.

  3. Overview of NornicDB supported platforms and packaging

    main

    NornicDB is being packaged for a wide range of environments. While Docker is currently the only available method, plans are in place for native installers across macOS, Windows, Linux, and Raspberry Pi.

    Supported Platforms Summary

    PlatformArchitecturePackage TypeStatus
    macOSarm64 (Apple Silicon)Homebrew, .pkg📋 Planned
    macOSamd64 (Intel)Homebrew, .pkg📋 Planned
    Windowsamd64MSI + Service📋 Planned
    Linuxamd64deb, rpm, systemd📋 Planned
    Linuxarm64deb, rpm, systemd📋 Planned
    Raspberry Piarm64/armdeb, systemd📋 Planned
    Dockeramd64, arm64Container✅ Available

    Distribution Channels by User Type

    • Developers: Homebrew (macOS), Chocolatey (Windows), and Docker Hub.
    • Enterprise/End-Users: macOS .pkg (with LaunchDaemon), Windows MSI (with Windows Service), and Linux .deb/.rpm packages.
    • Edge/IoT: Optimized ARM builds for Raspberry Pi and NVIDIA Jetson (using linux-arm64 builds).

  4. What is NornicDB?

    main

    NornicDB is a graph database designed for workloads requiring graph traversal, vector retrieval, and historical truth in a single system. It is Neo4j-compatible, supporting Bolt and Cypher, and provides multiple interfaces including REST, GraphQL, and gRPC.

    Key capabilities include:

    • Hybrid Retrieval: Combines graph, vector, and temporal workloads in one execution path.
    • AI-Native Features: Built-in support for vector search, memory decay, and auto-relationships.
    • Temporal/Ledger Semantics: Supports tritemporal facts, as-of reads, and canonical knowledge versioning via MVCC.
    • Multi-Protocol Support: Bolt/Cypher, REST, GraphQL, and Qdrant-compatible gRPC.

  5. Overview of NornicDB Architecture

    main

    NornicDB is a high-performance graph database designed for low-latency retrieval by consolidating transport, embedding, search, and ranking into a single operational unit. It is compatible with the Neo4j Bolt protocol and Cypher query language, making it a drop-in replacement for many graph-based workflows while adding native hybrid vector + graph capabilities.

    Key features include:

    • Full Neo4j Compatibility: Supports Bolt, Cypher, and HTTP/REST.
    • Hybrid Search: Combines vector search (HNSW) and BM25 full-text search using RRF (Reciprocal Rank Fusion).
    • Native LLM Integration: Includes an MCP (Model Context Protocol) server with 6 built-in tools.
    • Auto-Embedding: Provides server-side embedding via WITH EMBEDDING syntax and background workers.
    • GPU Acceleration: Supports Metal, CUDA, OpenCL, and Vulkan for significant speedups in vector operations.

  6. Overview of Knowledge Policy Metrics

    main

    NornicDB exposes observability metrics for its Knowledge Policy subsystem under the nornicdb_knowledge_policy_* prefix. These metrics are registered with the Prometheus registry and can be used to monitor decay workloads, suppression rates, flush performance, and policy mutations.

    Key Metric Groups

    • Scoring & Decay: Monitor how entities are scored and how many are suppressed (scored_total, decay_score, suppressions_total).
    • Access Flusher: Monitor the performance and pressure of the background flush process (access_flush_batch_rows, access_flush_duration_seconds, access_flush_buffer_fullness).
    • Mutations & Reconcile: Monitor policy-driven changes and schema updates (on_access_mutations_total, reconcile_total).
    • Index & Read Path: Monitor secondary index churn and read-path visibility drops (deindex_enqueued_total, read_filter_dropped_total).

    Labeling Note

    The database label is included only if cfg.Observability.Metrics.TenantLabelsEnabled is set to true. Flush-level metrics (access_flush_*) are not tenant-scoped because the flusher operates across namespaces.

  7. Runtime & Performance features in NornicDB

    main

    NornicDB includes features to optimize runtime performance and control behavior:

    • GPU acceleration: Offloading computations to hardware accelerators.
    • Feature flags: Controlling access to specific experimental or stable features.
    • Performance monitoring: Accessing benchmarks and performance documentation.

  8. Use NornicDB MCP tools for memory and task management

    main

    NornicDB provides a set of Model Context Protocol (MCP) tools designed for LLMs to manage long-term memory, semantic search, and task workflows.

    Core Mental Model:

    • Storage: Use store to remember information.
    • Retrieval by ID: Use recall when you know the specific ID or exact filters.
    • Semantic Search: Use discover to find information by meaning or topic.
    • Relationships: Use link to connect existing nodes.
    • Task Management: Use task for single task CRUD and tasks for querying/listing multiple tasks.

    Note: NornicDB handles storage and search; file indexing must be performed at the application layer.

    Want to remember something? → store
Know the ID, need to fetch? → recall
Search by meaning/topic? → discover
Connect two things? → link
Work with tasks? → task (single) or tasks (multiple)

  9. Integrate NornicDB with AI Agents and IDE Copilots

    main

    NornicDB can be connected to various AI-driven workflows, including IDE copilots (like Cursor), Model Context Protocol (MCP) clients, and Heimdall agentic loops. Integration paths depend on your specific use case:

    • IDE-assisted workflows: Configure specific chat modes for tools like Cursor.
    • MCP integration: Use MCP tools and patterns to expose NornicDB capabilities to agentic clients.
    • Heimdall automation: Use Heimdall plugins and event triggers to automate remediation and agentic workflows.

  11. Explore NornicDB performance benchmarks and tuning guides

    main

    The performance documentation for NornicDB is organized into three main areas to help you evaluate, profile, and optimize your deployment:

    1. Benchmarks and Analysis

    Use these reports to compare NornicDB against other systems (like Neo4j) or to understand specific query performance:

    • Hybrid query benchmarks: Performance data for hybrid retrieval.
    • HTTP API vs Neo4j measurements: Comparative analysis of API performance.
    • Single-request benchmark: Detailed metrics for individual request latency.
    • Aggregated test results: Summary of all performance testing.
    • Benchmark comparison against Neo4j: High-level comparison documentation.

    2. Profiling and Runtime Tuning

    Use these guides to optimize the NornicDB runtime and hardware utilization:

    • pprof quick guide: Instructions for using Go's pprof tool to profile the service.
    • HTTP optimization options: Specific configurations to tune HTTP/API performance.
    • GPU capability notes: Information on leveraging GPU acceleration for improved performance.

    3. Optimization Cookbooks and Methodologies

    For practical implementation of high-performance patterns:

    • Search methodology and tuning model: Understanding how search is tuned.
    • Hot-path query cookbook: Best practices for optimizing frequently executed queries.

  12. Explore NornicDB API Interfaces

    main

    NornicDB provides multiple interfaces for interacting with the database, allowing you to choose the protocol that best fits your application's needs:

    • Cypher: Use the Cypher query language for graph-based operations. A full catalog of supported functions is available in the Cypher function index.
    • HTTP: Provides a RESTful interface that is Neo4j-compatible but includes additional Nornic extensions. You can find the human-readable reference in openapi.md or use the openapi.yaml file to generate clients.
    • Bolt: Supports the Bolt protocol for high-performance binary communication. Note that while it aims for compatibility, you should check the Bolt protocol notes and feature parity documentation if migrating from Neo4j.
    • GraphQL: Offers a flexible query language for retrieving data. A practical usage guide is available in the user guides section.