npm - superlocalmemory - Versions diffs - 3.0.14 → 3.0.15 - Mend

superlocalmemory 3.0.14 → 3.0.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md +193 -191
package/package.json +1 -1
package/pyproject.toml +1 -1
package/src/superlocalmemory/core/embeddings.py +57 -2
package/src/superlocalmemory.egg-info/PKG-INFO +194 -192

package/README.md CHANGED Viewed

@@ -3,57 +3,104 @@
 </p>
 <h1 align="center">SuperLocalMemory V3</h1>
-<p align="center"><strong>Information-Geometric Agent Memory with Mathematical Guarantees</strong></p>
+<p align="center"><strong>The first local-only AI memory to break 74% retrieval on LoCoMo.<br/>No cloud. No APIs. No data leaves your machine.</strong></p>
 <p align="center">
-  The first agent memory system with mathematically grounded retrieval, lifecycle management, and consistency verification. Four-channel hybrid retrieval. Three operating modes. EU AI Act compliant.
+  <code>+16pp vs Mem0 (zero cloud)</code> &nbsp;·&nbsp; <code>85% Open-Domain (best of any system)</code> &nbsp;·&nbsp; <code>EU AI Act Ready</code>
 </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="Website"/></a>
-  <a href="https://arxiv.org/abs/2603.14588"><img src="https://img.shields.io/badge/arXiv-2603.14588-b31b1b?style=for-the-badge&logo=arxiv&logoColor=white" alt="arXiv V3 Paper"/></a>
-  <a href="https://zenodo.org/records/19038659"><img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.19038659-blue?style=for-the-badge&logo=doi&logoColor=white" alt="V3 DOI"/></a>
+  <a href="https://arxiv.org/abs/2603.14588"><img src="https://img.shields.io/badge/arXiv-2603.14588-b31b1b?style=for-the-badge&logo=arxiv&logoColor=white" alt="arXiv Paper"/></a>
+  <a href="https://pypi.org/project/superlocalmemory/"><img src="https://img.shields.io/pypi/v/superlocalmemory?style=for-the-badge&logo=pypi&logoColor=white" alt="PyPI"/></a>
+  <a href="https://www.npmjs.com/package/superlocalmemory"><img src="https://img.shields.io/npm/v/superlocalmemory?style=for-the-badge&logo=npm&logoColor=white" alt="npm"/></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT License"/></a>
+  <a href="#eu-ai-act-compliance"><img src="https://img.shields.io/badge/EU_AI_Act-Compliant-brightgreen?style=for-the-badge" alt="EU AI Act"/></a>
+  <a href="https://superlocalmemory.com"><img src="https://img.shields.io/badge/Web-superlocalmemory.com-ff6b35?style=for-the-badge" alt="Website"/></a>
 </p>
