superlocalmemory 3.7.8 → 3.8.1

package/plugin/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 v3.8.1 · Qualixar · AGPL-3.0-or-later*

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

@@ -285,7 +285,8 @@ If `build_code_graph` returns `files_parsed: 0`, no supported source files were
 
 ## Profile Requirement
 
-This skill uses graph tools that are only active under the `code` MCP profile. Your plugin `.mcp.json` must include:
+This skill uses graph tools that are only active under the `code` MCP profile
+(or `full` / `power`). Your plugin `.mcp.json` must include:
 
 ```json
 "env": {
@@ -293,8 +294,21 @@ This skill uses graph tools that are only active under the `code` MCP profile. Y
 }
 ```
 
-Without this, the six graph tools are not registered and will appear as unknown tools. Run `slm status` to confirm the active profile.
+Without this, the six graph tools are not registered and will appear as unknown
+tools. Run `slm status` to confirm the active profile.
+
+**Switching profiles at runtime (v3.8.0+):** Use `switch_profile("code")` via
+MCP to activate the code profile in a session that started with a different
+profile. See `slm-profile` for the full profile switching workflow.
+
+---
+
+## Related skills
+
+- `slm-profile` — workspace isolation and profile switching (required for code tools)
+- `slm-recall` — retrieve architectural decisions before graph queries
+- `slm-status` — confirm the active profile and graph index health
 
 ---
 
-SuperLocalMemory v3.6.18 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v3.8.1 · Qualixar · AGPL-3.0-or-later

package/plugin/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 v3.8.1 · Qualixar · AGPL-3.0-or-later

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

