NEWOne memory for every agent, bot and chat windowOne memory for every agent and botWhat’s new →
The SuperLocalMemory mascot presenting the architecture
Architecture

Local-first
by design.

One local control plane for evidence, memory, retrieval, optimization, governance, and peer coordination — memory runs on infrastructure you control. Enterprise deployments add per-workspace isolation, role-based access, GDPR controls, and a per-mode EU AI Act self-assessment. The design makes optional providers, connectors, scale projections, and networked surfaces explicit rather than hiding them behind a single “local” claim.

At a glance

One local memory system.
Every surface your agents use.

Pick a mode to see what changes.

LOCAL CONTROL PLANE

Canonical state stays local. Every external path is visible and explicitly enabled.

1Governed memory2Recall you can trust3Answer check

Mode A: remember and recall make no model-provider call by default. Rules extract facts; a local encoder and cross-encoder retrieve.

MEMORY RUNTIMEeight bounded stages
01

Governed admission

Identity, role, scope and the write gate check every save, then a durable receipt is issued.

02

Canonical store

SQLite, sqlite-vec and FTS are the source of truth, with restore points before upgrades.

03

Enrichment

Facts, entities, time, nine memory kinds and the knowledge graph advance in bounded, retryable stages.

rules, no language model
04

Learning + lifecycle

A bandit and a LightGBM ranker learn from outcomes; a shadow test promotes and rolls back.

05

Recall fusion

Semantic, keyword, temporal, Hopfield and graph candidates are fused, reranked and traced.

local encoder, 768-dim
06

Answer check

Laya on your Mac or Jev online decides whether the memories answer the question, or says “I don’t have that”.

same in every mode
07

Safe context

Secrets are redacted, boundaries neutralised and provenance attached before anything reaches a prompt.

08

Optimize + operate

Exact cache, reversible compression, doctor, audit trail and encrypted backup keep it inspectable.

SQLite remains canonicalProjections serve only once they match it. Web access never moves the database.
Inspect the full system →
Complete system map

One map.
Every component of the control plane.

SuperLocalMemory is a durable memory runtime, not a standalone vector index. The same installed system accepts evidence, derives governed memory, retrieves bounded context, checks whether the memories actually answer the question, and exposes optimization, coordination and optional Web access to agents and operators.

Interactive system map

See the control plane.
Inspect every boundary.

One map of the whole system: callers and the four doors, the save and recall paths, the answer gate and check, pictures and documents, the living brain, governance and SLM-Mesh. Light up a pillar, switch the operating mode, then select any component for its role, data flow, controls, boundary and guide.

Canonical memory pathRecall + evidence flowParity-gated projectionExplicit peer / provider pathOutbound-only Web access link
AGENTS + APPS
CLIMCPDashboardHooks + skillsCursor, Windsurf, Zed, JetBrains9 frameworks
CANONICAL MEMORY RUNTIME12 bounded stages
GOVERNANCE, SCALE + MESH
OPT-IN ADAPTERSProviders, Gmail, Calendar and transcripts stay off until you connect them. Adapter credentials use your OS keychain when one is available.
HOW WEB ACCESS REACHES THE SAME ENGINE
Web app or botOAuth sign-in, only the tools you granted
Connection gatewayChecks owner, app, profile and tool
Connector on your laptopOutbound only; renews its access
The engine on your laptopSame governed recall and writes

The memory database stays on your laptop. Tool requests and results pass through the gateway and the app you connected, and the laptop must be online.

Memory carried through the runtimeatomic facts · episodic scenes · temporal events · entities · nine kinds · graph-linked evidence · profiles + scopes
SQLite + sqlite-vec remain canonical

CozoDB and LanceDB serve only once they match SQLite; Mesh coordinates peers; Web access keeps the memory database on your laptop.

Boundary: installed optional components are not silently promoted. The receipt, trace, health, doctor, and scale commands are the release evidence for the stages actually active in a deployment.

Layer Diagram

Five runtime surfaces.
The ones agents touch most.

This view isolates the five surfaces that agents and operators touch most often. The interactive map above defines every component beneath them.

