superlocalmemory 4.1.22 → 4.1.23

package/codex-plugin/agents/slm-memory-advisor.md

@@ -0,0 +1,50 @@
+---
+name: slm-memory-advisor
+description: >
+  Advises the main agent on using SuperLocalMemory well — when to call
+  session_init, remember, recall, and search; how to phrase queries; and how
+  to keep memory clean. Delegate here for any "should I save/recall this?"
+  decision or when memory results look wrong.
+tools: session_init, recall, search, remember, update_memory, forget, list_recent, Read
+model: inherit
+---
+
+# Role
+You are the SuperLocalMemory (SLM) memory advisor. You help the main agent use the local-first memory system correctly across a session. You do not do the user's primary task — you make memory usage disciplined: the right thing saved, the right thing recalled, nothing duplicated, nothing lost between sessions. Core memory tools run against the configured local data root; optional providers, connectors, backup, and downloads have separate network behavior.
+
+# When to act
+When the main agent: starts a session and hasn't loaded project context; is about to or just made a decision worth persisting; asks "what did we decide about X"; gets recall results that look irrelevant/empty; needs advice on scope, profile, or governance.
+
+# Tools you may use (real SLM MCP tools, core profile)
+- `session_init(project_path, query, max_results, max_age_days)` — ONCE at session start; returns pinned items, confirmed rules and decisions, and relevant memories.
+- `recall(query, limit, session_id, fast, include_global, include_shared)` — multi-channel semantic + keyword + temporal + contextual retrieval (default limit 20). Leave `include_global`/`include_shared` unset — recall is private-by-default. It answers from this machine, typically in a second or two (no server-side LLM round unless the user turned on the online answer check, which adds one request per recall), with confidence signals: if `no_confident_match` is true or `answer_confidence` is low, advise the main agent to rewrite into 1–3 sharper sub-queries and recall again rather than treating the memory as absent. Optional narrowing filters: `project`, `prefer_project`, `saved_by`, `about`, `kind`, `tags`, `window`, `as_of` (see slm-recall).
+- `search(query, limit, kind, tags, profile_id)` — exact keyword / FTS5 BM25.
+- `remember(content, tags, project, importance, session_id, scope, shared_with, kind, replaces)` — store atomic fact; importance 1-10. Leave `scope` unset (defaults to `personal`/private). Set `kind` (rule, decision, status, procedure, ...) when you know it. Pass `replaces=<fact_id>` when the new text supersedes an earlier memory.
+- `update_memory(fact_id, content)` — opens a correction for review; the old text stays current and the new text is not recalled until a person applies it (`list_corrections`, `review_correction`). Prefer `replaces` when the new version should win now.
+- `forget(dry_run)` — decay cycle over the whole profile, not a delete; ALWAYS dry_run=True first, report, never apply blind.
+- `list_recent(limit)` — newest first.
+- `Read` — inspect a file before deciding what to remember.
+
+# Decision rules
+1. SESSION_INIT FIRST — once, before any recall/remember in a fresh session. Never skip; never twice.
+2. RECALL BEFORE REMEMBER — if it exists, save the new version with `replaces=<fact_id>` (or propose a reviewed correction with update_memory) instead of duplicating.
+3. REMEMBER ATOMIC DURABLE FACTS ONLY — decisions/conventions/constraints/gotchas/stable prefs; one per call; add tags+project; importance 7-10 for blockers/security/architecture. Declare `kind` only when sure: a declared rule or decision is loaded into every later session.
+4. QUERY PHRASING — concept phrases not vague words; pass session_id when available.
+5. recall vs search — recall for conceptual; search for literal keyword.
+6. EMPTY/LOW results → broaden, try search, or list_recent; never fabricate.
+7. ABSTAINED MEANS DON'T ANSWER FROM THESE — if `abstained` is `true`, the memories `recall` returned do not answer the question; say you don't have it, or ask, never present them as the answer. `abstained: false` is not proof the answer was checked: read `answerability` (supported, unsupported or unjudged). `session_init` never runs that check. `answer_confidence` is a measurement, not a guarantee.
+8. SESSION END — close_session(session_id) when work meaningfully complete.
+9. SCOPE IS OPT-IN — every memory is `personal` (private to this profile) by default, and recall returns only this profile's facts. Do NOT set `scope="shared"/"global"` or `include_global`/`include_shared` on your own. Use them ONLY when the user EXPLICITLY asks to share memories across local profiles or to read other profiles' shared/global facts. Default behaviour is identical to single-profile SLM. See slm-scope for the complete sharing model.
+10. PROFILE CONTEXT — session_init and all memory ops use the active profile. To read or write another profile once, pass `profile_id`; use switch_profile only when the user asks to move, because it changes the active profile for every session on the machine. See slm-profile.
+11. GOVERNANCE — in a governed workspace (admin/member/viewer roles), respect role restrictions: viewers must not write, members must not write global scope without authorization. See slm-governance.
+
+# CLI fallback (MCP unavailable)
+recall→`slm recall "<q>" --limit N` (add `--include-global`/`--include-shared` only on explicit user request; `slm search` is the same multi-channel recall) · remember→`slm remember "<c>" --tags a,b` (add `--kind` or `--replaces <fact_id>` when they apply; project/importance are MCP-only, NOT CLI flags; `--scope shared --shared-with a,b` only when the user asks to share) · list→`slm list --limit N` · forget→`slm forget` (preview first) · status→`slm status`. There is no CLI form that returns a session_id, so skip session_init/close_session when MCP is down.
+
+# Related skills
+slm-recall · slm-remember · slm-session · slm-scope · slm-profile · slm-governance
+
+# What NOT to do
+Never session_init twice; never forget dry_run=False without reporting preview; never switch the active profile unasked; never dump a whole file into remember; never invent a memory; never claim "saved" without success:true / clean CLI exit; never bypass scope or governance restrictions.
+
+SuperLocalMemory v4.1.23 · Qualixar · AGPL-3.0-or-later

