### Install and Run NornicDB Browser

Source: https://github.com/orneryd/nornicdb/blob/main/ui/README.md

Install dependencies and start the development server or build for production.

```bash
# Install dependencies
npm install

# Start development server (port 5174)
npm run dev

# Build for production
npm run build
```

--------------------------------

### Environment Setup for Training

Source: https://github.com/orneryd/nornicdb/blob/main/neural/docs/HEIMDALL_TRAINING.md

Install necessary Python packages and dependencies for training. Includes installing flash-attn for NVIDIA GPUs or setting up MPS fallback for Apple Silicon.

```bash
cd neural/
pip install -r requirements.txt

# For NVIDIA GPU
pip install flash-attn --no-build-isolation

# For Apple Silicon
export PYTORCH_ENABLE_MPS_FALLBACK=1
```

--------------------------------

### Start Qdrant with Default Configuration

Source: https://github.com/orneryd/nornicdb/blob/main/testing/benchmarks/nornic_vs_qdrant/RUN_QDRANT.md

This command starts Qdrant using its default configuration file located in the Qdrant installation directory. This is a simpler way to launch the service if no specific configuration is needed.

```bash
# Use default config (from ~/src/qdrant/config/config.yaml)
~/src/qdrant/target/release/qdrant
```

--------------------------------

### Go: Complete Feature Flag Configuration Example

Source: https://github.com/orneryd/nornicdb/blob/main/docs/features/feature-flags.md

Demonstrates checking the status of all features, enabling/disabling specific features at runtime, and integrating with the inference engine. Includes setup for WAL-backed storage.

```go
package main

import (
    "github.com/orneryd/nornicdb/pkg/config"
    "github.com/orneryd/nornicdb/pkg/inference"
    "github.com/orneryd/nornicdb/pkg/storage"
)

func main() {
    // Check current state
    status := config.GetFeatureStatus()
    
    // Tier 1 features (enabled by default)
    println("Edge Provenance:", status.EdgeProvenanceEnabled)    // true
    println("Cooldown:", status.CooldownEnabled)                  // true
    println("Evidence Buffering:", status.EvidenceBufferingEnabled) // true
    println("Per-Node Config:", status.PerNodeConfigEnabled)      // true
    println("WAL:", status.WALEnabled)                            // true
    
    // Experimental features (disabled by default)
    println("Kalman:", status.KalmanEnabled)                      // false
    println("Auto-TLP:", status.AutoTLPEnabled)                  // false
    println("GPU Clustering:", status.GPUClusteringEnabled)      // false
    println("Edge Decay:", status.EdgeDecayEnabled)              // true
    
    // Runtime configuration
    config.EnableKalmanFiltering()
    config.EnableAutoTLP()
    config.EnableGPUClustering()
    config.DisableEdgeDecay()
    
    // Disable specific feature if issues occur
    config.DisableCooldown()
    
    // Check specific feature
    if config.IsWALEnabled() {
        // Set up WAL-backed storage
        wal, _ := storage.NewWAL("/data/wal", nil)
        engine := storage.NewWALEngine(storage.NewMemoryEngine(), wal)
        _ = engine
    }
    
    // Use inference engine with auto-integration
    inferEngine := inference.New(nil)
    
    // All Tier 1 features automatically integrate:
    // - Cooldown checked before materialization
    // - Evidence accumulated before materialization
    // - Provenance logged for audit trails
    // - Per-node rules enforced
    
    result := inferEngine.ProcessSuggestion(inference.EdgeSuggestion{
        SourceID:   "node-A",
        TargetID:   "node-B",
        Type:       "RELATES_TO",
        Confidence: 0.85,
    }, "session-123")
    
    println("Should Materialize:", result.ShouldMaterialize)
    println("Cooldown Blocked:", result.CooldownBlocked)
    println("Evidence Pending:", result.EvidencePending)
    println("Node Config Blocked:", result.NodeConfigBlocked)
}
```

--------------------------------

### NornicDB Command Line Interface Examples

Source: https://github.com/orneryd/nornicdb/blob/main/macos/RELEASE_NOTES.md

Demonstrates how to start the NornicDB server manually, specify configuration files and ports, check the version, and view help.

```bash
# Start server manually
nornicdb serve

# With custom config
nornicdb serve --config ~/.nornicdb/config.yaml

# Specify ports
nornicdb serve --bolt-port 7687 --http-port 7474

# Check version
nornicdb version

# View help
nornicdb --help

```

--------------------------------

### Manual Installation of NornicDB on Raspberry Pi

Source: https://github.com/orneryd/nornicdb/blob/main/docs/packaging/raspberry-pi.md

Manually download the binary, make it executable, install it as a service, and start it. Verify the installation by checking the status endpoint.

```bash
# Download binary
curl -Lo /usr/local/bin/nornicdb \
  https://github.com/timothyswt/nornicdb/releases/latest/download/nornicdb-rpi64
chmod +x /usr/local/bin/nornicdb

# Install as service
sudo nornicdb install

# Start
sudo systemctl start nornicdb
sudo systemctl enable nornicdb

# Verify
curl http://localhost:7474/status
```

--------------------------------

### Run Setup Script

Source: https://github.com/orneryd/nornicdb/blob/main/neural/SETUP.md

Executes the setup script to prepare the environment. This script handles cloning dependencies and other initial setup tasks.

```bash
./setup.sh
```

--------------------------------

### Install qdrant-client

Source: https://github.com/orneryd/nornicdb/blob/main/docs/user-guides/qdrant-grpc.md

Install the official Python client for Qdrant.

```bash
pip install qdrant-client
```

--------------------------------

### Production Server Setup with Qdrant gRPC

Source: https://github.com/orneryd/nornicdb/blob/main/pkg/qdrantgrpc/README.md

Configure and start the Qdrant gRPC server for production use with persistent storage. Ensure the Badger engine is used for storage and the server is properly initialized with the database manager.

