name: superlocalmemory description: "AI agent memory with mathematical foundations. Store, recall, search, and manage memories locally. Local data root; optional networked features have separate behavior." version: "4.0.0" author: "Varun Pratap Bhardwaj" license: AGPL-3.0-or-later homepage: https://superlocalmemory.com repository: https://github.com/qualixar/superlocalmemory triggers:

• remember something
• recall memory
• search memories
• memory status
• store fact
• agent memory
• local memory
• memory health

SuperLocalMemory

AI agent memory with a local data root. Five candidate producers (semantic, BM25, temporal, spreading-activation, Hopfield) fuse via RRF, with an entity-graph post-fusion score enhancement — all with mathematical similarity scoring. Mode A operates without sending memory content to a cloud model provider; optional connectors, backup, and proxy providers are explicit choices with separate behavior.

Installation

pip install superlocalmemory
# or
npm install -g superlocalmemory

Quick Start

slm remember "Alice works at Google as a Staff Engineer" --json
slm recall "Who is Alice?" --json
slm status --json

Commands

All data-returning commands support --json for structured agent-native output.

Memory Operations

slm remember "<content>" --json           # Store a memory
slm remember "<content>" --tags "a,b" --json
slm recall "<query>" --json               # Semantic search
slm recall "<query>" --limit 5 --json
slm list --json -n 20                     # List recent memories
slm forget "<query>" --json               # Preview matches (add --yes to delete)
slm forget "<query>" --json --yes         # Delete matching memories
slm delete <fact_id> --json --yes         # Delete specific memory by ID
slm update <fact_id> "<content>" --json   # Update a memory

Diagnostics

slm status --json                         # System status (mode, profile, DB)
slm health --json                         # Math layer health
slm trace "<query>" --json                # Recall with per-channel breakdown

Configuration

slm mode --json                           # Get current mode
slm mode a --json                         # Set mode (a=local, b=ollama, c=cloud)
slm profile list --json                   # List profiles
slm profile switch <name> --json          # Switch profile
slm profile create <name> --json          # Create profile
slm connect --json                        # Auto-configure IDEs
slm connect --list --json                 # List supported IDEs

Bounded Loops

slm loop demo                             # Run built-in convergence demo (no API key needed)
slm loop history [--name <loop-name>]     # List recorded runs from SLM memory
slm loop show <run_id>                    # Show every lap of one run

Loop laps are persisted to SLM memory under the tag loop:<name>. MCP tools slm_loop_run, slm_loop_history, and slm_loop_show are available in the code and full profiles.

Services (no --json)

slm setup                                 # Interactive setup wizard
slm mcp                                   # Start MCP server (for IDE integration)
slm dashboard                             # Open web dashboard
slm warmup                                # Pre-download embedding model

JSON Envelope

Every --json response follows a consistent envelope:

{
  "success": true,
  "command": "recall",
  "version": "4.0.0",
  "data": {
    "results": [
      {"fact_id": "abc123", "score": 0.87, "content": "Alice works at Google"}
    ],
    "count": 1,
    "query_type": "semantic"
  },
  "next_actions": [
    {"command": "slm list --json", "description": "List recent memories"}
  ]
}

Error responses:

{
  "success": false,
  "command": "recall",
  "version": "4.0.0",
  "error": {"code": "ENGINE_ERROR", "message": "Description of what went wrong"}
}

Operating Modes

Dual Interface

SuperLocalMemory works via both MCP and CLI:

• MCP: 24 tools (code profile) for IDE integration (Claude Code, Cursor, Windsurf, VS Code, JetBrains, Zed); includes bounded-loop tools slm_loop_run/history/show
• CLI: commands with --json for scripts, CI/CD, and agent frameworks; includes slm loop demo/history/show

Part of Qualixar | Author: Varun Pratap Bhardwaj (qualixar.com | varunpratap.com)

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 changed in this release. See the CHANGELOG — every release is written up there, in plain language, newest first.

• 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