superlocalmemory 3.0.0__tar.gz

superlocalmemory-3.0.0/AUTHORS.md

@@ -0,0 +1,16 @@
+# Authors
+
+## Research Initiative
+
+**Qualixar** — Advancing Agent Development Through Research
+
+SuperLocalMemory is a Qualixar research initiative.
+
+## Creator
+
+Varun Pratap Bhardwaj ([@varun369](https://github.com/varun369)) — Solution Architect & Original Creator
+- ORCID: 0009-0002-8726-4289
+
+## Contributors
+
+See [GitHub contributors](https://github.com/varun369/SuperLocalMemoryV2/graphs/contributors).

superlocalmemory-3.0.0/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+ATTRIBUTION NOTICE:
+This software contains novel mathematical methods described in:
+- arXiv:2603.02240 (SuperLocalMemory V2 — Bayesian Trust Defense)
+- Zenodo DOI: 10.5281/zenodo.19038659 (SuperLocalMemory V3 — Information-Geometric Foundations)
+
+Academic use MUST cite the relevant paper.
+Commercial use MUST retain this notice, the NOTICE file, and visible attribution.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

superlocalmemory-3.0.0/NOTICE

@@ -0,0 +1,63 @@
+SuperLocalMemory V3
+Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+https://qualixar.com | https://varunpratap.com
+
+This product includes novel algorithms first described in peer-reviewed
+publications by the author:
+
+MATHEMATICAL FOUNDATIONS (Novel — Zero Prior Work)
+===================================================
+
+1. Fisher-Rao Information Geometry for Agent Memory Retrieval
+   - Geodesic similarity metric on statistical manifolds
+   - Graduated ramp from cosine to Fisher-Rao distance
+   - O(d) computational complexity
+   - First application to agent memory systems
+
+2. Sheaf Cohomology for Memory Consistency Verification
+   - Čech cohomology on knowledge graphs
+   - H¹(G,F) ≠ 0 detects contradictions algebraically
+   - First application to agent memory consistency
+
+3. Riemannian Langevin Dynamics for Memory Lifecycle
+   - Gradient flow on information-geometric manifolds
+   - Provably convergent to stationary distribution
+   - Self-organizing Active→Warm→Cold→Archived lifecycle
+   - First application to agent memory systems
+
+ARCHITECTURAL INNOVATIONS
+=========================
+
+4. Four-Channel Hybrid Retrieval with Weighted RRF Fusion
+5. Scene Clustering via Temporal-Semantic Coherence
+6. Bridge Discovery via Steiner Tree Approximation
+7. Cross-Encoder Energy-Weighted Blended Reranking
+8. Eleven-Step Structured Ingestion Pipeline
+9. Three Operating Modes (Zero-LLM / Local-LLM / Cloud-Augmented)
+10. Mathematical DNA — Coupled-Parameter Integrity Verification
+
+PUBLICATIONS
+============
+
+- V3 Paper: "SuperLocalMemory V3: Information-Geometric Foundations for
+  Zero-LLM Enterprise Agent Memory"
+  Zenodo DOI: 10.5281/zenodo.19038659
+  arXiv: Submitted March 2026 (cs.AI, cs.IR, cs.LG)
+
+- V2 Paper: "SuperLocalMemory: Privacy-Preserving Multi-Agent Memory with
+  Bayesian Trust Defense Against Memory Poisoning"
+  arXiv: 2603.02240
+
+PRIOR ART TIMESTAMPS
+=====================
+
+All algorithms are timestamped via:
+1. Zenodo DOI (CERN) — permanent citable artifact
+2. arXiv preprint — public timestamp
+3. GitHub commit history — Microsoft-backed timestamps
+4. npm registry — public package timestamps
+
+Academic use MUST cite the relevant paper.
+Commercial use MUST retain this notice and visible attribution.
+
+Part of Qualixar — The Complete Agent Development Platform

superlocalmemory-3.0.0/PKG-INFO

@@ -0,0 +1,304 @@
+Metadata-Version: 2.4
+Name: superlocalmemory
+Version: 3.0.0
+Summary: Information-geometric agent memory with mathematical guarantees
+Author-email: Varun Pratap Bhardwaj <admin@superlocalmemory.com>
+License: MIT
+Project-URL: Homepage, https://superlocalmemory.com
+Project-URL: Repository, https://github.com/qualixar/superlocalmemory
+Project-URL: Documentation, https://github.com/qualixar/superlocalmemory/wiki
+Project-URL: Issues, https://github.com/qualixar/superlocalmemory/issues
+Keywords: ai-memory,mcp-server,local-first,agent-memory,information-geometry,privacy-first,eu-ai-act
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+License-File: AUTHORS.md
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: numpy<3.0.0,>=1.26.0
+Requires-Dist: scipy<2.0.0,>=1.12.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: rank-bm25>=0.2.2
+Requires-Dist: vadersentiment>=3.3.2
+Provides-Extra: search
+Requires-Dist: sentence-transformers<4.0.0,>=2.5.0; extra == "search"
+Requires-Dist: torch>=2.2.0; extra == "search"
+Requires-Dist: scikit-learn<2.0.0,>=1.3.0; extra == "search"
+Requires-Dist: geoopt>=0.5.0; extra == "search"
+Provides-Extra: ui
+Requires-Dist: fastapi<1.0.0,>=0.109.0; extra == "ui"
+Requires-Dist: uvicorn[standard]<1.0.0,>=0.27.0; extra == "ui"
+Requires-Dist: python-multipart<1.0.0,>=0.0.6; extra == "ui"
+Provides-Extra: learning
+Requires-Dist: lightgbm<5.0.0,>=4.0.0; extra == "learning"
+Provides-Extra: performance
+Requires-Dist: diskcache<6.0.0,>=5.6.0; extra == "performance"
+Requires-Dist: orjson<4.0.0,>=3.9.0; extra == "performance"
+Provides-Extra: full
+Requires-Dist: superlocalmemory[learning,performance,search,ui]; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://superlocalmemory.com/assets/logo-mark.png" alt="SuperLocalMemory" width="200"/>
+</p>
+
+<h1 align="center">SuperLocalMemory V3</h1>
+<p align="center"><strong>Information-Geometric Agent Memory with Mathematical Guarantees</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.
+</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.02240"><img src="https://img.shields.io/badge/arXiv-2603.02240-b31b1b?style=for-the-badge&logo=arxiv&logoColor=white" alt="arXiv 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>
+</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>
+
+---
+
+## What is SuperLocalMemory?
+
+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.
+
+**Works with:** Claude, Cursor, Windsurf, VS Code Copilot, Continue, Cody, ChatGPT Desktop, Gemini CLI, JetBrains, Zed, and 17+ AI tools via MCP.
+
+> **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.
+
+### Key Results
+
+| Metric | Score | Context |
+|:-------|:-----:|:--------|
+| LoCoMo (Mode A, zero-LLM) | **62.3%** | Highest zero-LLM score. No cloud dependency. |
+| LoCoMo (Mode C, full) | **~78%** | Competitive with funded systems ($10M+) |
+| Math layer improvement | **+12.7pp** | Average gain from mathematical foundations |
+| Multi-hop improvement | **+12pp** | 50% vs 38% (math on vs off) |
+
+---
+
+## 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 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.
+
+---
+
+## Architecture
+
+```
+Query  ──►  Strategy Classifier  ──►  4 Parallel Channels:
+                                       ├── Semantic (Fisher-Rao graduated similarity)
+                                       ├── BM25 (keyword matching, k1=1.2, b=0.75)
+                                       ├── Entity Graph (spreading activation, 3 hops)
+                                       └── Temporal (date-aware retrieval)
+                                                    │
+                                       RRF Fusion (k=60)
+                                                    │
+                                       Scene Expansion + Bridge Discovery
+                                                    │
+                                       Cross-Encoder Reranking
+                                                    │
+                                       ◄── 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.
+
+---
+
+## Quick Start
+
+### Install via npm (recommended)
+
+```bash
+npm install -g superlocalmemory
+slm setup
+```
+
+### Install via pip
+
+```bash
+pip install superlocalmemory
+# or with all features:
+pip install "superlocalmemory[full]"
+```
+
+### First Use
+
+```bash
+# Store a memory
+slm remember "Alice works at Google as a Staff Engineer"
+
+# Recall
+slm recall "What does Alice do?"
+
+# Check status
+slm status
+
+# Switch modes
+slm mode a   # Zero-LLM (default)
+slm mode b   # Local Ollama
+slm mode c   # Full power
+```
+
+### MCP Integration (Claude, Cursor, etc.)
+
+Add to your IDE's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "superlocalmemory": {
+      "command": "slm",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+24 MCP tools available: `remember`, `recall`, `search`, `fetch`, `list_recent`, `get_status`, `build_graph`, `switch_profile`, `health`, `consistency_check`, `recall_trace`, and more.
+
+---
+
+## V3 Engine 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
+
+### 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
+
+### Trust & Compliance
+- 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
+
+---
+
+## 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** | **~78%** | 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.*
+
+---
+
+## Research Papers
+
+### V3: Information-Geometric Foundations
+> **SuperLocalMemory V3: Information-Geometric Foundations for Zero-LLM Enterprise Agent Memory**
+> Varun Pratap Bhardwaj (2026)
+> [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)
+
+---
+
+## Project Structure
+
+```
+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
+```
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+
+## Attribution
+
+Part of [Qualixar](https://qualixar.com) | Author: [Varun Pratap Bhardwaj](https://varunpratap.com)
+
+---
+
+<p align="center">
+  <sub>Built with mathematical rigor. Not in the race — here to help everyone build better AI memory systems.</sub>
+</p>

superlocalmemory-3.0.0/README.md

@@ -0,0 +1,259 @@
+<p align="center">
+  <img src="https://superlocalmemory.com/assets/logo-mark.png" alt="SuperLocalMemory" width="200"/>
+</p>
+
+<h1 align="center">SuperLocalMemory V3</h1>
+<p align="center"><strong>Information-Geometric Agent Memory with Mathematical Guarantees</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.
+</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.02240"><img src="https://img.shields.io/badge/arXiv-2603.02240-b31b1b?style=for-the-badge&logo=arxiv&logoColor=white" alt="arXiv 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>
+</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>
+
+---
+
+## What is SuperLocalMemory?
+
+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.
+
+**Works with:** Claude, Cursor, Windsurf, VS Code Copilot, Continue, Cody, ChatGPT Desktop, Gemini CLI, JetBrains, Zed, and 17+ AI tools via MCP.
+
+> **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.
+
+### Key Results
+
+| Metric | Score | Context |
+|:-------|:-----:|:--------|
+| LoCoMo (Mode A, zero-LLM) | **62.3%** | Highest zero-LLM score. No cloud dependency. |
+| LoCoMo (Mode C, full) | **~78%** | Competitive with funded systems ($10M+) |
+| Math layer improvement | **+12.7pp** | Average gain from mathematical foundations |
+| Multi-hop improvement | **+12pp** | 50% vs 38% (math on vs off) |
+
+---
+
+## 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 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.
+
+---
+
+## Architecture
+
+```
+Query  ──►  Strategy Classifier  ──►  4 Parallel Channels:
+                                       ├── Semantic (Fisher-Rao graduated similarity)
+                                       ├── BM25 (keyword matching, k1=1.2, b=0.75)
+                                       ├── Entity Graph (spreading activation, 3 hops)
+                                       └── Temporal (date-aware retrieval)
+                                                    │
+                                       RRF Fusion (k=60)
+                                                    │
+                                       Scene Expansion + Bridge Discovery
+                                                    │
+                                       Cross-Encoder Reranking
+                                                    │
+                                       ◄── 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.
+
+---
+
+## Quick Start
+
+### Install via npm (recommended)
+
+```bash
+npm install -g superlocalmemory
+slm setup
+```
+
+### Install via pip
+
+```bash
+pip install superlocalmemory
+# or with all features:
+pip install "superlocalmemory[full]"
+```
+
+### First Use
+
+```bash
+# Store a memory
+slm remember "Alice works at Google as a Staff Engineer"
+
+# Recall
+slm recall "What does Alice do?"
+
+# Check status
+slm status
+
+# Switch modes
+slm mode a   # Zero-LLM (default)
+slm mode b   # Local Ollama
+slm mode c   # Full power
+```
+
+### MCP Integration (Claude, Cursor, etc.)
+
+Add to your IDE's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "superlocalmemory": {
+      "command": "slm",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+24 MCP tools available: `remember`, `recall`, `search`, `fetch`, `list_recent`, `get_status`, `build_graph`, `switch_profile`, `health`, `consistency_check`, `recall_trace`, and more.
+
+---
+
+## V3 Engine 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
+
+### 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
+
+### Trust & Compliance
+- 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
+
+---
+
+## 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** | **~78%** | 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.*
+
+---
+
+## Research Papers
+
+### V3: Information-Geometric Foundations
+> **SuperLocalMemory V3: Information-Geometric Foundations for Zero-LLM Enterprise Agent Memory**
+> Varun Pratap Bhardwaj (2026)
+> [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)
+
+---
+
+## Project Structure
+
+```
+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
+```
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+
+## Attribution
+
+Part of [Qualixar](https://qualixar.com) | Author: [Varun Pratap Bhardwaj](https://varunpratap.com)
+
+---
+
+<p align="center">
+  <sub>Built with mathematical rigor. Not in the race — here to help everyone build better AI memory systems.</sub>
+</p>