superlocalmemory 3.8.13 → 4.0.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 v4.0.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 v4.0.0 · Qualixar · AGPL-3.0-or-later*

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

@@ -236,4 +236,4 @@ before recalling, then switch back. See `slm-profile` for workspace switching.
 
 ---
 
-*SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later*

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

@@ -238,4 +238,4 @@ different workspace, use `switch_profile` first. See `slm-profile`.
 
 ---
 
-*SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later*

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

@@ -0,0 +1,176 @@
+---
+name: slm-scope
+description: Controls memory visibility across profiles — personal (private, default), shared (selected profiles), or global (all profiles on this machine). Default is always personal. Only change scope when the user explicitly asks to share a memory across workspaces. Works with both remember (write scope) and recall (read scope flags).
+when_to_use: |
+  - "Share this memory with the team profile"
+  - "Store this globally so all my agents can see it"
+  - "Recall anything shared from the work profile"
+  - "Can other agents on this machine see my memories?"
+  - User explicitly asks to cross-profile share a fact or see shared facts
+  - Enterprise setup where multiple profiles collaborate
+allowed-tools: remember, recall, search, list_recent, Bash
+---
+
+# slm-scope — Memory Scope and Sharing Model
+
+SuperLocalMemory is profile-isolated by default. Every profile is a fully
+independent memory namespace. The scope model adds controlled, opt-in sharing
+between profiles on the same machine — it is never active unless you explicitly
+set it.
+
+---
+
+## The Three Scopes
+
+| Scope | Visibility | When to use |
+|-------|-----------|-------------|
+| `personal` | Active profile only | Default — all facts. Never set explicitly. |
+| `shared` | Active profile + `shared_with` profiles | Team handoffs, shared project context |
+| `global` | Every profile on this machine | Machine-wide conventions, org-wide rules |
+
+**The default is always `personal`.** A fact stored without a `scope` argument
+is private to the profile that stored it. Recall without scope flags returns only
+personal facts. This is identical to single-profile SLM.
+
+---
+
+## Opt-in is mandatory
+
+Never set `scope="shared"` or `scope="global"` (or the recall equivalents
+`include_shared`, `include_global`) unless the user explicitly asks you to share
+or read across profiles. This is a hard rule — scope expansion is an action with
+team-wide or machine-wide impact, and it must always be user-initiated.
+
+---
+
+## Writing a shared or global fact
+
+### share with specific profiles
+
+```
+remember(
+  content="API gateway rate limit is 1000 req/min per client",
+  tags="api,limits,ops",
+  project="platform",
+  importance=8,
+  session_id="<sid>",
+  scope="shared",
+  shared_with="devops-profile,backend-profile",
+)
+```
+
+`shared_with` is a comma-separated list of profile IDs that should be able to
+recall this fact. Use `slm status` to see the current profile name — that is the
+`profile_id` to supply.
+
+### share with all profiles on the machine
+
+```
+remember(
+  content="All services must enforce TLS 1.3 minimum",
+  tags="security,tls,global",
+  project="infra",
+  importance=9,
+  session_id="<sid>",
+  scope="global",
+)
+```
+
+`scope="global"` makes the fact visible to every profile on this machine. Use
+this only for machine-wide conventions (security rules, org-wide constraints).
+
+---
+
+## Reading shared or global facts
+
+By default, `recall` returns only the active profile's personal facts. To surface
+shared and global facts, pass the opt-in flags:
+
+```
+recall(
+  query="rate limiting rules",
+  limit=20,
+  include_global=True,   # include global-scope facts
+  include_shared=True,   # include facts shared with this profile
+  session_id="<sid>",
+)
+```
+
+You can opt in to either or both flags independently. Only the active profile's
+permitted shared facts are returned — you cannot read another profile's personal
+facts.
+
+### CLI equivalents
+
+```bash
+# Recall with global facts included
+slm recall "rate limiting rules" --include-global
+
+# Recall with shared facts included
+slm recall "rate limiting rules" --include-shared
+
+# Both
+slm recall "rate limiting rules" --include-global --include-shared
+
+# Store a global fact
+slm remember "TLS 1.3 minimum" --scope global
+
+# Store a shared fact (shared-with is a comma-separated list of profile IDs)
+slm remember "API rate limit 1000/min" --scope shared --shared-with devops,backend
+```
+
+CLI flags verified in source: `--include-global` / `--no-global`, `--include-shared` / `--no-shared`,
+`--scope personal|shared|global`, `--shared-with <profile-ids>`.
+
+---
+
+## Configuring scope defaults
+
+Per-profile defaults live in `mode_a/b/c.json` configuration. To make a profile
+always include global facts without passing flags each time:
+
+```json
+{
+  "recall": {
+    "include_global": true,
+    "include_shared": false
+  }
+}
+```
+
+Changing the default requires editing the profile config directly — this is an
+admin-level operation.
+
+---
+
+## Enterprise governance
+
+In a governed workspace (admin/member/viewer roles), scope expansion may be
+restricted:
+- **Viewers** cannot write `scope="global"` facts — their writes are always `personal`.
+- **Members** can write `scope="shared"` with profiles in their access list.
+- **Admins** can write `scope="global"` unrestricted.
+
+See `slm-governance` for the full enterprise behavior model.
+
+---
+
+## Scope deletion and retention
+
+A `scope="global"` fact deleted by one profile is deleted for all profiles. A
+`scope="shared"` fact is deleted from all profiles that had access to it.
+Use `slm forget "<query>" --dry-run` before any deletion involving shared facts
+to review the impact. See `slm-remember` for the full deletion discipline.
+
+---
+
+## Related skills
+
+- `slm-remember` — full fact storage reference including scope parameters
+- `slm-recall` — full retrieval reference including include_global/include_shared
+- `slm-profile` — what a profile is and how to switch between them
+- `slm-governance` — enterprise role restrictions on scope
+
+---
+
+*SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later*

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

