superlocalmemory 4.1.22 → 4.1.23

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

@@ -0,0 +1,287 @@
+---
+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. 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"
+  - "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.
+
+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 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`.
+
+---
+
+## 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:~/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` (active peers, with
+`remote_peer_count`, `local_session_count` and stale counts alongside),
+`uptime_s`, `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 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 |
+
+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` — 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.23 · Qualixar · AGPL-3.0-or-later*

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

@@ -0,0 +1,159 @@
+---
+name: slm-profile
+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"
+  - "What profile am I currently in?"
+  - "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
+allowed-tools: switch_profile, get_status, Bash
+---
+
+# slm-profile — Memory Profiles and Tool Sets
+
+Two different things are called "profile" in SuperLocalMemory. Keep them apart.
+
+- 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.
+
+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`).
+
+---
+
+## Memory profiles
+
+```bash
+slm profile list [--json]
+slm profile create <name> [--json]
+slm profile switch <name> [--json]
+slm status --json          # data.profile is the active profile
+```
+
+Creating a profile is a CLI action; there is no MCP tool for it. Over MCP:
+
+```
+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.
+
+### Reaching another profile for one call
+
+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.
+
+```
+recall(query="rollout plan", profile_id="work", session_id="<sid>")
+remember(content="...", tags="ops", profile_id="client-acme")
+```
+
+`forget` and the mesh tools take no `profile_id`; they act on the active profile.
+
+### What a profile isolates
+
+- `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`).
+
+### Separate stores
+
+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.
+
+---
+
+## 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 |
+
+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.
+
+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": "codex"
+}
+```
+
+`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.
+
+`switch_profile` is in `core`, `code`, `full` and `power`, and in the default
+set. It is not in `mesh`.
+
+---
+
+## If a tool is missing
+
+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 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.23 · Qualixar · AGPL-3.0-or-later*