rust-kgdb

AI Answers You Can Trust

The Problem: LLMs hallucinate. They make up facts, invent data, and confidently state falsehoods. In regulated industries (finance, healthcare, legal), this is not just annoying—it's a liability.

The Solution: HyperMind grounds every AI answer in YOUR actual data. Every response includes a complete audit trail. Same question = Same answer = Same proof.

Results

Models tested: Claude Sonnet 4 (90.9%), GPT-4o (81.8%)

Full Benchmark Report →

Quick Start

Installation

npm install rust-kgdb

Platforms: macOS (Intel/Apple Silicon), Linux (x64/ARM64), Windows (x64)

Basic Usage (5 Lines)

const { GraphDB } = require('rust-kgdb')

const db = new GraphDB('http://example.org/')
db.loadTtl(':alice :knows :bob .', null)
const results = db.querySelect('SELECT ?who WHERE { ?who :knows :bob }')
console.log(results)  // [{ bindings: { who: 'http://example.org/alice' } }]

Complete Example with AI Agent

const { GraphDB, HyperMindAgent, createSchemaAwareGraphDB } = require('rust-kgdb')

// Load your data
const db = createSchemaAwareGraphDB('http://insurance.org/')
db.loadTtl(`
  @prefix : <http://insurance.org/> .
  :CLM001 a :Claim ; :amount "50000" ; :provider :PROV001 .
  :PROV001 a :Provider ; :riskScore "0.87" ; :name "MedCorp" .
`, null)

// Create AI agent
const agent = new HyperMindAgent({
  kg: db,
  model: 'gpt-4o',
  apiKey: process.env.OPENAI_API_KEY
})

// Ask questions in plain English
const result = await agent.call('Find high-risk providers')

// Every answer includes:
// - The SPARQL query that was generated
// - The data that was retrieved
// - A reasoning trace showing how the conclusion was reached
// - A cryptographic hash for reproducibility
console.log(result.answer)
console.log(result.reasoningTrace)  // Full audit trail

Use Cases

Fraud Detection

const agent = new HyperMindAgent({
  kg: insuranceDB,
  name: 'fraud-detector',
  model: 'claude-3-opus'
})

const result = await agent.call('Find providers with suspicious billing patterns')
// Returns: List of providers with complete evidence trail
// - SPARQL queries executed
// - Rules that matched
// - Similar entities found via embeddings

Regulatory Compliance

const agent = new HyperMindAgent({
  kg: complianceDB,
  scope: { allowedGraphs: ['http://compliance.org/'] }  // Restrict access
})

const result = await agent.call('Check GDPR compliance for customer data flows')
// Returns: Compliance status with verifiable reasoning chain

Risk Assessment

const result = await agent.call('Calculate risk score for entity P001')
// Returns: Risk score with complete derivation
// - Which data points were used
// - Which rules were applied
// - Confidence intervals

Features

Core Database

• SPARQL 1.1 - Full query and update support (64 builtin functions)
• RDF 1.2 - Complete W3C standard implementation
• RDF-Star - Statements about statements
• Hypergraph - N-ary relationships beyond triples

Graph Analytics

• PageRank - Iterative ranking algorithm
• Connected Components - Community detection
• Shortest Paths - Path finding
• Triangle Count - Graph density
• Motif Finding - Pattern matching

AI Agent Framework

• Schema-Aware - Auto-extracts schema from your data
• Typed Tools - Input/output validation prevents errors
• Audit Trail - Every answer is traceable
• Memory - Working, episodic, and long-term memory

Performance

• 2.78 µs lookup speed (35x faster than RDFox)
• 146K triples/sec bulk insert
• 24 bytes/triple memory efficiency

How It Works

HyperMind combines two approaches:

1. Neural (LLM): Understands your question in natural language
2. Symbolic (Database): Executes precise queries against your data

Your Question → LLM Plans Query → Database Executes → Verified Answer
     ↓                ↓                  ↓                 ↓
"Find fraud"   SELECT ?x WHERE...   47 results      "Provider P001
                                                     is suspicious"
                                                     + reasoning trace
                                                     + audit hash

The LLM plans WHAT to look for. The database finds EXACTLY that. Every answer traces back to actual data. No hallucination possible.

API Reference

GraphDB

