superbrain-fabric-sdk 5.0.0 → 5.1.0

package/README.md

@@ -1,229 +1,80 @@
-# 🧠 superbrain-fabric-sdk v5.0.0 — TypeScript/Node.js
+# Superbrain Fabric Node.js SDK (V5.1) 🧠✨
 
-[![npm version](https://badge.fury.io/js/superbrain-fabric-sdk.svg)](https://badge.fury.io/js/superbrain-fabric-sdk)
-[![License: BSL 1.1](https://img.shields.io/badge/License-BSL%201.1-blue.svg)](https://github.com/golightstep/superbrainSdk/blob/main/LICENSE)
-[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org)
-
-> **The Distributed RAM Fabric for AI Agents** — Share terabytes of context across your LLM cluster at microsecond speeds using 36-byte UUID pointers.
-
----
-
-🔥 **v5.0.0-cognitive: The Cognitive Fabric Update** is now live!
+**Superbrain Fabric** is a high-performance, distributed cognitive RAM fabric. This SDK allows your AI agents to treat memory as an active, self-reflecting participant in their reasoning loops.
 
 ---
 
-## ⚡ v3.0.0-cognitive Highlights
+## 💎 The Soul Expansion (V5.1 Breakthroughs)
 
-This major release transforms the Node.js SDK into a microsecond-latency **Active Memory Tier**.
+V5.1 transitions Superbrain Fabric from a fast storage layer into a **Cognitive Organism**.
 
-### Key Highlights:
-- **Durable Persistence**: Full support for WAL-backed storage nodes (FileStore/Redis/Postgres).
-- **Coordinator Bypass**: 100x faster pointer resolution via local metadata caching.
-- **Semantic Triggers**: Subscribe to memory offsets and get notified when agents write with specific intents.
-- **Zero-Copy SHM**: Optimized FFI for direct `/dev/shm` access on Linux.
+### 📉 Layered Cognitive Compression (LCC)
+Achieve **11-38x token reduction** before data ever hits the wire.
+- **Level 1 (Deterministic)**: Prunes structural noise (HTML/JSON boilerplate).
+- **Level 2 (Semantic)**: Prevents redundant writes via Jaccard-deduplication.
+- **Level 3 (Extractive)**: Consolidates long contexts into extractive summaries.
 
-### 🧠 Example: Semantic Memory Trigger
-```typescript
-import { SuperbrainFabricClient } from 'superbrain-fabric-sdk';
+### 🕰️ Memory History (The Hippocampus)
+100% auditable lineage. Retrieve the full versioned history of any memory block to understand why an agent modified a belief.
 
-const client = new SuperbrainFabricClient('localhost:50050');
+### 🕸️ Knowledge Graph (The Cortical Mesh)
+Distributed relational memory. Link memories via explicit edges (`supports`, `contradicts`, `part-of`) and traverse them via recursive discovery.
 
-// Subscribe to "User Intent" updates across the whole cluster
-client.semanticSubscribe('User Intent', (notify) => {
-    console.log(`🧠 Neural Trigger: ${notify.snippet}`);
-    console.log(`Intent detected: ${notify.intent}`);
-});
+### 🪞 MIRROR Tier (Stability)
+Use Lyapunov-inspired stability loops to protect critical reasoning blocks from the automatic decay cycles.
 
-// Write with cognitive enrichment
-await client.writeCognitive(ptr, 0, data, {
-    liveliness: 0.8,
-    intent: 'User Intent',
-    summary: 'Updating user preference profile',
-    tag: 'Preference'
-});
-```
+---
 
-## 📦 Installation
+## 🚀 Quickstart
 
+### 1. Installation
 ```bash
 npm install superbrain-fabric-sdk
 ```
 
----
-
-## 🚀 New in v3.0.0-cognitive — Active Memory & Coordinator Bypass
-Version 3.0.0 introduces the ability to operate as a microsecond-latency **Active Memory Tier** for agent architectures.
-
-- **Coordinator Bypass**: Metadata is cached locally, eliminating the gRPC hop to the Coordinator for established pointers.
-- **Zero-Copy SHM**: When the SDK detects a co-located Memory Node (`127.0.0.1`), it seamlessly switches from gRPC streaming to direct `/dev/shm` memory-mapped file access.
-- **13.5µs Native Latency**: The Native Go core bypass achieves microsecond speed, bypassing the network entirely for local agents.
-
----
-
-## 🔧 Usage
-
-### Basic — Shared Memory Between Agents
+### 2. High-Level Memory Write
 ```typescript
-import { SuperbrainFabricClient } from 'superbrain-fabric-sdk';
-
-const client = new SuperbrainFabricClient('localhost:50050');
-await client.register('my-agent-id');
-
-// Allocate distributed RAM
-const ptrId = await client.allocate(100 * 1024 * 1024); // 100 MB
-
-// Write from Agent A on Machine A
-await client.write(ptrId, 0, Buffer.from('Shared AI context'));
-
-// Read from Agent B on Machine B (just needs the 36-byte pointer!)
-const data = await client.read(ptrId, 0, 17);
-
-await client.free(ptrId);
-client.close();
-```
+import { Client } from 'superbrain-fabric-sdk';
 
-### Advanced — Secure Fabric (E2EE)
-```typescript
-import { SuperbrainClient } from 'superbrain-distributed-sdk';
+// Connect to the Fabric
+const client = new Client("coordinator:50050");
 
-// All data encrypted with AES-256-GCM at client level
-// Memory nodes NEVER see plaintext
-const client = new SuperbrainClient('localhost:50050', {
-  encryptionKey: crypto.randomBytes(32)
+// Write a memory with automated LCC Level 3 and Mirror protection
+const ptrId = await client.writeMemory("Long research context...", {
+    liveliness: 0.9, 
+    tag: "strategy", 
+    lccLevel: 3,
+    mirrorReinforcement: true
 });
-await client.register('secure-agent');
 
-const ptr = await client.allocate(4 * 1024 * 1024);
-await client.write(ptr, 0, Buffer.from(JSON.stringify(sensitiveData)));
-const response = await client.read(ptr, 0, 0);
+console.log(`Memory anchored at: ${ptrId}`);
 ```
 
-### Multi-Agent Context Passing
+### 3. Relational Discovery (Knowledge Graph)
 ```typescript
-// Agent A writes — gets pointer
-const ctxPtr = await client.allocate(1024 * 1024);
-await client.write(ctxPtr, 0, Buffer.from(JSON.stringify({
-  topic: "distributed AI inference",
-  findings: researchResults,
-  timestamp: Date.now()
-})));
-
-// Share the 36-byte pointer ID via any channel (HTTP, gRPC, etc.)
-broadcast({ contextPtr: ctxPtr }); // other agents connect immediately
-
-// Agent B reads — microseconds, no data copying
-const received = JSON.parse((await clientB.read(ctxPtr, 0, 0)).toString());
-```
-
----
+// Link two cognitive blocks
+await client.addEdge(sourcePtr, targetPtr, "supports", 1.0);
 
-## 📊 Architecture
-
-```
-Your LLM App (SDK)                 SuperBrain Cluster
-┌─────────────────────────┐
-│  allocate(size) ────────┼──(1)──► Coordinator (Control Plane)
-│  free(ptr_id)   ────────┼──(5)──► Maps pointers → node locations
-│                         │                │
-│                         │         (2) pointer map returned
-│                         │                │
-│  write(ptr_id, data) ───┼──(3)──►┌───────▼──────────────┐
-│  read(ptr_id)   ────────┼──(4)──►│   Memory Nodes       │
-└─────────────────────────┘        │   (Data Plane)       │
-                                   │   1TB+ pooled RAM    │
-                                   └──────────────────────┘
-
-CRITICAL: write() and read() bypass the Coordinator entirely.
-They stream directly to the Memory Nodes over gRPC for maximum throughput (~100 MB/s).
-The Coordinator is ONLY in the control path (allocate + free).
+// Query the mesh
+const { edges, nodes } = await client.queryGraph(sourcePtr, 2);
 ```
 
-**Why this matters**: The Coordinator never becomes a bottleneck for your data. 1000 agents can read/write simultaneously to different nodes without fighting for the same control plane.
-
----
-
-## 🧹 Memory Management
-
-> **The Node.js SDK exposes the raw client layer — `free()` is always required after `allocate()`.**
-
+### 4. Audit Trail (History)
 ```typescript
-// ✅ Always do this after you are done with a pointer
-const ptr = await client.allocate(100 * 1024 * 1024);
-await client.write(ptr, 0, data);
-const result = await client.read(ptr, 0, 0);
-await client.free(ptr);   // ← required — leaks memory if skipped
-```
-
-### 🐍 Want Managed Memory? Use the Python SDK
-
-The Python SDK (`pip install superbrain-sdk`) provides higher-level APIs where **free() is never needed**:
-
-| Python API | Free needed? | What it does |
-|------------|:------------:|--------------|
-| `SharedContext.write("key", data)` | ❌ No | Key-based shared state across agents |
-| `fabric.store_kv_cache(prefix)` | ❌ No | Deduped prompt cache, auto-evicted |
-| `SuperBrainMemory` (LangChain) | ❌ No | Chat history in distributed RAM |
-
-```python
-# Python — no free() ever needed with high-level APIs
-from superbrain import DistributedContextFabric
-
-fabric = DistributedContextFabric(coordinator="localhost:50050")
-ctx = fabric.create_context("session-42")
-
-ctx.write("state", {"step": 10})   # written to distributed RAM
-ctx.read("state")                  # read from any machine
-# No free() ✅
+// See how a memory evolved over time
+const history = await client.getMemoryHistory(ptrId);
+history.forEach(snap => {
+    console.log(`Version ${snap.version} tag: ${snap.tag}`);
+});
 ```
 
-→ [Full Memory Management Guide](https://github.com/anispy211/superbrainSdk/blob/main/DOCUMENTATION.md#memory-management--when-to-free)
-
 ---
 
-## 🔐 Security Features
-
-| Feature | Status |
-|---------|--------|
-| mTLS (mutual TLS between all nodes) | ✅ |
-| E2EE (AES-256-GCM at SDK level) | ✅ |
-| Pub/Sub (real-time memory notifications) | ✅ |
-| Per-context key rotation | ✅ (v0.2.0) |
-| Anomaly detection | ✅ (v0.2.0) |
-| GDPR/SOC2 audit logging | ✅ (v0.2.0) |
-
----
-
-## 🗺️ Roadmap
-
-| Phase | Milestone | Features | Status |
-|-------|-----------|----------|--------|
-| **1** | **Distributed Fabric** | Multi-node RAM, Block I/O, P2P Gossip | ✅ Shipped |
-| **2** | **Secure Fabric** | mTLS, E2EE (AES-GCM), CA Authority | ✅ Shipped |
-| **3** | **Active Intelligence** | Cognitive Smart Layers, Durable WAL, Decay, FAISS | 🚀 **Current** |
-| **4** | **Hardware Acceleration** | GPUDirect RDMA, NVMe Spilling (Cold Storage) | 🏗️ Planned |
-| **5** | **Agent Harmony** | Raft-based Consensus Mirroring, Auto-Discovery | 🏗️ Planned |
-
----
-
-## 📚 Documentation
-
-- [Full Documentation & API Reference](https://github.com/anispy211/superbrainSdk/blob/main/DOCUMENTATION.md)
-- [GitHub Repository](https://github.com/anispy211/superbrainSdk)
-- [Main Server Repo](https://github.com/anispy211/memorypool)
-
----
-
-## 🖥️ Server Setup (Required)
-
-This SDK connects to a **SuperBrain coordinator**. To run one locally in 30 seconds:
-
-```bash
-git clone https://github.com/anispy211/memorypool
-cd memorypool
-docker compose up -d
-# Dashboard: http://localhost:8080
-```
+## 🛡️ Security & Performance
+- **E2EE**: Enable via `new Client(addr, Buffer.from(KEY))` for AES-256-GCM SDK-level protection.
+- **Low Latency**: Automated **SHM Bypass** (<15μs) for co-located agents.
+- **Durable Mode**: WAL-backed recovery support.
 
 ---
 
-MIT License · Built by [Anispy](https://github.com/anispy211)
+MIT License · Built by **Anispy**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "superbrain-fabric-sdk",
-  "version": "5.0.0",
-  "description": "Premium High-Performance Distributed Memory Fabric SDK for AI Agents",
+  "version": "5.1.0",
+  "description": "Superbrain Fabric v5.1 — The Soul Expansion: LCC, Memory History, Knowledge Graph & MIRROR stability.",
   "main": "index.js",
   "types": "index.d.ts",
   "repository": {
@@ -15,13 +15,14 @@
   "keywords": [
     "distributed-memory",
     "ai-agents",
-    "kv-cache",
+    "cognitive-fabric",
+    "layered-compression",
+    "memory-history",
+    "knowledge-graph",
+    "mirror-tier",
     "langchain",
-    "pytorch",
     "mcp",
     "grpc",
-    "performance",
-    "context-sharing",
     "llm",
     "rag"
   ],