superlocalmemory 2.5.1 → 2.6.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://varun369.github.io/SuperLocalMemoryV2/assets/branding/icon-512.png" alt="SuperLocalMemory V2" width="200"/>
+  <img src="https://superlocalmemory.com/assets/branding/icon-512.png" alt="SuperLocalMemory V2" width="200"/>
 </p>
 
 <h1 align="center">SuperLocalMemory V2</h1>
@@ -14,6 +14,10 @@
   <strong>Stop re-explaining your codebase every session. 100% local. Zero setup. Completely free.</strong>
 </p>
 
+<p align="center">
+  <a href="https://superlocalmemory.com"><img src="https://img.shields.io/badge/🌐_Website-superlocalmemory.com-ff6b35?style=for-the-badge" alt="Official Website"/></a>
+</p>
+
 <p align="center">
   <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.8+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.8+"/></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT License"/></a>
@@ -24,6 +28,7 @@
 </p>
 
 <p align="center">
+  <a href="https://superlocalmemory.com"><strong>superlocalmemory.com</strong></a> •
   <a href="#-quick-start">Quick Start</a> •
   <a href="#-why-superlocalemory">Why This?</a> •
   <a href="#-features">Features</a> •
@@ -40,24 +45,26 @@
 
 ---
 
-## NEW: v2.5 — "Your AI Memory Has a Heartbeat"
+## NEW: v2.6 — Security Hardening & Performance
+
+> **SuperLocalMemory is now production-hardened with trust enforcement, rate limiting, and accelerated graph building.**
 
-> **SuperLocalMemory is no longer passive storage — it's a real-time coordination layer.**
+| What's New in v2.6 | Why It Matters |
+|---------------------|----------------|
+| **Trust Enforcement** | Agents with trust below 0.3 are blocked from write/delete — Bayesian scoring now actively protects your memory. |
+| **Profile Isolation** | Memory profiles are fully sandboxed — no cross-profile data leakage. |
+| **Rate Limiting** | Protects against memory flooding and spam from misbehaving agents. |
+| **SSRF Protection** | Webhook dispatcher validates URLs to prevent server-side request forgery. |
+| **HNSW-Accelerated Graphs** | Knowledge graph edge building uses HNSW index for faster construction at scale. |
+| **Hybrid Search Engine** | Combined semantic + FTS5 + graph retrieval for maximum accuracy. |
 
-| What's New | Why It Matters |
-|------------|----------------|
-| **Real-Time Event Stream** | See every memory operation live in the dashboard — no refresh needed. SSE-powered, cross-process. |
-| **No More "Database Locked"** | WAL mode + serialized write queue. 50 concurrent agents writing? Zero errors. |
-| **Agent Tracking** | Know exactly which AI tool wrote what. Claude, Cursor, Windsurf, CLI — all tracked automatically. |
-| **Trust Scoring** | Bayesian trust signals detect spam, quick-deletes, and cross-agent validation. Silent in v2.5, enforced in v2.6. |
-| **Memory Provenance** | Every memory records who created it, via which protocol, with full derivation lineage. |
-| **Production-Grade Code** | 28 API endpoints across 8 modular route files. 13 modular JS files. 63 pytest tests. |
+**v2.5 highlights (included):** Real-time event stream, WAL-mode concurrent writes, agent tracking, memory provenance, 28 API endpoints.
 
 **Upgrade:** `npm install -g superlocalmemory@latest`
 
 **Dashboard:** `python3 ~/.claude-memory/ui_server.py` then open `http://localhost:8765`
 
