superlocalmemory 3.8.13 → 4.0.0

package/docs/pi-dev-integration.md

@@ -1,5 +1,5 @@
 # pi.dev Integration
-> SuperLocalMemory V3 Documentation
+> SuperLocalMemory V4 Documentation
 > https://superlocalmemory.com | Part of Qualixar
 
 pi.dev can connect to SuperLocalMemory through the standard stdio MCP

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.8.13",
+  "version": "4.0.0",
   "description": "Local-first agent memory with MCP and an agent-native CLI. Documented clients include Claude Code, Cursor, and Windsurf.",
   "keywords": [
     "ai-memory",
@@ -81,9 +81,14 @@
     "plugin/",
     "plugin-src/skills/slm-cache/SKILL.md",
     "plugin-src/skills/slm-compress/SKILL.md",
+    "plugin-src/skills/slm-governance/SKILL.md",
     "plugin-src/skills/slm-graph/SKILL.md",
+    "plugin-src/skills/slm-loop/SKILL.md",
+    "plugin-src/skills/slm-mesh/SKILL.md",
+    "plugin-src/skills/slm-profile/SKILL.md",
     "plugin-src/skills/slm-recall/SKILL.md",
     "plugin-src/skills/slm-remember/SKILL.md",
+    "plugin-src/skills/slm-scope/SKILL.md",
     "plugin-src/skills/slm-session/SKILL.md",
     "plugin-src/skills/slm-status/SKILL.md",
     "plugin-src/rules/AGENTS.md",

package/plugin/.claude-plugin/plugin.json

@@ -15,5 +15,5 @@
   "mcpServers": "./.mcp.json",
   "name": "superlocalmemory",
   "repository": "https://github.com/qualixar/superlocalmemory",
-  "version": "3.8.13"
+  "version": "4.0.0"
 }

package/plugin/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- BEGIN SuperLocalMemory v3.8.13 -->
+<!-- BEGIN SuperLocalMemory v4.0.0 -->
 
 ## SuperLocalMemory (SLM) — Agent Rules
 
@@ -39,6 +39,6 @@ slm-recall · slm-remember · slm-session · slm-status · slm-cache · slm-comp
 ### Subagents
 slm-memory-advisor (memory decisions, session hygiene, scope/profile guidance) · slm-optimize-advisor (context compression + KV cache) · slm-governance-advisor (scope/roles/compliance/GDPR)
 
-<!-- END SuperLocalMemory v3.8.13 -->
+<!-- END SuperLocalMemory v4.0.0 -->
 
-SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later

package/plugin/agents/slm-governance-advisor.md

@@ -77,4 +77,4 @@ slm-scope · slm-governance · slm-profile · slm-remember · slm-recall
 # What NOT to do
 Never session_init twice; never forget without dry-run preview; never store secrets; never bypass role checks; never claim an erasure succeeded without verifying via recall.
 
-SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later

package/plugin/agents/slm-loop-runner.md

@@ -68,4 +68,4 @@ assessment. The gate is the authority.
 
 ---
 
-SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later

package/plugin/agents/slm-memory-advisor.md

@@ -46,4 +46,4 @@ slm-recall · slm-remember · slm-session · slm-scope · slm-profile · slm-gov
 # What NOT to do
 Never session_init twice; never forget dry_run=False without reporting preview; never dump a whole file into remember; never invent a memory; never claim "saved" without success:true / clean CLI exit; never bypass scope or governance restrictions.
 
-SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later

package/plugin/agents/slm-optimize-advisor.md

@@ -41,4 +41,4 @@ slm-compress · slm-cache · slm-status · slm-profile
 # What NOT to do
 Never compress code-for-edit/JSON-to-parse/<500 chars; never store secrets/ccr_ids; never let optimize failure block/alter the task; never claim a specific savings %; never carry ccr_ids across profile switches.
 
-SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later

package/plugin/requirements.txt

@@ -1 +1 @@
-superlocalmemory==3.8.13
+superlocalmemory==4.0.0

