SuperLocalMemory V2

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 a7-layercontrol 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 storewhatan agent learned — it recordswhen. 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.

Fixed in V4.0.7.Version numbers disagreed across the project — the pip requirement pins, npm lockfile, editor plugin manifest, citation metadata and lockfile all still named the previous release, so installing fromrequirements.txtfetched the wrong version; one script now sets all fifteen. Stale-memory checks reported "nothing is stale" when code linking was simply switched off, and pointed at a setting that did not exist.slm gdprwas missing fromslm help. Consolidation, handed something that was neither a database handle nor a path, created a file named after the object instead of refusing it.

Carried forward from V4.0.5 and V4.0.6.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 — cached context, pins, bridge 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 never silently alter recall, ranking or model routing. The Living Brain leads with how many questions your memory has answered rather than a raw event count, and says so plainly where nothing has been measured yet. The knowledge graph opens reliably, with a default of 50 nodes and its details panel reachable on narrow screens. The optional adaptive ranker stays off unless an operator setsSLM_RANKING(v1,v2, orv2-ensemble) — that gate prevents feedback and observation data from changing ranking without an explicit decision, and does not disable the normal retrieval channels.

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.

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, andSLM-Meshpeer-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-Meshcoordinates trusted peers rather than replicating a distributed memory database; connectors are opt-in.

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.

slm dashboardopens a local operational view of the same control plane:

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

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 scored72.0%single-hop,70.3%multi-hop,80.0%temporal, and85.0%open-domain. Mode C scored64.0%single-hop,100.0%multi-hop, and86.0%open-domain on its 81-question Conv-30 scope (no temporal category was reported for that run). Across six LoCoMo conversations, the paper reports71.7%with the information-geometric layers versus58.9%without them:+12.7pp.

# 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 inqueryablestate. Enrichment then advances the same operation throughenrichingtocomplete, or records a retryablefailedstate. Useslm remember "..." --syncwhen the caller must wait for all declared derivation and projector stages. JSON output includes the opaqueoperation_id, currentmaterialization_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 superlocalmemoryor, while the Python virtual environment is active,python -m pip install --upgrade superlocalmemory. Then runslm restart && slm doctor. Repository-clone users use the matchingupgradeaction inscripts/install.shorscripts/install.ps1. Installers never move or delete memory data.

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 statuscan identify a positive pre-v3.7 layout candidate; the operator confirms it withslm 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.adoptreportsrestart_required: true; runslm restartbefore 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, withfailedretaining raw evidence, error details, attempt count, and retry timing. SQLite relational facts and FTS are the queryable checkpoint; optional ANN/vector projectors are verified beforecompleteis granted.

Recalled text is treated as untrusted evidence. Hooks, MCPsession_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.

The retrieval/lifecycle implementation includes three mathematical layers that can run without a cloud LLM:
- Fisher-informed scoring— dense candidate generation uses cosine similarity; Fisher-derived terms can modify later scoring when their state is available.
- Sheaf Cohomology for Consistency— algebraic topology detects contradictions via coboundary norms on the knowledge graph.
- Riemannian Langevin Lifecycle— memory positions evolve on the Poincare ball; neglected memories self-archive, no hardcoded thresholds.

Auto-capture hooks are installed explicitly withslm hooks install(Claude Code) orslm 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.

Multilingual models:configure an OpenAI-compatible embedding endpoint such as Ollama, vLLM, LiteLLM,bge-m3,multilingual-e5, orQwen3-Embedding. Language coverage and retrieval quality depend on the selected model and should be evaluated for the deployment corpus.

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.

- 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)orSkill (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-Meshis 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 isnota 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

EightSLM-MeshMCP tools:mesh_summary,mesh_peers,mesh_send,mesh_inbox,mesh_state,mesh_lock,mesh_events,mesh_status.

V4 platform support:Apple Silicon macOS, 64-bit Windows, and 64-bit Linux. Intel Mac and 32-bit Windows are not supported by the patchedcryptography50 runtime.

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

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:

{ "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/

Install directly in Claude Code — no system-level npm/pip needed. This is how you get theskills, 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 isolatedSLM_DATA_DIR
- Registers the 16-tool core MCP surface (core16profile by default;core14remains a compatibility alias)
- Ships the SLM skills / agents / hooks / commands / rules
- Additive — does not replace an existing SLM install
- slm connect claude-codedetects an existing plugin install and links them

Plugin vs Python/npm:python -m pip install superlocalmemoryinside an activated virtual environment, ornpm i -g superlocalmemory, give you theslmCLI + the MCP server (thetools). Theskills/agents/hooks/ commandscome 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 qualixarthen/plugin install superlocalmemory@qualixar.

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

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/hooksafter installation. MCP wiring remains a separate explicit step:

slm connect codexsemantically merges thesuperlocalmemoryMCP 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 withslm codex status; undo SLM-owned add-ons withslm codex remove.