superlocalmemory 4.1.22 → 4.1.24

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

@@ -0,0 +1,150 @@
+---
+name: slm-compress
+description: Compress large text, tool output, or transcripts to reduce context-window usage while keeping the full 1M window intact — call slm_compress(content, mode, reversible, ttl_seconds) to shrink content; if the result is lossy a ccr_id is returned so you can call slm_retrieve(ccr_id) later to recover the exact original; always fail-open (ok:false → continue with the original).
+when_to_use: "compress context, shrink output, save tokens, context window full, long transcript, compress tool result, reduce tokens, large output, compress text"
+allowed-tools: slm_compress, slm_retrieve, Bash
+---
+
+# slm-compress — Reversible Context Compression (Surface B)
+
+## Purpose
+
+When a tool output, transcript, or accumulated context grows large enough to crowd out working space, `slm_compress` reduces it in-place. The compressed form is used for the remainder of the session; the exact original is recoverable on demand via `slm_retrieve`. This works without a proxy and without touching `ANTHROPIC_BASE_URL`, so the full 1M context window is never sacrificed.
+
+## Primary MCP Tool: slm_compress
+
+```
+slm_compress(
+    content:      str,          # required — text to compress (max 1 MB)
+    mode:         str = "auto",  # "normalize" | "auto" | "aggressive"
+    reversible:   bool = True,  # store original in CCR for later retrieval
+    ttl_seconds:  int = 86400,  # CCR lifetime in seconds (default 24 h)
+) -> dict
+```
+
+### Return dict (all keys always present)
+
+| Key | Type | Meaning |
+|-----|------|---------|
+| `ok` | bool | `True` on success; `False` on internal error or empty input |
+| `compressed` | str | Compressed text (or original on failure) |
+| `strategy` | str | Which strategy was applied (e.g. `"normalize"`, `"none"`) |
+| `tokens_before` | int | Word-count estimate of the input |
+| `tokens_after` | int | Word-count estimate of the output |
+| `ratio` | float | `tokens_after / tokens_before` (lower = more compact) |
+| `lossy` | bool | Whether information was removed |
+| `ccr_id` | str \| None | UUID4 session token; present only when `lossy=True` and `reversible=True` |
+| `note` | str \| None | Human-readable note (e.g. warnings, recovery hint) |
+
+### Mode semantics (verified from source)
+
+- **`"normalize"`** — lossless whitespace collapse; no daemon dependency; `lossy: false`, `ccr_id: null`.
+- **`"auto"`** — delegates to `CompressRouter`; may be lossy depending on daemon config; default.
+- **`"aggressive"`** — requests aggressive compression from the daemon; daemon must have `compress_mode=aggressive` set in config; note field will warn if daemon config does not match.
+
+## Recovery Tool: slm_retrieve
+
+When `slm_compress` returns `lossy: true`, the original is stored under the `ccr_id`. Use `slm_retrieve` to get it back:
+
+```
+slm_retrieve(ccr_id: str) -> dict
+```
+
+| Key | Type | Meaning |
+|-----|------|---------|
+| `ok` | bool | `True` when content was found |
+| `content` | str \| None | Original text, decoded from UTF-8 (or Latin-1 fallback) |
+| `size_bytes` | int | Byte length of the stored original |
+| `error` | str \| None | Error message on failure; `None` on success |
+
+`ccr_id` must be a valid UUID4. Non-UUID4 strings return `ok: false` immediately.
+
+### CCR security rule
+
+`ccr_id` values are **unguessable session tokens**, and the stored original can be read back only by the same agent (or, for a remote caller, the same access key) that compressed it. Treat them like short-lived credentials:
+- Never log them.
+- Never share them across agents.
+- Never pass them as tool arguments to any tool other than `slm_retrieve`.
+- Never compress a `ccr_id` string itself.
+- They expire after `ttl_seconds` (default 24 h); `slm_retrieve` returns `ok: false` after expiry.
+
+## Decision: When to Compress
+
+**Compress when:**
+- A single tool output or transcript exceeds approximately 2 000 characters.
+- You are accumulating repeated context (e.g. full file reads across multiple steps).
+- Context is nearing the point where recall quality or response quality degrades.
+
+**Do NOT compress:**
+- Code you are about to read, edit, or diff — you need every character.
+- JSON you will parse programmatically — compression may alter structure.
+- Secrets, credentials, or `ccr_id` strings.
+- Anything under ~500 characters — overhead exceeds benefit.
+- The compressed form of content already compressed this session.
+
+## Fail-Open Guarantee
+
+`slm_compress` never raises an exception. On any internal error it returns:
+
+```json
+{ "ok": false, "compressed": "<original input>", "ratio": 1.0, ... }
+```
+
+**When `ok` is `false`, continue with the original content.** Never block a task waiting for compression to succeed.
+
+## Worked Example
+
+```python
+# Step 1: compress a large tool output
+result = await slm_compress(
+    content=long_log_text,
+    mode="auto",
+    reversible=True,
+    ttl_seconds=3600,
+)
+
+if result["ok"]:
+    working_text = result["compressed"]
+    ccr_id = result["ccr_id"]   # None if lossless
+else:
+    working_text = long_log_text  # fail-open
+    ccr_id = None
+
+# ... work with working_text ...
+
+# Step 2: restore original when needed (e.g. before final summary)
+if ccr_id:
+    restore = await slm_retrieve(ccr_id=ccr_id)
+    if restore["ok"]:
+        original_text = restore["content"]
+```
+
+## Secondary CLI (fallback when MCP is unavailable)
+
+Prefer the MCP tools above. If you must use the command line:
+
+```bash
+slm compress status [--json]
+slm compress mode safe|aggressive [--json]
+slm compress code on|off [--json]
+slm compress prose on|off [--json]
+slm compress ccr on|off [--json]
+slm compress align on|off [--json]
+```
+
+These subcommands control daemon-level compression settings — they do not compress content inline. For inline compression, use `slm_compress` via MCP.
+
+## Size Cap
+
+Content over 1 MB (1 000 000 bytes UTF-8) is processed but `reversible` is forced to `False` and `ccr_id` will be `None`. The `note` field will state `"content over 1MB: ccr skipped"`.
+
+---
+
+## Related skills
+
+- `slm-cache` — for repeated reads; use cache-aside before compressing a frequently re-read result
+- `slm-status` — check `tokens_saved_compress` and `compress_runs` from `slm_optimize_stats`
+
+---
+
+SuperLocalMemory v4.1.24 · Qualixar · AGPL-3.0-or-later

