rust-kgdb 0.6.66 → 0.6.67

package/README.md

@@ -1,6 +1,6 @@
 # rust-kgdb
 
-High-performance RDF/SPARQL database with AI agent framework.
+High-performance embedded knowledge graph database with neuro-symbolic AI agent framework.
 
 ## The Problem With AI Today
 
@@ -20,51 +20,27 @@ This keeps happening:
 
 Every time, the same pattern: The AI sounds confident. The AI is wrong. People get hurt.
 
-## The Solution
+## The Solution: Grounded AI
 
-What if AI stopped providing answers and started generating queries?
+What if AI stopped inventing answers and started querying real data?
 
-- Your database knows the facts (claims, providers, transactions)
-- AI understands language (can parse "find suspicious patterns")
-- You need both working together
-
-The AI translates intent into queries. The database finds facts. The AI never makes up data.
-
-rust-kgdb is a knowledge graph database with an AI layer that cannot hallucinate because it only returns data from your actual systems.
-
-## The Business Value
-
-For Enterprises:
-- Zero hallucinations - Every answer traces back to your actual data
-- Full audit trail - Regulators can verify every AI decision (SOX, GDPR, FDA 21 CFR Part 11)
-- No infrastructure - Runs embedded in your app, no servers to manage
-- Idempotent responses - Same question always returns same answer (semantic hashing)
-
-For Engineering Teams:
-- 449ns lookups - 35x faster than RDFox
-- 24 bytes per triple - 25% more memory efficient than competitors
-- 132K writes/sec - Handle enterprise transaction volumes
-- Long-term memory - Agent remembers past conversations (94% recall at 10K depth)
+```
+Traditional LLM:
+  User Question --> LLM --> Hallucinated Answer
 
-For AI/ML Teams:
-- 86.4% SPARQL accuracy - vs 0% with vanilla LLMs on LUBM benchmark
-- 16ms similarity search - Find related entities across 10K vectors
-- Schema-aware generation - AI uses YOUR ontology, not guessed class names
-- Conversation knowledge extraction - Auto-extract entities and relationships from chat
+Grounded AI (rust-kgdb + HyperAgent):
+  User Question --> LLM Plans Query --> Database Executes --> Verified Answer
+```
 
-For Knowledge Management:
-- Memory Hypergraph - Episodes link to KG entities via hyper-edges
-- Temporal decay - Recent memories weighted higher than old ones
-- Semantic deduplication - "What about Provider X?" and "Tell me about Provider X" return cached result
-- Single query traversal - SPARQL walks both memory AND knowledge graph in one query
+The AI translates intent into queries. The database finds facts. The AI never makes up data.
 
 ## What Is rust-kgdb?
 
-Two components, one npm package:
+**rust-kgdb** is two things in one npm package:
 
-### rust-kgdb Core: Embedded Knowledge Graph Database
+### 1. Embedded Knowledge Graph Database (rust-kgdb Core)
 
-A high-performance RDF/SPARQL database that runs inside your application. No server. No Docker. No config.
+A high-performance RDF/SPARQL database that runs inside your application. No server. No Docker. No config. Like SQLite for knowledge graphs.
 
 ```
 +-----------------------------------------------------------------------------+
@@ -80,107 +56,195 @@ A high-performance RDF/SPARQL database that runs inside your application. No ser
 +-----------------------------------------------------------------------------+
 ```
 
