Superlocalmemory

Why SuperLocalMemory?

SuperLocalMemory 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.

Agent-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.

Different 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.

SuperLocalMemory 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.

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.

What V4.0.6 ships. The Living Brain is written for the person who owns the memory, not for the person who built the ranker. It leads with how many questions your memory has actually answered instead of a raw event count, names its ranking phase in words, and refuses to present an untrained starting value as a measured result — where nothing has been measured yet, it says so and says what would change that. Alongside it, a readable consolidation layer: session, daily, and project summaries, each linked back to the memories it was derived from and each explicit about how much of the underlying data it could cover. Entity-level consolidation now actually runs during maintenance, merging repeated facts about the same entity and archiving the originals rather than deleting them. Codex and Bounded Loops are detected and shown among connected clients, labelled by the evidence that supports them — configuration proves setup, not traffic, and the dashboard says which one it has. Presence now distinguishes "no agents are active" from "presence has stopped being recorded", because those looked identical before and only one of them is fine. See reviewed corrections for the correction lifecycle and MCP tools for host-facing commands.

Fixed in V4.0.6. The knowledge graph no longer opens blank. It framed itself against a canvas that had no size yet, spent its whole frame budget drawing off-screen, and stopped — so the graph appeared only after you moved the node slider. Returning to the pane cleared the canvas without redrawing it, which failed the same way for a different reason. Both are fixed, the default node count is 50, and on narrower screens the details and chat panel is reachable instead of stranded a screen-height below the fold. Recall no longer raises when the reranker reports success but returns no scores; it falls back to its existing ranking. Corrections attempted without the daemon now refuse with the reason and the remedy, rather than reporting a transient error that could never clear.

Carried forward from V4.0.5. A correction is a review-gated lifecycle, not an in-place edit: SLM creates an immutable successor, keeps it out of current recall until an authenticated reviewer applies it, and preserves the predecessor for time-aware history. Every candidate path, including cached context, pins, bridge expansion, and scene expansion, uses hard current-truth admission and abstains if that truth cannot be read. slm brain, MCP, HTTP, and the Living Brain share one observation-only BrainTruth snapshot; feedback, external Bounded Loops evidence, and receipt claims are shown honestly but do not silently alter recall, ranking, or model routing. The optional Bounded Loops bridge remains capability-negotiated and independent.

Adaptive-ranking migration. V4.0.6 leaves the optional adaptive ranker off unless an operator sets SLM_RANKING (v1, v2, or v2-ensemble). This does not disable the normal retrieval channels; it prevents feedback and observation data from changing ranking without an explicit operator decision.

• SLM-Mesh — authenticated cross-session and cross-machine peer coordination (messages, locks, shared state, inbox/outbox, optional discovery). Coordination only — not automatic replicated memory.
• Multi-scope memory & profiles — workspaces (profiles) plus personal / shared / global scopes; cross-profile recall is default-deny.
• Cache & compression (context optimization) — exact-match cache with tagged invalidation, safe compression, and opt-in reversible/aggressive paths across proxy, MCP, and skill surfaces.
• Entity Explorer & skill evolution — compiled entity summaries/timelines; opt-in skill lineage, budgets, and verification outcomes.
• 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).
• 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.
• 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.
• 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).
• 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.
• Self-healing lifecycle & admin remediation — stale locks cleared on restart; list/resolve stuck operations from CLI, MCP, or the dashboard.

SLM is one strand of Qualixar's work on AI reliability engineering: making agent behavior observable, bounded, and reproducible instead of best-effort.

The 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.

How SLM fits beside other memory systems

Different products solve different boundaries. SLM is for developers who want one local-first operating control plane—not only an SDK, managed context API, or agent runtime. It combines dated evidence, graph-aware retrieval, cache and compression controls, SLM-Mesh, and MCP/CLI/hooks/dashboard/IDE surfaces in one install.

See the source-linked market comparison for current primary sources and protocol-scoped benchmark evidence. A LoCoMo percentage is comparable only when the dataset scope, answer model, judge, retrieval stack, and release artifact match.

The V4 capability architecture

