rust-kgdb 0.6.63 → 0.6.66

package/README.md

@@ -1,331 +1,125 @@
 # rust-kgdb
 
-[![npm version](https://img.shields.io/npm/v/rust-kgdb.svg)](https://www.npmjs.com/package/rust-kgdb)
-[![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/)
-
----
+High-performance RDF/SPARQL database with AI agent framework.
 
 ## The Problem With AI Today
 
 Enterprise AI projects keep failing. Not because the technology is bad, but because organizations use it wrong.
 
-A claims investigator asks ChatGPT: *"Has Provider #4521 shown suspicious billing patterns?"*
+A claims investigator asks ChatGPT: "Has Provider #4521 shown suspicious billing patterns?"
 
-The AI responds confidently: *"Yes, Provider #4521 has a history of duplicate billing and upcoding."*
+The AI responds confidently: "Yes, Provider #4521 has a history of duplicate billing and upcoding."
 
-The investigator opens a case. Weeks later, legal discovers **Provider #4521 has a perfect record**. The AI made it up. Lawsuit incoming.
+The investigator opens a case. Weeks later, legal discovers Provider #4521 has a perfect record. The AI made it up. Lawsuit incoming.
 
 This keeps happening:
 
-**A lawyer** cites "Smith v. Johnson (2019)" in court. The judge is confused. That case doesn't exist.
-
-**A doctor** avoids prescribing "Nexapril" due to cardiac interactions. Nexapril isn't a real drug.
-
-**A fraud analyst** flags Account #7842 for money laundering. It belongs to a children's charity.
+- A lawyer cites "Smith v. Johnson (2019)" in court. The judge is confused. That case does not exist.
+- A doctor avoids prescribing "Nexapril" due to cardiac interactions. Nexapril is not a real drug.
+- A fraud analyst flags Account #7842 for money laundering. It belongs to a children's charity.
 
 Every time, the same pattern: The AI sounds confident. The AI is wrong. People get hurt.
 
----
-
-## The Engineering Problem
-
-**The root cause is simple:** LLMs are language models, not databases. They predict plausible text. They don't look up facts.
-
-When you ask "Has Provider #4521 shown suspicious patterns?", the LLM doesn't query your claims database. It generates text that *sounds like* an answer based on patterns from its training data.
-
-**The industry's response?** Add guardrails. Use RAG. Fine-tune models.
-
-These help, but they're patches. RAG retrieves *similar* documents - similar isn't the same as *correct*. Fine-tuning teaches patterns, not facts. Guardrails catch obvious errors, but "Provider #4521 has billing anomalies" sounds perfectly plausible.
-
-**A real solution requires a different architecture.** One built on solid engineering principles, not hope.
-
----
-
 ## The Solution
 
-What if AI stopped providing **answers** and started generating **queries**?
+What if AI stopped providing answers and started generating queries?
 
-Think about it:
-- **Your database** knows the facts (claims, providers, transactions)
-- **AI** understands language (can parse "find suspicious patterns")
-- **You need both** working together
+- 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.
 
-```
-Before (Dangerous):
-  Human: "Is Provider #4521 suspicious?"
-  AI: "Yes, they have billing anomalies" <- FABRICATED
-
-After (Safe):
-  Human: "Is Provider #4521 suspicious?"
-  AI: Generates SPARQL query -> Executes against YOUR database
-  Database: Returns actual facts about Provider #4521
-  Result: Real data with audit trail <- VERIFIABLE
-```
-
-rust-kgdb is a knowledge graph database with an AI layer that **cannot hallucinate** because it only returns data from your actual systems.
-
----
+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
-- **Instant deployment** - `npm install` and you're running
-
-**For Engineering Teams:**
-- **449ns lookups** - 35x faster than RDFox, the previous gold standard
-- **24 bytes per triple** - 25% more memory efficient than competitors
-- **132K writes/sec** - Handle enterprise transaction volumes
-- **94% recall on memory retrieval** - Agent remembers past queries accurately
-
-**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
-- **Recursive reasoning** - Datalog rules cascade automatically (fraud rings, compliance chains)
-- **Schema-aware generation** - AI uses YOUR ontology, not guessed class names
-
-**The math matters.** When your fraud detection runs 35x faster, you catch fraud before payments clear. When your agent remembers with 94% accuracy, analysts don't repeat work. When every decision has a proof hash, you pass audits.
-
----
+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)
+
+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
+
+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
 
 ## What Is rust-kgdb?
 
-**Two components, one npm package:**
+Two components, one npm package:
 
 ### rust-kgdb Core: Embedded Knowledge Graph Database
 
-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.
 
 ```
 +-----------------------------------------------------------------------------+
-|                         rust-kgdb CORE ENGINE                                |
-|                                                                              |
-|  +-------------+  +-------------+  +-------------+  +-------------+        |
-|  |   GraphDB   |  | GraphFrame  |  |  Embeddings |  |   Datalog   |        |
-|  |  (SPARQL)   |  | (Analytics) |  |   (HNSW)    |  | (Reasoning) |        |
-|  |  449ns      |  |  PageRank   |  |  16ms/10K   |  |  Semi-naive |        |
-|  +-------------+  +-------------+  +-------------+  +-------------+        |
-|                                                                              |
+|                         rust-kgdb CORE ENGINE                               |
+|                                                                             |
+|  +-----------+  +-----------+  +-----------+  +-----------+                 |
+|  |  GraphDB  |  |GraphFrame |  |Embeddings |  |  Datalog  |                 |
+|  | (SPARQL)  |  |(Analytics)|  |  (HNSW)   |  |(Reasoning)|                 |
+|  |  449ns    |  | PageRank  |  | 16ms/10K  |  |Semi-naive |                 |
+|  +-----------+  +-----------+  +-----------+  +-----------+                 |
+|                                                                             |
 |  Storage: InMemory | RocksDB | LMDB    Standards: SPARQL 1.1 | RDF 1.2     |
-|  Memory: 24 bytes/triple               Compliance: SHACL | PROV | OWL 2 RL |
 +-----------------------------------------------------------------------------+
 ```
 
-**Performance (Verified on LUBM benchmark):**
+| 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 |
 
-| Metric | rust-kgdb | RDFox | Apache Jena | Why It Matters |
-|--------|-----------|-------|-------------|----------------|
-| **Lookup** | 449 ns | 5,000+ ns | 10,000+ ns | Catch fraud before payment clears |
-| **Memory/Triple** | 24 bytes | 32 bytes | 50-60 bytes | Fit more data in memory |
-| **Bulk Insert** | 146K/sec | 200K/sec | 50K/sec | Load million-record datasets fast |
-| **Concurrent Writes** | 132K ops/sec | - | - | Handle enterprise transaction volumes |
+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.**
+Like SQLite - but for knowledge graphs.
 
 ### HyperMind: Neuro-Symbolic Agent Framework
 
-An AI agent layer that uses **the database to prevent hallucinations**. The LLM plans, the database executes.
+An AI agent layer that uses the database to prevent hallucinations. The LLM plans, the database executes.
 
 ```
 +-----------------------------------------------------------------------------+
-|                      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           |
+|                      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          |
 +-----------------------------------------------------------------------------+
 ```
 
-**Agent Accuracy (LUBM Benchmark - 14 Queries, 3,272 Triples):**
-
-| Framework | Without Schema | With Schema | Notes |
-|-----------|---------------|-------------|-------|
-| **Vanilla LLM** | 0% | - | Hallucinates class names, adds markdown |
-| **LangChain** | 0% | 71.4% | Needs manual schema injection |
-| **DSPy** | 14.3% | 71.4% | Better prompting helps slightly |
-| **HyperMind** | - | 71.4% | Schema integrated by design |
-
-*Honest numbers: All frameworks achieve similar accuracy WITH schema. The difference is HyperMind integrates schema handling - you don't manually inject it.*
-
-**Memory Retrieval (Agent Recall Benchmark):**
-
-| Metric | HyperMind | Typical RAG | Why It Matters |
-|--------|-----------|-------------|----------------|
-| **Recall@10** | 94% at 10K depth | ~70% | Find the right past query |
-| **Search Speed** | 16.7ms / 10K queries | 500ms+ | 30x faster context retrieval |
-| **Idempotent Responses** | Yes (semantic hash) | No | Same question = same answer |
-
-**Long-Term Memory: Deep Flashback**
-
-Most AI agents forget everything between sessions. HyperMind stores memory in the *same* knowledge graph as your data:
-
-- **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
-
-When your fraud analyst asks "What did we find about Provider X last month?", the agent doesn't say "I don't remember." It retrieves the exact investigation with full context - 94% recall at 10,000 queries deep.
-
-**The insight:** AI writes questions (SPARQL queries). Database finds answers. No hallucination possible.
-
----
-
-## The Engineering Choices
-
-Every decision in this codebase has a reason:
-
-**Why embedded, not client-server?**
-Because data shouldn't leave your infrastructure. An embedded database means your patient records, claims data, and transaction histories never cross a network boundary. HIPAA compliance by architecture, not policy.
-
-**Why SPARQL, not SQL?**
-Because relationships matter. "Find all providers connected to this claimant through any intermediary" is one line in SPARQL. It's a nightmare in SQL with recursive CTEs. Knowledge graphs are built for connection queries.
-
-**Why category theory for tools?**
-Because composition must be safe. When Tool A outputs a `BindingSet` and Tool B expects a `Pattern`, the type system catches it at build time. No runtime surprises. No "undefined is not a function."
-
-**Why WASM sandbox for agents?**
-Because AI shouldn't have unlimited power. The sandbox enforces capability-based security. An agent can read the knowledge graph but can't delete data. It can execute 1M operations but not infinite loop. Defense in depth.
-
-**Why Datalog for reasoning?**
-Because rules should cascade. A fraud pattern that triggers another rule that triggers another - Datalog handles recursive inference naturally. Semi-naive evaluation ensures we don't recompute what we already know.
-
-**Why HNSW for embeddings?**
-Because O(log n) beats O(n). Finding similar claims from 100K vectors shouldn't scan all 100K. HNSW builds a navigable graph - ~20 hops to find your answer regardless of dataset size.
-
-**Why clustered mode for scale?**
-Because some problems don't fit on one machine. The same codebase that runs embedded on your laptop scales to Kubernetes clusters for billion-triple graphs. HDRF (High-Degree Replicated First) partitioning keeps high-connectivity nodes available across partitions. Raft consensus ensures consistency. gRPC handles inter-node communication. You write the same code - deployment decides the scale.
-
-These aren't arbitrary choices. Each one solves a real problem I encountered building enterprise AI systems.
-
----
-
-## Why Our Tool Calling Is Different
-
-Traditional AI tool calling (OpenAI Functions, LangChain Tools) has fundamental problems:
-
-**The Traditional Approach:**
-```
-LLM generates JSON -> Runtime validates schema -> Tool executes -> Hope it works
-```
-
-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 -> 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.
-4. **No mathematical guarantees.** "It usually works" is the best you get.
-
-**Our Approach: Tools as Typed Morphisms**
-```
-Tools are arrows in a category:
-  kg.sparql.query:     Query -> BindingSet
-  kg.motif.find:       Pattern -> Matches
-  kg.embeddings.search: EntityId -> SimilarEntities
-
-Composition is verified:
-  f: A -> B
-  g: B -> C
-  g o f: A -> C  [x] Compiles only if types match
-
-Errors caught at plan time, not runtime.
-```
-
-**What this means in practice:**
-
-| Problem | Traditional | HyperMind |
-|---------|-------------|-----------|
-| **Type mismatch** | Runtime error | Won't 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 |
-
-**Refinement Types: Beyond Basic Types**
-
-We don't just have `string` and `number`. We have:
-- `RiskScore` (number between 0 and 1)
-- `PolicyNumber` (matches regex `^POL-\d{8}$`)
-- `CreditScore` (integer between 300 and 850)
-
-The type system *guarantees* a tool that outputs `RiskScore` produces a valid risk score. Not "probably" - mathematically proven.
-
-**The Insight:** Category theory isn't academic overhead. It's the same math that makes your database transactions safe (ACID = category theory applied to data). We apply it to tool composition.
-
-**Trust Model: Proxied Execution**
-
-Traditional tool calling trusts the LLM output completely:
-```
-LLM -> Tool (direct execution) -> Result
-```
-
-The LLM decides what to execute. The tool runs it blindly. This is why prompt injection attacks work - the LLM's output *is* the program.
-
-**Our approach: Agent -> Proxy -> Sandbox -> Tool**
-```
-+---------------------------------------------------------------------+
-|  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                                        |
-|  [x] Are all types correct? 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: Cannot exceed granted permissions         |
-+----------------------------+----------------------------------------+
-                             | Execution with audit
-                             v
-+---------------------------------------------------------------------+
-|  ProofDAG: Records execution witness                                 |
-|  * What tool ran                                                     |
-|  * What inputs were used                                             |
-|  * What outputs were produced                                        |
-|  * SHA-256 hash of entire execution                                  |
-+---------------------------------------------------------------------+
-```
-
-The LLM never executes directly. It proposes. The proxy validates. The sandbox enforces. The proof records. Four independent layers of defense.
-
----
-
-## What You Can Do
-
-| Query Type | Use Case | Example |
-|------------|----------|---------|
-| **SPARQL** | Find connected entities | `SELECT ?claim WHERE { ?claim :provider :PROV001 }` |
-| **Datalog** | Recursive fraud detection | `fraud_ring(X,Y) :- knows(X,Y), claims_with(X,P), claims_with(Y,P)` |
-| **Motif** | Network pattern matching | `(a)-[e1]->(b); (b)-[e2]->(a)` finds circular relationships |
-| **GraphFrame** | Social network analysis | `gf.pageRank(0.15, 20)` ranks entities by connection importance |
-| **Pregel** | Shortest paths at scale | `pregelShortestPaths(gf, 'source', 100)` for billion-edge graphs |
-| **Embeddings** | Semantic similarity | `embeddings.findSimilar('CLM001', 10, 0.7)` finds related claims |
-| **Agent** | Natural language interface | `agent.ask("Which providers show fraud patterns?")` |
-
-Each of these runs in the same embedded database. No separate systems to maintain.
+| Framework | Without Schema | With Schema |
+|-----------|---------------|-------------|
+| Vanilla LLM | 0% | - |
+| LangChain | 0% | 71.4% |
+| DSPy | 14.3% | 71.4% |
+| HyperMind | - | 71.4% |
 
----
+All frameworks achieve similar accuracy WITH schema. The difference is HyperMind integrates schema handling - you do not manually inject it.
 
 ## Quick Start
 
@@ -365,61 +159,33 @@ const { GraphDB, HyperMindAgent } = require('rust-kgdb');
 
 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 .
+  <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> .
 `);
 
-const agent = new HyperMindAgent({ db });
-const result = await agent.ask("Which providers show suspicious billing patterns?");
+// 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
+});
+
+// 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"
 
-console.log(result.evidence);
-// Full audit trail proving every fact came from your database
-```
+console.log(result.explanation);
+// Full execution trace showing tool calls
 
----
-
-## Architecture: Two Layers
-
-```
-+---------------------------------------------------------------------------------+
-|                           YOUR APPLICATION                                       |
-|                 (Fraud Detection, Underwriting, Compliance)                      |
-+------------------------------------+--------------------------------------------+
-                                     |
-+------------------------------------v--------------------------------------------+
-|                    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
-+------------------------------------v--------------------------------------------+
-|                    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                                     |
-+----------------------------------------------------------------------------------+
+console.log(result.proof);
+// Cryptographic proof DAG with SHA-256 hashes
 ```
 
----
-
 ## Core Components
 
 ### GraphDB: SPARQL Engine (449ns lookups)
@@ -463,7 +229,7 @@ const gf = new GraphFrame(
 // Algorithms
 console.log('PageRank:', gf.pageRank(0.15, 20));
 console.log('Connected Components:', gf.connectedComponents());
-console.log('Triangles:', gf.triangleCount());  // 1
+console.log('Triangles:', gf.triangleCount());
 console.log('Shortest Paths:', gf.shortestPaths('alice'));
 
 // Motif finding (pattern matching)
@@ -477,19 +243,57 @@ const { EmbeddingService } = require('rust-kgdb');
 
 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'));
+// Store 384-dimensional vectors
+embeddings.storeVector('claim_001', vectorFromOpenAI);
+embeddings.storeVector('claim_002', vectorFromOpenAI);
 
 // Build HNSW index
 embeddings.rebuildIndex();
 
 // Find similar (16ms for 10K vectors)
 const similar = embeddings.findSimilar('claim_001', 10, 0.7);
+```
 
-// 1-hop neighbor cache (ARCADE algorithm)
-embeddings.onTripleInsert('claim_001', 'claimant', 'person_123', null);
-const neighbors = embeddings.getNeighborsOut('person_123');
+### Embedding Triggers: Auto-Generate on Insert
+
+```javascript
+const { GraphDB, EmbeddingService, TriggerManager } = require('rust-kgdb');
+
+const db = new GraphDB('http://example.org/');
+const embeddings = new EmbeddingService();
+
+// 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'
+  }
+});
+
+// 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
+  }
+});
+
+// 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
+
+// Query by similarity (uses auto-generated embeddings)
+const similar = embeddings.findSimilar('claim_001', 10, 0.7);
 ```
 
 ### DatalogProgram: Rule-Based Reasoning
@@ -517,239 +321,525 @@ const inferred = evaluateDatalog(datalog);
 // connected(alice, charlie) - derived!
 ```
 