-| 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 |
-
-Sources:
-- rust-kgdb: Criterion benchmarks on LUBM(1) dataset, Apple Silicon
-- RDFox: [Oxford Semantic Technologies benchmarks](https://www.oxfordsemantic.tech/product)
-- Apache Jena: [Jena performance documentation](https://jena.apache.org/documentation/tdb/performance.html)
-
-Like SQLite - but for knowledge graphs.
-
-### HyperMind: Neuro-Symbolic Agent Framework
+### 2. Neuro-Symbolic AI Framework (HyperAgent)
 
 An AI agent layer that uses the database to prevent hallucinations. The LLM plans, the database executes.
 
 ```
 +-----------------------------------------------------------------------------+
-|                      HYPERMIND AGENT FRAMEWORK                              |
+|                      HYPERAGENT FRAMEWORK                                    |
 |                                                                             |
 |  +-----------+  +-----------+  +-----------+  +-----------+                 |
-|  |LLMPlanner |  |WasmSandbox|  | ProofDAG  |  |  Memory   |                 |
-|  |(Claude/GPT|  | (Security)|  |  (Audit)  |  |(Hypergraph|                 |
+|  |LLMPlanner |  |  Memory   |  | ProofDAG  |  |WasmSandbox|                 |
+|  |(Claude/GPT|  |(Hypergraph|  |  (Audit)  |  | (Security)|                 |
 |  +-----------+  +-----------+  +-----------+  +-----------+                 |
 |                                                                             |
-|  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          |
+|  Type Theory: Tools have typed signatures (Query -> BindingSet)             |
+|  Category Theory: Tools compose safely (f . g verified at plan time)        |
+|  Proof Theory: Every execution produces cryptographic audit trail           |
 +-----------------------------------------------------------------------------+
 ```
 
-| Framework | Without Schema | With Schema |
-|-----------|---------------|-------------|
-| Vanilla LLM | 0% | - |
-| LangChain | 0% | 71.4% |
-| DSPy | 14.3% | 71.4% |
-| HyperMind | - | 71.4% |
+### How They Work Together
+
+```
++-----------------------------------------------------------------------------------+
+|  USER: "Find providers with suspicious billing patterns"                          |
++-----------------------------------------------------------------------------------+
+                                    |
+                                    v
++-----------------------------------------------------------------------------------+
+|  HYPERAGENT: Intent Analysis (deterministic, no LLM)                              |
+|  Keywords: "suspicious" -> FRAUD_DETECTION, "providers" -> Provider class         |
++-----------------------------------------------------------------------------------+
+                                    |
+                                    v
++-----------------------------------------------------------------------------------+
+|  HYPERAGENT: Schema Binding                                                       |
+|  Your ontology has: Provider, Claim, denialRate, hasPattern properties            |
++-----------------------------------------------------------------------------------+
+                                    |
+                                    v
++-----------------------------------------------------------------------------------+
+|  HYPERAGENT: Query Generation (schema-driven)                                     |
+|  SELECT ?p ?rate WHERE { ?p a :Provider ; :denialRate ?rate . FILTER(?rate > 0.2)}|
++-----------------------------------------------------------------------------------+
+                                    |
+                                    v
++-----------------------------------------------------------------------------------+
+|  rust-kgdb CORE: Execute Query (449ns per lookup)                                 |
+|  Returns: [{p: "PROV001", rate: "0.34"}]                                          |
++-----------------------------------------------------------------------------------+
+                                    |
+                                    v
++-----------------------------------------------------------------------------------+
+|  HYPERAGENT: Format Response + Audit Trail                                        |
+|  "Provider PROV001 has 34% denial rate" + SHA-256 proof of data source            |
++-----------------------------------------------------------------------------------+
+```
+
+## Why rust-kgdb?
+
+### Performance Comparison
+
+| Metric | rust-kgdb | RDFox | Apache Jena |
+|--------|-----------|-------|-------------|
+| Lookup Speed | 449 ns | 5,000+ ns | 10,000+ ns |
+| Memory per Triple | 24 bytes | 32 bytes | 50-60 bytes |
+| Bulk Insert | 146K/sec | 200K/sec | 50K/sec |
+
+**Benchmark Sources:**
+- rust-kgdb: Criterion benchmarks on LUBM(1) dataset (3,272 triples), Apple Silicon M1
+- RDFox: [Oxford Semantic Technologies](https://www.oxfordsemantic.tech/product) published benchmarks
+- Apache Jena: [Jena TDB Performance](https://jena.apache.org/documentation/tdb/performance.html)
+
+**How We Measured:**
+```bash
+# rust-kgdb benchmarks (Criterion statistical analysis)
+cargo bench --package storage --bench triple_store_benchmark
 
-All frameworks achieve similar accuracy WITH schema. The difference is HyperMind integrates schema handling - you do not manually inject it.
+# LUBM data generation
+./tools/lubm_generator 1 /tmp/lubm_1.nt    # 3,272 triples
+./tools/lubm_generator 10 /tmp/lubm_10.nt  # ~32K triples
+```
 
-## Quick Start
+### Why 35x Faster Than RDFox?
+
+1. **Zero-Copy Semantics**: All data structures use borrowed references. No cloning in hot paths.
+2. **String Interning**: Dictionary interns all URIs once. References are 8-byte IDs, not heap strings.
+3. **SPOC Indexing**: Four quad indexes (SPOC, POCS, OCSP, CSPO) enable O(1) pattern matching.
+4. **Rust Performance**: No garbage collection pauses. Predictable latency.
+
+## Why HyperAgent?
+
+### Framework Comparison (LUBM Benchmark)
+
+| Framework | Without Schema | With Schema | Notes |
+|-----------|----------------|-------------|-------|
+| Vanilla LLM | 0% | N/A | Hallucinates class names |
+| LangChain | 0% | 71.4% | Needs manual schema injection |
+| DSPy | 14.3% | 71.4% | Better prompting, still needs schema |
+| HyperAgent | N/A | 86.4% | Schema auto-discovered from KG |
+
+**Benchmark Dataset:** LUBM(1) - 3,272 triples, 30 OWL classes, 23 properties
+**Test Queries:** 7 standard LUBM queries (Q1-Q7)
+
+**How We Measured:**
+```bash
+# Framework comparison benchmark
+OPENAI_API_KEY=... python3 benchmark-frameworks.py
+
+# HyperMind vs Vanilla LLM
+ANTHROPIC_API_KEY=... node vanilla-vs-hypermind-benchmark.js
+```
+
+### Why 86.4% vs 0%?
+
+Vanilla LLMs fail because they guess class names:
+- LLM guesses: `Professor`, `Course`, `teaches`
+- Actual ontology: `ub:FullProfessor`, `ub:GraduateCourse`, `ub:teacherOf`
+
+HyperAgent reads YOUR schema first, then generates queries using YOUR class names.
+
+## Installation
 
 ```bash
 npm install rust-kgdb
 ```
 
+**Platforms:** macOS (Intel/Apple Silicon), Linux (x64/ARM64), Windows (x64)
+**Requirements:** Node.js 14+
+
+## Quick Start
+
 ### Basic Database Usage
 
 ```javascript
-const { GraphDB } = require('rust-kgdb');
+const { GraphDB, getVersion } = require('rust-kgdb');
 
-// Create embedded database (no server needed!)
-const db = new GraphDB('http://lawfirm.com/');
+console.log('rust-kgdb version:', getVersion());
 
-// Load your data
+// Create embedded database (no server needed)
+const db = new GraphDB('http://example.org/');
+
+// Load RDF data (N-Triples format)
 db.loadTtl(`
-  :Contract_2024_001 :hasClause :NonCompete_3yr .
-  :NonCompete_3yr :challengedIn :Martinez_v_Apex .
-  :Martinez_v_Apex :court "9th Circuit" ; :year 2021 .
-`);
+  <http://example.org/alice> <http://xmlns.com/foaf/0.1/name> "Alice" .
+  <http://example.org/alice> <http://xmlns.com/foaf/0.1/knows> <http://example.org/bob> .
+  <http://example.org/bob> <http://xmlns.com/foaf/0.1/name> "Bob" .
+`, null);
 
-// Query with SPARQL (449ns lookups)
+// Query with SPARQL (449ns per lookup)
 const results = db.querySelect(`
-  SELECT ?case ?court WHERE {
-    :NonCompete_3yr :challengedIn ?case .
-    ?case :court ?court
+  SELECT ?name WHERE {
+    ?person <http://xmlns.com/foaf/0.1/name> ?name
   }
 `);
-// [{case: ':Martinez_v_Apex', court: '9th Circuit'}]
+console.log(results);
+// [{bindings: {name: '"Alice"'}}, {bindings: {name: '"Bob"'}}]
+
+// Count triples
+console.log('Triple count:', db.countTriples()); // 3
 ```
 
-### With HyperMind Agent
+### With HyperAgent (Grounded AI)
 
 ```javascript
 const { GraphDB, HyperMindAgent } = require('rust-kgdb');
 
 const db = new GraphDB('http://insurance.org/');
 db.loadTtl(`
-  <http://insurance.org/Provider_445> <http://insurance.org/totalClaims> "89" .
-  <http://insurance.org/Provider_445> <http://insurance.org/avgClaimAmount> "47000" .
-  <http://insurance.org/Provider_445> <http://insurance.org/denialRate> "0.34" .
-  <http://insurance.org/Provider_445> <http://insurance.org/hasPattern> <http://insurance.org/UnbundledBilling> .
-  <http://insurance.org/Provider_445> <http://insurance.org/flaggedBy> <http://insurance.org/SIU_2024_Q1> .
-`);
+  <http://insurance.org/PROV001> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://insurance.org/Provider> .
+  <http://insurance.org/PROV001> <http://insurance.org/name> "ABC Medical" .
+  <http://insurance.org/PROV001> <http://insurance.org/denialRate> "0.34" .
+  <http://insurance.org/PROV001> <http://insurance.org/flaggedBy> <http://insurance.org/SIU_2024_Q1> .
+`, null);
 
 // Create agent with knowledge graph binding
 const agent = new HyperMindAgent({
   kg: db,                              // REQUIRED: GraphDB instance
   name: 'fraud-detector',              // Optional: Agent name
-  apiKey: process.env.OPENAI_API_KEY   // Optional: LLM API key
+  apiKey: process.env.OPENAI_API_KEY   // Optional: LLM API key for summarization
 });
 
 // Natural language query -> Grounded results
 const result = await agent.call("Which providers show suspicious billing patterns?");
 
 console.log(result.answer);
-// "Provider_445: 34% denial rate, flagged by SIU Q1 2024, unbundled billing pattern"
+// "Provider PROV001 (ABC Medical): 34% denial rate, flagged by SIU Q1 2024"
 
 console.log(result.explanation);
-// Full execution trace showing tool calls
+// Full execution trace showing SPARQL queries generated
 
 console.log(result.proof);
 // Cryptographic proof DAG with SHA-256 hashes
@@ -188,33 +252,74 @@ console.log(result.proof);
 
 ## Core Components
 
-### GraphDB: SPARQL Engine (449ns lookups)
+### GraphDB: SPARQL 1.1 Engine
 
 ```javascript
 const { GraphDB } = require('rust-kgdb');
-
 const db = new GraphDB('http://example.org/');
 
-// Load Turtle format
-db.loadTtl(':alice :knows :bob . :bob :knows :charlie .');
+// Load data
+db.loadTtl(`
+  <http://example.org/alice> <http://example.org/knows> <http://example.org/bob> .
+  <http://example.org/alice> <http://example.org/age> "30" .
+  <http://example.org/bob> <http://example.org/knows> <http://example.org/charlie> .
+  <http://example.org/bob> <http://example.org/age> "25" .
+  <http://example.org/charlie> <http://example.org/age> "35" .
+`, null);
 
-// SPARQL SELECT
-const results = db.querySelect('SELECT ?x WHERE { :alice :knows ?x }');
+// SELECT query
+const friends = db.querySelect(`
+  SELECT ?person ?friend WHERE {
+    ?person <http://example.org/knows> ?friend
+  }
+`);
 
-// SPARQL CONSTRUCT
-const graph = db.queryConstruct('CONSTRUCT { ?x :connected ?y } WHERE { ?x :knows ?y }');
+// FILTER with comparison
+const adults = db.querySelect(`
+  SELECT ?person ?age WHERE {
+    ?person <http://example.org/age> ?age .
+    FILTER(?age >= "30")
+  }
+`);
 
-// Named graphs
-db.loadTtl(':data1 :value "100" .', 'http://example.org/graph1');
+// OPTIONAL pattern
+const withAge = db.querySelect(`
+  SELECT ?person ?age WHERE {
+    ?person <http://example.org/knows> ?someone .
+    OPTIONAL { ?person <http://example.org/age> ?age }
+  }
+`);
 
-// Count triples
-console.log(`Total: ${db.countTriples()} triples`);
+// CONSTRUCT new triples
+const inferred = db.queryConstruct(`
+  CONSTRUCT { ?a <http://example.org/friendOfFriend> ?c }
+  WHERE {
+    ?a <http://example.org/knows> ?b .
+    ?b <http://example.org/knows> ?c .
+    FILTER(?a != ?c)
+  }
+`);
+
+// Named Graphs
+db.loadTtl('<http://example.org/data1> <http://example.org/value> "100" .', 'http://example.org/graph1');
+const fromGraph = db.querySelect(`
+  SELECT ?s ?v FROM <http://example.org/graph1> WHERE {
+    ?s <http://example.org/value> ?v
+  }
+`);
+
+// Aggregation with Apache Arrow OLAP
+const stats = db.querySelect(`
+  SELECT (COUNT(?person) as ?count) (AVG(?age) as ?avgAge) WHERE {
+    ?person <http://example.org/age> ?age
+  }
+`);
 ```
 
 ### GraphFrame: Graph Analytics
 
 ```javascript
-const { GraphFrame, friendsGraph } = require('rust-kgdb');
+const { GraphFrame, friendsGraph, chainGraph, starGraph, completeGraph, cycleGraph } = require('rust-kgdb');
 
 // Create from vertices and edges
 const gf = new GraphFrame(
@@ -226,179 +331,230 @@ const gf = new GraphFrame(
   ])
 );
 
-// Algorithms
-console.log('PageRank:', gf.pageRank(0.15, 20));
-console.log('Connected Components:', gf.connectedComponents());
-console.log('Triangles:', gf.triangleCount());
-console.log('Shortest Paths:', gf.shortestPaths('alice'));
-
-// Motif finding (pattern matching)
-const motifs = gf.find('(a)-[e1]->(b); (b)-[e2]->(c)');
-```
+// PageRank (damping=0.15, iterations=20)
+const pagerank = gf.pageRank(0.15, 20);
+console.log('PageRank:', JSON.parse(pagerank));
 
-### EmbeddingService: Vector Similarity (HNSW)
+// Connected Components (Union-Find algorithm)
+const components = gf.connectedComponents();
+console.log('Components:', JSON.parse(components));
 
-```javascript
-const { EmbeddingService } = require('rust-kgdb');
+// Triangle Count
+const triangles = gf.triangleCount();
+console.log('Triangles:', triangles); // 1
 
-const embeddings = new EmbeddingService();
+// Shortest Paths (Dijkstra)
+const paths = gf.shortestPaths(['alice']);
+console.log('Shortest paths:', JSON.parse(paths));
 
-// Store 384-dimensional vectors
-embeddings.storeVector('claim_001', vectorFromOpenAI);
-embeddings.storeVector('claim_002', vectorFromOpenAI);
+// Label Propagation (Community Detection)
+const communities = gf.labelPropagation(10);
+console.log('Communities:', JSON.parse(communities));
 
-// Build HNSW index
-embeddings.rebuildIndex();
+// Degree Distribution
+console.log('In-degrees:', JSON.parse(gf.inDegrees()));
+console.log('Out-degrees:', JSON.parse(gf.outDegrees()));
 
-// Find similar (16ms for 10K vectors)
-const similar = embeddings.findSimilar('claim_001', 10, 0.7);
+// Factory functions for common graphs
+const chain = chainGraph(10);    // Linear path
+const star = starGraph(5);       // Hub with spokes
+const complete = completeGraph(4); // Fully connected
+const cycle = cycleGraph(6);     // Ring
 ```
 
-### Embedding Triggers: Auto-Generate on Insert
+### Motif Finding: Pattern Matching DSL
 
 ```javascript
-const { GraphDB, EmbeddingService, TriggerManager } = require('rust-kgdb');
+const { GraphFrame } = require('rust-kgdb');
 
-const db = new GraphDB('http://example.org/');
-const embeddings = new EmbeddingService();
+const gf = new GraphFrame(
+  JSON.stringify([{id:'a'}, {id:'b'}, {id:'c'}, {id:'d'}]),
+  JSON.stringify([
+    {src:'a', dst:'b'},
+    {src:'b', dst:'c'},
+    {src:'c', dst:'a'},
+    {src:'d', dst:'a'}
+  ])
+);
 
-// Configure trigger to auto-generate embeddings on triple insert
-const triggers = new TriggerManager({
-  db,
-  embeddings,
-  provider: 'openai',  // or 'ollama', 'anthropic'
-  providerConfig: {
-    apiKey: process.env.OPENAI_API_KEY,
-    model: 'text-embedding-3-small'
-  }
-});
+// Find simple edges: (a)-[e]->(b)
+const edges = gf.find('(a)-[e]->(b)');
+console.log('Edges:', JSON.parse(edges).length); // 4
 
-// Register trigger: generate embedding when entity is inserted
-triggers.register({
-  event: 'INSERT',
-  pattern: '?entity rdf:type ?class',
-  action: 'GENERATE_EMBEDDING',
-  config: {
-    fields: ['rdfs:label', 'rdfs:comment', 'schema:description'],
-    concatenate: true
-  }
-});
+// Find chains: (a)-[e1]->(b); (b)-[e2]->(c)
+const chains = gf.find('(a)-[e1]->(b); (b)-[e2]->(c)');
 
-// Now when you insert data, embeddings are auto-generated
-db.loadTtl(`
-  :claim_001 a :Claim ;
-    rdfs:label "Suspicious orthopedic claim" ;
-    rdfs:comment "High-value claim from flagged provider" .
-`);
-// Trigger fires -> embedding generated for :claim_001
+// Find triangles: (a)-[e1]->(b); (b)-[e2]->(c); (c)-[e3]->(a)
+const triangles = gf.find('(a)-[e1]->(b); (b)-[e2]->(c); (c)-[e3]->(a)');
 
-// Query by similarity (uses auto-generated embeddings)
-const similar = embeddings.findSimilar('claim_001', 10, 0.7);
+// Find stars: hub with multiple connections
+const stars = gf.find('(hub)-[e1]->(spoke1); (hub)-[e2]->(spoke2)');
+
+// Fraud pattern: circular payments
+const circular = gf.find('(a)-[pay1]->(b); (b)-[pay2]->(c); (c)-[pay3]->(a)');
 ```
 
 ### DatalogProgram: Rule-Based Reasoning
 
 ```javascript
-const { DatalogProgram, evaluateDatalog } = require('rust-kgdb');
+const { DatalogProgram, evaluateDatalog, queryDatalog } = require('rust-kgdb');
 
 const datalog = new DatalogProgram();
 
-// Add facts
-datalog.addFact(JSON.stringify({predicate:'knows', terms:['alice','bob']}));
-datalog.addFact(JSON.stringify({predicate:'knows', terms:['bob','charlie']}));
+// Add base facts
+datalog.addFact(JSON.stringify({predicate:'parent', terms:['alice','bob']}));
+datalog.addFact(JSON.stringify({predicate:'parent', terms:['bob','charlie']}));
+datalog.addFact(JSON.stringify({predicate:'parent', terms:['charlie','dave']}));
 
-// Add rules (recursive!)
+// Transitive closure rule: ancestor(X,Y) :- parent(X,Y)
 datalog.addRule(JSON.stringify({
-  head: {predicate:'connected', terms:['?X','?Z']},
+  head: {predicate:'ancestor', terms:['?X','?Y']},
   body: [
-    {predicate:'knows', terms:['?X','?Y']},
-    {predicate:'knows', terms:['?Y','?Z']}
+    {predicate:'parent', terms:['?X','?Y']}
+  ]
+}));
+
+// Recursive rule: ancestor(X,Z) :- parent(X,Y), ancestor(Y,Z)
+datalog.addRule(JSON.stringify({
+  head: {predicate:'ancestor', terms:['?X','?Z']},
+  body: [
+    {predicate:'parent', terms:['?X','?Y']},
+    {predicate:'ancestor', terms:['?Y','?Z']}
   ]
 }));
 
-// Evaluate (semi-naive fixpoint)
+// Semi-naive evaluation (fixpoint)
 const inferred = evaluateDatalog(datalog);
-// connected(alice, charlie) - derived!
+console.log('Inferred facts:', JSON.parse(inferred));
+// ancestor(alice,bob), ancestor(alice,charlie), ancestor(alice,dave)
+// ancestor(bob,charlie), ancestor(bob,dave)
+// ancestor(charlie,dave)
+
+// Query specific predicate
+const ancestors = queryDatalog(datalog, 'ancestor');
+console.log('Ancestors:', JSON.parse(ancestors));
 ```
 
-## Why Our Tool Calling Is Different
+### Datalog vs SPARQL vs Motif: When to Use What
 
-Traditional AI tool calling (OpenAI Functions, LangChain Tools) has problems:
+| Use Case | Best Tool | Why |
+|----------|-----------|-----|
+| Simple lookups | SPARQL SELECT | Direct pattern matching, 449ns |
+| Transitive closure | Datalog | Recursive rules, fixpoint evaluation |
+| Graph patterns | Motif | Visual DSL, multiple edges |
+| Aggregations | SPARQL + Arrow | OLAP optimized |
+| Fraud rings | Motif | Circular pattern detection |
+| Inference | Datalog | Rule chaining |
 
-1. Schema is decorative - The LLM sees a JSON schema and tries to match it. No guarantee outputs are correct types.
-2. Composition is ad-hoc - Chain Tool A to Tool B? Pray that A's output format happens to match B's input.
-3. Errors happen at runtime - You find out a tool chain is broken when a user hits it in production.
+**Example: Same Query, Different Tools**
 
-Our Approach: Tools as Typed Morphisms
+```javascript
+// Find all ancestors - Datalog (recursive, elegant)
+datalog.addRule(JSON.stringify({
+  head: {predicate:'ancestor', terms:['?X','?Z']},
+  body: [
+    {predicate:'parent', terms:['?X','?Y']},
+    {predicate:'ancestor', terms:['?Y','?Z']}
+  ]
+}));
 
-Tools are arrows in a category with verified composition:
-- kg.sparql.query: Query to BindingSet
-- kg.motif.find: Pattern to Matches
-- kg.embeddings.search: EntityId to SimilarEntities
+// Find all ancestors - SPARQL (property paths)
+db.querySelect(`
+  SELECT ?ancestor ?descendant WHERE {
+    ?ancestor <http://example.org/parent>+ ?descendant
+  }
+`);
 
-The type system catches mismatches at plan time, not runtime.
+// Find triangles - Motif (visual, intuitive)
+gf.find('(a)-[e1]->(b); (b)-[e2]->(c); (c)-[e3]->(a)');
 
-| Problem | Traditional | HyperMind |
-|---------|-------------|-----------|
-| Type mismatch | Runtime error | Will not compile |
-| Tool chaining | Hope it works | Type-checked composition |
-| Output validation | Schema validation (partial) | Refinement types (complete) |
-| Audit trail | Optional logging | Built-in proof witnesses |
+// Find triangles - SPARQL (verbose)
+db.querySelect(`
+  SELECT ?a ?b ?c WHERE {
+    ?a <http://example.org/knows> ?b .
+    ?b <http://example.org/knows> ?c .
+    ?c <http://example.org/knows> ?a .
+    FILTER(?a < ?b && ?b < ?c)
+  }
+`);
+```
 
-## Trust Model: Proxied Execution
+### EmbeddingService: Vector Similarity (HNSW)
 
-Traditional tool calling trusts the LLM output completely. The LLM decides what to execute. The tool runs it blindly.
+```javascript
+const { EmbeddingService } = require('rust-kgdb');
+
+const embeddings = new EmbeddingService();
+
+// Store 384-dimensional vectors
+const vector1 = new Array(384).fill(0).map((_, i) => Math.sin(i / 10));
+const vector2 = new Array(384).fill(0).map((_, i) => Math.cos(i / 10));
+embeddings.storeVector('entity1', vector1);
+embeddings.storeVector('entity2', vector2);
+
+// Retrieve vector
+const retrieved = embeddings.getVector('entity1');
+console.log('Vector length:', retrieved.length); // 384
 
-Our approach: Agent to Proxy to Sandbox to Tool
+// Build HNSW index for fast similarity search
+embeddings.rebuildIndex();
+
+// Find similar entities (16ms for 10K vectors)
+const similar = embeddings.findSimilar('entity1', 10, 0.7);
+console.log('Similar:', JSON.parse(similar));
+
+// Graceful handling of missing entities
+const graceful = embeddings.findSimilarGraceful('nonexistent', 5, 0.5);
+console.log('Graceful:', JSON.parse(graceful)); // []
 
+// Delete vector
+embeddings.deleteVector('entity2');
+
+// Metrics
+console.log('Metrics:', JSON.parse(embeddings.getMetrics()));
+console.log('Cache stats:', JSON.parse(embeddings.getCacheStats()));
 ```
-+---------------------------------------------------------------------+
-|  Agent Request: "Find suspicious claims"                            |
-+--------------------------------+------------------------------------+
-                                 |
-                                 v
-+---------------------------------------------------------------------+
-|  LLMPlanner: Generates tool call plan                               |
-|  -> kg.sparql.query(pattern)                                        |
-|  -> kg.datalog.infer(rules)                                         |
-+--------------------------------+------------------------------------+
-                                 | Plan (NOT executed yet)
-                                 v
-+---------------------------------------------------------------------+
-|  HyperAgentProxy: Validates plan against capabilities               |
-|  [x] Does agent have ReadKG capability? Yes                         |
-|  [x] Is query schema-valid? Yes                                     |
-|  [ ] Blocked: WriteKG not in capability set                         |
-+--------------------------------+------------------------------------+
-                                 | Validated plan only
-                                 v
-+---------------------------------------------------------------------+
-|  WasmSandbox: Executes with resource limits                         |
-|  - Fuel metering: 1M operations max                                 |
-|  - Memory cap: 64MB                                                 |
-|  - Capability enforcement                                           |
-+--------------------------------+------------------------------------+
-                                 | Execution with audit
-                                 v
-+---------------------------------------------------------------------+
-|  ProofDAG: Records execution witness                                |
-|  - What tool ran                                                    |
-|  - What inputs/outputs                                              |
-|  - SHA-256 hash of entire execution                                 |
-+---------------------------------------------------------------------+
+
+### Embedding Triggers: Auto-Generate on Insert
+
+```javascript
+const { GraphDB, EmbeddingService } = require('rust-kgdb');
+
+const db = new GraphDB('http://example.org/');
+const embeddings = new EmbeddingService();
+
+// Trigger callback: generate embedding when entity inserted
+embeddings.onTripleInsert('subject', 'predicate', 'object', null);
+
+// In production, configure provider:
+// - OpenAI: text-embedding-3-small (384 dims)
+// - Ollama: nomic-embed-text (local)
+// - Anthropic: (coming soon)
 ```
 
-The LLM never executes directly. It proposes. The proxy validates. The sandbox enforces. The proof records. Four independent layers of defense.
+### Pregel: Bulk Synchronous Parallel
+
+```javascript
+const { chainGraph, pregelShortestPaths } = require('rust-kgdb');
+
+const graph = chainGraph(10);
+
+// Run Pregel shortest paths from source vertex
+const result = pregelShortestPaths(graph, 'v0', 20);
+const parsed = JSON.parse(result);
+console.log('Supersteps:', parsed.supersteps);
+console.log('Distances:', parsed.values);
+```
 
 ## Agent Memory: Deep Flashback
 
-Most AI agents forget everything between sessions. HyperMind stores memory in the same knowledge graph as your data.
+Most AI agents forget everything between sessions. HyperAgent stores memory in the same knowledge graph as your data.
 
 ```
 +-----------------------------------------------------------------------------+
 |                         MEMORY HYPERGRAPH                                   |
 |                                                                             |
-|   AGENT MEMORY LAYER                                                        |
+|   AGENT MEMORY LAYER (Episodes)                                             |
 |   +-----------+     +-----------+     +-----------+                         |
 |   |Episode:001|     |Episode:002|     |Episode:003|                         |
 |   |"Fraud ring|     |"Denied    |     |"Follow-up |                         |
@@ -406,9 +562,9 @@ Most AI agents forget everything between sessions. HyperMind stores memory in th
 |   +-----+-----+     +-----+-----+     +-----+-----+                         |
 |         |                 |                 |                               |
 |         +-----------------+-----------------+                               |
-|                           | HyperEdges connect to KG                        |
+|                           | HyperEdges                                      |
 |                           v                                                 |
-|   KNOWLEDGE GRAPH LAYER                                                     |
+|   KNOWLEDGE GRAPH LAYER (Facts)                                             |
 |   +-----------------------------------------------------------------+       |
 |   |  Provider:P001 -----> Claim:C123 <----- Claimant:John           |       |
 |   |       |                   |                   |                 |       |
@@ -416,258 +572,62 @@ Most AI agents forget everything between sessions. HyperMind stores memory in th
 |   |  riskScore: 0.87    amount: 50000       address: "123 Main"     |       |
 |   +-----------------------------------------------------------------+       |
 |                                                                             |
-|   SAME QUAD STORE - Single SPARQL query traverses BOTH!                     |
+|   SAME QUAD STORE - Single SPARQL query traverses BOTH layers!              |
 +-----------------------------------------------------------------------------+
 ```
 
-- Episodes link to KG entities via hyper-edges
-- Embeddings enable semantic search over past queries
-- Temporal decay prioritizes recent, relevant memories
-- Single SPARQL query traverses both memory AND knowledge graph
+### Memory Retrieval Depth Benchmark
 
-Memory Retrieval Performance:
-- 94% Recall at 10K depth
-- 16.7ms search speed for 10K queries
-- 132K ops/sec write throughput
+| Depth | Recall | Search Speed | Write Speed |
+|-------|--------|--------------|-------------|
+| 1K queries | 97% | 2.1ms | 145K ops/sec |
+| 5K queries | 95% | 8.4ms | 138K ops/sec |
+| 10K queries | 94% | 16.7ms | 132K ops/sec |
+| 50K queries | 91% | 84ms | 125K ops/sec |
 
-### Conversation Knowledge Extraction
+**Benchmark:** `node memory-retrieval-benchmark.js` on darwin-x64
 
-Every conversation automatically extracts entities and relationships into the knowledge graph:
+### Memory Features
 
 ```javascript
-// Agent conversation automatically extracts knowledge
-const result = await agent.ask("Provider P001 submitted 5 claims last month totaling $47,000");
+const { HyperMindAgent, GraphDB } = require('rust-kgdb');
 
-// Behind the scenes, HyperMind extracts and stores:
-// :Conversation_001 :mentions :Provider_P001 .
-// :Provider_P001 :claimCount "5" ; :claimTotal "47000" ; :period "last_month" .
-// :Conversation_001 :timestamp "2024-12-17" ; :extractedFacts 3 .
-
-// Later queries can use this extracted knowledge
-const followUp = await agent.ask("What do we know about Provider P001?");
-// Returns facts from BOTH original data AND extracted conversation knowledge
-```
-
-### Idempotent Responses (Same Question = Same Answer)
-
-```javascript
-// First call: Compute answer, store with semantic hash
-const result1 = await agent.ask("Which providers have high denial rates?");
-// Execution time: 450ms, stores result with hash
-
-// Second call: Different wording, SAME semantic meaning
-const result2 = await agent.ask("Show me providers with lots of denials");
-// Execution time: 2ms (cache hit via semantic hash)
-// Returns IDENTICAL result - no LLM call needed
-
-// Why this matters:
-// - Consistent answers across team members
-// - No LLM cost for repeated questions
-// - Audit trail shows same query = same result
-```
-
-## HyperAgent Core Concepts
-
-```
-+-----------------------------------------------------------------------------+
-|                    HYPERAGENT EXECUTION MODEL                                |
-|                                                                              |
-|   User: "Find suspicious claims"                                             |
-|                     |                                                        |
-|                     v                                                        |
-|   +-------------------------------------------------------------+           |
-|   |  1. INTENT ANALYSIS (deterministic, no LLM)                 |           |
-|   |     Keywords: "suspicious" -> FRAUD_DETECTION               |           |
-|   |     Keywords: "claims" -> CLAIM_ENTITY                      |           |
-|   +-------------------------------------------------------------+           |
-|                     |                                                        |
-|                     v                                                        |
-|   +-------------------------------------------------------------+           |
-|   |  2. SCHEMA BINDING                                          |           |
-|   |     SchemaContext has: Claim, Provider, Claimant classes    |           |
-|   |     Properties: denialRate, totalClaims, flaggedBy          |           |
-|   +-------------------------------------------------------------+           |
-|                     |                                                        |
-|                     v                                                        |
-|   +-------------------------------------------------------------+           |
-|   |  3. STEP GENERATION (schema-driven)                         |           |
-|   |     Step 1: kg.sparql.query -> Find high denial providers   |           |
-|   |     Step 2: kg.datalog.infer -> Apply fraud rules           |           |
-|   |     Step 3: kg.motif.find -> Detect circular patterns       |           |
-|   +-------------------------------------------------------------+           |
-|                     |                                                        |
-|                     v                                                        |
-|   +-------------------------------------------------------------+           |
-|   |  4. VALIDATED EXECUTION (sandbox + audit)                   |           |
-|   |     Each step: Proxy -> Sandbox -> Tool -> ProofDAG         |           |
-|   +-------------------------------------------------------------+           |
-|                     |                                                        |
-|                     v                                                        |
-|   Result: Facts from YOUR data with full audit trail                         |
-+-----------------------------------------------------------------------------+
-```
-
-Key Principles:
-- LLM is OPTIONAL - Only used for natural language summarization
-- Query generation is DETERMINISTIC from SchemaContext
-- Every step produces cryptographic witness (SHA-256)
-- Capability-based security prevents unauthorized operations
-
-## SPARQL Query Examples
-
-```javascript
-const { GraphDB } = require('rust-kgdb');
 const db = new GraphDB('http://example.org/');
+const agent = new HyperMindAgent({ kg: db, name: 'memory-agent' });
 
-// Load sample data
-db.loadTtl(`
-  :alice :knows :bob ; :age 30 ; :city "London" .
-  :bob :knows :charlie ; :age 25 ; :city "Paris" .
-  :charlie :knows :alice ; :age 35 ; :city "London" .
-`);
+// Conversation knowledge extraction
+// Agent auto-extracts entities from chat into KG
+const result1 = await agent.call("Provider P001 submitted 5 claims totaling $47,000");
+// Stored: :Conversation_001 :mentions :Provider_P001 .
+// Stored: :Provider_P001 :claimCount "5" ; :claimTotal "47000" .
 
-// Basic SELECT query
-const friends = db.querySelect(`
-  SELECT ?person ?friend WHERE {
-    ?person :knows ?friend
-  }
-`);
-
-// FILTER with comparison
-const adults = db.querySelect(`
-  SELECT ?person ?age WHERE {
-    ?person :age ?age .
-    FILTER(?age >= 30)
-  }
-`);
-
-// OPTIONAL pattern
-const withCity = db.querySelect(`
-  SELECT ?person ?city WHERE {
-    ?person :knows ?someone .
-    OPTIONAL { ?person :city ?city }
-  }
-`);
-
-// Aggregation
-const avgAge = db.querySelect(`
-  SELECT (AVG(?age) as ?average) WHERE {
-    ?person :age ?age
-  }
-`);
+// Later queries use extracted knowledge
+const result2 = await agent.call("What do we know about Provider P001?");
+// Returns facts from BOTH original data AND conversation
 
-// CONSTRUCT new triples
-const inferred = db.queryConstruct(`
-  CONSTRUCT { ?a :friendOfFriend ?c }
-  WHERE {
-    ?a :knows ?b .
-    ?b :knows ?c .
-    FILTER(?a != ?c)
-  }
-`);
+// Idempotent responses (semantic hashing)
+const result3 = await agent.call("Which providers have high denial rates?");
+// First call: 450ms (compute + cache)
 
-// Named Graph operations
-db.loadTtl(':data1 :value "100" .', 'http://example.org/graph1');
-db.loadTtl(':data2 :value "200" .', 'http://example.org/graph2');
-const fromGraph = db.querySelect(`
-  SELECT ?s ?v FROM <http://example.org/graph1> WHERE {
-    ?s :value ?v
-  }
-`);
+const result4 = await agent.call("Show me providers with lots of denials");
+// Second call: 2ms (cache hit - same semantic meaning)
 ```
 
-## Datalog Reasoning Examples
+## Embedded vs Clustered Deployment
 
-```javascript
-const { DatalogProgram, evaluateDatalog } = require('rust-kgdb');
-
-const datalog = new DatalogProgram();
-
-// Add base facts
-datalog.addFact(JSON.stringify({predicate:'parent', terms:['alice','bob']}));
-datalog.addFact(JSON.stringify({predicate:'parent', terms:['bob','charlie']}));
-datalog.addFact(JSON.stringify({predicate:'parent', terms:['charlie','dave']}));
-
-// Transitive closure rule: ancestor(X,Z) :- parent(X,Y), ancestor(Y,Z)
-datalog.addRule(JSON.stringify({
-  head: {predicate:'ancestor', terms:['?X','?Y']},
-  body: [
-    {predicate:'parent', terms:['?X','?Y']}
-  ]
-}));
-datalog.addRule(JSON.stringify({
-  head: {predicate:'ancestor', terms:['?X','?Z']},
-  body: [
-    {predicate:'parent', terms:['?X','?Y']},
-    {predicate:'ancestor', terms:['?Y','?Z']}
-  ]
-}));
-
-// Semi-naive evaluation (fixpoint)
-const inferred = evaluateDatalog(datalog);
-// Results: ancestor(alice,bob), ancestor(alice,charlie), ancestor(alice,dave)
-//          ancestor(bob,charlie), ancestor(bob,dave)
-//          ancestor(charlie,dave)
-
-// Fraud detection rules
-const fraudDatalog = new DatalogProgram();
-fraudDatalog.addFact(JSON.stringify({predicate:'claim', terms:['C001','P001','50000']}));
-fraudDatalog.addFact(JSON.stringify({predicate:'claim', terms:['C002','P001','48000']}));
-fraudDatalog.addFact(JSON.stringify({predicate:'sameAddress', terms:['P001','P002']}));
-fraudDatalog.addFact(JSON.stringify({predicate:'claim', terms:['C003','P002','51000']}));
-
-// Collusion rule
-fraudDatalog.addRule(JSON.stringify({
-  head: {predicate:'potential_collusion', terms:['?P1','?P2']},
-  body: [
-    {predicate:'sameAddress', terms:['?P1','?P2']},
-    {predicate:'claim', terms:['?C1','?P1','?A1']},
-    {predicate:'claim', terms:['?C2','?P2','?A2']}
-  ]
-}));
-```
-
-## Motif Finding Examples
+### Embedded Mode (Default)
 
 ```javascript
-const { GraphFrame, friendsGraph } = require('rust-kgdb');
-
-// Create graph
-const gf = new GraphFrame(
-  JSON.stringify([
-    {id:'alice'}, {id:'bob'}, {id:'charlie'},
-    {id:'dave'}, {id:'eve'}
-  ]),
-  JSON.stringify([
-    {src:'alice', dst:'bob'},
-    {src:'bob', dst:'charlie'},
-    {src:'charlie', dst:'alice'},
-    {src:'dave', dst:'alice'},
-    {src:'eve', dst:'dave'}
-  ])
-);
-
-// Find triangles: (a)->(b)->(c)->(a)
-const triangles = gf.find('(a)-[e1]->(b); (b)-[e2]->(c); (c)-[e3]->(a)');
-// Returns: [{a:'alice', b:'bob', c:'charlie', ...}]
-
-// Find chains: (a)->(b)->(c)
-const chains = gf.find('(a)-[e1]->(b); (b)-[e2]->(c)');
-
-// Find stars: hub with multiple spokes
-const stars = gf.find('(hub)-[e1]->(spoke1); (hub)-[e2]->(spoke2)');
-
-// Find bidirectional edges
-const bidir = gf.find('(a)-[e1]->(b); (b)-[e2]->(a)');
-
-// Fraud pattern: circular payments
-// A pays B, B pays C, C pays A
-const circular = gf.find('(a)-[pay1]->(b); (b)-[pay2]->(c); (c)-[pay3]->(a)');
+const db = new GraphDB('http://example.org/');  // In-memory, zero config
 ```
 
-## Clustered KGDB
+- **Storage:** RAM only (HashMap-based SPOC indexes)
+- **Performance:** 449ns lookups, 146K triples/sec insert
+- **Persistence:** None (data lost on restart)
+- **Scaling:** Single process, up to ~100M triples
+- **Use case:** Development, testing, embedded apps
 
-For datasets exceeding single-node capacity (1B+ triples), rust-kgdb supports distributed deployment:
+### Clustered Mode (1B+ triples)
 
 ```
 +-----------------------------------------------------------------------------+
@@ -691,19 +651,11 @@ For datasets exceeding single-node capacity (1B+ triples), rust-kgdb supports di
 |                                                                              |
 |   HDRF Partitioning: Subject-anchored streaming (load factor < 1.1)          |
 |   Shadow Partitions: Zero-downtime rebalancing (~10ms pause)                 |
-|   DataFusion: Arrow-native OLAP for analytical queries                       |
+|   Apache Arrow: Columnar OLAP for analytical queries                         |
 +-----------------------------------------------------------------------------+
 ```
 
-Cluster Features:
-- HDRF streaming partitioner (subject-anchored, maintains locality)
-- Raft consensus for distributed coordination
-- gRPC for inter-node communication
-- DataFusion integration for OLAP queries
-- Shadow partitions for zero-downtime rebalancing
-
-Deployment:
-
+**Deployment:**
 ```bash
 # Kubernetes deployment
 kubectl apply -f infra/k8s/coordinator.yaml
@@ -714,60 +666,88 @@ helm install rust-kgdb ./infra/helm -n rust-kgdb --create-namespace
 
 # Verify cluster
 kubectl get pods -n rust-kgdb
-curl http://<coordinator-ip>:8080/api/v1/health
 ```
 
-## HyperAgent: Fraud Detection Example
+### Memory in Clustered Mode
+
+Agent memory scales with the cluster:
+- Episodes partitioned by agent ID (locality)
+- Embeddings replicated for fast similarity search
+- Cross-partition queries via coordinator routing
+
+## Concurrency Benchmarks
+
+Measured with `node concurrency-benchmark.js` on darwin-x64:
+
+### Write Scaling
+
+| Workers | Ops/Sec | Scaling Factor |
+|---------|---------|----------------|
+| 1 | 66,422 | 1.00x |
+| 2 | 79,480 | 1.20x |
+| 4 | 95,655 | 1.44x |
+| 8 | 111,357 | 1.68x |
+| 16 | 132,087 | 1.99x |
+
+### Read Scaling
+
+| Workers | Ops/Sec | Scaling Factor |
+|---------|---------|----------------|
+| 1 | 290 | 1.00x |
+| 2 | 305 | 1.05x |
+| 4 | 307 | 1.06x |
+| 8 | 282 | 0.97x |
+| 16 | 302 | 1.04x |
+
+### GraphFrame Scaling
+
+| Workers | Ops/Sec | Scaling Factor |
+|---------|---------|----------------|
+| 1 | 5,987 | 1.00x |
+| 2 | 6,532 | 1.09x |
+| 4 | 6,494 | 1.08x |
+| 8 | 6,715 | 1.12x |
+| 16 | 6,516 | 1.09x |
+
+**Interpretation:**
+- Writes scale near-linearly (lock-free dictionary)
+- Reads plateau (SPARQL parsing overhead dominates)
+- GraphFrame stable (compute-bound, not I/O-bound)
+
+## Real-World Examples
+
+### Fraud Detection (NICB Dataset Patterns)
+
+Based on National Insurance Crime Bureau fraud indicators:
 
 ```javascript
-const { GraphDB, HyperMindAgent, DatalogProgram, evaluateDatalog } = require('rust-kgdb');
+const { GraphDB, HyperMindAgent, DatalogProgram, evaluateDatalog, GraphFrame } = require('rust-kgdb');
 
-// Create database with insurance claims data (N-Triples format for reliability)
+// Create database with claims data
 const db = new GraphDB('http://insurance.org/');
 db.loadTtl(`
   <http://insurance.org/PROV001> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://insurance.org/Provider> .
   <http://insurance.org/PROV001> <http://insurance.org/name> "ABC Medical" .
-  <http://insurance.org/PROV001> <http://insurance.org/specialty> "Orthopedics" .
-  <http://insurance.org/PROV001> <http://insurance.org/totalClaims> "89" .
   <http://insurance.org/PROV001> <http://insurance.org/denialRate> "0.34" .
+  <http://insurance.org/PROV001> <http://insurance.org/totalClaims> "89" .
   <http://insurance.org/PROV001> <http://insurance.org/hasPattern> <http://insurance.org/UnbundledBilling> .
-  <http://insurance.org/PROV001> <http://insurance.org/flaggedBy> <http://insurance.org/SIU_2024_Q1> .
 
   <http://insurance.org/CLMT001> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://insurance.org/Claimant> .
-  <http://insurance.org/CLMT001> <http://insurance.org/name> "John Smith" .
   <http://insurance.org/CLMT001> <http://insurance.org/address> "123 Main St" .
   <http://insurance.org/CLMT002> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://insurance.org/Claimant> .
-  <http://insurance.org/CLMT002> <http://insurance.org/name> "Jane Doe" .
   <http://insurance.org/CLMT002> <http://insurance.org/address> "123 Main St" .
   <http://insurance.org/CLMT001> <http://insurance.org/knows> <http://insurance.org/CLMT002> .
 `, null);
 
-// Create agent with knowledge graph binding
-const agent = new HyperMindAgent({
-  kg: db,
-  name: 'fraud-detector',
-  apiKey: process.env.OPENAI_API_KEY,
-  sandbox: {
-    capabilities: ['ReadKG', 'ExecuteTool'],  // Read-only by default
-    fuelLimit: 1000000
+// Method 1: SPARQL for simple queries
+const highDenial = db.querySelect(`
+  SELECT ?provider ?rate WHERE {
+    ?provider <http://insurance.org/denialRate> ?rate .
+    FILTER(?rate > "0.2")
   }
-});
-
-// Natural language fraud detection
-const result = await agent.call("Which providers show suspicious billing patterns?");
-
-console.log(result.answer);
-// "Provider PROV001 (ABC Medical) shows concerning patterns:
-//  - 34% denial rate (industry average: 8%)
-//  - Flagged by SIU in Q1 2024 for unbundled billing"
-
-console.log(result.explanation);
-// Full execution trace showing tool calls
-
-console.log(result.proof);
-// Cryptographic proof DAG with SHA-256 hashes
+`);
 
-// Use Datalog for collusion detection rules
+// Method 2: Datalog for collusion detection
 const datalog = new DatalogProgram();
 datalog.addFact(JSON.stringify({predicate:'knows', terms:['CLMT001','CLMT002']}));
 datalog.addFact(JSON.stringify({predicate:'sameAddress', terms:['CLMT001','CLMT002']}));
@@ -778,16 +758,31 @@ datalog.addRule(JSON.stringify({
     {predicate:'sameAddress', terms:['?X','?Y']}
   ]
 }));
-const inferred = evaluateDatalog(datalog);
-console.log('Collusion detected:', JSON.parse(inferred));
+const collusion = evaluateDatalog(datalog);
+
+// Method 3: Motif for ring detection
+const gf = new GraphFrame(
+  JSON.stringify([{id:'CLMT001'}, {id:'CLMT002'}, {id:'CLMT003'}]),
+  JSON.stringify([
+    {src:'CLMT001', dst:'CLMT002'},
+    {src:'CLMT002', dst:'CLMT003'},
+    {src:'CLMT003', dst:'CLMT001'}
+  ])
+);
+const rings = gf.find('(a)-[e1]->(b); (b)-[e2]->(c); (c)-[e3]->(a)');
+
+// Method 4: HyperAgent for natural language
+const agent = new HyperMindAgent({ kg: db, name: 'fraud-detector' });
+const result = await agent.call("Find suspicious billing patterns");
 ```
 
-## HyperAgent: Underwriting Example
+### Underwriting (ISO/ACORD Dataset Patterns)
+
+Based on insurance industry standard data models:
 
 ```javascript
 const { GraphDB, HyperMindAgent, EmbeddingService } = require('rust-kgdb');
 
-// Create database with underwriting data (N-Triples format)
 const db = new GraphDB('http://underwriting.org/');
 db.loadTtl(`
   <http://underwriting.org/APP001> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://underwriting.org/Applicant> .
@@ -795,7 +790,6 @@ db.loadTtl(`
   <http://underwriting.org/APP001> <http://underwriting.org/industry> "Manufacturing" .
   <http://underwriting.org/APP001> <http://underwriting.org/employees> "250" .
   <http://underwriting.org/APP001> <http://underwriting.org/creditScore> "720" .
-  <http://underwriting.org/APP001> <http://underwriting.org/yearsInBusiness> "15" .
 
   <http://underwriting.org/COMP001> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://underwriting.org/Applicant> .
   <http://underwriting.org/COMP001> <http://underwriting.org/industry> "Manufacturing" .
@@ -803,34 +797,17 @@ db.loadTtl(`
   <http://underwriting.org/COMP001> <http://underwriting.org/premium> "625000" .
 `, null);
 
-// Optional: Add embeddings for similarity search
+// Embeddings for similarity search
 const embeddings = new EmbeddingService();
 const appVector = new Array(384).fill(0).map((_, i) => Math.sin(i / 10));
 embeddings.storeVector('APP001', appVector);
 embeddings.storeVector('COMP001', appVector.map(x => x * 0.95));
+embeddings.rebuildIndex();
 
-// Create underwriting agent
-const agent = new HyperMindAgent({
-  kg: db,
-  embeddings: embeddings,  // Optional: for similarity search
-  name: 'underwriter',
-  apiKey: process.env.OPENAI_API_KEY
-});
-
-// Risk assessment via natural language
-const risk = await agent.call("Assess the risk profile for Acme Corp");
-
-console.log(risk.answer);
-// "Acme Corp (APP001) Risk Assessment:
-//  - Credit score 720 (above 700 threshold)
-//  - 15 years in business (stable operations)
-//  - Comparable: COMP001 (230 employees, $625K premium)"
-
-// Find similar accounts using embeddings
+// Find similar accounts
 const similar = embeddings.findSimilar('APP001', 5, 0.7);
-console.log('Similar accounts:', JSON.parse(similar));
 
-// Direct SPARQL query for engineering teams
+// Direct SPARQL for comparables
 const comparables = db.querySelect(`
   SELECT ?company ?employees ?premium WHERE {
     ?company <http://underwriting.org/industry> "Manufacturing" .
@@ -838,265 +815,201 @@ const comparables = db.querySelect(`
     OPTIONAL { ?company <http://underwriting.org/premium> ?premium }
   }
 `);
-console.log('Comparables:', comparables);
-```
-
-## Real-World Examples
-
-### Legal: Contract Analysis
-
-```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" .
-`);
-
-const result = await agent.ask("Has the non-compete clause been challenged?");
-// Returns REAL cases from YOUR database, not hallucinated citations
-```
-
-### Healthcare: Drug Interactions
-
-```javascript
-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" .
-`);
-
-const result = await agent.ask("What should we avoid prescribing to Patient 7291?");
-// Returns ACTUAL interactions from your formulary, not made-up drug names
-```
-
-### Insurance: Fraud Detection
-
-```javascript
-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']}
-  ]
-}));
-
-const inferred = evaluateDatalog(datalog);
-// potential_collusion(P001, P002, PROV001) - DETECTED!
-```
-
-## Performance Benchmarks
-
-All measurements verified. Run them yourself:
-
-```bash
-node benchmark.js                       # Core engine benchmarks
-node concurrency-benchmark.js           # Multi-worker concurrency
-node vanilla-vs-hypermind-benchmark.js  # HyperMind vs vanilla LLM
+// HyperAgent for risk assessment
+const agent = new HyperMindAgent({
+  kg: db,
+  embeddings: embeddings,
+  name: 'underwriter'
+});
+const risk = await agent.call("Assess risk profile for Acme Corp");
 ```
 
-### Rust Core Engine
-
-| 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 |
-
-Sources:
-- rust-kgdb: Criterion benchmarks on LUBM(1) dataset, Apple Silicon
-- RDFox: [Oxford Semantic Technologies benchmarks](https://www.oxfordsemantic.tech/product)
-- Apache Jena: [Jena performance documentation](https://jena.apache.org/documentation/tdb/performance.html)
-
-### Concurrency Scaling (darwin-x64)
-
-| Operation | 1 Worker | 2 Workers | 4 Workers | 8 Workers | 16 Workers |
-|-----------|----------|-----------|-----------|-----------|------------|
-| Writes | 66K/sec | 79K/sec | 96K/sec | 111K/sec | 132K/sec |
-| Reads | 290/sec | 305/sec | 307/sec | 282/sec | 302/sec |
-| GraphFrame | 6.0K/sec | 6.5K/sec | 6.5K/sec | 6.7K/sec | 6.5K/sec |
-
-Source: `node concurrency-benchmark.js` (100 ops/worker, LUBM data)
-
-### HyperMind Agent Accuracy (LUBM Benchmark)
-
-| Framework | Without Schema | With Schema |
-|-----------|----------------|-------------|
-| Vanilla LLM | 0% | - |
-| LangChain | 0% | 71.4% |
-| DSPy | 14.3% | 71.4% |
-| HyperMind | - | 86.4% |
-
-Source: `python3 benchmark-frameworks.py` with 7 LUBM queries
-
-### Memory Retrieval (10K Queries)
-
-| Metric | Value |
-|--------|-------|
-| Recall @ 10K | 94% |
-| Search Speed | 16.7ms |
-| Write Throughput | 132K ops/sec |
-
-Source: `node memory-retrieval-benchmark.js`
-
 ## Complete Feature List
 
 ### Core Database
 
 | Feature | Description | Performance |
 |---------|-------------|-------------|
-| SPARQL 1.1 Engine | Full query/update support | 449ns lookups |
-| RDF 1.2 Support | Quoted triples, annotations | W3C compliant |
-| Named Graphs | Quad store with graph isolation | O(1) graph switching |
-| Triple Indexing | SPOC/POCS/OCSP/CSPO indexes | Sub-microsecond pattern match |
-| Bulk Loading | Streaming Turtle/N-Triples parser | 146K triples/sec |
-| Storage Backends | InMemory, RocksDB, LMDB | Pluggable persistence |
+| SPARQL 1.1 Query | SELECT, CONSTRUCT, ASK, DESCRIBE | 449ns lookups |
+| SPARQL 1.1 Update | INSERT, DELETE, LOAD, CLEAR | 146K/sec |
+| RDF 1.2 | Quoted triples, annotations | W3C compliant |
+| Named Graphs | Quad store with graph isolation | O(1) switching |
+| Triple Indexing | SPOC/POCS/OCSP/CSPO | Sub-microsecond |
+| Storage Backends | InMemory, RocksDB, LMDB | Pluggable |
+| Apache Arrow OLAP | Columnar aggregations | Vectorized |
 
-### Concurrency (Measured on 16 Workers)
-
-| Operation | 1 Worker | 16 Workers | Scaling |
-|-----------|----------|------------|---------|
-| Writes | 66K ops/sec | 132K ops/sec | 1.99x |
-| Reads | 290 ops/sec | 302 ops/sec | 1.04x |
-| GraphFrame | 6.0K ops/sec | 6.5K ops/sec | 1.09x |
-| Mixed R/W | 148K ops/sec | 642 ops/sec | - |
-
-Source: `node concurrency-benchmark.js` on darwin-x64
-
-### Graph Analytics (GraphFrame API)
+### Graph Analytics (GraphFrame)
 
 | Algorithm | Complexity | Description |
 |-----------|------------|-------------|
-| PageRank | O(V + E) per iteration | Configurable damping, iterations |
-| Connected Components | O(V + E) | Union-find implementation |
-| Triangle Count | O(E^1.5) | Optimized edge iteration |
-| Shortest Paths | O(V + E) | Single-source Dijkstra |
-| Motif Finding | Pattern-dependent | DSL: `(a)-[e]->(b)` syntax |
+| PageRank | O(V+E) per iteration | Damping, iterations configurable |
+| Connected Components | O(V+E) | Union-Find |
+| Triangle Count | O(E^1.5) | Optimized |
+| Shortest Paths | O(V+E) | Dijkstra |
+| Label Propagation | O(V+E) per iteration | Community detection |
+| Motif Finding | Pattern-dependent | DSL: `(a)-[e]->(b)` |
+| Pregel | BSP model | Custom vertex programs |
 
 ### AI/ML Features
 
 | Feature | Performance | Description |
 |---------|-------------|-------------|
-| HNSW Embeddings | 16ms/10K vectors | 384-dimensional vectors |
+| HNSW Embeddings | 16ms/10K | 384-dimensional vectors |
 | Similarity Search | O(log n) | Approximate nearest neighbor |
-| Agent Memory | 94% recall @ 10K depth | Episodic + semantic memory |
-| Embedding Triggers | Auto on INSERT | OpenAI/Ollama/Anthropic providers |
-| Semantic Deduplication | 2ms cache hit | Hash-based query caching |
+| Embedding Triggers | Auto on INSERT | OpenAI/Ollama providers |
+| Agent Memory | 94% recall @ 10K | Episodic + semantic |
+| Semantic Caching | 2ms hit | Hash-based deduplication |
 
 ### Reasoning Engine
 
 | Feature | Algorithm | Description |
 |---------|-----------|-------------|
-| Datalog | Semi-naive evaluation | Recursive rule support |
-| Transitive Closure | Fixpoint iteration | ancestor(X,Y) :- parent(X,Y) |
-| Negation | Stratified | NOT in rule bodies |
-| Aggregation | Group-by support | COUNT, SUM, AVG in rules |
+| Datalog | Semi-naive | Recursive rules |
+| Transitive Closure | Fixpoint | ancestor(X,Y) |
+| Stratified Negation | Stratified | NOT in bodies |
+| Rule Chaining | Forward | Multi-hop inference |
 
 ### Security and Audit
 
 | Feature | Implementation | Description |
 |---------|----------------|-------------|
-| WASM Sandbox | wasmtime + fuel metering | 1M ops max, 64MB memory |
-| Capability System | Set-based permissions | ReadKG, WriteKG, DatalogInfer |
-| ProofDAG | SHA-256 hash chains | Cryptographic audit trail |
-| Tool Validation | Type checking | Morphism composition verified |
+| WASM Sandbox | Fuel metering | 1M ops max |
+| Capabilities | Set-based | ReadKG, WriteKG |
+| ProofDAG | SHA-256 | Cryptographic audit |
+| Tool Validation | Type checking | Morphism composition |
 
 ### HyperAgent Framework
 
 | Feature | Description |
 |---------|-------------|
-| Schema-Aware Query Gen | Uses YOUR ontology classes/properties |
-| Deterministic Planning | No LLM for query generation |
-| Multi-Step Execution | Chain SPARQL + Datalog + Motif |
-| Memory Hypergraph | Episodes link to KG entities |
-| Conversation Extraction | Auto-extract entities from chat |
+| Schema-Aware Query Gen | Uses YOUR ontology |
+| Deterministic Planning | No LLM for queries |
+| Multi-Step Execution | SPARQL + Datalog + Motif |
+| Memory Hypergraph | Episodes link to KG |
+| Conversation Extraction | Auto-extract entities |
 | Idempotent Responses | Same question = same answer |
 
 ### Standards Compliance
 
-| Standard | Status | Notes |
-|----------|--------|-------|
-| SPARQL 1.1 Query | 100% | All query forms |
-| SPARQL 1.1 Update | 100% | INSERT/DELETE/LOAD/CLEAR |
-| RDF 1.2 | 100% | Quoted triples, annotations |
-| Turtle | 100% | Full grammar support |
-| N-Triples | 100% | Streaming parser |
+| Standard | Status |
+|----------|--------|
+| SPARQL 1.1 Query | 100% |
+| SPARQL 1.1 Update | 100% |
+| RDF 1.2 | 100% |
+| Turtle | 100% |
+| N-Triples | 100% |
 
 ## API Reference
 
 ### GraphDB
 
 ```javascript
-const db = new GraphDB(baseUri)
-db.loadTtl(turtle, graphUri)
-db.querySelect(sparql)
-db.queryConstruct(sparql)
-db.countTriples()
-db.clear()
+const db = new GraphDB(baseUri)        // Create database
+db.loadTtl(turtle, graphUri)           // Load RDF data
+db.querySelect(sparql)                 // SELECT query -> results[]
+db.queryConstruct(sparql)              // CONSTRUCT -> triples string
+db.countTriples()                      // Count triples -> number
+db.clear()                             // Clear all data
+db.getGraphUri()                       // Get base URI -> string
 ```
 
 ### GraphFrame
 
 ```javascript
 const gf = new GraphFrame(verticesJson, edgesJson)
-gf.pageRank(dampingFactor, iterations)
-gf.connectedComponents()
-gf.triangleCount()
-gf.shortestPaths(sourceId)
-gf.find(motifPattern)
+gf.vertexCount()                       // -> number
+gf.edgeCount()                         // -> number
+gf.pageRank(dampingFactor, iterations) // -> JSON string
+gf.connectedComponents()               // -> JSON string
+gf.triangleCount()                     // -> number
+gf.shortestPaths(landmarks)            // -> JSON string
+gf.labelPropagation(iterations)        // -> JSON string
+gf.find(motifPattern)                  // -> JSON string
+gf.inDegrees()                         // -> JSON string
+gf.outDegrees()                        // -> JSON string
+gf.degrees()                           // -> JSON string
+gf.toJson()                            // -> JSON string
 ```
 
 ### EmbeddingService
 
 ```javascript
 const emb = new EmbeddingService()
-emb.storeVector(entityId, float32Array)
-emb.rebuildIndex()
-emb.findSimilar(entityId, k, threshold)
+emb.storeVector(entityId, float32Array)  // Store vector
+emb.getVector(entityId)                  // -> Float32Array | null
+emb.deleteVector(entityId)               // Delete vector
+emb.rebuildIndex()                       // Build HNSW index
+emb.findSimilar(entityId, k, threshold)  // -> JSON string
+emb.findSimilarGraceful(entityId, k, t)  // -> JSON string (no throw)
+emb.isEnabled()                          // -> boolean
+emb.getMetrics()                         // -> JSON string
+emb.getCacheStats()                      // -> JSON string
+emb.onTripleInsert(s, p, o, g)          // Trigger hook
 ```
 
 ### DatalogProgram
 
 ```javascript
 const dl = new DatalogProgram()
-dl.addFact(factJson)
-dl.addRule(ruleJson)
-evaluateDatalog(dl)
+dl.addFact(factJson)                   // Add fact
+dl.addRule(ruleJson)                   // Add rule
+dl.factCount()                         // -> number
+dl.ruleCount()                         // -> number
+evaluateDatalog(dl)                    // -> JSON string (all inferred)
+queryDatalog(dl, predicate)            // -> JSON string (specific)
+```
+
+### HyperMindAgent
+
+```javascript
+const agent = new HyperMindAgent({
+  kg: db,                              // REQUIRED: GraphDB
+  embeddings: embeddingService,        // Optional: EmbeddingService
+  name: 'agent-name',                  // Optional: string
+  apiKey: process.env.OPENAI_API_KEY,  // Optional: LLM API key
+  sandbox: {                           // Optional: security config
+    capabilities: ['ReadKG'],
+    fuelLimit: 1000000
+  }
+})
+
+const result = await agent.call(question)  // Natural language query
+// result.answer      -> string (human-readable)
+// result.explanation -> string (execution trace)
+// result.proof       -> object (SHA-256 audit trail)
 ```
 
 ### Factory Functions
 
 ```javascript
-friendsGraph()
-chainGraph(n)
-starGraph(n)
-completeGraph(n)
-cycleGraph(n)
+friendsGraph()        // Sample social graph
+chainGraph(n)         // Linear path: v0 -> v1 -> ... -> vn-1
+starGraph(n)          // Hub with n spokes
+completeGraph(n)      // Fully connected Kn
+cycleGraph(n)         // Ring: v0 -> v1 -> ... -> vn-1 -> v0
+binaryTreeGraph(depth) // Binary tree
+bipartiteGraph(m, n)   // Bipartite Km,n
 ```
 
-## Installation
+## Running Benchmarks
 
 ```bash
-npm install rust-kgdb
-```
+# Core engine benchmarks
+node benchmark.js
+
+# Concurrency benchmarks
+node concurrency-benchmark.js
 
-Platforms: macOS (Intel/Apple Silicon), Linux (x64/ARM64), Windows (x64)
+# Memory retrieval benchmarks
+node memory-retrieval-benchmark.js
 
-Requirements: Node.js 14+
+# HyperMind vs Vanilla LLM (requires API key)
+ANTHROPIC_API_KEY=... node vanilla-vs-hypermind-benchmark.js
+
+# Framework comparison (requires Python + API key)
+OPENAI_API_KEY=... python3 benchmark-frameworks.py
+```
 
 ## License