superlocalmemory 4.1.22 → 4.1.24

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

@@ -1,8 +1,8 @@
 ---
 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, recall
+description: Gate-verified bounded loops with SuperLocalMemory as the durable ledger. Use when a task has a checkable acceptance condition and you must iterate until an INDEPENDENT gate passes — never stopping because the agent believes it is done. `slm_loop_run` (MCP) waits, under hard bounds, for a recall gate to pass; `slm loop demo` shows the control flow keyless; `slm loop history` and `slm loop show <run_id>` (or `slm_loop_history` / `slm_loop_show`) inspect past runs, whose every lap is stored 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, wait for another agent's result"
+allowed-tools: slm_loop_run, slm_loop_history, slm_loop_show, recall, Bash
 ---
 
 # slm-loop — Bounded, gate-verified agent loops
@@ -16,19 +16,71 @@ 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).
+a security scan. When the goal is subjective, keep a human approval gate.
+
+## What SLM runs, and what you run
+
+SLM's loop engine runs the laps, enforces the bounds, calls the gate and writes
+the ledger. It does **not** start your tests or linters: it carries no
+subprocess or sandbox machinery. What each surface gives you:
+
+| Surface | What it does |
+|---|---|
+| `slm_loop_run` (MCP) | A *watcher*: each lap is a recall of `gate_query`; the loop ends when a confident match appears, or a bound trips. Use it to wait for a verification or coordination memory another agent will write (for example "build passed"). |
+| `slm loop demo` (CLI) | A keyless convergence demo: a stub proposer, a deterministic gate that passes on lap 3, every lap recorded. Proves the engine and ledger work end to end. |
+| `slm loop history`, `slm loop show` / `slm_loop_history`, `slm_loop_show` | Read the ledger of past runs. |
+| `superlocalmemory.loops.run_bounded_loop` (Python) | The engine itself, for code that supplies its own runner and gate callables. |
+
+For a task whose gate is a command (`pytest -q`, a schema validation), you run
+that command yourself each lap with Bash and read its exit code; the discipline
+below still applies, but SLM is not recording those laps. For graph runs with
+receipts, use the separate Bounded Loops product; SLM can take a read-only
+snapshot of its finished runs with `observe_bounded_loop_evidence(workspace)`
+(an absolute path), which records observations only and never changes recall or
+ranking.
 
 ## 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:
+Every lap SLM runs is written 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;
+- **auditable** — inspect the decision, gate verdict and budget for each lap;
+- **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.
 
+## MCP: `slm_loop_run`
+
+```
+slm_loop_run(
+  name: str,                    # 1–128 chars; also the memory tag
+  gate_query: str,              # the recall the gate checks each lap (up to 2000 chars)
+  gate_min_score: float = 0.0,  # minimum top-result score to pass
+  max_iterations: int = 20,     # hard lap cap, 1–200
+  max_wallclock_s: float = 15.0,# hard time cap; 0 disables; never more than 120
+  poll_interval_s: float = 1.0, # wait between laps; at least 0.25
+  max_tokens: int = 0,          # optional token budget; 0 disables
+  no_progress_window: int = 0,  # halt after N no-change laps; leave 0 for a watcher
+  require_support: bool = False,# pass only if the answer check ran and judged it sufficient
+)
+```
+
+The call **blocks** until the gate passes or a bound trips, then returns
+`{ok, status, reason, passed, laps, run_id, ledger: [{lap, decision, passed, detail}]}`.
+The gate recalls at most three memories per lap and ignores the loop's own
+ledger entries, so only a memory written by someone else can satisfy it. A
+recall the answer check judged insufficient never passes, even with a high
+score; with `require_support=True` an unchecked recall (check off, busy,
+loading, out of time) does not pass either. When the answer check is on, each
+lap asks it once about those memories; with the online check that is a request
+to the provider and may be billed. `slm_loop_run` is not available to remote
+callers.
+
+```
+slm_loop_history(name, limit=20)   # runs recorded under a loop name
+slm_loop_show(run_id, limit=200)   # every lap of one run, in order
+```
+
 ## CLI
 
 ```bash
@@ -37,9 +89,7 @@ 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.
+There is no `slm loop run`.
 
 ## The bounds
 
@@ -49,11 +99,14 @@ A loop runs inside a safety envelope. Any bound tripping ends the run with
 - **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.
+- **token budget / wall-clock** — cumulative ceilings, checked again after each
+  lap, so an overshooting lap halts even if its gate would pass.
+- **kill switch** — a non-empty `SLM_LOOP_KILL` in the loop's process
+  environment stops it before the next lap, with status `KILLED`.
 - **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.
+  (unattended). L2 and L3 require approval before a passing gate is accepted as
+  DONE unless approval is explicitly configured off. `slm_loop_run` and the demo
+  run at L1, so `PAUSE` arises only from code that sets a higher rung.
 
 ## Terminal statuses — report exactly
 
@@ -72,8 +125,8 @@ 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>`).
+2. Read back the ledger with `slm_loop_show` or `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.
 
@@ -91,9 +144,10 @@ paused, name the approval needed; when errored, quote the short detail.
 ## 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-recall` — query a loop's laps directly (`loop:<name>` tag), and the