```go
package main

import (
    "log"
    
    "github.com/orneryd/nornicdb/pkg/qdrantgrpc"
    "github.com/orneryd/nornicdb/pkg/search"
    "github.com/orneryd/nornicdb/pkg/storage"
)

func main() {
    // Create persistent base storage (Badger for production)
    base, err := storage.NewBadgerEngine("./data")
    if err != nil {
        log.Fatal(err)
    }
    defer base.Close()

    // Create database manager (collections map to database namespaces)
    dbManager, err := multidb.NewDatabaseManager(base, nil)
    if err != nil {
        log.Fatal(err)
    }
    
    // Configure server
    config := qdrantgrpc.DefaultConfig()
    config.ListenAddr = ":6334"
    
    // Create server (collections = databases; no migration/back-compat)
    server, err := qdrantgrpc.NewServerWithDatabaseManager(config, dbManager, base, nil, nil)
    if err != nil {
        log.Fatal(err)
    }
    
    if err := server.Start(); err != nil {
        log.Fatal(err)
    }
    defer server.Stop()
    
    log.Printf("Qdrant gRPC server listening on %s", server.Addr())
    
    // Keep running...
    select {}
}
```

--------------------------------

### Homebrew Installation and Service Management

Source: https://github.com/orneryd/nornicdb/blob/main/macos/README.md

Example commands for installing NornicDB using Homebrew and managing its service. This is a planned distribution method.

```bash
brew install nornicdb
brew services start nornicdb
```

--------------------------------

### Make Setup Script Executable

Source: https://github.com/orneryd/nornicdb/blob/main/neural/SETUP.md

Makes the setup script executable. This is a prerequisite before running the setup script.

```bash
chmod +x setup.sh
```

--------------------------------

### NornicDB Installation and Service Control Quick Reference

Source: https://github.com/orneryd/nornicdb/blob/main/macos/INSTALLATION_GUIDE.md

Provides quick commands for installing, starting, stopping, and restarting the NornicDB service on macOS. Also includes shortcuts for accessing logs, configuration, and uninstallation.

```bash
# Installation
make macos-all                    # Build and install everything

# Service Control
launchctl start com.nornicdb.server
launchctl stop com.nornicdb.server
launchctl kickstart -k gui/$(id -u)/com.nornicdb.server

# Logs
tail -f /usr/local/var/log/nornicdb/stdout.log
tail -f /usr/local/var/log/nornicdb/stderr.log

# Configuration
open ~/Library/Application\ Support/NornicDB/config.yaml

# Uninstallation
./macos/scripts/uninstall.sh
```

--------------------------------

### Install Go

Source: https://github.com/orneryd/nornicdb/blob/main/macos/INSTALLATION_GUIDE.md

Install Go version 1.21 or later using Homebrew if it's not already installed. This is a prerequisite for building NornicDB.

```bash
brew install go
```

--------------------------------

### Manual launchctl Commands

Source: https://github.com/orneryd/nornicdb/blob/main/macos/FEATURES.md

Provides examples of manual launchctl commands for checking and starting the NornicDB server, contrasted with the menu bar app's functionality.

```bash
# Check status
launchctl list | grep nornicdb

# Start server
launchctl start com.nornicdb.server
```

--------------------------------

### Quick Install NornicDB

Source: https://github.com/orneryd/nornicdb/blob/main/macos/INSTALLATION_GUIDE.md

Use this one-liner for a quick and recommended installation of NornicDB. It clones the repository, builds the binary and menu bar app, and installs everything as a service.

```bash
git clone https://github.com/orneryd/nornicdb.git
cd nornicdb
make macos-all
```

--------------------------------

### Start NornicDB Server with Custom Configuration

Source: https://github.com/orneryd/nornicdb/blob/main/macos/USER_GUIDE.txt

Starts the NornicDB server using a specified configuration file.

```bash
$ nornicdb serve --config ~/.nornicdb/config.yaml
```

--------------------------------

### Typical cypher-shell Workflow with Bolt Announcement Override

Source: https://github.com/orneryd/nornicdb/blob/main/docs/operations/configuration.md

Example workflow demonstrating setting the Bolt server announcement environment variable, starting NornicDB, and connecting with cypher-shell.

```bash
export NORNICDB_BOLT_SERVER_ANNOUNCEMENT="Neo4j/5.26.0"
./nornicdb serve
cypher-shell -a bolt://localhost:7687 -u neo4j -p password
```

--------------------------------

### Install Package via Finder

Source: https://github.com/orneryd/nornicdb/blob/main/macos/BUILD_GUIDE.md

Opens the generated .pkg installer file using the macOS Finder for interactive installation.

```bash
open dist/NornicDB-*.pkg
```

--------------------------------

### Start NornicDB Server

Source: https://github.com/orneryd/nornicdb/blob/main/macos/USER_GUIDE.txt

Starts the NornicDB server with default settings.

```bash
$ nornicdb serve
```

--------------------------------

### Install Package via Command Line

Source: https://github.com/orneryd/nornicdb/blob/main/macos/BUILD_GUIDE.md

Installs the .pkg package to the target root directory using the `installer` command. Requires administrator privileges.

```bash
sudo installer -pkg dist/NornicDB-*.pkg -target /
```

--------------------------------

### Install Dependencies

Source: https://github.com/orneryd/nornicdb/blob/main/neural/README.md

Navigate to the neural directory and install required Python packages using pip.

```bash
cd neural
pip install -r requirements.txt
```

--------------------------------

### Install and Manage NornicDB via systemd Service

Source: https://github.com/orneryd/nornicdb/blob/main/docs/packaging/linux.md

This snippet shows the commands to download, install, start, enable, and check the status of the NornicDB systemd service. It's a quick way to get NornicDB running on a Linux server.

```bash
# Download and install
curl -Lo /usr/local/bin/nornicdb \
  https://github.com/timothyswt/nornicdb/releases/latest/download/nornicdb-linux-amd64
chmod +x /usr/local/bin/nornicdb

# Install systemd service
sudo nornicdb install

# Start
sudo systemctl start nornicdb
sudo systemctl enable nornicdb

# Check status
sudo systemctl status nornicdb
journalctl -u nornicdb -f
```

--------------------------------

### Debian Post-Installation Script

