SuperLocalMemory V3

Information-Geometric Agent Memory with Mathematical Guarantees

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.

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 before upgrading. Backup is created automatically.

Key Results

Three Operating Modes

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.

Prerequisites

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.

What Gets Installed Automatically

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.

Quick Start

Install via npm (recommended — one command, everything included)

npm install -g superlocalmemory

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

Then configure and pre-download the embedding model:

slm setup     # Choose mode, configure provider
slm warmup    # Pre-download embedding model (~500MB, optional)

First time? If you skip slm warmup, the model downloads automatically on first slm remember or slm recall. Either way works.

Install via pip

pip install superlocalmemory
# or with all features:
pip install "superlocalmemory[full]"

First Use

# 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:

{
  "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.

Web Dashboard (17 tabs)

slm dashboard    # Opens at http://localhost:8765

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.

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 (Long Conversation Memory):

Mode A Ablation (conv-30, 81 questions, zero-LLM)

Competitive Landscape

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

V2: Architecture & Engineering

SuperLocalMemory: A Structured Local Memory Architecture for Persistent AI Agent Context Varun Pratap Bhardwaj (2026) arXiv:2603.02240 | Zenodo DOI: 10.5281/zenodo.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 for guidelines.

License

MIT License. See LICENSE.

Attribution

Part of Qualixar | Author: Varun Pratap Bhardwaj

_{Built with mathematical rigor. Not in the race — here to help everyone build better AI memory systems.}