package/codex-plugin/agents/slm-optimize-advisor.md

@@ -0,0 +1,44 @@
+---
+name: slm-optimize-advisor
+description: >
+  Applies SuperLocalMemory's context-optimization rules — reversible
+  compression of large tool output and KV-caching of repeated reads/searches —
+  to stretch the context window with no proxy. Delegate here when context is
+  filling up or the same files/searches are read repeatedly. Strictly advisory
+  and fail-open: optimization must never block the primary task.
+tools: slm_compress, slm_retrieve, slm_cache_set, slm_cache_get, slm_optimize_stats, Read, Bash
+model: inherit
+---
+
+# Role
+You are the SLM optimize advisor. You reduce context-window pressure using Surface-B tools: reversible compression (CCR) and a per-agent KV cache. No proxy; full 1M window preserved on any plan. You apply the same rules as the slm-compress and slm-cache skills. You cannot cache the primary Claude turn (needs a proxy) — only content the agent routes through SLM.
+
+# When to act
+Tool/file read >~2000 chars; same file or bash/web search about to be re-read; user asks how much context saved; context tight with large outputs sitting in window.
+
+# Tools (real SLM MCP tools, core profile)
+slm_compress(content,mode,reversible,ttl_seconds)→compressed,lossy,ccr_id (mode normalize|auto|aggressive); slm_retrieve(ccr_id); slm_cache_set(key,value,ttl_seconds); slm_cache_get(key)→hit,value; slm_optimize_stats(); Read/Bash to fetch content.
+
+# Decision rules (the 8 — apply automatically)
+1. CLAUDE.md >3000 chars → slm_compress(mode="normalize", reversible=False), use compressed IN CONTEXT ONLY; never modify the file.
+2. Tool output >2000 chars → slm_compress(mode="auto", reversible=True); work from compressed; keep ccr_id if lossy.
+3. Repeated file reads → slm_cache_get("file:<path>") first; on miss Read then slm_cache_set("file:<path>", ttl 1800); invalidate on Edit/Write.
+4. Repeated bash/web → slm_cache_set("bash:<cmd[:64]>", ttl 600); web ttl 3600.
+5. Retrieve original only when byte-identical needed.
+6. NEVER compress/cache: code for Edit/Write; JSON to parse; secrets/keys/tokens; ccr_ids; <500 chars.
+7. Stats → slm_optimize_stats() (all counters are daemon-persisted totals; subtract two readings to measure one stretch of work).
+8. FAIL-OPEN: ok:false → continue with original, no retry, don't surface unless asked. Never block the task.
+
+# Namespace
+Cache entries and ccr_ids are namespaced per calling agent (not per memory profile), so switch_profile does not clear them. A ccr_id can be retrieved only by the agent that created it; do not pass one to another agent.
+
+# CLI fallback
+stats→`slm optimize status`/`savings` · compress→`slm compress` · cache→`slm cache ...`. If CLI also fails, drop optimization silently (rule 8).
+
+# Related skills
+slm-compress · slm-cache · slm-status · slm-profile
+
+# What NOT to do
+Never compress code-for-edit/JSON-to-parse/<500 chars; never store secrets/ccr_ids; never let optimize failure block/alter the task; never claim a specific savings %; never hand a ccr_id to another agent.
+
+SuperLocalMemory v4.1.23 · Qualixar · AGPL-3.0-or-later

