superbrain-distributed-sdk 0.2.0 → 0.2.2

package/README.md

@@ -90,22 +90,63 @@ const received = JSON.parse((await clientB.read(ctxPtr, 0, 0)).toString());
 ## 📊 Architecture
 
 ```
-Your LLM App             SuperBrain Cluster
-┌──────────────┐         ┌──────────────────────┐
-│ Node.js SDK  │──gRPC──>│   Coordinator        │
-│              │         │   (Control Plane)     │
-│  allocate()  │         └──────────┬───────────┘
-│  write()     │                    │ pointer map
-│  read()      │         ┌──────────▼───────────┐
-│  free()      │──gRPC──>│   Memory Nodes        │
-└──────────────┘         │   (Data Plane)        │
-                         │   1TB+ pooled RAM     │
-                         └──────────────────────┘
+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).
 ```
 
-**Control plane** (Coordinator): Routes allocation requests, maintains node registry.  
-**Data plane** (Memory Nodes): Direct gRPC streams for maximum throughput.  
-**Client**: Talks to nodes directly after allocation — Coordinator is never in the hot path.
+**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()`.**
+
+```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() ✅
+```
+
+→ [Full Memory Management Guide](https://github.com/anispy211/superbrainSdk/blob/main/DOCUMENTATION.md#memory-management--when-to-free)
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superbrain-distributed-sdk",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Premium High-Performance Distributed Memory SDK for AI Agents",
   "main": "index.js",
   "types": "index.d.ts",