-### Pregel: Billion-Edge Graph Processing
+## Why Our Tool Calling Is Different
 
-```javascript
-const { pregelShortestPaths, chainGraph } = require('rust-kgdb');
+Traditional AI tool calling (OpenAI Functions, LangChain Tools) has problems:
 
-// Create large graph
-const graph = chainGraph(10000);  // 10K vertices
+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.
 
-// Run Pregel BSP algorithm
-const distances = pregelShortestPaths(graph, 'v0', 100);
-```
+Our Approach: Tools as Typed Morphisms
+
+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
 
----
+The type system catches mismatches at plan time, not runtime.
 
-## HyperMind Agent Framework
+| 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 |
+
+## Trust Model: Proxied Execution
 
-### Why Vanilla LLMs Fail
+Traditional tool calling trusts the LLM output completely. The LLM decides what to execute. The tool runs it blindly.
+
+Our approach: Agent to Proxy to Sandbox to Tool
 
 ```
-User: "Find all professors"
-
-Vanilla LLM Output:
-+-----------------------------------------------------------------------+
-| ```sparql                                                             |
-| SELECT ?professor WHERE { ?professor a ub:Faculty . }                 |
-| ```                            <- Parser rejects markdown              |
-|                                                                       |
-| This query retrieves faculty members.                                 |
-|                                ^ Mixed text breaks parsing            |
-+-----------------------------------------------------------------------+
-Result: FAIL PARSER ERROR - Invalid SPARQL syntax
++---------------------------------------------------------------------+
+|  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                                 |
++---------------------------------------------------------------------+
 ```
 