+  answer-check fields the recall gate depends on.
 - `slm-session` — session lifecycle around a longer loop run.
 
 ---
 
-SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.24 · Qualixar · AGPL-3.0-or-later

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

@@ -1,6 +1,6 @@
 ---
 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.
+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. Available in the default tool set and in the full, power and mesh MCP profiles. Only `slm mesh status` and `slm mesh peers` exist on the command line; the other tools are MCP-only.
 when_to_use: |
   - Multiple agent sessions running simultaneously on the same machine
   - "Announce what I'm working on to other sessions"
@@ -19,17 +19,21 @@ 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.
+By default the mesh is local: the SLM daemon on this machine is the broker and
+nothing leaves it. Two machines can be joined only if the user sets
+`SLM_MESH_PEER_URL` and `SLM_MESH_SHARED_SECRET` for their daemons; then peers and
+messages cross to the other machine. Do not configure that yourself.
 
 ---
 
 ## 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`.
+Mesh tools are registered in the `full`, `power` and `mesh` MCP tool sets and in
+the default set that applies when the host configures none. They are not in
+`core` or `code`. The tool set is fixed when the MCP server starts, and
+`switch_profile` cannot change it (it changes the active memory profile). If the
+tools are missing, check `SLM_MCP_PROFILE` in the host's MCP config and ask the
+user before changing it. See `slm-profile`.
 
 ---
 
@@ -209,8 +213,9 @@ 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`.
+Response includes: `broker_up`, `peer_count` (active peers, with
+`remote_peer_count`, `local_session_count` and stale counts alongside),
+`uptime_s`, `my_peer_id`, `heartbeat_active`.
 
 ---
 
@@ -259,7 +264,7 @@ 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 |
+| `broker_up: false` from `mesh_status` | Daemon not running or mesh not configured | Run `slm mesh status` (prints the broker's answer) or `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 |
@@ -272,11 +277,11 @@ mesh availability.
 
 ## Related skills
 
-- `slm-profile` — activate full/power/mesh profile to access mesh tools
+- `slm-profile` — which tool sets include the 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 v4.1.22 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.24 · Qualixar · AGPL-3.0-or-later*

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

@@ -1,150 +1,159 @@
 ---
 name: slm-profile
