# SuperLocalMemory — release-linked product context

SuperLocalMemory is a local-first agent-memory project by Varun Pratap Bhardwaj under the Qualixar AI Reliability Engineering research initiative. The source and package are licensed AGPL-3.0-or-later.

The current SuperLocalMemory product generation is 4.0.

## Operating modes and data paths

- Mode A runs core storage and retrieval against the configured local data root without a cloud model-provider call.
- Mode B adds an operator-configured Ollama endpoint. Its locality depends on where that endpoint runs.
- Mode C sends configured query or enrichment content to a cloud model provider.
- In every mode, optional connectors, cloud backup, proxies, model downloads, and dependency acquisition can use the network.

These modes are technical controls, not legal certifications. Regulatory status depends on the use case, operator, configuration, data flows, providers, and surrounding systems.

## Storage and retrieval

Core memory is SQLite-backed. The full data root can also contain configuration, logs, queues, models, derived indexes, caches, and optional backend state; copying only `memory.db` is not a complete backup contract.

The current recall architecture has five candidate producers: dense semantic, BM25 lexical, temporal, Hopfield associative, and spreading activation. Candidate fusion is followed by optional reranking and graph-based score enhancement. Dense candidate generation uses cosine similarity; Fisher-derived terms can inform later scoring. SQLite and sqlite-vec remain canonical. CozoDB and LanceDB are optional parity-gated projections, not automatic replacements for the canonical store.

V4 governs canonical writes through admission and policy control, durable per-store obligations, and a hash-sealed completion manifest. The operation is complete only when its declared representations are applied; a partial operation is surfaced as degraded for operator remediation.

The score contract separates query-relative `relevance_score`, internal diagnostic `ranking_score`, stored `memory_confidence`, and evidence-policy `trust_score`. Retrieval ordering is not answer probability. Until a held-out calibrator is frozen, canonical responses report `score_contract_version: "2"`, `calibration_status: "uncalibrated"`, `calibration_id: null`, and `answer_confidence: null`.

## Cache and compression

Exact caching is available only when Optimize/proxy caching is enabled. A cache hit can avoid the wrapped provider call, but the primary conversation is not intercepted on MCP-only or skill-only surfaces.

Safe compression uses conservative normalization, preserves JSON and code, and may produce no reduction. Aggressive prose compression is opt-in and lossy. Reversible CCR storage can retain an original for later byte-exact retrieval when enabled.

## Client surface

Run `slm connect --list` for the current documented client names. MCP-compatible clients can be configured manually, but a named template is not proof of a complete integration. The V4 release matrix requires install, session, remember, recall, update, forget, restart, upgrade, and artifact checks before publishing a verified count.

## Research evidence

The project has four public arXiv preprints with code-linked experiments. They are preprints, not conference-accepted or journal-published papers.

1. SuperLocalMemory 4.0: The Governed Memory Operating System for AI Agents — https://arxiv.org/abs/2608.08253; companion Zenodo record https://zenodo.org/records/21853302; DOI https://doi.org/10.5281/zenodo.21853302.
2. Privacy-Preserving Multi-Agent Memory with Bayesian Trust Defense Against Memory Poisoning — https://arxiv.org/abs/2603.02240
3. Information-Geometric Foundations for Zero-LLM Enterprise Agent Memory — https://arxiv.org/abs/2603.14588
4. The Living Brain: Biologically-Inspired Forgetting, Cognitive Quantization, and Multi-Channel Retrieval — https://arxiv.org/abs/2604.04514


Published V3 LoCoMo evidence carried into V4: Mode A Raw scored 60.4% across 10 conversations / 1,276 questions with zero-LLM answer construction; Mode A Retrieval scored 74.8% across the same scope with local retrieval and GPT-4.1-mini answer synthesis; Mode C scored 87.7% on Conv-30 / 81 questions with cloud embeddings and GPT-4.1-mini answer generation and judge. The paper also reports 71.7% with information-geometric layers versus 58.9% without them across six conversations (+12.7pp).

These figures retain their published V3 protocol scope and are carried into V4 architecture messaging. They are not a newly rerun V4 package benchmark; Mode C is not a full-dataset result.

## Installation

- npm CLI: `npm install -g superlocalmemory` creates a package-owned Python environment.
- Python CLI: `pipx install superlocalmemory` or `uv tool install superlocalmemory`.
- Python library: install with pip inside a project virtual environment.

## Links

- Website: https://superlocalmemory.com
- Source: https://github.com/qualixar/superlocalmemory
- Wiki: https://github.com/qualixar/superlocalmemory/wiki
- Research: https://superlocalmemory.com/research
- PyPI: https://pypi.org/project/superlocalmemory/
- npm: https://www.npmjs.com/package/superlocalmemory