SuperLocalMemory is one local control plane for persistent agent context. It is not just a vector store: the same runtime can accept evidence, build and govern memory, retrieve bounded evidence for an agent, and expose cache, compression, and SLM-Mesh peer-coordination controls through a CLI, MCP, dashboard, and supported IDE integrations.

Architecture boundary: SQLite + sqlite-vec remain canonical; CozoDB and LanceDB are parity-gated projections; SLM-Mesh coordinates trusted peers rather than replicating a distributed memory database; connectors are opt-in.

Memory boundaries: profiles isolate workspaces by default. Every memory is personal, shared with named profile readers, or global; cross-profile recall is default-deny and must be explicitly enabled. This scoped sharing is local authorization, not SLM-Mesh synchronization. See shared-memory.md.

 IDEs, agents, scripts, connectors, and humans
             │  CLI · MCP (HTTP/stdio) · hooks · dashboard
             ▼
 ┌────────────────────────── SLM CONTROL PLANE ──────────────────────────┐
 │  1. Admission       identity, scope, idempotency, raw evidence         │
 │  2. Queryable core  SQLite facts + FTS durable receipt                  │
 │  3. Enrichment      facts, entities, scenes, time, provenance, graph   │
 │  4. Memory brain    feedback, patterns, rewards, consolidation          │
 │  5. Retrieval       semantic · BM25 · temporal · Hopfield · activation │
 │  6. Context safety  policy, trust, provenance, redaction, budgets      │
 │  7. Operations      lifecycle, audit, cache/compress, mesh, backups    │
 └───────────────────────────────────────────────────────────────────────┘
             │
             ▼
 SQLite + sqlite-vec canonical store  ──► optional graph/vector projections

The seven stages are an execution model, not a promise that every optional enricher or retrieval channel runs for every request. The receipt, trace, and health surfaces expose the stages actually completed by the installed runtime.

What the dashboard exposes

slm dashboard opens a local operational view of the same control plane:

Dashboard visibility is not a substitute for runtime proof: use slm doctor, slm health, slm trace, and the relevant CLI/MCP operation to validate a deployment.

Watch the product walkthrough

Watch the SuperLocalMemory demo on YouTube — 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.

Published LoCoMo evidence (V3 architecture, carried into V4)

The V3 paper evaluates the multi-channel architecture that V4 still runs. Every figure below is protocol-scoped, so a reader can distinguish local retrieval, answer construction, and cloud-assisted evaluation rather than treating unlike runs as one score.

Published category results: Mode A Retrieval scored 72.0% single-hop, 70.3% multi-hop, 80.0% temporal, and 85.0% open-domain. Mode C scored 64.0% single-hop, 100.0% multi-hop, and 86.0% open-domain on its 81-question Conv-30 scope (no temporal category was reported for that run). Across six LoCoMo conversations, the paper reports 71.7% with the information-geometric layers versus 58.9% without them: +12.7pp.

See arXiv:2603.14588 and the official LoCoMo paper for the full protocol, ablation table, and limitations. These are published V3 architecture results carried into V4—not a substitute for a newly rerun release-artifact benchmark.

Quick Start

# Primary path 1 — npm global CLI (Node 18+)
# Creates a package-owned virtual environment. It does not modify system Python.
npm install -g superlocalmemory
slm setup       # Choose mode (A/B/C)
slm doctor      # Verify everything is working

# Primary path 2 — Python CLI + SDK in an activated virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install superlocalmemory
slm setup
slm doctor

# First use
slm remember "Alice works at Google as a Staff Engineer" --json
slm recall "What does Alice do?"
slm status

The default daemon write commits raw evidence plus a relational/FTS projection and returns a durable receipt in queryable state. Enrichment then advances the same operation through enriching to complete, or records a retryable failed state. Use slm remember "..." --sync when the caller must wait for all declared derivation and projector stages. JSON output includes the opaque operation_id, current materialization_state, and fact IDs.

# Wrap your agent — starts proxy + sets environment + launches agent
slm wrap claude
# Your first repeat prompt → CACHE HIT → $0.00
# See savings: slm optimize savings --since 1

