rust-kgdb 0.6.46 → 0.6.48

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 All notable changes to the rust-kgdb TypeScript SDK will be documented in this file.
 
+## [0.6.48] - 2025-12-17
+
+### Clearer Product Definition
+
+#### Added "What Is This?" Section
+New section at the very top of README explaining:
+
+1. **rust-kgdb** = High-Performance RDF Database (Rust core)
+   - SPARQL 1.1 query engine (449ns lookups)
+   - GraphFrames, Datalog, HNSW embeddings
+
+2. **HyperMind Agent Framework** = AI agent layer (JavaScript)
+   - Natural language queries
+   - Schema auto-extraction
+   - Audit trail
+
+**Summary**: "A knowledge graph database with an AI agent layer on top."
+
+#### Fixed Misleading +14.3pp Claim
+- **Old (wrong)**: "HyperMind's +14.3pp comes from predicate resolver"
+- **New (correct)**: DSPy gets 14.3% WITHOUT schema due to structured output format
+
+**Fact check**: All frameworks achieve identical 71.4% WITH schema.
+
+---
+
+## [0.6.47] - 2025-12-17
+
+### Memory Retrieval Depth Benchmark Added
+
+#### New Benchmark Documentation
+Added Memory Retrieval Depth Benchmark to README, based on academic benchmarks:
+- MemQ (arXiv 2503.05193)
+- mKGQAgent (Text2SPARQL 2025)
+- MTEB (Massive Text Embedding Benchmark)
+
+**Results** (50 queries per depth, HNSW index):
+
+| Depth | P50 Latency | Recall@5 | Recall@10 | MRR |
+|-------|-------------|----------|-----------|-----|
+| 10 | 0.06 ms | 78% | 100% | 0.68 |
+| 100 | 0.50 ms | 88% | 98% | 0.42 |
+| 1,000 | 1.59 ms | 80% | 94% | 0.50 |
+| 10,000 | 16.71 ms | 76% | 94% | 0.54 |
+
+**Key insight**: Even at 10K stored queries, Recall@10 stays at 94% with sub-17ms latency.
+
+Reproduce: `node memory-retrieval-benchmark.js`
+
+---
+
 ## [0.6.46] - 2025-12-17
 
 ### Honest Comparison Fix

package/README.md

@@ -4,6 +4,27 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![W3C](https://img.shields.io/badge/W3C-SPARQL%201.1%20%7C%20RDF%201.2-blue)](https://www.w3.org/TR/sparql11-query/)
 
+## What Is This?
+
+**rust-kgdb** is two things in one package:
+
+1. **High-Performance RDF Database** (Rust core)
+   - SPARQL 1.1 query engine with 449ns lookup speed
+   - GraphFrames analytics (PageRank, connected components, motifs)
+   - Datalog reasoning engine
+   - HNSW vector embeddings for similarity search
+   - 35x faster than RDFox, 25% less memory
+
+2. **HyperMind Agent Framework** (JavaScript layer)
+   - AI agents that query the database using natural language
+   - Schema auto-extraction from your data
+   - Typed tools that prevent hallucination
+   - Audit trail for every answer
+
+**Think of it as**: A knowledge graph database with an AI agent layer on top. The database provides ground truth. The agent layer makes it accessible via natural language.
+
+---
+
 ## AI Answers You Can Trust
 
 **The Problem**: LLMs hallucinate. They make up facts, invent data, and confidently state falsehoods. In regulated industries (finance, healthcare, legal), this is not just annoying—it's a liability.
@@ -135,6 +156,31 @@ db.loadTtl(':Provider123 :hasRiskScore "0.87" .', null)
 └─────────────────────────────────────────────────────────────────────────────┘
 ```
 
+### Memory Retrieval Depth Benchmark
+
+Based on academic benchmarks: MemQ (arXiv 2503.05193), mKGQAgent (Text2SPARQL 2025), MTEB.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  BENCHMARK: Memory Retrieval at Depth (50 queries per depth)                │
+│  METHODOLOGY: LUBM schema-driven queries, HNSW index, random seed 42        │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  DEPTH     │ P50 LATENCY  │ P95 LATENCY  │ Recall@5 │ Recall@10 │   MRR    │
+│  ──────────────────────────────────────────────────────────────────────────│
+│      10    │    0.06 ms   │    0.26 ms   │   78%    │   100%    │  0.68    │
+│     100    │    0.50 ms   │    0.75 ms   │   88%    │    98%    │  0.42    │
+│   1,000    │    1.59 ms   │    5.03 ms   │   80%    │    94%    │  0.50    │
+│  10,000    │   16.71 ms   │   17.37 ms   │   76%    │    94%    │  0.54    │
+│  ──────────────────────────────────────────────────────────────────────────│
+│                                                                             │
+│  KEY INSIGHT: Even at 10,000 stored queries, Recall@10 stays at 94%        │
+│  Sub-17ms retrieval from 10K query pool = practical for production use     │
+│                                                                             │
+│  Reproduce: node memory-retrieval-benchmark.js                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
 ### Where We Actually Outperform (Database Performance)
 
 ```
@@ -175,8 +221,8 @@ db.loadTtl(':Provider123 :hasRiskScore "0.87" .', null)
 │  HONEST TRUTH: Schema injection improves ALL frameworks equally.            │
 │  Any framework + schema context achieves ~71% accuracy.                     │
 │                                                                             │
-│  HyperMind's +14.3pp comes from predicate resolver, but this is             │
-│  incremental improvement, not a fundamental breakthrough.                   │
+│  NOTE: DSPy gets 14.3% WITHOUT schema (vs 0% for others) due to            │
+│  its structured output format. With schema, all converge to 71.4%.          │
 │                                                                             │
 │  OUR REAL VALUE: We include the database. Others don't.                     │
 │  - LangChain generates SPARQL → you need to find a database                 │

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-kgdb",
-  "version": "0.6.46",
+  "version": "0.6.48",
   "description": "High-performance RDF/SPARQL database with AI agent framework. GraphDB (449ns lookups, 35x faster than RDFox), GraphFrames analytics (PageRank, motifs), Datalog reasoning, HNSW vector embeddings. HyperMindAgent for schema-aware query generation with audit trails. W3C SPARQL 1.1 compliant. Native performance via Rust + NAPI-RS.",
   "main": "index.js",
   "types": "index.d.ts",