-description: Workspace isolation and runtime profile switching for SuperLocalMemory. Each profile is a fully independent memory namespace — separate facts, code graphs, and tool sets. Use switch_profile (MCP, requires code/full/power profile) to change the active workspace without restarting. Check the active profile with slm status. Required when working across multiple projects, clients, or tenants.
+description: Memory profiles (separate namespaces inside one SuperLocalMemory store) and MCP tool sets (which tools your host sees). Use switch_profile or slm profile switch to change the active memory profile, the profile_id argument to read or write another profile for one call, and SLM_MCP_PROFILE to choose a tool set. Required when working across multiple projects, clients, or tenants.
 when_to_use: |
   - "Switch to my work profile"
-  - "Use the code profile for this session"
   - "What profile am I currently in?"
-  - "I need mesh tools — switch to full profile"
-  - "Load the devops workspace"
+  - "Create a profile for this client"
+  - "Read the work profile once without leaving this one"
+  - "I need mesh or code-graph tools" (a tool-set question, not a profile switch)
+  - "Why can't I see tool X?"
   - Multi-project workflows needing memory isolation
   - Switching between personal and team workspaces
-  - Enabling additional MCP tools by activating a richer profile
-allowed-tools: switch_profile, Bash
+allowed-tools: switch_profile, get_status, Bash
 ---
 
-# slm-profile — Workspace Isolation and Profile Switching
+# slm-profile — Memory Profiles and Tool Sets
 
-A profile is a fully isolated memory workspace. Each profile has its own:
-- Memory facts (nothing bleeds across profiles by default)
-- Code graph index (separate per repo/project)
-- Active MCP tool set (determined by profile tier)
-- Retention policy and decay settings
+Two different things are called "profile" in SuperLocalMemory. Keep them apart.
 
-Profiles are the right tool when you have genuinely separate contexts: a personal
-project, a client engagement, a production vs staging environment.
+- A **memory profile** is a namespace inside one store. It has its own memories,
+  knowledge graph, learned patterns, retention settings and audit trail. A fresh
+  install has one, called `default`. This is what `switch_profile`,
+  `slm profile` and the `profile_id` argument are about.
+- An **MCP tool set** (`SLM_MCP_PROFILE`: `core`, `code`, `full`, `power`,
+  `mesh`) decides which tools the server shows your host. `switch_profile` does
+  not change it.
 
----
-
-## Available profiles and their tool sets
-
-| Profile | Tools | When to use |
-|---------|-------|-------------|
-| `core` | 18 tools — remember, recall, search, session, optimize | Minimal footprint, no code tools |
-| `code` | 38 tools — core + portable Brain evidence + code graph + profile switching + bounded loops + memory-kind management | Default for IDE/coding agents |
-| `full` | 56 tools — code + all memory ops + mesh + bounded loops | Multi-session, team workflows |
-| `power` | 68 tools — full + governance + behavioral tools | Enterprise, admin, audit use cases |
-| `mesh` | 8 tools — mesh coordination only | Lightweight cross-session signalling |
-
-The profile is set at MCP server startup via `SLM_MCP_PROFILE` in the MCP config.
-`switch_profile` lets you change it at runtime without a restart.
+A memory profile organises memory. It is not a security boundary: any local
+caller that can name a profile can read it, unless the user has turned on company
+mode with roles. For memories that must be unreachable from another bot or user,
+use a separate data directory (`SLM_DATA_DIR`) or company mode (`slm-governance`).
 
 ---
 
-## Checking the active profile
+## Memory profiles
 
 ```bash
-slm status --json
+slm profile list [--json]
+slm profile create <name> [--json]
+slm profile switch <name> [--json]
+slm status --json          # data.profile is the active profile
 ```
 
-The `profile` field in the output is the currently active profile name.
-
-Or via MCP (works in any profile):
+Creating a profile is a CLI action; there is no MCP tool for it. Over MCP:
 
