io.github.varun369/superlocalmemory

Why SuperLocalMemory?

Every hosted AI memory platform — Mem0 Cloud, Zep Cloud, Letta Cloud, EverMemOS Cloud — sends your data to cloud LLMs by default. Self-hosted variants exist but require Docker, a separate graph DB, or Ollama config, and most default to OpenAI until you flip env vars. After August 2, 2026, any of those cloud paths becomes a compliance question under the EU AI Act.

SuperLocalMemory V3 uses mathematics instead of cloud compute — differential geometry, algebraic topology, and stochastic analysis replace the work other systems need LLMs to do. Local-first out of the box. No Docker. No graph DB. No API keys. CPU-only.

Benchmark results (evaluated on LoCoMo, the standard long-conversation memory benchmark, published April 2026):

How to read this table. Scores from different papers use different LoCoMo splits, judge models, and prompt variants. We do NOT claim these numbers are apples-to-apples across rows. Rows marked "In-house" were run by us; cited rows link to the vendor's public source and date. The only apples-to-apples comparison is Mode A 74.8% vs Mem0 zero-retrieval-LLM 64.2% (+10.6pp) — both are zero-LLM configurations. Mem0's 91.6% and EverMemOS's 93.05% use cloud LLMs; Mode C uses a local LLM (Ollama).

What Mode A is: CPU-only, SQLite-only, zero-LLM retrieval on published LoCoMo questions. To the best of our knowledge it is the only publicly-released local-first memory that clears Mem0's zero-LLM baseline on this benchmark. If another fully-local system hits similar numbers, please open an issue so we can update this table.

Mathematical layers contribute +12.7 percentage points average across 6 conversations (n=832 questions), with up to +19.9pp on the most challenging dialogues.

Quick Start

# npm (recommended)
npm install -g superlocalmemory
slm setup       # Choose mode (A/B/C)
slm doctor      # Verify everything is working

# pip
pip install superlocalmemory
slm setup
slm doctor

# First use
slm remember "Alice works at Google as a Staff Engineer"
slm recall "What does Alice do?"
slm status

# Wrap your agent — starts proxy + sets environment + launches agent
slm wrap claude
# Your first repeat prompt → CACHE HIT → $0.00
# See savings: slm optimize savings --since 1

Upgrading: pip install -U superlocalmemory && slm restart && slm doctor — migration is automatic, no data loss.

Three Pillars

Memory

<a id="dual-interface-mcp--cli"></a>

Five-channel hybrid retrieval: Semantic (Fisher-Rao geodesic distance) + BM25 + Entity Graph + Temporal + Hopfield (associative/partial-query completion). RRF fusion, cross-encoder reranking, adaptive LightGBM ranking. All data stays local — SQLite + optional LanceDB/CozoDB.

Three mathematical contributions replace cloud LLM dependency:

1. Fisher-Rao Retrieval Metric — similarity scoring from the Fisher information structure of diagonal Gaussian families. To the best of our knowledge, the first public application of information geometry to agent memory retrieval.
2. Sheaf Cohomology for Consistency — algebraic topology detects contradictions via coboundary norms on the knowledge graph.
3. Riemannian Langevin Lifecycle — memory positions evolve on the Poincare ball; neglected memories self-archive, no hardcoded thresholds.

Auto-capture hooks (slm hooks install) fire only on real signals — topic pivot, web call, file edit — never on a timer. Fail-open, <10ms p99 hot path.

Multi-scope memory (v3.6.15, opt-in): keep memories personal (default), shared with named profiles, or global across the machine. Off by default — recall only ever returns your own facts until you turn sharing on, per call or in config. See docs/shared-memory.md.

<a id="multilingual-embedding-support"></a>

Multilingual: plug in any OpenAI-compatible embedding endpoint — Ollama, vLLM, LiteLLM, bge-m3, multilingual-e5, Qwen3-Embedding. The math layer is language-agnostic; 30+ languages work at full retrieval quality. No cloud dependency, no code changes.

Cache + Compress

<a id="three-surfaces-proxy--mcp-tools--skill"></a>

One engine, three ways in — choose the surface that fits your setup:

The hard constraint: The primary Claude conversation turn cannot be cached without a proxy. The MCP/skill path caches results you explicitly route through SLM (tool outputs, file reads, sub-model calls) — without a proxy the main conversation turn is not intercepted.