package/hermes-plugin/skills/slm-getting-started-bot/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: slm-getting-started-bot
+description: First-session orientation for SuperLocalMemory on a headless bot host (Grok Bot, or any Cursor-format plugin install with no hooks, no dashboard, and no interactive setup wizard). What is different here vs. Claude Code/Codex, which 18 tools are actually available, and the first three calls to make.
+when_to_use: |
+  - The very first session after SLM is installed as a Grok Bot / Cursor plugin
+  - "What can I do with SuperLocalMemory here?"
+  - A recall or remember call fails and you are not sure why on this host
+  - Comparing what works here vs. what the other skills describe for Claude Code
+allowed-tools: session_init, remember, recall, switch_profile
+---
+
+# slm-getting-started-bot — First Session on a Headless Bot Host
+
+You are talking to SuperLocalMemory through its MCP server, started as
+`uvx --from superlocalmemory==<version> slm mcp` by the plugin manifest. This
+skill is for the ways that is different from a Claude Code or Codex install —
+read it once per new host, not once per session.
+
+---
+
+## What is NOT available here
+
+Grok Bot (and Cursor's plugin host generally) reads only two parts of a
+plugin: `mcpServers` and `skills`. It does not run:
+
+- **Hooks** — no automatic session-start context load, no automatic
+  checkpoint on session end. Call `session_init` yourself at the start of a
+  session if you want prior context; nothing injects it for you.
+- **Slash commands or sub-agents** — the `commands/` and `agents/` components
+  other SLM plugins ship are Claude-Code-shaped and are not part of this
+  install. Everything you can do here, you do through the MCP tools
+  directly.
+- **A dashboard.** There is no browser UI to check on this host. `slm status`
+  style information comes back from the tools themselves (`session_init`'s
+  response, or asking `recall` for recent memories) — there is nothing to
+  click.
+- **`ANTHROPIC_BASE_URL` or any Claude-specific proxy behavior.** SLM does not
+  depend on it anywhere; nothing to configure here either way.
+
+None of this is a degraded mode — it is the whole surface. Do not tell the
+user a feature is "missing" when it was simply never wired to this host
+format in the first place.
+
+---
+
+## What IS available: the core profile (18 tools)
+
+This plugin sets `SLM_MCP_PROFILE=core`, the smallest tool tier, on purpose —
+a shared, memory-tight computer should not load tool descriptions or RAM for
+tiers it will not use. The 18 tools:
+
+`remember`, `recall`, `search`, `fetch`, `list_recent`, `update_memory`,
+`forget`, `session_init`, `close_session`, `slm_compress`, `slm_retrieve`,
+`slm_cache_set`, `slm_cache_get`, `slm_optimize_stats`, `review_correction`,
+`list_corrections`, `get_memory_summary`, `switch_profile`.
+
+If you are looking at another skill that mentions a tool NOT in this list
+(`build_code_graph`, `mesh_send`, `report_outcome`, `delete_memory`,
+`set_memory_kind`, anything governance/compliance-shaped), that skill describes
+a different, larger profile (`code`, `full`, `power`) — it is accurate for Claude
+Code or Codex installs, not for this one, unless someone has deliberately
+reconfigured `SLM_MCP_PROFILE`. Skip those steps rather than reporting an error.
+
+Two things the core set does cover that other skills explain: `remember` takes
+`kind` and `replaces` (a newer version of a memory should be saved with
+`replaces=<fact_id>`; see `slm-remember`), and `list_corrections` /
+`review_correction` handle the review of an `update_memory` edit. A bot with
+no one to review should prefer `replaces` over `update_memory`.
+
+---
+
+## The first three calls on a new host
+
+1. **`session_init`** — nothing runs this automatically here (no hooks), so
+   call it yourself at the start of the first real session:
+   ```
+   session_init(project_path="<where you are working>", query="")
+   ```
+   Returns recent relevant memories and a session id to pass to later calls.
+
+2. **`remember`** one real fact, before doing anything else, as a smoke test:
+   ```
+   remember(content="First session on this host, verifying setup.", tags="setup", session_id="<sid>")
+   ```
+
+3. **`recall`** it back:
+   ```
+   recall(query="first session verifying setup", session_id="<sid>")
+   ```
+   If this returns the fact, the daemon, the embedding path, and the
+   CPU-only torch install all worked. If it does not, the result still tells
+   you something — see Troubleshooting below.
+
+---
+
+## Cold start is slower here than on a warm laptop
+
+The first `remember`/`recall` on a fresh `SLM_DATA_DIR` has to: resolve
+`uvx`'s pinned `superlocalmemory` package, start the daemon, and warm an
+embedding model (and, unless this is the lite profile, a reranker model) —
+tens of seconds, not milliseconds. A `recall` whose `channel_status` shows
+`warming` (or `no_embedding`) for some channels in that window is not a bug; it
+means the embedding model had not finished loading yet, and the answer is
+incomplete rather than empty. Retry once rather than assuming something is
+broken.
+
+---
+
+## This host already runs the lite bot-host profile
+
+Unless something overrode it, `mcp.cursor.json` sets `SLM_RERANKER_ENABLED=
+false`, `SLM_RERANKER_IDLE_TIMEOUT=120`, and `SLM_MAX_EMBEDDING_WORKERS=1` —
+the RAM-conscious default for a computer shared by every bot on it. Recall
+still runs every other channel (BM25, semantic, entity graph, temporal,
+spreading activation, Hopfield) and fuses them; it just skips the
+cross-encoder re-ranking pass. If recall quality seems to matter more than
+RAM headroom for your use case, the user can set `SLM_RERANKER_ENABLED=true`
+in the manifest's env block — ask before changing it, since it trades RAM for
+quality on a shared box.
+
+---
+
+## Troubleshooting
+
+- **A tool call returns a "profile" or "tool not available" style error** —
+  you are probably calling a tool outside the 18-tool core set. Check the
+  list above before assuming the server is broken.
+- **Everything times out on the very first call of a session** — likely the
+  cold-start warmup described above. Wait and retry once before reporting a
+  failure.
+- **You are not sure whether another bot on this computer can see what you
+  just stored** — read `slm-bot-memory` before storing anything you would
+  not want another bot on this machine to read.
+
+---
+
+## Related skills
+
+- `slm-bot-memory` — cross-bot namespacing and what must never be stored
+- `slm-remember` / `slm-recall` — full parameter reference for the two tools
+  you will use the most
+- `slm-session` — what `session_init`/`close_session` actually do
+
+---
+
+*SuperLocalMemory v4.1.24 · Qualixar · AGPL-3.0-or-later*

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

@@ -0,0 +1,221 @@
+---
+name: slm-governance
+description: Governed-workspace behavior for SuperLocalMemory. Covers roles (admin/member/viewer) and company mode, retention and lifecycle settings, the audit trail, GDPR export and erasure, and how agents must behave when operating under workspace governance. The audit and retention tools need the power MCP profile. Agents must never bypass governance controls.
+when_to_use: |
+  - "What can I do in this workspace?" (role check)
+  - "Move cold memories to archive after 60 days"
+  - "Show the audit trail for recent memory operations"
+  - "Export my data for GDPR compliance"
+  - "Delete all memories about user X (right to erasure)"
+  - "Turn on 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, compact_memories, consistency_check, recall, search, remember, Bash
+---
+
+# slm-governance — Governed Workspace Behavior
+
+SuperLocalMemory can run with named users and roles per workspace (company
+mode), keeps a compliance audit trail, applies a retention lifecycle, and ships
+GDPR export and erasure commands. This skill documents how an agent must behave
+in a governed workspace and what the governance tools really do. The MCP audit
+and retention tools are in the `power` tool set (see `slm-profile`).
+
+---
+
+## Role model
+
+By default SLM is single-user: whoever runs it is the owner and nothing asks for
+a login. Company mode adds named users, each with one role per workspace
+(profile). A role in one workspace grants nothing in another.
+
+| Role | Read | Write | Share (`shared`/`global` writes) | Delete | Manage users and settings |
+|------|------|-------|-------|--------|-----------------|
+| `viewer` | Yes | No | No | No | No |
+| `member` | Yes | Yes | Yes | No | No |
+| `admin` | Yes | Yes | Yes | Yes | Yes |
+
+**Agent behavior by role:**
+
+- **Viewer**: Only call `recall`, `search`, `fetch`, `list_recent` and other
+  reads. Never call `remember`, `update_memory`, `delete_memory` or any write
+  tool. If a write is refused, say so: "This workspace is read-only for my role."
+- **Member**: May write memories, including `scope="shared"` and `scope="global"`
+  when the user explicitly asks for them. May not delete memories or change
+  users, roles or settings.
+- **Admin**: Everything above plus deletion and user administration.
+
+No MCP tool or `slm` command reports your role (only a signed-in dashboard session can ask the daemon, at `GET /api/rbac/whoami`). Do not guess it: attempt
+what the user asked and treat a permission refusal as final. Setting up users,
+roles and "Require login" is done in the dashboard under **Settings → Access**;
+there is no `slm user` or `slm role` command. The machine operator keeps user
+administration in every mode so a mistake cannot lock everyone out.
+
+---
+
+## require-login
+
+When login is required, every operation on memories needs a signed-in user,
+including the connection your assistant uses. SLM handles this at the daemon
+level; agents do not pass credentials in tool calls. If a tool call returns an
+authentication or permission error, you must:
+
+1. Stop the current operation immediately.
+2. Report the requirement to the user.
+3. Never cache, retry, or work around the block.
+
+In this mode, `include_global=True` and `include_shared=True` on `recall` are
+quietly turned off while the recall policy forbids cross-profile reads (the
+default), so an opt-in recall can come back with only personal facts. Do not try
+to work around it. See `slm-scope`.
+
+---
+
+## Retention and lifecycle
+
+Every memory moves through lifecycle states as it goes unused: active, warm, cold,
+archived. Two tools set and inspect that, and a third runs the forgetting cycle.
+They need the `power` tool set.
+
+### Set the thresholds
+
+```
+set_retention_policy(
+  cold_after_days: int = 30,      # days of inactivity before a memory goes cold
+  archive_after_days: int = 90,   # days before it is archived
+)
+```
+
+It sets two thresholds and returns them. There is no `profile_id` argument and
+there are no named retention zones or per-tag policies; tagging a memory does not
+route it to a different policy.
+
+### Look at the state
+
+```
+get_retention_stats(profile_id="")
+get_lifecycle_status(limit=50, profile_id="")
+```
+
+`get_retention_stats` reports, from the retention table, the count and average
+retention score per Ebbinghaus zone (`active`, `warm`, `cold`, `archive`,
+`forgotten`) and the totals. `get_lifecycle_status` counts the active, warm, cold
+and archived state of up to `limit` memories and returns up to ten short
+samples of each. Neither says when the next cycle runs.
+
+### Apply it
+
+```
+forget(dry_run=True)          # preview the decay cycle for the active profile
+compact_memories(dry_run=True) # preview lifecycle-state transitions
+```
+
+The MCP `forget` tool is not a delete: it recomputes retention scores and moves
+memories between zones. `compact_memories` moves memories whose lifecycle state
+has become due (for example cold to archived); it does not merge duplicates. Both
+default to a dry run. Run the preview first, show it to the user, and only then
+pass `dry_run=False`. Do not run either without the user's say-so.
+
+---
+
+## Audit trail
+
+```
+audit_trail(limit: int = 50)
+```
+
+Returns the newest `limit` rows of the compliance audit for the active profile,
+as `{"success", "entries", "count"}`. Each entry has `audit_id`, `profile_id`,
+`action`, `target_type`, `target_id`, `details` and `timestamp`. There are no
+filter arguments. Entries are compliance actions (store, retrieve, delete, export
+and the like).
+
+Use it for compliance reviews, for investigating an unexpected change, and for
+audit reports to a data controller.
+
+---
+
+## GDPR
+
+```bash
+slm gdpr status [--profile P] [--json]            # posture: receipts, audit counts, known gaps; read-only
+slm gdpr export --profile P [--output FILE] [--json]   # Art. 15/20 access and portability
+slm gdpr erase --profile P --dry-run [--json]     # preview an erasure
+slm gdpr erase --profile P --yes [--json]         # Art. 17 erasure, IRREVERSIBLE
+slm gdpr verify --receipt-id ID [--profile P]     # check an erasure receipt (exit 0 ok, 1 tampered, 2 not found)
+```
+
+`slm gdpr erase` erases a **profile**. It refuses to run without both `--profile`
+and `--yes`, and without them it only previews. It is the only irreversible
+operation here, so confirm the subject, the profile and the authority to erase
+with the user before running it. `slm gdpr status` lists the known gaps (for
+example backups and the code graph) rather than claiming completeness.
+
+To remove individual memories rather than a whole profile, use the deletion
+commands from `slm-remember`:
+
+```bash
+slm forget "<subject or project name>" --dry-run --json   # ALWAYS first
+slm forget "<subject or project name>" --yes --json
+slm delete <fact_id> --yes --json
+```
+
+Memories that belong to a reviewed correction cannot be deleted this way; the
+refusal names the case. After an erasure, confirm with `slm recall "<content>"`
+that nothing comes back, and never try to re-derive erased content from other
+stored facts.
+
+---
+
+## Scope enforcement in governed workspaces
+
+- **Viewers** cannot write anything, whatever the `scope` argument.
+- **Members and admins** can write `shared` and `global` facts; writing either
+  scope needs the share permission, which both roles hold.
+- Agents must not split a `global` fact into several `shared` facts, or otherwise
+  accumulate visibility the user did not ask for.
+
+---
+
+## Integrity checks
+
+```
+consistency_check(limit: int = 100)
+```
+
+Runs a sheaf-consistency check over up to `limit` memories and returns pairs of
+facts that contradict each other, with a severity (`fact_a`, `fact_b`,
+`severity`, `content_a`), plus `facts_checked`, `facts_errored` and
+`total_contradictions`. If the checker is disabled it says so in `note`. For the
+health of the store itself (orphan rows, erased words left behind, unfinished
+deletes) use `slm db integrity` and `slm db repair`; see `slm-status`.
+
+---
+
+## Agent checklist for governed workspaces
+
+Before each write operation:
+- [ ] The user asked for it, and a refusal from the workspace is respected
+- [ ] Scope is `personal` unless the user explicitly asked to share
+- [ ] Pass `session_id` so the write is attributed
+
+Before running any destructive or state-changing operation (`forget`,
+`compact_memories`, `slm forget --yes`, `slm gdpr erase --yes`):
+- [ ] The user authorized it in this conversation
+- [ ] Ran the dry run or preview and showed it to the user
+- [ ] GDPR: confirmed the subject or controller authorized the erasure
+
+---
+
+## Related skills
+
+- `slm-scope` — scope model details (personal/shared/global)
+- `slm-profile` — memory profiles and tool sets
+- `slm-remember` — fact storage, corrections and deletion
+- `slm-recall` — retrieval reference (includes scope read flags)
+- `slm-mesh` — mesh tools
+- To use this memory from a web assistant or another computer, see the slm-web-access skill.
+
+---
+
+*SuperLocalMemory v4.1.24 · Qualixar · AGPL-3.0-or-later*