superlocalmemory 3.7.7 → 3.8.0

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

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

@@ -0,0 +1,148 @@
+---
+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.
+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"
+  - 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
+---
+
+# slm-profile — Workspace Isolation and Profile Switching
+
+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
+
+Profiles are the right tool when you have genuinely separate contexts: a personal
+project, a client engagement, a production vs staging environment.
+
+---
+
+## Available profiles and their tool sets
+
+| Profile | Tools | When to use |
+|---------|-------|-------------|
+| `core` | 14 tools — remember, recall, search, session, optimize | Minimal footprint, no code tools |
+| `code` | 24 tools — core + 6 code-graph tools + switch_profile + 3 bounded-loop tools | Default for IDE/coding agents |
+| `full` | 42 tools — code + all memory ops + mesh + bounded loops | Multi-session, team workflows |
+| `power` | 54 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.
+
+---
+
+## Checking the active profile
+
+```bash
+slm status --json
+```
+
+The `profile` field in the output is the currently active profile name.
+
+Or via MCP (works in any profile):
+
+```bash
+slm status
+```
+
+---
+
+## Switching profiles at runtime (v3.8.0+)
+
+`switch_profile` is available in `code`, `full`, and `power` profiles.
+
+```
+switch_profile(
+  profile: str,   # one of: "core", "code", "full", "power", "mesh"
+)
+```
+
+### Example: activate full profile to access mesh tools
+
+```
+# You started in code profile but need mesh coordination
+switch_profile(profile="full")
+
+# Now mesh_peers, mesh_send, mesh_inbox, etc. are available
+mesh_peers()
+```
+
+### Example: switch workspaces
+
+```
+# Switch from personal to work workspace
+switch_profile(profile="work-project")
+```
+
+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.
+
+---
+
+## Configuring the initial profile
+
+In your `.mcp.json` (Claude Code) or `.codex/config.toml` (Codex):
+
+```json
+"env": {
+  "SLM_MCP_PROFILE": "code",
+  "SLM_DATA_DIR": "~/.superlocalmemory"
+}
+```
+
+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
+
+- `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.
+
+---
+
+## Multiple concurrent profiles
+
+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.
+
+---
+
+## 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
+
+---
+
+*SuperLocalMemory v3.8.0 · Qualixar · AGPL-3.0-or-later*

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

@@ -50,7 +50,7 @@ recall(
   query="authentication strategy decision",
   limit=20,            # default 20; reduce to 5 for quick pre-task checks
   session_id="<sid>",  # pass the session_id returned by session_init
-  fast=False,          # default False; True skips SpreadingActivation channel
+  fast=False,          # default False; True enables faster, reduced-channel retrieval
 )
 ```
 
@@ -101,8 +101,8 @@ correctly, but feedback is not attributed to the session.
 ### 3. Fast mode
 
 Use `fast=True` for pre-tool-call checks where sub-second response matters.
-This skips the SpreadingActivation channel. The remaining channels — semantic,
-lexical, temporal, and structural — still run.
+This enables a faster, reduced-channel mode. Core semantic and keyword channels
+always run; additional graph and contextual channels are skipped.
 
 ```
 recall(query="rate limiting approach", limit=5, session_id="<sid>", fast=True)
@@ -142,12 +142,12 @@ once you have the `fact_id` for full content.
 
 ## How multi-channel retrieval works
 
-`recall` runs five candidate producers in parallel — semantic vector similarity,
-lexical BM25, temporal recency, spreading activation, and Hopfield — then fuses
-them with Reciprocal Rank Fusion (RRF), applies a reranker, and layers an
-optional entity-graph post-fusion score enhancement. The `channel_weights` field in the
-response shows how each channel contributed for that query. Weights adapt over
-time based on engagement signals attributed via `session_id`.
+`recall` runs multiple candidate producers in parallel — semantic vector similarity,
+keyword matching, temporal recency weighting, and contextual graph channels — then
+fuses and reranks the combined results, with an optional entity-graph score
+enhancement. The `channel_weights` field in the response shows how each channel
+contributed for that query. Weights adapt over time based on engagement signals
+attributed via `session_id`.
 
 To inspect per-channel scores for a real query against your own data:
 
@@ -202,4 +202,40 @@ trusts that what you surface came from the store.
 
 ---
 
-*SuperLocalMemory v3.6.18 · Qualixar · AGPL-3.0-or-later*
+## Multi-scope retrieval (v3.6.15+, opt-in)
+
+By default `recall` returns only memories in the active profile (personal scope).
+To also surface memories shared from other profiles, pass the scope flags:
+
+```
+recall(
+  query="...",
+  include_global=True,   # include global-scope memories (visible to all profiles)
+  include_shared=True,   # include shared-scope memories (shared with this profile)
+  session_id="<sid>",
+)
+```
+
+Scope flags are **off by default**. Only enable them when the user explicitly asks
+to see shared or global facts. See `slm-scope` for the full sharing model.
+
+---
+
+## Profile-aware retrieval (v3.8.0+)
+
+`recall` always queries the currently active profile. To query a different
+workspace, use `switch_profile` (requires `code`, `full`, or `power` MCP profile)
+before recalling, then switch back. See `slm-profile` for workspace switching.
+
+---
+
+## Related skills
+
+- `slm-remember` — store the decisions and facts that recall surfaces later
+- `slm-session` — session lifecycle (must call before first recall)
+- `slm-scope` — multi-scope sharing model (personal / shared / global)
+- `slm-profile` — workspace isolation and profile switching
+
+---
+
+*SuperLocalMemory v3.8.0 · Qualixar · AGPL-3.0-or-later*

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

@@ -191,4 +191,51 @@ slm remember "<content>" --scope shared --shared-with alice,bob
 
 ---
 
-*SuperLocalMemory v3.6.18 · Qualixar · AGPL-3.0-or-later*
+## Multi-scope sharing (v3.6.15+, opt-in)
+
+Every `remember` call defaults to `personal` scope — private to the active profile.
+To share a fact with other profiles on the same machine, set the `scope` parameter:
+
+```
+# Share with every profile on this machine
+remember(
+  content="API rate limit is 100 req/min per tenant",
+  tags="api,limits,shared",
+  project="platform",
+  scope="global",      # visible to all profiles
+  session_id="<sid>",
+)
+
+# Share with specific profiles only
+remember(
+  content="Staging DB migration runs Fridays 22:00 UTC",
+  tags="db,ops",
+  scope="shared",
+  shared_with="work-profile,devops-profile",
+  session_id="<sid>",
+)
+```
+
+**Only set scope when the user explicitly asks to share.** The default
+`personal` scope is identical to single-profile SLM. See `slm-scope` for the
+complete sharing model and when to use each scope.
+
+---
+
+## Profile-aware storage (v3.8.0+)
+
+`remember` always stores in the active profile's namespace. To write to a
+different workspace, use `switch_profile` first. See `slm-profile`.
+
+---
+
+## Related skills
+
+- `slm-recall` — retrieve what was remembered
+- `slm-session` — session lifecycle; session_id is required for attribution
+- `slm-scope` — complete guide to personal / shared / global scopes
+- `slm-profile` — workspace isolation and profile switching
+
+---
+
+*SuperLocalMemory v3.8.0 · Qualixar · AGPL-3.0-or-later*