{ "markdown": "

\n \n \n \"SuperLocalMemory\"\n \n

\n\n

SuperLocalMemory V4.1.14

\n\n

Rent the LLM. Own the memory.

\n\n

Rent an LLM — but own the memory, for your company and for your industry.

\n\n

The governed memory layer for AI agents: local-first, auditable, and built for the compliance obligations teams now actually carry.
\nModels are interchangeable and rented by the token. What your agents remember is\nyours — it is your customers' data, your retention obligations, and your audit trail. SLM\nkeeps that layer on infrastructure you control, with multi-workspace isolation, role-based\naccess, and GDPR + EU AI Act governance controls built in.

\n\n

The boundary. SuperLocalMemory starts with a local runtime;\nprovider-backed enrichment, cloud backup, connectors, and proxy use are explicit choices.\nDifferent products solve different boundaries. Published benchmark evidence carried into V4\ncomes from the published V3 research architecture; it is not a claim of a newly rerun V4 package benchmark.

\n\n

How to check that, rather than believe it. Every reliability\nguarantee here is stated as a falsifiable invariant, tested under an adversarial condition with a\nnegative control, and shipped with the harness that regenerates the evidence:\npython benchmark/run_all.py --trials 200 --output-dir results/. What each experiment\ndoes not exercise is stated too.

\n

v4.1.14 — one control plane: SLM-Mesh peer coordination · multi-scope memory (personal / shared / global) · profiles · Cache · Compress · 7-layer retrieval · code graph · Entity Explorer · skill evolution · Modes A/B/C · GDPR retention & audit chain · bounded loops — across CLI, MCP, dashboard, the Claude plugin, the Codex add-on, and documented IDE integrations.
\nProxy: slm wrap claude  ·  MCP: add slm_compress to your config  ·  Skill: zero-config

\n

Four public arXiv preprints · V4: arXiv:2608.08253 · companion archive: Zenodo 21853302 (DOI 10.5281/zenodo.21853302) · prior preprints: 2603.02240 · 2603.14588 · 2604.04514.

\n\n

\n \"v4.1.14\n \"SuperLocalMemory\n \"V4\n \"arXiv\n \"Three\n \"PyPI\"/\n \"npm\"/\n \"AGPL\n \"Privacy\n \"Enterprise\n \"Website\"/\n \"MCP\n \"CLI\n \"Multilingual\n

\n\n---\n\n## Why SuperLocalMemory?\n\nSuperLocalMemory is an enterprise-grade, local-first memory control plane for AI agents. Your team's agent memory lives on infrastructure you control, with per-workspace isolation, role-based access, and GDPR / EU AI Act governance controls — built for organizations, and for EU data-residency obligations where agent context must not leave your environment by default.\n\nAgent-memory systems make different storage, model-provider, and deployment trade-offs. SuperLocalMemory starts with a local runtime and makes provider-backed enrichment, cloud backup, connectors, and proxy use explicit choices.\n\nDifferent products solve different boundaries. The published LoCoMo benchmark evidence in this README is protocol-scoped evidence from the published V3 research architecture; it is carried forward for continuity and is not a claim of a newly rerun V4 package benchmark.\n\nSuperLocalMemory V4 combines conventional dense and lexical retrieval with graph, temporal, associative, and statistical relevance scoring in a **7-layer** control plane (admission → queryable core → enrichment → brain → multi-channel retrieval → context safety → operations). The default local runtime does not require Docker, a separately operated graph database, or an API key.\n\n**Memory with a sense of time.** SLM does not only store *what* an agent learned — it records *when*. Every fact carries ingestion timing and provenance; recall runs a dedicated temporal candidate channel alongside semantic, lexical, and associative retrieval; scenes and entity timelines reconstruct sequence; and the lifecycle lets neglected memory decay and self-archive instead of growing without bound. Time is a first-class ranking and lifecycle signal rather than a timestamp column an agent never reads — which is what lets a long-lived agent reason about how its context changed, not only what it currently holds.\n\n**What changed in this release.** See the [CHANGELOG](CHANGELOG.md) — every release is written up there, in plain language, newest first.\n\n- **[SLM-Mesh](#slm-mesh-cross-session--cross-machine-coordination)** — authenticated cross-session and cross-machine peer coordination (messages, locks, shared state, inbox/outbox, optional discovery). Coordination only — not automatic replicated memory.\n- **Multi-scope memory & profiles** — workspaces (profiles) plus `personal` / `shared` / `global` scopes; cross-profile recall is default-deny.\n- **Cache & compression (context optimization)** — exact-match cache with tagged invalidation, safe compression, and opt-in reversible/aggressive paths across proxy, MCP, and skill surfaces.\n- **Entity Explorer & skill evolution** — compiled entity summaries/timelines; opt-in skill lineage, budgets, and verification outcomes.\n- **Modes A / B / C** — local-only (A), on-device LLM enrichment (B), provider-assisted (C). An operating mode records technical locality facts; it does **not** determine EU AI Act legal compliance (that is deployment-context assessment — see [Privacy controls](#privacy-controls-and-operating-modes)).\n- **GDPR posture, retention & audit chain** — export, fail-closed cross-store erasure, retention policies, and a hash-chained audit trail. Engineering controls for compliance programs, not a legal certification.\n- **7-layer retrieval/recall stack & code graph** — multi-channel candidates (semantic, BM25, temporal, Hopfield, spreading activation) plus optional code-graph tools for blast radius and review context.\n- **MCP profiles** — `code` exposes **31** tools for installed coding agents; `full` **49**; `power` **61**; `whole` **94** (all registered). Also `core` (16), `mesh` (8), and the unrestricted default surface (49 with mesh enabled).\n- **Governed write path & verifiable transactions** — admission + policy control, a per-owner obligation ledger, and a hash-sealed completion manifest with a reconciler that redrives unmet obligations.\n- **Self-healing lifecycle & admin remediation** — stale locks cleared on restart; list/resolve stuck operations from CLI, MCP, or the dashboard.\n\nSLM is one strand of Qualixar's work on AI reliability engineering: making agent behavior observable, bounded, and reproducible instead of best-effort.\n\nThe architecture evaluated in the V3 paper remains the foundation of this release. The figures below keep their original LoCoMo protocol, answer-construction, model, and sample scope.\n\n### How SLM fits beside other memory systems\n\nDifferent products solve different boundaries. SLM is for developers who want\none local-first operating control plane—not only an SDK, managed context API,\nor agent runtime. It combines dated evidence, graph-aware retrieval, cache and\ncompression controls, **SLM-Mesh**, and MCP/CLI/hooks/dashboard/IDE\nsurfaces in one install.\n\n| If your primary need is… | Product boundary to evaluate |\n|---|---|\n| Local-first agent memory plus operations, optimization, and IDE-agent surfaces | **SuperLocalMemory** — Mode A local core; Modes B/C by explicit choice. |\n| A memory SDK, self-hosted server, or managed platform | [Mem0](https://github.com/mem0ai/mem0) |\n| A temporal context-graph service or graph engine | [Zep / Graphiti](https://github.com/getzep/graphiti) |\n| A stateful agent runtime with memory blocks and archival memory | [Letta](https://docs.letta.com/guides/core-concepts/memory/context-hierarchy) |\n| LangGraph-native memory primitives and managers | [LangMem](https://github.com/langchain-ai/langmem) |\n| A context API/app with profiles, connectors, and RAG | [Supermemory](https://github.com/supermemoryai/supermemory) |\n| User profiles and event-timeline memory | [Memobase](https://github.com/memodb-io/memobase) |\n\nSee the [source-linked market comparison](https://superlocalmemory.com/comparison)\nfor current primary sources and protocol-scoped benchmark evidence. A LoCoMo\npercentage is comparable only when the dataset scope, answer model, judge,\nretrieval stack, and release artifact match.\n\n### The V4 capability architecture\n\nSuperLocalMemory is one local control plane for persistent agent context. It is\nnot just a vector store: the same runtime can accept evidence, build and govern\nmemory, retrieve bounded evidence for an agent, and expose cache, compression,\nand **SLM-Mesh** peer-coordination controls through a CLI, MCP, dashboard, and supported\nIDE integrations.\n\n![SuperLocalMemory V4 capability architecture: modes, seven operating layers, Scale Engine, SLM-Mesh, delivery surfaces, and opt-in adapters](docs/assets/slm-v37-capability-architecture.png)\n\n*Architecture boundary: SQLite + sqlite-vec remain canonical; CozoDB and\nLanceDB are parity-gated projections; **SLM-Mesh** coordinates trusted peers rather\nthan replicating a distributed memory database; connectors are opt-in.*\n\n**Memory boundaries:** profiles isolate workspaces by default. Every memory is\n`personal`, `shared` with named profile readers, or `global`; cross-profile\nrecall is default-deny and must be explicitly enabled. This scoped sharing is\nlocal authorization, not **SLM-Mesh** synchronization. See\n[shared-memory.md](docs/shared-memory.md).\n\n```text\n IDEs, agents, scripts, connectors, and humans\n │ CLI · MCP (HTTP/stdio) · hooks · dashboard\n ▼\n ┌────────────────────────── SLM CONTROL PLANE ──────────────────────────┐\n │ 1. Admission identity, scope, idempotency, raw evidence │\n │ 2. Queryable core SQLite facts + FTS durable receipt │\n │ 3. Enrichment facts, entities, scenes, time, provenance, graph │\n │ 4. Memory brain feedback, patterns, rewards, consolidation │\n │ 5. Retrieval semantic · BM25 · temporal · Hopfield · activation │\n │ 6. Context safety policy, trust, provenance, redaction, budgets │\n │ 7. Operations lifecycle, audit, cache/compress, mesh, backups │\n └───────────────────────────────────────────────────────────────────────┘\n │\n ▼\n SQLite + sqlite-vec canonical store ──► optional graph/vector projections\n```\n\nThe seven stages are an execution model, not a promise that every optional\nenricher or retrieval channel runs for every request. The receipt, trace, and\nhealth surfaces expose the stages actually completed by the installed runtime.\n\n| Capability | What ships today | Operator boundary |\n|---|---|---|\n| **Memory types and lifecycle** | Atomic facts, episodic scenes, temporal events, canonical entities, profiles/scopes, consolidation, forgetting and retention controls | Lifecycle policies and retention decisions remain operator-configured. |\n| **Memory boundaries** | Profile-isolated workspaces plus `personal`, `shared`, and `global` memory scopes | Personal is the default; shared/global recall requires explicit scope policy or per-call opt-in. |\n| **Ingestion** | Durable raw-to-complete operation state, fact extraction, entity resolution, graph/temporal/provenance derivations, and replay-safe identity | `--sync` waits for declared stages; dependencies and mode determine which enrichers are available. |\n| **Retrieval and recall** | Semantic, lexical, temporal, Hopfield and spreading-activation candidate channels; RRF fusion, optional reranking and graph score enhancement | Healthy channels participate; response provenance states the evidence used. |\n| **Brain and learning** | Behavioral patterns, feedback/outcome records, rewards, consolidation, LightGBM-related ranking components, soft prompts, and guarded skill-evolution workflows | Learning is evidence-driven; it does not claim autonomous correctness or guaranteed improvement. |\n| **Knowledge graph and entities** | Canonical entities, aliases, entity profiles, graph edges, scenes, timelines, explorer and graph APIs | Stored/derived graph data is evidence, not an instruction authority. |\n| **Scale Engine** | SQLite + sqlite-vec are canonical. CozoDB graph and LanceDB vector projections are managed with prepare → verify → promote → rollback; a structurally detected pre-v3.7 projection can be explicitly adopted. | Promotion is parity-gated and crash-recoverable. Legacy adoption preserves the prior projection as a rollback backup; repeated physical edge rows normalize to one logical edge with the strongest weight. |\n| **Optimize** | Exact cache, tagged invalidation, safe compression, opt-in aggressive prose compression, CCR originals, proxy/MCP/skill surfaces | Only proxy intercepts a primary provider turn. MCP/skill cache results explicitly routed through SLM. |\n| **SLM-Mesh** | Authenticated peer messages, inbox/outbox, locks, offline queue, optional discovery and mesh MCP tools | SLM-Mesh is coordination, not automatic replicated memory or conflict resolution. |\n| **Governance and operations** | Provenance, audit/retention/policy surfaces, export/erasure controls, diagnostics, health, backups and daemon lifecycle | These are engineering controls, not a legal certification. |\n| **Integrations** | CLI, Python SDK, MCP HTTP/stdio, Claude plugin, Codex add-on, supported IDE configurations, Gmail/Calendar/transcript adapters | Hooks, IDE edits, connectors, and networked adapters require explicit operator activation. |\n\n### What the dashboard exposes\n\n`slm dashboard` opens a local operational view of the same control plane:\n\n| Workspace | Use it to inspect or control |\n|---|---|\n| Dashboard and Health | daemon identity, storage/runtime health, diagnostics and recent activity |\n| Brain | consolidation, behavioral patterns, outcomes/rewards, learning state and soft prompts |\n| Knowledge Graph and Memories | graph neighborhoods, entities, scenes, temporal evidence, memory inspection and mutation |\n| Operations | ingestion-operation state, traces, maintenance and lifecycle work |\n| Entity Explorer and Skill Evolution | compiled entity summaries/timelines; opt-in skill lineage, budgets and verification outcomes |\n| Multi-Agent Memory | per-agent write activity and attribution; memories stamped by `SLM_AGENT_ID`, agent write counts, and trust signals |\n| SLM-Mesh Peers | configured peers, inbox/outbox, pending coordination and locks |\n| Settings and Optimize | mode/provider/configuration; cache, compression and savings telemetry |\n\nDashboard visibility is not a substitute for runtime proof: use `slm doctor`,\n`slm health`, `slm trace`, and the relevant CLI/MCP operation to validate a\ndeployment.\n\n### Watch the product walkthrough\n\n[![Watch the SuperLocalMemory demo](https://img.youtube.com/vi/PMWW_ypsL60/hqdefault.jpg)](https://www.youtube.com/watch?v=PMWW_ypsL60)\n\n**[Watch the SuperLocalMemory demo on YouTube](https://www.youtube.com/watch?v=PMWW_ypsL60)** — a five-minute walkthrough of installation, setup, recall, cache, and compression. The video shows a product walkthrough; use the commands and release notes in this README as the current release contract.\n\n### Published LoCoMo evidence (V3 architecture, carried into V4)\n\nThe V3 paper evaluates the multi-channel architecture that V4 still runs. Every figure below\nis protocol-scoped, so a reader can distinguish local retrieval, answer\nconstruction, and cloud-assisted evaluation rather than treating unlike runs as\none score.\n\n| Published configuration | LoCoMo aggregate | Protocol scope | What the result establishes |\n|---|---:|---|---|\n| **Mode A Raw** | **60.4%** | 10 conversations; 1,276 scored questions; local embeddings, local retrieval, and zero-LLM answer construction | End-to-end local answer construction under the published V3 protocol. |\n| **Mode A Retrieval** | **74.8%** | 10 conversations; 1,276 scored questions; local retrieval, then GPT-4.1-mini answer synthesis | Retrieval evidence: local retrieval contributes the evidence, while the disclosed external model constructs the final answer. |\n| **Mode C** | **87.7%** | Conv-30 only; 81 scored questions; text-embedding-3-large plus GPT-4.1-mini answer generation and judge | Cloud-assisted configuration on one fully disclosed conversation; not a full-dataset result. |\n\nPublished category results: Mode A Retrieval scored **72.0%** single-hop,\n**70.3%** multi-hop, **80.0%** temporal, and **85.0%** open-domain. Mode C\nscored **64.0%** single-hop, **100.0%** multi-hop, and **86.0%** open-domain\non its 81-question Conv-30 scope (no temporal category was reported for that\nrun). Across six LoCoMo conversations, the paper reports **71.7%** with the\ninformation-geometric layers versus **58.9%** without them: **+12.7pp**.\n\nSee [arXiv:2603.14588](https://arxiv.org/abs/2603.14588) and the [official\nLoCoMo paper](https://arxiv.org/abs/2402.17753) for the full protocol,\nablation table, and limitations. These are published V3 architecture results\ncarried into V4—not a substitute for a newly rerun release-artifact benchmark.\n\n---\n\n## Quick Start\n\n```bash\n# Primary path 1 — npm global CLI (Node 18+)\n# Creates a package-owned virtual environment. It does not modify system Python.\nnpm install -g superlocalmemory\nslm setup # Choose mode (A/B/C)\nslm doctor # Verify everything is working\n```\n\n```bash\n# Primary path 2 — Python CLI + SDK in an activated virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate # Windows PowerShell: .venv\\Scripts\\Activate.ps1\npython -m pip install superlocalmemory\nslm setup\nslm doctor\n```\n\n```bash\n# First use\nslm remember \"Alice works at Google as a Staff Engineer\" --json\nslm recall \"What does Alice do?\"\nslm status\n```\n\nThe default daemon write commits raw evidence plus a relational/FTS projection\nand returns a durable receipt in `queryable` state. Enrichment then advances the\nsame operation through `enriching` to `complete`, or records a retryable\n`failed` state. Use `slm remember \"...\" --sync` when the caller must wait for\nall declared derivation and projector stages. JSON output includes the opaque\n`operation_id`, current `materialization_state`, and fact IDs.\n\n```bash\n# Wrap your agent — starts proxy + sets environment + launches agent\nslm wrap claude\n# Your first repeat prompt → CACHE HIT → $0.00\n# See savings: slm optimize savings --since 1\n```\n\n**Upgrading:** use the owner of the installation: `npm update -g superlocalmemory`\nor, while the Python virtual environment is active,\n`python -m pip install --upgrade superlocalmemory`. Then run\n`slm restart && slm doctor`. Repository-clone users use the matching `upgrade`\naction in `scripts/install.sh` or `scripts/install.ps1`. Installers never move\nor delete memory data.\n\n---\n\n## Three Pillars\n\n### Memory\n\n\n\nCurrent recall has five candidate producers—dense semantic, BM25 lexical,\ntemporal, Hopfield associative, and spreading activation—followed by fusion,\noptional reranking, and entity-graph score enhancement. The entity graph does\nnot create an independent candidate in the current implementation. Core memory\nis SQLite-backed. SQLite and sqlite-vec remain the canonical source of truth.\nThe packaged Scale Engine can maintain CozoDB graph and LanceDB vector\nprojections, and it remains outside active retrieval paths until a staged\nparity witness proves it matches the canonical store. New installations remain\non Local Core. During upgrade, `slm db scale status` can identify a positive\npre-v3.7 layout candidate; the operator confirms it with `slm db scale adopt`.\nSLM then rebuilds from canonical SQLite, verifies it, and promotes it with a\ndurable recovery journal while retaining the prior directories as a rollback\nbackup. `adopt` reports `restart_required: true`; run `slm restart` before\nchecking daemon health. If proof fails, recall remains on SQLite and status\nretains the rejected manifest for inspection, retires its replaceable derived\npayload, and allows a corrected retry.\n\nCanonical ingestion is a durable state machine: `raw → queryable → enriching →\ncomplete`, with `failed` retaining raw evidence, error details, attempt count,\nand retry timing. SQLite relational facts and FTS are the queryable checkpoint;\noptional ANN/vector projectors are verified before `complete` is granted.\n\nRecalled text is treated as untrusted evidence. Hooks, MCP `session_init`, CLI\nsession context, and chat use one bounded renderer that redacts recognized\nsecrets, neutralizes forged boundary markers, and attaches provenance. Trusted\nIDE instruction files contain only the static SLM protocol; fresh memory is\nretrieved at runtime rather than copied into those files.\n\n**Score Contract v2:** `relevance_score` is query-relative relevance;\n`ranking_score` is internal ranking utility; `memory_confidence` belongs to the\nstored assertion; and `trust_score` is an evidence-policy signal. Legacy\n`score` and `confidence` remain aliases for one compatibility release. It is\nexplicitly uncalibrated: `calibration_status` is `uncalibrated` and\n`answer_confidence` is `null`. See\n[the retrieval score contract](docs/retrieval-score-contract.md).\n\nThe retrieval/lifecycle implementation includes three mathematical layers that\ncan run without a cloud LLM:\n\n1. **Fisher-informed scoring** — dense candidate generation uses cosine similarity; Fisher-derived terms can modify later scoring when their state is available.\n2. **Sheaf Cohomology for Consistency** — algebraic topology detects contradictions via coboundary norms on the knowledge graph.\n3. **Riemannian Langevin Lifecycle** — memory positions evolve continuously on the Poincare ball, and where a memory sits decides its lifecycle stage. There is no retention timer counting down against a memory: what moves it outward is being left alone, and what pulls it back is being used. The stage boundaries themselves are fixed radii.\n\nAuto-capture hooks are installed explicitly with `slm hooks install` (Claude\nCode) or `slm hooks install --agent codex` (Codex). Hook latency and capture\nquality must be evaluated for the target client and workload; SLM publishes no universal p99 claim.\n\n**Multi-scope memory (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](docs/shared-memory.md)**.\n\n\n\n**Multilingual models:** configure an OpenAI-compatible embedding endpoint such as Ollama, vLLM, LiteLLM, `bge-m3`, `multilingual-e5`, or `Qwen3-Embedding`. Language coverage and retrieval quality depend on the selected model and should be evaluated for the deployment corpus.\n\n### Cache + Compress\n\n\n\nOne engine, three ways in — choose the surface that fits your setup:\n\n| Surface | How you use it | Requires proxy? | Window effect | Cache scope |\n|---------|---------------|:---------------:|:-------------:|-------------|\n| **A — Proxy** | `slm wrap claude` or `ANTHROPIC_BASE_URL=http://127.0.0.1:8765` | **Yes** | Shrinks | Full-turn cache — every call |\n| **B — MCP tools** | Add 5 tools to MCP config; call `slm_compress`, `slm_cache_set/get` | **No** | **Preserved (1M)** | Results you explicitly route through SLM |\n| **C — Skill** | Copy `skills/slm-optimize/SKILL.md` → `~/.claude/skills/` | **No** | **Preserved (1M)** | Auto-applied by the agent per skill rules |\n\n**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.\n\n**How to choose:**\n- Metered API (pay-per-token), want every call cached → **Proxy (A)**\n- Pro/Max/Team subscription or any plan where you won't run a proxy → **MCP tools (B)** or **Skill (C)**\n- Zero configuration → **Skill (C)**: install once, auto-compresses CLAUDE.md and large outputs\n- Agent-controlled caching of repeated file reads → **MCP tools (B)**\n\n**Cache:** exact-match SQLite lookup is the stable cache path. Semantic cache\ncontrols are experimental until release-linked precision, invalidation, and\ntenant-isolation evidence exists. A cache hit can avoid a provider request, but\nactual cost and latency savings depend on the intercepted surface and provider.\n\n**Compress:** safe mode uses conservative normalization and preserves JSON and code; measured reduction varies by content and can be zero. Aggressive prose compression is opt-in and lossy. CCR can retain an original for later byte-exact retrieval when reversible storage is enabled.\n\n**Savings dashboard:** `slm optimize savings --since 7` — live USD/INR/tokens saved. Hot-reload config, fail-open.\n\n### SLM-Mesh (cross-session / cross-machine coordination)\n\n\n\n\n**SLM-Mesh** is the V4 peer-coordination plane: authenticated messages, locks, shared lightweight state, inbox/outbox, and an offline queue between configured peers (same machine sessions or cross-machine). Optional mDNS discovery (`SLM_MESH_DISCOVERY=on`). It is **not** a replicated or conflict-resolving distributed-memory database — multi-scope memory sharing is a separate local-authorization feature.\n\n```bash\n# Machine A (broker)\nexport SLM_MESH_HOST=192.168.1.100\nexport SLM_MESH_SHARED_SECRET=my-secret-key\nslm init\n\n# Machine B (client)\nexport SLM_MESH_PEER_URL=http://192.168.1.100:8765\nexport SLM_MESH_SHARED_SECRET=my-secret-key\nslm init\n```\n\nEight **SLM-Mesh** MCP tools: `mesh_summary`, `mesh_peers`, `mesh_send`, `mesh_inbox`, `mesh_state`, `mesh_lock`, `mesh_events`, `mesh_status`.\n\nFull docs: [docs/multi-machine.md](docs/multi-machine.md) · [docs/distributed-deployment.md](docs/distributed-deployment.md)\n\n---\n\n## Install Paths\n\n> **V4 platform support:** Apple Silicon macOS, 64-bit Windows, and 64-bit Linux. Intel Mac and 32-bit Windows are not supported by the patched `cryptography` 50 runtime.\n\n| Path | Command | When |\n|:-----|:--------|:-----|\n| **npm global CLI** (primary) | `npm install -g superlocalmemory` | Node 18+; package-owned virtual environment; system Python is not modified; run `slm setup` explicitly afterward |\n| **Python CLI + SDK** (primary) | Activate a Python virtual environment, then `python -m pip install superlocalmemory` | Python 3.11+; the `slm` CLI and importable SDK stay inside that environment |\n| **Repository clone — macOS/Linux** | `./scripts/install.sh install` | Research/contributor path; delegates to an existing uv or pipx installation |\n| **Repository clone — Windows** | `.\\scripts\\install.ps1 -Action Install` | Research/contributor path; delegates to an existing uv or pipx installation |\n| **Claude Code Plugin** | `/plugin marketplace add qualixar/superlocalmemory` then `/plugin install superlocalmemory@qualixar` | Self-bootstraps venv, isolated SLM_DATA_DIR, additive — 34-tool code profile. Ships the skills/agents/hooks/commands |\n| **Portable / IDE connect** | `slm connect [--here]` | Wire any IDE without reinstalling; `slm connect claude-code` → plugin pointer |\n\nAfter any install path: `slm setup` → `slm doctor` → `slm warmup` (optional, pre-downloads ~500MB embedding model).\n\n### Upgrading an existing installation\n\nAn npm, pip, or repository update upgrades the SLM runtime; it does not silently\nrewrite your IDE configuration, hooks, or plugin state. Review the existing\nintegrations first:\n\n```bash\nslm upgrade-hosts\n```\n\nThen explicitly apply the hosts you approve, for example\n`slm upgrade-hosts --host codex --apply`, or use\n`slm upgrade-hosts --all-detected --apply` after reviewing the preview. See\n[Host Integration Upgrades](docs/host-upgrades.md) for the full safety contract\nand the Claude Code plugin update path.\n\n| Component | Size | When |\n|:----------|:-----|:-----|\n| Core libraries (numpy, scipy, networkx) | ~50MB | During install |\n| Dashboard & MCP server (fastapi, uvicorn) | ~20MB | During install |\n| Learning engine (lightgbm) | ~10MB | During install |\n| Search engine (sentence-transformers, torch) | ~200MB | During install |\n| Embedding model (nomic-embed-text-v1.5, 768d) | ~500MB | First use or `slm warmup` |\n| **Mode B** requires [Ollama](https://ollama.com) + a model (`ollama pull llama3.2`) | ~2GB | Manual |\n\n---\n\n## MCP + Profiles\n\nSLM supports two MCP transports:\n\n**HTTP (recommended):**\n```json\n{ \"mcpServers\": { \"superlocalmemory\": { \"type\": \"http\", \"url\": \"http://127.0.0.1:8765/mcp/\" } } }\n```\nOr: `claude mcp add --transport http superlocalmemory http://127.0.0.1:8765/mcp/`\n\n**stdio (universal fallback):**\n```json\n{ \"mcpServers\": { \"superlocalmemory\": { \"command\": \"slm\", \"args\": [\"mcp\"] } } }\n```\n\n### MCP Profiles\n\nControl tool surface via `SLM_MCP_PROFILE`:\n\n| Profile | Tools | Use case |\n|:--------|:-----:|:---------|\n| `core` | 16 | Memory, session, optimize, and correction review |\n| `code` | 31 | Core + portable Brain evidence + code-graph tools + profile switching + bounded loops |\n| `mesh` | 8 | SLM-Mesh only — multi-session / multi-machine coordination |\n| `full` | 49 | Memory + portable Brain evidence + optimize + evolution + mesh + bounded loops |\n| `power` | 61 | Full + administration, lifecycle, and diagnostics |\n| `whole` | 94 | Every registered MCP tool |\n\n**Precedence:** `ALL` > `TOOLS` > `PROFILE` > `default`\n\n```bash\nexport SLM_MCP_PROFILE=full # or core / code / mesh / power / whole\nslm mcp\n```\n\nFor a predictable small surface, set `core` explicitly. Leaving the variable\nunset retains the compatibility default, whose mesh tools follow the local\nmesh setting. Count-suffixed aliases remain for backward compatibility and emit a migration warning: `core14`, `core16`, `code20`, `code21`, `code24`, `code28`, `code29`, `code31`, `mesh8`, `full38`, `full39`, `full42`, `full46`, `full47`, `full49`, `power50`, `power51`, `power54`, `power58`, `power59`, `power61`, `whole81`, `whole84`, `whole91`, `whole92`, `whole94`. Unknown names stop startup instead of silently selecting another tool set.\n\nPer-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](docs/ide-setup.md).\n\n---\n\n## Editor plugins\n\nThe plugin is how most people should install SLM. It brings the MCP server, the\nskills, the sub-agents, the slash commands and the hooks in one step, and keeps\nthem at the same version as the package.\n\n**Five surfaces, one source.** Everything below is generated from `plugin-src/`,\nso no surface can quietly fall behind another:\n\n| Editor | Install | Skills | Agents | Commands | Hooks |\n|---|---|---:|---:|---:|---:|\n| **Claude Code** | `claude plugin marketplace add qualixar/superlocalmemory` then `claude plugin install superlocalmemory@qualixar` | 12 | 4 | 1 | yes |\n| **Codex** | copy `codex-plugin/` into your Codex plugins directory | 12 | 4 | 1 | yes |\n| **VS Code / Copilot** | copy `copilot-plugin/.github/` into your repository | 12 | 4 | as prompts | yes |\n| **Antigravity** | copy `antigravity-plugin/` into your plugins directory | 12 | 4 | 1 | yes |\n| **Hermes** | install the native plugin from the immutable release commit | 12 | 4 | all SLM commands | yes |\n\n### What you get\n\n- **Skills** — `slm-remember`, `slm-recall`, `slm-session`, `slm-graph`,\n `slm-mesh`, `slm-scope`, `slm-profile`, `slm-governance`, `slm-cache`,\n `slm-compress`, `slm-status`, `slm-loop`.\n- **Sub-agents** — a memory advisor, a governance advisor, a context-optimization\n advisor, and a loop runner, each scoped to the tools it actually needs.\n- **Commands** — `/slm-loop`, to run a task as a gate-verified bounded loop.\n- **Hooks** — session start and end, so context loads and commits without being\n asked.\n\n### Hermes\n\nHermes users get the same SLM skills and advisor roles through a native\n`plugin.yaml` package, plus `/slm ` and generated `/slm-`\naliases for the public CLI surface. The plugin is intentionally separate from\nthe PyPI/npm runtime: install the owning SLM runtime first, then install the\nreviewed pinned pack from the `v4.1.13` GitHub release. It is additive and does\nnot replace Hermes's selected memory provider or existing configuration. See\n[the Hermes integration guide](docs/hermes.md).\n\n### Keeping it current\n\n`pipx upgrade superlocalmemory` upgrades the **package**. It does not\nupgrade the plugin — those are separate channels, and the plugin is delivered by\nyour editor. `slm doctor` reports both versions side by side and names the\ncommand that updates the one that is behind.\n\n```bash\nclaude plugin marketplace update qualixar\nclaude plugin update superlocalmemory@qualixar\n```\n\nFor the other three, replace the directory from the tag you are on.\n\n## Privacy controls and operating modes\n\n\n\n| Mode | What | Core memory path | Optional network behavior |\n|:----:|:-----|:-----------------|:--------------------------|\n| **A** | Local Guardian | Local processing | Model/dependency downloads, connectors, backup, and other enabled integrations may use the network |\n| **B** | Smart Local | Local Ollama enrichment | Same optional integrations as Mode A |\n| **C** | Provider-assisted | Local storage with provider calls | Query or enrichment content is sent to the configured provider |\n\n```bash\nslm mode a # Zero-cloud (default)\nslm mode b # Local Ollama\nslm mode c # Cloud LLM\n```\n\nMode A can run core memory operations without sending memory content to a cloud model provider. This does not disable optional connectors, cloud backup, proxy providers, dependency acquisition, or model downloads; review configuration and network policy for the deployment.\n\nSuperLocalMemory provides local storage, export/erasure commands, provenance, policy, and audit features that can support a compliance program. The software is not a legal certification, and compliance depends on the use case, operator, configuration, and surrounding systems.\n\nAvailable controls include local export and erasure commands, hash-chained audit records, provenance tracking, and ABAC policy enforcement. Verify their behavior and retention boundaries for your deployment; see [docs/compliance.md](docs/compliance.md).\n\n---\n\n## Teams and Enterprise Memory (V4)\n\nV4 includes multi-user, multi-workspace controls for teams and organizations (introduced on the 3.8 line and retained). These are opt-in — personal single-user installs work exactly as before with no required login.\n\n### Users and roles\n\nSLM supports three role tiers within a workspace: **admin**, **member**, and **viewer**.\n\n| Role | Can read memory | Can write memory | Can manage users/config |\n|------|:---------------:|:----------------:|:-----------------------:|\n| admin | yes | yes | yes |\n| member | yes | yes | no |\n| viewer | yes | no | no |\n\nRoles are scoped per workspace (profile). A user may have different roles in different workspaces.\n\n### Workspace isolation\n\nEach workspace (profile) is a fully isolated memory namespace. One workspace cannot read another's personal memories. Shared and global scopes are opt-in and still profile-bounded at the authorization layer.\n\n### Login gate\n\nEnterprise deployments set `require_login = true` in configuration. With login enabled:\n- Every dashboard and API request requires an authenticated session.\n- First-run creates an admin account with a user-chosen password (no default credentials are shipped).\n- Session cookies use `HttpOnly` with optional `Secure` enforcement.\n- Personal installs run with `require_login = false` (loopback owner is trusted).\n\n```bash\nslm config set security.require_login true # Enable for team/enterprise use\n```\n\n### Memory scopes\n\n| Scope | Who can recall | Set with |\n|-------|---------------|----------|\n| `personal` | Owner profile only (default) | `slm remember \"...\" --scope personal` |\n| `shared` | Named profiles the owner grants | `slm remember \"...\" --scope shared --shared-with profile-a,profile-b` |\n| `global` | Any authorized user on this machine | `slm remember \"...\" --scope global` |\n\nRecall is default-deny: shared and global facts are never returned unless the caller explicitly opts in (`--include-shared`, `--include-global`) or the scope policy allows it. See [docs/shared-memory.md](docs/shared-memory.md).\n\n### GDPR and data governance\n\nSLM ships built-in controls that support GDPR compliance programs:\n\n- **Export** — full profile data export as a structured JSONL bundle\n- **Erasure** — profile deletion removes data from 30+ scoped tables; erasure is logged to the tamper-proof audit chain before any data is deleted\n- **Retention rules** — time-based policies (`indefinite`, `gdpr-30d`, `hipaa-7y`, `custom`) applied per profile\n- **Audit trail** — every store, recall, mutation, and erasure produces a hash-chained audit record\n- **PII redaction** — configurable automatic redaction before memory content crosses trust boundaries\n\nThese are engineering controls. Compliance depends on deployment configuration, use case, and operator responsibility. See [docs/compliance.md](docs/compliance.md).\n\n### EU AI Act mode verification\n\nSLM includes a per-mode EU AI Act *technical posture* report (`EUAIActChecker`). It records facts the runtime can know — whether data is configured to stay local, whether generative AI is used, and that transparency / human-oversight need deployment evidence.\n\n**An operating mode does not establish legal compliance under the EU AI Act.** Legal risk classification and conformity assessment depend on intended purpose, affected persons, sector, deployment context, and operator controls. The checker therefore returns `compliant=None` / risk category `undetermined` for every mode and always requires deployment-context review. Mode A/B/C only change technical locality and enrichment options (for example Mode C may send content to a configured provider). See [docs/compliance.md](docs/compliance.md) and `src/superlocalmemory/core/modes.py`.\n\n### Deployment tiers\n\nSLM ships one binary and is configured for the appropriate tier at install or post-install time.\n\n| Tier | Login gate | PII redaction | Retention | Audit |\n|------|:---------:|:-------------:|:---------:|:-----:|\n| **Personal** | off | off | off | on |\n| **Enterprise** | on | on | on | on |\n\nThe installer or `slm reconfigure` sets the tier. Each setting is independently overridable at runtime. Full tier documentation: [docs/deployment-tiers.md](docs/deployment-tiers.md).\n\n### RBAC and teams docs\n\nFull reference: [docs/rbac-teams.md](docs/rbac-teams.md) · [docs/deployment-tiers.md](docs/deployment-tiers.md)\n\n---\n\n## Bounded Loops (V4)\n\nA bounded loop terminates only when an **independent gate** passes — a test\nsuite exit code, a linter, a JSON-schema check, or an SLM-recall condition.\nThe agent's own \"I finished\" message is recorded as advisory context and never\nused as the termination signal. Every lap is persisted to SLM memory under the\ntag `loop:`, so runs are auditable and resumable across sessions.\n\nThree surfaces ship together:\n\n| Surface | How you use it |\n|---------|---------------|\n| **CLI** | `slm loop demo` · `slm loop history [--name ]` · `slm loop show ` |\n| **Skill + agent** | `/slm-loop` skill with the `slm-loop-runner` agent — delegate a task that has a checkable acceptance condition |\n| **MCP tools** | `slm_loop_run` · `slm_loop_history` · `slm_loop_show` — call from any IDE or agent (available in the `code` and `full` MCP profiles) |\n\n```bash\n# Run the built-in convergence demo (no API key needed)\nslm loop demo\n\n# Inspect recorded runs\nslm loop history --name convergence-demo\nslm loop show \n```\n\nLoop laps are stored as ordinary SLM memories and are visible in the dashboard\nunder Knowledge Graph and Memories (filter by tag `loop:`) and in the\nMulti-Agent Memory workspace.\n\n---\n\n## Framework Adapters (V4)\n\nSLM ships nine adapters under `ide/integrations/`: LangGraph, Semantic Kernel,\nMicrosoft Agent Framework, LangChain, LlamaIndex, CrewAI, AutoGen, Google ADK,\nand OpenAI Agents. Each wires SLM as memory and history without replacing the\nframework runtime; its directory contains installation/configuration guidance.\nPydantic AI is not included because it does not expose a formal external-memory\ninterface.\n\n---\n\n## Advanced\n\n| Topic | Link |\n|:------|:-----|\n| Full optimize docs | [docs/optimize-overview.md](docs/optimize-overview.md) · [docs/optimize-cli.md](docs/optimize-cli.md) · [docs/optimize-config.md](docs/optimize-config.md) |\n| Distributed deployment | [docs/distributed-deployment.md](docs/distributed-deployment.md) |\n| Multi-machine mesh | [docs/multi-machine.md](docs/multi-machine.md) |\n| Auto-memory hooks | [docs/auto-memory.md](docs/auto-memory.md) |\n| Architecture + math | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |\n| Published benchmark evidence | [docs/benchmarks.md](docs/benchmarks.md) |\n| CLI reference | [docs/cli-reference.md](docs/cli-reference.md) |\n| MCP tools reference | [docs/mcp-tools.md](docs/mcp-tools.md) |\n| Optional Bounded Loops bridge | [docs/bounded-loops-bridge.md](docs/bounded-loops-bridge.md) |\n| Getting started | [docs/getting-started.md](docs/getting-started.md) |\n| IDE setup (15 configs) | [docs/ide-setup.md](docs/ide-setup.md) |\n| Teams, users, and RBAC | [docs/rbac-teams.md](docs/rbac-teams.md) |\n| Deployment tiers | [docs/deployment-tiers.md](docs/deployment-tiers.md) |\n| pi.dev integration | [docs/pi-dev-integration.md](docs/pi-dev-integration.md) |\n| Skill evolution | [docs/skill-evolution.md](docs/skill-evolution.md) |\n| V2 migration | [docs/migration-from-v2.md](docs/migration-from-v2.md) |\n| Configuration | [docs/configuration.md](docs/configuration.md) |\n| Retrieval score contract | [docs/retrieval-score-contract.md](docs/retrieval-score-contract.md) |\n| Wiki | [github.com/qualixar/superlocalmemory/wiki](https://github.com/qualixar/superlocalmemory/wiki) |\n\nOpen the web dashboard with `slm dashboard`; workspaces appear only when their\nruntime capability is enabled and healthy. See [CHANGELOG.md](CHANGELOG.md) for\nthe complete release history.\n## Research Papers\n\nSuperLocalMemory has a V4 [arXiv preprint](https://arxiv.org/abs/2608.08253) with [Zenodo archive](https://zenodo.org/records/21853302) and [DOI](https://doi.org/10.5281/zenodo.21853302), plus [The Living Brain (V3.3)](https://arxiv.org/abs/2604.04514), [Information-Geometric Foundations (V3)](https://arxiv.org/abs/2603.14588), and [Trust & Behavioral Foundations (V2)](https://arxiv.org/abs/2603.02240).\n\nUse the citation metadata on the linked arXiv or Zenodo records.\n\n## Support / License / Qualixar\nSee [CONTRIBUTING.md](CONTRIBUTING.md), the [Wiki](https://github.com/qualixar/superlocalmemory/wiki), and [LICENSE](LICENSE) (AGPL-3.0). For commercial licensing, see [COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md) or contact varun.pratap.bhardwaj@gmail.com.\nCopyright (c) 2026 Varun Pratap Bhardwaj / Qualixar · [Qualixar](https://qualixar.com) · [research archive](https://huggingface.co/Qualixar). Acknowledgments: [Everything Claude Code](https://github.com/affaan-m/everything-claude-code) informed skill observation; [HKUDS/OpenSpace](https://github.com/HKUDS/OpenSpace) informed skill-evolution verification.\n\n## Star This Project\n\nIf 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.\n\n[![Star SuperLocalMemory on GitHub](https://img.shields.io/github/stars/qualixar/superlocalmemory?style=for-the-badge&logo=github&label=Star%20on%20GitHub)](https://github.com/qualixar/superlocalmemory)\n", "bytes": 46974, "sha": "514b175036fb3324050a93c0577b41579e25c8b63bb2647b3e1daba89c0c4d37", "repo_slug": "varun369/superlocalmemoryv2", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_varun369_superlocalmemory_403ec590/readme" }