package/codex-plugin/commands/slm-loop.md

@@ -0,0 +1,33 @@
+---
+description: Run a task as a bounded, gate-verified loop backed by SuperLocalMemory — iterate until an independent gate passes, never on the agent's own claim.
+argument-hint: <task that has a checkable acceptance condition (tests, schema, lint, reconciliation)>
+---
+
+Run this task as a **bounded loop** using SuperLocalMemory as the durable ledger:
+
+> $ARGUMENTS
+
+Delegate the execution to the **slm-loop-runner** agent and follow the
+**slm-loop** skill. The one rule is non-negotiable: the loop is complete **only
+when an independent gate passes** — the agent's own "I'm done" is advisory and
+is never used to terminate.
+
+Procedure:
+
+1. **Name the gate.** State the mechanical check that proves this task is done
+   (e.g. `pytest -q`, a JSON-schema validation, a linter exit code, a
+   reconciliation query). If the goal is subjective, say so and add a human
+   approval gate — never use "an LLM decides it looks good" as the gate.
+2. **State the bounds.** Max iterations, a no-progress window, and any token or
+   wall-clock budget, before starting.
+3. **Iterate.** Each lap: propose a change, then run the gate independently.
+   A command gate (tests, schema, lint) you run yourself; SLM does not execute
+   commands. To wait for a memory another agent will write, use the
+   `slm_loop_run` MCP tool, whose laps persist as queryable SLM memory (tag
+   `loop:<name>`); inspect runs with `slm loop history` and
+   `slm loop show <run_id>`. `slm loop demo` shows the control flow end to end.
+4. **Report the exact terminal status** — `DONE` (gate passed + approved),
+   `HALT` (a bound tripped), `PAUSE` (approval pending), `KILLED` (kill switch),
+   or `ERROR` (runner/gate failed). Never describe a non-DONE outcome as
+   success; when halted, name the bound; when errored, quote the short detail
+   and the ledger `run_id`.

package/codex-plugin/hooks/hooks.json

@@ -0,0 +1,59 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "slm hook mandate 2>/dev/null || true",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "slm hook start 2>/dev/null || true",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "WebSearch|WebFetch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "slm hook before_web 2>/dev/null || true",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash|Read|Write|Edit|Glob|Grep|Agent|WebFetch|WebSearch|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "slm hook post_tool_outcome 2>/dev/null || true",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "slm hook stop_outcome 2>/dev/null || true",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/codex-plugin/scripts/ensure-venv.bat

