name: superlocalmemory description: "AI agent memory with mathematical foundations. Store, recall, search, and manage memories locally. Local data root; optional networked features have separate behavior." version: "4.1.25" author: "Varun Pratap Bhardwaj" license: AGPL-3.0-or-later homepage: https://superlocalmemory.com repository: https://github.com/qualixar/superlocalmemory triggers:

• remember something
• recall memory
• search memories
• memory status
• store fact
• agent memory
• local memory
• memory health
• save a picture
• save a PDF
• message another bot

SuperLocalMemory

AI agent memory with a local data root. Five candidate producers (semantic, BM25, temporal, spreading-activation, Hopfield) fuse via RRF, with an entity-graph post-fusion score enhancement — all with mathematical similarity scoring. Mode A operates without sending memory content to a cloud model provider; optional connectors, backup, and proxy providers are explicit choices with separate behavior.

Installation

pip install superlocalmemory
# or
npm install -g superlocalmemory

Quick Start

slm remember "Alice works at Google as a Staff Engineer" --json
slm recall "Who is Alice?" --json
slm status --json

Commands

All data-returning commands support --json for structured agent-native output.

Memory Operations

slm remember "<content>" --json           # Store a memory
slm remember "<content>" --tags "a,b" --json
slm recall "<query>" --json               # Semantic search
slm recall "<query>" --limit 5 --json
slm list --json -n 20                     # List recent memories
slm forget "<query>" --json               # Preview matches (add --yes to delete)
slm forget "<query>" --json --yes         # Delete matching memories
slm delete <fact_id> --json --yes         # Delete specific memory by ID
slm update <fact_id> "<content>" --json   # Update a memory

Pictures, documents and folders (4.1.25, optional)

Off by default. Needs a computer with 16 GB of memory and downloads about 1.5 GB. Ask the user before turning it on.

slm media status --json                   # is it on, and how is set-up going
slm media enable                          # asks first; --yes skips the question (only with the user's yes)
slm media disable                         # memories are kept
slm media repair --dry-run                # count pictures that cannot be found by what they show yet
slm sources add ~/Notes --kind obsidian   # or --kind folder; read-only; shows what would be read, then asks
slm sources list --json

When it is on, a normal slm recall also returns saved pictures and PDF pages (a media block per result). The MCP tools are remember_media, remember_document, get_media, media_status and, for web apps, media_upload_link; they are listed only in the full, power and whole tool sets. A picture is up to 25 MB, a PDF up to 100 MB and 500 pages. Do not save a file that shows a secret. The slm-media skill has the details.

Company mode and the dashboard key

slm team status --json                    # Require login: on|off, user count
slm team policy --require-login on|off    # on the SLM computer; only when the user asks
slm token show                            # the key the dashboard asks for in strict mode; a secret, never paste it into chat

Diagnostics

slm status --json                         # System status (mode, profile, DB)
slm health --json                         # Math layer health
slm trace "<query>" --json                # Recall with per-channel breakdown

Configuration

slm mode --json                           # Get current mode
slm mode a --json                         # Set mode (a=local, b=ollama, c=cloud)
slm profile list --json                   # List profiles
slm profile switch <name> --json          # Switch profile
slm profile create <name> --json          # Create profile
slm connect --json                        # Auto-configure IDEs
slm connect --list --json                 # List supported IDEs

Bounded Loops

slm loop demo                             # Run built-in convergence demo (no API key needed)
slm loop history [--name <loop-name>]     # List recorded runs from SLM memory
slm loop show <run_id>                    # Show every lap of one run

Loop laps are persisted to SLM memory under the tag loop:<name>. MCP tools slm_loop_run, slm_loop_history, and slm_loop_show are available in the code and full profiles.

Services (no --json)

slm setup                                 # Interactive setup wizard
slm mcp                                   # Start MCP server (for IDE integration)
slm dashboard                             # Open web dashboard
slm warmup                                # Pre-download embedding model

JSON Envelope

Every --json response follows a consistent envelope:

{
  "success": true,
  "command": "recall",
  "version": "4.0.0",
  "data": {
    "results": [
      {"fact_id": "abc123", "score": 0.87, "content": "Alice works at Google"}
    ],
    "count": 1,
    "query_type": "semantic"
  },
  "next_actions": [
    {"command": "slm list --json", "description": "List recent memories"}
  ]
}

Error responses:

{
  "success": false,
  "command": "recall",
  "version": "4.0.0",
  "error": {"code": "ENGINE_ERROR", "message": "Description of what went wrong"}
}

Operating Modes

Dual Interface

SuperLocalMemory works via both MCP and CLI:

• MCP: 38 tools (code profile), 57 (full, the default; 62 with pictures and documents on) for IDE integration (Claude Code, Cursor, Windsurf, VS Code, JetBrains, Zed); includes bounded-loop tools slm_loop_run/history/show, bot-message tools mesh_peers, mesh_send, mesh_inbox, mesh_wait (a connected web app passes each reply's ack_ids back as ack) and mesh_state
• CLI: commands with --json for scripts, CI/CD, and agent frameworks; includes slm loop demo/history/show

Part of Qualixar | Author: Varun Pratap Bhardwaj (qualixar.com | varunpratap.com)

The governed memory brain for every AI agent. It lives on your machine. It never bluffs.

One memory for every agent you and your team use — Claude Code, Codex, Cursor, Copilot, Antigravity, Hermes, ChatGPT, Claude on the web, Grok Bot, Muse and any harness that speaks MCP or runs a command. Decisions, documents, screenshots and PDFs, recalled the way you ask for them, governed like company data, shared through a mesh where your local agents and web bots talk to each other, and answered honestly: when the answer isn't there, your agent hears "That isn't in SuperLocalMemory." — not a confident guess.

Install · See it work · Full demo · Every capability · Docs · Website

Agents forget everything between sessions. The usual fix — a vector store with a save button — makes it worse: it always returns something, even when nothing it holds answers the question, and your agent builds on it. This is a memory brain, not a bucket: it understands what was saved (who, what, when, which project), keeps it true over time, governs who may see it, and refuses to bluff. Four arXiv papers describe how it works.

In Mode A, core remember and recall make no model-provider call: no API key, no cloud account, no Docker. Anything that sends data out is a choice you make, and the docs say exactly what goes.

Install

The easiest way: let your AI agent install it. Copy the block below into Claude Code, Codex, Cursor or any agent that can run commands. It reads the setup guide, asks you one question, sets everything up and tells you what works. No terminal commands for you to learn.

Install SuperLocalMemory on this computer for me. Follow
https://github.com/qualixar/superlocalmemory/blob/main/SETUP_FOR_AGENTS.md
step by step and show me what each step printed. Ask me only one question,
before turning on anything optional: whether I also want to find my pictures,
screenshots and PDFs by describing them. Connect SuperLocalMemory to the agent
I am using. When you finish, run slm doctor and tell me in plain words what works.

No AI agent? One line in Terminal (macOS and Linux). It brings its own Python, sets everything up, connects the AI tools it finds and opens the dashboard; no Python or npm needed beforehand:

curl -fsSLo get-slm.sh https://raw.githubusercontent.com/qualixar/superlocalmemory/main/scripts/get-slm.sh && sh get-slm.sh

Add pictures and documents from the start with sh get-slm.sh --media at the end. It downloads the script first, so you can read it before it runs. Windows: use the agent prompt above, or npm or pip below.

Prefer the terminal? Both routes end in the same setup: your text memory on this machine, and, if you say yes, your pictures and documents too.

npm, the primary route (Node 18+). It installs SLM into a package-owned virtual environment:

npm install -g superlocalmemory   # add --media to also turn on pictures and documents
slm setup                         # pick Mode A to keep everything on this machine
slm connect claude-code           # or codex, cursor, windsurf, zed, claude-desktop, jetbrains, opencode ...

pip, the other primary route (Python 3.12 to 3.14), in a Python virtual environment you activate:

python3 -m venv .venv
source .venv/bin/activate         # Windows: .venv\Scripts\activate
python -m pip install superlocalmemory   # or, without a venv: pipx install superlocalmemory
slm setup
slm connect claude-code
slm media enable                  # optional: pictures and documents (about 1.5 GB; needs 16 GB of memory)

Claude Code plugin: claude plugin marketplace add qualixar/superlocalmemory, then claude plugin install superlocalmemory@qualixar. Codex: slm connect codex, then slm codex install.

Two models, one memory. Text is searched with a small local text model (nomic). If you turn on pictures and documents, a second local model (Google's EmbeddingGemma 2) reads them, and one recall returns both. The picture model unloads after 30 minutes without use, so it holds no memory while you only work with text. Details: pictures and documents, getting started, agent setup steps.

Repository clone: ./scripts/install.sh install (macOS, Linux) or .\scripts\install.ps1 -Action Install (Windows). Runs on Windows, Linux and Apple Silicon macOS (platforms).

30-second example

$ slm remember "We deploy the API blue-green; rollback is a DNS flip." --kind decision
Queryable ✓ 1 facts
$ 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.

$ slm recall "zxqv plorth wimble"
  That isn't in SuperLocalMemory.

$ slm remember "Staging DB moved to Postgres 17 on port 5434." --replaces <id>
Replaced ✓ 1 fact(s). To undo: 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. Scores rank memories; they are not probabilities.

Why SuperLocalMemory: twelve superpowers

1. It knows when it doesn't know. Every recall comes back in one of three tiers: a supported answer; the closest memories, labelled "I don't have this exactly — here are the closest memories"; or "That isn't in SuperLocalMemory." for nonsense. Just after a start it says it is still warming up and shows what it has found, so you never hear "empty" when the truth is "not ready yet". Your agent stops building on the wrong memory.

2. A second opinion that never leaves your Mac. On Apple Silicon, SLM installs Laya, a small on-device model that judges whether the memories found actually answer the question. Prefer the cloud, or not on a Mac? Jev does the same check online, only after you tick its consent.

3. Your documents and screenshots become a knowledge base you can ask. Save a photo, a screenshot or a PDF and find it weeks later by describing it — "the slide with the quarterly numbers". The picture model is Google's EmbeddingGemma 2, running on your computer: one model reads both your words and your pictures, so a description finds the image. OCR runs locally too, every PDF page is indexed by its picture and its text, and every answer cites its file and page. No generative model ever looks at your files.

4. Karpathy's LLM-wiki idea, built in — with search kept. Andrej Karpathy's LLM-wiki pattern turns raw documents into an organised knowledge base with an index and a health check. SLM does that from the data it already stores — a document index of every file with its people, projects and dates, and a document health check that finds empty pages, unlinked documents, duplicate pages and contradicted facts — while keeping real hybrid search for the moment you need to find something.

5. It looks after itself. Memory health describes your older memories in the background — dates, names, projects, kinds — only ever by adding, never touching what you wrote. Anything that moves or deletes waits for your Fix, and Undo puts it back.

6. Governed, not just stored. Every save passes an admission check and gets a receipt. Every read respects roles, workspaces and scopes. Every erasure reaches every copy — summaries, caches, indexes, picture mirrors — and comes with a verifiable receipt. Every action lands in a hash-chained audit trail. Built for tea