Source: https://github.com/orneryd/nornicdb/blob/main/docs/packaging/linux.md

This script runs after a Debian package is installed or upgraded. It handles user creation, directory setup, and service management (enabling and starting the NornicDB service).

```bash
#!/bin/bash
set -e

case "$1" in
    configure) 
        # Create system user
        if ! getent passwd nornicdb > /dev/null; then
            useradd -r -s /bin/false -d /var/lib/nornicdb nornicdb
        fi
        
        # Create directories
        mkdir -p /var/lib/nornicdb
        mkdir -p /var/log/nornicdb
        chown -R nornicdb:nornicdb /var/lib/nornicdb
        chown -R nornicdb:nornicdb /var/log/nornicdb
        
        # Enable and start service
        systemctl daemon-reload
        systemctl enable nornicdb
        systemctl start nornicdb || true
        
        echo ""
        echo "NornicDB installed successfully!"
        echo "Access at: http://localhost:7474"
        echo ""
        echo "Manage with:"
        echo "  sudo systemctl status nornicdb"
        echo "  sudo systemctl restart nornicdb"
        echo "  sudo journalctl -u nornicdb -f"
        ;;
esac

exit 0

```

--------------------------------

### Full AMD64 Vulkan+BGE Build, Push, and Run Example

Source: https://github.com/orneryd/nornicdb/blob/main/DIY.md

This example demonstrates setting registry and version, downloading the BGE model, building a Docker image with Vulkan and BGE support, pushing it to a registry, and then running it as a detached container.

```bash
# set registry and version
export REGISTRY=timothyswt
export VERSION=latest

# download BGE model
make download-bge

# build the Vulkan + BGE image
make build-amd64-vulkan-bge

# push to registry
make push-amd64-vulkan-bge

# run
docker run -d --rm -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data \
  ${REGISTRY}/nornicdb-amd64-vulkan-bge:${VERSION}
```

--------------------------------

### Build All Components and Package

Source: https://github.com/orneryd/nornicdb/blob/main/macos/BUILD_GUIDE.md

Builds the server binary, menu bar app, and the installer package in one go. Useful for a complete build cycle.

```bash
make build macos-menubar macos-package
```

--------------------------------

### Get Relationship Start Node

Source: https://github.com/orneryd/nornicdb/blob/main/docs/api-reference/cypher-functions/README.md

Retrieves the starting node of a relationship.

```cypher
RETURN startNode(r)
```

--------------------------------

### Install, Start, and Manage NornicDB with Homebrew

Source: https://github.com/orneryd/nornicdb/blob/main/docs/packaging/macos.md

Commands to install, start, check status, stop, and uninstall NornicDB using Homebrew. Ensure the Homebrew tap is added first.

```bash
# Install
brew tap timothyswt/nornicdb
brew install nornicdb

# Start as background service
brew services start nornicdb

# Check status
brew services list

# Stop
brew services stop nornicdb

# Uninstall
brew uninstall nornicdb
```

--------------------------------

### Package Documentation Example (Go)

Source: https://github.com/orneryd/nornicdb/blob/main/AGENTS.md

Illustrates package-level documentation including purpose, supported features, and example usage. Ensure all public APIs have this level of detail.

```go
// Package cypher provides Neo4j-compatible Cypher query execution for NornicDB.
//
// This package implements a Cypher query parser and executor that supports
// the core Neo4j Cypher query language features. It enables NornicDB to be
// compatible with existing Neo4j applications and tools.
//
// Supported Cypher Features:
//   - MATCH: Pattern matching with node and relationship patterns
//   - CREATE: Creating nodes and relationships
//   - MERGE: Upsert operations with ON CREATE/ON MATCH clauses
//   [... more features ...]
//
// Example Usage:
//
//	// Create executor with storage backend
//	storage := storage.NewMemoryEngine()
//	executor := cypher.NewStorageExecutor(storage)
//
//	// Execute Cypher queries
//	result, err := executor.Execute(ctx, "CREATE (n:Person {name: 'Alice'})", nil)
package cypher
```

--------------------------------

### Install librsvg for Icon Generation

Source: https://github.com/orneryd/nornicdb/blob/main/macos/Assets/README.md

Install the librsvg library using Homebrew. This is a one-time setup required for generating icons from SVG.

```bash
# Install librsvg (one-time setup)
brew install librsvg
```

--------------------------------

### Start NornicDB Server

Source: https://github.com/orneryd/nornicdb/blob/main/docs/performance/benchmarks-vs-neo4j.md

Command to start the NornicDB server. Ensure you are in the 'nornicdb' directory.

```bash
cd nornicdb && go run cmd/server/main.go
```

--------------------------------

### Go gRPC Client Example

Source: https://github.com/orneryd/nornicdb/blob/main/docs/user-guides/qdrant-grpc.md

Demonstrates searching points using the Go gRPC client with upstream Qdrant protos.

```go
package main

import (
	"context"
	"log"

	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"

	qdrant "github.com/qdrant/go-client/qdrant"
)

func main() {
	ctx := context.Background()

	conn, err := grpc.Dial("127.0.0.1:6334", grpc.WithTransportCredentials(insecure.NewCredentials()))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()

	points := qdrant.NewPointsClient(conn)

	resp, err := points.Search(ctx, &qdrant.SearchPoints{
		CollectionName: "my_vectors",
		Vector:         make([]float32, 128),
		Limit:          10,
	})
	if err != nil {
		log.Fatal(err)
	}
	_ = resp
}
```

--------------------------------

### Start NornicDB Instance

Source: https://github.com/orneryd/nornicdb/blob/main/docs/performance/test-results.md

Starts the NornicDB service using Docker Compose with the specified ARM64 configuration. Ensure Docker is installed and running.

```bash
docker compose -f docker-compose.arm64.yml up -d nornicdb
```

--------------------------------

### Build and Install NornicDB CLI

Source: https://github.com/orneryd/nornicdb/blob/main/docs/operations/cli-commands.md

Builds the NornicDB CLI binary locally or installs it globally using Go.

```bash
go build -o nornicdb ./cmd/nornicdb
# or install globally
go install ./cmd/nornicdb
```

