superlocalmemory 4.0.10 → 4.1.2

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

@@ -2,7 +2,7 @@
 name: slm-loop
 description: Run gate-verified bounded loops with SuperLocalMemory as the durable ledger. Use when a task has a checkable acceptance condition (tests, schema, lint, reconciliation) and you must iterate until an INDEPENDENT gate passes — never stopping just because the agent believes it is done. `slm loop demo` runs a keyless convergence demo; `slm loop history` and `slm loop show <run_id>` inspect past runs whose every lap is persisted as queryable SLM memory (tag `loop:<name>`). Terminal statuses are DONE / HALT / PAUSE / KILLED / ERROR — report them exactly, never converting HALT/PAUSE/ERROR into success.
 when_to_use: "run a bounded loop, gate-verified task, iterate until tests pass, verify against an independent gate, don't trust the agent's own done claim, slm loop, convergence loop, loop until green, loop ledger, resume a loop"
-allowed-tools: Bash, slm_recall
+allowed-tools: Bash, recall
 ---
 
 # slm-loop — Bounded, gate-verified agent loops
@@ -96,4 +96,4 @@ paused, name the approval needed; when errored, quote the short detail.
 
 ---
 
-SuperLocalMemory v4.0.10 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.2 · Qualixar · AGPL-3.0-or-later

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

@@ -279,4 +279,4 @@ mesh availability.
 
 ---
 
-*SuperLocalMemory v4.0.10 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.2 · Qualixar · AGPL-3.0-or-later*

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

@@ -30,10 +30,10 @@ project, a client engagement, a production vs staging environment.
 
 | Profile | Tools | When to use |
 |---------|-------|-------------|
-| `core` | 14 tools — remember, recall, search, session, optimize | Minimal footprint, no code tools |
-| `code` | 29 tools — core + portable Brain evidence + code graph + profile switching + bounded loops | Default for IDE/coding agents |
-| `full` | 47 tools — code + all memory ops + mesh + bounded loops | Multi-session, team workflows |
-| `power` | 59 tools — full + governance + behavioral tools | Enterprise, admin, audit use cases |
+| `core` | 18 tools — remember, recall, search, session, optimize | Minimal footprint, no code tools |
+| `code` | 34 tools — core + portable Brain evidence + code graph + profile switching + bounded loops | Default for IDE/coding agents |
+| `full` | 50 tools — code + all memory ops + mesh + bounded loops | Multi-session, team workflows |
+| `power` | 62 tools — full + governance + behavioral tools | Enterprise, admin, audit use cases |
 | `mesh` | 8 tools — mesh coordination only | Lightweight cross-session signalling |
 
 The profile is set at MCP server startup via `SLM_MCP_PROFILE` in the MCP config.