-**Problems:** (1) Markdown code fences, (2) Wrong class name (Faculty vs Professor), (3) Mixed text
+The LLM never executes directly. It proposes. The proxy validates. The sandbox enforces. The proof records. Four independent layers of defense.
+
+## Agent Memory: Deep Flashback
 
-### How HyperMind Solves This
+Most AI agents forget everything between sessions. HyperMind stores memory in the same knowledge graph as your data.
 
 ```
-User: "Find all professors"
-
-HyperMind Output:
-+-----------------------------------------------------------------------+
-| PREFIX ub: <http://swat.cse.lehigh.edu/onto/univ-bench.owl#>         |
-| SELECT ?professor WHERE { ?professor a ub:Professor . }               |
-+-----------------------------------------------------------------------+
-Result: OK 15 results returned in 2.3ms
++-----------------------------------------------------------------------------+
+|                         MEMORY HYPERGRAPH                                   |
+|                                                                             |
+|   AGENT MEMORY LAYER                                                        |
+|   +-----------+     +-----------+     +-----------+                         |
+|   |Episode:001|     |Episode:002|     |Episode:003|                         |
+|   |"Fraud ring|     |"Denied    |     |"Follow-up |                         |
+|   | detected" |     | claim"    |     | on P001"  |                         |
+|   +-----+-----+     +-----+-----+     +-----+-----+                         |
+|         |                 |                 |                               |
+|         +-----------------+-----------------+                               |
+|                           | HyperEdges connect to KG                        |
+|                           v                                                 |
+|   KNOWLEDGE GRAPH LAYER                                                     |
+|   +-----------------------------------------------------------------+       |
+|   |  Provider:P001 -----> Claim:C123 <----- Claimant:John           |       |
+|   |       |                   |                   |                 |       |
+|   |       v                   v                   v                 |       |
+|   |  riskScore: 0.87    amount: 50000       address: "123 Main"     |       |
+|   +-----------------------------------------------------------------+       |
+|                                                                             |
+|   SAME QUAD STORE - Single SPARQL query traverses BOTH!                     |
++-----------------------------------------------------------------------------+
 ```
 