--------------------------------

### GET /health API Response Example

Source: https://github.com/orneryd/nornicdb/blob/main/macos/docs/EMBEDDING_SERVER.md

Example response from the /health endpoint, providing status, model details, and performance metrics of the embedding server.

```json
{
  "status": "ok",
  "model": "apple-ml-embeddings-v3",
  "dimensions": 768,
  "requests_served": 42,
  "average_latency_ms": 15.3
}
```

--------------------------------

### Start NornicDB Server

Source: https://github.com/orneryd/nornicdb/blob/main/testing/benchmarks/http_write_latency/README.md

Starts the NornicDB server with pprof enabled for profiling. Alternatively, use the environment variable.

```bash
# Start server with pprof enabled (for profiling)
./nornicdb --enable-pprof --http-port 7474 --data-dir ./data/test

# Or use environment variable
NORNICDB_ENABLE_PPROF=true ./nornicdb --http-port 7474
```

--------------------------------

### Building and Deploying a Go Plugin

Source: https://github.com/orneryd/nornicdb/blob/main/docs/features/apoc-functions.md

Commands to build a Go plugin and instructions for deploying it to NornicDB, either by copying or mounting via Docker.

```bash
go build -buildmode=plugin -o apoc-ml.so plugin_ml.go
```

```bash
# Copy to plugins directory
cp apoc-ml.so /opt/nornicdb/plugins/

# Or mount in Docker
docker run -v ./apoc-ml.so:/plugins/apoc-ml.so \
           -e NORNICDB_PLUGINS_DIR=/plugins \
           nornicdb/nornicdb
```

--------------------------------

### macOS Vulkan SDK Setup

Source: https://github.com/orneryd/nornicdb/blob/main/pkg/gpu/vulkan/BUILD.md

Installs the Vulkan SDK using Homebrew or sets environment variables for manual installation. This is required for macOS builds with Vulkan support.

```bash
# Install Vulkan SDK via Homebrew
brew install vulkan-sdk

# Or download from LunarG and set environment variables
export VULKAN_SDK=/path/to/vulkan-sdk
export CGO_CFLAGS="-I$VULKAN_SDK/include"
export CGO_LDFLAGS="-L$VULKAN_SDK/lib -lvulkan"
```

--------------------------------

### Driver Connection String Examples

Source: https://github.com/orneryd/nornicdb/blob/main/docs/architecture/multi-db-implementation-spec.md

Shows how to connect to the default database or a specific database using the driver connection string.

```python
# Default database
driver = GraphDatabase.driver("bolt://localhost:7687")

# Specific database
driver = GraphDatabase.driver(
    "bolt://localhost:7687",
    database="tenant_a"
)

# Or per-session
session = driver.session(database="tenant_a")
```

--------------------------------

### Storage Engine Key Examples

Source: https://github.com/orneryd/nornicdb/blob/main/docs/architecture/multi-db-implementation-spec.md

Shows example keys within the single BadgerDB instance, demonstrating how different databases and object types are distinguished using prefixes.

```text
Keys: tenant_a:node:123    tenant_b:node:789    nornic:node:001         
      tenant_a:edge:456    tenant_b:edge:012    nornic:edge:002         
      system:db:tenant_a   system:db:tenant_b   system:db:nornic        
```

--------------------------------

### Full Raspberry Pi Installation Script

Source: https://github.com/orneryd/nornicdb/blob/main/docs/packaging/raspberry-pi.md

This script automates the detection of Raspberry Pi architecture, downloads the appropriate NornicDB binary, installs it, sets up the systemd service, and starts NornicDB. It includes checks for memory and provides feedback on the installation status.

```bash
#!/bin/bash
set -e

echo "╔══════════════════════════════════════════════════════════════╗"
echo "║           NornicDB Raspberry Pi Installer                    ║"
echo "╚══════════════════════════════════════════════════════════════╝"

# Detect architecture
ARCH=$(uname -m)
case $ARCH in
    aarch64) 
        BINARY="nornicdb-rpi64"
        ;;
    armv7l) 
        BINARY="nornicdb-rpi32"
        ;;
    armv6l) 
        BINARY="nornicdb-rpi-zero"
        ;;
    *) 
        echo "Unsupported architecture: $ARCH"
        exit 1
        ;;
esac

echo "Detected: $ARCH → $BINARY"

# Check available memory
MEM_MB=$(free -m | awk '/^Mem:/{print $2}')
if [ "$MEM_MB" -lt 512 ]; then
    echo "⚠️  Warning: Less than 512MB RAM detected"
    echo "   NornicDB may have limited functionality"
fi

# Download
VERSION=${NORNICDB_VERSION:-"latest"}
URL="https://github.com/timothyswt/nornicdb/releases/${VERSION}/download/${BINARY}"

echo "Downloading NornicDB..."
curl -Lo /tmp/nornicdb "$URL"
chmod +x /tmp/nornicdb

# Install
echo "Installing to /usr/local/bin/nornicdb..."
sudo mv /tmp/nornicdb /usr/local/bin/nornicdb

# Create user and directories
echo "Setting up service user and directories..."
sudo useradd -r -s /bin/false nornicdb 2>/dev/null || true
sudo mkdir -p /var/lib/nornicdb
sudo mkdir -p /var/log/nornicdb
sudo chown -R nornicdb:nornicdb /var/lib/nornicdb
sudo chown -R nornicdb:nornicdb /var/log/nornicdb

# Install systemd service
echo "Installing systemd service..."
sudo tee /etc/systemd/system/nornicdb.service > /dev/null << 'EOF'
[Unit]
Description=NornicDB Graph Database
After=network.target

[Service]
Type=simple
User=nornicdb
Group=nornicdb
ExecStart=/usr/local/bin/nornicdb serve --data-dir /var/lib/nornicdb
Restart=on-failure
RestartSec=5

# Pi-optimized memory limits
MemoryMax=75%
MemoryHigh=60%

# File limits
LimitNOFILE=65536

Environment=NORNICDB_LOG_LEVEL=info
Environment=GOMAXPROCS=4

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable nornicdb
sudo systemctl start nornicdb

# Wait for startup
sleep 3

# Verify
if curl -s http://localhost:7474/status | grep -q "ok"; then
    echo ""
    echo "╔══════════════════════════════════════════════════════════════╗"
    echo "║  ✓ NornicDB installed successfully!                         ║"
    echo "╠══════════════════════════════════════════════════════════════╣"
    echo "║  Web UI:    http://$(hostname -I | awk '{print $1}'):7474    ║"
    echo "║  Bolt:      bolt://$(hostname -I | awk '{print $1}'):7687    ║"
    echo "║                                                              ║"
    echo "║  Commands:                                                   ║"
    echo "║    sudo systemctl status nornicdb                            ║"
    echo "║    sudo journalctl -u nornicdb -f                            ║"
    echo "╚══════════════════════════════════════════════════════════════╝"
else
    echo "⚠️  NornicDB installed but may not be running"
    echo "   Check: sudo systemctl status nornicdb"
fi
```