class GraphDB {
  constructor(appGraphUri: string)
  loadTtl(ttlContent: string, graphName: string | null): void
  querySelect(sparql: string): QueryResult[]
  query(sparql: string): TripleResult[]
  countTriples(): number
  clear(): void
}

HyperMindAgent

class HyperMindAgent {
  constructor(options: {
    kg: GraphDB,           // Your knowledge graph
    model?: string,        // 'gpt-4o' | 'claude-3-opus' | etc.
    apiKey?: string,       // LLM API key
    memory?: MemoryManager,
    scope?: AgentScope,
    embeddings?: EmbeddingService
  })

  call(prompt: string): Promise<AgentResponse>
}

interface AgentResponse {
  answer: string
  reasoningTrace: ReasoningStep[]  // Audit trail
  hash: string                      // Reproducibility hash
}

GraphFrame

class GraphFrame {
  constructor(verticesJson: string, edgesJson: string)
  pageRank(resetProb: number, maxIter: number): string
  connectedComponents(): string
  shortestPaths(landmarks: string[]): string
  triangleCount(): number
  find(pattern: string): string  // Motif pattern matching
}

EmbeddingService

class EmbeddingService {
  storeVector(entityId: string, vector: number[]): void
  findSimilar(entityId: string, k: number, threshold: number): string
  rebuildIndex(): void
}

DatalogProgram

class DatalogProgram {
  addFact(factJson: string): void
  addRule(ruleJson: string): void
}

function evaluateDatalog(program: DatalogProgram): string
function queryDatalog(program: DatalogProgram, query: string): string

More Examples

Knowledge Graph

const { GraphDB } = require('rust-kgdb')

const db = new GraphDB('http://example.org/')
db.loadTtl(`
  @prefix : <http://example.org/> .
  :alice :knows :bob .
  :bob :knows :charlie .
  :charlie :knows :alice .
`, null)

console.log(`Loaded ${db.countTriples()} triples`)  // 3

const results = db.querySelect(`
  PREFIX : <http://example.org/>
  SELECT ?person WHERE { ?person :knows :bob }
`)
console.log(results)  // [{ bindings: { person: 'http://example.org/alice' } }]

Graph Analytics

const { GraphFrame } = require('rust-kgdb')

const graph = new GraphFrame(
  JSON.stringify([{id:'alice'}, {id:'bob'}, {id:'charlie'}]),
  JSON.stringify([
    {src:'alice', dst:'bob'},
    {src:'bob', dst:'charlie'},
    {src:'charlie', dst:'alice'}
  ])
)

console.log('Triangles:', graph.triangleCount())  // 1
console.log('PageRank:', JSON.parse(graph.pageRank(0.15, 20)))
console.log('Components:', JSON.parse(graph.connectedComponents()))

Rule-Based Reasoning

const { DatalogProgram, evaluateDatalog } = require('rust-kgdb')

const program = new DatalogProgram()
program.addFact(JSON.stringify({predicate: 'parent', terms: ['alice', 'bob']}))
program.addFact(JSON.stringify({predicate: 'parent', terms: ['bob', 'charlie']}))

// grandparent(X, Z) :- parent(X, Y), parent(Y, Z)
program.addRule(JSON.stringify({
  head: {predicate: 'grandparent', terms: ['?X', '?Z']},
  body: [
    {predicate: 'parent', terms: ['?X', '?Y']},
    {predicate: 'parent', terms: ['?Y', '?Z']}
  ]
}))

console.log('Inferred:', JSON.parse(evaluateDatalog(program)))
// grandparent(alice, charlie)

Semantic Similarity

const { EmbeddingService } = require('rust-kgdb')

const embeddings = new EmbeddingService()

// Store 384-dimension vectors
embeddings.storeVector('claim_001', new Array(384).fill(0.5))
embeddings.storeVector('claim_002', new Array(384).fill(0.6))
embeddings.rebuildIndex()

// HNSW similarity search
const similar = JSON.parse(embeddings.findSimilar('claim_001', 5, 0.7))
console.log('Similar:', similar)

Benchmarks

Performance (Measured)

Industry Comparison

AI Agent Accuracy

W3C Standards Compliance

Running Tests

npm test           # 42 feature tests
npm run test:jest  # 217 unit tests

Links

• npm: rust-kgdb
• GitHub: gonnect-uk/rust-kgdb
• Benchmark Report: HYPERMIND_BENCHMARK_REPORT.md
• Changelog: CHANGELOG.md