-**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
+- 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 Performance:
+- 94% Recall at 10K depth
+- 16.7ms search speed for 10K queries
+- 132K ops/sec write throughput
 
-**Accuracy: 0% -> 86.4%** (LUBM benchmark, 14 queries)
+### Conversation Knowledge Extraction
 
-### Agent Components
+Every conversation automatically extracts entities and relationships into the knowledge graph:
 
 ```javascript
-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();
-
-// Execute with natural language
-const result = await agent.call("Find circular payment patterns");
-
-// Get cryptographic proof
-console.log(result.witness.proof_hash);  // sha256:a3f2b8c9...
+// Agent conversation automatically extracts knowledge
+const result = await agent.ask("Provider P001 submitted 5 claims last month totaling $47,000");
+
+// 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
 ```
 
-### WASM Sandbox: Secure Execution
+### Idempotent Responses (Same Question = Same Answer)
 
 ```javascript
-const sandbox = new WasmSandbox({
-  capabilities: ['ReadKG', 'ExecuteTool'],  // Fine-grained
-  fuelLimit: 1000000,                        // CPU metering
-  maxMemory: 64 * 1024 * 1024               // Memory limit
-});
-
-// All tool calls are:
-// [x] Capability-checked
-// [x] Fuel-metered
-// [x] Memory-bounded
-// [x] Logged for audit
+// 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
 ```
 