Entry point
05
MCP + CLI Interface
Documented client configurations · --json structured output · agent-native commands
MCP CLI JSON API
04
Cache Engine
Exact cache opt-in · Semantic experimental · wrapped-call avoidance on hit
Exact Semantic LRU
03
Compression Engine
Content-specific reduction · Reversible storage available · JSON/code preserved in safe mode
Extractive Reversible KV-cache
02
Memory Store
Durable operations · SQLite source of truth · explicit projectors
SQLite M018 Retryable
Foundation
01
Research-Informed Scoring
Cosine dense candidates · Fisher-informed scoring · 4 public arXiv preprints
Fisher-Rao Manifold Public preprints
Layer 05 — MCP + CLI Interface

Agent-native from
the ground up.

The MCP server exposes a profile-selected tool surface. Named client templates configure transport, but each client still needs a release-specific install, session, mutation, recall, restart, and uninstall check.

Data-returning CLI commands support --json where documented, returning an envelope with command metadata and data. Consumers must parse the versioned fields they use rather than infer meaning from display text.

  • Documented clients via MCP — run slm connect --list for the release surface
  • Structured output on documented data-returning CLI commands
  • Versioned fields for agent pipelines; compatibility aliases remain temporary
  • stdin/stdout safe — pipeable to jq, shell scripts, CI/CD pipelines
MCP + CLI — illustrative response shape
# structured recall — agent-parseable envelope $ slm recall "JWT token lifetime" --json   "success": true,   "command": "recall",   "release_channel": "v4",   "data":     "results": [       { "content": "JWT tokens refresh every 15m",         "relevance_score": 0.82, "memory_confidence": 0.97, "rank_position": 1     ],     "retrieval_time_ms": 4.2,     "score_contract_version": "2",     "calibration_status": "uncalibrated",     "answer_confidence": null   ,   "next_actions": [ { "command": "slm list --json" } ] }
Layer 04 — Cache Engine

Exact reuse when enabled.
Semantic reuse stays opt-in.

When Optimize or proxy caching is enabled, exact-match caching keys the normalized request and can avoid a repeated provider call. Caching is off by default in the shipped configuration; runtime latency and provider accounting must be measured.

Semantic cache is experimental and explicitly opt-in because a near-match can return the wrong response. The implementation can record prompt-class threshold state, but production use remains blocked on held-out false-hit calibration, tenant isolation, and invalidation evidence. LRU and TTL settings bound retained entries when configured.

  • SHA-256 exact-match — key equality without a semantic-near-match decision
  • Prompt-class threshold state — experimental until calibrated on a representative corpus
  • LRU eviction with configurable TTL — cache stays bounded
  • Provider call avoided only when the selected surface returns a valid cached response
cache --status
# inspect cache health and savings $ slm cache --status
engine: exact + semantic (opt-in active) entries: deployment-specific hit rate: measure on representative traffic tokens saved: provider-accounting dependent cost saved: verify against provider invoices eviction: inspect configured policy size on disk: measure the deployed cache
✓ Cache available · activation required
Layer 03 — Compression Engine

Content-specific reduction.
Safe and lossy modes separated.

When compression is explicitly enabled, safe handling preserves JSON and code invariants and may produce no reduction. Reversible CCR storage can retain the original for byte-exact retrieval; aggressive prose reduction is a separate opt-in, lossy path.

Prefix ordering can improve reuse when the configured provider supports prompt caching and all provider-specific conditions are met. Pricing, TTL, minimum-prefix, and discount behavior belong to the provider contract and must be measured separately.

  • Safe JSON/code handling — structure preserved; reduction may be zero
  • Structured round trip — verify byte invariants for the selected safe path
  • Safe mode preserves JSON and code and may yield no reduction
  • KV-cache alignment — provider-dependent and measured from real traffic
compression report
# check compression stats for last session $ slm compress --report
mode: extractive (code/JSON detected) input tokens: measure the supplied corpus output tokens: content- and mode-dependent reversible: verify round-trip invariants prefix align: inspect provider eligibility provider hit: measure from provider evidence
✓ Keep compression and provider-cache evidence separate
Layer 02 — Memory Store

Durable first.
Projected second.

Every accepted write owns a durable operation record and raw evidence in the SQLite-backed source of truth. A queryable relational and FTS projection is committed before asynchronous enrichment begins.

