superlocalmemory 4.1.22 → 4.1.23

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

@@ -0,0 +1,370 @@
+---
+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, set_memory_kind, review_memory_kinds, confirm_memory_kinds, list_corrections, review_correction, delete_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:
+
+- If the new text **replaces** the old one (a status that moved on, a decision
+  that changed, a rule that was reworded), save it with
+  `remember(..., replaces="<fact_id>")`. It takes effect at once and can be
+  undone.
+- If you are **correcting** the old memory and want a person to approve the
+  change, use `update_memory(fact_id, content)`. This opens a correction for
+  review; it does not overwrite anything (see "Updating a memory" below).
+- Only call `remember` with neither 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:
+
+```
+remember(
+  content="JWT tokens use 1h expiry for API access tokens; refresh tokens 30d",
+  tags="auth,security,decision",
+  project="superlocalmemory",
+  kind="decision",
+  replaces="f8a2bc91",
+)
+```
+
+The old memory is retired, not deleted: recall stops returning it and it is no
+longer loaded at session start. The response's `replaced` says what was retired,
+or why nothing was (the new memory is saved either way). An unknown id, or an id
+from another profile, is refused before anything is saved.
+
+### 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,
+  "pending_id": null,
+  "operation_id": "op-7c21",
+  "materialization_state": "complete",
+  "message": "Stored through canonical daemon ingestion."
+}
+```
+
+`pending: true` with `materialization_state` `queryable` or `enriching` means the
+memory is already stored and findable by its words while enrichment finishes;
+do not re-save. A reply with `materialization_state: "accepted"` and `count: 0`
+means the memory is durable but the writer was busy; it becomes searchable
+within seconds, and resending the same `idempotency_key` returns the final
+receipt. When the call used `replaces` the reply carries `replaced`; when the
+same words were already saved under another confirmed kind it carries
+`kind_conflict` and keeps that kind.
+
+Failures come back as `success: false` with a `code` and `retryable`:
+`DAEMON_UNAVAILABLE` (`retryable: true`), `INVALID_KIND`, `NOT_AUTHORIZED`, or an
+unknown-profile / unknown-`replaces` refusal (`retryable: false`).
+
+**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,   # "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
+  kind: str = "",      # what sort of memory this is; see "Say what kind it is"
+  replaces: str = None,# fact_id (or memory_id) of the earlier memory this one replaces
+  profile_id: str = "",# write to another existing profile; "" = the active one
+  agent_id: str = "mcp_client", # attribution; resolved from the connection when left alone
+)
+```
+
+> **Multi-scope (opt-in):** leave `scope` unset for `personal` (private to
+> this profile — the default, the same as a single-profile install). `"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. Older stores spelled this type
+`"temporal"`; that value still reads correctly and needs nothing from you.
+
+---
+
+### 5. Say what kind it is
+
+`kind` is one of nine values: `rule` (a standing instruction: "always/never
+..."), `decision` (a choice that settles a question), `status` (the current
+state of something, which a later update will replace), `procedure` (steps or
+commands), `prospective` (a plan or to-do), `opinion` (a preference or view),
+`correction` (says an earlier memory was wrong), `episodic` (something that
+happened) or `semantic` (a lasting fact). An unknown value is refused with
+`INVALID_KIND` before anything is saved.
+
+Set it whenever you know. A kind you declare is confirmed, and confirmed rules
+(up to 10) and confirmed decisions (up to 5) are loaded by `session_init` at
+the start of later sessions. Leave `kind` empty when unsure: SLM may suggest
+one later, and a suggestion changes nothing until someone confirms it. Never
+set a kind just to get a memory loaded at session start.
+
+Manage kinds after the fact:
+
+| Tool | Use |
+|---|---|
+| `set_memory_kind(fact_id, kind)` | Set and confirm the kind of one memory you know the type of |
+| `review_memory_kinds(kind="", limit=20)` | List suggestions waiting for confirmation (limit 1–100) |
+| `confirm_memory_kinds(items)` | Confirm up to 200 at once; each item is `{"fact_id": ..., "kind": ...}`, and omitting `kind` accepts the suggestion |
+| `memory_kinds_status()` | Counts per kind, the classifying backend, any run in progress |
+
+CLI: `slm remember "<text>" --kind rule`, `slm kinds status|set|review|confirm`,
+`slm kinds backfill start|pause|resume|cancel|revert|status`, and
+`slm kinds settings` (backend, standing rules on or off). Classifying with Jev
+sends memory text online and needs its own consent (`--jev-consent yes`).
+
+### 6. Updating a memory: `replaces` versus `update_memory`
+
+`update_memory(fact_id, content)` and `slm update <fact_id> "<new text>"` do not
+overwrite a memory. They keep the original and propose a correction: the reply
+has `predecessor_fact_id`, `successor_fact_id`, `correction_case` (with
+`case_id`, `status`, `version`) and `review_required: true`. Until a person
+applies the case, **the original stays current and the new text is not
+returned by recall**. A memory can have only one open correction at a time; a
+second edit is refused with a message naming the open case.
+
+Review cases with `list_corrections(limit=100)` and
+`review_correction(case_id, action, expected_version)`, where `action` is
+`apply`, `reject` or `rollback` and `expected_version` is the case's current
+`version`. `apply` retires the original and admits the new text; `rollback`
+undoes an applied case (including one made by `replaces`). CLI:
+`slm review-correction <case_id> apply|reject|rollback <expected_version>`.
+
+Two rules about SLM's own guesses. When it saves a memory that looks like an
+update to an older one, it may file a correction case of its own. That guess
+never hides the memory you saved: both stay findable until a person reviews it,
+approving retires the older one, and rejecting keeps both. And if you edit,
+replace or delete a memory that only such an unreviewed machine guess names,
+your action wins and the guess is closed as overtaken (`slm corrections
+overtaken` lists them, `slm corrections restore-overtaken <case_id>` puts one
+back). A correction a person proposed, or one already decided, is kept
+permanently and protects the memories in it from being deleted.
+
+### 7. 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.
+
+### 8. 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
+
+The MCP `forget(dry_run=True)` tool runs an Ebbinghaus decay cycle over the
+whole profile — it does NOT delete by query. To delete one memory you have the
+id of, call `delete_memory(fact_id)`. To delete by query, 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`.
+A memory that belongs to a reviewed correction cannot be deleted (it is refused
+with the case ids and nothing is changed). Treat every other deletion as permanent.
+
+---
+
+## CLI fallback (when MCP is unavailable)
+
+```bash
+# Store a fact
+slm remember "<content>" [--tags a,b,c] [--kind rule|decision|...] [--json]
+
+# Replace an earlier memory (takes effect at once; undo with review-correction)
+slm remember "<content>" --replaces <fact_id> --kind status
+
+# Store a shared/global fact (opt-in)
+slm remember "<content>" --scope global
+slm remember "<content>" --scope shared --shared-with alice,bob
+
+# Propose a reviewed correction instead of replacing
+slm update <fact_id> "<new text>"
+slm review-correction <case_id> apply|reject|rollback <expected_version>
+
+# Flags: --tags, --kind, --replaces, --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 has changed and the new version should win now | `remember(..., replaces="<fact_id>")` |
+| Fact needs a correction a person should approve | `update_memory(fact_id, new_content)`, then `review_correction` |
+| Duplicate found that matches recall result | `replaces` the existing one, or leave it |
+| Fact is wrong and should disappear | `slm forget "<query>" --dry-run` then `--yes` |
+| Fact has a known ID and is clearly obsolete | `delete_memory(fact_id)` or `slm delete <fact_id> --yes` |
+
+---
+
+## Sharing across profiles (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
+
+`remember` stores in the active profile. To write one memory to another existing
+profile, pass `profile_id="<name>"`; an unknown name is rejected, never created.
+`switch_profile` moves the active profile for every later call and for other
+sessions on this machine, so use it only when the user asks to move. 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.23 · Qualixar · AGPL-3.0-or-later*

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

@@ -0,0 +1,183 @@
+---
+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: `--include-global` / `--no-global`, `--include-shared` / `--no-shared`
+on `slm recall`; `--scope personal|shared|global` and `--shared-with <profile-ids>`
+on `slm remember`. Leaving a flag unset uses the configured default.
+
+---
+
+## Configuring scope defaults
+
+The defaults live in the `scope` section of the mode config files (`mode_a.json`,
+`mode_b.json`, `mode_c.json`, and the active `config.json`). To make a profile's
+recalls always include global facts without passing a flag each time:
+
+```json
+{
+  "scope": {
+    "default_scope": "personal",
+    "recall_include_global": true,
+    "recall_include_shared": false
+  }
+}
+```
+
+Omit the section, or any field, to keep the safe defaults (`personal`, `false`,
+`false`). An invalid `default_scope` is ignored with a warning. Changing the
+default requires editing the config directly — this is an admin-level operation,
+and an agent must not do it on its own.
+
+---
+
+## Enterprise governance
+
+In a workspace with roles (company mode, see `slm-governance`):
+- **Viewers** cannot write at all, whatever `scope` says.
+- **Members and admins** can write `shared` and `global` facts: both hold the
+  share permission. Deleting needs the delete permission, which only admins hold.
+- Explicit `include_global=True` / `include_shared=True` on `recall` are quietly
+  turned off while the recall policy forbids cross-profile reads, which is the
+  default in company mode. If an opt-in recall returns only personal facts in a
+  governed workspace, that is the policy working, not a bug; do not try to work
+  around it.
+
+---
+
+## 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.23 · Qualixar · AGPL-3.0-or-later*