package/plugin/skills/slm-cache/SKILL.md

@@ -145,4 +145,4 @@ These subcommands control daemon-level cache settings. They do not read or write
 
 ---
 
-SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later

package/plugin/skills/slm-compress/SKILL.md

@@ -147,4 +147,4 @@ Content over 1 MB (1 000 000 bytes UTF-8) is processed but `reversible` is force
 
 ---
 
-SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later

package/plugin/skills/slm-governance/SKILL.md

@@ -245,4 +245,4 @@ Before running any destructive operation (`forget`, `compact_memories`):
 
 ---
 
-*SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-graph/SKILL.md

@@ -311,4 +311,4 @@ profile. See `slm-profile` for the full profile switching workflow.
 
 ---
 
-SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later

package/plugin/skills/slm-loop/SKILL.md

@@ -96,4 +96,4 @@ paused, name the approval needed; when errored, quote the short detail.
 
 ---
 
-SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later

package/plugin/skills/slm-mesh/SKILL.md

@@ -279,4 +279,4 @@ mesh availability.
 
 ---
 
-*SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-profile/SKILL.md

@@ -145,4 +145,4 @@ Name them differently in your MCP config (e.g. `superlocalmemory-personal` and
 
 ---
 
-*SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-recall/SKILL.md

@@ -236,4 +236,4 @@ before recalling, then switch back. See `slm-profile` for workspace switching.
 
 ---
 
-*SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-remember/SKILL.md

@@ -238,4 +238,4 @@ different workspace, use `switch_profile` first. See `slm-profile`.
 
 ---
 
-*SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-scope/SKILL.md

@@ -173,4 +173,4 @@ to review the impact. See `slm-remember` for the full deletion discipline.
 
 ---
 
-*SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-session/SKILL.md

@@ -227,4 +227,4 @@ explicitly and call `recall` with `include_global`/`include_shared` after
 
 ---
 
-*SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-status/SKILL.md

@@ -163,4 +163,4 @@ multi-profile setup. To switch the active profile, see `slm-profile`.
 
 ---
 
-SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later

package/plugin-src/rules/AGENTS.md

@@ -128,4 +128,4 @@ When the SLM MCP server is unavailable, use these CLI equivalents:
 - **slm-optimize-advisor** — context compression and KV cache
 - **slm-governance-advisor** — scope/role compliance, retention policies, GDPR
 
-SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later

package/plugin-src/skills/slm-cache/SKILL.md

@@ -145,4 +145,4 @@ These subcommands control daemon-level cache settings. They do not read or write
 
 ---
 
-SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later

package/plugin-src/skills/slm-compress/SKILL.md

@@ -147,4 +147,4 @@ Content over 1 MB (1 000 000 bytes UTF-8) is processed but `reversible` is force
 
 ---
 
-SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later

package/plugin-src/skills/slm-governance/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: slm-governance
+description: Enterprise compliance and governed workspace behavior for SuperLocalMemory. Covers role-based access (admin/member/viewer), retention policies, audit trail, GDPR data export/erase, and how agents must behave when operating under workspace governance. Requires power MCP profile for audit/retention tools. Agents must never bypass governance controls.
+when_to_use: |
+  - "What can I do in this workspace?" (role check)
+  - "Set a 90-day retention policy on this memory"
+  - "Show the audit trail for recent memory operations"
+  - "Export my data for GDPR compliance"
+  - "Delete all memories for user X (right to erasure)"
+  - "Configure require-login for this workspace"
+  - Enterprise deployment with multi-team shared SLM
+  - Compliance, audit, or data governance task
+allowed-tools: audit_trail, set_retention_policy, get_retention_stats, get_lifecycle_status, recall, search, remember, Bash
+---
+
+# slm-governance — Enterprise Compliance and Governed Workspace Behavior
+
+SuperLocalMemory supports enterprise deployments with role-based access control,
+retention policies, audit logging, and GDPR compliance tooling. This skill
+documents how agents must behave when operating in a governed workspace and how
+to use the governance MCP tools (available in the `power` profile).
+
+---
+
+## Role model
+
+Governed workspaces have three roles:
+
+| Role | Read | Write personal | Write shared/global | Admin operations |
+|------|------|---------------|---------------------|-----------------|
+| `viewer` | Yes | No | No | No |
+| `member` | Yes | Yes | Yes (within access list) | No |
+| `admin` | Yes | Yes | Yes (unrestricted) | Yes |
+
+**Agent behavior by role:**
+
+- **Viewer**: Only call `recall`, `search`, `fetch`, `list_recent`. Never call
+  `remember`, `update_memory`, `forget`, or any write tool. If a write is
+  attempted, fail gracefully: "This workspace is read-only in viewer mode."
+- **Member**: May write personal facts and shared facts with permitted profiles.
+  May NOT write `scope="global"` facts without explicit admin authorization.
+  May NOT call `set_retention_policy`, `audit_trail`, or `compact_memories`.
+- **Admin**: Full access including governance tools in the `power` profile.
+
+An agent operating in a governed workspace must check its role before any write
+operation. Role information is visible in workspace configuration or via
+`slm status --json` (the `role` field, if present).
+
+---
+
+## Retention policies
+
+Retention policies control how long facts are stored before they become eligible
+for decay. Available in the `power` MCP profile.
+
+### Set a retention policy
+
+```
+set_retention_policy(
+  profile_id: str = "",   # "" = active profile
+  days: int = 90,         # facts older than this become decay-eligible
+  zone: str = "default",  # retention zone name
+)
+```
+
+Retention zones let you apply different policies to different fact categories:
+
+```
+# Standard facts: 90-day retention
+set_retention_policy(profile_id="", days=90, zone="default")
+
+# Security findings: 365-day retention (compliance requirement)
+set_retention_policy(profile_id="", days=365, zone="security")
+```
+
+Tag your facts with the zone name to route them to the right policy:
+```
+remember(content="Critical auth bypass in v2.1", tags="security,cve,finding", ...)
+```
+
+### Check retention statistics
+
+```
+get_retention_stats()
+```
+
+Returns zone distribution, average fact age, and decay-eligible counts. Use this
+to verify policies are working as expected.
+
+### Check lifecycle status
+
+```
+get_lifecycle_status()
+```
+
+Reports the state of the retention and decay subsystem — whether decay cycles are
+running, when the next cycle runs, and any backlog.
+
+---
+
+## Audit trail
+
+`audit_trail` is available in the `power` profile. It returns a structured log of
+recent memory operations (writes, reads, profile switches, policy changes).
+
+```
+audit_trail(
+  limit: int = 50,          # number of entries to return
+  operation: str = "",      # filter by operation type (e.g. "remember", "forget")
+  profile_id: str = "",     # filter by profile; "" = active profile
+)
+```
+
+Use this for:
+- Compliance reviews ("what data was written in the last 30 days?")
+- Investigating unexpected memory changes
+- Generating audit reports for data controllers
+
+The audit trail covers MCP and CLI operations. It does not record the content of
+facts by default — only operation type, timestamp, agent ID, and fact ID.
+
+---
+
+## GDPR compliance
+
+### Data export
+
+SLM does not have a dedicated MCP export tool. For GDPR data subject access
+requests, use the CLI:
+
+```bash
+# Export all memories in a profile to JSON
+slm status --json     # confirm active profile
+slm list --limit 9999 --json > export.json
+```
+
+For a complete export including entity graph data, run:
+```bash
+slm status --json
+```
+
+Contact your workspace admin to arrange a full database-level export if the CLI
+output is insufficient for compliance purposes.
+
+### Right to erasure
+
+To erase all memories for a subject or project:
+
+```bash
+# Step 1: preview what will be deleted (ALWAYS do this first)
+slm forget "<subject or project name>" --dry-run --json
+
+# Step 2: review the preview, then execute
+slm forget "<subject or project name>" --yes --json
+```
+
+For targeted deletion by fact ID:
+```bash
+slm delete <fact_id> --yes --json
+```
+
+For data reconstruction prevention: after erasure, confirm the fact is gone by
+running `slm recall "<content>"`. A successful erasure returns no results. Never
+attempt to re-derive erased content from other stored facts.
+
+---
+
+## require-login
+
+When `require_login` is enabled in workspace configuration, agents must
+authenticate before any memory operation. SLM handles authentication at the
+daemon level — agents do not need to pass credentials in tool calls. If an
+agent receives an authentication error from any MCP tool, it must:
+
+1. Stop the current operation immediately.
+2. Report the authentication requirement to the user.
+3. Never cache, retry, or work around the authentication block.
+
+---
+
+## Scope enforcement in governed workspaces
+
+In a governed workspace, scope restrictions are enforced server-side:
+- **Viewers** cannot write any fact regardless of `scope` parameter.
+- **Members** cannot write `scope="global"` unless their access list includes
+  the global scope — attempts return a permission error.
+- **Admins** can write any scope.
+
+Agents must not attempt to work around scope restrictions by splitting a global
+fact into multiple shared facts to accumulate equivalent visibility.
+
+---
+
+## Compact memories (admin-only)
+
+`compact_memories` deduplicates and consolidates stored memories. This is an
+admin operation — it can change fact IDs and remove content.
+
+```
+compact_memories(
+  profile_id: str = "",   # "" = active profile
+  dry_run: bool = True,   # ALWAYS true first — inspect before running
+)
+```
+
+Always run with `dry_run=True` first and review the impact report. Never run
+compaction without admin authorization.
+
+---
+
+## Consistency check (admin-only)
+
+```
+consistency_check(profile_id: str = "")
+```
+
+Verifies data integrity of the memory store — checks for orphaned entities,
+broken references, and index-database mismatches. Use after migrations or
+unexpected shutdowns. Returns a structured report.
+
+---
+
+## Agent checklist for governed workspaces
+
+Before each write operation:
+- [ ] Confirm my role allows writes (viewer → skip; member/admin → proceed)
+- [ ] Confirm scope is appropriate for my role (member → no global)
+- [ ] Set correct tags including zone name if retention policy applies
+- [ ] Pass `session_id` for full audit attribution
+
+Before running any destructive operation (`forget`, `compact_memories`):
+- [ ] Admin authorization confirmed
+- [ ] Ran with `dry_run=True` and reviewed output
+- [ ] GDPR: confirmed the subject or controller authorized the erasure
+
+---
+
+## Related skills
+
+- `slm-scope` — scope model details (personal/shared/global)
+- `slm-profile` — workspace isolation and profile switching
+- `slm-remember` — fact storage reference (includes scope parameters)
+- `slm-recall` — retrieval reference (includes scope read flags)
+- `slm-mesh` — mesh tools (full/power profiles)
+
+---
+
+*SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-graph/SKILL.md

@@ -311,4 +311,4 @@ profile. See `slm-profile` for the full profile switching workflow.
 
 ---
 
-SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later

package/plugin-src/skills/slm-loop/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: slm-loop
+description: Run gate-verified bounded loops with SuperLocalMemory as the durable ledger. Use when a task has a checkable acceptance condition (tests, schema, lint, reconciliation) and you must iterate until an INDEPENDENT gate passes — never stopping just because the agent believes it is done. `slm loop demo` runs a keyless convergence demo; `slm loop history` and `slm loop show <run_id>` inspect past runs whose every lap is persisted as queryable SLM memory (tag `loop:<name>`). Terminal statuses are DONE / HALT / PAUSE / KILLED / ERROR — report them exactly, never converting HALT/PAUSE/ERROR into success.
+when_to_use: "run a bounded loop, gate-verified task, iterate until tests pass, verify against an independent gate, don't trust the agent's own done claim, slm loop, convergence loop, loop until green, loop ledger, resume a loop"
+allowed-tools: Bash, slm_recall
+---
+
+# slm-loop — Bounded, gate-verified agent loops
+
+## The one rule
+
+A bounded loop is complete **only when an independent gate passes** — not when
+the agent claims it is finished. The agent's own "I'm done" signal is recorded
+for audit and is *never* used to terminate the loop. If you take one thing from
+this skill: **the gate is the authority.**
+
+Use a bounded loop whenever the goal has a mechanical, checkable contract: a
+test suite, a JSON schema, a linter, a reconciliation rule, a citation checker,
+a security scan. When the goal is subjective, keep a human approval gate (see
+rungs below).
+
+## What SLM adds
+
+Every lap is written to SuperLocalMemory as a durable, queryable memory (tagged
+`loop:<name>`, session `loop:<run_id>`). That makes a run:
+
+- **auditable** — inspect the decision + gate verdict + budget for each lap;
+- **resumable / historical** — a run's ledger survives across sessions;
+- **discoverable** — visible via `slm recall`, the dashboard, and any
+  SLM-integrated tool, alongside everything else the agent remembers.
+
+## CLI
+
+```bash
+slm loop demo [--iterations N] [--json]   # keyless convergence demo
+slm loop history [--name NAME] [--json]   # list recorded runs
+slm loop show <run_id> [--json]           # every lap of one run
+```
+
+`slm loop demo` proposes a fix, checks it against a deterministic gate that
+passes on lap 3, and records the run — a zero-setup way to see the control flow
+and confirm the SLM-backed ledger works end to end.
+
+## The bounds
+
+A loop runs inside a safety envelope. Any bound tripping ends the run with
+`HALT` (never a success):
+
+- **max_iterations** — a hard lap cap.
+- **no_progress_window** — consecutive no-change laps before halting a spinning
+  agent.
+- **token budget / wall-clock** — cumulative ceilings.
+- **kill switch** — set `SLM_LOOP_KILL` to stop before the next lap.
+- **approval rung** — L1 (report), L2 (assisted, pauses for approval), L3
+  (unattended). L2/L3 require approval before a passing gate is accepted as
+  DONE unless approval is explicitly configured off.
+
+## Terminal statuses — report exactly
+
+| Status   | Meaning |
+|----------|---------|
+| `DONE`   | The independent gate passed **and** approval was granted or not required. |
+| `HALT`   | A bound tripped (iterations, no-progress, token, or wall-clock). |
+| `PAUSE`  | The gate passed but required approval is not yet granted. |
+| `KILLED` | The external kill switch tripped between laps. |
+| `ERROR`  | The runner or gate failed to execute; inspect the lap detail. |
+
+Say `DONE` only when the status is exactly `DONE`. Never describe `HALT`,
+`PAUSE`, or `ERROR` as success. When halted, name which bound tripped; when
+paused, name the approval needed; when errored, quote the short detail.
+
+## Reporting workflow
+
+1. Run or resume the loop.
+2. Read back the ledger with `slm loop show <run_id>` (or `slm recall` on tag
+   `loop:<name>`).
+3. Report the exact terminal status, the lap count, and the gate's final
+   verdict. Include the `run_id` so the run can be re-inspected later.
+
+## Gate discipline
+
+- The gate verifies; the runner only proposes. They are separate.
+- Prefer a typed, parseable gate (a test exit code, a schema validation, a
+  scanner report) over a vague check. A missing tool, an empty report, or a
+  crashed scanner is **not** a clean pass — fail closed.
+- Never use "an LLM decides it looks good" as the gate. That reintroduces the
+  exact failure mode bounded loops exist to remove.
+
+---
+
+## Related skills
+
+- `slm-status` — confirm SLM is healthy before relying on the ledger.
+- `slm-recall` — query a loop's laps directly (`loop:<name>` tag).
+- `slm-session` — session lifecycle around a longer loop run.
+
+---
+
+SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later