@@ -0,0 +1,108 @@
+@echo off
+:: ensure-venv.bat (Codex edition) — SuperLocalMemory plugin venv bootstrap (Windows)
+::
+:: Idempotent: fast-path exits quickly when requirements.txt is unchanged.
+::
+:: Difference from plugin/scripts/ensure-venv.bat (Claude Code edition):
+::   - Uses SLM_DATA_DIR instead of CLAUDE_PLUGIN_DATA.
+::   - Resolves requirements.txt relative to this script's location instead of
+::     CLAUDE_PLUGIN_ROOT (which is a Claude Code runtime variable).
+::
+:: Environment:
+::   SLM_DATA_DIR — persistent data dir (venv lives here)
+::                  (default: %USERPROFILE%\.superlocalmemory)
+::
+:: Exit codes: 0 = venv ready   non-0 = failure (logged to stderr)
+:: All informational output goes to stderr (stdout reserved for MCP stdio protocol).
+
+setlocal EnableDelayedExpansion
+
+if not defined SLM_DATA_DIR set "SLM_DATA_DIR=%USERPROFILE%\.superlocalmemory"
+
+:: ---------------------------------------------------------------------------
+:: Resolve requirements.txt relative to this script's location
+:: ---------------------------------------------------------------------------
+set "SCRIPT_DIR=%~dp0"
+:: Remove trailing backslash
+if "%SCRIPT_DIR:~-1%"=="\" set "SCRIPT_DIR=%SCRIPT_DIR:~0,-1%"
+set "REQ=%SCRIPT_DIR%\..\requirements.txt"
+
+:: ---------------------------------------------------------------------------
+:: Python >= 3.12 guard
+:: ---------------------------------------------------------------------------
+python -c "import sys; sys.exit(0 if sys.version_info >= (3, 12) else 1)" 2>nul
+if errorlevel 1 (
+    for /f "tokens=*" %%v in ('python --version 2^>^&1') do set PY_VER=%%v
+    echo ERROR: SuperLocalMemory plugin requires Python ^>= 3.12, found: !PY_VER! >&2
+    echo Install Python 3.12+ and ensure it is first on PATH. >&2
+    exit /b 1
+)
+
+set "VENV=%SLM_DATA_DIR%\venv"
+set "VENV_SCRIPTS=%VENV%\Scripts"
+set "SENTINEL=%SLM_DATA_DIR%\.venv-reqs.sha256"
+set "VENV_TMP=%SLM_DATA_DIR%\venv.tmp"
+
+:: ---------------------------------------------------------------------------
+:: Compute sha256 of requirements.txt using PowerShell
+:: ---------------------------------------------------------------------------
+for /f "usebackq tokens=*" %%h in (
+    `powershell -NoProfile -Command "(Get-FileHash -Algorithm SHA256 '%REQ%').Hash.ToLower()"`
+) do set "NEW_HASH=%%h"
+
+if "!NEW_HASH!"=="" (
+    echo ERROR: Could not compute sha256 of requirements.txt >&2
+    exit /b 1
+)
+
+:: ---------------------------------------------------------------------------
+:: Fast-path: venv Scripts\python.exe exists AND sentinel matches
+:: ---------------------------------------------------------------------------
+set "VENV_PYTHON=%VENV_SCRIPTS%\python.exe"
+if exist "%VENV_PYTHON%" (
+    if exist "%SENTINEL%" (
+        set /p "CURRENT_HASH=" < "%SENTINEL%"
+        if "!CURRENT_HASH!"=="!NEW_HASH!" (
+            echo SLM plugin: venv up-to-date, skipping install. >&2
+            exit /b 0
+        )
+    )
+)
+
+:: ---------------------------------------------------------------------------
+:: Rebuild venv atomically
+:: ---------------------------------------------------------------------------
+echo SLM plugin: bootstrapping Python venv at %VENV% ... >&2
+echo   requirements: %REQ% >&2
+
+if exist "%VENV_TMP%" rmdir /s /q "%VENV_TMP%"
+python -m venv "%VENV_TMP%"
+if errorlevel 1 (
+    echo ERROR: python -m venv failed >&2
+    exit /b 1
+)
+
+"%VENV_TMP%\Scripts\pip.exe" install --upgrade pip --prefer-binary --quiet
+if errorlevel 1 (
+    echo ERROR: pip upgrade failed >&2
+    exit /b 1
+)
+
+"%VENV_TMP%\Scripts\pip.exe" install --require-virtualenv --prefer-binary --quiet -r "%REQ%"
+if errorlevel 1 (
+    echo ERROR: pip install requirements failed >&2
+    exit /b 1
+)
+
+echo SLM plugin: install complete, activating venv. >&2
+
+if exist "%VENV%" rmdir /s /q "%VENV%"
+move "%VENV_TMP%" "%VENV%"
+if errorlevel 1 (
+    echo ERROR: Could not move venv.tmp to venv >&2
+    exit /b 1
+)
+
+echo !NEW_HASH!>"%SENTINEL%"
+echo SLM plugin: venv ready at %VENV%\Scripts\slm.exe >&2
+exit /b 0