-### Execution Witness (Audit Trail)
-
-Every execution produces a cryptographic proof:
+## HyperAgent Core Concepts
 
-```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..."
-}
+```
++-----------------------------------------------------------------------------+
+|                    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                         |
++-----------------------------------------------------------------------------+
 ```
 
-**Compliance:** Full audit trail for SOX, GDPR, FDA 21 CFR Part 11.
+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
 
-## Agent Memory: Deep Flashback
+```javascript
+const { GraphDB } = require('rust-kgdb');
+const db = new GraphDB('http://example.org/');
 
-Most AI agents have amnesia. Ask the same question twice, they start from scratch.
+// 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" .
+`);
 
-### The Problem
+// Basic SELECT query
+const friends = db.querySelect(`
+  SELECT ?person ?friend WHERE {
+    ?person :knows ?friend
+  }
+`);
 
-- ChatGPT forgets after context window fills
-- LangChain rebuilds context every call (~500ms)
-- Vector databases return "similar" docs, not exact matches
+// FILTER with comparison
+const adults = db.querySelect(`
+  SELECT ?person ?age WHERE {
+    ?person :age ?age .
+    FILTER(?age >= 30)
+  }
+`);
 
-### Our Solution: Memory Hypergraph
+// OPTIONAL pattern
+const withCity = db.querySelect(`
+  SELECT ?person ?city WHERE {
+    ?person :knows ?someone .
+    OPTIONAL { ?person :city ?city }
+  }
+`);
 
-```
-+-----------------------------------------------------------------------------+
-|                         MEMORY HYPERGRAPH                                    |
-|                                                                              |
-|   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                      |
-|                              v                                               |
-|   KNOWLEDGE GRAPH LAYER                                                      |
-|   +---------------------------------------------------------------------+   |
-|   |  Provider:P001 ------> Claim:C123 <------ Claimant:John            |   |
-|   |       |                    |                    |                   |   |
-|   |       v                    v                    v                   |   |
-|   |   riskScore: 0.87     amount: 50000        address: "123 Main"     |   |
-|   +---------------------------------------------------------------------+   |
-|                                                                              |
-|   SAME QUAD STORE - Single SPARQL query traverses BOTH!                     |
-+-----------------------------------------------------------------------------+
+// Aggregation
+const avgAge = db.querySelect(`
+  SELECT (AVG(?age) as ?average) WHERE {
+    ?person :age ?age
+  }
+`);
+
+// CONSTRUCT new triples
+const inferred = db.queryConstruct(`
+  CONSTRUCT { ?a :friendOfFriend ?c }
+  WHERE {
+    ?a :knows ?b .
+    ?b :knows ?c .
+    FILTER(?a != ?c)
+  }
+`);
+
+// 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
+  }
+`);
 ```
 
