superlocalmemory 4.1.20 → 4.1.22

package/README.md

@@ -5,15 +5,28 @@
   </picture>
 </p>
 
-# SuperLocalMemory: local-first memory for AI agents
+# SuperLocalMemory: governed, 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.
+Claude Code, Codex, Cursor and other MCP clients forget what they learned when a session ends. SuperLocalMemory (SLM) gives them one long-term memory that lives on your machine: it learns from use, enforces who may read and erase what, coordinates many agents, and says "I don't have that" instead of guessing.
+
+**Every recall is checked before your agent uses it.** A judge decides whether the memories found actually answer the question: **Laya** runs fully on your Mac, and **Jev** runs online on Windows, Linux and macOS. When they don't answer it, SLM says so instead of handing over a confident wrong answer: a hallucination guard for retrieval ([answer check](#answer-check-laya-and-jev)).
+
+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.
 
 [![PyPI](https://img.shields.io/pypi/v/superlocalmemory)](https://pypi.org/project/superlocalmemory/)
 [![npm](https://img.shields.io/npm/v/superlocalmemory)](https://www.npmjs.com/package/superlocalmemory)
+[![PyPI downloads](https://img.shields.io/pepy/dt/superlocalmemory?label=PyPI%20downloads)](https://pepy.tech/project/superlocalmemory)
+[![npm downloads](https://img.shields.io/npm/dt/superlocalmemory?label=npm%20downloads)](https://www.npmjs.com/package/superlocalmemory)
+[![GitHub stars](https://img.shields.io/github/stars/qualixar/superlocalmemory?style=flat&logo=github)](https://github.com/qualixar/superlocalmemory/stargazers)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](pyproject.toml)
 [![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)
-[![arXiv](https://img.shields.io/badge/arXiv-2608.08253-b31b1b)](https://arxiv.org/abs/2608.08253)
+[![Answer check: Jev · Laya](https://img.shields.io/badge/answer_check-Jev_%C2%B7_Laya-f97316)](#answer-check-laya-and-jev)
+[![arXiv V4](https://img.shields.io/badge/arXiv-2608.08253-b31b1b)](https://arxiv.org/abs/2608.08253)
+[![arXiv V3.3](https://img.shields.io/badge/arXiv-2604.04514-b31b1b)](https://arxiv.org/abs/2604.04514)
+[![arXiv V3](https://img.shields.io/badge/arXiv-2603.14588-b31b1b)](https://arxiv.org/abs/2603.14588)
+[![arXiv V2](https://img.shields.io/badge/arXiv-2603.02240-b31b1b)](https://arxiv.org/abs/2603.02240)
+
+**[Install](https://www.superlocalmemory.com/install)** · **[Product walkthrough](https://www.superlocalmemory.com/demo)** · **[Demo video](https://www.youtube.com/watch?v=PMWW_ypsL60)** · **[CLI proof](docs/QUICK_PROOF.md)** · **[Release notes](CHANGELOG.md)**
 
 ```bash
 npm install -g superlocalmemory   # primary route (Node 18+, Python 3.12+); or: pipx install superlocalmemory
@@ -23,7 +36,7 @@ slm connect cursor                # or claude-code, codex, windsurf, zed ... 12
 
 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](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.
+Runs on Windows, Linux and macOS ([platforms](#platform-support)). No Docker, no required graph database, no API key.
 
 ## 30-second example
 
@@ -49,14 +62,47 @@ $ 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.
+Real output from a fresh Mode A install, trimmed. Scores rank; they are not probabilities. While the embedding model loads, recall says `Incomplete search`.
+
+### Watch the product walkthrough
+
+[![Watch the SuperLocalMemory demo](https://img.youtube.com/vi/PMWW_ypsL60/hqdefault.jpg)](https://www.youtube.com/watch?v=PMWW_ypsL60)
+
+Five minutes: install, setup, recall, cache and compression.
+
+### The dashboard
+
+Captured from a real install in Mode A, with Laya running on the Mac and a store of fictional project memories. Nothing is mocked: each verdict, score and timing is what SLM returned.
+
+| Memories that answer the question | Memories that do not: "I don't have that" |
+|---|---|
+| ![Answer Check: Laya judges that the memories answer "When is Project Kestrel going live?" with confidence 0.85, in 1.4 s of the 3 s limit](docs/screenshots/dashboard-4.1.21/answer-check-answered.png) | ![Answer Check: for "How much did the Kestrel pilot cost?" Laya finds no memory that answers it and SLM says "I don't have that"](docs/screenshots/dashboard-4.1.21/answer-check-dont-have-that.png) |
+
+| Recall Lab: why each memory was chosen | Every memory with its kind and project |
+|---|---|
+| ![Recall Lab: per-channel scores for "what did we decide about the database"](docs/screenshots/dashboard-4.1.21/recall-lab.png) | ![Memories table filtered by kind: decisions, rules, corrections, facts, with the project each belongs to](docs/screenshots/dashboard-4.1.21/memories-kinds-projects.png) |
+
+![Saved views: a saved question that runs the same search your agent uses and shows the memory each result came from](docs/screenshots/dashboard-4.1.21/saved-views.png)
+
+## Why SuperLocalMemory: the moats
+
+A vector store answers "what is similar". AI agent memory must also answer: is this still true, who may see it, can it be erased with proof, and does the agent actually have the answer?
+
+**1. Governed memory, not a vector store.** Roles per workspace, personal / shared / global scopes with default-deny cross-profile recall, GDPR erasure with HMAC-verifiable receipts, retention rules and a hash-chained audit log. The [V4 paper](https://arxiv.org/abs/2608.08253) measures what the governed write path costs. Code: `src/superlocalmemory/access/`, `compliance/`.
+
+**2. A zero-LLM core built on published math.** Five retrieval channels, fusion and the learned ranker run without a language model; V3 scored 60.4% on LoCoMo with no LLM anywhere ([benchmarks](#benchmarks-v3)). Fisher-information scoring, sheaf contradiction detection and Langevin lifecycle dynamics added 12.7 points ([V3 paper](https://arxiv.org/abs/2603.14588)).
+
+**3. It says "I don't have that."** The [answer check](docs/answer-check.md) decides whether the top results answer the question, on your Mac (Laya) or online (Jev), and recall reports `abstained` instead of a confident wrong answer.
+
+**4. Memory that learns, and cannot quietly get worse.** A Thompson-sampling bandit tunes channel weights and a LightGBM ranker learns from reported outcomes. A retrained ranker is promoted only after a shadow A/B test on live recalls, and rolled back automatically if NDCG@10 drops 2% or more. Code: `learning/shadow_test.py`, `learning/model_rollback.py`.
 
-## Why SuperLocalMemory
+**5. 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`). Unused memories fade and lose vector precision ([V3.3 paper](https://arxiv.org/abs/2604.04514)).
 
-- **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](docs/answer-check.md) 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.
+**6. Many agents, one coordinated memory.** Every write records its agent, with Bayesian trust scores against poisoning ([V2 paper](https://arxiv.org/abs/2603.02240)). SLM-Mesh gives parallel sessions messages, locks and shared state.
+
+**7. "Done" means a gate passed.** Bounded loops repeat a task until an independent check (tests, a schema, a linter) passes, never on the agent's word, and store every lap as auditable memory.
+
+**8. Context you don't pay for twice.** Exact cache and reversible compression work through MCP tools or a skill, with no proxy, so your full context window stays intact.
 
 SLM is part of Qualixar's AI Reliability Engineering work: agent memory that is observable, bounded and honest about what it doesn't know.
 
@@ -64,73 +110,181 @@ SLM is part of Qualixar's AI Reliability Engineering work: agent memory that is
 
 | Surface | What you get | Docs |
 |---|---|---|
-| Editor plugins | Claude Code, Codex, VS Code / Copilot, Antigravity, Hermes. Each ships 12 skills, 4 sub-agents and session hooks | [IDE setup](docs/ide-setup.md), [Hermes](docs/hermes.md) |
-| `slm connect <ide>` | Writes the MCP config for 12 IDEs: Antigravity, Claude Code, Claude Desktop, Codex, Continue, Cursor, Gemini CLI, JetBrains, OpenCode, VS Code / Copilot, Windsurf, Zed | [IDE setup](docs/ide-setup.md) |
-| MCP | stdio (`slm mcp`) or HTTP at `http://127.0.0.1:8765/mcp/`, with tool profiles from 8 to 101 tools | [MCP tools](docs/mcp-tools.md) |
+| Editor plugins | Claude Code, Codex, VS Code / Copilot, Antigravity, Hermes. Each ships 14 skills, 4 sub-agents and session hooks | [IDE setup](docs/ide-setup.md), [Hermes](docs/hermes.md) |
+| `slm connect <ide>` | Writes the MCP config for 12 IDEs, including Cursor, Windsurf, Zed, JetBrains, Gemini CLI and Claude Desktop | [IDE setup](docs/ide-setup.md) |
+| MCP | stdio (`slm mcp`) or HTTP at `http://127.0.0.1:8765/mcp/`; profiles from 8 to 103 tools | [MCP tools](docs/mcp-tools.md) |
 | Framework adapters | LangGraph, LangChain, LlamaIndex, CrewAI, AutoGen, Semantic Kernel, Microsoft Agent Framework, Google ADK, OpenAI Agents | [Framework adapters](docs/framework-adapters.md) |
-| Python SDK and HTTP API | `MemoryEngine` in your own code; a local REST API behind the dashboard | [API reference](docs/api-reference.md) |
+| Python SDK and HTTP API | `MemoryEngine` in your code; the local REST API | [API reference](docs/api-reference.md) |
 | Auto-capture hooks | `slm hooks install` for Claude Code, `--agent codex` for Codex | [Auto-memory](docs/auto-memory.md) |
-| Other computers | `slm remote`: HTTPS listener with named, revocable keys for agents on another machine | [Remote access](docs/distributed-deployment.md#remote-access-over-tls-4120) |
-
-On Claude Code, `slm connect claude-code` points you to the plugin: `claude plugin marketplace add qualixar/superlocalmemory`, then `claude plugin install superlocalmemory@qualixar`.
+| Cursor-format plugin (Grok Bot, Cursor) | A marketplace-distributed plugin — different from `slm connect cursor` above — that runs on a shared, memory-tight computer with no hooks or dashboard | See below |
+
+Claude Code memory in two commands: `claude plugin marketplace add qualixar/superlocalmemory`, then `claude plugin install superlocalmemory@qualixar`.
+
+### Grok Bot (and other Cursor-format plugin hosts)
+
+Grok Bot runs plugins in Cursor's format: a `.cursor-plugin/plugin.json` manifest, not the
+`.claude-plugin/` one Claude Code reads. SuperLocalMemory ships both from one source, so the
+plugin works on Grok Bot's shared, memory-constrained computer without any manual MCP setup.
+
+**Install:** add the `qualixar` marketplace (`.cursor-plugin/marketplace.json` at this repo's
+root) in Grok Bot's Plugins screen, then add `superlocalmemory`. No API key, no sign-in step —
+the server runs locally on the Grok Bot computer, so nothing goes to a memory SaaS.
+*(The MCP server starts as `uvx --from superlocalmemory==<version> slm mcp`: a pinned,
+on-PATH command, with `UV_TORCH_BACKEND=cpu` so a GPU-less Linux box never pulls PyTorch's CUDA
+wheel stack. The first start resolves the package once; the first recall downloads the local
+embedding model once.)*
+
+**Try it:** tell any bot *"Remember that our Q4 theme is agent reliability."* Then open a
+different bot and ask *"What's our Q4 theme?"*
+
+**What's shared and what isn't:** every write is attributed to `SLM_AGENT_ID=cursor_plugin` —
+that is attribution, not an access boundary. If your bots share one `SLM_DATA_DIR` (the default
+on one Grok Bot computer), they share one memory store: anything stored without an explicit
+`scope` is visible to any bot that can reach that store, the same way two terminal sessions on
+one laptop would see each other's files. Mark a fact `scope=global` only when every bot on that
+computer should see it; a bot that genuinely needs private memory needs its own `SLM_DATA_DIR`.
+See the `slm-bot-memory` skill (ships with this plugin) for the full model, including what
+should never be stored on a computer shared with other bots (secrets, keys, other people's
+personal data).
+
+**Tools:** this plugin sets `SLM_MCP_PROFILE=core` — 18 tools (`remember`, `recall`, `search`,
+session lifecycle, compression/cache, corrections) — deliberately smaller than the 56-tool
+default profile every other host gets, so a shared computer is not listing tool descriptions
+for tiers it will not use.
+
+**Resources — the lite bot-host profile:** this plugin also sets `SLM_RERANKER_ENABLED=false`,
+`SLM_RERANKER_IDLE_TIMEOUT=120` and `SLM_MAX_EMBEDDING_WORKERS=1` by default, because the box is
+"shared by every bot on it" with as little as 1.8-3.5 GiB free. Measured on macOS, warm, after
+one remember and one recall: about 390 MB resident with the reranker on (daemon + reranker
+worker + embedding worker) vs. about 190 MB with it off — recall still runs every other channel
+(BM25, semantic, entity graph, temporal, spreading activation, Hopfield) and fuses them, just
+without the cross-encoder re-ordering pass. Set `SLM_RERANKER_ENABLED=true` in the plugin's env
+block to trade that RAM back for ranking precision, or run `slm serve stop` when a bot is done
+with it.
+
+## What developers use it for
+
+- **Persistent memory for Claude Code, Codex and Cursor.** Decisions, conventions, fixes and project context carry across sessions and across tools; confirmed rules and decisions load at session start.
+- **An MCP memory server for any agent.** stdio or HTTP, with adapters for LangGraph, LangChain, LlamaIndex, CrewAI, AutoGen, Semantic Kernel, Microsoft Agent Framework, Google ADK and the OpenAI Agents SDK.
+- **Local-first RAG without a vector database service.** SQLite + sqlite-vec, hybrid search (BM25, embeddings, knowledge graph, temporal), reranking, no Docker and no cloud account.
+- **A hallucination guard for retrieval.** The answer check, Jev or Laya, abstains when the retrieved memories don't answer the question, so your agent doesn't build on a wrong one.
+- **Team and enterprise AI memory.** Roles, company mode with sign-in, scoped sharing, GDPR export and verified erasure, a hash-chained audit trail and an EU AI Act posture report.
+- **Multi-agent memory and coordination.** One store shared by many agents with per-agent attribution, SLM-Mesh messages, locks and shared state, and bounded loops that finish only when an independent gate passes.
+- **Lower token cost.** Exact caching and reversible compression of tool output and file reads keep long agent sessions inside the context window.
+- **Memory for local LLMs.** Mode B runs extraction on Ollama, llama.cpp, vLLM, LM Studio or any OpenAI-compatible server on your machine.
+- **A searchable work log.** Bi-temporal "what was true then" queries, daily, session and project summaries, and saved views, each answer pointing back to its memory ids.
+
+## Architecture
+
+![SuperLocalMemory architecture: modes, eight-layer pipeline, governance, Scale Engine, SLM-Mesh, bounded loops](docs/assets/slm-4.1.21-architecture.svg)
+
+*SQLite + sqlite-vec are canonical; CozoDB and LanceDB are parity-gated projections; SLM-Mesh coordinates trusted peers rather than replicating a distributed database; connectors are opt-in.* [Architecture docs](docs/ARCHITECTURE.md).
 
 ## Everything SLM does
 
+### Memory and recall
+
 | Capability | What you get | Docs |
 |---|---|---|
-| Hybrid recall | Semantic, keyword (BM25), temporal, associative (Hopfield) and spreading-activation channels, fused and reranked. `slm trace` shows each channel's score | [Recall](docs/recall.md) |
-| Answer check | A second step that says whether the results answer the question. Laya on your Mac or Jev online, one at a time; a dashboard tab with history and the "I don't have that" rate | [Answer check](docs/answer-check.md) |
+| Hybrid recall | Semantic, keyword (BM25), temporal, associative (Hopfield) and spreading-activation channels, fused by reciprocal rank and reranked. `slm trace` shows each channel's score | [Recall](docs/recall.md) |
 | Memory kinds | Nine kinds: fact, event, status, opinion, rule, decision, how-to, plan, correction. "What did we decide" favours decisions | [Memory kinds](docs/memory-kinds.md) |
 | Standing rules | Confirmed rules (up to 10) and decisions (up to 5) load into every new agent session | [Memory kinds](docs/memory-kinds.md#standing-rules-at-session-start) |
 | Replace and correct | `--replaces <id>` retires an old fact, kept and undoable. Edits go through reviewed corrections with rollback | [Corrections](docs/reviewed-corrections.md) |
 | Time travel | `--as-of`, `--known-as-of`, `--valid-at`, and `--window 7d` or a date range | [Recall](docs/recall.md#time-travel) |
-| Recall filters | `--project`, `--saved-by`, `--about`, `--kind`; applied before the answer check | [Recall](docs/recall.md#narrowing-a-recall) |
-| Summaries | `slm summary session`, `day` or `project` | [Recall](docs/recall.md#summaries) |
+| Recall filters | `--project`, `--saved-by`, `--about`, `--kind`, and exact tags with `--tag` (repeat it; `--tags-match all` or `any`); applied before the answer check, and an empty result says why | [Recall](docs/recall.md#narrowing-a-recall) |
+| Project-aware recall | Memories from your current project rank first, hiding nothing. `--project` narrows and says when nothing matched | [Recall](docs/recall.md) |
+| Summaries and saved views | `slm summary session`, `day` or `project`, each citing its memory ids; `slm view create "Work log" "what did I ship" --window 7d`, then `slm view run` | [Summaries](docs/recall.md#summaries), [Views](docs/recall.md#saved-views) |
 | Knowledge graph | Entities, aliases, scenes and timelines; Entity Explorer in the dashboard | [Architecture](docs/ARCHITECTURE.md) |
-| Code graph | Build a graph of a repo, then ask for blast radius, review context and code search by meaning | [MCP tools](docs/mcp-tools.md) |
-| Learning | Ranking adapts to what you use; learned patterns become soft prompts; opt-in skill evolution | [Skill evolution](docs/skill-evolution.md) |
-| Cache and compress | Exact cache and safe compression through a proxy (`slm wrap claude`), MCP tools or a skill; `slm optimize savings` | [Optimize](docs/optimize-overview.md) |
-| Multi-agent and mesh | Each memory records which agent saved it. SLM-Mesh gives sessions and machines messages, locks and shared state | [Multi-machine](docs/multi-machine.md) |
-| Profiles and scopes | Isolated workspaces. Memories are personal by default; shared and global are opt-in | [Profiles](docs/profiles.md), [Scopes](docs/shared-memory.md) |
-| Bounded loops | `slm loop`: repeat a task until an independent check passes, with every lap stored as memory | [CLI reference](docs/cli-reference.md#bounded-loops-v380) |
-| Modes and providers | A: local. B: local Ollama. C: a cloud provider. Any OpenAI-compatible embedder, including multilingual models | [Configuration](docs/configuration.md) |
-| Backup and restore | Cloud backup to GitHub or Google Drive, encrypted before upload. Restore points before each store update, and a safe path back to the previous version | [Cloud backup](docs/cloud-backup.md), [Restore points](docs/restore-points.md) |
+| Code graph | Index a repo, then ask for blast radius, callers, review context and code search by meaning | [MCP tools](docs/mcp-tools.md) |
+| Modes and providers | A: no model calls. B: a model on this machine (Ollama by default, or another local OpenAI-compatible server). C: your own endpoint or a cloud provider. Multilingual embedders work. `slm models` recommends models that fit this computer | [Configuration](docs/configuration.md) |
+| Switch the embedding model | `slm embedder switch MODEL` re-indexes every memory in the background while recall keeps working, then changes over in one step; `status`, `cancel` and `rollback` | [CLI reference](docs/cli-reference.md#embedding-models-and-store-health) |
+
+Recalled text is untrusted evidence: before it reaches a prompt, secrets are redacted, forged boundary markers neutralised and provenance attached, a defence against prompt injection through memory.
+
+### Learning in memory
+
+- **Adaptive ranking.** A contextual Thompson-sampling bandit picks channel weights per query type; a LightGBM learning-to-rank model trains on `report_outcome` and `report_feedback`. The same question on an unchanged store gets the same ranking.
+- **Guarded promotion.** A candidate ranker runs in shadow and is promoted only on a measured win; a later NDCG@10 drop of 2% or more restores the previous model automatically.
+- **Soft prompts.** Consolidation mines behavioural patterns and turns stable ones into soft prompts for new sessions.
+- **Forgetting.** An Ebbinghaus retention cycle and a Langevin lifecycle move neglected memories toward archive and pull used ones back.
+- **Skill evolution (opt-in).** Measures agent skills, proposes revisions and keeps lineage, under a budget and blind verification. [Skill evolution](docs/skill-evolution.md)
+
+### Governance
+
+| Control | What it does | Docs |
+|---|---|---|
+| Roles | Admin, member and viewer per workspace. A role in one workspace grants nothing in another | [Teams](docs/rbac-teams.md) |
+| Company mode | Every read and write is attributed to a signed-in person; turn on with "Require login" | [Company mode](docs/company-mode.md) |
+| Profiles and scopes | Isolated workspaces. Memories are `personal` by default; `shared` and `global` are opt-in | [Profiles](docs/profiles.md), [Scopes](docs/shared-memory.md) |
+| GDPR | `slm gdpr export` (Art. 15/20), `slm gdpr erase` (Art. 17) across every store, `slm gdpr verify` checks the erasure receipt | [Compliance](docs/compliance.md) |
+| Retention and audit | Per-profile retention rules; a hash-chained audit trail of stores, recalls, changes and erasures; ABAC policy checks | [Compliance](docs/compliance.md) |
+| EU AI Act posture | A per-mode technical report (data locality, generative AI use). Risk class stays "undetermined"; no legal verdict | [Compliance](docs/compliance.md) |
+| Write gate | Install token, API keys and remote keys decide who may write | [Auth write gate](docs/auth-write-gate.md) |
 | Evidence export | Checksummed JSONL bundles: `slm evidence export`, `verify`, `import` | [CLI reference](docs/cli-reference.md#data-and-evidence) |
-| Teams and governance | Admin, member and viewer roles; sign-in; `slm gdpr export`, `erase` and `verify`; retention rules; hash-chained audit log | [Teams](docs/rbac-teams.md), [Compliance](docs/compliance.md) |
-| Dashboard | `slm dashboard`: 16 panes, including Answer Check, Brain, Knowledge Graph, Memories, Health, Governance, Optimize, Mesh Peers and Cloud Backup | [Dashboard](docs/DASHBOARD-COVERAGE.md) |
-| Operations | `slm doctor`, `status`, `health`, `restart`, `ops`; stuck operations listed and resolved | [Troubleshooting](docs/troubleshooting.md) |
-| Scale Engine | Optional CozoDB and LanceDB copies, promoted only after they match SQLite | [Scale Engine](docs/scale-engine.md) |
+| Backup and restore | Cloud backup to GitHub or Google Drive, encrypted before upload. A restore point before each store update | [Cloud backup](docs/cloud-backup.md), [Restore points](docs/restore-points.md) |
+
+Engineering controls that support a compliance program, not a certification.
+
+### Multi-agent: SLM-Mesh and bounded loops
+
+**Shared memory with attribution.** Claude Code, Codex, Cursor and Hermes share one store; each memory records its agent (`SLM_AGENT_ID`) and the dashboard shows per-agent activity.
+
+**SLM-Mesh** coordinates sessions on one machine, or several machines with a shared secret: `mesh_peers`, `mesh_send`, `mesh_inbox`, `mesh_state`, `mesh_lock`, `mesh_events`, `mesh_status`, `mesh_summary`. Messages route across machines; locks and state are per machine. [Multi-machine](docs/multi-machine.md)
+
+**Bounded loops** end only when an independent gate passes (tests, a linter, a schema, a recall condition), never because the agent says it is done. Runs end DONE, HALT, PAUSE, KILLED or ERROR, with each lap stored under `loop:<name>`. Run `slm loop demo`, the `slm_loop_*` MCP tools or `/slm-loop`; the separate Bounded Loops product can store its finished runs here as read-only evidence. [CLI reference](docs/cli-reference.md#bounded-loops-v380), [Bounded Loops bridge](docs/bounded-loops-bridge.md)
+
+### Answer check: Laya and Jev
+
+Answer check adds a second step after ranking; choose one in **Settings → Answer check**:
+
+- **Laya, on this Mac:** a small on-device model (about 1.1 GB) for Apple Silicon Macs. Nothing leaves the machine.
+- **Jev, online, on any computer:** Windows, Linux or macOS, through 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 the online option never turns itself on. Results are never hidden: recall marks them `abstained` and your agent decides. A repeat question gets the same verdict. The **Answer Check** tab shows verdicts, timing against the 3-second recall ceiling and the "I don't have that" rate; it never stores questions or memory text. [Answer check](docs/answer-check.md)
+
+### Context optimisation: cache and compression
+
+| Feature | What it does |
+|---|---|
+| Exact cache | `slm_cache_get` / `slm_cache_set` keep tool output and file reads with a TTL; a hit skips the repeat call |
+| Compression | `slm_compress` shrinks large output; safe mode keeps JSON and code intact. A reversible result returns an id, and `slm_retrieve` restores the exact original |
+| Three surfaces | Works through a proxy (`slm wrap claude`), MCP tools or a skill. Only the proxy caches the main conversation turn |
+| Savings | `slm optimize savings --since 7` reports tokens and cost saved |
+| Memory compression | Vector precision follows retention: fading memories are quantized to fewer bits, and consolidation folds clusters of faded memories into one gist |
+
+All of it fails open. [Optimize](docs/optimize-overview.md), [Proxy setup](docs/proxy-setup.md)
+
+### Remote access and teams
+
+`slm remote` serves memory to other computers over TLS only. Each client gets a named key bound to one profile, read-only or read-write, revocable at once. Remote callers authenticate to read and never see this computer's paths or account. [Remote access](docs/distributed-deployment.md#remote-access-over-tls-4120), [Deployment tiers](docs/deployment-tiers.md)
+
+### Scale and operations
+
+- **[Scale Engine](docs/scale-engine.md):** SQLite stays canonical. Optional CozoDB graph and LanceDB vector copies go through prepare, verify, promote and rollback, and serve recall only once they match SQLite.
+- **[Dashboard](docs/DASHBOARD-COVERAGE.md):** `slm dashboard`, 16 panes including Answer Check, Brain, Knowledge Graph, Governance, Optimize and Mesh Peers.
+- **Durable writes:** each save moves raw → queryable → enriching → complete with a receipt; a failed step keeps the raw evidence and retries. Saves under heavy load are queued, never refused.
+- **[Operations](docs/troubleshooting.md):** `slm doctor`, `status`, `health`, `restart`, `ops`; stuck operations are listed and resolved.
+- **Store health:** `slm db integrity` reports the store's health; `slm db repair` previews fixes for leftover rows, erased words, unfinished deletes and memories that lost their searchable fact, applies them with `--apply`, and undoes a run with `--undo`. It never brings back anything erased, deleted or withheld. [CLI reference](docs/cli-reference.md#embedding-models-and-store-health)
 
 ## MCP memory server: tool profiles
 
-Pick how many tools your agent sees with `SLM_MCP_PROFILE`. Counts come from the server itself.
+Pick how many tools your agent sees with `SLM_MCP_PROFILE`.
 
 | Profile | Tools | For |
 |---|---:|---|
 | `core` | 18 | Remember, recall, sessions, optimize, correction review |
 | `code` | 38 | Core plus code graph, memory kinds, Brain evidence, profile switching, bounded loops |
 | `mesh` | 8 | SLM-Mesh coordination only |
-| `full` (and unset) | 54 | Memory, kinds, Brain, optimize, skill evolution, mesh, loops |
-| `power` | 66 | Full plus administration, lifecycle and diagnostics |
-| `whole` | 101 | Every registered tool |
+| `full` (and unset) | 56 | Memory, kinds, Brain, optimize, skill evolution, mesh, loops, views and summaries |
+| `power` | 68 | Full plus administration, lifecycle and diagnostics |
+| `whole` | 103 | Every registered tool |
 
 ```json
 { "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.
+For stdio clients use `{"command": "slm", "args": ["mcp"]}`.
 
 ## Privacy and security
 
@@ -144,9 +298,7 @@ What leaves your machine, and when:
 | Encrypted backup files | You connect GitHub or Google Drive backup. Files are encrypted before upload |
 | Mesh messages | You configure SLM-Mesh peers |
 
-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](docs/distributed-deployment.md#remote-access-over-tls-4120), [Security policy](SECURITY.md) and [encryption at rest](docs/SECURITY-encryption-at-rest.md).
+Model downloads send no memory content. Credentials in memory text are redacted on every outbound path. Outbound requests never follow redirects, and forwarded-for headers count only from a proxy you name. See [Security policy](SECURITY.md) and [encryption at rest](docs/SECURITY-encryption-at-rest.md).
 
 ## Benchmarks (V3)
 
@@ -162,30 +314,78 @@ Method, category breakdown and ablations: [docs/benchmarks.md](docs/benchmarks.m
 
 ## Research
 
-SLM's design is described in the V4 paper, [SuperLocalMemory 4.0: The Governed Memory Operating System for AI Agents](https://arxiv.org/abs/2608.08253) (DOI [10.5281/zenodo.21853302](https://doi.org/10.5281/zenodo.21853302)). Earlier preprints: [information-geometric foundations, V3](https://arxiv.org/abs/2603.14588), [the Living Brain, V3.3](https://arxiv.org/abs/2604.04514), and [trust and behavioural foundations, V2](https://arxiv.org/abs/2603.02240). Cite it with [CITATION.cff](CITATION.cff) or GitHub's "Cite this repository" button:
+Four arXiv preprints by Varun Pratap Bhardwaj describe SLM, newest first:
+
+1. **V4 (2026):** [SuperLocalMemory 4.0: The Governed Memory Operating System for AI Agents](https://arxiv.org/abs/2608.08253), with Garima Singh and Arun Pratap Bhardwaj. arXiv:2608.08253. Multi-scope isolation, role-based access, verified erasure, hash-chained audit and bi-temporal recall, with their measured cost.
+2. **V3.3 (2026):** [SuperLocalMemory V3.3: The Living Brain](https://arxiv.org/abs/2604.04514), arXiv:2604.04514. Biologically inspired forgetting, cognitive quantization, multi-channel retrieval without an LLM.
+3. **V3 (2026):** [SuperLocalMemory V3: Information-Geometric Foundations for Zero-LLM Enterprise Agent Memory](https://arxiv.org/abs/2603.14588), arXiv:2603.14588. Fisher-information retrieval, Langevin lifecycle, sheaf contradiction detection; the LoCoMo results above.
+4. **V2 (2026):** [SuperLocalMemory: Privacy-Preserving Multi-Agent Memory with Bayesian Trust Defense Against Memory Poisoning](https://arxiv.org/abs/2603.02240), arXiv:2603.02240.
+
+Cite the V4 paper with [CITATION.cff](CITATION.cff) or GitHub's "Cite this repository" button:
 
 ```bibtex
 @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}
+  year    = {2026}
 }
 ```
 
+## Documentation
+
+**Start:** [Getting started](docs/getting-started.md) · [IDE setup](docs/ide-setup.md) · [Linux install](docs/install-linux.md) · [Quick proof](docs/QUICK_PROOF.md) · [Migrating from V2](docs/migration-from-v2.md)
+
+**Use:** [Recall](docs/recall.md) · [Memory kinds](docs/memory-kinds.md) · [Answer check](docs/answer-check.md) · [Auto-memory](docs/auto-memory.md) · [Shared memory](docs/shared-memory.md) · [Optimize](docs/optimize-overview.md)
+
+**Reference:** [CLI](docs/cli-reference.md) · [MCP tools](docs/mcp-tools.md) · [Configuration](docs/configuration.md) · [Errors](docs/errors.md) · [Troubleshooting](docs/troubleshooting.md) · [Distributed deployment](docs/distributed-deployment.md) · [Privacy diagnostics](docs/privacy-diagnostics.md)
+
+**Design:** [Architecture](docs/ARCHITECTURE.md) · [Score contract](docs/retrieval-score-contract.md) · [Compliance](docs/compliance.md) · [Benchmarks](docs/benchmarks.md)
+
 ## Upgrade
 
 ```bash
-pipx upgrade superlocalmemory     # or: npm update -g superlocalmemory
+npm update -g superlocalmemory    # or, in your activated venv: python -m pip install --upgrade 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](docs/host-upgrades.md).
+Upgrades never move or delete memory; an update that changes the store takes a restore point first. Plugins update through your editor; see [host upgrades](docs/host-upgrades.md).
+
+## Platform support
+
+| | SuperLocalMemory | Jev (online check) | Laya (on-device check) |
+|---|---|---|---|
+| Apple Silicon macOS | Yes | Yes | Yes |
+| 64-bit Windows | Yes | Yes | No (Laya uses Apple's MLX) |
+| 64-bit Linux (x86-64, ARM64) | Yes | Yes | No |
+| Intel Mac, 32-bit Windows | No prebuilt install | — | — |
+
+Python 3.12+, and Node 18+ for npm. Intel Mac and 32-bit Windows lack a build of the pinned security library (`cryptography` 50); older versions have high-severity advisories. The default embedding model (about 500 MB) downloads on first use or with `slm warmup`.
 
 ## Contributing and license
 
 Issues and pull requests are welcome; start with [CONTRIBUTING.md](CONTRIBUTING.md). Report vulnerabilities through [SECURITY.md](SECURITY.md). Release notes are in [CHANGELOG.md](CHANGELOG.md).
 
 SLM is licensed under [AGPL-3.0-or-later](LICENSE). For a commercial license, see [COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md). Copyright (c) 2026 Varun Pratap Bhardwaj / [Qualixar](https://qualixar.com). Website: [superlocalmemory.com](https://www.superlocalmemory.com).
+
+---
+
+<div align="center">
+
+### Built by Qualixar
+
+**SuperLocalMemory** is made by [Varun Pratap Bhardwaj](https://varunpratap.com) at [Qualixar](https://qualixar.com), where the work is AI Reliability Engineering: memory, contracts, tests and loops that make AI agents dependable enough to trust with real work.
+
+[![GitHub stars](https://img.shields.io/github/stars/qualixar/superlocalmemory?style=social)](https://github.com/qualixar/superlocalmemory/stargazers)
+[![PyPI downloads](https://img.shields.io/pepy/dt/superlocalmemory?label=PyPI%20downloads)](https://pepy.tech/project/superlocalmemory)
+[![npm downloads](https://img.shields.io/npm/dt/superlocalmemory?label=npm%20downloads)](https://www.npmjs.com/package/superlocalmemory)
+[![Follow on X](https://img.shields.io/badge/follow-%40varunPbhardwaj-000000?logo=x)](https://x.com/varunPbhardwaj)
+
+If SLM keeps your agents from forgetting, **[star the repository](https://github.com/qualixar/superlocalmemory)**: it is how other developers find it.
+
+**More from Qualixar:** [Qualixar OS](https://github.com/qualixar/qualixar-os) · [SkillFortify](https://github.com/qualixar/skillfortify) · [SLM Mesh](https://github.com/qualixar/slm-mesh) · [AgentAssert](https://github.com/qualixar/agentassert-abc) · [AgentAssay](https://github.com/qualixar/agentassay) · [Bounded Loops](https://github.com/qualixar/bounded-loops) · [Jev Decision Layer](https://github.com/qualixar/jev-decision-layer) · [SLM MCP Hub](https://github.com/qualixar/slm-mcp-hub)
+
+[superlocalmemory.com](https://www.superlocalmemory.com) · [qualixar.com](https://qualixar.com) · [Papers](#research) · [LinkedIn](https://www.linkedin.com/in/varun-pratap-bhardwaj-7ab63742/) · [X](https://x.com/varunPbhardwaj)
+
+</div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "4.1.20",
+  "version": "4.1.22",
   "description": "Local-first agent memory with MCP and an agent-native CLI. Documented clients include Claude Code, Cursor, and Windsurf.",
   "keywords": [
     "ai-memory",
@@ -78,8 +78,10 @@
     "scripts/preuninstall.js",
     ".claude-plugin/",
     "plugin/",
+    "plugin-src/skills/slm-bot-memory/SKILL.md",
     "plugin-src/skills/slm-cache/SKILL.md",
     "plugin-src/skills/slm-compress/SKILL.md",
+    "plugin-src/skills/slm-getting-started-bot/SKILL.md",
     "plugin-src/skills/slm-governance/SKILL.md",
     "plugin-src/skills/slm-graph/SKILL.md",
     "plugin-src/skills/slm-loop/SKILL.md",

package/plugin/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
     "name": "Qualixar",
     "url": "https://github.com/qualixar/superlocalmemory"
   },
-  "description": "Local-first agent memory + reversible context compression and KV cache, as an MCP server. 38-tool code profile with graph intelligence.",
+  "description": "Local-first agent memory + reversible context compression and KV cache, as an MCP server. Serves the 56-tool full profile by default; set SLM_MCP_PROFILE=code for the 38-tool code profile.",
   "displayName": "SuperLocalMemory",
   "keywords": [
     "memory",
@@ -15,5 +15,5 @@
   "mcpServers": "./.mcp.json",
   "name": "superlocalmemory",
   "repository": "https://github.com/qualixar/superlocalmemory",
-  "version": "4.1.20"
+  "version": "4.1.22"
 }

package/plugin/.cursor-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "author": {
+    "name": "Qualixar"
+  },
+  "description": "Local-first long-term memory for your agents and bots: remember, recall and session context stored on your own computer, with reversible compression and a cache for large tool outputs.",
+  "homepage": "https://github.com/qualixar/superlocalmemory",
+  "hooks": {
+    "hooks": {}
+  },
+  "keywords": [
+    "memory",
+    "long-term-memory",
+    "local-first",
+    "mcp",
+    "agents"
+  ],
+  "license": "AGPL-3.0-or-later",
+  "logo": "assets/logo.svg",
+  "mcpServers": "./mcp.cursor.json",
+  "name": "superlocalmemory",
+  "repository": "https://github.com/qualixar/superlocalmemory",
+  "skills": "./cursor-skills/",
+  "version": "4.1.22"
+}

package/plugin/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- BEGIN SuperLocalMemory v4.1.20 -->
+<!-- BEGIN SuperLocalMemory v4.1.22 -->
 
 ## SuperLocalMemory (SLM) — Agent Rules
 
@@ -40,6 +40,6 @@ slm-recall · slm-remember · slm-session · slm-status · slm-cache · slm-comp
 ### Subagents
 slm-memory-advisor (memory decisions, session hygiene, scope/profile guidance) · slm-optimize-advisor (context compression + KV cache) · slm-governance-advisor (scope/roles/compliance/GDPR)
 
-<!-- END SuperLocalMemory v4.1.20 -->
+<!-- END SuperLocalMemory v4.1.22 -->
 
-SuperLocalMemory v4.1.20 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later

package/plugin/agents/slm-governance-advisor.md

@@ -77,4 +77,4 @@ slm-scope · slm-governance · slm-profile · slm-remember · slm-recall
 # What NOT to do
 Never session_init twice; never forget without dry-run preview; never store secrets; never bypass role checks; never claim an erasure succeeded without verifying via recall.
 
-SuperLocalMemory v4.1.20 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later

package/plugin/agents/slm-loop-runner.md

@@ -68,4 +68,4 @@ assessment. The gate is the authority.
 
 ---
 
-SuperLocalMemory v4.1.20 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later

package/plugin/agents/slm-memory-advisor.md

@@ -47,4 +47,4 @@ slm-recall · slm-remember · slm-session · slm-scope · slm-profile · slm-gov
 # What NOT to do
 Never session_init twice; never forget dry_run=False without reporting preview; never dump a whole file into remember; never invent a memory; never claim "saved" without success:true / clean CLI exit; never bypass scope or governance restrictions.
 
-SuperLocalMemory v4.1.20 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later

package/plugin/agents/slm-optimize-advisor.md

@@ -41,4 +41,4 @@ slm-compress · slm-cache · slm-status · slm-profile
 # What NOT to do
 Never compress code-for-edit/JSON-to-parse/<500 chars; never store secrets/ccr_ids; never let optimize failure block/alter the task; never claim a specific savings %; never carry ccr_ids across profile switches.
 
-SuperLocalMemory v4.1.20 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later

package/plugin/assets/logo.svg

@@ -0,0 +1,36 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" role="img" aria-labelledby="title desc">
+  <title id="title">SuperLocalMemory mark</title>
+  <desc id="desc">A local memory core represented by connected evidence nodes in a cyan and violet ring.</desc>
+  <defs>
+    <linearGradient id="slm-ring" x1="18" y1="18" x2="110" y2="110" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#22d3ee"/>
+      <stop offset=".52" stop-color="#60a5fa"/>
+      <stop offset="1" stop-color="#a78bfa"/>
+    </linearGradient>
+    <linearGradient id="slm-core" x1="39" y1="37" x2="91" y2="91" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#d9fbff"/>
+      <stop offset="1" stop-color="#c4b5fd"/>
+    </linearGradient>
+  </defs>
+  <circle cx="64" cy="64" r="58" fill="#07111f" stroke="url(#slm-ring)" stroke-width="4"/>
+  <path d="M33 51c4-15 16-25 31-25 20 0 35 16 35 36 0 17-12 31-28 35" fill="none" stroke="url(#slm-ring)" stroke-linecap="round" stroke-width="4"/>
+  <path d="M35 78c6 15 22 24 38 20 9-2 16-8 20-16" fill="none" stroke="url(#slm-ring)" stroke-linecap="round" stroke-width="4" opacity=".82"/>
+  <g fill="none" stroke="url(#slm-ring)" stroke-linecap="round" stroke-linejoin="round" stroke-width="3.5">
+    <path d="M43 55 58 45l14 10 13-8"/>
+    <path d="M43 55v18l15 9 14-9 13 8"/>
+    <path d="M58 45v37"/>
+    <path d="M72 55v18"/>
+  </g>
+  <g fill="url(#slm-core)" stroke="#07111f" stroke-width="2">
+    <circle cx="43" cy="55" r="6"/>
+    <circle cx="58" cy="45" r="6"/>
+    <circle cx="72" cy="55" r="6"/>
+    <circle cx="85" cy="47" r="6"/>
+    <circle cx="43" cy="73" r="6"/>
+    <circle cx="58" cy="82" r="6"/>
+    <circle cx="72" cy="73" r="6"/>
+    <circle cx="85" cy="81" r="6"/>
+  </g>
+  <circle cx="64" cy="64" r="8" fill="url(#slm-ring)"/>
+  <circle cx="64" cy="64" r="3" fill="#f8fafc"/>
+</svg>