Advanced Topics

For those interested in the technical foundations of why HyperMind achieves deterministic AI reasoning.

Why It Works: The Technical Foundation

HyperMind's reliability comes from three mathematical foundations:

The Reasoning Trace (Audit Trail)

Every HyperMind answer includes a cryptographically-signed derivation showing exactly how the conclusion was reached:

┌─────────────────────────────────────────────────────────────────────────────┐
│                           REASONING TRACE                                    │
│                                                                              │
│                    ┌────────────────────────────────┐                       │
│                    │      CONCLUSION (Root)         │                       │
│                    │  "Provider P001 is suspicious" │                       │
│                    │  Confidence: 94%               │                       │
│                    └───────────────┬────────────────┘                       │
│                                    │                                        │
│                    ┌───────────────┼───────────────┐                       │
│                    │               │               │                       │
│                    ▼               ▼               ▼                       │
│      ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐       │
│      │  Database Query  │ │ Rule Application │ │ Similarity Match │       │
│      │                  │ │                  │ │                  │       │
│      │ Tool: SPARQL     │ │ Tool: Datalog    │ │ Tool: Embeddings │       │
│      │ Result: 47 claims│ │ Result: MATCHED  │ │ Result: 87%      │       │
│      │ Time: 2.3ms      │ │ Rule: fraud(?P)  │ │ similar to known │       │
│      └──────────────────┘ └──────────────────┘ └──────────────────┘       │
│                                                                              │
│      HASH: sha256:8f3a2b1c4d5e...  (Reproducible, Auditable, Verifiable)   │
└─────────────────────────────────────────────────────────────────────────────┘

For Academics: Mathematical Foundations

HyperMind is built on rigorous mathematical foundations:

• Context Theory (Spivak's Ologs): Schema represented as a category where objects are classes and morphisms are properties
• Type Theory (Hindley-Milner): Every tool has a typed signature enabling compile-time validation
• Proof Theory (Curry-Howard): Proofs are programs, types are propositions - every conclusion has a derivation
• Category Theory: Tools as morphisms with validated composition

These foundations ensure that HyperMind transforms probabilistic LLM outputs into deterministic, verifiable reasoning chains.

Architecture Layers

┌─────────────────────────────────────────────────────────────────────────────┐
│                    INTELLIGENCE CONTROL PLANE                                │
│                                                                              │
│   ┌────────────────┐   ┌────────────────┐   ┌────────────────┐             │
│   │ Schema         │   │ Tool           │   │ Reasoning      │             │
│   │ Awareness      │   │ Validation     │   │ Trace          │             │
│   └───────┬────────┘   └───────┬────────┘   └───────┬────────┘             │
│           └────────────────────┼────────────────────┘                       │
│                                ▼                                            │
│   ┌─────────────────────────────────────────────────────────────────────┐  │
│   │                      HYPERMIND AGENT                                 │  │
│   │  User Query → LLM Planner → Typed Execution Plan → Tools → Answer   │  │
│   └─────────────────────────────────────────────────────────────────────┘  │
│                                ▼                                            │
│   ┌─────────────────────────────────────────────────────────────────────┐  │
│   │                      rust-kgdb ENGINE                                │  │
│   │  • GraphDB (SPARQL 1.1)    • GraphFrames (Analytics)                │  │
│   │  • Datalog (Rules)         • Embeddings (Similarity)                │  │
│   └─────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

Security Model

HyperMind includes capability-based security:

const agent = new HyperMindAgent({
  kg: db,
  scope: new AgentScope({
    allowedGraphs: ['http://insurance.org/'],  // Restrict graph access
    allowedPredicates: ['amount', 'provider'], // Restrict predicates
    maxResultSize: 1000                        // Limit result size
  }),
  sandbox: {
    capabilities: ['ReadKG', 'ExecuteTool'],   // No WriteKG = read-only
    fuelLimit: 1_000_000                       // CPU budget
  }
})

Memory System

Agents have persistent memory across sessions:

const agent = new HyperMindAgent({
  kg: db,
  memory: new MemoryManager({
    workingMemorySize: 10,           // Current session cache
    episodicRetentionDays: 30,       // Episode history
    longTermGraph: 'http://memory/'  // Persistent knowledge
  })
})

License

Apache 2.0