rust-kgdb 0.6.63 → 0.6.64

package/README.md

@@ -1,331 +1,111 @@
 # 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 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
 
-**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
+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
 
-**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 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
 
 ## 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 | 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 |
+| 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 |
 
-**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
 
@@ -379,47 +159,6 @@ console.log(result.evidence);
 // Full audit trail proving every fact came from your database
 ```
 
----
-
-## 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                                     |
-+----------------------------------------------------------------------------------+
-```
-
----
-
 ## Core Components
 
 ### GraphDB: SPARQL Engine (449ns lookups)
@@ -463,7 +202,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 +216,15 @@ 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');
 ```
 
 ### DatalogProgram: Rule-Based Reasoning
@@ -517,239 +252,114 @@ const inferred = evaluateDatalog(datalog);
 // connected(alice, charlie) - derived!
 ```
 
-### Pregel: Billion-Edge Graph Processing
-
-```javascript
-const { pregelShortestPaths, chainGraph } = require('rust-kgdb');
-
-// Create large graph
-const graph = chainGraph(10000);  // 10K vertices
-
-// Run Pregel BSP algorithm
-const distances = pregelShortestPaths(graph, 'v0', 100);
-```
-
----
+## Why Our Tool Calling Is Different
 
-## HyperMind Agent Framework
+Traditional AI tool calling (OpenAI Functions, LangChain Tools) has problems:
 
-### Why Vanilla LLMs Fail
+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.
 
-```
-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
-```
+Our Approach: Tools as Typed Morphisms
 
-**Problems:** (1) Markdown code fences, (2) Wrong class name (Faculty vs Professor), (3) Mixed text
+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
 
-### How HyperMind Solves This
+The type system catches mismatches at plan time, not runtime.
 
-```
-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
-```
-
-**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
-
-**Accuracy: 0% -> 86.4%** (LUBM benchmark, 14 queries)
+| 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 |
 
-### Agent Components
+## Trust Model: Proxied Execution
 
-```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...
-```
+Traditional tool calling trusts the LLM output completely. The LLM decides what to execute. The tool runs it blindly.
 
-### WASM Sandbox: Secure Execution
+Our approach: Agent to Proxy to Sandbox to Tool
 
-```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
 ```
-
-### Execution Witness (Audit Trail)
-
-Every execution produces a cryptographic proof:
-
-```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..."
-}
++---------------------------------------------------------------------+
+|  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                                 |
++---------------------------------------------------------------------+
 ```
 
-**Compliance:** Full audit trail for SOX, GDPR, FDA 21 CFR Part 11.
-
----
+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
 
-Most AI agents have amnesia. Ask the same question twice, they start from scratch.
-
-### The Problem
-
-- ChatGPT forgets after context window fills
-- LangChain rebuilds context every call (~500ms)
-- Vector databases return "similar" docs, not exact matches
-
-### Our Solution: Memory Hypergraph
+Most AI agents forget everything between sessions. HyperMind stores memory in the same knowledge graph as your data.
 
 ```
 +-----------------------------------------------------------------------------+
-|                         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"     |   |
-|   +---------------------------------------------------------------------+   |
-|                                                                              |
+|                         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!                     |
 +-----------------------------------------------------------------------------+
 ```
 
-### Benchmarked Performance
-
-| 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 |
-
-### Idempotent Responses
-
-Same question = Same answer. Even with different wording.
-
-```javascript
-// First call: Compute answer, cache with semantic hash
-const result1 = await agent.call("Analyze claims from Provider P001");
-
-// Second call (different wording): Cache HIT!
-const result2 = await agent.call("Show me P001's claim patterns");
-// Same semantic hash -> Same result
-```
-
----
-
-## Mathematical Foundations
-
-### Category Theory: Tools as Morphisms
-
-```
-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)
-```
-
-**In practice:** The AI can only chain tools where outputs match inputs. Like Lego blocks that must fit.
-
-### WCOJ: Worst-Case Optimal Joins
+- 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
 
-Finding "all cases where Judge X ruled on Contract Y involving Company Z"?
-
-**Traditional:** Check every case with Judge X (50K), every contract (500K combinations), every company (25M checks).
-
-**WCOJ:** Keep sorted indexes. Walk through all three simultaneously. Skip impossible combinations. 50K checks instead of 25 million.
-
-### HNSW: Hierarchical Navigable Small World
-
-Finding similar items from 50,000 vectors?
-
-**Brute force:** Compare to all 50,000. O(n).
-
-**HNSW:** Build a multi-layer graph. Start at top layer, descend toward target. ~20 hops. O(log n).
-
-### Datalog: Recursive Rule Evaluation
-
-```
-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.
-
----
+Memory Retrieval Performance:
+- 94% Recall at 10K depth
+- 16.7ms search speed for 10K queries
+- 132K ops/sec write throughput
 
 ## Real-World Examples
 
@@ -781,7 +391,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,48 +419,22 @@ 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
+node vanilla-vs-hypermind-benchmark.js
 ```
 
 ### 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 |
-
-### Agent Accuracy (LUBM Benchmark)
-
-| 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.*
+| 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 |
 
 ### Concurrency (16 Workers)
 
@@ -859,348 +443,86 @@ node vanilla-vs-hypermind-benchmark.js  # Agent accuracy
 | 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+
-
----
-
-## Complete Fraud Detection Example
-
-Copy this entire example to get started with fraud detection:
-
-```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);
-```
-
----
+| 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 |
+| AI | HNSW Embeddings | 16ms/10K vectors |
+| AI | Agent Memory | 94% recall |
+| Reasoning | Datalog | Semi-naive |
+| Security | WASM Sandbox | Capability-based |
+| Audit | ProofDAG | SHA-256 witnesses |
 
 ## 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