Upgrading: use the owner of the installation: npm update -g superlocalmemory or, while the Python virtual environment is active, python -m pip install --upgrade superlocalmemory. Then run slm restart && slm doctor. Repository-clone users use the matching upgrade action in scripts/install.sh or scripts/install.ps1. Installers never move or delete memory data.

Three Pillars

Memory

Current recall has five candidate producers—dense semantic, BM25 lexical, temporal, Hopfield associative, and spreading activation—followed by fusion, optional reranking, and entity-graph score enhancement. The entity graph does not create an independent candidate in the current implementation. Core memory is SQLite-backed. SQLite and sqlite-vec remain the canonical source of truth. The packaged Scale Engine can maintain CozoDB graph and LanceDB vector projections, and it remains outside active retrieval paths until a staged parity witness proves it matches the canonical store. New installations remain on Local Core. During upgrade, slm db scale status can identify a positive pre-v3.7 layout candidate; the operator confirms it with slm db scale adopt. SLM then rebuilds from canonical SQLite, verifies it, and promotes it with a durable recovery journal while retaining the prior directories as a rollback backup. adopt reports restart_required: true; run slm restart before checking daemon health. If proof fails, recall remains on SQLite and status retains the rejected manifest for inspection, retires its replaceable derived payload, and allows a corrected retry.

Canonical ingestion is a durable state machine: raw → queryable → enriching → complete, with failed retaining raw evidence, error details, attempt count, and retry timing. SQLite relational facts and FTS are the queryable checkpoint; optional ANN/vector projectors are verified before complete is granted.

Recalled text is treated as untrusted evidence. Hooks, MCP session_init, CLI session context, and chat use one bounded renderer that redacts recognized secrets, neutralizes forged boundary markers, and attaches provenance. Trusted IDE instruction files contain only the static SLM protocol; fresh memory is retrieved at runtime rather than copied into those files.

Score Contract v2: relevance_score is query-relative relevance; ranking_score is internal ranking utility; memory_confidence belongs to the stored assertion; and trust_score is an evidence-policy signal. Legacy score and confidence remain aliases for one compatibility release. V3.8.0 is explicitly uncalibrated: calibration_status is uncalibrated and answer_confidence is null. See the retrieval score contract.

The retrieval/lifecycle implementation includes three mathematical layers that can run without a cloud LLM:

1. Fisher-informed scoring — dense candidate generation uses cosine similarity; Fisher-derived terms can modify later scoring when their state is available.
2. Sheaf Cohomology for Consistency — algebraic topology detects contradictions via coboundary norms on the knowledge graph.
3. Riemannian Langevin Lifecycle — memory positions evolve on the Poincare ball; neglected memories self-archive, no hardcoded thresholds.

Auto-capture hooks are installed explicitly with slm hooks install (Claude Code) or slm hooks install --agent codex (Codex). Hook latency and capture quality must be evaluated for the target client and workload; V3.8.0 publishes no universal p99 claim.