-### Benchmarked Performance
+## Datalog Reasoning Examples
 
-| 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 |
+```javascript
+const { DatalogProgram, evaluateDatalog } = require('rust-kgdb');
 
-### Idempotent Responses
+const datalog = new DatalogProgram();
 
-Same question = Same answer. Even with different wording.
+// 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']}));
 
-```javascript
-// First call: Compute answer, cache with semantic hash
-const result1 = await agent.call("Analyze claims from Provider P001");
+// 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']}
+  ]
+}));
 
-// Second call (different wording): Cache HIT!
-const result2 = await agent.call("Show me P001's claim patterns");
-// Same semantic hash -> Same result
+// 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
+
+```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', ...}]
 
-## Mathematical Foundations
+// Find chains: (a)->(b)->(c)
+const chains = gf.find('(a)-[e1]->(b); (b)-[e2]->(c)');
 
-### Category Theory: Tools as Morphisms
+// 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)');
 ```
-Tools are typed arrows:
-  kg.sparql.query:     Query -> BindingSet
-  kg.motif.find:       Pattern -> Matches
-  kg.datalog.apply:    Rules -> InferredFacts
-
-Composition is type-checked:
-  f: A -> B
-  g: B -> C
-  g o f: A -> C  (valid only if B matches)
-
-Laws guaranteed:
-  Identity:      id o f = f
-  Associativity: (h o g) o f = h o (g o f)
+
+## Clustered KGDB
+
+For datasets exceeding single-node capacity (1B+ triples), rust-kgdb supports distributed deployment:
+
 ```
++-----------------------------------------------------------------------------+
+|                       DISTRIBUTED CLUSTER ARCHITECTURE                       |
+|                                                                              |
+|   +-------------------+                                                      |
+|   |   COORDINATOR     |  <- Routes queries, manages partitions               |
+|   | (Raft consensus)  |                                                      |
+|   +--------+----------+                                                      |
+|            |                                                                 |
+|   +--------+--------+--------+--------+                                      |
+|   |        |        |        |        |                                      |
+|   v        v        v        v        v                                      |
+| +----+  +----+  +----+  +----+  +----+                                       |
+| |Exec|  |Exec|  |Exec|  |Exec|  |Exec|  <- Partition executors               |
+| | 0  |  | 1  |  | 2  |  | 3  |  | 4  |                                       |
+| +----+  +----+  +----+  +----+  +----+                                       |
+|   |        |        |        |        |                                      |
+|   v        v        v        v        v                                      |
+| [===]   [===]   [===]   [===]   [===]   <- Local RocksDB partitions          |
+|                                                                              |
+|   HDRF Partitioning: Subject-anchored streaming (load factor < 1.1)          |
+|   Shadow Partitions: Zero-downtime rebalancing (~10ms pause)                 |
+|   DataFusion: Arrow-native 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
 
-**In practice:** The AI can only chain tools where outputs match inputs. Like Lego blocks that must fit.
+Deployment:
 
-### WCOJ: Worst-Case Optimal Joins
+```bash
+# Kubernetes deployment
+kubectl apply -f infra/k8s/coordinator.yaml
+kubectl apply -f infra/k8s/executor.yaml
 