--------------------------------

### Start NornicDB Server with MCP Disabled

Source: https://github.com/orneryd/nornicdb/blob/main/docs/architecture/system-design.md

Start the NornicDB server with the MCP (Multi-Cluster Protocol) feature disabled using a CLI flag. This is useful if you are not using NornicDB in a multi-cluster setup.

```bash
./nornicdb serve --mcp-enabled=false
```

--------------------------------

### Complete NornicDB Setup Script

Source: https://github.com/orneryd/nornicdb/blob/main/neural/SETUP.md

A comprehensive bash script to set up the NornicDB neural training environment. It checks Python, creates a virtual environment, installs PyTorch based on hardware detection, installs dependencies, optionally installs Flash Attention, and creates the data directory.

```bash
#!/bin/bash
set -e

echo "🚀 Setting up NornicDB Neural Training Environment"

# Check Python version
if ! command -v python3 &> /dev/null; then
    echo "❌ Python 3 not found. Please install Python 3.8+"
    exit 1
fi

PYTHON_VERSION=$(python3 --version | cut -d' ' -f2 | cut -d'.' -f1,2)
echo "✓ Python $PYTHON_VERSION detected"

# Navigate to neural directory
cd "$(dirname "$0")"

# Create virtual environment
echo "📦 Creating virtual environment..."
python3 -m venv venv

# Activate virtual environment
echo "🔌 Activating virtual environment..."
source venv/bin/activate

# Upgrade pip
echo "⬆️  Upgrading pip..."
pip install --upgrade pip

# Detect platform and install PyTorch
echo "🔍 Detecting hardware..."
if [[ "$OSTYPE" == "darwin"* ]]; then
    # macOS
    if sysctl -n machdep.cpu.brand_string | grep -q "Apple"; then
        echo "🍎 Apple Silicon detected - installing PyTorch with MPS support"
        pip install torch torchvision torchaudio
        export PYTORCH_ENABLE_MPS_FALLBACK=1
    else
        echo "🍎 Intel Mac detected - installing CPU-only PyTorch"
        pip install torch torchvision torchaudio
    fi
elif command -v nvidia-smi &> /dev/null; then
    echo "🎮 NVIDIA GPU detected - installing PyTorch with CUDA"
    pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
else
    echo "💻 No GPU detected - installing CPU-only PyTorch"
    pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
fi

# Install dependencies
echo "📚 Installing dependencies..."
pip install -r requirements.txt

# Try to install flash-attention (may fail on non-CUDA systems)
if command -v nvidia-smi &> /dev/null; then
    echo "⚡ Installing Flash Attention 2..."
    pip install flash-attn --no-build-isolation || echo "⚠️  Flash Attention install failed (not critical)"
fi

# Create data directory
echo "📁 Creating data directory..."
mkdir -p data

```

--------------------------------

### Quick Test: Check Presets and Estimate Memory

Source: https://github.com/orneryd/nornicdb/blob/main/neural/SETUP.md

Tests the installation by checking available presets and estimating memory requirements for a specific model.

```bash
python train.py --help
```

```bash
python train.py --preset heimdall --estimate_memory
```

--------------------------------

### Start Small Training

Source: https://github.com/orneryd/nornicdb/blob/main/neural/docs/QUICK_REFERENCE.md

Begin training with a small subset of data for initial testing.

```bash
python train.py --dataset data/training.jsonl --max_samples 100 --epochs 1
```

--------------------------------

### NornicDB Startup Plugin Logs

Source: https://github.com/orneryd/nornicdb/blob/main/docs/user-guides/plugin-system.md

Example of NornicDB's startup logs showing loaded plugins and their details.

```text
🔌 Loading Plugins from /app/plugins...
  ✓ apoc.so: 964 functions loaded (v1.0.0)
  ✓ my-plugin.so: 2 functions loaded (v1.0.0)
📦 Total: 966 plugin functions available
```

--------------------------------

### Docker Compose Basic Setup

Source: https://github.com/orneryd/nornicdb/blob/main/docs/getting-started/docker-deployment.md

Defines a basic Docker Compose setup for NornicDB, including persistent volumes for data and logs, port mappings, and a health check. This is a starting point for more complex configurations.

```yaml
version: "3.8"

services:
  nornicdb:
    image: timothyswt/nornicdb-arm64-metal-bge:latest
    container_name: nornicdb
    ports:
      - "7474:7474" # HTTP API
      - "7687:7687" # Bolt protocol
    volumes:
      - nornicdb-data:/data
      - nornicdb-logs:/logs
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7474/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

volumes:
  nornicdb-data:
  nornicdb-logs:
```

--------------------------------

### Authorization Endpoint Request

Source: https://github.com/orneryd/nornicdb/blob/main/cmd/oauth-provider/README.md

Example GET request to the authorization endpoint for initiating the OAuth 2.0 flow.

```http
GET /oauth2/v1/authorize?response_type=code&client_id=...&redirect_uri=...&state=...
```

--------------------------------

### Start Qdrant with a Specific Configuration

Source: https://github.com/orneryd/nornicdb/blob/main/testing/benchmarks/nornic_vs_qdrant/RUN_QDRANT.md