Multi-scope memory (v3.6.15, 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.

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.

Cache + Compress

One engine, three ways in — choose the surface that fits your setup:

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.

How to choose:

• Metered API (pay-per-token), want every call cached → Proxy (A)
• Pro/Max/Team subscription or any plan where you won't run a proxy → MCP tools (B) or Skill (C)
• Zero configuration → Skill (C): install once, auto-compresses CLAUDE.md and large outputs
• Agent-controlled caching of repeated file reads → MCP tools (B)

Cache: exact-match SQLite lookup is the stable cache path. Semantic cache controls are experimental until release-linked precision, invalidation, and tenant-isolation evidence exists. A cache hit can avoid a provider request, but actual cost and latency savings depend on the intercepted surface and provider.

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.

Savings dashboard: slm optimize savings --since 7 — live USD/INR/tokens saved. Hot-reload config, fail-open.

SLM-Mesh (cross-session / cross-machine coordination)

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.

# Machine A (broker)
export SLM_MESH_HOST=192.168.1.100
export SLM_MESH_SHARED_SECRET=my-secret-key
slm init

# Machine B (client)
export SLM_MESH_PEER_URL=http://192.168.1.100:8765
export SLM_MESH_SHARED_SECRET=my-secret-key
slm init

Eight SLM-Mesh MCP tools: mesh_summary, mesh_peers, mesh_send, mesh_inbox, mesh_state, mesh_lock, mesh_events, mesh_status.

Full docs: docs/multi-machine.md · docs/distributed-deployment.md

Install Paths

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.

After any install path: slm setup → slm doctor → slm warmup (optional, pre-downloads ~500MB embedding model).

Upgrading an existing installation

An npm, pip, or repository update upgrades the SLM runtime; it does not silently rewrite your IDE configuration, hooks, or plugin state. Review the existing integrations first:

slm upgrade-hosts

Then explicitly apply the hosts you approve, for example slm upgrade-hosts --host codex --apply, or use slm upgrade-hosts --all-detected --apply after reviewing the preview. See Host Integration Upgrades for the full safety contract and the Claude Code plugin update path.

MCP + Profiles

SLM supports two MCP transports:

HTTP (recommended, v3.6.7+):

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

Or: claude mcp add --transport http superlocalmemory http://127.0.0.1:8765/mcp/

stdio (universal fallback):

{ "mcpServers": { "superlocalmemory": { "command": "slm", "args": ["mcp"] } } }

MCP Profiles (WP-01)

Control tool surface via SLM_MCP_PROFILE:

Precedence: ALL > TOOLS > PROFILE > default

export SLM_MCP_PROFILE=full   # or core / code / mesh / power / whole
slm mcp

For a predictable small surface, set core explicitly. Leaving the variable unset retains the compatibility default, whose mesh tools follow the local mesh 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.

Per-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.

Claude Code Plugin

Install directly in Claude Code — no system-level npm/pip needed. This is how you get the skills, agents, hooks, commands, and rules (the MCP server is bootstrapped automatically). It is a two-step flow — add the marketplace once, then install:

# 1. Add the Qualixar marketplace (one-time — the repo IS the marketplace)
/plugin marketplace add qualixar/superlocalmemory

# 2. Install the plugin
/plugin install superlocalmemory@qualixar

• Self-bootstraps a Python venv, installs all deps in an isolated SLM_DATA_DIR
• Registers the 16-tool core MCP surface (core16 profile by default; core14 remains a compatibility alias)
• Ships the SLM skills / agents / hooks / commands / rules
• Additive — does not replace an existing SLM install
• slm connect claude-code detects an existing plugin install and links them

Plugin vs Python/npm: python -m pip install superlocalmemory inside an activated virtual environment, or npm i -g superlocalmemory, give you the slm CLI + the MCP server (the tools). The skills/agents/hooks/ commands come only through the plugin above. Use the plugin for Claude Code; use pip/npm for the CLI or other IDEs.

To update later: /plugin marketplace update qualixar then /plugin install superlocalmemory@qualixar.

Codex add-on

For Codex, install the SLM-owned skills, two focused subagents, and four lifecycle hooks explicitly:

slm codex install

This adds only SLM-owned files under ~/.agents/skills, ~/.codex/agents, and ~/.codex/hooks.json; it does not replace another agent's hooks or rewrite ~/.codex/config.toml. Codex requires review and trust for new command hooks: open /hooks after installation. MCP wiring remains a separate explicit step:

slm connect codex

slm connect codex semantically merges the superlocalmemory MCP server into ~/.codex/config.toml, preserving unrelated configuration keys and writing atomically. TOML serializers can normalize whitespace and comments, so it is not a byte-preserving operation; use it only when you want the MCP server configured. Check the result with slm codex status; undo SLM-owned add-ons with slm codex remove.

GitHub Copilot integration

The shipped installer configures the SuperLocalMemory MCP server and additive agent instructions for VS Code with GitHub Copilot:

slm connect vscode-copilot --here

Run it from the project root. It semantically merges the SLM server into .vscode/mcp.json and adds SLM-owned guidance inside .github/copilot-instructions.md, preserving unrelated servers and existing instructions. The generated copilot-plugin/ source bundle is maintained for parity checks, but v3.8.1 does not claim that slm connect installs its prompt, agent, or hook files.

Privacy controls and operating modes