-<p align="center">
-  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+"/></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT License"/></a>
-  <a href="#three-operating-modes"><img src="https://img.shields.io/badge/EU_AI_Act-Compliant-brightgreen?style=flat-square" alt="EU AI Act"/></a>
-  <a href="#"><img src="https://img.shields.io/badge/tests-1400+-brightgreen?style=flat-square" alt="1400+ Tests"/></a>
-  <a href="#"><img src="https://img.shields.io/badge/platform-Mac_|_Linux_|_Windows-blue?style=flat-square" alt="Cross Platform"/></a>
-  <a href="https://github.com/qualixar/superlocalmemory/wiki"><img src="https://img.shields.io/badge/Wiki-Documentation-blue?style=flat-square" alt="Wiki"/></a>
-</p>
+---
+## Why SuperLocalMemory?
+Every major AI memory system — Mem0, Zep, Letta, EverMemOS — sends your data to cloud LLMs for core operations. That means latency on every query, cost on every interaction, and after **August 2, 2026**, a compliance problem under the EU AI Act.
+SuperLocalMemory V3 takes a different approach: **mathematics instead of cloud compute.** Three techniques from differential geometry, algebraic topology, and stochastic analysis replace the work that other systems need LLMs to do — similarity scoring, contradiction detection, and lifecycle management. The result is an agent memory that runs entirely on your machine, on CPU, with no API keys, and still outperforms funded alternatives.
+**The numbers** (evaluated on [LoCoMo](https://arxiv.org/abs/2402.09714), the standard long-conversation memory benchmark):
+| System | Score | Cloud Required | Open Source | Funding |
+|:-------|:-----:|:--------------:|:-----------:|:-------:|
+| EverMemOS | 92.3% | Yes | No | — |
+| Hindsight | 89.6% | Yes | No | — |
+| **SLM V3 Mode C** | **87.7%** | Optional | **Yes (MIT)** | $0 |
+| Zep v3 | 85.2% | Yes | Deprecated | $35M |
+| **SLM V3 Mode A** | **74.8%** | **No** | **Yes (MIT)** | $0 |
+| Mem0 | 64.2% | Yes | Partial | $24M |
+Mode A scores **74.8% with zero cloud dependency** — outperforming Mem0 by 16 percentage points without a single API call. On open-domain questions, Mode A scores **85.0% — the highest of any system in the evaluation**, including cloud-powered ones. Mode C reaches **87.7%**, matching enterprise cloud systems.
+Mathematical layers contribute **+12.7 percentage points** on average across 6 conversations (n=832 questions), with up to **+19.9pp on the most challenging dialogues**. This isn't more compute — it's better math.
+> **Upgrading from V2 (2.8.6)?** V3 is a complete architectural reinvention — new mathematical engine, new retrieval pipeline, new storage schema. Your existing data is preserved but requires migration. After installing V3, run `slm migrate` to upgrade your data. Read the [Migration Guide](https://github.com/qualixar/superlocalmemory/wiki/Migration-from-V2) before upgrading. Backup is created automatically.
 ---
-## What is SuperLocalMemory?
+## Quick Start
-SuperLocalMemory gives AI assistants persistent, structured memory that survives across sessions. Unlike simple vector stores, V3 uses **information geometry** to provide mathematically grounded retrieval, automatic contradiction detection, and self-organizing memory lifecycle management.
+### Install via npm (recommended)
-**Works with:** Claude, Cursor, Windsurf, VS Code Copilot, Continue, Cody, ChatGPT Desktop, Gemini CLI, JetBrains, Zed, and 17+ AI tools via MCP.
+```bash
+npm install -g superlocalmemory
+slm setup     # Choose mode (A/B/C)
+slm warmup    # Pre-download embedding model (~500MB, optional)
+```
+### Install via pip
+```bash
+pip install superlocalmemory
+```
-> **Upgrading from V2 (2.8.6)?** V3 is a complete architectural reinvention — new mathematical engine, new retrieval pipeline, new storage schema. Your existing data is preserved but requires migration. After installing V3, run `slm migrate` to upgrade your data. Read the [Migration Guide](docs/migration-from-v2.md) before upgrading. Backup is created automatically.
+### First Use
-### Key Results
+```bash
+slm remember "Alice works at Google as a Staff Engineer"
+slm recall "What does Alice do?"
+slm status
+```
-| Metric | Score | Context |
-|:-------|:-----:|:--------|
-| LoCoMo (Mode C, full power) | **87.7%** | On conv-30, 81 scored questions |
-| LoCoMo (Mode A, zero-LLM) | **62.3%** | Highest zero-LLM score. No cloud dependency. |
-| Math layer improvement | **+12.7pp** | Average gain from mathematical foundations |
-| Multi-hop improvement | **+12pp** | 50% vs 38% (math on vs off) |
+### MCP Integration (Claude, Cursor, Windsurf, VS Code, etc.)
+```json
+{
+  "mcpServers": {
+    "superlocalmemory": {
+      "command": "slm",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+24 MCP tools available. Works with Claude Code, Cursor, Windsurf, VS Code Copilot, Continue, Cody, ChatGPT Desktop, Gemini CLI, JetBrains, Zed, and 17+ AI tools.
 ---
 ## Three Operating Modes
-| Mode | What | LLM Required? | EU AI Act | Best For |
-|:----:|:-----|:-------------:|:---------:|:---------|
-| **A** | Local Guardian | No | Compliant | Privacy-first, air-gapped, enterprise |
-| **B** | Smart Local | Local only (Ollama) | Compliant | Enhanced quality, data stays local |
-| **C** | Full Power | Cloud (optional) | Partial | Maximum accuracy, research |
+| Mode | What | Cloud? | EU AI Act | Best For |
+|:----:|:-----|:------:|:---------:|:---------|
+| **A** | Local Guardian | **None** | **Compliant** | Privacy-first, air-gapped, enterprise |
+| **B** | Smart Local | Local only (Ollama) | Compliant | Better answers, data stays local |
+| **C** | Full Power | Cloud LLM | Partial | Maximum accuracy, research |
+```bash
+slm mode a   # Zero-cloud (default)
+slm mode b   # Local Ollama
+slm mode c   # Cloud LLM
+```
-**Mode A** is the only agent memory that operates with **zero cloud dependency** while achieving competitive retrieval accuracy. All data stays on your device. No API keys required.
+**Mode A** is the only agent memory that operates with **zero cloud dependency** while achieving competitive retrieval accuracy on a standard benchmark. All data stays on your device. No API keys. No GPU. Runs on 2 vCPUs + 4GB RAM.
 ---
@@ -61,8 +108,8 @@ SuperLocalMemory gives AI assistants persistent, structured memory that survives
 ```
 Query  ──►  Strategy Classifier  ──►  4 Parallel Channels:
-                                       ├── Semantic (Fisher-Rao graduated similarity)
-                                       ├── BM25 (keyword matching, k1=1.2, b=0.75)
+                                       ├── Semantic (Fisher-Rao geodesic distance)
+                                       ├── BM25 (keyword matching)
                                        ├── Entity Graph (spreading activation, 3 hops)
                                        └── Temporal (date-aware retrieval)
                                                     │
@@ -75,104 +122,79 @@ Query  ──►  Strategy Classifier  ──►  4 Parallel Channels:
                                        ◄── Top-K Results with channel scores
 ```
-### Mathematical Foundations (Novel Contributions)
-1. **Fisher-Rao Retrieval Metric** — Similarity scoring derived from the Fisher information structure of diagonal Gaussian families. Graduated ramp from cosine to Fisher-information-weighted scoring over the first 10 accesses per memory.
-2. **Sheaf Cohomology for Consistency** — Algebraic topology detects contradictions between facts by computing coboundary norms on the knowledge graph. Non-trivial restriction maps amplify disagreements along discriminative subspaces.
-3. **Riemannian Langevin Lifecycle** — Memory positions evolve on the Poincare ball via a discretized Langevin SDE. Frequently accessed memories stay near the origin (ACTIVE); neglected memories diffuse toward the boundary (ARCHIVED). The potential is modulated by access frequency, age, and importance.
----
-## Prerequisites
+### Mathematical Foundations
-| Requirement | Version | Why |
-|:-----------|:--------|:----|
-| **Node.js** | 14+ | npm package manager |
-| **Python** | 3.11+ | V3 engine runtime |
-| **pip** | Latest | Python dependency installer |
+Three novel contributions replace cloud LLM dependency with mathematical guarantees:
-> All Python dependencies are installed automatically during `npm install`. You don't need to run pip manually. If any dependency fails, the installer shows clear instructions.
+1. **Fisher-Rao Retrieval Metric** — Similarity scoring derived from the Fisher information structure of diagonal Gaussian families. Graduated ramp from cosine to geodesic distance over the first 10 accesses. The first application of information geometry to agent memory retrieval.
-### What Gets Installed Automatically
+2. **Sheaf Cohomology for Consistency** — Algebraic topology detects contradictions by computing coboundary norms on the knowledge graph. The first algebraic guarantee for contradiction detection in agent memory.
-| Component | Size | When |
-|:----------|:-----|:-----|
-| Core math libraries (numpy, scipy, networkx) | ~50MB | During `npm install` |
-| Search engine (sentence-transformers, einops, torch) | ~200MB | During `npm install` |
-| Embedding model (nomic-ai/nomic-embed-text-v1.5) | ~500MB | On first use OR `slm warmup` |
+3. **Riemannian Langevin Lifecycle** — Memory positions evolve on the Poincare ball via discretized Langevin SDE. Frequently accessed memories stay active; neglected memories self-archive. No hardcoded thresholds.
-**If any dependency fails during install**, the installer prints the exact `pip install` command to fix it. BM25 keyword search works even without embeddings — you're never fully blocked.
+These three layers collectively yield **+12.7pp average improvement** over the engineering-only baseline, with the Fisher metric alone contributing **+10.8pp** on the hardest conversations.
 ---
-## Quick Start
+## Benchmarks
-### Install via npm (recommended — one command, everything included)
+Evaluated on [LoCoMo](https://arxiv.org/abs/2402.09714) — 10 multi-session conversations, 1,986 total questions, 4 scored categories.
-```bash
-npm install -g superlocalmemory
-```
+### Mode A (Zero-Cloud, 10 Conversations, 1,276 Questions)
-This single command:
-- Installs the V3 engine and CLI
-- Auto-installs all Python dependencies (numpy, scipy, networkx, sentence-transformers, einops, torch, etc.)
-- Creates the data directory at `~/.superlocalmemory/`
-- Detects and guides V2 migration if applicable
+| Category | Score | vs. Mem0 (64.2%) |
+|:---------|:-----:|:-----------------:|
+| Single-Hop | 72.0% | +3.0pp |
+| Multi-Hop | 70.3% | +8.6pp |
+| Temporal | 80.0% | +21.7pp |
+| **Open-Domain** | **85.0%** | **+35.0pp** |
+| **Aggregate** | **74.8%** | **+10.6pp** |
-Then configure and pre-download the embedding model:
-```bash
-slm setup     # Choose mode, configure provider
-slm warmup    # Pre-download embedding model (~500MB, optional)
-```
+Mode A achieves **85.0% on open-domain questions — the highest of any system in the evaluation**, including cloud-powered ones.
-> **First time?** If you skip `slm warmup`, the model downloads automatically on first `slm remember` or `slm recall`. Either way works.
+### Math Layer Impact (6 Conversations, n=832)
-### Install via pip
+| Conversation | With Math | Without | Delta |
+|:-------------|:---------:|:-------:|:-----:|
+| Easiest | 78.5% | 71.2% | +7.3pp |
+| Hardest | 64.2% | 44.3% | **+19.9pp** |
+| **Average** | **71.7%** | **58.9%** | **+12.7pp** |
-```bash
-pip install superlocalmemory
-# or with all features:
-pip install "superlocalmemory[full]"
-```
+Mathematical layers help most where heuristic methods struggle — the harder the conversation, the bigger the improvement.
-### First Use
+### Ablation (What Each Component Contributes)
-```bash
-# Store a memory
-slm remember "Alice works at Google as a Staff Engineer"
+| Removed | Impact |
+|:--------|:------:|
+| Cross-encoder reranking | **-30.7pp** |
+| Fisher-Rao metric | **-10.8pp** |
+| All math layers | **-7.6pp** |
+| BM25 channel | **-6.5pp** |
+| Sheaf consistency | -1.7pp |
+| Entity graph | -1.0pp |
-# Recall
-slm recall "What does Alice do?"
+Full ablation details in the [Wiki](https://github.com/qualixar/superlocalmemory/wiki/Benchmarks).
-# Check status
-slm status
+---
-# Switch modes
-slm mode a   # Zero-LLM (default)
-slm mode b   # Local Ollama
-slm mode c   # Full power
-```
+## EU AI Act Compliance
-### MCP Integration (Claude, Cursor, etc.)
+The EU AI Act (Regulation 2024/1689) takes full effect **August 2, 2026**. Every AI memory system that sends personal data to cloud LLMs for core operations has a compliance question to answer.
-Add to your IDE's MCP config:
+| Requirement | Mode A | Mode B | Mode C |
+|:------------|:------:|:------:|:------:|
+| Data sovereignty (Art. 10) | **Pass** | **Pass** | Requires DPA |
+| Right to erasure (GDPR Art. 17) | **Pass** | **Pass** | **Pass** |
+| Transparency (Art. 13) | **Pass** | **Pass** | **Pass** |
+| No network calls during memory ops | **Yes** | **Yes** | No |
-```json
-{
-  "mcpServers": {
-    "superlocalmemory": {
-      "command": "slm",
-      "args": ["mcp"]
-    }
-  }
-}
-```
+To the best of our knowledge, **no existing agent memory system addresses EU AI Act compliance**. Modes A and B pass all checks by architectural design — no personal data leaves the device during any memory operation.
-24 MCP tools available: `remember`, `recall`, `search`, `fetch`, `list_recent`, `get_status`, `build_graph`, `switch_profile`, `health`, `consistency_check`, `recall_trace`, and more.
+Built-in compliance tools: GDPR Article 15/17 export + complete erasure, tamper-proof SHA-256 audit chain, data provenance tracking, ABAC policy enforcement.
+---
-### Web Dashboard (17 tabs)
+## Web Dashboard
 ```bash
 slm dashboard    # Opens at http://localhost:8765
@@ -193,82 +215,58 @@ slm dashboard    # Opens at http://localhost:8765
 </p>
 </details>
-The V3 dashboard provides real-time visibility into your memory system:
-- **Dashboard** — Mode switcher, health score, quick store/recall
-- **Recall Lab** — Search with per-channel score breakdown (Semantic, BM25, Entity, Temporal)
-- **Knowledge Graph** — Interactive entity relationship visualization
-- **Memories** — Browse, search, and manage stored memories
-- **Trust Dashboard** — Bayesian trust scores per agent with Beta distribution visualization
-- **Math Health** — Fisher-Rao confidence, Sheaf consistency, Langevin lifecycle state
-- **Compliance** — GDPR export/erasure, EU AI Act status, audit trail
-- **Learning** — Adaptive ranking progress, behavioral patterns, outcome tracking
-- **IDE Connections** — Connected AI tools status and configuration
-- **Settings** — Mode, provider, auto-capture/recall configuration
-> The dashboard runs locally at `http://localhost:8765`. No data leaves your machine.
+17 tabs: Dashboard, Recall Lab, Knowledge Graph, Memories, Trust Scores, Math Health, Compliance, Learning, IDE Connections, Settings, and more. Runs locally — no data leaves your machine.
 ---
-## V3 Engine Features
+## Features
-### Retrieval (4-Channel Hybrid)
-- Semantic similarity with Fisher-Rao information geometry
-- BM25 keyword matching (persisted tokens, survives restart)
-- Entity graph with spreading activation (3-hop, decay=0.7)
-- Temporal date-aware retrieval with interval support
-- RRF fusion (k=60) + cross-encoder reranking
+### Retrieval
+- 4-channel hybrid: Semantic (Fisher-Rao) + BM25 + Entity Graph + Temporal
+- RRF fusion + cross-encoder reranking
+- Agentic sufficiency verification (auto-retry on weak results)
+- Adaptive ranking with LightGBM (learns from usage)
 ### Intelligence
-- 11-step ingestion pipeline (entity resolution, fact extraction, emotional tagging, scene building, sheaf consistency)
-- Adaptive learning with LightGBM-based ranking (3-phase bootstrap)
-- Behavioral pattern detection (query habits, entity preferences, active hours)
-- Outcome tracking for retrieval feedback loops
+- 11-step ingestion pipeline (entity resolution, fact extraction, emotional tagging, scene building)
+- Automatic contradiction detection via sheaf cohomology
+- Self-organizing memory lifecycle (no hardcoded thresholds)
+- Behavioral pattern detection and outcome tracking
-### Trust & Compliance
-- Bayesian Beta distribution trust scoring (per-agent, per-fact)
+### Trust & Security
+- Bayesian Beta-distribution trust scoring (per-agent, per-fact)
 - Trust gates (block low-trust agents from writing/deleting)
 - ABAC (Attribute-Based Access Control) with DB-persisted policies
-- GDPR Article 15/17 compliance (full export + complete erasure)
-- EU AI Act data sovereignty (Mode A: zero cloud, data stays local)
 - Tamper-proof hash-chain audit trail (SHA-256 linked entries)
-- Data provenance tracking (who created what, when, from where)
 ### Infrastructure
-- 17-tab web dashboard (trust visualization, math health, recall lab)
-- 17+ IDE integrations with pre-built configs
-- Profile isolation (16+ independent memory spaces)
-- V2 to V3 migration tool (zero data loss, rollback support)
-- Auto-capture and auto-recall hooks for Claude Code
+- 17-tab web dashboard with real-time visualization
+- 17+ IDE integrations (Claude, Cursor, Windsurf, VS Code, JetBrains, Zed, etc.)
+- 24 MCP tools + 6 MCP resources
+- Profile isolation (independent memory spaces)
+- 1400+ tests, MIT license, cross-platform (Mac/Linux/Windows)
+- CPU-only — no GPU required
 ---
-## Benchmarks
-Evaluated on the [LoCoMo benchmark](https://arxiv.org/abs/2402.09714) (Long Conversation Memory):
-### Mode A Ablation (conv-30, 81 questions, zero-LLM)
-| Configuration | Micro Avg | Multi-Hop | Open Domain |
-|:-------------|:---------:|:---------:|:-----------:|
-| Full (all layers) | **62.3%** | **50%** | **78%** |
-| Math layers off | 59.3% | 38% | 70% |
-| Entity channel off | 56.8% | 38% | 73% |
-| BM25 channel off | 53.2% | 23% | 71% |
-| Cross-encoder off | 31.8% | 17% | — |
-### Competitive Landscape
-| System | Score | LLM Required | Open Source | EU AI Act |
-|:-------|:-----:|:------------:|:-----------:|:---------:|
-| EverMemOS | 92.3% | Yes | No | No |
-| MemMachine | 91.7% | Yes | No | No |
-| Hindsight | 89.6% | Yes | No | No |
-| **SLM V3 Mode C** | **87.7%** | Optional | **Yes** | Partial |
-| **SLM V3 Mode A** | **62.3%** | **No** | **Yes** | **Yes** |
-| Mem0 ($24M) | 34.2% F1 | Yes | Partial | No |
-*SLM V3 is the only system offering a fully local mode with mathematical guarantees and EU AI Act compliance.*
+## CLI Reference
+| Command | What It Does |
+|:--------|:-------------|
+| `slm remember "..."` | Store a memory |
+| `slm recall "..."` | Search memories |
+| `slm forget "..."` | Delete matching memories |
+| `slm trace "..."` | Recall with per-channel score breakdown |
+| `slm status` | System status |
+| `slm health` | Math layer health (Fisher, Sheaf, Langevin) |
+| `slm mode a/b/c` | Switch operating mode |
+| `slm setup` | Interactive first-time wizard |
+| `slm warmup` | Pre-download embedding model |
+| `slm migrate` | V2 to V3 migration |
+| `slm dashboard` | Launch web dashboard |
+| `slm mcp` | Start MCP server (for IDE integration) |
+| `slm connect` | Configure IDE integrations |
+| `slm profile list/create/switch` | Profile management |
 ---
@@ -277,43 +275,47 @@ Evaluated on the [LoCoMo benchmark](https://arxiv.org/abs/2402.09714) (Long Conv
 ### V3: Information-Geometric Foundations
 > **SuperLocalMemory V3: Information-Geometric Foundations for Zero-LLM Enterprise Agent Memory**
 > Varun Pratap Bhardwaj (2026)
-> [arXiv:2603.14588](https://arxiv.org/abs/2603.14588) | [Zenodo DOI: 10.5281/zenodo.19038659](https://zenodo.org/records/19038659)
+> [arXiv:2603.14588](https://arxiv.org/abs/2603.14588) · [Zenodo DOI: 10.5281/zenodo.19038659](https://zenodo.org/records/19038659)
 ### V2: Architecture & Engineering
 > **SuperLocalMemory: A Structured Local Memory Architecture for Persistent AI Agent Context**
 > Varun Pratap Bhardwaj (2026)
-> [arXiv:2603.02240](https://arxiv.org/abs/2603.02240) | [Zenodo DOI: 10.5281/zenodo.18709670](https://zenodo.org/records/18709670)
+> [arXiv:2603.02240](https://arxiv.org/abs/2603.02240) · [Zenodo DOI: 10.5281/zenodo.18709670](https://zenodo.org/records/18709670)
+### Cite This Work
+```bibtex
+@article{bhardwaj2026slmv3,
+  title={Information-Geometric Foundations for Zero-LLM Enterprise Agent Memory},
+  author={Bhardwaj, Varun Pratap},
+  journal={arXiv preprint arXiv:2603.14588},
+  year={2026},
+  url={https://arxiv.org/abs/2603.14588}
+}
+```
 ---
-## Project Structure
+## Prerequisites
-```
-superlocalmemory/
-├── src/superlocalmemory/     # Python package (17 sub-packages)
-│   ├── core/                 # Engine, config, modes, profiles
-│   ├── retrieval/            # 4-channel retrieval + fusion + reranking
-│   ├── math/                 # Fisher-Rao, Sheaf, Langevin
-│   ├── encoding/             # 11-step ingestion pipeline
-│   ├── storage/              # SQLite with WAL, FTS5, migrations
-│   ├── trust/                # Bayesian scoring, gates, provenance
-│   ├── compliance/           # GDPR, EU AI Act, ABAC, audit chain
-│   ├── learning/             # Adaptive ranking, behavioral patterns
-│   ├── mcp/                  # MCP server (24 tools, 6 resources)
-│   ├── cli/                  # CLI with setup wizard
-│   └── server/               # Dashboard API + UI server
-├── tests/                    # 1400+ tests
-├── ui/                       # 17-tab web dashboard
-├── ide/                      # IDE configs for 17+ tools
-├── docs/                     # Documentation
-└── pyproject.toml            # Modern Python packaging
-```
+| Requirement | Version | Why |
+|:-----------|:--------|:----|
+| **Node.js** | 14+ | npm package manager |
+| **Python** | 3.11+ | V3 engine runtime |
+All Python dependencies install automatically during `npm install`. If anything fails, the installer shows exact fix commands. BM25 keyword search works even without embeddings — you're never fully blocked.
+| Component | Size | When |
+|:----------|:-----|:-----|
+| Core libraries (numpy, scipy, networkx) | ~50MB | During install |
+| Search engine (sentence-transformers, torch) | ~200MB | During install |
+| Embedding model (nomic-embed-text-v1.5, 768d) | ~500MB | First use or `slm warmup` |
 ---
 ## Contributing
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. [Wiki](https://github.com/qualixar/superlocalmemory/wiki) for detailed documentation.
 ## License
@@ -321,7 +323,7 @@ MIT License. See [LICENSE](LICENSE).
 ## Attribution
-Part of [Qualixar](https://qualixar.com) | Author: [Varun Pratap Bhardwaj](https://varunpratap.com)
+Part of [Qualixar](https://qualixar.com) · Author: [Varun Pratap Bhardwaj](https://varunpratap.com)
 ---

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.0.14",
+  "version": "3.0.15",
   "description": "Information-geometric agent memory with mathematical guarantees. 4-channel retrieval, Fisher-Rao similarity, zero-LLM mode, EU AI Act compliant. Works with Claude, Cursor, Windsurf, and 17+ AI tools.",
   "keywords": [
     "ai-memory",

package/pyproject.toml CHANGED Viewed

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "3.0.14"
+version = "3.0.15"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "MIT"}

package/src/superlocalmemory/core/embeddings.py CHANGED Viewed

@@ -8,16 +8,29 @@ Thread-safe, dimension-validated embedding with Fisher variance computation.
 Supports local (768-dim nomic) and cloud (3072-dim) models with EXPLICIT errors
 on dimension mismatch — NEVER silently falls back to a different dimension.
+Memory management: Forces CPU-only inference to prevent GPU memory accumulation.
+Auto-unloads model after idle timeout to keep long-running MCP servers lean.
 Part of Qualixar | Author: Varun Pratap Bhardwaj
 """
 from __future__ import annotations
 import logging
+import os
 import threading
 import time
 from typing import TYPE_CHECKING
+# Force CPU before any torch/sentence-transformers import.
+# On Apple Silicon, PyTorch defaults to Metal (MPS) which allocates 4-6 GB
+# of GPU shader buffers that grow over time and never get released.
+# On Windows/Linux with CUDA, similar GPU memory issues occur.
+# CPU-only keeps footprint under 1 GB (vs 6+ GB with GPU).
+os.environ.setdefault("CUDA_VISIBLE_DEVICES", "")
+os.environ.setdefault("PYTORCH_MPS_HIGH_WATERMARK_RATIO", "0.0")
+os.environ.setdefault("PYTORCH_ENABLE_MPS_FALLBACK", "1")
 import numpy as np
 if TYPE_CHECKING:
@@ -44,11 +57,16 @@ class DimensionMismatchError(RuntimeError):
     """
+_IDLE_TIMEOUT_SECONDS = 300  # 5 minutes — unload model after idle
 class EmbeddingService:
     """Thread-safe embedding service with strict dimension validation.
     Lazy-loads the underlying model on first embed call.
     Validates every output dimension against the configured expectation.
+    Auto-unloads after 5 minutes idle to keep MCP server memory low.
+    Forces CPU-only inference to prevent GPU memory accumulation.
     """
     def __init__(self, config: EmbeddingConfig) -> None:
@@ -57,6 +75,8 @@ class EmbeddingService:
         self._lock = threading.Lock()
         self._loaded = False
         self._available = True  # Set False if model can't load
+        self._last_used: float = 0.0
+        self._idle_timer: threading.Timer | None = None
     @property
     def is_available(self) -> bool:
@@ -65,6 +85,32 @@ class EmbeddingService:
             self._ensure_loaded()
         return self._available and self._model is not None
+    def unload(self) -> None:
+        """Explicitly unload the model to free memory.
+        Called automatically after idle timeout, or manually for cleanup.
+        The model will lazy-reload on next embed call.
+        """
+        with self._lock:
+            if self._model is not None:
+                del self._model
+                self._model = None
+                self._loaded = False
+                import gc
+                gc.collect()
+                logger.info("EmbeddingService: model unloaded (idle timeout)")
+    def _reset_idle_timer(self) -> None:
+        """Reset the idle unload timer after each use."""
+        if self._idle_timer is not None:
+            self._idle_timer.cancel()
+        self._idle_timer = threading.Timer(
+            _IDLE_TIMEOUT_SECONDS, self.unload,
+        )
+        self._idle_timer.daemon = True
+        self._idle_timer.start()
+        self._last_used = time.time()
     # ------------------------------------------------------------------
     # Public API
     # ------------------------------------------------------------------
@@ -91,6 +137,7 @@ class EmbeddingService:
             return None
         vec = self._encode_single(text)
         self._validate_dimension(vec)
+        self._reset_idle_timer()
         return vec.tolist()
     def embed_batch(self, texts: list[str]) -> list[list[float]]:
@@ -115,6 +162,7 @@ class EmbeddingService:
         vectors = self._encode_batch(texts)
         for vec in vectors:
             self._validate_dimension(vec)
+        self._reset_idle_timer()
         return [v.tolist() for v in vectors]
     def compute_fisher_params(
@@ -185,7 +233,13 @@ class EmbeddingService:
             self._loaded = True
     def _load_local_model(self) -> None:
-        """Load sentence-transformers model for local embedding."""
+        """Load sentence-transformers model for local embedding.
+        Forces CPU device to prevent GPU memory accumulation:
+        - Apple Silicon MPS: allocates 4-6 GB Metal shader buffers
+        - NVIDIA CUDA: allocates GPU VRAM that never releases
+        - CPU-only: stable ~880 MB footprint, no growth over time
+        """
         try:
             from sentence_transformers import SentenceTransformer
         except ImportError:
@@ -199,6 +253,7 @@ class EmbeddingService:
             return
         model = SentenceTransformer(
             self._config.model_name, trust_remote_code=True,
+            device="cpu",
         )
         actual_dim = model.get_sentence_embedding_dimension()
         if actual_dim != self._config.dimension:
@@ -208,7 +263,7 @@ class EmbeddingService:
             )
         self._model = model
         logger.info(
-            "EmbeddingService: local model loaded (%s, %d-dim)",
+            "EmbeddingService: local model loaded (%s, %d-dim, device=cpu)",
             self._config.model_name,
             actual_dim,
         )

package/src/superlocalmemory.egg-info/PKG-INFO CHANGED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superlocalmemory
-Version: 3.0.13
+Version: 3.0.15
 Summary: Information-geometric agent memory with mathematical guarantees
 Author-email: Varun Pratap Bhardwaj <admin@superlocalmemory.com>
 License: MIT
@@ -50,57 +50,104 @@ Dynamic: license-file
 </p>
 <h1 align="center">SuperLocalMemory V3</h1>
-<p align="center"><strong>Information-Geometric Agent Memory with Mathematical Guarantees</strong></p>
+<p align="center"><strong>The first local-only AI memory to break 74% retrieval on LoCoMo.<br/>No cloud. No APIs. No data leaves your machine.</strong></p>
 <p align="center">
-  The first agent memory system with mathematically grounded retrieval, lifecycle management, and consistency verification. Four-channel hybrid retrieval. Three operating modes. EU AI Act compliant.
+  <code>+16pp vs Mem0 (zero cloud)</code> &nbsp;·&nbsp; <code>85% Open-Domain (best of any system)</code> &nbsp;·&nbsp; <code>EU AI Act Ready</code>
 </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="Website"/></a>
-  <a href="https://arxiv.org/abs/2603.14588"><img src="https://img.shields.io/badge/arXiv-2603.14588-b31b1b?style=for-the-badge&logo=arxiv&logoColor=white" alt="arXiv V3 Paper"/></a>
-  <a href="https://zenodo.org/records/19038659"><img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.19038659-blue?style=for-the-badge&logo=doi&logoColor=white" alt="V3 DOI"/></a>
+  <a href="https://arxiv.org/abs/2603.14588"><img src="https://img.shields.io/badge/arXiv-2603.14588-b31b1b?style=for-the-badge&logo=arxiv&logoColor=white" alt="arXiv Paper"/></a>
+  <a href="https://pypi.org/project/superlocalmemory/"><img src="https://img.shields.io/pypi/v/superlocalmemory?style=for-the-badge&logo=pypi&logoColor=white" alt="PyPI"/></a>
+  <a href="https://www.npmjs.com/package/superlocalmemory"><img src="https://img.shields.io/npm/v/superlocalmemory?style=for-the-badge&logo=npm&logoColor=white" alt="npm"/></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT License"/></a>
+  <a href="#eu-ai-act-compliance"><img src="https://img.shields.io/badge/EU_AI_Act-Compliant-brightgreen?style=for-the-badge" alt="EU AI Act"/></a>
+  <a href="https://superlocalmemory.com"><img src="https://img.shields.io/badge/Web-superlocalmemory.com-ff6b35?style=for-the-badge" alt="Website"/></a>
 </p>
-<p align="center">
-  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+"/></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT License"/></a>
-  <a href="#three-operating-modes"><img src="https://img.shields.io/badge/EU_AI_Act-Compliant-brightgreen?style=flat-square" alt="EU AI Act"/></a>
-  <a href="#"><img src="https://img.shields.io/badge/tests-1400+-brightgreen?style=flat-square" alt="1400+ Tests"/></a>
-  <a href="#"><img src="https://img.shields.io/badge/platform-Mac_|_Linux_|_Windows-blue?style=flat-square" alt="Cross Platform"/></a>
-  <a href="https://github.com/qualixar/superlocalmemory/wiki"><img src="https://img.shields.io/badge/Wiki-Documentation-blue?style=flat-square" alt="Wiki"/></a>
-</p>
+---
+## Why SuperLocalMemory?
+Every major AI memory system — Mem0, Zep, Letta, EverMemOS — sends your data to cloud LLMs for core operations. That means latency on every query, cost on every interaction, and after **August 2, 2026**, a compliance problem under the EU AI Act.
+SuperLocalMemory V3 takes a different approach: **mathematics instead of cloud compute.** Three techniques from differential geometry, algebraic topology, and stochastic analysis replace the work that other systems need LLMs to do — similarity scoring, contradiction detection, and lifecycle management. The result is an agent memory that runs entirely on your machine, on CPU, with no API keys, and still outperforms funded alternatives.
+**The numbers** (evaluated on [LoCoMo](https://arxiv.org/abs/2402.09714), the standard long-conversation memory benchmark):
+| System | Score | Cloud Required | Open Source | Funding |
+|:-------|:-----:|:--------------:|:-----------:|:-------:|
+| EverMemOS | 92.3% | Yes | No | — |
+| Hindsight | 89.6% | Yes | No | — |
+| **SLM V3 Mode C** | **87.7%** | Optional | **Yes (MIT)** | $0 |
+| Zep v3 | 85.2% | Yes | Deprecated | $35M |
+| **SLM V3 Mode A** | **74.8%** | **No** | **Yes (MIT)** | $0 |
+| Mem0 | 64.2% | Yes | Partial | $24M |
+Mode A scores **74.8% with zero cloud dependency** — outperforming Mem0 by 16 percentage points without a single API call. On open-domain questions, Mode A scores **85.0% — the highest of any system in the evaluation**, including cloud-powered ones. Mode C reaches **87.7%**, matching enterprise cloud systems.
+Mathematical layers contribute **+12.7 percentage points** on average across 6 conversations (n=832 questions), with up to **+19.9pp on the most challenging dialogues**. This isn't more compute — it's better math.
+> **Upgrading from V2 (2.8.6)?** V3 is a complete architectural reinvention — new mathematical engine, new retrieval pipeline, new storage schema. Your existing data is preserved but requires migration. After installing V3, run `slm migrate` to upgrade your data. Read the [Migration Guide](https://github.com/qualixar/superlocalmemory/wiki/Migration-from-V2) before upgrading. Backup is created automatically.
 ---
-## What is SuperLocalMemory?
+## Quick Start
-SuperLocalMemory gives AI assistants persistent, structured memory that survives across sessions. Unlike simple vector stores, V3 uses **information geometry** to provide mathematically grounded retrieval, automatic contradiction detection, and self-organizing memory lifecycle management.
+### Install via npm (recommended)
-**Works with:** Claude, Cursor, Windsurf, VS Code Copilot, Continue, Cody, ChatGPT Desktop, Gemini CLI, JetBrains, Zed, and 17+ AI tools via MCP.
+```bash
+npm install -g superlocalmemory
+slm setup     # Choose mode (A/B/C)
+slm warmup    # Pre-download embedding model (~500MB, optional)
+```
+### Install via pip
+```bash
+pip install superlocalmemory
+```
-> **Upgrading from V2 (2.8.6)?** V3 is a complete architectural reinvention — new mathematical engine, new retrieval pipeline, new storage schema. Your existing data is preserved but requires migration. After installing V3, run `slm migrate` to upgrade your data. Read the [Migration Guide](docs/migration-from-v2.md) before upgrading. Backup is created automatically.
+### First Use
-### Key Results
+```bash
+slm remember "Alice works at Google as a Staff Engineer"
+slm recall "What does Alice do?"
+slm status
+```
-| Metric | Score | Context |
-|:-------|:-----:|:--------|
-| LoCoMo (Mode C, full power) | **87.7%** | On conv-30, 81 scored questions |
-| LoCoMo (Mode A, zero-LLM) | **62.3%** | Highest zero-LLM score. No cloud dependency. |
-| Math layer improvement | **+12.7pp** | Average gain from mathematical foundations |
-| Multi-hop improvement | **+12pp** | 50% vs 38% (math on vs off) |
+### MCP Integration (Claude, Cursor, Windsurf, VS Code, etc.)
+```json
+{
+  "mcpServers": {
+    "superlocalmemory": {
+      "command": "slm",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+24 MCP tools available. Works with Claude Code, Cursor, Windsurf, VS Code Copilot, Continue, Cody, ChatGPT Desktop, Gemini CLI, JetBrains, Zed, and 17+ AI tools.
 ---
 ## Three Operating Modes
-| Mode | What | LLM Required? | EU AI Act | Best For |
-|:----:|:-----|:-------------:|:---------:|:---------|
-| **A** | Local Guardian | No | Compliant | Privacy-first, air-gapped, enterprise |
-| **B** | Smart Local | Local only (Ollama) | Compliant | Enhanced quality, data stays local |
-| **C** | Full Power | Cloud (optional) | Partial | Maximum accuracy, research |
+| Mode | What | Cloud? | EU AI Act | Best For |
+|:----:|:-----|:------:|:---------:|:---------|
+| **A** | Local Guardian | **None** | **Compliant** | Privacy-first, air-gapped, enterprise |
+| **B** | Smart Local | Local only (Ollama) | Compliant | Better answers, data stays local |
+| **C** | Full Power | Cloud LLM | Partial | Maximum accuracy, research |
+```bash
+slm mode a   # Zero-cloud (default)
+slm mode b   # Local Ollama
+slm mode c   # Cloud LLM
+```
-**Mode A** is the only agent memory that operates with **zero cloud dependency** while achieving competitive retrieval accuracy. All data stays on your device. No API keys required.
+**Mode A** is the only agent memory that operates with **zero cloud dependency** while achieving competitive retrieval accuracy on a standard benchmark. All data stays on your device. No API keys. No GPU. Runs on 2 vCPUs + 4GB RAM.
 ---
@@ -108,8 +155,8 @@ SuperLocalMemory gives AI assistants persistent, structured memory that survives
 ```
 Query  ──►  Strategy Classifier  ──►  4 Parallel Channels:
-                                       ├── Semantic (Fisher-Rao graduated similarity)
-                                       ├── BM25 (keyword matching, k1=1.2, b=0.75)
+                                       ├── Semantic (Fisher-Rao geodesic distance)
+                                       ├── BM25 (keyword matching)
                                        ├── Entity Graph (spreading activation, 3 hops)
                                        └── Temporal (date-aware retrieval)
                                                     │
@@ -122,104 +169,79 @@ Query  ──►  Strategy Classifier  ──►  4 Parallel Channels:
                                        ◄── Top-K Results with channel scores
 ```
-### Mathematical Foundations (Novel Contributions)
-1. **Fisher-Rao Retrieval Metric** — Similarity scoring derived from the Fisher information structure of diagonal Gaussian families. Graduated ramp from cosine to Fisher-information-weighted scoring over the first 10 accesses per memory.
-2. **Sheaf Cohomology for Consistency** — Algebraic topology detects contradictions between facts by computing coboundary norms on the knowledge graph. Non-trivial restriction maps amplify disagreements along discriminative subspaces.
-3. **Riemannian Langevin Lifecycle** — Memory positions evolve on the Poincare ball via a discretized Langevin SDE. Frequently accessed memories stay near the origin (ACTIVE); neglected memories diffuse toward the boundary (ARCHIVED). The potential is modulated by access frequency, age, and importance.
----
-## Prerequisites
+### Mathematical Foundations
-| Requirement | Version | Why |
-|:-----------|:--------|:----|
-| **Node.js** | 14+ | npm package manager |
-| **Python** | 3.11+ | V3 engine runtime |
-| **pip** | Latest | Python dependency installer |
+Three novel contributions replace cloud LLM dependency with mathematical guarantees:
-> All Python dependencies are installed automatically during `npm install`. You don't need to run pip manually. If any dependency fails, the installer shows clear instructions.
+1. **Fisher-Rao Retrieval Metric** — Similarity scoring derived from the Fisher information structure of diagonal Gaussian families. Graduated ramp from cosine to geodesic distance over the first 10 accesses. The first application of information geometry to agent memory retrieval.
-### What Gets Installed Automatically
+2. **Sheaf Cohomology for Consistency** — Algebraic topology detects contradictions by computing coboundary norms on the knowledge graph. The first algebraic guarantee for contradiction detection in agent memory.
-| Component | Size | When |
-|:----------|:-----|:-----|
-| Core math libraries (numpy, scipy, networkx) | ~50MB | During `npm install` |
-| Search engine (sentence-transformers, einops, torch) | ~200MB | During `npm install` |
-| Embedding model (nomic-ai/nomic-embed-text-v1.5) | ~500MB | On first use OR `slm warmup` |
+3. **Riemannian Langevin Lifecycle** — Memory positions evolve on the Poincare ball via discretized Langevin SDE. Frequently accessed memories stay active; neglected memories self-archive. No hardcoded thresholds.
-**If any dependency fails during install**, the installer prints the exact `pip install` command to fix it. BM25 keyword search works even without embeddings — you're never fully blocked.
+These three layers collectively yield **+12.7pp average improvement** over the engineering-only baseline, with the Fisher metric alone contributing **+10.8pp** on the hardest conversations.
 ---
-## Quick Start
+## Benchmarks
-### Install via npm (recommended — one command, everything included)
+Evaluated on [LoCoMo](https://arxiv.org/abs/2402.09714) — 10 multi-session conversations, 1,986 total questions, 4 scored categories.
-```bash
-npm install -g superlocalmemory
-```
+### Mode A (Zero-Cloud, 10 Conversations, 1,276 Questions)
-This single command:
-- Installs the V3 engine and CLI
-- Auto-installs all Python dependencies (numpy, scipy, networkx, sentence-transformers, einops, torch, etc.)
-- Creates the data directory at `~/.superlocalmemory/`
-- Detects and guides V2 migration if applicable
+| Category | Score | vs. Mem0 (64.2%) |
+|:---------|:-----:|:-----------------:|
+| Single-Hop | 72.0% | +3.0pp |
+| Multi-Hop | 70.3% | +8.6pp |
+| Temporal | 80.0% | +21.7pp |
+| **Open-Domain** | **85.0%** | **+35.0pp** |
+| **Aggregate** | **74.8%** | **+10.6pp** |
-Then configure and pre-download the embedding model:
-```bash
-slm setup     # Choose mode, configure provider
-slm warmup    # Pre-download embedding model (~500MB, optional)
-```
+Mode A achieves **85.0% on open-domain questions — the highest of any system in the evaluation**, including cloud-powered ones.
-> **First time?** If you skip `slm warmup`, the model downloads automatically on first `slm remember` or `slm recall`. Either way works.
+### Math Layer Impact (6 Conversations, n=832)
-### Install via pip
+| Conversation | With Math | Without | Delta |
+|:-------------|:---------:|:-------:|:-----:|
+| Easiest | 78.5% | 71.2% | +7.3pp |
+| Hardest | 64.2% | 44.3% | **+19.9pp** |
+| **Average** | **71.7%** | **58.9%** | **+12.7pp** |
-```bash
-pip install superlocalmemory
-# or with all features:
-pip install "superlocalmemory[full]"
-```
+Mathematical layers help most where heuristic methods struggle — the harder the conversation, the bigger the improvement.
-### First Use
+### Ablation (What Each Component Contributes)
-```bash
-# Store a memory
-slm remember "Alice works at Google as a Staff Engineer"
+| Removed | Impact |
+|:--------|:------:|
+| Cross-encoder reranking | **-30.7pp** |
+| Fisher-Rao metric | **-10.8pp** |
+| All math layers | **-7.6pp** |
+| BM25 channel | **-6.5pp** |
+| Sheaf consistency | -1.7pp |
+| Entity graph | -1.0pp |
-# Recall
-slm recall "What does Alice do?"
+Full ablation details in the [Wiki](https://github.com/qualixar/superlocalmemory/wiki/Benchmarks).
-# Check status
-slm status
+---
-# Switch modes
-slm mode a   # Zero-LLM (default)
-slm mode b   # Local Ollama
-slm mode c   # Full power
-```
+## EU AI Act Compliance
-### MCP Integration (Claude, Cursor, etc.)
+The EU AI Act (Regulation 2024/1689) takes full effect **August 2, 2026**. Every AI memory system that sends personal data to cloud LLMs for core operations has a compliance question to answer.
-Add to your IDE's MCP config:
+| Requirement | Mode A | Mode B | Mode C |
+|:------------|:------:|:------:|:------:|
+| Data sovereignty (Art. 10) | **Pass** | **Pass** | Requires DPA |
+| Right to erasure (GDPR Art. 17) | **Pass** | **Pass** | **Pass** |
+| Transparency (Art. 13) | **Pass** | **Pass** | **Pass** |
+| No network calls during memory ops | **Yes** | **Yes** | No |
-```json
-{
-  "mcpServers": {
-    "superlocalmemory": {
-      "command": "slm",
-      "args": ["mcp"]
-    }
-  }
-}
-```
+To the best of our knowledge, **no existing agent memory system addresses EU AI Act compliance**. Modes A and B pass all checks by architectural design — no personal data leaves the device during any memory operation.
-24 MCP tools available: `remember`, `recall`, `search`, `fetch`, `list_recent`, `get_status`, `build_graph`, `switch_profile`, `health`, `consistency_check`, `recall_trace`, and more.
+Built-in compliance tools: GDPR Article 15/17 export + complete erasure, tamper-proof SHA-256 audit chain, data provenance tracking, ABAC policy enforcement.
+---
-### Web Dashboard (17 tabs)
+## Web Dashboard
 ```bash
 slm dashboard    # Opens at http://localhost:8765
@@ -240,82 +262,58 @@ slm dashboard    # Opens at http://localhost:8765
 </p>
 </details>
-The V3 dashboard provides real-time visibility into your memory system:
-- **Dashboard** — Mode switcher, health score, quick store/recall
-- **Recall Lab** — Search with per-channel score breakdown (Semantic, BM25, Entity, Temporal)
-- **Knowledge Graph** — Interactive entity relationship visualization
-- **Memories** — Browse, search, and manage stored memories
-- **Trust Dashboard** — Bayesian trust scores per agent with Beta distribution visualization
-- **Math Health** — Fisher-Rao confidence, Sheaf consistency, Langevin lifecycle state
-- **Compliance** — GDPR export/erasure, EU AI Act status, audit trail
-- **Learning** — Adaptive ranking progress, behavioral patterns, outcome tracking
-- **IDE Connections** — Connected AI tools status and configuration
-- **Settings** — Mode, provider, auto-capture/recall configuration
-> The dashboard runs locally at `http://localhost:8765`. No data leaves your machine.
+17 tabs: Dashboard, Recall Lab, Knowledge Graph, Memories, Trust Scores, Math Health, Compliance, Learning, IDE Connections, Settings, and more. Runs locally — no data leaves your machine.
 ---
-## V3 Engine Features
+## Features
-### Retrieval (4-Channel Hybrid)
-- Semantic similarity with Fisher-Rao information geometry
-- BM25 keyword matching (persisted tokens, survives restart)
-- Entity graph with spreading activation (3-hop, decay=0.7)
-- Temporal date-aware retrieval with interval support
-- RRF fusion (k=60) + cross-encoder reranking
+### Retrieval
+- 4-channel hybrid: Semantic (Fisher-Rao) + BM25 + Entity Graph + Temporal
+- RRF fusion + cross-encoder reranking
+- Agentic sufficiency verification (auto-retry on weak results)
+- Adaptive ranking with LightGBM (learns from usage)
 ### Intelligence
-- 11-step ingestion pipeline (entity resolution, fact extraction, emotional tagging, scene building, sheaf consistency)
-- Adaptive learning with LightGBM-based ranking (3-phase bootstrap)
-- Behavioral pattern detection (query habits, entity preferences, active hours)
-- Outcome tracking for retrieval feedback loops
+- 11-step ingestion pipeline (entity resolution, fact extraction, emotional tagging, scene building)
+- Automatic contradiction detection via sheaf cohomology
+- Self-organizing memory lifecycle (no hardcoded thresholds)
+- Behavioral pattern detection and outcome tracking
-### Trust & Compliance
-- Bayesian Beta distribution trust scoring (per-agent, per-fact)
+### Trust & Security
+- Bayesian Beta-distribution trust scoring (per-agent, per-fact)
 - Trust gates (block low-trust agents from writing/deleting)
 - ABAC (Attribute-Based Access Control) with DB-persisted policies
-- GDPR Article 15/17 compliance (full export + complete erasure)
-- EU AI Act data sovereignty (Mode A: zero cloud, data stays local)
 - Tamper-proof hash-chain audit trail (SHA-256 linked entries)
-- Data provenance tracking (who created what, when, from where)
 ### Infrastructure
-- 17-tab web dashboard (trust visualization, math health, recall lab)
-- 17+ IDE integrations with pre-built configs
-- Profile isolation (16+ independent memory spaces)
-- V2 to V3 migration tool (zero data loss, rollback support)
-- Auto-capture and auto-recall hooks for Claude Code
+- 17-tab web dashboard with real-time visualization
+- 17+ IDE integrations (Claude, Cursor, Windsurf, VS Code, JetBrains, Zed, etc.)
+- 24 MCP tools + 6 MCP resources
+- Profile isolation (independent memory spaces)
+- 1400+ tests, MIT license, cross-platform (Mac/Linux/Windows)
+- CPU-only — no GPU required
 ---
-## Benchmarks
-Evaluated on the [LoCoMo benchmark](https://arxiv.org/abs/2402.09714) (Long Conversation Memory):
-### Mode A Ablation (conv-30, 81 questions, zero-LLM)
-| Configuration | Micro Avg | Multi-Hop | Open Domain |
-|:-------------|:---------:|:---------:|:-----------:|
-| Full (all layers) | **62.3%** | **50%** | **78%** |
-| Math layers off | 59.3% | 38% | 70% |
-| Entity channel off | 56.8% | 38% | 73% |
-| BM25 channel off | 53.2% | 23% | 71% |
-| Cross-encoder off | 31.8% | 17% | — |
-### Competitive Landscape
-| System | Score | LLM Required | Open Source | EU AI Act |
-|:-------|:-----:|:------------:|:-----------:|:---------:|
-| EverMemOS | 92.3% | Yes | No | No |
-| MemMachine | 91.7% | Yes | No | No |
-| Hindsight | 89.6% | Yes | No | No |
-| **SLM V3 Mode C** | **87.7%** | Optional | **Yes** | Partial |
-| **SLM V3 Mode A** | **62.3%** | **No** | **Yes** | **Yes** |
-| Mem0 ($24M) | 34.2% F1 | Yes | Partial | No |
-*SLM V3 is the only system offering a fully local mode with mathematical guarantees and EU AI Act compliance.*
+## CLI Reference
+| Command | What It Does |
+|:--------|:-------------|
+| `slm remember "..."` | Store a memory |
+| `slm recall "..."` | Search memories |
+| `slm forget "..."` | Delete matching memories |
+| `slm trace "..."` | Recall with per-channel score breakdown |
+| `slm status` | System status |
+| `slm health` | Math layer health (Fisher, Sheaf, Langevin) |
+| `slm mode a/b/c` | Switch operating mode |
+| `slm setup` | Interactive first-time wizard |
+| `slm warmup` | Pre-download embedding model |
+| `slm migrate` | V2 to V3 migration |
+| `slm dashboard` | Launch web dashboard |
+| `slm mcp` | Start MCP server (for IDE integration) |
+| `slm connect` | Configure IDE integrations |
+| `slm profile list/create/switch` | Profile management |
 ---
@@ -324,43 +322,47 @@ Evaluated on the [LoCoMo benchmark](https://arxiv.org/abs/2402.09714) (Long Conv
 ### V3: Information-Geometric Foundations
 > **SuperLocalMemory V3: Information-Geometric Foundations for Zero-LLM Enterprise Agent Memory**
 > Varun Pratap Bhardwaj (2026)
-> [arXiv:2603.14588](https://arxiv.org/abs/2603.14588) | [Zenodo DOI: 10.5281/zenodo.19038659](https://zenodo.org/records/19038659)
+> [arXiv:2603.14588](https://arxiv.org/abs/2603.14588) · [Zenodo DOI: 10.5281/zenodo.19038659](https://zenodo.org/records/19038659)
 ### V2: Architecture & Engineering
 > **SuperLocalMemory: A Structured Local Memory Architecture for Persistent AI Agent Context**
 > Varun Pratap Bhardwaj (2026)
-> [arXiv:2603.02240](https://arxiv.org/abs/2603.02240) | [Zenodo DOI: 10.5281/zenodo.18709670](https://zenodo.org/records/18709670)
+> [arXiv:2603.02240](https://arxiv.org/abs/2603.02240) · [Zenodo DOI: 10.5281/zenodo.18709670](https://zenodo.org/records/18709670)
+### Cite This Work
+```bibtex
+@article{bhardwaj2026slmv3,
+  title={Information-Geometric Foundations for Zero-LLM Enterprise Agent Memory},
+  author={Bhardwaj, Varun Pratap},
+  journal={arXiv preprint arXiv:2603.14588},
+  year={2026},
+  url={https://arxiv.org/abs/2603.14588}
+}
+```
 ---
-## Project Structure
+## Prerequisites
-```
-superlocalmemory/
-├── src/superlocalmemory/     # Python package (17 sub-packages)
-│   ├── core/                 # Engine, config, modes, profiles
-│   ├── retrieval/            # 4-channel retrieval + fusion + reranking
-│   ├── math/                 # Fisher-Rao, Sheaf, Langevin
-│   ├── encoding/             # 11-step ingestion pipeline
-│   ├── storage/              # SQLite with WAL, FTS5, migrations
-│   ├── trust/                # Bayesian scoring, gates, provenance
-│   ├── compliance/           # GDPR, EU AI Act, ABAC, audit chain
-│   ├── learning/             # Adaptive ranking, behavioral patterns
-│   ├── mcp/                  # MCP server (24 tools, 6 resources)
-│   ├── cli/                  # CLI with setup wizard
-│   └── server/               # Dashboard API + UI server
-├── tests/                    # 1400+ tests
-├── ui/                       # 17-tab web dashboard
-├── ide/                      # IDE configs for 17+ tools
-├── docs/                     # Documentation
-└── pyproject.toml            # Modern Python packaging
-```
+| Requirement | Version | Why |
+|:-----------|:--------|:----|
+| **Node.js** | 14+ | npm package manager |
+| **Python** | 3.11+ | V3 engine runtime |
+All Python dependencies install automatically during `npm install`. If anything fails, the installer shows exact fix commands. BM25 keyword search works even without embeddings — you're never fully blocked.
+| Component | Size | When |
+|:----------|:-----|:-----|
+| Core libraries (numpy, scipy, networkx) | ~50MB | During install |
+| Search engine (sentence-transformers, torch) | ~200MB | During install |
+| Embedding model (nomic-embed-text-v1.5, 768d) | ~500MB | First use or `slm warmup` |
 ---
 ## Contributing
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. [Wiki](https://github.com/qualixar/superlocalmemory/wiki) for detailed documentation.
 ## License
@@ -368,7 +370,7 @@ MIT License. See [LICENSE](LICENSE).
 ## Attribution
-Part of [Qualixar](https://qualixar.com) | Author: [Varun Pratap Bhardwaj](https://varunpratap.com)
+Part of [Qualixar](https://qualixar.com) · Author: [Varun Pratap Bhardwaj](https://varunpratap.com)
 ---