How to choose:

• Metered API (pay-per-token), want every call cached → Proxy (A)
• Pro/Max/Team subscription or any plan where you won't run a proxy → MCP tools (B) or Skill (C)
• Zero configuration → Skill (C): install once, auto-compresses CLAUDE.md and large outputs
• Agent-controlled caching of repeated file reads → MCP tools (B)

Cache: exact-match SQLite lookup (SHA-256, zero false hits) + vCache-gated semantic (opt-in). 100% cost saved on a hit (input + output tokens).

Compress: safe mode = lossless normalization (JSON/code/tool outputs, 60-95% fewer tokens); aggressive mode = LLMLingua-2 prose only (opt-in). CCR stores originals for byte-exact reversal. Anthropic 90% / OpenAI 50% prefix-cache discount alignment included. [CITATION-NEEDED-ONLINE: live provider prefix-cache discount rates]

Savings dashboard: slm optimize savings --since 7 — live USD/INR/tokens saved. Hot-reload config, fail-open.

Mesh

<a id="multi-machine-mesh-coordination"></a>

Run SLM on multiple machines and have agents coordinate as one team — no external broker, no Docker. HTTP-based sync every 30s, mDNS discovery (SLM_MESH_DISCOVERY=on), graceful offline queue.

# Machine A (broker)
export SLM_MESH_HOST=192.168.1.100
export SLM_MESH_SHARED_SECRET=my-secret-key
slm init

# Machine B (client)
export SLM_MESH_PEER_URL=http://192.168.1.100:8765
export SLM_MESH_SHARED_SECRET=my-secret-key
slm init

8 mesh MCP tools: mesh_peers, mesh_send, mesh_broadcast, mesh_project, mesh_inbox, mesh_pending, mesh_state, mesh_lock.

Full docs: docs/multi-machine.md · docs/distributed-deployment.md

Install Paths

After any install path: slm setup → slm doctor → slm warmup (optional, pre-downloads ~500MB embedding model).

MCP + Profiles

SLM supports two MCP transports:

HTTP (recommended, v3.6.7+):

{ "mcpServers": { "superlocalmemory": { "type": "http", "url": "http://127.0.0.1:8765/mcp/" } } }

Or: claude mcp add --transport http superlocalmemory http://127.0.0.1:8765/mcp/

stdio (universal fallback):

{ "mcpServers": { "superlocalmemory": { "command": "slm", "args": ["mcp"] } } }

MCP Profiles (WP-01)

Control tool surface via SLM_MCP_PROFILE:

Precedence: ALL > TOOLS > PROFILE > default

export SLM_MCP_PROFILE=full38   # or core14 / mesh8 / power50 / whole81
slm mcp

Per-IDE configs available for Claude Code, Cursor, Windsurf, VS Code Copilot, Continue, Gemini CLI, JetBrains, Zed, and more (15 configs in ide/configs/). See docs/ide-setup.md.

Claude Code Plugin

Install directly in Claude Code — no system-level npm/pip needed. This is how you get the skills, agents, hooks, commands, and rules (the MCP server is bootstrapped automatically). It is a two-step flow — add the marketplace once, then install:

# 1. Add the Qualixar marketplace (one-time — the repo IS the marketplace)
/plugin marketplace add qualixar/superlocalmemory

# 2. Install the plugin
/plugin install superlocalmemory@qualixar

• Self-bootstraps a Python venv, installs all deps in an isolated SLM_DATA_DIR
• Registers the 14-tool core MCP surface (core14 profile by default)
• Ships the SLM skills / agents / hooks / commands / rules
• Additive — does not replace an existing SLM install
• slm connect claude-code detects an existing plugin install and links them

Plugin vs pip/npm: pip install superlocalmemory / npm i -g superlocalmemory give you the slm CLI + the MCP server (the tools). The skills/agents/hooks/ commands come only through the plugin above. Use the plugin for Claude Code; use pip/npm for the CLI or other IDEs.

To update later: /plugin marketplace update qualixar then /plugin install superlocalmemory@qualixar.

Modes + EU AI Act

<a id="eu-ai-act-compliance"></a>

slm mode a   # Zero-cloud (default)
slm mode b   # Local Ollama
slm mode c   # Cloud LLM