Enrichment is lease-owned, checkpointed, retryable, and marked complete only after its declared stages succeed. SQLite remains canonical; CozoDB and LanceDB projections are activated only through explicit prepare, verify, promote, and rollback controls.

  • Durable states: raw → queryable → enriching → complete or failed
  • Queryable checkpoint: relational facts and FTS are available before enrichment completes
  • Failure contract: raw evidence, errors, attempts, and retry timing remain inspectable
  • Optional projectors: ANN and vector indexes are verified before complete is granted
memory store status
# submit durable evidence and inspect the receipt $ slm remember "Use SQLite for durable state" --json
"operation_id": "<opaque-operation-id>" "materialization_state": "queryable" "fact_ids": ["<queryable-fact-id>"] "note": "queryable now; canonical enrichment pending"
✓ Raw evidence is durable before this receipt returns
Layer 01 — Retrieval and Score Enhancement

Inspectable channels.
Separated score meanings.

Dense semantic candidate generation uses cosine similarity. Lexical, temporal, Hopfield associative, and spreading-activation channels can add candidates before fusion; entity-graph information enhances scores after fusion.

Fisher-derived terms can inform later scoring when their state is available. This ranking utility is not answer probability. The score contract keeps query relevance, stored-memory confidence, trust, and internal ranking utility separate.

dFR(p, q) = arccos( Σ √(pi · qi) )
  • Cosine dense retrieval — one of five candidate-producing channels
  • Fisher-informed enhancement — applied later when required state is available
  • No answer probability — answer confidence stays null until a held-out calibrator is frozen
  • Exposure is not truth — access telemetry remains separate from correctness feedback
  • 4 public arXiv preprints — versioned research, not venue-reviewed certification
retrieval — score contract v2 trace
# trace retrieval path on manifold $ slm recall "auth timeout" --trace
dense metric: cosine · later scoring: Fisher-informed when available score contract: relevance · ranking utility · memory confidence · trust candidate sources: dense · BM25 · temporal · associative · spreading activation
rank 1 · relevance_score 0.82 · ranking_score internal → "JWT tokens expire after 15m" · memory_confidence 0.97 calibration_status: uncalibrated answer_confidence: null
✓ trace: candidate ranks + fusion + reranker status + measured latency
Data Flow

What happens when
you run slm recall.

A recall command traverses the configured layers and records runtime evidence. Latency depends on corpus, hardware, warmup state, enabled channels, and reranker availability.

01
CLI receives query Layer 5
The MCP server or CLI dispatcher receives slm recall "JWT token lifetime". If --json is present, the response envelope is prepared. Input and explicit scope are normalized and validated before retrieval.
02
Scope and source of truth selected Layer 2
Profile, project, tenant, lifecycle, and deletion filters constrain the query. SQLite is the normal-path source of truth; optional projectors participate only when they are explicitly configured and healthy.
03
Five candidate producers run Layer 1
Dense semantic, BM25 lexical, temporal, Hopfield associative, and spreading-activation channels can produce candidates. Entity-graph information is a later score enhancement, not a sixth candidate producer.
04
Fusion, reranking, and enhancement Layer 1
Candidate scores are fused with channel provenance. Optional reranking and graph- or Fisher-derived enhancements run only when their required state and dependencies are available; their output remains ranking utility, not answer probability.
05
Score Contract v2 serialized Layer 5
The response separates query-relative relevance, internal ranking utility, stored assertion confidence, and policy trust. Until a held-out calibrator is frozen, calibration_status is uncalibrated and answer_confidence is null.
Storage Detail

Hot, warm, cold.

SQLite is the normal-path source of truth. The scale engine includes CozoDB and LanceDB scale-engine projectors, but promotion is explicit and reversible: prepare an isolated projection, verify parity, then promote or roll back.

Optional graph projector Optional vector projector Canonical store
Engine CozoDB LanceDB SQLite + zstd
Format Property graph Columnar vectors Compressed rows
Access time Benchmark required Benchmark required Benchmark required
Compression None None Content-specific; release benchmark required
Use for Promotion-gated graph projection Promotion-gated vector projection Normal-path durable records, indexes, and configured compressed payloads
Open Source — AGPL v3

Every layer.
All open source.

Read the code, fork it, and audit it. The SuperLocalMemory source and packages are AGPL-3.0-or-later. Optional model providers and external integrations retain their own licenses, terms, and network behavior.

View on GitHub Read the Papers
AGPL v3 · Local-first core · Optional network paths documented separately

Read the guidesArchitecture in detail · Scale engine · Score contract

★ Star on GitHub