superlocalmemory 4.1.21 → 4.1.22

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

@@ -0,0 +1,273 @@
+---
+name: slm-remember
+description: Capture durable facts, decisions, constraints, and gotchas into SuperLocalMemory. Use when the user says "remember that", "save this decision", "note this constraint", or when a session produces a conclusion worth persisting across sessions. Always recall first to avoid duplicates.
+when_to_use: |
+  - "Remember that we use JWT with 1h expiry"
+  - "Save this architectural decision"
+  - "Store the constraint that X must not Y"
+  - "Note this as a gotcha / blocker / convention"
+  - After making a non-obvious decision during a coding session
+  - After resolving a bug whose root cause should be persisted
+allowed-tools: remember, recall, update_memory, Bash
+---
+
+# slm-remember — Capture Durable Facts
+
+Store atomic, durable facts into SuperLocalMemory for retrieval in future
+sessions. One fact per call. Recall before you remember.
+
+---
+
+## What to store (and what not to)
+
+**Store:**
+- Architectural decisions ("Decided to use Postgres not MySQL — reason: JSONB support")
+- Project conventions ("All API routes follow /api/v1/resource/{id} pattern")
+- Hard constraints ("Never expose raw SQL errors to the HTTP response")
+- Resolved gotchas ("Ollama needs keep_alive=-1 or it unloads the model between calls")
+- Security rules ("Rate limit all public endpoints at 100 req/min")
+
+**Do not store:**
+- Transient context that is only relevant within this conversation
+- Large blobs of code or full file contents (those belong in the project, not memory)
+- Facts the project README already captures
+
+---
+
+## Recall-before-remember (mandatory discipline)
+
+Before calling `remember`, always call `recall` first with the core terms of
+what you are about to store. If a near-duplicate exists:
+
+- Use `update_memory(fact_id, content)` to refine the existing fact instead
+  of creating a new one.
+- Only call `remember` when no sufficiently similar fact is found.
+
+Duplicates degrade retrieval quality for every future session.
+
+---
+
+## MCP-first workflow
+
+### 1. Check for duplicates first
+
+```
+recall(query="JWT token expiry auth", limit=5, session_id="<sid>")
+```
+
+If a near-duplicate is returned:
+
+```
+update_memory(
+  fact_id="f8a2bc91",
+  content="JWT tokens use 1h expiry for API access tokens; refresh tokens 30d (updated 2026-06-16)",
+)
+```
+
+`update_memory` returns `{"success": true, "fact_id": "f8a2bc91", "content": "..."}`.
+
+### 2. Store a new fact
+
+```
+remember(
+  content="Decided to use JWT with 1h expiry for API auth; refresh tokens persist 30 days",
+  tags="auth,security,decision",
+  project="superlocalmemory",
+  importance=8,
+  session_id="<sid>",
+)
+```
+
+Real response shape:
+```json
+{
+  "success": true,
+  "fact_ids": ["c9d4e112"],
+  "count": 1,
+  "pending": false,
+  "message": "Stored (recallable now; enriching async)."
+}
+```
+
+When `pending: true`, the daemon was offline at save time; the fact enters a
+pending queue and becomes recallable once the daemon is back. Do not re-save.
+
+**Never claim "saved" unless `success: true` is in the response.**
+
+### 3. Parameter reference
+
+```
+remember(
+  content: str,       # required — the atomic fact to store
+  tags: str = "",     # comma-separated tags, e.g. "auth,security,gotcha"
+  project: str = "",  # project scope, e.g. "superlocalmemory"
+  importance: int = 5,# 1–10; see scale below
+  session_id: str = "",# from session_init; attributes the write to this session
+  session_date: str = "",# when the memory is ABOUT, if not today
+  scope: str = None,   # v3.6.15 multi-scope: "personal" (default) | "shared" | "global"
+  shared_with: str = "",# comma-separated profile_ids for scope="shared"
+  idempotency_key: str = "",# replaying the same key will not store a second copy
+)
+```
+
+> **Multi-scope (v3.6.15, opt-in):** leave `scope` unset for `personal` (private to
+> this profile — the default, identical to 3.6.14). `"global"` is visible to every
+> profile on the machine; `"shared"` is visible to the profiles in `shared_with`.
+> See [docs/shared-memory.md](../../../docs/shared-memory.md).
+
+**importance scale:**
+- 1–3: Low — passing notes, ideas, soft preferences
+- 4–6: Normal — patterns, conventions, standard decisions (default: 5)
+- 7–8: High — architectural decisions, integration contracts, known gotchas
+- 9–10: Critical — security rules, blockers, irreversible decisions
+
+Use 7–10 only for facts that would cause real damage if forgotten.
+
+### 4. Date a memory to when it happened
+
+`session_date` says **when the memory is about**, as distinct from when you
+wrote it. Omit it and the memory is dated today.
+
+```
+remember(
+  content="The outage on the payments queue was caused by a stale DNS entry",
+  tags="incident,payments,postmortem",
+  project="platform",
+  session_date="2026-08-14",       # YYYY-MM-DD, or a full ISO 8601 timestamp
+  session_id="<sid>",
+)
+```
+
+Use it whenever you are writing something down after the fact — a postmortem, a
+decision taken in a meeting last week, a migration that ran on a known date.
+Time-filtered recall (`window="7d"`, `window="2026-07-01..2026-07-31"`) reads
+event time, so a mis-dated memory is one a time-scoped question cannot find.
+
+`session_date` does not change what **kind** of memory it is. A memory that
+describes something planned — "the migration is scheduled for Tuesday", "the
+certificate expires on 2026-09-01" — is stored as a **prospective** memory, and
+recall reports it as `"fact_type": "prospective"`. That is inferred from how the
+content reads, not from the date you pass. Stores written before 4.1.0 spelled
+this type `"temporal"`; that value still reads correctly and needs nothing from
+you.
+
+---
+
+### 5. One fact per call
+
+Store one atomic fact per `remember` call. Do not concatenate multiple unrelated
+points into a single content string — they will be hard to update individually
+and harder to retrieve cleanly. If you have three separate decisions, make three
+calls.
+
+### 6. Always set tags and project
+
+Untagged, unscoped facts are harder to retrieve and harder to manage. Minimum:
+set `tags` to one or two relevant terms and `project` to the repo/product name.
+
+---
+
+## Deleting stale facts via CLI
+
+For deletion, the CLI is the authoritative surface. The MCP `forget` tool in
+v3.6.14 runs an Ebbinghaus decay cycle — it does NOT delete by query. For
+targeted deletion, use the CLI:
+
+```bash
+# Preview what would be deleted (always do this first)
+slm forget "<query>" --dry-run [--json]
+
+# Execute deletion after confirming the preview
+slm forget "<query>" --yes [--json]
+
+# Delete a specific fact by exact ID (use when you have the fact_id)
+slm delete <fact_id> --yes [--json]
+```
+
+Flags verified in source (main.py):
+- `slm forget`: positional `query`, `--dry-run`, `--yes` / `-y`, `--json`
+- `slm delete`: positional `fact_id`, `--yes` / `-y`, `--json`
+
+Always run `--dry-run` first and review the preview before passing `--yes`.
+
+---
+
+## CLI fallback (when MCP is unavailable)
+
+```bash
+# Store a fact
+slm remember "<content>" [--tags a,b,c] [--json]
+
+# Store a shared/global fact (v3.6.15, opt-in)
+slm remember "<content>" --scope global
+slm remember "<content>" --scope shared --shared-with alice,bob
+
+# Flags verified in source (main.py): --tags, --json, --sync, --scope, --shared-with
+# --sync: wait for full enrichment before returning (default is async)
+# --scope: personal (default) | shared | global ; --shared-with: profile ids for shared
+```
+
+**Flags that do NOT exist** on `slm remember`:
+`--importance`, `--project`, `--format` — these are MCP-only params or fabricated.
+
+---
+
+## Update vs forget discipline
+
+| Scenario | Action |
+|----------|--------|
+| Fact is still true but needs refinement | `update_memory(fact_id, new_content)` |
+| Fact is superseded or wrong | `slm forget "<query>" --dry-run` then `--yes` |
+| Duplicate found that matches recall result | `update_memory` on the existing one |
+| Fact has a known ID and is clearly obsolete | `slm delete <fact_id> --yes` |
+
+---
+
+## 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 v4.1.22 · Qualixar · AGPL-3.0-or-later*

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