superlocalmemory 4.1.22 → 4.1.23

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

@@ -8,7 +8,7 @@ when_to_use: |
   - "Find stored information about authentication / the database / error handling"
   - "Search for what I said about Y"
   - Automatically before any non-trivial task, to surface prior context
-allowed-tools: recall, search, fetch, list_recent, Bash
+allowed-tools: recall, search, fetch, list_recent, get_memory_summary, run_view, report_outcome, report_feedback, Bash
 ---
 
 # slm-recall — Search & Retrieve Memory
@@ -26,6 +26,8 @@ multi-channel retrieval. The golden rule: **recall before you remember**.
 | Exact keyword match needed ("find facts containing BM25") | `search` — FTS5 BM25 only, lower latency |
 | You have a specific `fact_id` from a prior result | `fetch` — exact lookup, full detail |
 | Browse newest entries without a query | `list_recent` |
+| A day, a project or a session in readable form | `get_memory_summary` |
+| A question the user saved under a name | `run_view` |
 
 Use `recall` as the default. `search` is a fallback for zero-result recall on a
 known exact term. `fetch` is for when you already know the ID.
@@ -54,18 +56,23 @@ recall(
 )
 ```
 
-Real response shape (`--json` equivalent):
+Real response shape (trimmed to the fields that matter; `slm recall --json`
+wraps the same data in a `data` envelope):
 ```json
 {
   "success": true,
   "results": [
     {
       "fact_id": "f8a2bc91",
+      "memory_id": "m7e19ca0",
       "content": "Decided to use JWT with 1h expiry for API auth (2026-06-10)",
       "score": 0.87,
       "confidence": 0.91,
       "trust_score": 0.84,
       "fact_type": "semantic",
+      "memory_kind": "decision",
+      "memory_kind_state": "confirmed",
+      "age_label": "4 months ago",
       "channel_scores": {
         "semantic": 0.88,
         "bm25": 0.61,
@@ -93,15 +100,25 @@ Real response shape (`--json` equivalent):
   },
   "incomplete_channels": [],
   "retrieval_time_ms": 134,
+  "query_id": "q-3f9a",
   "no_confident_match": false,
   "calibration_status": "uncalibrated",
   "calibration_id": null,
   "answer_confidence": null,
   "abstained": false,
-  "abstention_reason": null
+  "abstention_reason": null,
+  "answer_check_status": "off",
+  "answerability": "unjudged",
+  "answerability_reason": "disabled"
 }
 ```
 
+Other fields that can appear: `profile` (the namespace that answered),
+`project_scope` (what a `project` filter did), `tag_scope` (what a `tags`
+filter did), `temporal_frame`, `reranker_status`, and `thematic_context`.
+Long contents are clamped and later results can come back as short stubs
+(`truncated` / `stub` on the result); call `fetch` for the full text.
+
 **Read `channel_status` before concluding that nothing is stored.** It reports
 what each retrieval channel did on this query. `channel_weights` says how much
 each channel counts; `channel_status` says whether it ran at all.
@@ -114,6 +131,7 @@ each channel counts; `channel_status` says whether it ran at all.
 | `error` | it raised — **its results are missing from this answer** |
 | `timeout` | it exceeded its guard — **results missing** |
 | `no_embedding` | the query could not be embedded, so it could not run |
+| `warming` | the embedding model, or the entity graph, was still loading right after a start — **results missing**, and the same question a little later usually works |
 | `disabled` | switched off by configuration |
 | `not_configured` | the backing service is not set up |
 
@@ -125,14 +143,26 @@ entities in your question, which is why it reports `no_candidates` when the
 rest come back empty.
 
 `empty`, `no_candidates`, `disabled` and `not_configured` are normal. `error`,
-`timeout` and `no_embedding` mean the answer is **incomplete, not negative** —
-say so to the user rather than reporting "no memories found". `incomplete_channels`
-carries the same warning as a plain list.
+`timeout`, `no_embedding` and `warming` mean the answer is **incomplete, not
+negative** — say so to the user rather than reporting "no memories found".
+`incomplete_channels` lists the channels abandoned at the time limit, so two
+runs of the same question that differ only there are an incomplete answer, not
+a changed memory.
 
-**Refine on low confidence.** `recall` returns confidence signals with every result. If `no_confident_match` is `true` (or `answer_confidence` is low / `abstained` is `true`), do NOT invent a memory — rewrite the query into 1–3 more specific sub-queries (split multi-hop questions; try entity names, synonyms, or broader phrasing) and call `recall` again before concluding nothing was found. A confident match → use it directly. SLM answers from this machine in about 1–2 s, with no server-side LLM round — unless the user turned on the online answer check, which adds one request to that service per recall — and lets you, the calling model, drive this refinement.
+**Refine on low confidence.** `recall` returns confidence signals with every result. If `no_confident_match` is `true` (or `answer_confidence` is low / `abstained` is `true`), do NOT invent a memory — rewrite the query into 1–3 more specific sub-queries (split multi-hop questions; try entity names, synonyms, or broader phrasing) and call `recall` again before concluding nothing was found. A confident match → use it directly. SLM answers from this machine, typically in a second or two, with no server-side LLM round — unless the user turned on the online answer check, which adds one request to that service per recall — and lets you, the calling model, drive this refinement.
 
 **`abstained` means the results shown do not answer the question.** If `abstained` is `true`, say you don't have it, or ask — never present the returned memories as the answer anyway. `abstention_reason` distinguishes why: `"judged_insufficient"` means candidates were found and scored, but none of them actually answers this question; `"evidence_floor"` / `"no_candidates"` means nothing was found at all. `answer_confidence` is a measurement, not a guarantee — treat a low number the same way you'd treat `abstained: true`. `calibration_status: "uncalibrated"` means no judge is configured for this recall; in that case `abstained` only ever reflects the older "nothing found" signal.
 
+**`abstained: false` does not mean the answer was checked.** `answerability` says
+whether it was: `supported` (the answer check ran and judged the shown memories
+sufficient), `unsupported` (it ran and judged them insufficient) or `unjudged`
+(it produced no verdict). `answerability_reason` gives the cause: `judged_fresh`
+or `judged_from_memo` for a verdict, and for `unjudged` one of `disabled`,
+`warming`, `unavailable`, `busy`, `budget_exhausted`, `no_results`,
+`not_a_question` or `other_profile`. An empty result set is `unjudged` /
+`no_results`, which is not evidence that no answer exists (check
+`channel_status`). `answer_check_note` carries a sentence you can show a person.
+
 ### 2. Passing session_id
 
 Pass the `session_id` returned by `session_init`, on **every** recall in that
@@ -148,21 +178,26 @@ session. It does two things.
 2. **It attributes engagement to the session**, so a later `report_outcome`
    can close the loop on the right recall.
 
-Omitting it costs both: recall still returns correct results, but every turn
-starts cold and no feedback is attributable.
+If you omit it, SLM looks for `SLM_SESSION_ID`, `CLAUDE_SESSION_ID` or
+`CLAUDE_CODE_SESSION_ID` in the environment, then for the host's registered
+session, and only then falls back to a per-agent label that is never credited
+to a conversation. Recall still returns correct results either way, but a
+fallback label means turns start cold and feedback cannot be attributed.
 
-**Use the real id, not a made-up one.** An id beginning `http:`, `mcp:`, `cli:`
-or `probe:` is treated as a synthetic per-request label, not a conversation, and
-is excluded from the working set — inventing one per call would otherwise fill
-the registry and evict genuine conversations.
+**Use the real id, not a made-up one.** An id beginning `http:`, `mcp:`, `cli:`,
+`probe:`, `engine:`, `agent:`, `api:` or `view:` is treated as a synthetic
+per-request label, not a conversation, and is excluded from the working set —
+inventing one per call would otherwise fill the registry and evict genuine
+conversations.
 
 ### 3. Fast mode
 
 `fast` controls **one** thing: whether the server runs its own internal LLM
 reformulation round. It does **not** disable any retrieval channel — every
-channel and the reranker run either way. There are four always: meaning,
+channel and the reranker run either way. Four channels register always: meaning,
 keyword, entity graph and time. Spreading activation and Hopfield register as a
-fifth and sixth when their prerequisites are present, so a store sees up to six.
+fifth and sixth when their prerequisites are present, so a store sees up to six
+(`profile` in `channel_status` is a shortcut ahead of them, not a search).
 
 Leave it unset. Unset resolves to "skip the internal round", because you are the
 reasoner: you refine the query yourself using the confidence signals above, and
@@ -178,11 +213,14 @@ recall(query="rate limiting approach", limit=5, session_id="<sid>")
 When `recall` returns zero results on a specific term, try `search`:
 
 ```
-search(query="BM25 indexing", limit=10, profile_id="")
+search(query="BM25 indexing", limit=20)
 ```
 
-`profile_id=""` uses the active profile. Response has `success`, `results`,
-and `count` but no `channel_scores` or `query_type`.
+Full-text FTS5 with BM25 ranking, no semantic channel. It takes the same
+`kind`, `tags` / `tags_match` and `profile_id` arguments as `recall` (below).
+The response has `success`, `results` (each with `fact_id`, `content`,
+`fact_type`, `confidence`, `date` and the memory-kind fields) and `count`, but
+no `channel_scores`, `query_type` or answer-check fields.
 
 ### 5. Pull full detail for a known fact
 
@@ -191,44 +229,96 @@ fetch(fact_ids="f8a2bc91,d4c1e203")
 ```
 
 Returns the full record for each ID: `entities`, `lifecycle`, `access_count`,
-`importance`, `observation_date`, `referenced_date`. Use this when the recall
+`importance`, `observation_date`, `referenced_date`, `project`. `fact_ids` may be
+a comma-separated string or a list. Ids it could not resolve come back in
+`not_found`; if none resolve, `success` is `false`. Use this when the recall
 summary (120-char truncation in `list_recent`) is not enough.
 
 ### 6. Browse recent memories
 
 ```
-list_recent(limit=20, profile_id="")
+list_recent(limit=20, kind="", tags="", tags_match="all", profile_id="")
 ```
 
 Returns facts newest-first. Content is truncated to 120 chars. Use `fetch`
 once you have the `fact_id` for full content.
 
+### 7. Narrow a recall
+
+Every filter below is optional and composes with the others as AND.
+
+| Argument | Effect |
+|---|---|
+| `project` | Only memories saved under that project (a name or a path; case ignored). If none of the memories found were saved under it, the unfiltered results come back and `project_scope.filter.applied` is `false` with a `note` — never a silent empty answer. |
+| `project_strict=True` | With `project`: no fall-back, only that project's memories even if there are none. |
+| `prefer_project` | Ranks memories saved under that project above others of similar relevance and removes nothing. Pass your working directory on every recall in a project. |
+| `saved_by` | Only memories saved by that agent id (for example `claude-desktop`). |
+| `about` | Only memories that mention that person, project or tool. |
+| `kind` | Only memories of one kind: `semantic`, `episodic`, `status`, `opinion`, `rule`, `decision`, `procedure`, `prospective` or `correction`. An unknown value is refused with `INVALID_KIND`. |
+| `tags`, `tags_match` | Only memories saved with these exact labels (a comma-separated string, or a list when a label contains a comma). `tags_match` is `"all"` (default) or `"any"`. Case and spacing do not matter. Unlike `project`, a tag filter never falls back; an empty answer says why in `tag_scope`. |
+| `window` | Event-time range: `"24h"`, `"7d"`, `"30d"`, `"1y"` or `"2026-07-01..2026-07-31"`. An unreadable value is refused. |
+| `as_of`, `known_as_of`, `valid_at` | Point-in-time recall (ISO 8601). `known_as_of` is what SLM knew by then; `valid_at` is what was true then. `include_unknown=True` also admits older memories with no recorded time provenance. |
+| `profile_id` | Serve this one call from another existing profile without moving the active one. |
+
+Questions phrased like "what did we decide", "how do I" or "what is the current
+status of" are answered with decisions, how-tos and the newest current-state
+memory first, without any filter.
+
+```
+recall(query="rollback procedure", kind="procedure", tags="ops", prefer_project="/work/api", session_id="<sid>")
+```
+
+### 8. Summaries and saved views
+
+`get_memory_summary(kind="day", target="")` returns a readable summary of a
+`day` (an ISO date, `today` or `yesterday`), a `project` (a directory path), a
+`session` (a session id; leave `target` empty to get `recent_sessions` to pick
+from) or a `community` (the `community_id` a recall gave in `thematic_context`).
+It comes with `coverage` and `source_fact_ids`; session data is sparse, so do
+not present a partial summary as a complete record.
+
+`run_view(name="")` lists the user's saved views; with a name it runs that
+saved question through ordinary recall, and the same `no_confident_match` rule
+applies. Views are created from the dashboard, with `slm view create`, or with
+`manage_view`.
+
 ---
 
-### 7. Close the loop — say which memories helped
+### 9. Close the loop — say which memories helped
 
-Retrieval ranks a memory partly on whether it has actually been useful before.
-That evidence only exists if you supply it.
+Whether a memory has been useful is evidence SLM records only if you supply it.
+It is stored as learning signals (the count shows in `session_init`'s `learning`
+block and on the dashboard). Signals reorder results only where adaptive ranking
+is switched on by the operator (`SLM_RANKING`); it is off unless set, so do not
+promise the user that a report changes the next answer.
 
 ```
 report_outcome(
   memory_ids="f8a2bc91,c31d0f77",   # the ids you actually used
   outcome="success",                # "success" | "failure" | "partial"
   context="used the JWT expiry decision to write the refresh handler",
+  recall_query_id="q-3f9a",         # the query_id of the recall; ties the report to that answer
 )
 ```
 
+`report_outcome` and `report_feedback` are not in the smallest (`core`) tool set.
+If your host does not list them, skip this step; nothing else depends on it.
+
 Call it when a recall visibly changed what you did: you applied the decision,
 followed the convention, or avoided the gotcha. Report `failure` when a
 confidently-returned memory turned out to be wrong or stale — a negative signal
-is worth as much as a positive one, and it is the only way a stale memory stops
-being promoted.
+is recorded the same as a positive one. To retire a stale memory outright, save
+the new version with `replaces` (see `slm-remember`).
 
 Report only ids you genuinely used. Reporting every returned id marks the
-irrelevant ones useful and trains the ranker toward noise.
+irrelevant ones useful and records noise as signal. Without `recall_query_id`
+the report is matched to a recall by overlapping memory ids within a time window.
 
 `report_feedback(fact_id, feedback, query)` is the finer-grained form for a
-single fact and the query that surfaced it.
+single fact and the query that surfaced it; `feedback` is `"relevant"` (the
+default), `"irrelevant"` or `"partial"`. If the signal could not be written to
+the learning store it answers `success: false` with `durable: false`: do not
+tell the user it was recorded.
 
 ---
 
@@ -238,8 +328,8 @@ single fact and the query that surfaced it.
 keyword matching, temporal recency weighting, and contextual graph channels — then
 fuses and reranks the combined results, with an optional entity-graph score
 enhancement. The `channel_weights` field in the response shows how each channel
-contributed for that query. Weights adapt over time based on engagement signals
-attributed via `session_id`.
+contributed for that query. Adaptive re-weighting from engagement signals is an
+operator opt-in (`SLM_RANKING`) and is off by default.
 
 To inspect per-channel scores for a real query against your own data:
 
@@ -254,35 +344,40 @@ No benchmark numbers are cited here; performance is workload-dependent.
 ## CLI fallback (when MCP is unavailable)
 
 ```bash
-# Multi-channel semantic recall
-slm recall "<query>" [--limit N] [--fast] [--json]
+# Multi-channel recall
+slm recall "<query>" [--limit N] [--json]
 
-# Opt into shared/global facts for one query (v3.6.15 — off by default)
-slm recall "<query>" --include-global --include-shared
+# Narrow it (all optional, combined as AND)
+slm recall "<query>" --project <name-or-path> [--project-strict] [--prefer-project <path>]
+slm recall "<query>" --kind decision --tag auth --tag security [--tags-match any]
+slm recall "<query>" --saved-by claude-desktop --about "Alice" --window 7d
+slm recall "<query>" --as-of 2026-01-01T00:00:00+00:00 [--known-as-of ...] [--valid-at ...] [--include-unknown]
 
-# Keyword/FTS5 search (alias: slm search)
-slm search "<query>" [--limit N] [--json]
+# Opt into shared/global facts for one query (off by default)
+slm recall "<query>" --include-global --include-shared
 
 # Per-channel score breakdown
 slm trace "<query>" [--limit N] [--json]
 
-# Browse recent memories
-slm list [--limit N] [--json]
+# Browse recent memories; each line shows the memory's kind and its id
+slm list [--limit N] [--kind KIND] [--tag LABEL ...] [--tags-match all|any] [--json]
+
+# Summaries and saved views
+slm summary day [today|yesterday|YYYY-MM-DD] | project <path> | session <id> | sessions  [--json]
+slm view list | create <name> "<query>" [--kind K --window W --limit N] | run <name> | show <name> | rename <name> <new> | delete <name>
 ```
 
-Flags verified in source (main.py):
-- `slm recall`: `--limit`, `--fast`, `--json`, `--include-global` / `--no-global`, `--include-shared` / `--no-shared`
-- `slm search`: `--limit`, `--json`
-- `slm trace`: `--limit`, `--json`
-- `slm list`: `--limit` / `-n`, `--json`
+`slm search` is an alias of `slm recall`: it runs the same multi-channel
+retrieval, not the FTS5-only keyword search the MCP `search` tool performs.
+`--fast` forces the quick path; it is already the default for agents.
 
-> **Multi-scope (v3.6.15, opt-in):** recall is shared-OFF by default — it returns only
-> this profile's facts. Pass `--include-global` / `--include-shared` (or the MCP
-> `include_global` / `include_shared` args) to opt in for a query, or set the defaults in
-> your `mode_a/b/c.json` config. See [docs/shared-memory.md](../../../docs/shared-memory.md).
+Flags that do **not** exist on `slm recall`: `--min-score`, `--format`,
+`--tags` (the flag is the repeatable `--tag`).
 
-**Flags that do NOT exist** (fabricated in old skills — never write these):
-`--min-score`, `--format`, `--project`, `--tags` on recall or search.
+Recall returns only this profile's own memories unless you pass
+`--include-global` / `--include-shared` (or the MCP `include_global` /
+`include_shared` arguments), or the user has set the defaults in their
+configuration. See [docs/shared-memory.md](../../../docs/shared-memory.md).
 
 ---
 
@@ -294,7 +389,7 @@ trusts that what you surface came from the store.
 
 ---
 
-## Multi-scope retrieval (v3.6.15+, opt-in)
+## Shared and global memories (opt-in)
 
 By default `recall` returns only memories in the active profile (personal scope).
 To also surface memories shared from other profiles, pass the scope flags:
@@ -313,11 +408,13 @@ to see shared or global facts. See `slm-scope` for the full sharing model.
 
 ---
 
-## Profile-aware retrieval (v3.8.0+)
+## Profile-aware retrieval
 
-`recall` always queries the currently active profile. To query a different
-workspace, use `switch_profile` (requires `code`, `full`, or `power` MCP profile)
-before recalling, then switch back. See `slm-profile` for workspace switching.
+`recall` queries the active profile. To read another existing profile for one
+call, pass `profile_id="<name>"` (the active profile is not moved). The
+`switch_profile` tool changes the active profile for every later call and for
+other sessions on this machine, so reserve it for when the user asks to move.
+See `slm-profile`.
 
 ---
 
@@ -330,4 +427,4 @@ before recalling, then switch back. See `slm-profile` for workspace switching.
 
 ---
 
-*SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.23 · Qualixar · AGPL-3.0-or-later*

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

@@ -8,7 +8,7 @@ when_to_use: |
   - "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
+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
@@ -39,9 +39,14 @@ sessions. One fact per call. Recall before you remember.
 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.
+- 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.
 
@@ -58,13 +63,19 @@ 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)",
+remember(
+  content="JWT tokens use 1h expiry for API access tokens; refresh tokens 30d",
+  tags="auth,security,decision",
+  project="superlocalmemory",
+  kind="decision",
+  replaces="f8a2bc91",
 )
 ```
 
-`update_memory` returns `{"success": true, "fact_id": "f8a2bc91", "content": "..."}`.
+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
 
@@ -85,12 +96,25 @@ Real response shape:
   "fact_ids": ["c9d4e112"],
   "count": 1,
   "pending": false,
-  "message": "Stored (recallable now; enriching async)."
+  "pending_id": null,
+  "operation_id": "op-7c21",
+  "materialization_state": "complete",
+  "message": "Stored through canonical daemon ingestion."
 }
 ```
 