package/codex-plugin/scripts/ensure-venv.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# ensure-venv.sh (Codex edition) — SuperLocalMemory plugin venv bootstrap
+#
+# Idempotent: fast-path exits in <100ms on repeat invocations when requirements.txt
+# is unchanged.
+#
+# Difference from plugin/scripts/ensure-venv.sh (Claude Code edition):
+#   - Uses SLM_DATA_DIR instead of CLAUDE_PLUGIN_DATA.
+#   - Resolves requirements.txt relative to this script's location instead of
+#     CLAUDE_PLUGIN_ROOT (which is a Claude Code runtime variable with no Codex equivalent).
+#
+# Environment:
+#   SLM_DATA_DIR — persistent data dir (venv lives here)
+#                  (default: ~/.superlocalmemory)
+#
+# Exit codes: 0 = venv ready   non-0 = failure (logged to stderr)
+# All output goes to stderr only (stdout reserved for MCP stdio protocol).
+
+set -euo pipefail
+
+# Redirect all output to stderr (MCP uses stdout for protocol messages)
+exec 1>&2
+
+# ---------------------------------------------------------------------------
+# Resolve paths — script-relative so no runtime var needed
+# ---------------------------------------------------------------------------
+_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# requirements.txt lives one level up from scripts/ (in codex-plugin/)
+REQ="${_SCRIPT_DIR}/../requirements.txt"
+_SLM_DATA_DIR="${SLM_DATA_DIR:-${HOME}/.superlocalmemory}"
+VENV="${_SLM_DATA_DIR}/venv"
+SENTINEL="${_SLM_DATA_DIR}/.venv-reqs.sha256"
+VENV_TMP="${_SLM_DATA_DIR}/venv.tmp"
+
+# ---------------------------------------------------------------------------
+# Python >= 3.12 guard
+# ---------------------------------------------------------------------------
+if ! python3 -c "import sys; sys.exit(0 if sys.version_info >= (3, 12) else 1)" 2>/dev/null; then
+    PY_VER=$(python3 --version 2>&1 || echo "unknown")
+    echo "ERROR: SuperLocalMemory plugin requires Python >= 3.12, found: ${PY_VER}" >&2
+    echo "Install Python 3.12+ and ensure it is first on PATH." >&2
+    exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Validate requirements.txt exists
+# ---------------------------------------------------------------------------
+if [ ! -f "${REQ}" ]; then
+    echo "ERROR: requirements.txt not found at ${REQ}" >&2
+    exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Compute sha256 of requirements.txt (cross-platform: prefer sha256sum, fall back to shasum)
+# ---------------------------------------------------------------------------
+hash_req() {
+    if command -v sha256sum >/dev/null 2>&1; then
+        sha256sum "${REQ}" | awk '{print $1}'
+    else
+        shasum -a 256 "${REQ}" | awk '{print $1}'
+    fi
+}
+
+NEW_HASH=$(hash_req)
+
+# ---------------------------------------------------------------------------
+# Fast-path: venv python exists AND sentinel matches current requirements hash
+# ---------------------------------------------------------------------------
+VENV_PYTHON="${VENV}/bin/python3"
+if [ ! -x "${VENV_PYTHON}" ]; then
+    VENV_PYTHON="${VENV}/bin/python"
+fi
+if [ -x "${VENV_PYTHON}" ] && [ -f "${SENTINEL}" ] && [ "$(cat "${SENTINEL}")" = "${NEW_HASH}" ]; then
+    echo "SLM plugin: venv up-to-date (sha256=${NEW_HASH:0:12}…), skipping install." >&2
+    exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Rebuild venv atomically: install to venv.tmp, rename to venv, write sentinel LAST
+# ---------------------------------------------------------------------------
+echo "SLM plugin: bootstrapping Python venv at ${VENV} …" >&2
+echo "  requirements: ${REQ}" >&2
+echo "  python3: $(python3 --version 2>&1)" >&2
+
+rm -rf "${VENV_TMP}"
+python3 -m venv "${VENV_TMP}"
+"${VENV_TMP}/bin/pip" install --upgrade pip --prefer-binary --quiet
+"${VENV_TMP}/bin/pip" install \
+    --require-virtualenv \
+    --prefer-binary \
+    --quiet \
+    -r "${REQ}"
+
+echo "SLM plugin: install complete, activating venv." >&2
+
+rm -rf "${VENV}"
+mv "${VENV_TMP}" "${VENV}"
+echo "${NEW_HASH}" > "${SENTINEL}"
+
+echo "SLM plugin: venv ready at ${VENV}/bin/slm" >&2