-[Interactive Architecture Diagram](https://varun369.github.io/SuperLocalMemoryV2/architecture.html) | [Architecture Doc](docs/ARCHITECTURE-V2.5.md) | [Full Changelog](CHANGELOG.md)
+[Interactive Architecture Diagram](https://superlocalmemory.com/architecture.html) | [Architecture Doc](docs/ARCHITECTURE-V2.5.md) | [Full Changelog](CHANGELOG.md)
 
 ---
 
@@ -108,7 +115,7 @@ Or clone manually:
 git clone https://github.com/varun369/SuperLocalMemoryV2.git && cd SuperLocalMemoryV2 && ./install.sh
 ```
 
-Both methods auto-detect and configure **16+ IDEs and AI tools** — Cursor, VS Code/Copilot, Codex, Claude, Windsurf, Gemini CLI, JetBrains, and more.
+Both methods auto-detect and configure **17+ IDEs and AI tools** — Cursor, VS Code/Copilot, Codex, Claude, Windsurf, Gemini CLI, JetBrains, and more.
 
 ---
 
@@ -254,7 +261,7 @@ python ~/.claude-memory/ui_server.py
 | **Hierarchical Leiden** | Recursive community detection — clusters within clusters up to 3 levels. "Python" → "FastAPI" → "Auth patterns" |
 | **Community Summaries** | TF-IDF structured reports per cluster: key topics, projects, categories at a glance |
 | **MACLA Confidence** | Bayesian Beta-Binomial scoring (arXiv:2512.18950) — calibrated confidence, not raw frequency |
-| **Auto-Backup** | Configurable SQLite backups with retention policies, one-click restore from dashboard |
+| **Auto-Backup** | Configurable SQLite backups with retention policies, restore from any backup via CLI |
 | **Profile UI** | Create, switch, delete profiles from the web dashboard — full isolation per context |
 | **Profile Isolation** | All API endpoints (graph, clusters, patterns, timeline) scoped to active profile |
 
@@ -266,12 +273,12 @@ SuperLocalMemory V2.2.0 implements **hybrid search** combining multiple strategi
 
 ### Search Strategies
 
-| Strategy | Method | Best For | Speed |
-|----------|--------|----------|-------|
-| **Semantic Search** | TF-IDF vectors + cosine similarity | Conceptual queries ("authentication patterns") | 45ms |
-| **Full-Text Search** | SQLite FTS5 with ranking | Exact phrases ("JWT tokens expire") | 30ms |
-| **Graph-Enhanced** | Knowledge graph traversal | Related concepts ("show auth-related") | 60ms |
-| **Hybrid Mode** | All three combined | General queries | 80ms |
+| Strategy | Method | Best For |
+|----------|--------|----------|
+| **Semantic Search** | TF-IDF vectors + cosine similarity | Conceptual queries ("authentication patterns") |
+| **Full-Text Search** | SQLite FTS5 with ranking | Exact phrases ("JWT tokens expire") |
+| **Graph-Enhanced** | Knowledge graph traversal | Related concepts ("show auth-related") |
+| **Hybrid Mode** | All three combined | General queries (default) |
 
 ### Search Examples
 
@@ -293,52 +300,65 @@ slm recall "API design patterns"
 # Combines semantic + exact + graph for optimal results
 ```
 
-### Search Performance by Dataset Size
+### Measured Search Latency
 
-| Memories | Semantic | FTS5 | Graph | Hybrid |
-|----------|----------|------|-------|--------|
-| 100 | 35ms | 25ms | 50ms | 65ms |
-| 500 | 45ms | 30ms | 60ms | 80ms |
-| 1,000 | 55ms | 35ms | 70ms | 95ms |
-| 5,000 | 85ms | 50ms | 110ms | 150ms |
+| Database Size | Median | P95 | P99 |
+|---------------|--------|-----|-----|
+| 100 memories | **10.6ms** | 14.9ms | 15.8ms |
+| 500 memories | **65.2ms** | 101.7ms | 112.5ms |
+| 1,000 memories | **124.3ms** | 190.1ms | 219.5ms |
 
-**All search strategies remain sub-second even with 5,000+ memories.**
+For typical personal databases (under 500 memories), search returns faster than you blink. [Full benchmarks →](https://github.com/varun369/SuperLocalMemoryV2/wiki/Performance-Benchmarks)
 
 ---
 
-## ⚡ Performance
+## ⚡ Measured Performance
+
+All numbers measured on real hardware (Apple M4 Pro, 24GB RAM). No estimates — real benchmarks.
+
+### Search Speed
+
+| Database Size | Median Latency | P95 Latency |
+|---------------|----------------|-------------|
+| 100 memories | **10.6ms** | 14.9ms |
+| 500 memories | **65.2ms** | 101.7ms |
+| 1,000 memories | **124.3ms** | 190.1ms |
 
-### Benchmarks (v2.2.0)
+For typical personal use (under 500 memories), search results return faster than you blink.
 
-| Operation | Time | Comparison | Notes |
-|-----------|------|------------|-------|
-| **Add Memory** | < 10ms | - | Instant indexing |
-| **Search (Hybrid)** | 80ms | 3.3x faster than v1 | 500 memories |
-| **Graph Build** | < 2s | - | 100 memories |
-| **Pattern Learning** | < 2s | - | Incremental |
-| **Dashboard Load** | < 500ms | - | 1,000 memories |
-| **Timeline Render** | < 300ms | - | All memories |
+### Concurrent Writes — Zero Errors
 
-### Storage Efficiency
+| Scenario | Writes/sec | Errors |
+|----------|------------|--------|
+| 1 AI tool writing | **204/sec** | 0 |
+| 2 AI tools simultaneously | **220/sec** | 0 |
+| 5 AI tools simultaneously | **130/sec** | 0 |
+| 10 AI tools simultaneously | **25/sec** | 0 |
 
-| Tier | Description | Compression | Savings |
-|------|-------------|-------------|---------|
-| **Tier 1** | Active memories (0-30 days) | None | - |
-| **Tier 2** | Warm memories (30-90 days) | 60% | Progressive summarization |
-| **Tier 3** | Cold storage (90+ days) | 96% | JSON archival |
+WAL mode + serialized write queue = zero "database is locked" errors, ever.
 
-**Example:** 1,000 memories with mixed ages = ~15MB (vs 380MB uncompressed)
+### Storage
 
-### Scalability
+10,000 memories = **13.6 MB** on disk (~1.9 KB per memory). Your entire AI memory history takes less space than a photo.
 
-| Dataset Size | Search Time | Graph Build | RAM Usage |
-|--------------|-------------|-------------|-----------|
-| 100 memories | 35ms | 0.5s | < 30MB |
-| 500 memories | 45ms | 2s | < 50MB |
-| 1,000 memories | 55ms | 5s | < 80MB |
-| 5,000 memories | 85ms | 30s | < 150MB |
+### Trust Defense
 
-**Tested up to 10,000 memories** with linear scaling and no degradation.
+Bayesian trust scoring achieves **perfect separation** (trust gap = 1.0) between honest and malicious agents. Detects "sleeper" attacks with 74.7% trust drop. Zero false positives.
+
+### Graph Construction
+
+| Memories | Build Time |
+|----------|-----------|
+| 100 | 0.28s |
+| 1,000 | 10.6s |
+
+Leiden clustering discovers 6-7 natural topic communities automatically.
+
+> **Graph Scaling:** Knowledge graph features work best with up to 10,000 memories. For larger databases, the system uses intelligent sampling (most recent + highest importance memories) for graph construction. Core search and memory storage have no upper limit.
+
+> **LoCoMo benchmark results coming soon** — evaluation against the standardized [LoCoMo](https://snap-research.github.io/locomo/) long-conversation memory benchmark (Snap Research, ACL 2024).
+
+[Full benchmark details →](https://github.com/varun369/SuperLocalMemoryV2/wiki/Performance-Benchmarks)
 
 ---
 
@@ -470,7 +490,7 @@ Not another simple key-value store. SuperLocalMemory implements **cutting-edge m
 | **Completely Free** | Limited | Limited | Partial | ✅ | ✅ |
 
 **SuperLocalMemory V2 is the ONLY solution that:**
-- ✅ Works across 16+ IDEs and CLI tools
+- ✅ Works across 17+ IDEs and CLI tools
 - ✅ Remains 100% local (no cloud dependencies)
 - ✅ Completely free with unlimited memories
 
@@ -482,7 +502,7 @@ Not another simple key-value store. SuperLocalMemory implements **cutting-edge m
 
 ### Multi-Layer Memory Architecture
 
-**[View Interactive Architecture Diagram](https://varun369.github.io/SuperLocalMemoryV2/architecture.html)** — Click any layer for details, research references, and file paths.
+**[View Interactive Architecture Diagram](https://superlocalmemory.com/architecture.html)** — Click any layer for details, research references, and file paths.
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
@@ -496,7 +516,7 @@ Not another simple key-value store. SuperLocalMemory implements **cutting-edge m
 ├─────────────────────────────────────────────────────────────┤
 │  Layer 7: UNIVERSAL ACCESS                                  │
 │  MCP + Skills + CLI (works everywhere)                      │
-│  16+ IDEs with single database                              │
+│  17+ IDEs with single database                              │
 ├─────────────────────────────────────────────────────────────┤
 │  Layer 6: MCP INTEGRATION                                   │
 │  Model Context Protocol: 6 tools, 4 resources, 2 prompts    │
@@ -634,23 +654,18 @@ superlocalmemoryv2:reset hard --confirm                  # Nuclear option
 
 ---
 
-## 📊 Performance
-
-**SEO:** Performance benchmarks, memory system speed, search latency, visualization dashboard performance
+## 📊 Performance at a Glance
 
-| Metric | Result | Notes |
-|--------|--------|-------|
-| **Hybrid search** | **80ms** | Semantic + FTS5 + Graph combined |
-| **Semantic search** | **45ms** | 3.3x faster than v1 |
-| **FTS5 search** | **30ms** | Exact phrase matching |
-| **Graph build (100 memories)** | **< 2 seconds** | Leiden clustering |
-| **Pattern learning** | **< 2 seconds** | Incremental updates |
-| **Dashboard load** | **< 500ms** | 1,000 memories |
-| **Timeline render** | **< 300ms** | All memories visualized |
-| **Storage compression** | **60-96% reduction** | Progressive tiering |
-| **Memory overhead** | **< 50MB RAM** | Lightweight |
+| Metric | Measured Result |
+|--------|----------------|
+| **Search latency** | **10.6ms** median (100 memories) |
+| **Concurrent writes** | **220/sec** with 2 agents, zero errors |
+| **Storage** | **1.9 KB** per memory at scale (13.6 MB for 10K) |
+| **Trust defense** | **1.0** trust gap (perfect separation) |
+| **Graph build** | **0.28s** for 100 memories |
+| **Search quality** | **MRR 0.90** (first result correct 9/10 times) |
 
-**Tested up to 10,000 memories** with sub-second search times and linear scaling.
+[Full benchmark details →](https://github.com/varun369/SuperLocalMemoryV2/wiki/Performance-Benchmarks)
 
 ---
 

package/api_server.py

@@ -51,6 +51,53 @@ app = FastAPI(
 UI_DIR.mkdir(exist_ok=True)
 app.mount("/static", StaticFiles(directory=str(UI_DIR)), name="static")
 
+# Rate limiting (v2.6)
+try:
+    from rate_limiter import write_limiter, read_limiter
+
+    @app.middleware("http")
+    async def rate_limit_middleware(request, call_next):
+        client_ip = request.client.host if request.client else "unknown"
+
+        # Determine if this is a write or read endpoint
+        is_write = request.method in ("POST", "PUT", "DELETE", "PATCH")
+        limiter = write_limiter if is_write else read_limiter
+
+        allowed, remaining = limiter.is_allowed(client_ip)
+        if not allowed:
+            from fastapi.responses import JSONResponse
+            return JSONResponse(
+                status_code=429,
+                content={"error": "Too many requests. Please slow down."},
+                headers={"Retry-After": str(limiter.window)}
+            )
+
+        response = await call_next(request)
+        response.headers["X-RateLimit-Remaining"] = str(remaining)
+        return response
+
+except ImportError:
+    pass  # Rate limiter not available — continue without it
+
+# Optional API key authentication (v2.6)
+try:
+    from auth_middleware import check_api_key
+
+    @app.middleware("http")
+    async def auth_middleware(request, call_next):
+        is_write = request.method in ("POST", "PUT", "DELETE", "PATCH")
+        headers = dict(request.headers)
+        if not check_api_key(headers, is_write=is_write):
+            from fastapi.responses import JSONResponse
+            return JSONResponse(
+                status_code=401,
+                content={"error": "Invalid or missing API key. Set X-SLM-API-Key header."}
+            )
+        response = await call_next(request)
+        return response
+except ImportError:
+    pass  # Auth middleware not available
+
 
 # ============================================================================
 # Request/Response Models

package/docs/architecture-diagram.drawio

@@ -67,7 +67,7 @@
         </mxCell>
 
         <!-- Layer 10: A2A Agent Collaboration -->
-        <mxCell id="L10" value="&lt;b&gt;Layer 10: A2A Agent Collaboration&lt;/b&gt;&lt;br&gt;&lt;font style=&#39;font-size:10px;color:#ECFDF5;&#39;&gt;src/a2a_server.py (PLANNED v2.6) &amp;mdash; Agent-to-Agent Protocol (Google/Linux Foundation)&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#10B981;fontColor=#FFFFFF;strokeColor=#059669;arcSize=8;fontSize=12;align=center;verticalAlign=middle;shadow=1;dashed=1;dashPattern=8 4;" vertex="1" parent="1">
+        <mxCell id="L10" value="&lt;b&gt;Layer 10: A2A Agent Collaboration&lt;/b&gt;&lt;br&gt;&lt;font style=&#39;font-size:10px;color:#ECFDF5;&#39;&gt;src/a2a_server.py (PLANNED v2.7) &amp;mdash; Agent-to-Agent Protocol (Google/Linux Foundation)&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#10B981;fontColor=#FFFFFF;strokeColor=#059669;arcSize=8;fontSize=12;align=center;verticalAlign=middle;shadow=1;dashed=1;dashPattern=8 4;" vertex="1" parent="1">
           <mxGeometry x="340" y="165" width="520" height="55" as="geometry" />
         </mxCell>
 
@@ -181,7 +181,7 @@
         </mxCell>
 
         <!-- A2A Path Label -->
-        <mxCell id="a2a_label" value="&lt;font color=&#39;#6EE7B7&#39; style=&#39;font-size:14px;font-weight:bold;&#39;&gt;A2A Protocol&lt;/font&gt;&lt;br&gt;&lt;font color=&#39;#34D399&#39; style=&#39;font-size:11px;&#39;&gt;Agent &amp;harr; Agent&lt;/font&gt;&lt;br&gt;&lt;font color=&#39;#FBBF24&#39; style=&#39;font-size:10px;font-weight:bold;&#39;&gt;PLANNED v2.6&lt;/font&gt;" style="text;html=1;align=center;verticalAlign=top;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;" vertex="1" parent="1">
+        <mxCell id="a2a_label" value="&lt;font color=&#39;#6EE7B7&#39; style=&#39;font-size:14px;font-weight:bold;&#39;&gt;A2A Protocol&lt;/font&gt;&lt;br&gt;&lt;font color=&#39;#34D399&#39; style=&#39;font-size:11px;&#39;&gt;Agent &amp;harr; Agent&lt;/font&gt;&lt;br&gt;&lt;font color=&#39;#FBBF24&#39; style=&#39;font-size:10px;font-weight:bold;&#39;&gt;PLANNED v2.7&lt;/font&gt;" style="text;html=1;align=center;verticalAlign=top;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;" vertex="1" parent="1">
           <mxGeometry x="960" y="172" width="140" height="60" as="geometry" />
         </mxCell>
 
@@ -316,11 +316,11 @@
           <mxGeometry x="105" y="600" width="110" height="25" as="geometry" />
         </mxCell>
 
-        <!-- Legend: Planned v2.6 -->
+        <!-- Legend: Planned v2.7 -->
         <mxCell id="legend_planned_box" value="" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#10B981;strokeColor=#059669;arcSize=30;dashed=1;dashPattern=4 2;" vertex="1" parent="1">
           <mxGeometry x="85" y="628" width="14" height="14" as="geometry" />
         </mxCell>
-        <mxCell id="legend_planned_text" value="&lt;font color=&#39;#D1D5DB&#39; style=&#39;font-size:10px;&#39;&gt;Planned v2.6 (A2A)&lt;/font&gt;" style="text;html=1;align=left;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;" vertex="1" parent="1">
+        <mxCell id="legend_planned_text" value="&lt;font color=&#39;#D1D5DB&#39; style=&#39;font-size:10px;&#39;&gt;Planned v2.7 (A2A)&lt;/font&gt;" style="text;html=1;align=left;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;" vertex="1" parent="1">
           <mxGeometry x="105" y="623" width="120" height="25" as="geometry" />
         </mxCell>