@@ -146,4 +146,4 @@ Name them differently in your MCP config (e.g. `superlocalmemory-personal` and
 
 ---
 
-*SuperLocalMemory v4.0.10 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.2 · Qualixar · AGPL-3.0-or-later*

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

@@ -50,7 +50,7 @@ recall(
   query="authentication strategy decision",
   limit=20,            # default 20; reduce to 5 for quick pre-task checks
   session_id="<sid>",  # pass the session_id returned by session_init
-  fast=False,          # default False; True enables faster, reduced-channel retrieval
+  fast=None,           # leave unset; see "Fast mode" below for what it controls
 )
 ```
 
@@ -65,12 +65,12 @@ Real response shape (`--json` equivalent):
       "score": 0.87,
       "confidence": 0.91,
       "trust_score": 0.84,
-      "fact_type": "decision",
+      "fact_type": "semantic",
       "channel_scores": {
         "semantic": 0.88,
-        "lexical": 0.61,
+        "bm25": 0.61,
         "temporal": 0.72,
-        "structural": 0.55
+        "hopfield": 0.55
       }
     }
   ],
@@ -78,32 +78,92 @@ Real response shape (`--json` equivalent):
   "query_type": "semantic",
   "channel_weights": {
     "semantic": 0.4,
-    "lexical": 0.2,
+    "bm25": 0.2,
     "temporal": 0.2,
-    "structural": 0.2
+    "hopfield": 0.2
   },
+  "channel_status": {
+    "semantic": "ok",
+    "bm25": "ok",
+    "temporal": "empty",
+    "hopfield": "ok",
+    "spreading_activation": "no_candidates",
+    "entity_graph": "no_embedding",
+    "profile": "disabled"
+  },
+  "incomplete_channels": [],
   "retrieval_time_ms": 134,
   "no_confident_match": false
 }
 ```
 
+**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.
+
+| status | meaning |
+|---|---|
+| `ok` | the channel ran and contributed candidates |
+| `empty` | it ran and there was genuinely nothing to return |
+| `no_candidates` | it ran but nothing survived fusion |
+| `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 |
+| `disabled` | switched off by configuration |
+| `not_configured` | the backing service is not set up |
+
+`semantic`, `bm25`, `temporal`, `hopfield` and `spreading_activation` each
+search and return their own candidates. `profile` is a shortcut that runs before
+them and can answer directly. `entity_graph` produces nothing of its own — it
+re-scores what the others found, by how well each result connects to the
+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.
+
 **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 returns fast local results (~1–2s, no server-side LLM round on the hot path) and lets you, the calling model, drive this refinement.
 
 ### 2. Passing session_id
 
-Pass the `session_id` returned by `session_init`. It threads engagement signals
-through to the ranker so each recall contributes to improving retrieval for
-your project over time. Omitting it degrades the learning loop — recall works
-correctly, but feedback is not attributed to the session.
+Pass the `session_id` returned by `session_init`, on **every** recall in that
+session. It does two things.
+
+1. **It carries the conversation forward.** Each recall offers its five
+   best-ranked results to a small per-session working set of seven slots. A
+   memory that keeps coming back is reinforced rather than duplicated, and the
+   least-activated slot is the one evicted, so something referenced across
+   several turns is hard to lose. Later recalls in the same session rank the
+   held memories higher, and turn three is not as cold as turn one. The bias is
+   deliberately small — it nudges the order, it never overrides an exact match.
+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.
+
+**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.
 
 ### 3. Fast mode
 
-Use `fast=True` for pre-tool-call checks where sub-second response matters.
-This enables a faster, reduced-channel mode. Core semantic and keyword channels
-always run; additional graph and contextual channels are skipped.
+`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,
+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.
+
+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
+you do it better than a local model would. Pass `fast=False` only when SLM is
+deployed with no capable client in front of it.
 
 ```
-recall(query="rate limiting approach", limit=5, session_id="<sid>", fast=True)
+recall(query="rate limiting approach", limit=5, session_id="<sid>")
 ```
 
 ### 4. Keyword fallback via search
@@ -138,6 +198,33 @@ once you have the `fact_id` for full content.
 
 ---
 
+### 7. 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.
+
+```
+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",
+)
+```
+
+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.
+
+Report only ids you genuinely used. Reporting every returned id marks the
+irrelevant ones useful and trains the ranker toward noise.
+
+`report_feedback(fact_id, feedback, query)` is the finer-grained form for a
+single fact and the query that surfaced it.
+
+---
+
 ## How multi-channel retrieval works
 
 `recall` runs multiple candidate producers in parallel — semantic vector similarity,
@@ -236,4 +323,4 @@ before recalling, then switch back. See `slm-profile` for workspace switching.
 
 ---
 
-*SuperLocalMemory v4.0.10 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.2 · Qualixar · AGPL-3.0-or-later*

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

@@ -103,8 +103,10 @@ remember(
   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
 )
 ```
 
@@ -121,14 +123,44 @@ remember(
 
 Use 7–10 only for facts that would cause real damage if forgotten.
 
-### 4. One fact per call
+### 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.
 
-### 5. Always set tags and project
+### 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.
@@ -238,4 +270,4 @@ different workspace, use `switch_profile` first. See `slm-profile`.
 
 ---
 
-*SuperLocalMemory v4.0.10 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.2 · Qualixar · AGPL-3.0-or-later*

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

@@ -173,4 +173,4 @@ to review the impact. See `slm-remember` for the full deletion discipline.
 
 ---
 
-*SuperLocalMemory v4.0.10 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.2 · Qualixar · AGPL-3.0-or-later*

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

@@ -121,7 +121,14 @@ remember(content="...", session_id=session_id, tags="auth,decision", project="my
 ```
 
 This attribution is what allows the ranker to learn which recalls led to useful
-outcomes for this project.
+outcomes for this project. It also gives the session a small working set, so
+successive recalls in one conversation build on what the earlier ones surfaced
+instead of each starting cold.
+
+**Do not synthesise a session id.** An id beginning `http:`, `mcp:`, `cli:` or
+`probe:` is read as a synthetic per-request label rather than a conversation and
+is deliberately excluded from that working set. Use the one `session_init`
+returned, unchanged, for the whole session.
 
 ---
 
@@ -177,6 +184,23 @@ never attributed to a project or agent. Over many sessions this compounds:
 projects where lifecycle is respected have measurably better retrieval quality
 than projects where session_init is skipped.
 
+Within a single session it compounds faster. The session's working set holds the
+memories its recalls have already surfaced, and later recalls rank those higher,
+so a long conversation converges on the material it is actually about.
+
+### Closing the loop explicitly
+
+Engagement signals say a memory was *shown*. `report_outcome` says it was
+*right*:
+
+```
+report_outcome(memory_ids="<ids you actually used>", outcome="success")
+```
+
+Send it when a recalled memory changed what you did, and send `failure` when a
+confidently-returned memory turned out to be wrong — that is the only signal
+that stops a stale memory from being promoted. See the `slm-recall` skill.
+
 ---
 
 ## CLI fallback (when MCP is unavailable)
@@ -198,7 +222,9 @@ slm doctor [--json]    # preflight check including daemon and embedding worker
 | Mistake | Consequence | Fix |
 |---------|-------------|-----|
 | Calling `session_init` twice in one session | Two session IDs; signals split across them | Call once; store the returned ID |
-| Omitting `session_id` from `recall` / `remember` | No learning attribution | Always pass the stored `session_id` |
+| Omitting `session_id` from `recall` / `remember` | No learning attribution, and every turn starts cold | Always pass the stored `session_id` |
+| Inventing a `session_id` such as `mcp:agent` or `http:1234` | Read as synthetic, excluded from the working set | Use the id `session_init` returned |
+| Never reporting an outcome | Ranking cannot tell a useful memory from a merely returned one | `report_outcome` after a recall that changed what you did |
 | Never calling `close_session` | Temporal summaries not written | Call at end of each meaningful work unit |
 | Calling `close_session` without a `session_id` when no prior writes exist | Returns error "No session_id found" | Pass the explicit `session_id` from `session_init` |
 
@@ -227,4 +253,4 @@ explicitly and call `recall` with `include_global`/`include_shared` after
 
 ---
 
-*SuperLocalMemory v4.0.10 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.2 · Qualixar · AGPL-3.0-or-later*

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

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

package/plugin-src/rules/AGENTS.md

@@ -80,13 +80,17 @@ When the SLM MCP server is unavailable, use these CLI equivalents:
 
 ---
 
-## Tool reference (core profile — 16 tools)
-
-> The MCP config ships `SLM_MCP_PROFILE=code` and `SLM_AGENT_ID=claude_code` (31 tools):
-> the 16 core memory and correction-review tools below **plus** 6 code-graph tools
-> (`build_code_graph`, `get_blast_radius`, `query_graph`, `semantic_search_code`,
-> `get_review_context`, `detect_changes`) and `switch_profile`.
-> Use `full` (49 tools) to add mesh coordination. Use `power` (61 tools) for governance
+## Tool reference (core profile — 18 tools)
+
+> The MCP config ships `SLM_MCP_PROFILE=code` and `SLM_AGENT_ID=claude_code` (34 tools):
+> the 18 core tools below **plus** 6 code-graph tools (`build_code_graph`,
+> `get_blast_radius`, `query_graph`, `semantic_search_code`, `get_review_context`,
+> `detect_changes`), 5 portable-evidence tools (`get_brain_evidence_status`,
+> `record_agent_experience`, `record_cognitive_turn`, `finalize_cognitive_turn`,
+> `observe_bounded_loop_evidence`), 3 bounded-loop tools (`slm_loop_run`,
+> `slm_loop_history`, `slm_loop_show`) and 2 usefulness reports (`report_outcome`,
+> `report_feedback`).
+> Use `full` (50 tools) to add mesh coordination. Use `power` (62 tools) for governance
 > and audit tools. See slm-profile for profile switching.
 
 | Tool               | Signature (key params)                                                                       | Notes                                  |
@@ -105,6 +109,10 @@ When the SLM MCP server is unavailable, use these CLI equivalents:
 | `slm_cache_set`    | `key, value, ttl_seconds=86400`                                                              | KV cache set                           |
 | `slm_cache_get`    | `key`                                                                                        | KV cache get; returns hit, value       |
 | `slm_optimize_stats` | `()`                                                                                       | Returns compress_runs, tokens_saved_compress, cache_kv_hits |
+| `review_correction` | `case_id, action, expected_version, event_valid_until=None`                                 | Apply, reject or roll back a review-gated correction |
+| `list_corrections` | `limit=100`                                                                                  | Correction cases awaiting review, active profile |
+| `get_memory_summary` | `kind="day", target=""`                                                                    | Readable summary of a day, project or session |
+| `switch_profile`   | `profile_id`                                                                                 | Change the active memory profile; every later call scopes to it |
 
 ## Skills
 
@@ -129,4 +137,4 @@ When the SLM MCP server is unavailable, use these CLI equivalents:
 - **slm-optimize-advisor** — context compression and KV cache
 - **slm-governance-advisor** — scope/role compliance, retention policies, GDPR
 
-SuperLocalMemory v4.0.10 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.2 · Qualixar · AGPL-3.0-or-later

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

@@ -145,4 +145,4 @@ These subcommands control daemon-level cache settings. They do not read or write
 
 ---
 
-SuperLocalMemory v4.0.4 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.2 · Qualixar · AGPL-3.0-or-later

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

@@ -147,4 +147,4 @@ Content over 1 MB (1 000 000 bytes UTF-8) is processed but `reversible` is force
 
 ---
 
-SuperLocalMemory v4.0.4 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.2 · Qualixar · AGPL-3.0-or-later

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

@@ -245,4 +245,4 @@ Before running any destructive operation (`forget`, `compact_memories`):
 
 ---
 
-*SuperLocalMemory v4.0.4 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.2 · Qualixar · AGPL-3.0-or-later*

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

@@ -312,4 +312,4 @@ profile. See `slm-profile` for the full profile switching workflow.
 
 ---
 
-SuperLocalMemory v4.0.4 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.2 · Qualixar · AGPL-3.0-or-later

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

@@ -2,7 +2,7 @@
 name: slm-loop
 description: Run gate-verified bounded loops with SuperLocalMemory as the durable ledger. Use when a task has a checkable acceptance condition (tests, schema, lint, reconciliation) and you must iterate until an INDEPENDENT gate passes — never stopping just because the agent believes it is done. `slm loop demo` runs a keyless convergence demo; `slm loop history` and `slm loop show <run_id>` inspect past runs whose every lap is persisted as queryable SLM memory (tag `loop:<name>`). Terminal statuses are DONE / HALT / PAUSE / KILLED / ERROR — report them exactly, never converting HALT/PAUSE/ERROR into success.
 when_to_use: "run a bounded loop, gate-verified task, iterate until tests pass, verify against an independent gate, don't trust the agent's own done claim, slm loop, convergence loop, loop until green, loop ledger, resume a loop"
-allowed-tools: Bash, slm_recall
+allowed-tools: Bash, recall
 ---
 
 # slm-loop — Bounded, gate-verified agent loops
@@ -96,4 +96,4 @@ paused, name the approval needed; when errored, quote the short detail.
 
 ---
 
-SuperLocalMemory v4.0.4 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.2 · Qualixar · AGPL-3.0-or-later

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

@@ -279,4 +279,4 @@ mesh availability.
 
 ---
 
-*SuperLocalMemory v4.0.4 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.2 · Qualixar · AGPL-3.0-or-later*

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

@@ -30,10 +30,10 @@ project, a client engagement, a production vs staging environment.
 
 | Profile | Tools | When to use |
 |---------|-------|-------------|
-| `core` | 14 tools — remember, recall, search, session, optimize | Minimal footprint, no code tools |
-| `code` | 29 tools — core + portable Brain evidence + code graph + profile switching + bounded loops | Default for IDE/coding agents |
-| `full` | 47 tools — code + all memory ops + mesh + bounded loops | Multi-session, team workflows |
-| `power` | 59 tools — full + governance + behavioral tools | Enterprise, admin, audit use cases |
+| `core` | 18 tools — remember, recall, search, session, optimize | Minimal footprint, no code tools |
+| `code` | 34 tools — core + portable Brain evidence + code graph + profile switching + bounded loops | Default for IDE/coding agents |
+| `full` | 50 tools — code + all memory ops + mesh + bounded loops | Multi-session, team workflows |
+| `power` | 62 tools — full + governance + behavioral tools | Enterprise, admin, audit use cases |
 | `mesh` | 8 tools — mesh coordination only | Lightweight cross-session signalling |
 
 The profile is set at MCP server startup via `SLM_MCP_PROFILE` in the MCP config.
@@ -146,4 +146,4 @@ Name them differently in your MCP config (e.g. `superlocalmemory-personal` and
 
 ---
 
-*SuperLocalMemory v4.0.4 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.2 · Qualixar · AGPL-3.0-or-later*

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

@@ -50,7 +50,7 @@ recall(
   query="authentication strategy decision",
   limit=20,            # default 20; reduce to 5 for quick pre-task checks
   session_id="<sid>",  # pass the session_id returned by session_init
-  fast=False,          # default False; True enables faster, reduced-channel retrieval
+  fast=None,           # leave unset; see "Fast mode" below for what it controls
 )
 ```
 
@@ -65,12 +65,12 @@ Real response shape (`--json` equivalent):
       "score": 0.87,
       "confidence": 0.91,
       "trust_score": 0.84,
-      "fact_type": "decision",
+      "fact_type": "semantic",
       "channel_scores": {
         "semantic": 0.88,
-        "lexical": 0.61,
+        "bm25": 0.61,
         "temporal": 0.72,
-        "structural": 0.55
+        "hopfield": 0.55
       }
     }
   ],
@@ -78,32 +78,92 @@ Real response shape (`--json` equivalent):
   "query_type": "semantic",
   "channel_weights": {
     "semantic": 0.4,
-    "lexical": 0.2,
+    "bm25": 0.2,
     "temporal": 0.2,
-    "structural": 0.2
+    "hopfield": 0.2
   },
+  "channel_status": {
+    "semantic": "ok",
+    "bm25": "ok",
+    "temporal": "empty",
+    "hopfield": "ok",
+    "spreading_activation": "no_candidates",
+    "entity_graph": "no_embedding",
+    "profile": "disabled"
+  },
+  "incomplete_channels": [],
   "retrieval_time_ms": 134,
   "no_confident_match": false
 }
 ```
 
+**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.
+
+| status | meaning |
+|---|---|
+| `ok` | the channel ran and contributed candidates |
+| `empty` | it ran and there was genuinely nothing to return |
+| `no_candidates` | it ran but nothing survived fusion |
+| `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 |
+| `disabled` | switched off by configuration |
+| `not_configured` | the backing service is not set up |
+
+`semantic`, `bm25`, `temporal`, `hopfield` and `spreading_activation` each
+search and return their own candidates. `profile` is a shortcut that runs before
+them and can answer directly. `entity_graph` produces nothing of its own — it
+re-scores what the others found, by how well each result connects to the
+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.
+
 **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 returns fast local results (~1–2s, no server-side LLM round on the hot path) and lets you, the calling model, drive this refinement.
 
 ### 2. Passing session_id
 
-Pass the `session_id` returned by `session_init`. It threads engagement signals
-through to the ranker so each recall contributes to improving retrieval for
-your project over time. Omitting it degrades the learning loop — recall works
-correctly, but feedback is not attributed to the session.
+Pass the `session_id` returned by `session_init`, on **every** recall in that
+session. It does two things.
+
+1. **It carries the conversation forward.** Each recall offers its five
+   best-ranked results to a small per-session working set of seven slots. A
+   memory that keeps coming back is reinforced rather than duplicated, and the
+   least-activated slot is the one evicted, so something referenced across
+   several turns is hard to lose. Later recalls in the same session rank the
+   held memories higher, and turn three is not as cold as turn one. The bias is
+   deliberately small — it nudges the order, it never overrides an exact match.
+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.
+
+**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.
 
 ### 3. Fast mode
 
-Use `fast=True` for pre-tool-call checks where sub-second response matters.
-This enables a faster, reduced-channel mode. Core semantic and keyword channels
-always run; additional graph and contextual channels are skipped.
+`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,
+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.
+
+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
+you do it better than a local model would. Pass `fast=False` only when SLM is
+deployed with no capable client in front of it.
 
 ```
-recall(query="rate limiting approach", limit=5, session_id="<sid>", fast=True)
+recall(query="rate limiting approach", limit=5, session_id="<sid>")
 ```
 
 ### 4. Keyword fallback via search
@@ -138,6 +198,33 @@ once you have the `fact_id` for full content.
 
 ---
 
+### 7. 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.
+
+```
+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",
+)
+```
+
+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.
+
+Report only ids you genuinely used. Reporting every returned id marks the
+irrelevant ones useful and trains the ranker toward noise.
+
+`report_feedback(fact_id, feedback, query)` is the finer-grained form for a
+single fact and the query that surfaced it.
+
+---
+
 ## How multi-channel retrieval works
 
 `recall` runs multiple candidate producers in parallel — semantic vector similarity,
@@ -236,4 +323,4 @@ before recalling, then switch back. See `slm-profile` for workspace switching.
 
 ---
 
-*SuperLocalMemory v4.0.4 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.2 · Qualixar · AGPL-3.0-or-later*