-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.
+`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.**
 
@@ -104,14 +128,18 @@ remember(
   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"
+  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 (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
+> **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).
 
@@ -147,31 +175,87 @@ event time, so a mis-dated memory is one a time-scoped question cannot find.
 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.
+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. One fact per call
+### 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.
 
-### 6. Always set tags and project
+### 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 via CLI
+## Deleting stale facts
 
-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:
+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)
@@ -189,6 +273,8 @@ Flags verified in source (main.py):
 - `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.
 
 ---
 
@@ -196,13 +282,20 @@ Always run `--dry-run` first and review the preview before passing `--yes`.
 
 ```bash
 # Store a fact
-slm remember "<content>" [--tags a,b,c] [--json]
+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 (v3.6.15, opt-in)
+# Store a shared/global fact (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
+# 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
 ```
@@ -216,14 +309,15 @@ slm remember "<content>" --scope shared --shared-with alice,bob
 
 | 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` |
+| 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` |
 
 ---
 
-## Multi-scope sharing (v3.6.15+, opt-in)
+## 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:
@@ -254,10 +348,13 @@ complete sharing model and when to use each scope.
 
 ---
 
-## Profile-aware storage (v3.8.0+)
+## Profile-aware storage
 
-`remember` always stores in the active profile's namespace. To write to a
-different workspace, use `switch_profile` first. See `slm-profile`.
+`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`.
 
 ---
 
@@ -270,4 +367,4 @@ different workspace, use `switch_profile` first. See `slm-profile`.
 
 ---
 
-*SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.23 · Qualixar · AGPL-3.0-or-later*