Mode A is, to the best of our knowledge, the only publicly-released agent memory that runs with zero cloud calls while clearing Mem0's published LoCoMo score. All data stays on your device. No API keys. No GPU. Runs on 2 vCPUs + 4GB RAM.

The EU AI Act (Regulation 2024/1689) takes full effect August 2, 2026.

To the best of our knowledge, no existing agent memory system addresses EU AI Act compliance by architectural design. Modes A and B pass all checks — no personal data leaves the device during any memory operation.

Built-in compliance tools: GDPR Article 15/17 export + complete erasure, tamper-proof SHA-256 audit chain, data provenance tracking, ABAC policy enforcement. See docs/compliance.md.

Advanced

Web dashboard:

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

17-tab sidebar with Knowledge Graph (Sigma.js WebGL, community detection), Health Monitor, Entity Explorer, Mesh Peers, Ingestion Status, Privacy blur mode. Cross-platform: macOS + Windows + Linux.

Release history:

Research Papers

SuperLocalMemory is backed by three published research papers (arXiv preprints + Zenodo DOIs). These are preprints — not conference-accepted or journal-published yet.

Paper 3: The Living Brain (V3.3)

SuperLocalMemory V3.3: The Living Brain — Biologically-Inspired Forgetting, Cognitive Quantization, and Multi-Channel Retrieval for Zero-LLM Agent Memory Systems Varun Pratap Bhardwaj (2026) arXiv:2604.04514 · Zenodo DOI: 10.5281/zenodo.19435120

Paper 2: Information-Geometric Foundations (V3)

SuperLocalMemory V3: Information-Geometric Foundations for Zero-LLM Enterprise Agent Memory Varun Pratap Bhardwaj (2026) arXiv:2603.14588 · Zenodo DOI: 10.5281/zenodo.19038659

Paper 1: Trust & Behavioral Foundations (V2)

SuperLocalMemory: A Structured Local Memory Architecture for Persistent AI Agent Context Varun Pratap Bhardwaj (2026) arXiv:2603.02240 · Zenodo DOI: 10.5281/zenodo.18709670

Cite This Work

@article{bhardwaj2026slmv33,
  title={SuperLocalMemory V3.3: The Living Brain — Biologically-Inspired
         Forgetting, Cognitive Quantization, and Multi-Channel Retrieval
         for Zero-LLM Agent Memory Systems},
  author={Bhardwaj, Varun Pratap},
  journal={arXiv preprint arXiv:2604.04514},
  year={2026},
  url={https://arxiv.org/abs/2604.04514}
}

@article{bhardwaj2026slmv3,
  title={Information-Geometric Foundations for Zero-LLM Enterprise Agent Memory},
  author={Bhardwaj, Varun Pratap},
  journal={arXiv preprint arXiv:2603.14588},
  year={2026}
}

@article{bhardwaj2026slm,
  title={A Structured Local Memory Architecture for Persistent AI Agent Context},
  author={Bhardwaj, Varun Pratap},
  journal={arXiv preprint arXiv:2603.02240},
  year={2026}
}

Support / License / Qualixar

See CONTRIBUTING.md for guidelines. Wiki for detailed documentation.

GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE.

For commercial licensing (closed-source, proprietary, or hosted use), see COMMERCIAL-LICENSE.md or contact varun.pratap.bhardwaj@gmail.com.

Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar.

Part of Qualixar · Author: Varun Pratap Bhardwaj

Acknowledgments

• Everything Claude Code (ECC) — SLM's skill observation patterns were inspired by ECC's continuous learning architecture. SLM supports direct ingestion of ECC observations via slm ingest --source ecc. We recommend ECC for Claude Code users who want the deepest learning experience alongside SLM.
• HKUDS/OpenSpace — The skill evolution research in SLM draws from the EvoSkills co-evolutionary verification concepts (arXiv:2604.01687). We adopted their 3-trigger evolution system and anti-loop guard patterns.

Qualixar AI Agent Reliability Platform

Qualixar is building the open-source infrastructure for AI agent reliability engineering. Seven products, one coherent platform:

Zero cloud dependency. Local-first. EU AI Act compliant.

Start here → qualixar.com · All papers on Qualixar HuggingFace

Star This Project

If this project solves a real problem for you, please star the repo — it helps other developers discover Qualixar and signals that the AI agent reliability community is growing.