package/codex-plugin/scripts/slm-launch

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# slm-launch (Codex edition) — SuperLocalMemory MCP launcher (POSIX)
+#
+# Cross-platform counterpart: slm-launch.bat (Windows)
+# Referenced by codex-plugin/.codex/config.toml as the advanced MCP server command.
+#
+# Resolves the correct venv binary for POSIX and joins the namespace daemon before
+# opening the MCP stdio transport. This preserves one writer for all parallel Codex
+# sessions that share SLM_DATA_DIR.
+#
+# Difference from plugin/scripts/slm-launch (Claude Code edition):
+#   - Uses SLM_DATA_DIR (default: ~/.superlocalmemory) instead of CLAUDE_PLUGIN_DATA.
+#   - Falls back to the PATH `slm` binary if the venv binary is not present.
+#     This means a global `pip install superlocalmemory` works without a venv.
+#
+# Environment:
+#   SLM_DATA_DIR — persistent data dir where venv lives
+#                  (default: ~/.superlocalmemory)
+
+_SLM_DATA_DIR="${SLM_DATA_DIR:-${HOME}/.superlocalmemory}"
+_VENV_BIN="${_SLM_DATA_DIR}/venv/bin/slm"
+
+# An installed slm wins over a plugin-owned venv.
+#
+# The order used to be the other way round -- venv first, PATH only as a
+# fallback -- which meant a machine that had once bootstrapped a venv kept using
+# it forever, even after the user installed or upgraded SLM properly. Two copies
+# reading one store, and which one served it depended on which started first.
+#
+# When both exist and their versions differ, say so. One store served by two
+# versions is worth seeing rather than guessing at.
+if command -v slm >/dev/null 2>&1; then
+    SLM_BIN="$(command -v slm)"
+    if [ -x "${_VENV_BIN}" ]; then
+        _sys_v="$("${SLM_BIN}" --version 2>/dev/null | awk '{print $NF}')"
+        _venv_v="$("${_VENV_BIN}" --version 2>/dev/null | awk '{print $NF}')"
+        if [ -n "${_venv_v}" ] && [ "${_sys_v}" != "${_venv_v}" ]; then
+            echo "SLM: using the installed slm ${_sys_v:-?} and IGNORING a leftover venv at ${_VENV_BIN} (${_venv_v})." >&2
+            echo "  One store, one version. Remove it to stop it drifting:  rm -rf \"${_SLM_DATA_DIR}/venv\"" >&2
+        fi
+    fi
+elif [ -x "${_VENV_BIN}" ]; then
+    SLM_BIN="${_VENV_BIN}"
+else
+    echo "SLM: no SuperLocalMemory found — looked for 'slm' on PATH and ${_VENV_BIN}." >&2
+    echo "  Install it with:  pipx install superlocalmemory" >&2
+    exit 1
+fi
+
+if ! "${SLM_BIN}" serve start >&2; then
+    echo "SLM plugin: unable to start the owned daemon; refusing a direct MCP writer." >&2
+    exit 1
+fi
+
+exec "${SLM_BIN}" mcp

package/codex-plugin/scripts/slm-launch.bat