@@ -227,4 +227,4 @@ explicitly and call `recall` with `include_global`/`include_shared` after
 
 ---
 
-*SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later*

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

@@ -163,4 +163,4 @@ multi-profile setup. To switch the active profile, see `slm-profile`.
 
 ---
 
-SuperLocalMemory v3.8.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.0.0 · Qualixar · AGPL-3.0-or-later

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "3.8.13"
+version = "4.0.0"
 description = "Local-first agent memory with auditable hybrid retrieval"
 readme = "README.md"
 license = "AGPL-3.0-or-later"
@@ -16,7 +16,6 @@ keywords = [
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
-    "Operating System :: OS Independent",
     "Operating System :: MacOS",
     "Operating System :: Microsoft :: Windows",
     "Operating System :: POSIX :: Linux",
@@ -37,7 +36,7 @@ dependencies = [
     "numpy==2.4.4",
     "scipy==1.17.1",
     "networkx==3.6.1",
-    "mcp==1.28.1",
+    "mcp==2.0.0",
     "python-dateutil==2.9.0.post0",
     "rank-bm25==0.2.2",
     "vadersentiment==3.3.2",
@@ -63,7 +62,7 @@ dependencies = [
     # Keep this direct: portalocker also needs pywin32 today, but capture must
     # not depend on that transitive implementation detail.
     "pywin32==311; sys_platform == 'win32'",
-    "cryptography==48.0.1",
+    "cryptography==50.0.0",
     # Semantic search + cross-encoder reranker. Do NOT use
     # sentence-transformers[onnx] — its extras pull optimum which
     # overrides the sentence-transformers pin via transitive deps.
@@ -91,6 +90,9 @@ dependencies = [
     # the ~560MB model downloads on first setup/warmup (fail-open). Verified the
     # pin does NOT disturb the transformers/torch/numpy pins above.
     "llmlingua==0.2.2",
+    # LLMLingua pulls NLTK transitively. Pin the patched release so clean
+    # installs cannot resolve to the vulnerable 3.9.x line.
+    "nltk==3.10.0",
 ]
 
 [project.optional-dependencies]
@@ -173,9 +175,14 @@ superlocalmemory = ["ui/**/*", "optimize/NOTICE"]
 [tool.setuptools.data-files]
 "share/superlocalmemory/codex/skills/slm-cache" = ["plugin-src/skills/slm-cache/SKILL.md"]
 "share/superlocalmemory/codex/skills/slm-compress" = ["plugin-src/skills/slm-compress/SKILL.md"]
+"share/superlocalmemory/codex/skills/slm-governance" = ["plugin-src/skills/slm-governance/SKILL.md"]
 "share/superlocalmemory/codex/skills/slm-graph" = ["plugin-src/skills/slm-graph/SKILL.md"]
+"share/superlocalmemory/codex/skills/slm-loop" = ["plugin-src/skills/slm-loop/SKILL.md"]
+"share/superlocalmemory/codex/skills/slm-mesh" = ["plugin-src/skills/slm-mesh/SKILL.md"]
+"share/superlocalmemory/codex/skills/slm-profile" = ["plugin-src/skills/slm-profile/SKILL.md"]
 "share/superlocalmemory/codex/skills/slm-recall" = ["plugin-src/skills/slm-recall/SKILL.md"]
 "share/superlocalmemory/codex/skills/slm-remember" = ["plugin-src/skills/slm-remember/SKILL.md"]
+"share/superlocalmemory/codex/skills/slm-scope" = ["plugin-src/skills/slm-scope/SKILL.md"]
 "share/superlocalmemory/codex/skills/slm-session" = ["plugin-src/skills/slm-session/SKILL.md"]
 "share/superlocalmemory/codex/skills/slm-status" = ["plugin-src/skills/slm-status/SKILL.md"]
 "share/superlocalmemory/portable-kit/rules" = ["plugin-src/rules/AGENTS.md"]