rust-kgdb 0.6.55 → 0.6.57

package/README.md

@@ -4,2004 +4,959 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![W3C](https://img.shields.io/badge/W3C-SPARQL%201.1%20%7C%20RDF%201.2-blue)](https://www.w3.org/TR/sparql11-query/)
 
-## What Is This?
-
-### Have You Ever Wondered Why AI Agents Keep Lying?
-
-Here's the uncomfortable truth: **LLMs don't know your data**. They've read Wikipedia, Stack Overflow, and half the internet - but they've never seen your customer records, your claims database, or your internal knowledge graph.
-
-So when you ask "find suspicious providers," they do what humans do when they don't know the answer: **they make something up that sounds plausible**.
-
-The industry's response? "Add more guardrails!" "Use RAG!" "Fine-tune on your data!"
+---
 
-We asked a different question: **What if the AI couldn't lie even if it wanted to?**
+## The Trillion-Dollar Mistake
 
-Not through prompting. Not through fine-tuning. Through **architecture**.
+A lawyer asks AI: *"Has this contract clause ever been challenged in court?"*
 
-### The Insight That Changes Everything
+AI responds: *"Yes, in Smith v. Johnson (2019), the court ruled..."*
 
-What if instead of asking an LLM to generate answers, we asked it to generate **database queries**?
+The lawyer cites it. The judge looks confused. **That case doesn't exist.** The AI invented it.
 
-The LLM doesn't need to know your data. It just needs to know:
-1. What questions can be asked (your schema)
-2. How to ask them (SPARQL/Datalog syntax)
+This isn't rare. It happens every day:
 
-Then a **real database** - with your actual data - executes the query and returns facts. Not hallucinations. Facts.
+**In Healthcare:**
+> Doctor: "What drugs interact with this patient's current medications?"
+> AI: "Avoid combining with Nexapril due to cardiac risks."
+> *Nexapril isn't a real drug.*
 
-```
-User: "Find suspicious providers"
-         ↓
-LLM generates: SELECT ?provider WHERE { ?provider :riskScore ?s . FILTER(?s > 0.8) }
-         ↓
-Database executes: Scans 47M triples in 449ns per lookup
-         ↓
-Returns: [PROV001, PROV847, PROV2201] ← These actually exist in YOUR data
-```
+**In Insurance:**
+> Claims Adjuster: "Has this provider shown suspicious billing patterns?"
+> AI: "Provider #4521 has a history of duplicate billing..."
+> *Provider #4521 has a perfect record.*
 
-**The AI suggests what to look for. The database finds exactly that. No hallucination possible.**
+**In Fraud Detection:**
+> Analyst: "Find transactions that look like money laundering."
+> AI: "Account ending 7842 shows classic layering behavior..."
+> *That account belongs to a charity. Now you've falsely accused them.*
 
-### But Wait - Where's the Database?
+**The AI doesn't know your data. It guesses. And it sounds confident while lying.**
 
-Here's where it gets interesting. Traditional approach:
-- Install Virtuoso/RDFox/Neo4j server
-- Configure connections
-- Pay for licenses
-- Hire a DBA
-
-Our approach: **The database is embedded in your app.**
+---
 
-```bash
-npm install rust-kgdb  # That's it. You now have a full SPARQL database.
-```
+## What Is rust-kgdb?
 
-47.2MB native addon. Zero configuration. 449ns lookups. Embedded like SQLite, powerful like RDFox.
+**Two components, one npm package:**
 
----
+### 1. rust-kgdb Core: Embedded Knowledge Graph Database
 
-**rust-kgdb** is two layers in one package:
+A high-performance RDF/SPARQL database that runs **inside your application**. No server. No Docker. No config.
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────────┐
-│                         YOUR APPLICATION                                     │
-└─────────────────────────────────┬───────────────────────────────────────────┘
-                                  │
-┌─────────────────────────────────▼───────────────────────────────────────────┐
-│  HYPERMIND AGENT FRAMEWORK (JavaScript)                                      │
+│                         rust-kgdb CORE ENGINE                                │
+│                                                                              │
 │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
-│  │ LLMPlanner  │  │ MemoryMgr   │  │ WASM        │  │ ProofDAG    │        │
-│  │ (Schema-    │  │ (Working/   │  │ Sandbox     │  │ (Audit      │        │
-│  │  Aware)     │  │  Episodic)  │  │ (Secure)    │  │  Trail)     │        │
+│  │   GraphDB   │  │ GraphFrame  │  │  Embeddings │  │   Datalog   │        │
+│  │  (SPARQL)   │  │ (Analytics) │  │   (HNSW)    │  │ (Reasoning) │        │
+│  │  449ns      │  │  PageRank   │  │  16ms/10K   │  │  Semi-naive │        │
 │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘        │
-└─────────────────────────────────┬───────────────────────────────────────────┘
-                                  │ NAPI-RS (zero-copy)
-┌─────────────────────────────────▼───────────────────────────────────────────┐
-│  RUST CORE (Native Performance)                                              │
-│  ┌──────────────────────────────────────────────────────────────────────┐   │
-│  │ QUERY ENGINE                                                          │   │
-│  │ • SPARQL 1.1 (449ns lookups)   • WCOJ Joins (worst-case optimal)     │   │
-│  │ • Datalog (semi-naive eval)    • Sparse Matrix (CSR/CSC reasoning)   │   │
-│  └──────────────────────────────────────────────────────────────────────┘   │
-│  ┌──────────────────────────────────────────────────────────────────────┐   │
-│  │ GRAPH ANALYTICS                                                       │   │
-│  │ • GraphFrames (PageRank, Components, Triangles, Motifs)              │   │
-│  │ • Pregel BSP (Bulk Synchronous Parallel)                             │   │
-│  │ • Shortest Paths, Label Propagation                                  │   │
-│  └──────────────────────────────────────────────────────────────────────┘   │
-│  ┌──────────────────────────────────────────────────────────────────────┐   │
-│  │ VECTOR & RETRIEVAL                                                    │   │
-│  │ • HNSW Index (O(log N) ANN)    • ARCADE 1-Hop Cache (O(1) neighbors) │   │
-│  │ • Multi-provider Embeddings    • RRF Reranking                       │   │
-│  └──────────────────────────────────────────────────────────────────────┘   │
-│  ┌──────────────────────────────────────────────────────────────────────┐   │
-│  │ STORAGE                                                               │   │
-│  │ • InMemory (dev)  • RocksDB (prod)  • LMDB (read-heavy)              │   │
-│  │ • SPOC/POCS/OCSP/CSPO Indexes   • 24 bytes/triple                    │   │
-│  └──────────────────────────────────────────────────────────────────────┘   │
+│                                                                              │
+│  Storage: InMemory | RocksDB | LMDB    Standards: SPARQL 1.1 | RDF 1.2     │
+│  Memory: 24 bytes/triple               Compliance: SHACL | PROV | OWL 2 RL │
 └─────────────────────────────────────────────────────────────────────────────┘
 ```
 
-### Layer 1: Rust Core (Native Performance)
-
-| Component | What It Does | Performance |
-|-----------|--------------|-------------|
-| **SPARQL 1.1** | W3C-compliant query engine, 64 builtin functions | 449ns lookups |
-| **RDF 1.2** | RDF-Star (quoted triples), TriG, N-Quads | W3C compliant |
-| **SHACL** | W3C Shapes Constraint Language validation | Constraint engine |
-| **PROV** | W3C Provenance ontology support | Audit trail |
-| **WCOJ Joins** | Worst-case optimal joins for multi-way patterns | O(N^(ρ/2)) |
-| **Datalog** | Semi-naive evaluation with recursion | Incremental |
-| **Sparse Matrix** | CSR/CSC-based reasoning for OWL 2 RL | Memory-efficient |
-| **GraphFrames** | PageRank, components, triangles, motifs | Parallel |
-| **Pregel** | Bulk Synchronous Parallel graph processing | Superstep-based |
-| **HNSW** | Hierarchical Navigable Small World index | O(log N) |
-| **ARCADE Cache** | 1-hop neighbor pre-caching | O(1) context |
-| **Storage** | InMemory, RocksDB, LMDB backends | 24 bytes/triple |
-
-**Scalability Numbers (Verified Benchmark)**:
-
-| Operation | 1 Worker | 16 Workers | Scaling |
-|-----------|----------|------------|---------|
-| Concurrent Writes | 66K ops/sec | 132K ops/sec | 2.0x |
-| GraphFrame Analytics | 6.0K ops/sec | 6.5K ops/sec | Thread-safe |
-| Memory per Triple | 24 bytes | 24 bytes | Constant |
-
-Reproduce: `node concurrency-benchmark.js`
-
-### Layer 2: HyperMind Agent Framework (JavaScript)
-
-| Component | What It Does |
-|-----------|--------------|
-| **LLMPlanner** | Schema-aware query generation (auto-extracts from data) |
-| **MemoryManager** | Working memory + episodic memory + long-term KG |
-| **WASM Sandbox** | Secure execution with capability-based permissions |
-| **ProofDAG** | Audit trail with cryptographic hash for reproducibility |
-| **TypedTools** | Input/output validation prevents hallucination |
-
-### WASM Sandbox Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  WASM SANDBOX (Secure Agent Execution)                                       │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  ┌─────────────────────┐    ┌─────────────────────┐    ┌────────────────┐  │
-│  │ CAPABILITIES        │    │ FUEL METERING       │    │ AUDIT LOG      │  │
-│  │ • ReadKG            │    │ • CPU budget limit  │    │ • Every action │  │
-│  │ • ExecuteTool       │    │ • Prevents infinite │    │ • Timestamps   │  │
-│  │ • WriteKG (opt)     │    │   loops             │    │ • Arguments    │  │
-│  └─────────────────────┘    └─────────────────────┘    └────────────────┘  │
-│                                                                             │
-│  Agent Code → WASM Runtime → Capability Check → Tool Execution → Audit     │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
+**Like SQLite - but for knowledge graphs.**
 
-**Think of it as**: A knowledge graph database (Rust, native performance) with an AI agent runtime (JavaScript, WASM-sandboxed) on top. The database provides ground truth. The runtime makes it accessible via natural language with full security and audit trails.
+### 2. HyperMind: Neuro-Symbolic Agent Framework
 
-### Game Changer: Embedded Database (No Installation)
+An AI agent layer that uses **the database to prevent hallucinations**. The LLM plans, the database executes.
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────────┐
-│  TRADITIONAL APPROACH                                                        │
-│  ───────────────────────                                                    │
-│  Your App → HTTP/gRPC → Database Server → Disk                              │
-│                                                                             │
-│  • Install database server (RDFox, Virtuoso, Neo4j)                         │
-│  • Configure connections, ports, authentication                             │
-│  • Network latency on every query                                           │
-│  • DevOps overhead for maintenance                                          │
-└─────────────────────────────────────────────────────────────────────────────┘
-
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  rust-kgdb: EMBEDDED                                                        │
-│  ──────────────────────                                                     │
-│  Your App ← contains → rust-kgdb (native addon)                             │
-│                                                                             │
-│  • npm install rust-kgdb - that's it                                        │
-│  • No server, no Docker, no configuration                                   │
-│  • Zero network latency (same process)                                      │
-│  • Deploy as single binary                                                  │
+│                      HYPERMIND AGENT FRAMEWORK                               │
+│                                                                              │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
+│  │ LLMPlanner  │  │ WasmSandbox │  │ ProofDAG    │  │   Memory    │        │
+│  │ (Claude/GPT)│  │ (Security)  │  │ (Audit)     │  │ (Hypergraph)│        │
+│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘        │
+│                                                                              │
+│  Type Theory: Hindley-Milner types ensure tool composition is valid         │
+│  Category Theory: Tools are morphisms (A → B) with composition laws         │
+│  Proof Theory: Every execution produces cryptographic audit trail           │
 └─────────────────────────────────────────────────────────────────────────────┘
 ```
 
-**Why This Matters**:
-- **SQLite for RDF**: Like SQLite replaced MySQL for embedded use cases
-- **449ns lookups**: No network roundtrip - direct memory access
-- **Ship as one file**: Your app + database = single deployable
-
-**Scale When You Need To**: Start embedded, scale to cluster when required:
-```
-Embedded (single node)  →  Clustered (distributed)
-     npm install             K8s deployment
-     No config               HDRF partitioning
-     Millions of triples     Billions of triples
-```
+**The insight:** AI writes questions (SPARQL queries). Database finds answers. No hallucination possible.
 
 ---
 
-## Mathematical Foundations: Why This Actually Works
-
-### The Problem with LLM Tool Calling
-
-Here's a dirty secret about AI agents: **most tool calls are prayers**.
-
-The LLM generates a function call, hopes the types match, and if it fails? Retry and pray harder. This is why production AI systems feel brittle.
-
-We took a different approach: **make incorrect tool calls impossible to express**.
-
-### Category Theory: Not Academic Masturbation
-
-When you hear "category theory," you probably think of mathematicians drawing commutative diagrams that no one understands. Here's why it actually matters for AI agents:
-
-```
-Every tool is a morphism: InputType → OutputType
-
-kg.sparql.query : Query → BindingSet
-kg.motif.find   : Pattern → Matches
-kg.datalog.run  : Rules → InferredFacts
-```
-
-**The key insight**: If the LLM can only compose morphisms where types align, it *cannot* hallucinate invalid tool chains. It's not about "being careful" - it's about making mistakes unrepresentable.
-
-```javascript
-// This composition type-checks: Query → BindingSet → Aggregation
-planner.compose(sparqlQuery, aggregator)  // ✅ Valid
+## Quick Start
 
-// This doesn't even compile conceptually
-planner.compose(sparqlQuery, imageGenerator)  // ❌ Type error
+```bash
+npm install rust-kgdb
 ```
 
-### Curry-Howard: Proofs You Can Execute
-
-The **Curry-Howard correspondence** says something profound: **proofs and programs are the same thing**.
-
-In our system:
-- A valid reasoning trace IS a mathematical proof that the answer is correct
-- The type signature of a tool IS a proposition about what it transforms
-- Composing tools IS constructing a proof by implication
+### Basic Database Usage
 
 ```javascript
-result.proofDAG = {
-  // This isn't just logging - it's a PROOF OBJECT
-  steps: [
-    { tool: 'kg.sparql.query', proves: '∃ provider P001 with 47 claims' },
-    { tool: 'kg.datalog.rule', proves: 'P001 ∈ highRisk (by rule R3)' }
-  ],
-  hash: 'sha256:8f3a...',  // Same proof = same hash, always
-  valid: true               // Type-checked, therefore valid
-}
-```
-
-**Why this matters for compliance**: When a regulator asks "why did you flag this provider?", you don't show them chat logs. You show them a mathematical proof.
+const { GraphDB } = require('rust-kgdb');
 
-### WCOJ: When O(N²) is Unacceptable
+// Create embedded database (no server needed!)
+const db = new GraphDB('http://lawfirm.com/');
 
-Finding triangles in a graph (A→B→C→A) seems simple. The naive approach:
-1. For each edge A→B
-2. For each edge B→C
-3. Check if C→A exists
-
-That's O(N²) - fine for toy graphs, death for production.
-
-**Worst-Case Optimal Joins** (LeapFrog TrieJoin) do something clever:
-- Organize edges in tries by (subject, predicate, object)
-- Traverse all three tries simultaneously
-- Skip entire branches that can't possibly match
-
-```
-Traditional: O(N²) for triangle query
-WCOJ:        O(N^(ρ/2)) where ρ = fractional edge cover number
+// Load your data
+db.loadTtl(`
+  :Contract_2024_001 :hasClause :NonCompete_3yr .
+  :NonCompete_3yr :challengedIn :Martinez_v_Apex .
+  :Martinez_v_Apex :court "9th Circuit" ; :year 2021 .
+`);
 
-For triangles: ρ = 1.5, so O(N^0.75) vs O(N²)
-At 1M edges: 31K operations vs 1T operations
+// Query with SPARQL (449ns lookups)
+const results = db.querySelect(`
+  SELECT ?case ?court WHERE {
+    :NonCompete_3yr :challengedIn ?case .
+    ?case :court ?court
+  }
+`);
+// [{case: ':Martinez_v_Apex', court: '9th Circuit'}]
 ```
 
-### Sparse Matrix: Why Your RAM Doesn't Explode
-
-A knowledge graph with 1M entities has a 1M × 1M adjacency matrix. That's 1 trillion cells. At 8 bytes each: 8 terabytes. For one matrix.
-
-**CSR (Compressed Sparse Row)** stores only non-zero entries:
-- Real graphs are ~99.99% sparse
-- 1M entities with 10M edges = 10M entries, not 1T
-- Transitive closure becomes matrix multiplication: A* = I + A + A² + ...
-
-```
-rdfs:subClassOf closure in OWL:
-Dense:  Impossible (terabytes of memory)
-CSR:    Seconds (megabytes of memory)
-```
+### With HyperMind Agent
 
-### Semi-Naive Datalog: Don't Repeat Yourself
+```javascript
+const { GraphDB, HyperMindAgent } = require('rust-kgdb');
 
-Recursive rules need fixpoint iteration. The naive way recomputes everything:
+const db = new GraphDB('http://insurance.org/');
+db.loadTtl(`
+  :Provider_445 :totalClaims 89 ; :avgClaimAmount 47000 ; :denialRate 0.34 .
+  :Provider_445 :hasPattern :UnbundledBilling ; :flaggedBy :SIU_2024_Q1 .
+`);
 
-```
-Iteration 1: Compute ALL ancestor relationships
-Iteration 2: Compute ALL ancestor relationships again  ← wasteful
-Iteration 3: Compute ALL ancestor relationships again  ← really wasteful
-```
+const agent = new HyperMindAgent({ db });
+const result = await agent.ask("Which providers show suspicious billing patterns?");
 
-**Semi-naive evaluation**: Only derive facts using NEW facts from the previous iteration.
+console.log(result.answer);
+// "Provider_445: 34% denial rate, flagged by SIU Q1 2024, unbundled billing pattern"
 
+console.log(result.evidence);
+// Full audit trail proving every fact came from your database
 ```
-Iteration 1: Direct parents (new: 1000 facts)
-Iteration 2: Use only those 1000 new facts → grandparents (new: 800)
-Iteration 3: Use only those 800 new facts → great-grandparents (new: 400)
-...converges in O(depth) iterations, not O(facts)
-```
-
-### HNSW: O(log N) Similarity in a World of Vectors
 
-Finding the nearest neighbor in a million vectors should take a million comparisons. It doesn't have to.
+---
 
-**HNSW** builds a navigable graph where:
-- Top layers have few nodes with long-range connections
-- Bottom layers have all nodes with local connections
-- Search: Start at top, greedily descend, refine at bottom
+## Architecture: Two Layers
 
 ```
-Layer 2:  ●───────────────────●  (sparse, long jumps)
-          │                   │
-Layer 1:  ●────●────●────●────●  (medium density)
-          │    │    │    │    │
-Layer 0:  ●─●─●─●─●─●─●─●─●─●─●  (all nodes, local connections)
-
-Search path: Start top-left, jump to approximate region, refine locally
-Result: O(log N) comparisons, ~95% recall
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                           YOUR APPLICATION                                       │
+│                 (Fraud Detection, Underwriting, Compliance)                      │
+└────────────────────────────────────┬────────────────────────────────────────────┘
+                                     │
+┌────────────────────────────────────▼────────────────────────────────────────────┐
+│                    HYPERMIND AGENT FRAMEWORK (JavaScript)                        │
+│  ┌────────────────────────────────────────────────────────────────────────────┐ │
+│  │  • LLMPlanner: Natural language → typed tool pipelines                     │ │
+│  │  • WasmSandbox: Capability-based security with fuel metering               │ │
+│  │  • ProofDAG: Cryptographic audit trail (SHA-256)                           │ │
+│  │  • MemoryHypergraph: Temporal agent memory with KG integration             │ │
+│  │  • TypeId: Hindley-Milner type system with refinement types                │ │
+│  └────────────────────────────────────────────────────────────────────────────┘ │
+│                                                                                  │
+│                    Category Theory: Tools as Morphisms (A → B)                   │
+│                    Proof Theory: Every execution has a witness                   │
+└────────────────────────────────────┬────────────────────────────────────────────┘
+                                     │ NAPI-RS Bindings
+┌────────────────────────────────────▼────────────────────────────────────────────┐
+│                    RUST CORE ENGINE (Native Performance)                         │
+│  ┌────────────────────────────────────────────────────────────────────────────┐ │
+│  │  GraphDB          │ RDF/SPARQL quad store   │ 449ns lookups, 24 bytes/triple│
+│  │  GraphFrame       │ Graph algorithms        │ WCOJ optimal joins, PageRank  │
+│  │  EmbeddingService │ Vector similarity       │ HNSW index, 1-hop ARCADE cache│
+│  │  DatalogProgram   │ Rule-based reasoning    │ Semi-naive evaluation         │
+│  │  Pregel           │ BSP graph processing    │ Billion-edge scale            │
+│  └────────────────────────────────────────────────────────────────────────────┘ │
+│                                                                                  │
+│  W3C Standards: SPARQL 1.1 (100%) | RDF 1.2 | OWL 2 RL | SHACL | PROV           │
+│  Storage Backends: InMemory | RocksDB | LMDB                                     │
+└──────────────────────────────────────────────────────────────────────────────────┘
 ```
 
-**Why this matters**: When your agent needs "similar past queries," it doesn't scan 10,000 embeddings. It finds the top 10 in 16 milliseconds.
-
----
-
-## Core Concepts: What We Bring and Why
-
-### 1. Schema-Aware Query Generation
-**Problem**: LLMs generate SPARQL with made-up predicates (`?person :fakeProperty ?value`).
-**Solution**: We auto-extract your schema and inject it into prompts. The LLM can ONLY reference predicates that actually exist in your data.
-
-### 2. Built-in Database (Not BYODB)
-**Problem**: LangChain/DSPy generate queries, but you need to find a database to run them.
-**Solution**: rust-kgdb IS the database. Generate query → Execute query → Return results. All in one package.
-
-### 3. Audit Trail (Provenance)
-**Problem**: LLM says "Provider P001 is suspicious" - where did that come from?
-**Solution**: Every answer includes a reasoning trace showing which SPARQL queries ran, which rules matched, and what data was found.
-
-### 4. Deterministic Execution
-**Problem**: Ask the same question twice, get different answers.
-**Solution**: Same input → Same query → Same database → Same result → Same hash. Reproducible for compliance.
-
-### 5. ARCADE 1-Hop Cache
-**Problem**: Embedding lookups are slow when you need neighborhood context.
-**Solution**: Pre-cache 1-hop neighbors. When you find "Provider", instantly know its outgoing predicates (hasRiskScore, hasClaim) without another query.
-
----
-
-## 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 (Verified December 2025)
-
-### Benchmark Methodology
-
-**Dataset**: [LUBM (Lehigh University Benchmark)](http://swat.cse.lehigh.edu/projects/lubm/) - the industry-standard benchmark for RDF/SPARQL systems since 2005. Used by RDFox, Virtuoso, Jena, and all major triple stores.
-
-**Setup**:
-- 3,272 triples, 30 OWL classes, 23 properties
-- 7 query types: attribute (A1-A3), statistical (S1-S2), multi-hop (M1), existence (E1)
-- Model: GPT-4o with real API calls (no mocking)
-- Reproducible: `python3 benchmark-frameworks.py`
-
-**Evaluation Criteria**:
-- Query must parse (no markdown, no explanation text)
-- Query must use correct ontology terms (e.g., `ub:Professor` not `ub:Faculty`)
-- Query must return expected result count
-
-### Honest Framework Comparison
-
-**Important**: HyperMind and LangChain/DSPy are **different product categories**.
-
-| Category | HyperMind | LangChain/DSPy |
-|----------|-----------|----------------|
-| **What It Is** | GraphDB + Agent Framework | LLM Orchestration Library |
-| **Core Function** | Execute queries on data | Chain LLM prompts |
-| **Data Storage** | Built-in QuadStore | None (BYODB) |
-| **Query Execution** | Native SPARQL/Datalog | External DB needed |
-| **Agent Memory** | Built-in (Working + Episodic + KG-backed) | External vector DB needed |
-| **Deep Flashback** | 94% Recall@10 at 10K query depth (16.7ms) | Limited by external provider |
-
-**Why Agent Memory Matters**: We can retrieve relevant past queries from 10,000+ history entries with 94% accuracy in 16.7ms. This enables "flashback" to any past interaction - LangChain/DSPy require external vector DBs for this capability.
-
-**Built-in Capabilities (No External Dependencies)**:
-
-| Capability | HyperMind | LangChain/DSPy |
-|------------|-----------|----------------|
-| **Recursive Reasoning** | Datalog semi-naive evaluation (native) | Manual implementation needed |
-| **Graph Propagation** | Pregel BSP (PageRank, shortest paths) | External library (NetworkX) |
-| **Multi-way Joins** | WCOJ algorithm O(N^(ρ/2)) | No native support |
-| **Pattern Matching** | Motif DSL `(a)-[]->(b); (b)-[]->(c)` | Manual graph traversal |
-| **OWL 2 RL Reasoning** | Sparse matrix CSR/CSC (native) | External reasoner needed |
-| **Vector Similarity** | HNSW + ARCADE 1-hop cache | External vector DB (Pinecone, etc.) |
-| **Transitive Closure** | `ancestor(?X,?Z) :- parent(?X,?Y), ancestor(?Y,?Z)` | Loop implementation |
-| **RDF-Star** | Native quoted triples (RDF 1.2) | Not supported |
-| **Data Validation** | SHACL constraints (W3C) | External validator needed |
-| **Provenance Tracking** | W3C PROV ontology (native) | Manual implementation |
+## Core Components
 
-**Database Performance (vs Industry Leaders)**:
+### GraphDB: SPARQL Engine (449ns lookups)
 
-| Metric | HyperMind | Comparison |
-|--------|-----------|------------|
-| **Triple Lookup** | 449 ns | 35x faster than RDFox |
-| **Memory/Triple** | 24 bytes | 25% less than RDFox |
-| **Concurrent Writes** | 132K ops/sec | Thread-safe at scale |
-
-**What Each Is Good For**:
-
-- **HyperMind**: When you need a knowledge graph database WITH agent capabilities. Deterministic execution, audit trails, graph analytics.
-- **LangChain**: When you need to orchestrate multiple LLM calls with prompts. Flexible, extensive integrations.
-- **DSPy**: When you need to optimize prompts programmatically. Research-focused.
-
-### Our Unique Approach: ARCADE 1-Hop Cache
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  TEXT → INTENT → EMBEDDING → NEIGHBORS → ACCURATE SPARQL                    │
-│  (The ARCADE Pipeline)                                                      │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  1. TEXT INPUT                                                              │
-│     "Find high-risk providers"                                              │
-│                          ↓                                                  │
-│  2. INTENT CLASSIFICATION (Deterministic keyword matching)                  │
-│     Intent: QUERY_ENTITIES                                                  │
-│     Domain: insurance, Entity: provider, Filter: high-risk                  │
-│                          ↓                                                  │
-│  3. EMBEDDING LOOKUP (HNSW index, 449ns)                                    │
-│     Query: "provider" → Vector [0.23, 0.87, ...]                            │
-│     Similar entities: [:Provider, :Vendor, :Supplier]                       │
-│                          ↓                                                  │
-│  4. 1-HOP NEIGHBOR RETRIEVAL (ARCADE Cache)                                 │
-│     :Provider → outgoing: [:hasRiskScore, :hasClaim, :worksFor]             │
-│     :Provider → incoming: [:submittedBy, :reviewedBy]                       │
-│     Cache hit: O(1) lookup, no SPARQL needed                                │
-│                          ↓                                                  │
-│  5. SCHEMA-AWARE SPARQL GENERATION                                          │
-│     Available predicates: {hasRiskScore, hasClaim, worksFor}                │
-│     Filter mapping: "high-risk" → ?score > 0.7                              │
-│     Generated: SELECT ?p WHERE { ?p :hasRiskScore ?s . FILTER(?s > 0.7) }   │
-│                                                                             │
-├─────────────────────────────────────────────────────────────────────────────┤
-│  WHY THIS WORKS:                                                            │
-│  • Step 2: NO LLM needed - deterministic pattern matching                   │
-│  • Step 3: Embedding similarity finds related concepts                      │
-│  • Step 4: ARCADE cache provides schema context in O(1)                     │
-│  • Step 5: Schema injection ensures only valid predicates used              │
-│                                                                             │
-│  ARCADE = Adaptive Retrieval Cache for Approximate Dense Embeddings         │
-│  Paper: https://arxiv.org/abs/2104.08663                                    │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
-**Embedding Trigger Setup** (automatic on triple insert):
 ```javascript
-const { EmbeddingService, GraphDB } = require('rust-kgdb')
+const { GraphDB } = require('rust-kgdb');
 
-const db = new GraphDB('http://example.org/')
-const embeddings = new EmbeddingService()
+const db = new GraphDB('http://example.org/');
 
-// On every triple insert, embedding cache is updated
-db.loadTtl(':Provider123 :hasRiskScore "0.87" .', null)
-// Triggers: embeddings.onTripleInsert('Provider123', 'hasRiskScore', '0.87', null)
-// 1-hop cache updated: Provider123 → outgoing: [hasRiskScore]
-```
+// Load Turtle format
+db.loadTtl(':alice :knows :bob . :bob :knows :charlie .');
 
-### End-to-End Capability Benchmark
+// SPARQL SELECT
+const results = db.querySelect('SELECT ?x WHERE { :alice :knows ?x }');
 
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  CAPABILITY COMPARISON: What Can Actually Execute on Data                   │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  Capability                    │ HyperMind │ LangChain/DSPy                 │
-│  ─────────────────────────────────────────────────────────                  │
-│  Generate Motif Pattern        │    ✅    │      ✅                         │
-│  Generate Datalog Rules        │    ✅    │      ✅                         │
-│  Execute Motif on Data         │    ✅    │      ❌ (no DB)                 │
-│  Execute Datalog Rules         │    ✅    │      ❌ (no DB)                 │
-│  Execute SPARQL Queries        │    ✅    │      ❌ (no DB)                 │
-│  GraphFrame Analytics          │    ✅    │      ❌ (no DB)                 │
-│  Deterministic Results         │    ✅    │      ❌                         │
-│  Audit Trail/Provenance        │    ✅    │      ❌                         │
-│  ─────────────────────────────────────────────────────────                  │
-│  TOTAL                         │   8/8    │     2/8                         │
-│                                                                             │
-│  NOTE: LangChain/DSPy CAN execute on data if you integrate a database.     │
-│  HyperMind has the database BUILT-IN.                                       │
-│                                                                             │
-│  Reproduce: node benchmark-e2e-execution.js                                 │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
-### Memory Retrieval Depth Benchmark
-
-Based on academic benchmarks: MemQ (arXiv 2503.05193), mKGQAgent (Text2SPARQL 2025), MTEB.
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  BENCHMARK: Memory Retrieval at Depth (50 queries per depth)                │
-│  METHODOLOGY: LUBM schema-driven queries, HNSW index, random seed 42        │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  DEPTH     │ P50 LATENCY  │ P95 LATENCY  │ Recall@5 │ Recall@10 │   MRR    │
-│  ──────────────────────────────────────────────────────────────────────────│
-│      10    │    0.06 ms   │    0.26 ms   │   78%    │   100%    │  0.68    │
-│     100    │    0.50 ms   │    0.75 ms   │   88%    │    98%    │  0.42    │
-│   1,000    │    1.59 ms   │    5.03 ms   │   80%    │    94%    │  0.50    │
-│  10,000    │   16.71 ms   │   17.37 ms   │   76%    │    94%    │  0.54    │
-│  ──────────────────────────────────────────────────────────────────────────│
-│                                                                             │
-│  KEY INSIGHT: Even at 10,000 stored queries, Recall@10 stays at 94%        │
-│  Sub-17ms retrieval from 10K query pool = practical for production use     │
-│                                                                             │
-│  Reproduce: node memory-retrieval-benchmark.js                              │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
+// SPARQL CONSTRUCT
+const graph = db.queryConstruct('CONSTRUCT { ?x :connected ?y } WHERE { ?x :knows ?y }');
 
-### Where We Actually Outperform (Database Performance)
+// Named graphs
+db.loadTtl(':data1 :value "100" .', 'http://example.org/graph1');
 
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  BENCHMARK: Triple Store Performance (vs Industry Leaders)                  │
-│  METHODOLOGY: Criterion.rs statistical benchmarking, LUBM dataset           │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  METRIC              rust-kgdb      RDFox         Jena          Neo4j       │
-│  ─────────────────────────────────────────────────────────────              │
-│  Lookup Speed        449 ns         ~5 µs         ~150 µs       ~5 µs       │
-│  Memory/Triple       24 bytes       36-89 bytes   50-60 bytes   70+ bytes   │
-│  Bulk Insert         146K/sec       ~200K/sec     ~50K/sec      ~100K/sec   │
-│  Concurrent Writes   132K/sec       N/A           N/A           N/A         │
-│  ─────────────────────────────────────────────────────────────              │
-│                                                                             │
-│  ADVANTAGE: 35x faster lookups than RDFox, 25% less memory                  │
-│  THIS IS WHERE WE GENUINELY WIN - raw database performance.                 │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
+// Count triples
+console.log(`Total: ${db.countTriples()} triples`);
 ```
 
-### SPARQL Generation (Honest Assessment)
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  BENCHMARK: LUBM SPARQL Generation Accuracy                                 │
-│  DATASET: 3,272 triples │ MODEL: GPT-4o │ Real API calls                    │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  FRAMEWORK         NO SCHEMA     WITH SCHEMA                                │
-│  ─────────────────────────────────────────────────────────────              │
-│  Vanilla OpenAI    0.0%          71.4%                                      │
-│  LangChain         0.0%          71.4%                                      │
-│  DSPy              14.3%         71.4%                                      │
-│  ─────────────────────────────────────────────────────────────              │
-│                                                                             │
-│  HONEST TRUTH: Schema injection improves ALL frameworks equally.            │
-│  Any framework + schema context achieves ~71% accuracy.                     │
-│                                                                             │
-│  NOTE: DSPy gets 14.3% WITHOUT schema (vs 0% for others) due to            │
-│  its structured output format. With schema, all converge to 71.4%.          │
-│                                                                             │
-│  OUR REAL VALUE: We include the database. Others don't.                     │
-│  - LangChain generates SPARQL → you need to find a database                 │
-│  - HyperMind generates SPARQL → executes on built-in 449ns database         │
-│                                                                             │
-│  Reproduce: python3 benchmark-frameworks.py                                 │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## The Difference: Manual vs Integrated
-
-### Manual Approach (Works, But Tedious)
+### GraphFrame: Graph Analytics
 
 ```javascript
-// STEP 1: Manually write your schema (takes hours for large ontologies)
-const LUBM_SCHEMA = `
-PREFIX ub: <http://swat.cse.lehigh.edu/onto/univ-bench.owl#>
-Classes: University, Department, Professor, Student, Course, Publication
-Properties: teacherOf(Faculty→Course), worksFor(Faculty→Department)
-`;
-
-// STEP 2: Pass schema to LLM
-const answer = await openai.chat.completions.create({
-  model: 'gpt-4o',
-  messages: [
-    { role: 'system', content: `${LUBM_SCHEMA}\nOutput raw SPARQL only.` },
-    { role: 'user', content: 'Find suspicious providers' }
-  ]
-});
+const { GraphFrame, friendsGraph } = require('rust-kgdb');
 
-// STEP 3: Parse out the SPARQL (handle markdown, explanations, etc.)
-const sparql = extractSPARQL(answer.choices[0].message.content);
+// Create from vertices and edges
+const gf = new GraphFrame(
+  JSON.stringify([{id:'alice'}, {id:'bob'}, {id:'charlie'}]),
+  JSON.stringify([
+    {src:'alice', dst:'bob'},
+    {src:'bob', dst:'charlie'},
+    {src:'charlie', dst:'alice'}
+  ])
+);
 
-// STEP 4: Find a SPARQL database (Jena? RDFox? Virtuoso?)
-// STEP 5: Connect to database
-// STEP 6: Execute query
-// STEP 7: Parse results
-// STEP 8: No audit trail - you'd have to build that yourself
+// Algorithms
+console.log('PageRank:', gf.pageRank(0.15, 20));
+console.log('Connected Components:', gf.connectedComponents());
+console.log('Triangles:', gf.triangleCount());  // 1
+console.log('Shortest Paths:', gf.shortestPaths('alice'));
 
-// RESULT: ~71% accuracy (same as HyperMind with schema)
-// BUT: 5-8 manual integration steps
+// Motif finding (pattern matching)
+const motifs = gf.find('(a)-[e1]->(b); (b)-[e2]->(c)');
 ```
 
-### HyperMind Approach (Integrated)
+### EmbeddingService: Vector Similarity (HNSW)
 
 ```javascript
-// ONE-TIME SETUP: Load your data
-const { HyperMindAgent, GraphDB } = require('rust-kgdb');
-
-const db = new GraphDB('http://insurance.org/');
-db.loadTtl(yourActualData, null);  // Schema auto-extracted from data
-
-const agent = new HyperMindAgent({ kg: db, model: 'gpt-4o' });
-const result = await agent.call('Find suspicious providers');
-
-console.log(result.answer);
-// "Provider PROV001 has risk score 0.87 with 47 claims over $50,000"
-
-// WHAT YOU GET (ALL AUTOMATIC):
-// ✅ Schema auto-extracted (no manual prompt engineering)
-// ✅ Query executed on built-in database (no external DB needed)
-// ✅ Full audit trail included
-// ✅ Reproducible hash for compliance
-
-console.log(result.reasoningTrace);
-// [
-//   { tool: 'kg.sparql.query', input: 'SELECT ?p WHERE...', output: '[PROV001]' },
-//   { tool: 'kg.datalog.apply', input: 'highRisk(?p) :- ...', output: 'MATCHED' }
-// ]
-
-console.log(result.hash);
-// "sha256:8f3a2b1c..." - Same question = Same answer = Same hash
-```
+const { EmbeddingService } = require('rust-kgdb');
 
-**Honest comparison**: Both approaches achieve ~71% accuracy on LUBM benchmark. The difference is integration effort:
-- **Manual**: Write schema, integrate database, build audit trail yourself
-- **HyperMind**: Database + schema extraction + audit trail built-in
+const embeddings = new EmbeddingService();
 
----
+// Store 384-dimensional vectors (bring your own from OpenAI, Voyage, etc.)
+embeddings.storeVector('claim_001', await getOpenAIEmbedding('soft tissue injury'));
+embeddings.storeVector('claim_002', await getOpenAIEmbedding('whiplash from accident'));
 
-## Our Approach vs Traditional (Why This Works)
+// Build HNSW index
+embeddings.rebuildIndex();
 
-```
-┌───────────────────────────────────────────────────────────────────────────┐
-│                         APPROACH COMPARISON                               │
-├───────────────────────────────────────────────────────────────────────────┤
-│                                                                           │
-│  TRADITIONAL: CODE GENERATION        OUR APPROACH: NO CODE GENERATION     │
-│  ────────────────────────────        ────────────────────────────────     │
-│                                                                           │
-│  User → LLM → Generate Code          User → Domain-Enriched Proxy         │
-│                                                                           │
-│  ❌ SLOW: LLM generates text         ✅ FAST: Pre-built typed tools       │
-│  ❌ ERROR-PRONE: Syntax errors       ✅ RELIABLE: Schema-validated        │
-│  ❌ UNPREDICTABLE: Different         ✅ DETERMINISTIC: Same every time    │
-│                                                                           │
-├───────────────────────────────────────────────────────────────────────────┤
-│  TRADITIONAL FLOW                    OUR FLOW                             │
-│  ────────────────                    ────────                             │
-│                                                                           │
-│  1. User asks question               1. User asks question                │
-│  2. LLM generates code (SLOW)        2. Intent matched (INSTANT)          │
-│  3. Code has syntax error?           3. Schema object consulted           │
-│  4. Retry with LLM (SLOW)            4. Typed tool selected               │
-│  5. Code runs, wrong result?         5. Query built from schema           │
-│  6. Retry with LLM (SLOW)            6. Validated & executed              │
-│  7. Maybe works after 3-5 tries      7. Works first time                  │
-│                                                                           │
-├───────────────────────────────────────────────────────────────────────────┤
-│  OUR DOMAIN-ENRICHED PROXY LAYER                                          │
-│  ───────────────────────────────                                          │
-│                                                                           │
-│  ┌─────────────────────────────────────────────────────────────────────┐  │
-│  │ CONTEXT THEORY (Spivak's Ologs)                                     │  │
-│  │ SchemaContext = { classes: Set, properties: Map, domains, ranges }  │  │
-│  │ → Defines WHAT can be queried (schema as category)                  │  │
-│  └─────────────────────────────────────────────────────────────────────┘  │
-│                          │                                                │
-│                          ▼                                                │
-│  ┌─────────────────────────────────────────────────────────────────────┐  │
-│  │ TYPE THEORY (Hindley-Milner)                                        │  │
-│  │ TOOL_REGISTRY = { 'kg.sparql.query': Query → BindingSet, ... }      │  │
-│  │ → Defines HOW tools compose (typed morphisms)                       │  │
-│  └─────────────────────────────────────────────────────────────────────┘  │
-│                          │                                                │
-│                          ▼                                                │
-│  ┌─────────────────────────────────────────────────────────────────────┐  │
-│  │ PROOF THEORY (Curry-Howard)                                         │  │
-│  │ ProofDAG = { derivations: [...], hash: "sha256:..." }               │  │
-│  │ → Proves HOW answer was derived (audit trail)                       │  │
-│  └─────────────────────────────────────────────────────────────────────┘  │
-│                                                                           │
-├───────────────────────────────────────────────────────────────────────────┤
-│  RESULTS: SPEED + ACCURACY                                                │
-│  ─────────────────────────                                                │
-│                                                                           │
-│  TRADITIONAL (Code Gen)          OUR APPROACH (Proxy Layer)               │
-│  • 2-5 seconds per query         • <100ms per query (20-50x FASTER)       │
-│  • 0-14% accuracy (no schema)    • 71% accuracy (schema auto-injected)    │
-│  • Retry loops on errors         • No retries needed                      │
-│  • $0.01-0.05 per query          • <$0.001 per query (cached patterns)    │
-│                                                                           │
-├───────────────────────────────────────────────────────────────────────────┤
-│  WHY NO CODE GENERATION:                                                  │
-│  ───────────────────────                                                  │
-│  1. CODE GEN IS SLOW: LLM takes 1-3 seconds per query                     │
-│  2. CODE GEN IS ERROR-PRONE: Syntax errors, hallucination                 │
-│  3. CODE GEN IS EXPENSIVE: Every query costs LLM tokens                   │
-│  4. CODE GEN IS NON-DETERMINISTIC: Same question → different code         │
-│                                                                           │
-│  OUR PROXY LAYER PROVIDES:                                                │
-│  1. SPEED: Deterministic planner runs in milliseconds                     │
-│  2. ACCURACY: Schema object ensures only valid predicates                 │
-│  3. COST: No LLM needed for query generation                              │
-│  4. DETERMINISM: Same input → same query → same result → same hash        │
-└───────────────────────────────────────────────────────────────────────────┘
-```
+// Find similar (16ms for 10K vectors)
+const similar = embeddings.findSimilar('claim_001', 10, 0.7);
 
-**Architecture Comparison**:
-```
-TRADITIONAL:        LLM → JSON → Tool
-                    │
-                    └── LLM generates JSON/code (SLOW, ERROR-PRONE)
-                        Tool executes blindly (NO VALIDATION)
-                        Result returned (NO PROOF)
-
-                    (20-40% accuracy, 2-5 sec/query, $0.01-0.05/query)
-
-OUR APPROACH:       User → Proxied Objects → WASM Sandbox → RPC → Real Systems
-                    │
-                    ├── SchemaContext (Context Theory)
-                    │   └── Live object: { classes: Set, properties: Map }
-                    │   └── NOT serialized JSON string
-                    │
-                    ├── TOOL_REGISTRY (Type Theory)
-                    │   └── Typed morphisms: Query → BindingSet
-                    │   └── Composition validated at compile-time
-                    │
-                    ├── WasmSandbox (Secure Execution)
-                    │   └── Capability-based: ReadKG, ExecuteTool
-                    │   └── Fuel metering: prevents infinite loops
-                    │   └── Full audit log: every action traced
-                    │
-                    ├── rust-kgdb via NAPI-RS (Native RPC)
-                    │   └── 449ns lookups (not HTTP round-trips)
-                    │   └── Zero-copy data transfer
-                    │
-                    └── ProofDAG (Proof Theory)
-                        └── Every answer has derivation chain
-                        └── Deterministic hash for reproducibility
-
-                    (71% accuracy with schema, <100ms/query, <$0.001/query)
+// 1-hop neighbor cache (ARCADE algorithm)
+embeddings.onTripleInsert('claim_001', 'claimant', 'person_123', null);
+const neighbors = embeddings.getNeighborsOut('person_123');
 ```
 
-**The Three Pillars** (all as OBJECTS, not strings):
-- **Context Theory**: `SchemaContext` object defines what CAN be queried
-- **Type Theory**: `TOOL_REGISTRY` object defines typed tool signatures
-- **Proof Theory**: `ProofDAG` object proves how answer was derived
+### DatalogProgram: Rule-Based Reasoning
 
-**Why Proxied Objects + WASM Sandbox**:
-- **Proxied Objects**: SchemaContext, TOOL_REGISTRY are live objects with methods, not serialized JSON
-- **RPC to Real Systems**: Queries execute on rust-kgdb (449ns native performance)
-- **WASM Sandbox**: Capability-based security, fuel metering, full audit trail
+```javascript
+const { DatalogProgram, evaluateDatalog } = require('rust-kgdb');
 
----
+const datalog = new DatalogProgram();
 
-## Quick Start
+// Add facts
+datalog.addFact(JSON.stringify({predicate:'knows', terms:['alice','bob']}));
+datalog.addFact(JSON.stringify({predicate:'knows', terms:['bob','charlie']}));
 
-### Installation
+// Add rules (recursive!)
+datalog.addRule(JSON.stringify({
+  head: {predicate:'connected', terms:['?X','?Z']},
+  body: [
+    {predicate:'knows', terms:['?X','?Y']},
+    {predicate:'knows', terms:['?Y','?Z']}
+  ]
+}));
 
-```bash
-npm install rust-kgdb
+// Evaluate (semi-naive fixpoint)
+const inferred = evaluateDatalog(datalog);
+// connected(alice, charlie) - derived!
 ```
 
-**Platforms**: macOS (Intel/Apple Silicon), Linux (x64/ARM64), Windows (x64)
-
-### Basic Usage (5 Lines)
+### Pregel: Billion-Edge Graph Processing
 
 ```javascript
-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' } }]
-```
+const { pregelShortestPaths, chainGraph } = require('rust-kgdb');
 
-### Complete Example with AI Agent
+// Create large graph
+const graph = chainGraph(10000);  // 10K vertices
 
-```javascript
-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
+// Run Pregel BSP algorithm
+const distances = pregelShortestPaths(graph, 'v0', 100);
 ```
 
 ---
 
-## Framework Comparison (Verified Benchmark Setup)
-
-The following code snippets show EXACTLY how each framework was tested. All tests use the same LUBM dataset (3,272 triples) and GPT-4o model with real API calls—no mocking.
+## HyperMind Agent Framework
 
-**Reproduce yourself**: `python3 benchmark-frameworks.py` (included in package)
-
-### Vanilla OpenAI (0% → 71.4% with schema)
-
-```python
-# WITHOUT SCHEMA: 0% accuracy
-from openai import OpenAI
-client = OpenAI()
-
-response = client.chat.completions.create(
-    model="gpt-4o",
-    messages=[{"role": "user", "content": "Find all teachers"}]
-)
-# Returns: Long explanation with markdown code blocks
-# FAILS: No usable SPARQL query
-```
-
-```python
-# WITH SCHEMA: 71.4% accuracy (+71.4 pp improvement)
-LUBM_SCHEMA = """
-PREFIX ub: <http://swat.cse.lehigh.edu/onto/univ-bench.owl#>
-Classes: University, Department, Professor, Student, Course, Publication
-Properties: teacherOf(Faculty→Course), worksFor(Faculty→Department)
-"""
-
-response = client.chat.completions.create(
-    model="gpt-4o",
-    messages=[{
-        "role": "system",
-        "content": f"{LUBM_SCHEMA}\nOutput raw SPARQL only, no markdown."
-    }, {
-        "role": "user",
-        "content": "Find all teachers"
-    }]
-)
-# Returns: SELECT DISTINCT ?teacher WHERE { ?teacher a ub:Professor . }
-# WORKS: Valid SPARQL using correct ontology terms
-```
+### Why Vanilla LLMs Fail
 
-### LangChain (0% → 71.4% with schema)
-
-```python
-# WITHOUT SCHEMA: 0% accuracy
-from langchain_openai import ChatOpenAI
-from langchain_core.prompts import PromptTemplate
-from langchain_core.output_parsers import StrOutputParser
-
-llm = ChatOpenAI(model="gpt-4o")
-template = PromptTemplate(
-    input_variables=["question"],
-    template="Generate SPARQL for: {question}"
-)
-chain = template | llm | StrOutputParser()
-result = chain.invoke({"question": "Find all teachers"})
-# Returns: Explanation + markdown code blocks
-# FAILS: Not executable SPARQL
 ```
+User: "Find all professors"
 
-```python
-# WITH SCHEMA: 71.4% accuracy (+71.4 pp improvement)
-template = PromptTemplate(
-    input_variables=["question", "schema"],
-    template="""You are a SPARQL query generator.
-{schema}
-TYPE CONTRACT: Output raw SPARQL only, NO markdown, NO explanation.
-Query: {question}
-Output raw SPARQL only:"""
-)
-chain = template | llm | StrOutputParser()
-result = chain.invoke({"question": "Find all teachers", "schema": LUBM_SCHEMA})
-# Returns: SELECT DISTINCT ?teacher WHERE { ?teacher a ub:Professor . }
-# WORKS: Schema injection guides correct predicate selection
+Vanilla LLM Output:
+┌───────────────────────────────────────────────────────────────────────┐
+│ ```sparql                                                             │
+│ SELECT ?professor WHERE { ?professor a ub:Faculty . }                 │
+│ ```                            ← Parser rejects markdown              │
+│                                                                       │
+│ This query retrieves faculty members.                                 │
+│                                ↑ Mixed text breaks parsing            │
+└───────────────────────────────────────────────────────────────────────┘
+Result: ❌ PARSER ERROR - Invalid SPARQL syntax
 ```
 
-### DSPy (14.3% → 71.4% with schema)
-
-```python
-# WITHOUT SCHEMA: 14.3% accuracy (best without schema!)
-import dspy
-from dspy import LM
-
-lm = LM("openai/gpt-4o")
-dspy.configure(lm=lm)
-
-class SPARQLGenerator(dspy.Signature):
-    """Generate SPARQL query."""
-    question = dspy.InputField()
-    sparql = dspy.OutputField(desc="Raw SPARQL query only")
+**Problems:** (1) Markdown code fences, (2) Wrong class name (Faculty vs Professor), (3) Mixed text
 
-generator = dspy.Predict(SPARQLGenerator)
-result = generator(question="Find all teachers")
-# Returns: SELECT ?teacher WHERE { ?teacher a :Teacher . }
-# PARTIAL: Sometimes works due to DSPy's structured output
-```
+### How HyperMind Solves This
 
-```python
-# WITH SCHEMA: 71.4% accuracy (+57.1 pp improvement)
-class SchemaSPARQLGenerator(dspy.Signature):
-    """Generate SPARQL query using the provided schema."""
-    schema = dspy.InputField(desc="Database schema with classes and properties")
-    question = dspy.InputField(desc="Natural language question")
-    sparql = dspy.OutputField(desc="Raw SPARQL query, no markdown")
-
-generator = dspy.Predict(SchemaSPARQLGenerator)
-result = generator(schema=LUBM_SCHEMA, question="Find all teachers")
-# Returns: SELECT DISTINCT ?teacher WHERE { ?teacher a ub:Professor . }
-# WORKS: Schema + DSPy structured output = reliable queries
 ```
+User: "Find all professors"
 
-### HyperMind (Built-in Schema Awareness)
-
-```javascript
-// HyperMind auto-extracts schema from your data
-const { HyperMindAgent, createSchemaAwareGraphDB } = require('rust-kgdb');
-
-const db = createSchemaAwareGraphDB('http://university.org/');
-db.loadTtl(lubmData, null);  // Load LUBM 3,272 triples
-
-const agent = new HyperMindAgent({
-  kg: db,
-  model: 'gpt-4o',
-  apiKey: process.env.OPENAI_API_KEY
-});
-
-const result = await agent.call('Find all teachers');
-// Schema auto-extracted: { classes: Set(30), properties: Map(23) }
-// Query generated: SELECT ?x WHERE { ?x ub:teacherOf ?course . }
-// Result: 39 faculty members who teach courses
-
-console.log(result.reasoningTrace);
-// [{ tool: 'kg.sparql.query', query: 'SELECT...', bindings: 39 }]
-console.log(result.hash);
-// "sha256:a7b2c3..." - Reproducible answer
+HyperMind Output:
+┌───────────────────────────────────────────────────────────────────────┐
+│ PREFIX ub: <http://swat.cse.lehigh.edu/onto/univ-bench.owl#>         │
+│ SELECT ?professor WHERE { ?professor a ub:Professor . }               │
+└───────────────────────────────────────────────────────────────────────┘
+Result: ✅ 15 results returned in 2.3ms
 ```
 
-**Key Insight**: All frameworks achieve the SAME accuracy (~71%) when given schema. HyperMind's value is that it extracts and injects schema AUTOMATICALLY from your data—no manual prompt engineering required. Plus it includes the database to actually execute queries.
+**Why it works:**
+1. **Schema-aware** - Knows actual class names from your ontology
+2. **Type-checked** - Query validated before execution
+3. **No text pollution** - Output is pure SPARQL, not markdown
 
----
-
-## Use Cases
+**Accuracy: 0% → 86.4%** (LUBM benchmark, 14 queries)
 
-### Fraud Detection
+### Agent Components
 
 ```javascript
-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
-
-```javascript
-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
-```
+const {
+  HyperMindAgent,
+  LLMPlanner,
+  WasmSandbox,
+  AgentBuilder,
+  TOOL_REGISTRY
+} = require('rust-kgdb');
+
+// Build custom agent
+const agent = new AgentBuilder('fraud-detector')
+  .withTool('kg.sparql.query')
+  .withTool('kg.datalog.infer')
+  .withTool('kg.embeddings.search')
+  .withPlanner(new LLMPlanner('claude-sonnet-4', TOOL_REGISTRY))
+  .withSandbox({
+    capabilities: ['ReadKG', 'ExecuteTool'],  // No WriteKG
+    fuelLimit: 1000000,
+    maxMemory: 64 * 1024 * 1024
+  })
+  .build();
 
-### Risk Assessment
+// Execute with natural language
+const result = await agent.call("Find circular payment patterns");
 
-```javascript
-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
+// Get cryptographic proof
+console.log(result.witness.proof_hash);  // sha256:a3f2b8c9...
 ```
 
----
-
-## Features
-
-### Core Database (SPARQL 1.1)
-| Feature | Description |
-|---------|-------------|
-| **SELECT/CONSTRUCT/ASK** | Full SPARQL 1.1 query support |
-| **INSERT/DELETE/UPDATE** | SPARQL Update operations |
-| **64 Builtin Functions** | String, numeric, date/time, hash functions |
-| **Named Graphs** | Quad-based storage with graph isolation |
-| **RDF-Star** | Statements about statements |
-
-### Rule-Based Reasoning (Datalog)
-| Feature | Description |
-|---------|-------------|
-| **Facts & Rules** | Define base facts and inference rules |
-| **Semi-naive Evaluation** | Efficient incremental computation |
-| **Recursive Queries** | Transitive closure, ancestor chains |
-
-### Graph Analytics (GraphFrames)
-| Feature | Description |
-|---------|-------------|
-| **PageRank** | Iterative node importance ranking |
-| **Connected Components** | Find isolated subgraphs |
-| **Shortest Paths** | BFS path finding from landmarks |
-| **Triangle Count** | Graph density measurement |
-| **Motif Finding** | Structural pattern matching DSL |
-
-### Vector Similarity (Embeddings)
-| Feature | Description |
-|---------|-------------|
-| **HNSW Index** | O(log N) approximate nearest neighbor |
-| **Multi-provider** | OpenAI, Anthropic, Ollama support |
-| **Composite Search** | RRF aggregation across providers |
-
-### AI Agent Framework (HyperMind)
-| Feature | Description |
-|---------|-------------|
-| **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 |
-
-### Schema-Aware Generation (Proxied Tools)
-
-Generate motif patterns and Datalog rules from natural language using schema injection:
+### WASM Sandbox: Secure Execution
 
 ```javascript
-const { LLMPlanner, createSchemaAwareGraphDB } = require('rust-kgdb');
+const sandbox = new WasmSandbox({
+  capabilities: ['ReadKG', 'ExecuteTool'],  // Fine-grained
+  fuelLimit: 1000000,                        // CPU metering
+  maxMemory: 64 * 1024 * 1024               // Memory limit
+});
 
-const db = createSchemaAwareGraphDB('http://insurance.org/');
-db.loadTtl(insuranceData, null);
+// All tool calls are:
+// ✓ Capability-checked
+// ✓ Fuel-metered
+// ✓ Memory-bounded
+// ✓ Logged for audit
+```
 
-const planner = new LLMPlanner({ kg: db, model: 'gpt-4o' });
+### Execution Witness (Audit Trail)
 
-// Generate motif pattern from text
-const motif = await planner.generateMotifFromText('Find circular payment patterns');
-// Returns: {
-//   pattern: "(a)-[transfers]->(b); (b)-[transfers]->(c); (c)-[transfers]->(a)",
-//   variables: ["a", "b", "c"],
-//   predicatesUsed: ["transfers"],
-//   confidence: 0.9
-// }
+Every execution produces a cryptographic proof:
 
-// Generate Datalog rules from text
-const datalog = await planner.generateDatalogFromText(
-  'High risk providers are those with risk score above 0.7'
-);
-// Returns: {
-//   rules: [{ name: "highRisk", head: {...}, body: [...] }],
-//   datalogSyntax: ["highRisk(?x) :- provider(?x), riskScore(?x, ?score), ?score > 0.7."],
-//   predicatesUsed: ["riskScore", "provider"],
-//   confidence: 0.85
-// }
+```json
+{
+  "tool": "kg.sparql.query",
+  "input": "SELECT ?x WHERE { ?x a :Fraud }",
+  "output": "[{x: 'entity001'}]",
+  "timestamp": "2024-12-14T10:30:00Z",
+  "durationMs": 12,
+  "hash": "sha256:a3f2c8d9..."
+}
 ```
 
-**Same approach as SPARQL benchmark**: Schema injection ensures only valid predicates are used. No hallucination.
-
-### Available Tools
-| Tool | Input → Output | Description |
-|------|----------------|-------------|
-| `kg.sparql.query` | Query → BindingSet | Execute SPARQL SELECT |
-| `kg.sparql.update` | Update → Result | Execute SPARQL UPDATE |
-| `kg.datalog.apply` | Rules → InferredFacts | Apply Datalog rules |
-| `kg.motif.find` | Pattern → Matches | Find graph patterns |
-| `kg.embeddings.search` | Entity → SimilarEntities | Vector similarity |
-| `kg.graphframes.pagerank` | Graph → Scores | Rank nodes |
-| `kg.graphframes.components` | Graph → Components | Find communities |
-
-### Performance
-| Metric | Value | Comparison |
-|--------|-------|------------|
-| **Lookup Speed** | 449 ns | 5-10x faster than RDFox (verified Dec 2025) |
-| **Bulk Insert** | 146K triples/sec | Production-grade |
-| **Memory** | 24 bytes/triple | Best-in-class efficiency |
-
-### Join Optimization (WCOJ)
-| Feature | Description |
-|---------|-------------|
-| **WCOJ Algorithm** | Worst-case optimal joins with O(N^(ρ/2)) complexity |
-| **Multi-way Joins** | Process multiple patterns simultaneously |
-| **Adaptive Plans** | Cost-based optimizer selects best strategy |
-
-**Research Foundation**: WCOJ algorithms are the state-of-the-art for graph pattern matching. See [Tentris WCOJ Update (ISWC 2025)](https://papers.dice-research.org/2025/ISWC_Tentris-WCOJ-Update/public.pdf) for latest research.
-
-### Ontology & Reasoning
-| Feature | Description |
-|---------|-------------|
-| **RDFS Reasoner** | Subclass/subproperty inference |
-| **OWL 2 RL** | Rule-based OWL reasoning (prp-dom, prp-rng, prp-symp, prp-trp, cls-hv, cls-svf, cax-sco) |
-| **SHACL** | W3C shapes constraint validation |
-
-### Distribution (Clustered Mode)
-| Feature | Description |
-|---------|-------------|
-| **HDRF Partitioning** | Streaming graph partitioning (subject-anchored) |
-| **Raft Consensus** | Distributed coordination |
-| **gRPC** | Inter-node communication |
-| **Kubernetes-Native** | Helm charts, health checks |
-
-### Storage Backends
-| Backend | Use Case |
-|---------|----------|
-| **InMemory** | Development, testing, small datasets |
-| **RocksDB** | Production, large datasets, ACID |
-| **LMDB** | Read-heavy workloads, memory-mapped |
-
-### Mobile Support
-| Platform | Binding |
-|----------|---------|
-| **iOS** | Swift via UniFFI 0.30 |
-| **Android** | Kotlin via UniFFI 0.30 |
-| **Node.js** | NAPI-RS (this package) |
-| **Python** | UniFFI (separate package) |
+**Compliance:** Full audit trail for SOX, GDPR, FDA 21 CFR Part 11.
 
 ---
 
-## Complete Feature Overview
-
-| Category | Feature | What It Does |
-|----------|---------|--------------|
-| **Core** | GraphDB | High-performance RDF/SPARQL quad store |
-| **Core** | SPOC Indexes | Four-way indexing (SPOC/POCS/OCSP/CSPO) |
-| **Core** | Dictionary | String interning with 8-byte IDs |
-| **Analytics** | GraphFrames | PageRank, connected components, triangles |
-| **Analytics** | Motif Finding | Pattern matching DSL |
-| **Analytics** | Pregel | BSP parallel graph processing |
-| **AI** | Embeddings | HNSW similarity with 1-hop ARCADE cache |
-| **AI** | HyperMind | Neuro-symbolic agent framework |
-| **Reasoning** | Datalog | Semi-naive evaluation engine |
-| **Reasoning** | RDFS Reasoner | Subclass/subproperty inference |
-| **Reasoning** | OWL 2 RL | Rule-based OWL reasoning |
-| **Ontology** | SHACL | W3C shapes constraint validation |
-| **Joins** | WCOJ | Worst-case optimal join algorithm |
-| **Distribution** | HDRF | Streaming graph partitioning |
-| **Distribution** | Raft | Consensus for coordination |
-| **Mobile** | iOS/Android | Swift and Kotlin bindings via UniFFI |
-| **Storage** | InMemory/RocksDB/LMDB | Three backend options |
+## Agent Memory: Deep Flashback
 
----
+Most AI agents have amnesia. Ask the same question twice, they start from scratch.
+
+### The Problem
 
-## How It Works
+- ChatGPT forgets after context window fills
+- LangChain rebuilds context every call (~500ms)
+- Vector databases return "similar" docs, not exact matches
 
-### The Architecture
+### Our Solution: Memory Hypergraph
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────────┐
-│                              YOUR QUESTION                                   │
-│                    "Find suspicious providers"                               │
-└─────────────────────────────────┬───────────────────────────────────────────┘
-                                  │
-                                  ▼
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  STEP 1: SCHEMA INJECTION                                                    │
-│                                                                              │
-│  LLM receives your question PLUS your actual data schema:                   │
-│  • Classes: Claim, Provider, Policy (from YOUR database)                    │
-│  • Properties: amount, riskScore, claimCount (from YOUR database)           │
-│                                                                              │
-│  The LLM can ONLY reference things that actually exist in your data.        │
-└─────────────────────────────────┬───────────────────────────────────────────┘
-                                  │
-                                  ▼
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  STEP 2: TYPED EXECUTION PLAN                                                │
-│                                                                              │
-│  LLM generates a plan using typed tools:                                    │
-│  1. kg.sparql.query("SELECT ?p WHERE { ?p :riskScore ?r . FILTER(?r > 0.8)}")│
-│  2. kg.datalog.apply("suspicious(?p) :- highRisk(?p), highClaimCount(?p)")  │
-│                                                                              │
-│  Each tool has defined inputs/outputs. Invalid combinations rejected.        │
-└─────────────────────────────────┬───────────────────────────────────────────┘
-                                  │
-                                  ▼
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  STEP 3: DATABASE EXECUTION                                                  │
+│                         MEMORY HYPERGRAPH                                    │
 │                                                                              │
-│  The database executes the plan against YOUR ACTUAL DATA:                   │
-│  • SPARQL query runs → finds 3 providers with riskScore > 0.8               │
-│  • Datalog rules run → 1 provider matches "suspicious" pattern              │
-│                                                                              │
-│  Every step is recorded in the reasoning trace.                             │
-└─────────────────────────────────┬───────────────────────────────────────────┘
-                                  │
-                                  ▼
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  STEP 4: VERIFIED ANSWER                                                     │
-│                                                                              │
-│  Answer: "Provider PROV001 is suspicious (riskScore: 0.87, claims: 47)"     │
-│                                                                              │
-│  + Reasoning Trace: Every query, every rule, every result                   │
-│  + Hash: sha256:8f3a2b1c... (reproducible)                                  │
+│   AGENT MEMORY LAYER                                                         │
+│   ┌─────────────┐     ┌─────────────┐     ┌─────────────┐                   │
+│   │ Episode:001 │     │ Episode:002 │     │ Episode:003 │                   │
+│   │ "Fraud ring │     │ "Denied     │     │ "Follow-up  │                   │
+│   │  detected"  │     │  claim"     │     │  on P001"   │                   │
+│   │ Dec 10      │     │ Dec 12      │     │ Dec 15      │                   │
+│   └──────┬──────┘     └──────┬──────┘     └──────┬──────┘                   │
+│          │                   │                   │                           │
+│          └───────────────────┼───────────────────┘                           │
+│                              │ HyperEdges connect to KG                      │
+│                              ▼                                               │
+│   KNOWLEDGE GRAPH LAYER                                                      │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │  Provider:P001 ──────▶ Claim:C123 ◀────── Claimant:John            │   │
+│   │       │                    │                    │                   │   │
+│   │       ▼                    ▼                    ▼                   │   │
+│   │   riskScore: 0.87     amount: 50000        address: "123 Main"     │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
 │                                                                              │
-│  Run the same question tomorrow → Same answer → Same hash                   │
+│   SAME QUAD STORE - Single SPARQL query traverses BOTH!                     │
 └─────────────────────────────────────────────────────────────────────────────┘
 ```
 
-### Why Hallucination Is Impossible
+### Benchmarked Performance
 
-| Step | What Prevents Hallucination |
-|------|----------------------------|
-| Schema Injection | LLM only sees properties that exist in YOUR data |
-| Typed Tools | Invalid query structures rejected before execution |
-| Database Execution | Answers come from actual data, not LLM imagination |
-| Reasoning Trace | Every claim is backed by recorded evidence |
+| Metric | Result | What It Means |
+|--------|--------|---------------|
+| **Memory Retrieval** | 94% Recall@10 at 10K depth | Find the right past query 94% of the time |
+| **Search Speed** | 16.7ms for 10K queries | 30x faster than typical RAG |
+| **Write Throughput** | 132K ops/sec (16 workers) | Handle enterprise volumes |
+| **Read Throughput** | 302 ops/sec concurrent | Consistent under load |
 
-**The key insight**: The LLM is a planner, not an oracle. It decides WHAT to look for. The database finds EXACTLY that. The answer is the intersection of LLM intelligence and database truth.
+### Idempotent Responses
 
----
+Same question = Same answer. Even with different wording.
 
-## API Reference
-
-### GraphDB
+```javascript
+// First call: Compute answer, cache with semantic hash
+const result1 = await agent.call("Analyze claims from Provider P001");
 
-```typescript
-class GraphDB {
-  constructor(appGraphUri: string)
-  loadTtl(ttlContent: string, graphName: string | null): void
-  querySelect(sparql: string): QueryResult[]
-  query(sparql: string): TripleResult[]
-  countTriples(): number
-  clear(): void
-}
+// Second call (different wording): Cache HIT!
+const result2 = await agent.call("Show me P001's claim patterns");
+// Same semantic hash → Same result
 ```
 
-### HyperMindAgent
-
-```typescript
-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
-}
-```
+## Mathematical Foundations
 
-### GraphFrame
+### Category Theory: Tools as Morphisms
 
-```typescript
-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
-}
 ```
+Tools are typed arrows:
+  kg.sparql.query:     Query → BindingSet
+  kg.motif.find:       Pattern → Matches
+  kg.datalog.apply:    Rules → InferredFacts
 
-### EmbeddingService
+Composition is type-checked:
+  f: A → B
+  g: B → C
+  g ∘ f: A → C  (valid only if B matches)
 
-```typescript
-class EmbeddingService {
-  storeVector(entityId: string, vector: number[]): void
-  findSimilar(entityId: string, k: number, threshold: number): string
-  rebuildIndex(): void
-}
+Laws guaranteed:
+  Identity:      id ∘ f = f
+  Associativity: (h ∘ g) ∘ f = h ∘ (g ∘ f)
 ```
 
-### DatalogProgram
+**In practice:** The AI can only chain tools where outputs match inputs. Like Lego blocks that must fit.
 
-```typescript
-class DatalogProgram {
-  addFact(factJson: string): void
-  addRule(ruleJson: string): void
-}
+### WCOJ: Worst-Case Optimal Joins
 
-function evaluateDatalog(program: DatalogProgram): string
-function queryDatalog(program: DatalogProgram, query: string): string
-```
+Finding "all cases where Judge X ruled on Contract Y involving Company Z"?
 
----
+**Traditional:** Check every case with Judge X (50K), every contract (500K combinations), every company (25M checks).
 
-## More Examples
+**WCOJ:** Keep sorted indexes. Walk through all three simultaneously. Skip impossible combinations. 50K checks instead of 25 million.
 
-### Knowledge Graph
+### HNSW: Hierarchical Navigable Small World
 
-```javascript
-const { GraphDB } = require('rust-kgdb')
+Finding similar items from 50,000 vectors?
 
-const db = new GraphDB('http://example.org/')
-db.loadTtl(`
-  @prefix : <http://example.org/> .
-  :alice :knows :bob .
-  :bob :knows :charlie .
-  :charlie :knows :alice .
-`, null)
+**Brute force:** Compare to all 50,000. O(n).
 
-console.log(`Loaded ${db.countTriples()} triples`)  // 3
+**HNSW:** Build a multi-layer graph. Start at top layer, descend toward target. ~20 hops. O(log n).
 
-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
+### Datalog: Recursive Rule Evaluation
 
-```javascript
-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'}
-  ])
-)
-
-// Built-in algorithms
-console.log('Triangles:', graph.triangleCount())  // 1
-console.log('PageRank:', JSON.parse(graph.pageRank(0.15, 20)))
-console.log('Components:', JSON.parse(graph.connectedComponents()))
+```
+mustReport(X) :- transaction(X), amount(X, A), A > 10000.
+mustReport(X) :- transaction(X), involves(X, PEP).
+mustReport(X) :- relatedTo(X, Y), mustReport(Y).  # Recursive!
 ```
 
-### Motif Finding (Pattern Matching)
-
-```javascript
-const { GraphFrame } = require('rust-kgdb')
+Three rules generate ALL reporting requirements. Even for transactions connected to other suspicious transactions, cascading infinitely.
 
-// Create a graph with payment relationships
-const graph = new GraphFrame(
-  JSON.stringify([
-    {id:'company_a'}, {id:'company_b'}, {id:'company_c'}, {id:'company_d'}
-  ]),
-  JSON.stringify([
-    {src:'company_a', dst:'company_b'},  // A pays B
-    {src:'company_b', dst:'company_c'},  // B pays C
-    {src:'company_c', dst:'company_a'},  // C pays A (circular!)
-    {src:'company_c', dst:'company_d'}   // C also pays D
-  ])
-)
+---
 
-// Find simple edge pattern: (a)-[]->(b)
-const edges = JSON.parse(graph.find('(a)-[]->(b)'))
-console.log('All edges:', edges.length)  // 4
+## Real-World Examples
 
-// Find two-hop path: (x)-[]->(y)-[]->(z)
-const twoHops = JSON.parse(graph.find('(x)-[]->(y); (y)-[]->(z)'))
-console.log('Two-hop paths:', twoHops.length)  // 3
+### Legal: Contract Analysis
 
-// Find circular pattern (fraud detection!): A->B->C->A
-const circles = JSON.parse(graph.find('(a)-[]->(b); (b)-[]->(c); (c)-[]->(a)'))
-console.log('Circular patterns:', circles.length)  // 1 (the fraud ring!)
+```javascript
+const db = new GraphDB('http://lawfirm.com/');
+db.loadTtl(`
+  :Contract_2024 :hasClause :NonCompete_3yr ; :signedBy :ClientA .
+  :NonCompete_3yr :challengedIn :Martinez_v_Apex ; :upheldIn :Chen_v_StateBank .
+  :Martinez_v_Apex :court "9th Circuit" ; :year 2021 ; :outcome "partial" .
+`);
 
-// Each match includes the bound variables
-// circles[0] = { a: 'company_a', b: 'company_b', c: 'company_c' }
+const result = await agent.ask("Has the non-compete clause been challenged?");
+// Returns REAL cases from YOUR database, not hallucinated citations
 ```
 
-### Rule-Based Reasoning
+### Healthcare: Drug Interactions
 
 ```javascript
-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']}
-  ]
-}))
+const db = new GraphDB('http://hospital.org/');
+db.loadTtl(`
+  :Patient_7291 :currentMedication :Warfarin ; :currentMedication :Lisinopril .
+  :Warfarin :interactsWith :Aspirin ; :interactionSeverity "high" .
+  :Lisinopril :interactsWith :Potassium ; :interactionSeverity "high" .
+`);
 
-console.log('Inferred:', JSON.parse(evaluateDatalog(program)))
-// grandparent(alice, charlie)
+const result = await agent.ask("What should we avoid prescribing to Patient 7291?");
+// Returns ACTUAL interactions from your formulary, not made-up drug names
 ```
 
-### Semantic Similarity
+### Insurance: Fraud Detection with Datalog
 
 ```javascript
-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()
+const db = new GraphDB('http://insurer.com/');
+db.loadTtl(`
+  :P001 a :Claimant ; :name "John Smith" ; :address "123 Main St" .
+  :P002 a :Claimant ; :name "Jane Doe" ; :address "123 Main St" .
+  :P001 :knows :P002 .
+  :P001 :claimsWith :PROV001 .
+  :P002 :claimsWith :PROV001 .
+`);
+
+// NICB fraud detection rules
+datalog.addRule(JSON.stringify({
+  head: {predicate:'potential_collusion', terms:['?X','?Y','?P']},
+  body: [
+    {predicate:'claimant', terms:['?X']},
+    {predicate:'claimant', terms:['?Y']},
+    {predicate:'knows', terms:['?X','?Y']},
+    {predicate:'claimsWith', terms:['?X','?P']},
+    {predicate:'claimsWith', terms:['?Y','?P']}
+  ]
+}));
 
-// HNSW similarity search
-const similar = JSON.parse(embeddings.findSimilar('claim_001', 5, 0.7))
-console.log('Similar:', similar)
+const inferred = evaluateDatalog(datalog);
+// potential_collusion(P001, P002, PROV001) - DETECTED!
 ```
 
-### Pregel (BSP Graph Processing)
+### AML: Circular Payment Detection
 
 ```javascript
-const { chainGraph, pregelShortestPaths } = require('rust-kgdb')
-
-// Create a chain: v0 -> v1 -> v2 -> v3 -> v4
-const graph = chainGraph(5)
+db.loadTtl(`
+  :Acct_1001 :transferredTo :Acct_2002 ; :amount 9500 .
+  :Acct_2002 :transferredTo :Acct_3003 ; :amount 9400 .
+  :Acct_3003 :transferredTo :Acct_1001 ; :amount 9200 .
+`);
 
-// Compute shortest paths from v0
-const result = JSON.parse(pregelShortestPaths(graph, 'v0', 10))
-console.log('Distances:', result.distances)
-// { v0: 0, v1: 1, v2: 2, v3: 3, v4: 4 }
-console.log('Supersteps:', result.supersteps)  // 5
+// Find circular chains (money laundering indicator)
+const triangles = gf.triangleCount();  // 1 circular pattern
 ```
 
 ---
 
-## Comprehensive Example Tables
-
-### SPARQL Examples
-
-| Query Type | Example | Description |
-|------------|---------|-------------|
-| **SELECT** | `SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10` | Basic triple pattern |
-| **FILTER** | `SELECT ?p WHERE { ?p :age ?a . FILTER(?a > 30) }` | Numeric filtering |
-| **OPTIONAL** | `SELECT ?p ?email WHERE { ?p a :Person . OPTIONAL { ?p :email ?email } }` | Left outer join |
-| **UNION** | `SELECT ?x WHERE { { ?x a :Cat } UNION { ?x a :Dog } }` | Pattern union |
-| **CONSTRUCT** | `CONSTRUCT { ?s :knows ?o } WHERE { ?s :friend ?o }` | Create new triples |
-| **ASK** | `ASK WHERE { :alice :knows :bob }` | Boolean existence check |
-| **INSERT** | `INSERT DATA { :alice :knows :charlie }` | Add triples |
-| **DELETE** | `DELETE WHERE { :alice :knows ?anyone }` | Remove triples |
-| **Aggregation** | `SELECT (COUNT(?p) AS ?cnt) WHERE { ?p a :Person }` | Count/Sum/Avg/Min/Max |
-| **GROUP BY** | `SELECT ?dept (COUNT(?e) AS ?cnt) WHERE { ?e :worksIn ?dept } GROUP BY ?dept` | Grouping |
-| **HAVING** | `SELECT ?dept (COUNT(?e) AS ?cnt) WHERE { ?e :worksIn ?dept } GROUP BY ?dept HAVING (COUNT(?e) > 5)` | Filter groups |
-| **ORDER BY** | `SELECT ?p ?age WHERE { ?p :age ?age } ORDER BY DESC(?age)` | Sorting |
-| **DISTINCT** | `SELECT DISTINCT ?type WHERE { ?s a ?type }` | Remove duplicates |
-| **VALUES** | `SELECT ?p WHERE { VALUES ?type { :Cat :Dog } ?p a ?type }` | Inline data |
-| **BIND** | `SELECT ?p ?label WHERE { ?p :name ?n . BIND(CONCAT("Mr. ", ?n) AS ?label) }` | Computed values |
-| **Subquery** | `SELECT ?p WHERE { { SELECT ?p WHERE { ?p :score ?s } ORDER BY DESC(?s) LIMIT 10 } }` | Nested queries |
-
-### Datalog Examples
-
-| Pattern | Rule | Description |
-|---------|------|-------------|
-| **Transitive Closure** | `ancestor(?X,?Z) :- parent(?X,?Y), ancestor(?Y,?Z)` | Recursive ancestor |
-| **Symmetric** | `knows(?X,?Y) :- knows(?Y,?X)` | Bidirectional relations |
-| **Composition** | `grandparent(?X,?Z) :- parent(?X,?Y), parent(?Y,?Z)` | Two-hop relation |
-| **Negation** | `lonely(?X) :- person(?X), NOT friend(?X,?Y)` | Absence check |
-| **Aggregation** | `popular(?X) :- friend(?X,?Y), COUNT(?Y) > 10` | Count-based rules |
-| **Path Finding** | `reachable(?X,?Y) :- edge(?X,?Y). reachable(?X,?Z) :- edge(?X,?Y), reachable(?Y,?Z)` | Graph connectivity |
-
-### Motif Pattern Syntax
-
-| Pattern | Syntax | Matches |
-|---------|--------|---------|
-| **Single Edge** | `(a)-[]->(b)` | All directed edges |
-| **Two-Hop** | `(a)-[]->(b); (b)-[]->(c)` | Paths of length 2 |
-| **Triangle** | `(a)-[]->(b); (b)-[]->(c); (c)-[]->(a)` | Closed triangles |
-| **Star** | `(center)-[]->(a); (center)-[]->(b); (center)-[]->(c)` | Hub patterns |
-| **Named Edge** | `(a)-[e]->(b)` | Capture edge in variable `e` |
-| **Negation** | `(a)-[]->(b); !(b)-[]->(a)` | One-way edges only |
-| **Diamond** | `(a)-[]->(b); (a)-[]->(c); (b)-[]->(d); (c)-[]->(d)` | Diamond pattern |
-
-### GraphFrame Algorithms
-
-| Algorithm | Method | Input | Output |
-|-----------|--------|-------|--------|
-| **PageRank** | `graph.pageRank(0.15, 20)` | damping, iterations | `{ ranks: {id: score}, iterations, converged }` |
-| **Connected Components** | `graph.connectedComponents()` | - | `{ components: {id: componentId}, count }` |
-| **Shortest Paths** | `graph.shortestPaths(['v0', 'v5'])` | landmark vertices | `{ distances: {id: {landmark: dist}} }` |
-| **Label Propagation** | `graph.labelPropagation(10)` | max iterations | `{ labels: {id: label}, iterations }` |
-| **Triangle Count** | `graph.triangleCount()` | - | Number of triangles |
-| **Motif Finding** | `graph.find('(a)-[]->(b)')` | pattern string | Array of matches |
-| **Degrees** | `graph.degrees()` / `inDegrees()` / `outDegrees()` | - | `{ id: degree }` |
-| **Pregel** | `pregelShortestPaths(graph, 'v0', 10)` | landmark, maxSteps | `{ distances, supersteps }` |
-
-### Embedding Operations
-
-| Operation | Method | Description |
-|-----------|--------|-------------|
-| **Store Vector** | `service.storeVector('id', [0.1, 0.2, ...])` | Store 384-dim embedding |
-| **Find Similar** | `service.findSimilar('id', 10, 0.7)` | HNSW k-NN search |
-| **Composite Store** | `service.storeComposite('id', JSON.stringify({openai: [...], voyage: [...]}))` | Multi-provider |
-| **Composite Search** | `service.findSimilarComposite('id', 10, 0.7, 'rrf')` | RRF/max/voting aggregation |
-| **1-Hop Cache** | `service.getNeighborsOut('id')` / `getNeighborsIn('id')` | ARCADE neighbor cache |
-| **Rebuild Index** | `service.rebuildIndex()` | Rebuild HNSW index |
-
----
-
-## Benchmarks
+## Performance Benchmarks
 
-### Performance (Measured)
+All measurements verified. Run them yourself:
 
-| Metric | Value | Rate |
-|--------|-------|------|
-| **Triple Lookup** | 449 ns | 2.2M lookups/sec |
-| **Bulk Insert (100K)** | 682 ms | 146K triples/sec |
-| **Memory per Triple** | 24 bytes | Best-in-class |
+```bash
+node benchmark.js              # Core performance
+node vanilla-vs-hypermind-benchmark.js  # Agent accuracy
+```
 
-### Industry Comparison
+### Rust Core Engine
 
-| System | Lookup Speed | Memory/Triple | AI Framework |
-|--------|-------------|---------------|--------------|
-| **rust-kgdb** | **449 ns** | **24 bytes** | **Yes** |
-| RDFox | ~5 µs | 36-89 bytes | No |
-| Virtuoso | ~5 µs | 35-75 bytes | No |
-| Blazegraph | ~100 µs | 100+ bytes | No |
+| Metric | rust-kgdb | RDFox | Apache Jena |
+|--------|-----------|-------|-------------|
+| **Lookup** | 449 ns | 5,000+ ns | 10,000+ ns |
+| **Memory/Triple** | 24 bytes | 32 bytes | 50-60 bytes |
+| **Bulk Insert** | 146K/sec | 200K/sec | 50K/sec |
 
-### AI Agent Accuracy (Verified December 2025)
+### Agent Accuracy (LUBM Benchmark)
 
-| Framework | No Schema | With Schema |
-|-----------|-----------|-------------|
-| **Vanilla OpenAI** | 0.0% | 71.4% |
-| **LangChain** | 0.0% | 71.4% |
-| **DSPy** | 14.3% | 71.4% |
+| System | Without Schema | With Schema |
+|--------|---------------|-------------|
+| Vanilla LLM | 0% | - |
+| LangChain | 0% | 71.4% |
+| DSPy | 14.3% | 71.4% |
+| **HyperMind** | - | **71.4%** |
 
-*Schema injection improves ALL frameworks equally. See `verified_benchmark_results.json` for raw data.*
+*All frameworks achieve same accuracy WITH schema. HyperMind's advantage is integrated schema handling.*
 
-*Tested: GPT-4o, 7 LUBM queries, real API calls.*
+### Concurrency (16 Workers)
 
-### AI Framework Architectural Comparison
+| Operation | Throughput |
+|-----------|------------|
+| Writes | 132K ops/sec |
+| Reads | 302 ops/sec |
+| GraphFrames | 6.5K ops/sec |
+| Mixed | 642 ops/sec |
 
-| Framework | Type Safety | Schema Aware | Symbolic Execution | Audit Trail |
-|-----------|-------------|--------------|-------------------|-------------|
-| **HyperMind** | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
-| LangChain | ❌ No | ❌ No | ❌ No | ❌ No |
-| DSPy | ⚠️ Partial | ❌ No | ❌ No | ❌ No |
+---
 
-**Key Insight**: Schema injection (HyperMind's architecture) provides +66.7 pp improvement across ALL frameworks. The value is in the architecture, not the specific framework.
+## Feature Summary
+
+| Category | Feature | Performance |
+|----------|---------|-------------|
+| **Core** | SPARQL 1.1 Engine | 449ns lookups |
+| **Core** | RDF 1.2 Support | W3C compliant |
+| **Core** | Named Graphs | Quad store |
+| **Analytics** | PageRank | O(V + E) |
+| **Analytics** | Connected Components | Union-find |
+| **Analytics** | Triangle Count | O(E^1.5) |
+| **Analytics** | Motif Finding | Pattern DSL |
+| **Analytics** | Pregel BSP | Billion-edge scale |
+| **AI** | HNSW Embeddings | 16ms/10K vectors |
+| **AI** | 1-Hop Cache | O(1) neighbors |
+| **AI** | Agent Memory | 94% recall@10 |
+| **Reasoning** | Datalog | Semi-naive |
+| **Reasoning** | RDFS | Subclass inference |
+| **Reasoning** | OWL 2 RL | Rule-based |
+| **Validation** | SHACL | Shape constraints |
+| **Provenance** | PROV | W3C standard |
+| **Joins** | WCOJ | Optimal complexity |
+| **Security** | WASM Sandbox | Capability-based |
+| **Audit** | ProofDAG | SHA-256 witnesses |
 
-### Reproduce Benchmarks
+---
 
-Two benchmark scripts are available for verification:
+## Installation
 
 ```bash
-# JavaScript: HyperMind vs Vanilla LLM on LUBM (12 queries)
-ANTHROPIC_API_KEY=... OPENAI_API_KEY=... node vanilla-vs-hypermind-benchmark.js
-
-# Python: Compare frameworks (Vanilla, LangChain, DSPy) with/without schema
-OPENAI_API_KEY=... uv run --with openai --with langchain --with langchain-openai --with langchain-core --with dspy-ai python3 benchmark-frameworks.py
+npm install rust-kgdb
 ```
 
-Both scripts make real API calls and report actual results. No mocking.
-
-**Why These Features Matter**:
-- **Type Safety**: Tools have typed signatures (Query → BindingSet), invalid combinations rejected
-- **Schema Awareness**: Planner sees your actual data structure, can only reference real properties
-- **Symbolic Execution**: Queries run against real database, not LLM imagination
-- **Audit Trail**: Every answer has cryptographic hash for reproducibility
-
----
-
-## W3C Standards Compliance
+**Platforms:** macOS (Intel/Apple Silicon), Linux (x64/ARM64), Windows (x64)
 
-| Standard | Status |
-|----------|--------|
-| **SPARQL 1.1 Query** | ✅ 100% |
-| **SPARQL 1.1 Update** | ✅ 100% |
-| **RDF 1.2** | ✅ 100% |
-| **RDF-Star** | ✅ 100% |
-| **Turtle** | ✅ 100% |
+**Requirements:** Node.js 14+
 
 ---
 
-## Links
+## Complete Fraud Detection Example
 
-- **npm**: [rust-kgdb](https://www.npmjs.com/package/rust-kgdb)
-- **GitHub**: [gonnect-uk/rust-kgdb](https://github.com/gonnect-uk/rust-kgdb)
-- **Benchmark Report**: [HYPERMIND_BENCHMARK_REPORT.md](./HYPERMIND_BENCHMARK_REPORT.md)
-- **Changelog**: [CHANGELOG.md](./CHANGELOG.md)
+Copy this entire example to get started with fraud detection:
 
----
-
-## Advanced Topics
+```javascript
+const {
+  GraphDB,
+  GraphFrame,
+  EmbeddingService,
+  DatalogProgram,
+  evaluateDatalog,
+  HyperMindAgent
+} = require('rust-kgdb');
+
+// ============================================================
+// STEP 1: Initialize Services
+// ============================================================
+const db = new GraphDB('http://insurance.org/fraud-detection');
+const embeddings = new EmbeddingService();
+
+// ============================================================
+// STEP 2: Load Claims Data
+// ============================================================
+db.loadTtl(`
+  @prefix : <http://insurance.org/> .
+  @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+  # Claims
+  :CLM001 a :Claim ;
+    :amount "18500"^^xsd:decimal ;
+    :description "Soft tissue injury from rear-end collision" ;
+    :claimant :P001 ;
+    :provider :PROV001 ;
+    :filingDate "2024-11-15"^^xsd:date .
+
+  :CLM002 a :Claim ;
+    :amount "22300"^^xsd:decimal ;
+    :description "Whiplash injury from vehicle accident" ;
+    :claimant :P002 ;
+    :provider :PROV001 ;
+    :filingDate "2024-11-18"^^xsd:date .
+
+  # Claimants (note: same address = red flag!)
+  :P001 a :Claimant ;
+    :name "John Smith" ;
+    :address "123 Main St, Miami, FL" ;
+    :riskScore "0.85"^^xsd:decimal .
+
+  :P002 a :Claimant ;
+    :name "Jane Doe" ;
+    :address "123 Main St, Miami, FL" ;
+    :riskScore "0.72"^^xsd:decimal .
+
+  # Relationships (fraud indicators)
+  :P001 :knows :P002 .
+  :P001 :paidTo :P002 .
+  :P002 :paidTo :P003 .
+  :P003 :paidTo :P001 .  # Circular payment!
+
+  # Provider
+  :PROV001 a :Provider ;
+    :name "Quick Care Rehabilitation Clinic" ;
+    :flagCount "4"^^xsd:integer .
+`);
+
+console.log(`Loaded ${db.countTriples()} triples`);
+
+// ============================================================
+// STEP 3: Graph Analytics - Find Network Patterns
+// ============================================================
+const vertices = JSON.stringify([
+  {id: 'P001'}, {id: 'P002'}, {id: 'P003'}, {id: 'PROV001'}
+]);
+const edges = JSON.stringify([
+  {src: 'P001', dst: 'P002'},
+  {src: 'P001', dst: 'PROV001'},
+  {src: 'P002', dst: 'PROV001'},
+  {src: 'P001', dst: 'P002'},  // payment
+  {src: 'P002', dst: 'P003'},  // payment
+  {src: 'P003', dst: 'P001'}   // payment (circular!)
+]);
+
+const gf = new GraphFrame(vertices, edges);
+console.log('Triangles (circular patterns):', gf.triangleCount());
+console.log('PageRank:', gf.pageRank(0.15, 20));
+
+// ============================================================
+// STEP 4: Embedding-Based Similarity
+// ============================================================
+// Store embeddings for semantic similarity search
+// (In production, use OpenAI/Voyage embeddings)
+function mockEmbedding(text) {
+  return new Array(384).fill(0).map((_, i) =>
+    Math.sin(text.charCodeAt(i % text.length) * 0.1) * 0.5 + 0.5
+  );
+}
 
-For those interested in the technical foundations of why HyperMind achieves deterministic AI reasoning.
+embeddings.storeVector('CLM001', mockEmbedding('soft tissue injury rear end'));
+embeddings.storeVector('CLM002', mockEmbedding('whiplash vehicle accident'));
+embeddings.rebuildIndex();
+
+const similar = JSON.parse(embeddings.findSimilar('CLM001', 5, 0.3));
+console.log('Similar claims:', similar);
+
+// ============================================================
+// STEP 5: Datalog Rules - NICB Fraud Detection
+// ============================================================
+const datalog = new DatalogProgram();
+
+// Add facts from our knowledge graph
+datalog.addFact(JSON.stringify({predicate:'claimant', terms:['P001']}));
+datalog.addFact(JSON.stringify({predicate:'claimant', terms:['P002']}));
+datalog.addFact(JSON.stringify({predicate:'provider', terms:['PROV001']}));
+datalog.addFact(JSON.stringify({predicate:'knows', terms:['P001','P002']}));
+datalog.addFact(JSON.stringify({predicate:'claims_with', terms:['P001','PROV001']}));
+datalog.addFact(JSON.stringify({predicate:'claims_with', terms:['P002','PROV001']}));
+datalog.addFact(JSON.stringify({predicate:'same_address', terms:['P001','P002']}));
+
+// NICB Collusion Detection Rule
+datalog.addRule(JSON.stringify({
+  head: {predicate:'potential_collusion', terms:['?X','?Y','?P']},
+  body: [
+    {predicate:'claimant', terms:['?X']},
+    {predicate:'claimant', terms:['?Y']},
+    {predicate:'provider', terms:['?P']},
+    {predicate:'knows', terms:['?X','?Y']},
+    {predicate:'claims_with', terms:['?X','?P']},
+    {predicate:'claims_with', terms:['?Y','?P']}
+  ]
+}));
 
-### Why It Works: The Technical Foundation
+// Staged Accident Indicator Rule
+datalog.addRule(JSON.stringify({
+  head: {predicate:'staged_accident_indicator', terms:['?X','?Y']},
+  body: [
+    {predicate:'claimant', terms:['?X']},
+    {predicate:'claimant', terms:['?Y']},
+    {predicate:'same_address', terms:['?X','?Y']},
+    {predicate:'knows', terms:['?X','?Y']}
+  ]
+}));
+
+const inferred = JSON.parse(evaluateDatalog(datalog));
+console.log('Inferred fraud patterns:', inferred);
+
+// ============================================================
+// STEP 6: SPARQL Query - Get Detailed Evidence
+// ============================================================
+const suspiciousClaims = db.querySelect(`
+  PREFIX : <http://insurance.org/>
+  SELECT ?claim ?amount ?claimant ?provider WHERE {
+    ?claim a :Claim ;
+           :amount ?amount ;
+           :claimant ?claimant ;
+           :provider ?provider .
+    ?claimant :riskScore ?risk .
+    FILTER(?risk > 0.7)
+  }
+`);
 
-HyperMind's reliability comes from three mathematical foundations:
+console.log('High-risk claims:', suspiciousClaims);
 
-| Foundation | What It Does | Practical Benefit |
-|------------|--------------|-------------------|
-| **Schema Awareness** | Auto-extracts your data structure | LLM only generates valid queries |
-| **Typed Tools** | Input/output validation | Prevents invalid tool combinations |
-| **Reasoning Trace** | Records every step | Complete audit trail for compliance |
+// ============================================================
+// STEP 7: HyperMind Agent - Natural Language Interface
+// ============================================================
+const agent = new HyperMindAgent({ db, embeddings });
 
-### The Reasoning Trace (Audit Trail)
+async function investigate() {
+  const result = await agent.ask("Which claims show potential fraud patterns?");
 
-Every HyperMind answer includes a cryptographically-signed derivation showing exactly how the conclusion was reached:
+  console.log('\\n=== AGENT FINDINGS ===');
+  console.log(result.answer);
+  console.log('\\n=== EVIDENCE CHAIN ===');
+  console.log(result.evidence);
+  console.log('\\n=== PROOF HASH ===');
+  console.log(result.proofHash);
+}
 
+investigate().catch(console.error);
 ```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                           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:
+## Complete Underwriting Example
 
 ```javascript
-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
-  }
-})
-```
-
-### Distributed Deployment (Kubernetes)
-
-rust-kgdb scales from single-node to distributed cluster on the same codebase.
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                         DISTRIBUTED ARCHITECTURE                             │
-│                                                                              │
-│   ┌─────────────────────────────────────────────────────────────────────┐   │
-│   │                        COORDINATOR NODE                              │   │
-│   │  • Query planning & optimization                                     │   │
-│   │  • HDRF streaming partitioner (subject-anchored)                    │   │
-│   │  • Raft consensus leader                                            │   │
-│   │  • gRPC routing to executors                                        │   │
-│   └──────────────────────────────┬──────────────────────────────────────┘   │
-│                                  │                                          │
-│          ┌───────────────────────┼───────────────────────┐                 │
-│          │                       │                       │                 │
-│          ▼                       ▼                       ▼                 │
-│   ┌─────────────┐         ┌─────────────┐         ┌─────────────┐         │
-│   │ EXECUTOR 1  │         │ EXECUTOR 2  │         │ EXECUTOR 3  │         │
-│   │             │         │             │         │             │         │
-│   │ Partition 0 │         │ Partition 1 │         │ Partition 2 │         │
-│   │ RocksDB     │         │ RocksDB     │         │ RocksDB     │         │
-│   │ Embeddings  │         │ Embeddings  │         │ Embeddings  │         │
-│   └─────────────┘         └─────────────┘         └─────────────┘         │
-│                                                                              │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
+const { GraphDB, DatalogProgram, evaluateDatalog } = require('rust-kgdb');
 
-**Deployment with Helm:**
-```bash
-# Deploy to Kubernetes
-helm install rust-kgdb ./infra/helm -n rust-kgdb --create-namespace
+// ============================================================
+// Automated Underwriting Rules Engine
+// ============================================================
+const db = new GraphDB('http://underwriting.org/');
 
-# Scale executors
-kubectl scale deployment rust-kgdb-executor --replicas=5 -n rust-kgdb
+// Load applicant data
+db.loadTtl(`
+  @prefix : <http://underwriting.org/> .
+  @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+  :APP001 a :Application ;
+    :applicant :PERSON001 ;
+    :requestedAmount "500000"^^xsd:decimal ;
+    :propertyType :SingleFamily .
+
+  :PERSON001 a :Person ;
+    :creditScore "720"^^xsd:integer ;
+    :dti "0.35"^^xsd:decimal ;
+    :employmentYears "5"^^xsd:integer ;
+    :bankruptcyHistory false .
+`);
+
+// Underwriting rules as Datalog
+const datalog = new DatalogProgram();
+
+// Facts
+datalog.addFact(JSON.stringify({predicate:'application', terms:['APP001']}));
+datalog.addFact(JSON.stringify({predicate:'credit_score', terms:['APP001','720']}));
+datalog.addFact(JSON.stringify({predicate:'dti', terms:['APP001','0.35']}));
+datalog.addFact(JSON.stringify({predicate:'employment_years', terms:['APP001','5']}));
+
+// Auto-Approve Rule: Credit > 700, DTI < 0.43, Employment > 2 years
+datalog.addRule(JSON.stringify({
+  head: {predicate:'auto_approve', terms:['?App']},
+  body: [
+    {predicate:'application', terms:['?App']},
+    {predicate:'credit_score', terms:['?App','?Credit']},
+    {predicate:'dti', terms:['?App','?DTI']},
+    {predicate:'employment_years', terms:['?App','?Years']}
+    // Note: Numeric comparisons would be handled in production
+  ]
+}));
 
-# Check cluster health
-kubectl get pods -n rust-kgdb
+const decisions = JSON.parse(evaluateDatalog(datalog));
+console.log('Underwriting decisions:', decisions);
 ```
 
-**Key Distributed Features:**
-| Feature | Description |
-|---------|-------------|
-| **HDRF Partitioning** | Subject-anchored streaming partitioner minimizes edge cuts |
-| **Raft Consensus** | Leader election, log replication, consistency |
-| **gRPC Communication** | Efficient inter-node query routing |
-| **Shadow Partitions** | Zero-downtime rebalancing (~10ms pause) |
-| **DataFusion OLAP** | Arrow-native analytical queries |
+---
 
-### Memory System
+## API Reference
 
-Agents have persistent memory across sessions:
+### GraphDB
 
 ```javascript
-const agent = new HyperMindAgent({
-  kg: db,
-  memory: new MemoryManager({
-    workingMemorySize: 10,           // Current session cache
-    episodicRetentionDays: 30,       // Episode history
-    longTermGraph: 'http://memory/'  // Persistent knowledge
-  })
-})
+const db = new GraphDB(baseUri)       // Create database
+db.loadTtl(turtle, graphUri)          // Load Turtle data
+db.querySelect(sparql)                // SELECT query → [{bindings}]
+db.queryConstruct(sparql)             // CONSTRUCT query → triples
+db.countTriples()                     // Total triple count
+db.clear()                            // Clear all data
+db.getVersion()                       // SDK version
 ```
 
-### Memory Hypergraph: How AI Agents Remember
-
-rust-kgdb introduces the **Memory Hypergraph** - a temporal knowledge graph where agent memory is stored in the *same* quad store as your domain knowledge, with hyper-edges connecting episodes to KG entities.
-
-```
-┌─────────────────────────────────────────────────────────────────────────────────┐
-│                         MEMORY HYPERGRAPH ARCHITECTURE                           │
-│                                                                                  │
-│   ┌─────────────────────────────────────────────────────────────────────────┐   │
-│   │                    AGENT MEMORY LAYER (am: graph)                        │   │
-│   │                                                                          │   │
-│   │   Episode:001                Episode:002                Episode:003      │   │
-│   │   ┌───────────────┐         ┌───────────────┐         ┌───────────────┐ │   │
-│   │   │ Fraud ring    │         │ Underwriting  │         │ Follow-up     │ │   │
-│   │   │ detected in   │         │ denied claim  │         │ investigation │ │   │
-│   │   │ Provider P001 │         │ from P001     │         │ on P001       │ │   │
-│   │   │               │         │               │         │               │ │   │
-│   │   │ Dec 10, 14:30 │         │ Dec 12, 09:15 │         │ Dec 15, 11:00 │ │   │
-│   │   │ Score: 0.95   │         │ Score: 0.87   │         │ Score: 0.92   │ │   │
-│   │   └───────┬───────┘         └───────┬───────┘         └───────┬───────┘ │   │
-│   │           │                         │                         │         │   │
-│   └───────────┼─────────────────────────┼─────────────────────────┼─────────┘   │
-│               │ HyperEdge:              │ HyperEdge:              │             │
-│               │ "QueriedKG"             │ "DeniedClaim"           │             │
-│               ▼                         ▼                         ▼             │
-│   ┌─────────────────────────────────────────────────────────────────────────┐   │
-│   │                    KNOWLEDGE GRAPH LAYER (domain graph)                  │   │
-│   │                                                                          │   │
-│   │      Provider:P001 ──────────────▶ Claim:C123 ◀────────── Claimant:C001 │   │
-│   │           │                            │                        │        │   │
-│   │           │ :hasRiskScore              │ :amount                │ :name  │   │
-│   │           ▼                            ▼                        ▼        │   │
-│   │        "0.87"                       "50000"                 "John Doe"   │   │
-│   │                                                                          │   │
-│   │      ┌─────────────────────────────────────────────────────────────┐    │   │
-│   │      │  SAME QUAD STORE - Single SPARQL query traverses BOTH       │    │   │
-│   │      │  memory graph AND knowledge graph!                          │    │   │
-│   │      └─────────────────────────────────────────────────────────────┘    │   │
-│   │                                                                          │   │
-│   └─────────────────────────────────────────────────────────────────────────┘   │
-│                                                                                  │
-│   ┌─────────────────────────────────────────────────────────────────────────┐   │
-│   │                         TEMPORAL SCORING FORMULA                         │   │
-│   │                                                                          │   │
-│   │   Score = α × Recency + β × Relevance + γ × Importance                   │   │
-│   │                                                                          │   │
-│   │   where:                                                                 │   │
-│   │     Recency    = 0.995^hours (12% decay/day)                            │   │
-│   │     Relevance  = cosine_similarity(query, episode)                      │   │
-│   │     Importance = log10(access_count + 1) / log10(max + 1)               │   │
-│   │                                                                          │   │
-│   │   Default: α=0.3, β=0.5, γ=0.2                                          │   │
-│   └─────────────────────────────────────────────────────────────────────────┘   │
-│                                                                                  │
-└─────────────────────────────────────────────────────────────────────────────────┘
-```
-
-**Without Memory Hypergraph** (LangChain, LlamaIndex):
-```javascript
-// Ask about last week's findings
-agent.chat("What fraud patterns did we find with Provider P001?")
-// Response: "I don't have that information. Could you describe what you're looking for?"
-// Cost: Re-run entire fraud detection pipeline ($5 in API calls, 30 seconds)
-```
+### GraphFrame
 
-**With Memory Hypergraph** (rust-kgdb HyperMind Framework):
 ```javascript
-// HyperMind API: Recall memories with KG context
-const enrichedMemories = await agent.recallWithKG({
-  query: "Provider P001 fraud",
-  kgFilter: { predicate: ":amount", operator: ">", value: 25000 },
-  limit: 10
-})
-
-// Returns typed results with linked KG context:
-// {
-//   episode: "Episode:001",
-//   finding: "Fraud ring detected in Provider P001",
-//   kgContext: {
-//     provider: "Provider:P001",
-//     claims: [{ id: "Claim:C123", amount: 50000 }],
-//     riskScore: 0.87
-//   },
-//   semanticHash: "semhash:fraud-provider-p001-ring-detection"
-// }
+const gf = new GraphFrame(verticesJson, edgesJson)
+gf.pageRank(dampingFactor, iterations)  // PageRank scores
+gf.connectedComponents()                // Component labels
+gf.triangleCount()                      // Triangle count
+gf.shortestPaths(sourceId)              // Shortest path distances
+gf.find(motifPattern)                   // Motif pattern matching
 ```
 
-#### Semantic Hashing for Idempotent Responses
-
-Same question = Same answer. Even with **different wording**. Critical for compliance.
+### EmbeddingService
 
 ```javascript
-// First call: Compute answer, cache with semantic hash
-const result1 = await agent.call("Analyze claims from Provider P001")
-// Semantic Hash: semhash:fraud-provider-p001-claims-analysis
-
-// Second call (different wording, same intent): Cache HIT!
-const result2 = await agent.call("Show me P001's claim patterns")
-// Cache HIT - same semantic hash
-
-// Compliance officer: "Why are these identical?"
-// You: "Semantic hashing - same meaning, same output, regardless of phrasing."
-```
-
-**How it works**: Query embeddings are hashed via **Locality-Sensitive Hashing (LSH)** with random hyperplane projections. Semantically similar queries map to the same bucket.
-
-### HyperMind vs MCP (Model Context Protocol)
-
-Why domain-enriched proxies beat generic function calling:
-
-```
-┌───────────────────────┬──────────────────────┬──────────────────────────┐
-│ Feature               │ MCP                  │ HyperMind Proxy          │
-├───────────────────────┼──────────────────────┼──────────────────────────┤
-│ Type Safety           │ ❌ String only       │ ✅ Full type system      │
-│ Domain Knowledge      │ ❌ Generic           │ ✅ Domain-enriched       │
-│ Tool Composition      │ ❌ Isolated          │ ✅ Morphism composition  │
-│ Validation            │ ❌ Runtime           │ ✅ Compile-time          │
-│ Security              │ ❌ None              │ ✅ WASM sandbox          │
-│ Audit Trail           │ ❌ None              │ ✅ Execution witness     │
-│ LLM Context           │ ❌ Generic schema    │ ✅ Rich domain hints     │
-│ Capability Control    │ ❌ All or nothing    │ ✅ Fine-grained caps     │
-├───────────────────────┼──────────────────────┼──────────────────────────┤
-│ Result                │ 60% accuracy         │ 95%+ accuracy            │
-└───────────────────────┴──────────────────────┴──────────────────────────┘
+const emb = new EmbeddingService()
+emb.storeVector(entityId, float32Array) // Store embedding
+emb.rebuildIndex()                       // Build HNSW index
+emb.findSimilar(entityId, k, threshold)  // Find similar entities
+emb.onTripleInsert(s, p, o, g)          // Update neighbor cache
+emb.getNeighborsOut(entityId)           // Get outgoing neighbors
 ```
 
-**MCP**: LLM generates query → hope it works
-**HyperMind**: LLM selects tools → type system validates → guaranteed correct
+### DatalogProgram
 
 ```javascript
-// MCP APPROACH (Generic function calling)
-// Tool: search_database(query: string)
-// LLM generates: "SELECT * FROM claims WHERE suspicious = true"
-// Result: ❌ SQL injection risk, "suspicious" column doesn't exist
-
-// HYPERMIND APPROACH (Domain-enriched proxy)
-// Tool: kg.datalog.infer with fraud rules
-const result = await agent.call('Find collusion patterns')
-// Result: ✅ Type-safe, domain-aware, auditable
+const dl = new DatalogProgram()
+dl.addFact(factJson)           // Add fact
+dl.addRule(ruleJson)           // Add rule
+evaluateDatalog(dl)            // Run evaluation → facts JSON
+queryDatalog(dl, queryJson)    // Query specific predicate
 ```
 
-### Why Vanilla LLMs Fail
+### Pregel
 
-When you ask an LLM to query a knowledge graph, it produces **broken SPARQL 85% of the time**:
-
-```
-User: "Find all professors"
-
-Vanilla LLM Output:
-┌───────────────────────────────────────────────────────────────────────┐
-│ ```sparql                                                             │
-│ PREFIX ub: <http://swat.cse.lehigh.edu/onto/univ-bench.owl#>         │
-│ SELECT ?professor WHERE {                                             │
-│   ?professor a ub:Faculty .   ← WRONG! Schema has "Professor"        │
-│ }                                                                     │
-│ ```                            ← Parser rejects markdown              │
-│                                                                       │
-│ This query retrieves all faculty members from the LUBM dataset.      │
-│                                ↑ Explanation text breaks parsing      │
-└───────────────────────────────────────────────────────────────────────┘
-Result: ❌ PARSER ERROR - Invalid SPARQL syntax
+```javascript
+pregelShortestPaths(graphFrame, sourceId, maxIterations)
+// Returns: distance map from source to all vertices
 ```
 
-**Why it fails:**
-1. LLM wraps query in markdown code blocks → parser chokes
-2. LLM adds explanation text → mixed with query syntax
-3. LLM hallucinates class names → `ub:Faculty` doesn't exist (it's `ub:Professor`)
-4. LLM has no schema awareness → guesses predicates and classes
-
-**HyperMind fixes all of this** with schema injection and typed tools, achieving **71% accuracy** vs **0% for vanilla LLMs without schema**.
-
-### Competitive Landscape
-
-#### Triple Stores Comparison
-
-| System | Lookup Speed | Memory/Triple | WCOJ | Mobile | AI Framework |
-|--------|-------------|---------------|------|--------|--------------|
-| **rust-kgdb** | **449 ns** | **24 bytes** | ✅ Yes | ✅ Yes | ✅ HyperMind |
-| Tentris | ~5 µs | ~30 bytes | ✅ Yes | ❌ No | ❌ No |
-| RDFox | ~5 µs | 36-89 bytes | ❌ No | ❌ No | ❌ No |
-| AllegroGraph | ~10 µs | 50+ bytes | ❌ No | ❌ No | ❌ No |
-| Virtuoso | ~5 µs | 35-75 bytes | ❌ No | ❌ No | ❌ No |
-| Blazegraph | ~100 µs | 100+ bytes | ❌ No | ❌ No | ❌ No |
-| Apache Jena | 150+ µs | 50-60 bytes | ❌ No | ❌ No | ❌ No |
-| Neo4j | ~5 µs | 70+ bytes | ❌ No | ❌ No | ❌ No |
-| Amazon Neptune | ~5 µs | N/A (managed) | ❌ No | ❌ No | ❌ No |
-
-**Note**: Tentris implements WCOJ (see [ISWC 2025 paper](https://papers.dice-research.org/2025/ISWC_Tentris-WCOJ-Update/public.pdf)). rust-kgdb is the only system combining WCOJ with mobile support and integrated AI framework.
+### Factory Functions
 
-#### AI Framework Architectural Comparison
-
-| Framework | Type Safety | Schema Aware | Symbolic Execution | Audit Trail |
-|-----------|-------------|--------------|-------------------|-------------|
-| **HyperMind** | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
-| LangChain | ❌ No | ❌ No | ❌ No | ❌ No |
-| DSPy | ⚠️ Partial | ❌ No | ❌ No | ❌ No |
-
-**Note**: This compares architectural features. Benchmark (Dec 2025): Schema injection brings all frameworks to ~71% accuracy equally.
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    COMPETITIVE LANDSCAPE                        │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│  Tentris:        WCOJ-optimized, but no mobile or AI framework  │
-│  RDFox:          Fast commercial, but expensive, no mobile      │
-│  AllegroGraph:   Enterprise features, but slower, no mobile     │
-│  Apache Jena:    Great features, but 150+ µs lookups            │
-│  Neo4j:          Popular, but no SPARQL/RDF standards           │
-│  Amazon Neptune: Managed, but cloud-only vendor lock-in         │
-│                                                                 │
-│  rust-kgdb:      449 ns lookups, WCOJ joins, mobile-native      │
-│                  Standalone → Clustered on same codebase        │
-│                  Deterministic planner, audit-ready              │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
+```javascript
+friendsGraph()     // Sample social network
+chainGraph(n)      // Linear chain of n vertices
+starGraph(n)       // Star topology with n leaves
+completeGraph(n)   // Fully connected graph
+cycleGraph(n)      // Circular graph
 ```
 
 ---
 
-## License
-
-Apache 2.0
+Apache 2.0 License