-Finding "all cases where Judge X ruled on Contract Y involving Company Z"?
+# Helm chart
+helm install rust-kgdb ./infra/helm -n rust-kgdb --create-namespace
 
-**Traditional:** Check every case with Judge X (50K), every contract (500K combinations), every company (25M checks).
+# Verify cluster
+kubectl get pods -n rust-kgdb
+curl http://<coordinator-ip>:8080/api/v1/health
+```
 
-**WCOJ:** Keep sorted indexes. Walk through all three simultaneously. Skip impossible combinations. 50K checks instead of 25 million.
+## HyperAgent: Fraud Detection Example
 
-### HNSW: Hierarchical Navigable Small World
+```javascript
+const { GraphDB, HyperMindAgent, DatalogProgram, evaluateDatalog } = require('rust-kgdb');
+
+// Create database with insurance claims data (N-Triples format for reliability)
+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/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
+  }
+});
 
-Finding similar items from 50,000 vectors?
+// Natural language fraud detection
+const result = await agent.call("Which providers show suspicious billing patterns?");
 
-**Brute force:** Compare to all 50,000. O(n).
+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"
 
-**HNSW:** Build a multi-layer graph. Start at top layer, descend toward target. ~20 hops. O(log n).
+console.log(result.explanation);
+// Full execution trace showing tool calls
 
-### Datalog: Recursive Rule Evaluation
+console.log(result.proof);
+// Cryptographic proof DAG with SHA-256 hashes
 
+// Use Datalog for collusion detection rules
+const datalog = new DatalogProgram();
+datalog.addFact(JSON.stringify({predicate:'knows', terms:['CLMT001','CLMT002']}));
+datalog.addFact(JSON.stringify({predicate:'sameAddress', terms:['CLMT001','CLMT002']}));
+datalog.addRule(JSON.stringify({
+  head: {predicate:'potential_collusion', terms:['?X','?Y']},
+  body: [
+    {predicate:'knows', terms:['?X','?Y']},
+    {predicate:'sameAddress', terms:['?X','?Y']}
+  ]
+}));
+const inferred = evaluateDatalog(datalog);
+console.log('Collusion detected:', JSON.parse(inferred));
 ```
-mustReport(X) :- transaction(X), amount(X, A), A > 10000.
-mustReport(X) :- transaction(X), involves(X, PEP).
-mustReport(X) :- relatedTo(X, Y), mustReport(Y).  # Recursive!
-```
 
-Three rules generate ALL reporting requirements. Even for transactions connected to other suspicious transactions, cascading infinitely.
+## HyperAgent: Underwriting Example
+
+```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> .
+  <http://underwriting.org/APP001> <http://underwriting.org/name> "Acme Corp" .
+  <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" .
+  <http://underwriting.org/COMP001> <http://underwriting.org/employees> "230" .
+  <http://underwriting.org/COMP001> <http://underwriting.org/premium> "625000" .
+`, null);
+
+// Optional: Add 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));
+
+// 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
+const similar = embeddings.findSimilar('APP001', 5, 0.7);
+console.log('Similar accounts:', JSON.parse(similar));
+
+// Direct SPARQL query for engineering teams
+const comparables = db.querySelect(`
+  SELECT ?company ?employees ?premium WHERE {
+    ?company <http://underwriting.org/industry> "Manufacturing" .
+    ?company <http://underwriting.org/employees> ?employees .
+    OPTIONAL { ?company <http://underwriting.org/premium> ?premium }
+  }
+`);
+console.log('Comparables:', comparables);
+```
 
 ## Real-World Examples
 
@@ -781,7 +871,7 @@ 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 with Datalog
+### Insurance: Fraud Detection
 
 ```javascript
 const db = new GraphDB('http://insurer.com/');
@@ -809,398 +899,205 @@ const inferred = evaluateDatalog(datalog);
 // potential_collusion(P001, P002, PROV001) - DETECTED!
 ```
 
-### AML: Circular Payment Detection
-
-```javascript
-db.loadTtl(`
-  :Acct_1001 :transferredTo :Acct_2002 ; :amount 9500 .
-  :Acct_2002 :transferredTo :Acct_3003 ; :amount 9400 .
-  :Acct_3003 :transferredTo :Acct_1001 ; :amount 9200 .
-`);
-
-// Find circular chains (money laundering indicator)
-const triangles = gf.triangleCount();  // 1 circular pattern
-```
-
----
-
 ## Performance Benchmarks
 
 All measurements verified. Run them yourself:
 
 ```bash