This command starts the Qdrant service using a custom configuration file. It specifies the Qdrant executable path and the configuration file path. The service will be accessible via REST and gRPC on default ports, with isolated storage and disabled telemetry.

```bash
cd ~/src/NornicDB
~/src/qdrant/target/release/qdrant \
  --config-path testing/benchmarks/nornic_vs_qdrant/qdrant-bench.yaml
```

--------------------------------

### Health Check Endpoint Request

Source: https://github.com/orneryd/nornicdb/blob/main/cmd/oauth-provider/README.md

Example GET request to the health endpoint to check the server's status.

```http
GET /health
```

--------------------------------

### Full Lifecycle Plugin Example

Source: https://github.com/orneryd/nornicdb/blob/main/docs/user-guides/heimdall-plugins.md

An example implementation of a plugin that satisfies the FullLifecycleHook interface, demonstrating the structure for PrePrompt, PreExecute, PostExecute, and OnDatabaseEvent hooks.

```go
// Implement all hooks (convenience interface)
var _ heimdall.FullLifecycleHook = (*MyPlugin)(nil)

type MyPlugin struct {
    // ... your fields ...
}

func (p *MyPlugin) PrePrompt(ctx *heimdall.PromptContext) error {
    ctx.NotifyInfo("Processing", "Preparing your request...")
    return nil
}

func (p *MyPlugin) PreExecute(ctx *heimdall.PreExecuteContext, done func(heimdall.PreExecuteResult)) {
    // Synchronous validation
    done(heimdall.PreExecuteResult{})
}

func (p *MyPlugin) PostExecute(ctx *heimdall.PostExecuteContext) {
    log.Printf("Action %s completed in %v", ctx.Action.Action, ctx.Duration)
}

func (p *MyPlugin) OnDatabaseEvent(event *heimdall.DatabaseEvent) {
    // React to database operations
}
```

--------------------------------

### Manual CUDA Library Setup with yzma

Source: https://github.com/orneryd/nornicdb/blob/main/docs/getting-started/windows-cuda.md

Manually install yzma and download CUDA-optimized llama.cpp libraries to a specified directory.

```powershell
go install github.com/hybridgroup/yzma/cmd/yzma@latest
yzma install --lib .\lib\llama --processor cuda
```

--------------------------------

### Discovery Endpoint Request

Source: https://github.com/orneryd/nornicdb/blob/main/cmd/oauth-provider/README.md

Example GET request to the discovery endpoint to fetch OAuth 2.0 metadata for automatic configuration.

```http
GET /.well-known/oauth-authorization-server
```

--------------------------------

### Go gRPC Client for Qdrant

Source: https://github.com/orneryd/nornicdb/blob/main/docs/skills/grpc.skill.md

Shows how to initialize a Go gRPC client and perform operations like listing collections and scrolling points. Requires `github.com/qdrant/go-client`.

```go
import (
    "context"
    "github.com/qdrant/go-client/qdrant"
)

client, _ := qdrant.NewClient(&qdrant.Config{
    Host:   "localhost",
    Port:   6334,
    UseTLS: false,
})

collections, _ := client.ListCollections(ctx)

scroll, _ := client.Scroll(ctx, &qdrant.ScrollPoints{
    CollectionName: "docs",
    Limit:          qdrant.PtrOf(uint32(100)),
    WithPayload:    qdrant.NewWithPayload(true),
    WithVectors:    qdrant.NewWithVectors(true),
})
for _, p := range scroll {
    _ = p
}
```

--------------------------------

### Userinfo Endpoint Request

Source: https://github.com/orneryd/nornicdb/blob/main/cmd/oauth-provider/README.md

Example GET request to the userinfo endpoint to retrieve profile data using an access token.

```http
GET /oauth2/v1/userinfo
Authorization: Bearer <access_token>
```

--------------------------------

### Storage Layout Example

Source: https://github.com/orneryd/nornicdb/blob/main/docs/architecture/multi-db-implementation-spec.md

Shows how data is organized on disk using BadgerDB keys, prefixed by database names.

```text
BadgerDB Keys:
├── nornic:node:*              # Default database nodes
├── nornic:edge:*              # Default database edges
├── nornic:idx:*               # Default database indexes
├── tenant_a:node:*           # Tenant A nodes
├── tenant_a:edge:*           # Tenant A edges
├── tenant_b:node:*           # Tenant B nodes
├── tenant_b:edge:*           # Tenant B edges
└── system:node:databases:*   # Database metadata
```

--------------------------------

### Get neighbors within N hops

Source: https://github.com/orneryd/nornicdb/blob/main/docs/user-guides/graph-traversal.md

Retrieve all neighbors within N hops from a starting node using the `apoc.neighbors.tohop` procedure.

```cypher
MATCH (startNode)
CALL apoc.neighbors.tohop(startNode, 'FOLLOWS', 3)
YIELD node
RETURN node
```

--------------------------------

### Install NornicDB Binary and Directories

Source: https://github.com/orneryd/nornicdb/blob/main/docs/operations/deployment.md

Install the NornicDB binary to the system path and create necessary directories for data and configuration, setting appropriate ownership.

```bash
# Copy binary
sudo cp bin/nornicdb /usr/local/bin/

# Create data directory
sudo mkdir -p /var/lib/nornicdb
sudo chown nornicdb:nornicdb /var/lib/nornicdb

# Create config directory
sudo mkdir -p /etc/nornicdb
```

--------------------------------

### Linux Vulkan Setup

Source: https://github.com/orneryd/nornicdb/blob/main/pkg/gpu/vulkan/BUILD.md

Installs necessary Vulkan packages on Ubuntu/Debian or Fedora. It also shows how to set environment variables for the Vulkan SDK.

```bash
# Ubuntu/Debian
sudo apt install vulkan-tools libvulkan-dev vulkan-validationlayers

# Fedora
sudo dnf install vulkan-tools vulkan-loader-devel vulkan-validation-layers

# Set environment variables
export VULKAN_SDK=/path/to/vulkan-sdk  # If using SDK
export CGO_CFLAGS="-I$VULKAN_SDK/include"
export CGO_LDFLAGS="-L$VULKAN_SDK/lib -lvulkan"
```