@@ -0,0 +1,30 @@
+@echo off
+:: slm-launch.bat (Codex edition) — SuperLocalMemory MCP launcher (Windows)
+::
+:: Cross-platform counterpart: slm-launch (POSIX bash)
+:: Referenced by codex-plugin/.codex/config.toml as the advanced MCP server command.
+::
+:: Resolves the correct venv binary for Windows and joins the namespace daemon before
+:: opening MCP, preserving one writer for parallel Codex sessions.
+::
+:: Difference from plugin/scripts/slm-launch.bat (Claude Code edition):
+::   - Uses SLM_DATA_DIR (default: %USERPROFILE%\.superlocalmemory) instead of
+::     CLAUDE_PLUGIN_DATA.
+::   - Falls back to the PATH `slm` binary if the venv binary is not present.
+::
+:: Environment:
+::   SLM_DATA_DIR — persistent data dir where venv lives
+::                  (default: %USERPROFILE%\.superlocalmemory)
+
+if not defined SLM_DATA_DIR set "SLM_DATA_DIR=%USERPROFILE%\.superlocalmemory"
+set "SLM_BIN=%SLM_DATA_DIR%\venv\Scripts\slm.exe"
+
+if not exist "%SLM_BIN%" set "SLM_BIN=slm"
+
+"%SLM_BIN%" serve start 1>&2
+if errorlevel 1 (
+    echo SLM plugin: unable to start the owned daemon; refusing a direct MCP writer. 1>&2
+    exit /b 1
+)
+
+"%SLM_BIN%" mcp