-```bash
-slm status
+```
+switch_profile(
+  profile_id: str,   # the name of an existing profile
+)
 ```
 
----
+`switch_profile` changes the **active profile**. The change is not private to
+your session: it is written as the machine's active profile, so every later call
+from every session on this machine, and the dashboard, now work in it until
+someone switches again. An unknown name is refused (`Profile '<name>' does not
+exist`); nothing is created. In company mode it also needs a role on the target
+profile. Only switch when the user asks to move; do not switch to peek at
+something.
 
-## Switching profiles at runtime (v3.8.0+)
+### Reaching another profile for one call
 
-`switch_profile` is available in `code`, `full`, and `power` profiles.
+Most tools take an optional `profile_id`: `remember`, `recall`, `search`,
+`fetch`, `list_recent`, `update_memory`, `delete_memory`, `session_init`,
+`close_session`, `report_outcome`, `report_feedback`, `get_status`,
+`get_memory_summary`, the correction and memory-kind tools, and others. A
+non-empty value serves that one call from that profile (which must already
+exist) and **never moves the active profile**. An empty value means the active
+profile. Prefer this to switching and switching back.
 
 ```
-switch_profile(
-  profile: str,   # one of: "core", "code", "full", "power", "mesh"
-)
+recall(query="rollout plan", profile_id="work", session_id="<sid>")
+remember(content="...", tags="ops", profile_id="client-acme")
 ```
 
-### Example: activate full profile to access mesh tools
+`forget` and the mesh tools take no `profile_id`; they act on the active profile.
 
-```
-# You started in code profile but need mesh coordination
-switch_profile(profile="full")
+### What a profile isolates
 