--------------------------------

### Go Example for Text Query

Source: https://github.com/orneryd/nornicdb/blob/main/pkg/qdrantgrpc/README.md

A practical Go code example demonstrating how to perform a text-based search query using the gRPC client for the Qdrant API.

```APIDOC
### Go Example (direct gRPC call)

```go
conn, _ := grpc.Dial(addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
defer conn.Close()

points := qdrant.NewPointsClient(conn)

resp, err := points.Query(ctx, &qdrant.QueryPoints{
    CollectionName: "my_collection",
    Limit:          10,
    Query: &qdrant.Query{
        Variant: &qdrant.Query_Nearest{
            Nearest: &qdrant.VectorInput{
                Variant: &qdrant.VectorInput_Document{
                    Document: &qdrant.Document{Text: "database performance"},
                },
            },
        },
    },
    WithPayload: &qdrant.WithPayloadSelector{
        SelectorOptions: &qdrant.WithPayloadSelector_Enable{Enable: true},
    },
})
if err != nil {
    // handle error
}
_ = resp
```
```

--------------------------------

### Download Starter Dataset

Source: https://github.com/orneryd/nornicdb/blob/main/neural/docs/PERFECT_TRAINING_DATA.md

Use curl to download a pre-made starter dataset for Cypher.

```bash
curl -o data/cypher_starter.jsonl https://raw.githubusercontent.com/orneryd/NornicDB/main/neural/data/examples/cypher_starter.jsonl
```

--------------------------------

### Chocolatey Package Management Commands

Source: https://github.com/orneryd/nornicdb/blob/main/docs/packaging/windows.md

Common PowerShell commands for installing, starting, checking status, and uninstalling the NornicDB service using Chocolatey.

```powershell
# Install
choco install nornicdb

# Start service
Start-Service NornicDB

# Check status
Get-Service NornicDB

# Uninstall
choco uninstall nornicdb
```

--------------------------------

### macOS Service Management with brew services

Source: https://github.com/orneryd/nornicdb/blob/main/docs/packaging/macos.md

Commands to manage the NornicDB service if it was installed via Homebrew. Includes starting, stopping, and restarting the service.

```bash
# Using brew services (if installed via Homebrew)
brew services start nornicdb
brew services stop nornicdb
brew services restart nornicdb
```

--------------------------------

### Build and Install Plugin

Source: https://github.com/orneryd/nornicdb/blob/main/docs/user-guides/plugin-system.md

Commands to build the Go plugin and copy it to the NornicDB plugins directory.

```bash
# Build the plugin (must use same Go version as NornicDB)
go build -buildmode=plugin -o my-plugin.so my_plugin.go

# Copy to plugins directory
cp my-plugin.so /path/to/nornicdb/plugins/
```

--------------------------------

### Quick Start Docker Deployment

Source: https://github.com/orneryd/nornicdb/blob/main/docs/operations/deployment.md

Run NornicDB in a Docker container for a quick setup. This command maps ports and mounts a volume for data persistence.

```bash
docker run -d \
  --name nornicdb \
  -p 7474:7474 \
  -p 7687:7687 \
  -v nornicdb-data:/data \
  -e NORNICDB_ADDRESS=0.0.0.0 \
  timothyswt/nornicdb-arm64-metal:latest
```

--------------------------------

### Go Package Comments

Source: https://github.com/orneryd/nornicdb/blob/main/docs/development/code-style.md

Example of how to write package-level documentation comments in Go.

```go
// Package nornicdb provides a graph database with memory decay.
//
// NornicDB implements a Neo4j-compatible graph database with
// vector search and automatic memory management.
package nornicdb
```

--------------------------------

### Reranking Configuration

Source: https://github.com/orneryd/nornicdb/blob/main/docs/skills/rag-procedures.skill.md

Example bash commands to enable and configure the reranking provider for NornicDB search. This setup is typically done in the environment where NornicDB is running.

```bash
# Hybrid + adaptive RRF — no extra config; on by default
# Reranking
export NORNICDB_SEARCH_RERANK_ENABLED=true
export NORNICDB_SEARCH_RERANK_PROVIDER=local      # local | ollama | openai | http
export NORNICDB_SEARCH_RERANK_MODEL=bge-reranker-v2-m3-Q4_K_M.gguf
export NORNICDB_SEARCH_RERANK_API_URL=...         # for provider=http (Cohere, TEI, ...)
export NORNICDB_SEARCH_RERANK_API_KEY=...
```

--------------------------------

### Practical Example: Social Network Setup

Source: https://github.com/orneryd/nornicdb/blob/main/docs/getting-started/first-queries.md

Creates multiple 'Person' nodes and establishes 'FRIENDS_WITH' relationships between them, including relationship properties like 'since'.

```cypher
// Create people
CREATE 
  (alice:Person {name: "Alice", age: 30}),
  (bob:Person {name: "Bob", age: 35}),
  (carol:Person {name: "Carol", age: 28}),
  (dave:Person {name: "Dave", age: 32})

// Create friendships
CREATE
  (alice)-[:FRIENDS_WITH {since: 2020}]->(bob),
  (alice)-[:FRIENDS_WITH {since: 2019}]->(carol),
  (bob)-[:FRIENDS_WITH {since: 2021}]->(dave),
  (carol)-[:FRIENDS_WITH {since: 2020}]->(dave)

RETURN *

```

--------------------------------

### Go Implementation for NornicDB Service Installation

Source: https://github.com/orneryd/nornicdb/blob/main/docs/packaging/linux.md

This Go code snippet illustrates the implementation details for the `nornicdb install` command. It covers creating the necessary user, directories, setting ownership, writing the systemd unit file, and reloading the systemd daemon.

```go
func installService() error {
    // Create user
    exec.Command("useradd", "-r", "-s", "/bin/false", "nornicdb").Run()
    
    // Create directories
    os.MkdirAll("/var/lib/nornicdb", 0755)
    os.MkdirAll("/var/log/nornicdb", 0755)
    exec.Command("chown", "-R", "nornicdb:nornicdb", "/var/lib/nornicdb").Run()
    exec.Command("chown", "-R", "nornicdb:nornicdb", "/var/log/nornicdb").Run()
    
    // Install systemd unit
    serviceFile := `[Unit]
Description=NornicDB Graph Database
...
`
    ioutil.WriteFile("/etc/systemd/system/nornicdb.service", []byte(serviceFile), 0644)
    
    // Reload systemd
    exec.Command("systemctl", "daemon-reload").Run()
    
    fmt.Println("✓ NornicDB service installed")
    fmt.Println("  Start with: sudo systemctl start nornicdb")
    fmt.Println("  Enable on boot: sudo systemctl enable nornicdb")
    return nil
}
```

--------------------------------

### Get ANTLR Go Module

Source: https://github.com/orneryd/nornicdb/blob/main/pkg/cypher/antlr/README.md

Install or update the ANTLR Go module to resolve the 'no required module provides package github.com/antlr4-go/antlr/v4' error.

```bash
go get github.com/antlr4-go/antlr/v4
```

--------------------------------

### Querying Array Properties

Source: https://github.com/orneryd/nornicdb/blob/main/docs/user-guides/property-data-types.md

Provides examples of querying array properties, including checking for value existence, accessing elements, and getting array size.

```cypher
// Check if value is in array
MATCH (n:Person)
WHERE "developer" IN n.tags
RETURN n
```

```cypher
// Access array elements
MATCH (n:Person)
RETURN n.scores[0] AS firstScore
```

```cypher
// Array length
MATCH (n:Person)
RETURN size(n.tags) AS tagCount
```

--------------------------------

### Example Session: User Authentication

Source: https://github.com/orneryd/nornicdb/blob/main/docs/ai-agents/chat-modes.md

Demonstrates a typical agent interaction for adding user authentication to a Go API, including memory checks, task creation, linking, and storing decisions.

```markdown
User: "I need to add user authentication to our Go API"

Agent: Discovering similar work in memory...
→ discover(query="user authentication Go API")
← Found: node-892 "JWT implementation pattern"
node-893 "Go middleware authentication"

"Found 2 related items:

- JWT implementation pattern (node-892)
- Go middleware auth (node-893)

Creating a task to track this work..."

→ task(title="Implement user authentication", description="Add JWT-based auth to Go API", priority="high")
← task-456 created

→ link(from="task-456", to="node-892", relation="implements")
← edge created

"Created task-456: Implement user authentication

- Linked to existing JWT pattern (node-892)
- Status: pending
- Priority: high

Based on node-892, I recommend using the middleware pattern with JWT tokens.
Shall I start implementation?"

User: "Yes, go ahead"

Agent: Starting work on task-456...
→ task(id="task-456", status="active")

[... implementation work ...]

→ store(content="Implemented JWT auth using RS256 with 24h token expiry. Middleware validates Bearer tokens and adds user context to request.", type="decision", tags=["auth", "jwt", "go"])
← node-897 created

→ link(from="node-897", to="task-456", relation="implements")
← edge created

→ task(id="task-456", status="done")

"Task completed! Stored the implementation decision as node-897 for future reference."
```

--------------------------------

### RAG (Retrieval-Augmented Generation) Example

Source: https://github.com/orneryd/nornicdb/blob/main/docs/user-guides/vector-search.md

Demonstrates a typical RAG workflow: searching for context, building a context string, and generating a response with LLM.

```go
results, _ := db.Search(ctx, userQuery, nil, 5)

context := ""
for _, r := range results {
    context += r.Content + "\n"
}

response := llm.Generate(userQuery, context)
```

--------------------------------

### Test Server Binary Directly

Source: https://github.com/orneryd/nornicdb/blob/main/macos/BUILD_GUIDE.md

Builds the server binary and then runs it directly from the command line, specifying a data directory for testing. This bypasses the installer.

```bash
make build
./bin/nornicdb serve --data-dir ./test-data
```

--------------------------------

### Discovery Probe Example

Source: https://github.com/orneryd/nornicdb/blob/main/docs/operations/configuration.md

A simple GET request to the Bolt port serves as a discovery probe. This works without any special configuration and is useful for health checks.

```http
GET /

```

--------------------------------

### Test Bolt Server with Python Driver

Source: https://github.com/orneryd/nornicdb/blob/main/pkg/bolt/README.md

Starts the Bolt server in one terminal and runs a Python script to test its functionality in another. Requires the neo4j-driver to be installed.

```bash
# Terminal 1: Start server
cd cmd/nornicdb-bolt
go run main.go

# Terminal 2: Run Python test
pip install neo4j-driver
python3 << EOF
from neo4j import GraphDatabase
driver = GraphDatabase.driver("bolt://localhost:7687")
with driver.session() as session:
    result = session.run("CREATE (n:Test {id: 1}) RETURN n")
    print("Success:", result.single()[0])
driver.close()
EOF
```

--------------------------------

### Benchmark Query Optimization in Go

Source: https://github.com/orneryd/nornicdb/blob/main/AGENTS.md

Demonstrates how to document performance improvements with benchmarks. This example shows a before-and-after comparison of query optimization, including metrics for operations per second and memory usage.

```go
// ❌ BAD: No proof of improvement
func optimizeQuery() { /* new algorithm */ }

// ✅ GOOD: Benchmarked and documented
// BenchmarkQueryOptimization shows 2.3x speedup:
//   Before: 4,252 ops/sec
//   After:  9,780 ops/sec
//   Memory: -15% (reduced allocations)
func optimizeQuery() { /* new algorithm with proof */ }
```

--------------------------------

### Start and Verify Raft Cluster

Source: https://github.com/orneryd/nornicdb/blob/main/docs/user-guides/clustering.md

Commands to launch the Docker Compose setup and confirm cluster health. Includes a delay for leader election and health checks for each node.

```bash
docker compose -f docker-compose.raft.yml up -d

# Wait for leader election
sleep 5

# Verify each node responds
for port in 7474 7475 7476; do
  curl -s http://localhost:$port/health
done

```