SuperLocalMemory: local-first memory for AI agents

Claude Code, Codex, Cursor and other MCP clients lose what they learned when a session ends. SuperLocalMemory (SLM) gives them one long-term memory that lives on your machine, and it can tell you when it doesn't have the answer instead of guessing.

npm install -g superlocalmemory   # primary route (Node 18+, Python 3.12+); or: pipx install superlocalmemory
slm setup                         # pick Mode A to keep everything on this machine
slm connect cursor                # or claude-code, codex, windsurf, zed ... 12 IDEs

npm installs SLM into a package-owned virtual environment. The other primary route is pip in a Python virtual environment you activate: python3 -m venv .venv, activate it, then python -m pip install superlocalmemory. Repository clone: ./scripts/install.sh install (macOS, Linux) or .\scripts\install.ps1 -Action Install (Windows); see CONTRIBUTING.md.

Runs on Apple Silicon macOS, 64-bit Windows and 64-bit Linux; Intel Mac and 32-bit Windows are not supported (the pinned cryptography has no build for them). No Docker, no required graph database, no API key.

30-second example

$ slm remember "We deploy the API blue-green; rollback is a DNS flip." --kind decision
Queryable ✓ 1 facts (operation=ebca8e80...).
$ slm remember "Always run the migration dry-run before a release." --kind rule
$ slm remember "Staging DB is Postgres 16 on port 5433."

$ slm recall "how do we roll back the API"
  1. [0.67] We deploy the API blue-green; rollback is a DNS flip.
  2. [0.53] Always run the migration dry-run before a release.
  3. [0.52] Staging DB is Postgres 16 on port 5433.

$ slm recall "what did we decide about rollback" --kind decision
  1. [0.54] We deploy the API blue-green; rollback is a DNS flip.

$ slm remember "Staging DB moved to Postgres 17 on port 5434." --replaces 0f57a17af3dd46e5
Replaced ✓ 1 fact(s) of 0f57a17af3dd46e5.
To undo, run:
  slm review-correction ... rollback 1
$ slm recall "which port does staging postgres use"
  1. [0.68] Staging DB moved to Postgres 17 on port 5434.

Real output from a fresh Mode A install, trimmed. The id comes from slm recall --json. Scores are ranking signals, not probabilities. Right after a start, the embedding model is still loading: recall still answers from keyword and time channels and says Incomplete search until the model is ready.

Why SuperLocalMemory

• Local-first by default. Memory lives in SQLite on your disk. In Mode A, core remember and recall make no model-provider call. Anything that sends data out is a choice you make, and the docs say exactly what goes.
• It says "I don't have that." The optional answer check judges whether the top results actually answer the question, on your Mac or through Jev, and flags it when they don't.
• Memory with a sense of time. Every fact records when it happened and when SLM learned it. Ask what was true last month (--valid-at), or what SLM knew before a date (--known-as-of). Replaced facts stop being served as current.
• One memory, every agent. The same store serves Claude Code, Codex, Cursor, Windsurf, Hermes and any MCP client, so a decision saved in one tool is there in the next.

SLM is part of Qualixar's AI Reliability Engineering work: agent memory that is observable, bounded and honest about what it doesn't know.

Works with your agents

On Claude Code, slm connect claude-code points you to the plugin: claude plugin marketplace add qualixar/superlocalmemory, then claude plugin install superlocalmemory@qualixar.

Everything SLM does

MCP memory server: tool profiles

Pick how many tools your agent sees with SLM_MCP_PROFILE. Counts come from the server itself.

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

For stdio clients use {"command": "slm", "args": ["mcp"]}. An unknown profile name stops startup and lists the valid ones.

Answer Check: memory that says "I don't have that"

Relevance and "does this answer it" are different questions. The closest memory on file can still be the wrong answer, and an agent that treats it as the answer makes things up with confidence.

Answer check adds a second step after ranking. It reads the top results and decides whether they answer the question. Choose one, in Settings → Answer check in the dashboard:

• On this Mac (Laya): a small model, about 1.1 GB, on Apple Silicon. Nothing leaves the machine.
• Online with Jev: TypeSafe or OpenRouter, with your own key and an explicit consent box. Sends the question and the top 3 memories.
• Off.

Only one runs at a time, and nothing turns the online option on by itself. Each option shows whether it is ready, has a Test button, and is applied live with one Save. Results are never hidden: recall returns them with abstained and abstention_reason set, and your agent decides what to do. The same question gets the same verdict on a repeat. The Answer Check tab shows each verdict, its timing against the 3-second recall ceiling, and how often it said "I don't have that" over 24 hours, 7 days or 30 days. The history keeps outcomes and timings, never your questions or memory text.

Privacy and security

What leaves your machine, and when:

Model downloads (embedding model, Laya) fetch files but send no memory content. Credentials found in memory text are redacted on every outbound path, and a provider's key goes only to that provider.

Since 4.1.20, other computers must authenticate to read memory, not only to write it. SLM ignores forwarded-for headers unless you name a trusted proxy, so a proxy can't make a remote caller look local. SLM's own outbound requests never follow redirects, and the remote listener never answers with one, so a key is never sent through a redirect. Remote callers never see this computer's paths, account or environment outside the memories themselves. Remote agents connect through slm remote: TLS only, one named key per client, each key bound to one profile (its holder reads that profile's memories in full and nothing else), read-only keys available, and slm remote keys revoke <name> takes effect on the next request. See Remote access, Security policy and encryption at rest.

Benchmarks (V3)

These numbers come from the published V3 architecture paper, which V4 still runs. They are not a fresh V4 package run.

Method, category breakdown and ablations: docs/benchmarks.md and arXiv:2603.14588. A LoCoMo score is comparable only when the subset, answer model and judge match.

Research

SLM's design is described in the V4 paper, SuperLocalMemory 4.0: The Governed Memory Operating System for AI Agents (DOI 10.5281/zenodo.21853302). Earlier preprints: information-geometric foundations, V3, the Living Brain, V3.3, and trust and behavioural foundations, V2. Cite it with CITATION.cff or GitHub's "Cite this repository" button:

@article{bhardwaj2026superlocalmemory,
  title   = {SuperLocalMemory 4.0: The Governed Memory Operating System for AI Agents},
  author  = {Bhardwaj, Varun Pratap and Singh, Garima and Bhardwaj, Arun Pratap},
  journal = {arXiv preprint arXiv:2608.08253},
  year    = {2026},
  doi     = {10.5281/zenodo.21853302}
}

Upgrade

pipx upgrade superlocalmemory     # or: npm update -g superlocalmemory
slm restart && slm doctor
slm upgrade-hosts                 # preview IDE and plugin updates; nothing changes until you --apply

Upgrades never move or delete memory, and an update that changes the store takes a restore point first. Plugin updates follow your editor; see host upgrades.

Contributing and license

Issues and pull requests are welcome; start with CONTRIBUTING.md. Report vulnerabilities through SECURITY.md. Release notes are in CHANGELOG.md.

SLM is licensed under AGPL-3.0-or-later. For a commercial license, see COMMERCIAL-LICENSE.md. Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar. Website: superlocalmemory.com.