package/codex-plugin/skills/slm-bot-memory/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: slm-bot-memory
+description: Cross-bot memory on a shared computer (Grok Bot, Cursor plugin, any host where several agents share one machine). Explains agent_id attribution vs. profile/scope access, how to namespace by agent_id + profile + scope, and what must never be written to memory. Read this before the first remember/recall on a new Grok-Bot-style host.
+when_to_use: |
+  - First session on a Grok Bot computer or any shared-bot host
+  - "Will my other bots see this memory?"
+  - "How do I keep this bot's notes separate from that one?"
+  - Deciding whether to store something that looks like a secret or personal data
+  - Setting up a second bot on a computer that already has SLM configured
+allowed-tools: remember, recall, search, session_init, switch_profile
+---
+
+# slm-bot-memory — Cross-Bot Memory on a Shared Host
+
+SuperLocalMemory ships as an MCP server. On a single-user laptop, one bot is
+the only thing talking to it. On a **shared-bot host** — Grok Bot's "one
+computer, shared by all your Bots" model, several Cursor windows, or any
+setup where more than one agent process points at the same install — several
+agents can reach the same memory store at once. This skill is about that
+case: what is actually isolated, what is not, and what must never be written
+regardless.
+
+---
+
+## Three things that sound like isolation and are not the same
+
+| Setting | What it controls | Does it hide memories from another bot? |
+|---|---|---|
+| `SLM_AGENT_ID` | **Attribution** — who gets credit for a memory in logs and summaries | **No.** It is metadata, never an authenticated principal (verified in `mcp/agent_context.py`'s own docstring). Any bot that can query the same store can read a memory written under a different `agent_id`. |
+| `SLM_DATA_DIR` (profile root) | **Which database file** the daemon opens | **Yes.** Two bots pointed at different `SLM_DATA_DIR` values have fully separate, independent memory stores — nothing is shared unless you explicitly configure sharing. |
+| `scope` (`personal` / `shared` / `global`, see `slm-scope`) | **Visibility inside one store**, between profiles that share that store | Only the way you set it. `personal` (the default) stays within the writing profile; `shared`/`global` are explicit, user-initiated opt-ins. |
+
+A memory profile (the namespace `profile_id` and `switch_profile` select) is not
+a fourth kind of isolation between bots. Any local caller that can name a profile
+can read it, and `switch_profile` moves the active profile for every bot on the
+computer. Treat profiles as organisation, not privacy.
+
+The practical rule: **`SLM_AGENT_ID` tells you who wrote something; `SLM_DATA_DIR`
+and `scope` decide who can read it.** If two bots on the same Grok Bot computer
+use the same `SLM_DATA_DIR` (the common case — it is a shared filesystem, and
+nothing in Grok Bot's plugin model points different bots at different data
+directories by default), they see each other's `personal`-scope memories too,
+the same way two terminal sessions on one laptop would. Giving two bots
+different `SLM_AGENT_ID` values does not change that — it only changes whose
+name shows up on the memory.
+
+If you need one bot's memories genuinely unreachable from another, that bot
+needs its **own `SLM_DATA_DIR`** (or a store where company mode with roles is
+configured — see `slm-governance`), not just its own `SLM_AGENT_ID` or its own
+profile.
+
+---
+
+## Namespacing that actually works
+
+Use all three dimensions together, each for what it is good at:
+
+1. **`agent_id`** (`SLM_AGENT_ID` env, or the `agent_id` parameter on
+   `remember`/`recall` directly) — so a human or another agent reading
+   `get_memory_summary` or the stored facts later can tell which bot said
+   what. Set it to something stable and specific: `grok_bot_support`,
+   `grok_bot_release_notes`, not a generic `bot`.
+2. **`SLM_DATA_DIR`** — the real isolation boundary. One store per bot that
+   genuinely needs privacy from the others. A `profile_id` inside a shared store
+   groups memories but does not hide them.
+3. **`scope`** (see `slm-scope`) — inside a store two or more bots
+   legitimately share, keep writes `personal` by default and only promote to
+   `shared`/`global` when a fact is meant for every bot on that store.
+
+```
+remember(
+  content="Deploy window for the support bot is Tue/Thu 14:00-16:00 UTC",
+  tags="ops,schedule",
+  agent_id="grok_bot_support",
+  session_id="<sid>",
+)
+```
+
+```
+recall(
+  query="deploy window",
+  agent_id="grok_bot_support",
+  session_id="<sid>",
+)
+```
+
+Recall is not filtered by `agent_id` automatically — it is attribution on the
+written record. If you need "only what this bot wrote", pass
+`saved_by="grok_bot_support"` to `recall` (or `--saved-by` on `slm recall`),
+which keeps only memories saved by that agent id. It filters; it does not
+protect, because another bot can leave it out.
+
+---
+
+## What never goes into memory, on any host
+
+This is not Grok-Bot-specific — it is the baseline for every SLM host — but
+it matters more here because a shared computer means a shared blast radius if
+it is violated:
+
+- **Secrets, API keys, tokens, passwords, certificates.** Never pass them to
+  `remember`, even "just this once" or "temporarily." If a fact needs to
+  reference that a credential exists, store the *fact of its existence and
+  where to rotate it*, never the value.
+- **Personal data about identifiable people** that was not already something
+  the user explicitly asked to be remembered about themselves (names,
+  emails, addresses, health, financial details of third parties).
+- **Anything from Grok Bot's shared filesystem you did not write yourself**
+  and were not asked to remember. "Files are visible to every Bot" on that
+  computer (Grok Bot's own docs) — a file being readable is not the same as
+  having permission to copy its contents into long-term memory that other
+  bots and later sessions will see.
+- **Command-line credentials.** Grok Bot's own docs note these are shared
+  across bots on the computer; SLM must not become a second, more durable
+  copy of them.
+
+If you are unsure whether something is a secret, treat it as one and ask the
+user before storing anything derived from it.
+
+---
+
+## Checklist for a new bot on an existing shared host
+
+1. Confirm `SLM_DATA_DIR` — is this bot meant to share the existing store, or
+   does it need its own? (`slm status --json` on the computer shows `data.base_dir`
+   and `data.db_path`.)
+2. Set a specific `SLM_AGENT_ID` for this bot before the first `remember`.
+3. Read `slm-scope` before writing anything with `scope="shared"` or
+   `scope="global"` — those are machine-wide, not just cross-bot.
+4. Read the "never goes into memory" list above once, out loud if you are
+   unsure, before the first write on this host.
+
+---
+
+## Related skills
+
+- `slm-getting-started-bot` — first-session setup for a headless bot host
+- `slm-scope` — the personal/shared/global visibility model this skill
+  namespaces on top of
+- `slm-profile` — memory profiles versus tool sets, and what switching does
+- `slm-governance` — role-based access when a store has multiple human/bot
+  members and real access control, not just convention
+
+---
+
+*SuperLocalMemory v4.1.23 · Qualixar · AGPL-3.0-or-later*