-# Now mesh_peers, mesh_send, mesh_inbox, etc. are available
-mesh_peers()
-```
+- `recall` returns only the profile's own memories, plus shared or global ones
+  only when you opt in (see `slm-scope`).
+- `remember` writes to the profile you name or the active one.
+- The code graph is not partitioned by profile: it lives in `code_graph.db` in the data directory.
+- The `slm_cache_*` key-value cache and `slm_compress` recovery store are keyed
+  by the calling agent, not by profile, so switching profiles does not give you
+  a clean cache (see `slm-cache`).
 
-### Example: switch workspaces
+### Separate stores
 
-```
-# Switch from personal to work workspace
-switch_profile(profile="work-project")
-```
+To keep two bots or two clients completely apart, give each its own
+`SLM_DATA_DIR` in its MCP config. You can run several SLM MCP servers at once,
+named differently (for example `superlocalmemory-personal` and
+`superlocalmemory-work`), each pointed at its own directory.
 
-Wait — profile names and workspace names are distinct concepts:
-- **Profile tier** (`core`, `code`, `full`, `power`, `mesh`) controls which MCP
-  tools are registered.
-- **Workspace / data directory** (`SLM_DATA_DIR`) controls which memory database
-  is used.
+---
 
-`switch_profile` changes the **tool tier** within the current workspace. To
-switch to a completely different memory database (workspace), you need to change
-`SLM_DATA_DIR` — this requires restarting the MCP server or using a separately
-configured MCP server instance.
+## MCP tool sets
 
----
+| Profile | Tools | What it is |
+|---------|-------|------------|
+| `core` | 18 tools — remember, recall, search, fetch, list_recent, update_memory, forget, session, optimize, corrections, summaries, switch_profile | Smallest set; the Grok Bot / Cursor plugin uses it |
+| `code` | 38 tools — core + portable Brain evidence, report_outcome/report_feedback, 6 code-graph tools, memory kinds, bounded loops | For coding agents that need the graph; no mesh, no `get_status` |
+| `full` | 56 tools — everyday memory, delete_memory, get_status, observe, saved views, learning tools, skills, optimize, kinds, loops, mesh | Same set as the no-profile default |
+| `power` | 68 tools — full + audit_trail, retention, compaction, consistency_check, behavioral and diagnostic tools | Governance and admin work |
+| `mesh` | 8 tools — mesh coordination only | Lightweight cross-session signalling |
 
-## Configuring the initial profile
+A host that sets no profile gets the 56-tool `full` set (this is what the Claude
+Code and Codex plugins do; the Antigravity plugin sets `power`). Two more
+environment variables widen or narrow it: `SLM_MCP_ALL_TOOLS=1` registers every
+tool (103), and `SLM_MCP_TOOLS=remember,recall,...` registers exactly the names
+listed. `SLM_MCP_PROFILE=whole` is also every tool. The code-graph tools beyond
+the six in `code` (such as `update_code_graph`, `list_graph_stats`) and tools
+such as `core_memory` and `settle_session_outcomes` exist only with
+`SLM_MCP_ALL_TOOLS=1`, `whole` or an explicit `SLM_MCP_TOOLS` list. Tools whose
+function is to manage the SLM computer are never available to a remote caller.
 
-Set it where your host defines the MCP server's environment — `.mcp.json` (Claude
-Code), `.codex/config.toml` (Codex), or `mcp.cursor.json` (Cursor / Grok Bot):
+The tool set is read when the MCP server starts. To change it, set it in the
+host's MCP config and restart the host; asking the server at runtime does not
+work:
 
 ```json
 "env": {
   "SLM_MCP_PROFILE": "code",
-  "SLM_AGENT_ID": "claude_code",
-  "SLM_DATA_DIR": "~/.superlocalmemory"
+  "SLM_AGENT_ID": "claude_code"
 }
 ```
 
-Profile aliases from older versions still resolve: `code20` → `code`,
-`full38` → `full`, `power50` → `power`. Stale configs get a startup warning
-but continue to work.
-
----
-
-## Profile isolation guarantees
+`slm connect <ide> --profile <name>` writes that variable into a supported
+host's config. Setting `SLM_MCP_PROFILE` to a name that does not exist stops
+`slm mcp` with a message listing the valid names. Older count-suffixed names
+such as `code20`, `full38` and `power50` still resolve, with a startup warning.
+On an install that already has memories, do not set `SLM_DATA_DIR` in the MCP
+config: it points the host at a different, empty store.
 
-- `recall` returns only memories in the active profile (plus opt-in shared/global
-  facts — see `slm-scope`).
-- `remember` writes to the active profile only unless `scope="shared"/"global"`.
-- Code graph tools (`build_code_graph`, `get_blast_radius`, etc.) index into the
-  active profile's graph store.
-- KV cache entries are namespaced per profile — switching profiles gives you a
-  clean cache.
+`switch_profile` is in `core`, `code`, `full` and `power`, and in the default
+set. It is not in `mesh`.
 
 ---
 
-## Multiple concurrent profiles
+## If a tool is missing
 
-You can run multiple SLM MCP server instances simultaneously, each pointed at a
-different `SLM_DATA_DIR`, to serve different workspaces in the same IDE session.
-Name them differently in your MCP config (e.g. `superlocalmemory-personal` and
-`superlocalmemory-work`) and route tool calls to the appropriate server.
+Check the tool set first (`slm status` does not show it; look at the host's MCP
+config for `SLM_MCP_PROFILE`). Mesh tools need `full`, `power`, `mesh` or the
+default. Code-graph tools need `code` or `SLM_MCP_ALL_TOOLS=1`. Audit and
+retention tools need `power`. `report_outcome` and `report_feedback` need
+anything but `core` or `mesh`.
 
 ---
 
 ## Related skills
 
 - `slm-scope` — opt-in fact sharing across profiles (personal/shared/global)
-- `slm-graph` — code-graph tools available in code/full/power profiles
-- `slm-mesh` — mesh tools available in full/power/mesh profiles
-- `slm-status` — check active profile name and tool inventory
-- `slm-governance` — enterprise role-based access to profiles
+- `slm-graph` — code-graph tools and the tool set they need
+- `slm-mesh` — mesh tools and the tool set they need
+- `slm-status` — check the active profile name
+- `slm-governance` — roles and company mode
 
 ---
 
-*SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.24 · Qualixar · AGPL-3.0-or-later*