@@ -0,0 +1,282 @@
+---
+name: slm-mesh
+description: Cross-session peer coordination via the SLM mesh network. Lets multiple AI agent sessions on the same machine discover each other, send messages, share lightweight state, and lock files to avoid conflicts. Requires full, power, or mesh MCP profile. All 8 tools are MCP-only — there is no CLI fallback.
+when_to_use: |
+  - Multiple agent sessions running simultaneously on the same machine
+  - "Announce what I'm working on to other sessions"
+  - "Check if another agent has locked a file before I edit it"
+  - "Send a message to the other Claude session"
+  - "Is anyone else working on this project?"
+  - Parallel agent workflows needing coordination
+  - Cross-session state sharing without persisting to the memory store
+allowed-tools: mesh_summary, mesh_peers, mesh_send, mesh_inbox, mesh_state, mesh_lock, mesh_events, mesh_status, Bash
+---
+
+# slm-mesh — Cross-Session Peer Coordination
+
+The mesh network lets multiple AI agent sessions on the same machine discover
+each other and coordinate in real time — without writing to the persistent
+memory store. Mesh messages are transient (48-hour TTL); they complement memory
+(which is durable) rather than replacing it.
+
+Mesh is local-only: it uses the SLM daemon as a local broker. No data leaves
+the machine.
+
+---
+
+## Profile requirement
+
+Mesh tools are available in the `full`, `power`, and `mesh` MCP profiles.
+Confirm the active profile with `slm status` before calling mesh tools. If the
+tools are not available, switch to `full` profile with `switch_profile("full")`
+(requires `code` or higher active profile). See `slm-profile`.
+
+---
+
+## Tool reference
+
+### 1. `mesh_summary` — announce what this session is doing
+
+```
+mesh_summary(summary: str = "") -> dict
+```
+
+Call at session start to register on the mesh and announce your purpose. Other
+sessions can see your summary via `mesh_peers`. The session stays alive via
+automatic heartbeat.
+
+```
+mesh_summary(summary="Refactoring auth module in api/src/auth/")
+```
+
+Response: `{peer_id, summary, project_path, registered, heartbeat_active, broker_response}`
+
+Call this once at the start of any session that will participate in the mesh.
+The peer registration happens automatically at MCP startup, but calling
+`mesh_summary` sets the human-readable description that other agents see.
+
+---
+
+### 2. `mesh_peers` — list active sessions
+
+```
+mesh_peers() -> dict
+```
+
+Returns all active peer sessions on this machine.
+
+```
+mesh_peers()
+```
+
+Response: `{peers: [{peer_id, summary, project_path, last_seen}], count, my_peer_id}`
+
+Use this to discover other sessions before sending a message or checking for
+conflicts.
+
+---
+
+### 3. `mesh_send` — send a message to another session
+
+```
+mesh_send(
+  to: str,       # peer_id | "broadcast" | "project:/path/to/dir"
+  message: str,  # max 4 KB — use file paths for large data
+) -> dict
+```
+
+Send a targeted, broadcast, or project-wide message.
+
+```
+# Direct message to a specific peer
+peers = await mesh_peers()
+target_id = peers["peers"][0]["peer_id"]
+mesh_send(to=target_id, message="I'm starting work on auth/handler.py — please hold off")
+
+# Broadcast to all sessions
+mesh_send(to="broadcast", message="Deploying to staging in 5 minutes")
+
+# Message all sessions working in the same project
+mesh_send(to="project:/Users/me/myproject", message="Tests are green on main")
+```
+
+**4 KB message cap.** For large payloads (diffs, file contents), write to a file
+and send the path instead. The circuit breaker opens automatically if the daemon
+is repeatedly unreachable — `mesh_send` returns `ok: false` in that case.
+
+---
+
+### 4. `mesh_inbox` — read messages sent to this session
+
+```
+mesh_inbox() -> dict
+```
+
+Returns unread messages (direct, broadcast, and project-targeted). Messages are
+automatically marked as read after retrieval.
+
+```
+inbox = await mesh_inbox()
+for msg in inbox["messages"]:
+    print(msg["from"], msg["content"])
+```
+
+Response: `{messages: [{id, from, content, sent_at, read}], count, unread}`
+
+Messages auto-expire after 48 hours.
+
+---
+
+### 5. `mesh_state` — get or set shared coordination state
+
+```
+mesh_state(
+  key: str = "",
+  value: str = "",
+  action: str = "get",   # "get" | "set"
+) -> dict
+```
+
+Shared state is visible to all authenticated peers. Use it for non-secret
+coordination metadata: feature flags, task assignments, progress markers.
+
+```
+# Set state
+mesh_state(key="deploy_in_progress", value="true", action="set")
+mesh_state(key="current_reviewer", value=my_peer_id, action="set")
+
+# Read one key
+mesh_state(key="deploy_in_progress", action="get")
+
+# Read all state
+mesh_state(action="get")
+```
+
+**Security constraint:** Credentials, tokens, passwords, and API keys are
+rejected by the broker. Never store secrets in shared state.
+
+---
+
+### 6. `mesh_lock` — file lock coordination
+
+```
+mesh_lock(
+  file_path: str,         # must be an absolute path
+  action: str = "query",  # "query" | "acquire" | "release"
+) -> dict
+```
+
+Check, acquire, or release a file lock before editing a shared file.
+
+```
+# Step 1: check if the file is already locked
+lock = await mesh_lock(file_path="/abs/path/to/auth/handler.py", action="query")
+
+if lock.get("locked"):
+    print(f"File is locked by {lock['locked_by']} — wait")
+else:
+    # Step 2: acquire the lock
+    mesh_lock(file_path="/abs/path/to/auth/handler.py", action="acquire")
+
+    # ... edit the file ...
+
+    # Step 3: release the lock when done
+    mesh_lock(file_path="/abs/path/to/auth/handler.py", action="release")
+```
+
+`file_path` must be an absolute path (starts with `/` on Unix, drive letter on
+Windows). Relative paths are rejected.
+
+---
+
+### 7. `mesh_events` — recent mesh activity log
+
+```
+mesh_events() -> dict
+```
+
+Returns the activity log for the mesh network: peer joins, leaves, messages sent,
+and state changes. Use to understand what other sessions have been doing.
+
+---
+
+### 8. `mesh_status` — mesh broker health
+
+```
+mesh_status() -> dict
+```
+
+Returns broker uptime, peer count, and connection health. Use at session start
+to confirm the mesh is available before relying on coordination.
+
+Response includes: `broker_up`, `peer_count`, `uptime_seconds`, `my_peer_id`,
+`heartbeat_active`.
+
+---
+
+## Common workflow: parallel agents coordinating on a shared repo
+
+```
+# Both agents call at session start:
+await mesh_summary(summary="Working on feature/auth-refactor")
+
+# Agent A: check who else is active
+peers = await mesh_peers()
+# → sees Agent B working on the same project
+
+# Agent A: before editing a shared file
+lock = await mesh_lock("/repo/src/auth/handler.py", action="query")
+if not lock.get("locked"):
+    await mesh_lock("/repo/src/auth/handler.py", action="acquire")
+    # ... edit handler.py ...
+    await mesh_lock("/repo/src/auth/handler.py", action="release")
+
+# Agent A: after finishing a phase
+await mesh_send(to="project:/repo", message="Auth refactor complete — handler.py ready for review")
+
+# Agent B: check inbox
+inbox = await mesh_inbox()
+```
+
+---
+
+## Mesh vs memory: when to use which
+
+| Need | Use |
+|------|-----|
+| Ephemeral coordination signal (< 48h) | `mesh_send` / `mesh_state` |
+| Durable fact across sessions/days | `remember` |
+| File conflict prevention | `mesh_lock` |
+| Cross-profile fact sharing | `scope="shared"/"global"` on `remember` |
+| Session announcement | `mesh_summary` |
+| Finding parallel agents | `mesh_peers` |
+
+---
+
+## Error handling
+
+All 8 mesh tools return structured errors — they never raise exceptions.
+
+| Error | Cause | Action |
+|-------|-------|--------|
+| `broker_up: false` from `mesh_status` | Daemon not running or mesh not configured | Run `slm status` to check daemon health |
+| `ok: false` from `mesh_send` with circuit-breaker message | Repeated daemon unreachability | Daemon unreachable; stop sending until broker is up |
+| `ok: false` from `mesh_lock` | Lock operation failed | Check `file_path` is absolute; retry once |
+| Empty `peers` from `mesh_peers` | No other sessions registered | You're the only active session |
+
+Mesh failures are non-fatal for the primary task. If `mesh_status` shows
+`broker_up: false`, proceed without mesh coordination — do not block work on
+mesh availability.
+
+---
+
+## Related skills
+
+- `slm-profile` — activate full/power/mesh profile to access mesh tools
+- `slm-scope` — for durable cross-profile sharing (complement to transient mesh state)
+- `slm-remember` — persist coordination decisions that should survive session end
+- `slm-governance` — enterprise governance of mesh (who can send/receive)
+
+---
+
+*SuperLocalMemory v3.8.1 · Qualixar · AGPL-3.0-or-later*