-node benchmark.js              # Core performance
-node vanilla-vs-hypermind-benchmark.js  # Agent accuracy
+node benchmark.js                       # Core engine benchmarks
+node concurrency-benchmark.js           # Multi-worker concurrency
+node vanilla-vs-hypermind-benchmark.js  # HyperMind vs vanilla LLM
 ```
 
 ### 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 |
+| 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 |
 
-### Agent Accuracy (LUBM Benchmark)
+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)
 
-| System | Without Schema | With Schema |
-|--------|---------------|-------------|
-| Vanilla LLM | 0% | - |
-| LangChain | 0% | 71.4% |
-| DSPy | 14.3% | 71.4% |
-| **HyperMind** | - | **71.4%** |
-
-*All frameworks achieve same accuracy WITH schema. HyperMind's advantage is integrated schema handling.*
-
-### Concurrency (16 Workers)
-
-| Operation | Throughput |
-|-----------|------------|
-| Writes | 132K ops/sec |
-| Reads | 302 ops/sec |
-| GraphFrames | 6.5K ops/sec |
-| Mixed | 642 ops/sec |
-
----
-
-## 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 |
-
----
-
-## Installation
-
-```bash
-npm install rust-kgdb
-```
-
-**Platforms:** macOS (Intel/Apple Silicon), Linux (x64/ARM64), Windows (x64)
-
-**Requirements:** Node.js 14+
+### 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 |
 
-## Complete Fraud Detection Example
+Source: `node concurrency-benchmark.js` (100 ops/worker, LUBM data)
 
-Copy this entire example to get started with fraud detection:
+### HyperMind Agent Accuracy (LUBM Benchmark)
 
-```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
-  );
-}
-
-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']}
-  ]
-}));
-
-// 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)
-  }
-`);
-
-console.log('High-risk claims:', suspiciousClaims);
-
-// ============================================================
-// STEP 7: HyperMind Agent - Natural Language Interface
-// ============================================================
-const agent = new HyperMindAgent({ db, embeddings });
-
-async function investigate() {
-  const result = await agent.ask("Which claims show potential fraud patterns?");
-
-  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);
-```
-
----
-
-## Complete Underwriting Example
-
-```javascript
-const { GraphDB, DatalogProgram, evaluateDatalog } = require('rust-kgdb');
-
-// ============================================================
-// Automated Underwriting Rules Engine
-// ============================================================
-const db = new GraphDB('http://underwriting.org/');
-
-// 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
-  ]
-}));
-
-const decisions = JSON.parse(evaluateDatalog(datalog));
-console.log('Underwriting decisions:', decisions);
-```
-
----
+| 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 |
+
+### 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)
+
+| 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 |
+
+### AI/ML Features
+
+| Feature | Performance | Description |
+|---------|-------------|-------------|
+| HNSW Embeddings | 16ms/10K vectors | 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 |
+
+### 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 |
+
+### 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 |
+
+### 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 |
+| 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 |
 
 ## API Reference
 
 ### GraphDB
 
 ```javascript
-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
+const db = new GraphDB(baseUri)
+db.loadTtl(turtle, graphUri)
+db.querySelect(sparql)
+db.queryConstruct(sparql)
+db.countTriples()
+db.clear()
 ```
 
 ### GraphFrame
 
 ```javascript
 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
+gf.pageRank(dampingFactor, iterations)
+gf.connectedComponents()
+gf.triangleCount()
+gf.shortestPaths(sourceId)
+gf.find(motifPattern)
 ```
 
 ### EmbeddingService
 
 ```javascript
 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
+emb.storeVector(entityId, float32Array)
+emb.rebuildIndex()
+emb.findSimilar(entityId, k, threshold)
 ```
 
 ### DatalogProgram
 
 ```javascript
 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
+dl.addFact(factJson)
+dl.addRule(ruleJson)
+evaluateDatalog(dl)
 ```
 
-### Pregel
+### Factory Functions
 
 ```javascript
-pregelShortestPaths(graphFrame, sourceId, maxIterations)
-// Returns: distance map from source to all vertices
+friendsGraph()
+chainGraph(n)
+starGraph(n)
+completeGraph(n)
+cycleGraph(n)
 ```
 
-### Factory Functions
+## Installation
 
-```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
+```bash
+npm install rust-kgdb
 ```
 
----
+Platforms: macOS (Intel/Apple Silicon), Linux (x64/ARM64), Windows (x64)
+
+Requirements: Node.js 14+
+
+## License
 
-Apache 2.0 License
+Apache 2.0