@hyperspell/openclaw-hyperspell 0.20.0 → 0.21.1

package/README.md

@@ -149,6 +149,7 @@ files back to Hyperspell.
 | `knowledgeGraph.enabled` | boolean | `false` | Memory Network: extract entities (people, projects, organizations, topics) from memories into `memory/` markdown files. See [Memory Network](#memory-network). |
 | `knowledgeGraph.scanIntervalMinutes` | number | `60` | Extraction cadence the setup wizard bakes into the cron job it creates. The cron job is the runtime source of truth — to change cadence after setup, edit the cron job (and keep this field in sync). |
 | `knowledgeGraph.batchSize` | number | `20` | Memories per extraction scan batch |
+| `coverageLog` | boolean | `false` | **Opt-in.** Append a local-only JSONL event whenever auto-context finds no relevant memories, so capture gaps can be told apart from ranking misses. Events include prompt text — see [Coverage log](#coverage-log). |
 | `debug` | boolean | `false` | Enable diagnostic logging. One-line diagnostics (auto-context ranked/cut/injection summaries, orientation and emotional-context injection counts) are emitted at **info** level, so they appear in `gateway.log` at default host log levels — no host `logging.level` change needed. Verbose output (per-request/response dumps, per-candidate score lines) stays at debug level. |
 | `dreaming.enabled` | boolean | `false` | Allow `memory-core` to sidecar-load so Dreaming can consolidate local session transcripts into `workspace/MEMORY.md`. See [Running alongside Dreaming](#running-alongside-dreaming). |
 
@@ -271,6 +272,61 @@ composite = relevance
 Chatter is additionally capped at `chatterQuota` results per injection,
 regardless of score.
 
+Provenance is a signal too: an optional `sourceWeights` map multiplies a
+result's **base relevance** (before the kind boosts/penalties are added) by a
+per-source factor, so "a journaled Notion page is more intentional memory than
+a titled Slack aside on the same topic" is expressible. Any source not listed
+— including sources that don't exist yet — is neutral (`1.0`); the shipped
+default is `{}`, a strict no-op. It weights sources already in the result set;
+to *exclude* a source, use the `sources` filter instead (weights of 0 are
+rejected at load with exactly that pointer). Suggested starting points, priors
+to seed your own tuning rather than measured truth: authored systems slightly
+up (`notion` 1.15, drive/box/dropbox 1.1), conversational exhaust slightly
+down (`slack`/`microsoft_teams` 0.85, `trace` 0.8) — magnitudes small enough
+to break ties, never to override a real relevance gap. Typos in weight keys
+are not schema errors (new backend sources must not fail validation); with
+`debug: true` unknown keys are flagged once at startup in `gateway.log`.
+
+Selected results are also checked against each other for **near-duplicates**:
+when the same memory exists in several forms (a re-synced doc section, a
+`remember` note quoting it, a curated copy of a hot-buffer row), every copy
+clears the threshold, none is chatter, and pre-dedup they filled multiple
+injection slots with one piece of information. Each candidate's lead text is
+compared against already-selected results by token overlap; above
+`dedupThreshold` (0.8) the copy is skipped and its slot passes to the
+next-ranked *different* memory. Skipped copies never consume the chatter
+quota. Set `dedupThreshold: 0` to disable. Paraphrased duplicates (same fact,
+different words) are beyond a string measure and out of scope.
+
+Within each selected memory, the second excerpt earns its place: a result
+renders up to two highlight bullets, and the runner-up rides along only when
+its score is within 0.15 of the top one's — a .95/.40 pair renders one bullet
+(the distant second is usually a weaker paraphrase), a .95/.85 pair renders
+both. The top highlight is always kept, so a selected memory never disappears
+from the injection because of this rule.
+
+An optional **elbow cutoff** (`ranking.elbow`, **off by default**) stops
+injecting at a natural score cliff instead of always filling `maxResults`: a
+narrow query backed by 3 genuinely relevant memories no longer pads the
+context with a plateau of marginal ones that happen to clear the threshold.
+It is strictly conservative — it only ever cuts *earlier*, never later, never
+below `minResults` (default 3), and when no clear cliff exists (gradual
+decline, flat plateau) selection is identical to today. A cliff means the
+drop from the last accepted result is both large against the decline seen so
+far (`gapRatio` × mean gap, default 2.5×) *and* material in absolute terms
+(`minGap`, default 0.05). Before enabling, run
+`node --experimental-strip-types docs/elbow-scan.mjs` against your real data
+to check firing rate and cut depth (with `debug: true` the live verdict shows
+in `gateway.log` as `auto-context: elbow stopped at k (ceiling N)`).
+
+Age matters too, gently: results accrue a small **recency penalty** that grows
+with age (exponential decay, 90-day half-life by default) and is hard-capped at
+`recencyMaxPenalty` (0.1) so it can break near-ties toward current information
+but never bury a strong old match. Deliberately-kept memory (curated/story)
+ages at half rate (`recencyCuratedFactor`) — an old truth you chose to keep
+still beats a fresh shallow echo. Results without a timestamp are never
+penalized. Set `recencyHalfLifeDays: 0` to disable.
+
 **`storyBoost` does nothing until you set `storyTerms`.** The default is `[]`,
 so no result ever classifies as "story". Set it to the distinctive proper nouns
 of your active work — the title, character names, a project codename, invented
@@ -313,7 +369,7 @@ Tips:
   The `hyperspell_search` tool and `/getcontext` return raw relevance order —
   don't test `storyTerms` there and conclude it's broken.
 - To verify it's working, enable `debug: true` and watch `gateway.log` for the
-  per-search tally (`auto-context: ranked {...} candidates → selected {...}`) —
+  per-search tally (`auto-context: ranked {...} candidates → selected {...}`) and the cut tally (threshold / max-results / elbow / near-duplicate / chatter-quota) —
   it appears at default host log levels. The per-candidate lines
   (`[story] 0.47→0.82 The Lighthouse Keeper — Chapter 3`), which show story
   matches even when they lose to the threshold, are debug-level and also need
@@ -329,10 +385,34 @@ Full knobs and defaults:
   "storyBoost": 0.15,       // extra lift for storyTerms matches (stacks with curationBoost)
   "storyTerms": [],         // REQUIRED for storyBoost to do anything
   "candidateMultiplier": 3, // fetch this × maxResults candidates before re-ranking
-  "chatterQuota": 2         // hard cap on chatter results per injection
+  "chatterQuota": 2,        // hard cap on chatter results per injection
+  "recencyHalfLifeDays": 90,  // age at which half the recency penalty has accrued (0 = off)
+  "recencyMaxPenalty": 0.1,   // ceiling on the recency penalty — a tiebreaker, never a burial
+  "recencyCuratedFactor": 0.5, // kept memory (curated/story) ages at this fraction of the rate
+  "sourceWeights": {},        // per-source multiplier on base relevance; unlisted = 1.0
+  "dedupThreshold": 0.8,      // token-overlap ratio that skips a near-duplicate (0 = off)
+  "elbow": {                  // stop early at a natural score cliff (opt-in)
+    "enabled": false,
+    "minResults": 3,          // never cut below this many accepted results
+    "gapRatio": 2.5,          // cliff = drop >= this multiple of the mean gap so far...
+    "minGap": 0.05            // ...AND at least this big on the raw composite scale
+  }
 }
 ```
 
+### Coverage log
+
+No ranking tweak can surface a memory that was never captured — and by default nothing distinguishes "ranking failed" from "it was never stored." With `coverageLog: true`, every auto-context turn that injects **no** memory sections appends one line to `<workspaceDir>/.hyperspell-coverage.jsonl`:
+
+- `outcome: "empty"` — the search succeeded but returned zero candidates (a capture question: was this ever stored?)
+- `outcome: "below_threshold"` — candidates existed but none cleared `relevanceThreshold`; `topScore` vs `threshold` says how near the miss was (a ranking question)
+
+Failed searches never produce events — backend-unavailable is not "no memories." In multi-user mode there is one event per turn with per-lane detail, and a lane whose search failed is recorded as `status: "error"`, never as zero candidates.
+
+**Local-only guarantee:** the log is written only to the workspace directory and is never sent to Hyperspell or anywhere remote. Because each event carries the triggering prompt (truncated to 500 chars), the feature is **off by default** — prompt text reaches disk only if you explicitly opt in. The file is capped at 5 MB with one `.old` rotation generation (~10 MB total), so content ages out instead of accumulating.
+
+Review with `jq`, e.g.: `jq -r '[.ts, .outcome, .topScore, .prompt] | @tsv' ~/.openclaw/workspace/.hyperspell-coverage.jsonl` — after a week or two of labeling (capture gap / ranking near-miss / correct absence), the tallies say whether the next investment belongs in capture or ranking. Delete the file when done.
+
 ### `excludeChannels` is forward-only
 
 Adding a channel to `excludeChannels` stops all future injection/writes/tools for that conversation, but does **not** remove content that was synced before the channel was quarantined.

package/dist/commands/preview.js

@@ -3,7 +3,7 @@ import { gatherOrientation, personalUserId } from "../hooks/startup-orientation.
 import { isExcludedChannel } from "../lib/exclude-channels.js";
 import { log } from "../logger.js";
 /**
- * Assemble a read-only report of what before_agent_start WOULD inject at the
+ * Assemble a read-only report of what the injection hook WOULD inject at the
  * start of the next session. Calls only the pure fetch/format functions the
  * real hooks are composed from — never the hook handlers themselves — so it
  * cannot touch the inject-once session caches, and it never calls rollMood
@@ -12,7 +12,7 @@ import { log } from "../logger.js";
  */
 export async function buildPreviewReport(client, cfg, ctx) {
     // Quarantined channels get no injected memory of any kind (index.ts guards
-    // before_agent_start with the same check) — report that instead of a bundle.
+    // the injection hook with the same check) — report that instead of a bundle.
     if (isExcludedChannel({ channelId: ctx.channel }, cfg)) {
         return "This channel is quarantined (excludeChannels): no context would be injected here and no memory would be written.";
     }

package/dist/commands/setup.js

@@ -293,6 +293,7 @@ async function runSetup() {
                 maxResults: 10,
                 relevanceThreshold: 0.6,
                 ranking: DEFAULT_RANKING,
+                coverageLog: false,
                 debug: false,
                 knowledgeGraph: { enabled: false, scanIntervalMinutes: 60, batchSize: 20 },
                 startupOrientation: {

package/dist/config.js

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { DEFAULT_RANKING } from "./lib/ranking.js";
+import { DEFAULT_ELBOW, DEFAULT_RANKING, } from "./lib/ranking.js";
 /**
  * Convert user-facing scope names (which may contain hyphens) to SDK-safe
  * metadata values (alphanumeric + underscore only). Must be applied at every
@@ -27,12 +27,13 @@ const ALLOWED_KEYS = [
     "maxResults",
     "relevanceThreshold",
     "ranking",
+    "coverageLog",
     "debug",
     "knowledgeGraph",
     "multiUser",
     "dreaming",
 ];
-const VALID_SOURCES = [
+export const VALID_SOURCES = [
     "reddit",
     "notion",
     "slack",
@@ -95,6 +96,27 @@ function parseWatchPaths(raw) {
         };
     });
 }
+/** Per-source multipliers: non-numeric values silently skip (num()'s
+ * convention); explicit non-positive values throw (a 0 weight is a filtering
+ * decision wearing a weighting costume — the sources filter is the right
+ * tool, and the error says so). Keys lowercase but are NOT validated against
+ * VALID_SOURCES: the backend adds sources independently of plugin releases,
+ * and an unmatched key is a harmless neutral no-op (startup diag logs it). */
+function parseSourceWeights(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (typeof v !== "number")
+            continue;
+        if (!Number.isFinite(v) || v <= 0) {
+            throw new Error(`ranking.sourceWeights.${k} must be a positive number (got ${v}); ` +
+                `to exclude a source entirely, use the "sources" filter instead`);
+        }
+        out[k.trim().toLowerCase()] = v;
+    }
+    return out;
+}
 function parseRanking(raw) {
     const r = (raw ?? {});
     const num = (v, d) => (typeof v === "number" ? v : d);
@@ -116,6 +138,24 @@ function parseRanking(raw) {
             : DEFAULT_RANKING.storyTerms,
         candidateMultiplier: Math.max(1, num(r.candidateMultiplier, DEFAULT_RANKING.candidateMultiplier)),
         chatterQuota: Math.max(0, num(r.chatterQuota, DEFAULT_RANKING.chatterQuota)),
+        recencyHalfLifeDays: Math.max(0, num(r.recencyHalfLifeDays, DEFAULT_RANKING.recencyHalfLifeDays)),
+        recencyMaxPenalty: Math.max(0, num(r.recencyMaxPenalty, DEFAULT_RANKING.recencyMaxPenalty)),
+        recencyCuratedFactor: Math.min(1, Math.max(0, num(r.recencyCuratedFactor, DEFAULT_RANKING.recencyCuratedFactor))),
+        sourceWeights: parseSourceWeights(r.sourceWeights),
+        dedupThreshold: Math.min(1, Math.max(0, num(r.dedupThreshold, DEFAULT_RANKING.dedupThreshold))),
+        elbow: parseElbow(r.elbow),
+    };
+}
+function parseElbow(raw) {
+    const e = (raw ?? {});
+    const num = (v, d) => (typeof v === "number" ? v : d);
+    return {
+        enabled: e.enabled ?? DEFAULT_ELBOW.enabled,
+        // >= 2: at least one gap must exist before meanGap is defined (the
+        // first accepted result never records a gap).
+        minResults: Math.max(2, num(e.minResults, DEFAULT_ELBOW.minResults)),
+        gapRatio: Math.max(1, num(e.gapRatio, DEFAULT_ELBOW.gapRatio)),
+        minGap: Math.max(0, num(e.minGap, DEFAULT_ELBOW.minGap)),
     };
 }
 function parseSources(raw) {
@@ -376,6 +416,10 @@ export function parseConfig(raw) {
         maxResults: cfg.maxResults ?? 10,
         relevanceThreshold: cfg.relevanceThreshold ?? 0.6,
         ranking: parseRanking(cfg.ranking),
+        // Default OFF (deviates from proposal 15 §6 by maintainer decision):
+        // coverage events carry prompt text, so nothing is written to disk
+        // unless the operator explicitly opts in.
+        coverageLog: cfg.coverageLog ?? false,
         debug: cfg.debug ?? false,
         knowledgeGraph: {
             enabled: kgRaw.enabled ?? false,

package/dist/hooks/auto-context.js

@@ -2,6 +2,7 @@ import { appendFileSync } from "node:fs";
 import { buildScopeFilter, getCanReadScopes, resolveUser, } from "../lib/sender.js";
 import { excludeFilterFor, mergeWithExclude } from "../lib/filters.js";
 import { explainSelection, kindTally, rerank, } from "../lib/ranking.js";
+import { recordCoverageEvent, } from "../lib/coverage-log.js";
 import { classifySearchError, logSearchError } from "../lib/search-error.js";
 import { resolveCurrentSessionId } from "../lib/session.js";
 import { recordSender, senderIdFromCtx } from "../lib/speaker-tracker.js";
@@ -54,22 +55,38 @@ function formatHighlightBullets(results, maxResults, threshold) {
         return null;
     return sections.join("\n\n");
 }
+// A second highlight rides along only when it is within this much of the top
+// one's score — a distant second is dilution inside a correct pick (proposal
+// 12). Absolute difference (not a ratio) to match every other score rule in
+// this pipeline; 0.15 is "one storyBoost's worth" on the composite scale.
+// Deliberately a constant, not config: a formatting heuristic two levels
+// below anything a user reasons about — promote to ranking.highlightGap only
+// if live tuning proves deployments actually differ.
+const HIGHLIGHT_GAP = 0.15;
 /**
  * Format already-SELECTED composite-ranked results (threshold + chatter quota
  * applied upstream by selectRanked). Highlights are floored at the lower of
  * (threshold, the result's own base relevance), so we don't hide the very lines
- * that define a boosted-but-quiet memory.
+ * that define a boosted-but-quiet memory. Exported for direct testing.
  */
-function formatSelected(selected, threshold) {
+export function formatSelected(selected, threshold) {
     const sections = [];
     for (const r of selected) {
         const hiFloor = Math.min(threshold, r._base);
-        const chosen = [...r.highlights]
+        const passing = [...r.highlights]
             .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
-            .filter((h) => (h.score ?? 0) >= hiFloor)
-            .slice(0, 2);
-        if (chosen.length === 0)
+            .filter((h) => (h.score ?? 0) >= hiFloor);
+        if (passing.length === 0)
             continue;
+        // Floor first (is this highlight relevant at all?), gap second (is the
+        // runner-up close enough to the winner to be worth its tokens?). The TOP
+        // highlight is always kept — the lowered hiFloor exists to protect
+        // boosted-but-quiet memories, and the gap rule must never re-hide them; a
+        // selected result can never format to fewer sections than today.
+        const [top, second] = passing;
+        const chosen = second && (top.score ?? 0) - (second.score ?? 0) <= HIGHLIGHT_GAP
+            ? [top, second]
+            : [top];
         const title = r.title ?? `[${r.source}]`;
         const bullets = chosen
             .map((h) => `- ${h.text.replace(/\n/g, " ")} [${Math.round((h.score ?? 0) * 100)}%]`)
@@ -168,7 +185,12 @@ export function dropCurrentSession(results, currentSessionId) {
     }
     return kept;
 }
-export function buildAutoContextHandler(client, cfg) {
+/** Highest raw relevance among candidates — `topScore 0.54` vs `threshold 0.6`
+ * is a ranking near-miss; `0.12` means the vault has nothing close (capture). */
+function topScoreOf(results) {
+    return results.length ? Math.max(...results.map((r) => r.score ?? 0)) : null;
+}
+export function buildAutoContextHandler(client, cfg, opts) {
     return async (event, ctx) => {
         const prompt = event.prompt;
         if (!prompt || prompt.length < 5)
@@ -184,7 +206,7 @@ export function buildAutoContextHandler(client, cfg) {
         // Multi-user path
         if (cfg.multiUser) {
             const resolved = resolveUser(ctx, cfg);
-            return multiUserSearch(client, cfg, prompt, resolved, currentSessionId);
+            return multiUserSearch(client, cfg, prompt, resolved, currentSessionId, opts?.stateRoot);
         }
         // Single-user path — preserves main's highlights + threshold behavior
         log.debug(`auto-context: searching for "${prompt.slice(0, 50)}..."`);
@@ -195,13 +217,19 @@ export function buildAutoContextHandler(client, cfg) {
             const limit = ranking.enabled
                 ? cfg.maxResults * ranking.candidateMultiplier
                 : cfg.maxResults;
-            const results = dropCurrentSession(await client.search(prompt, { limit, filter: excludeFilterFor(cfg) }), currentSessionId);
+            // Kept as two steps so the coverage event below can report the pre-drop
+            // fetch count (a session-echo-dominated pool must be visible as such).
+            const rawResults = await client.search(prompt, {
+                limit,
+                filter: excludeFilterFor(cfg),
+            });
+            const results = dropCurrentSession(rawResults, currentSessionId);
             let formatted;
             if (ranking.enabled) {
                 const ranked = rerank(results, ranking);
                 // Threshold + chatter quota applied here, so a high-similarity echo can
                 // inform but never flood (the quota bounds count; the penalty bounds rank).
-                const explained = explainSelection(ranked, cfg.maxResults, cfg.relevanceThreshold, ranking.chatterQuota);
+                const explained = explainSelection(ranked, cfg.maxResults, cfg.relevanceThreshold, ranking.chatterQuota, ranking.dedupThreshold, ranking.elbow);
                 logScoreSamples(prompt, currentSessionId, "single", explained, cfg.relevanceThreshold);
                 const selected = explained.filter((e) => e.selected).map((e) => e.result);
                 // Candidates → selected kind tally, logged UNCONDITIONALLY (unlike the
@@ -217,6 +245,11 @@ export function buildAutoContextHandler(client, cfg) {
                 // nothing is injected (e.g. chatterQuota 0 with only chatter clearing
                 // the threshold). Stable "auto-context: cut" prefix for log greps.
                 // flatMap (not filter) so TS narrows to the cut member of the union.
+                // Elbow verdict — the live-validation instrument for proposal 13's
+                // rollout: firing rate + cut depth come straight from this line.
+                if (ranking.elbow.enabled && explained.some((e) => e.cut === "elbow")) {
+                    log.diag(`auto-context: elbow stopped at ${selected.length} (ceiling ${cfg.maxResults})`);
+                }
                 const cuts = explained.flatMap((e) => (e.selected ? [] : [e]));
                 if (cuts.length > 0) {
                     const cutTally = cuts.reduce((acc, e) => ((acc[e.cut] = (acc[e.cut] ?? 0) + 1), acc), {});
@@ -241,6 +274,23 @@ export function buildAutoContextHandler(client, cfg) {
             // every-turn banner (which reads as framing and trains search-as-ritual).
             if (!formatted) {
                 log.debug("auto-context: no relevant memories found");
+                // Coverage signal (proposal 15): search SUCCEEDED but injected nothing —
+                // durably distinguish "never captured" (empty) from "captured but ranked
+                // out" (below_threshold). Thrown searches never reach here (the catch
+                // below owns them), so availability blips can't pollute the log.
+                if (cfg.coverageLog) {
+                    recordCoverageEvent({
+                        outcome: results.length > 0 ? "below_threshold" : "empty",
+                        prompt,
+                        fetched: rawResults.length,
+                        candidates: results.length,
+                        droppedCurrentSession: rawResults.length - results.length,
+                        topScore: topScoreOf(results),
+                        threshold: cfg.relevanceThreshold,
+                        ranking: ranking.enabled,
+                        sessionId: currentSessionId,
+                    }, opts?.stateRoot);
+                }
                 return;
             }
             return { prependContext: wrapContext(formatted) };
@@ -259,7 +309,7 @@ export function buildAutoContextHandler(client, cfg) {
 // single-user path only: this path never runs rerank/explainSelection, so
 // there is no composite score to attribute. If ranking ever lands here, call
 // logScoreSamples with scope "personal" / "shared" per search.
-async function multiUserSearch(client, cfg, prompt, resolved, currentSessionId) {
+async function multiUserSearch(client, cfg, prompt, resolved, currentSessionId, stateRoot) {
     const multiUser = cfg.multiUser;
     const isKnownSender = !!resolved?.resolved;
     const includeShared = multiUser.includeSharedInSearch;
@@ -297,9 +347,18 @@ async function multiUserSearch(client, cfg, prompt, resolved, currentSessionId)
     let idx = 0;
     let personalResults = [];
     let sharedResults = [];
+    // Per-lane fulfillment + pre-drop counts feed the coverage event below: a
+    // lane that REJECTED must never be recorded as "zero candidates" (#39's
+    // unavailable-is-not-empty distinction, kept intact in the log schema).
+    let personalOk = false;
+    let sharedOk = false;
+    let rawPersonalCount = 0;
+    let rawSharedCount = 0;
     if (personalSearch) {
         const r = settled[idx++];
         if (r.status === "fulfilled") {
+            personalOk = true;
+            rawPersonalCount = r.value.length;
             personalResults = dropCurrentSession(r.value, currentSessionId);
         }
         else {
@@ -309,6 +368,8 @@ async function multiUserSearch(client, cfg, prompt, resolved, currentSessionId)
     if (sharedSearch) {
         const r = settled[idx++];
         if (r.status === "fulfilled") {
+            sharedOk = true;
+            rawSharedCount = r.value.length;
             sharedResults = dropCurrentSession(r.value, currentSessionId);
         }
         else {
@@ -342,6 +403,49 @@ async function multiUserSearch(client, cfg, prompt, resolved, currentSessionId)
     const haveMemorySections = sections.some((s) => s.startsWith("<personal-context>") || s.startsWith("<shared-context>"));
     if (!haveMemorySections) {
         log.debug("auto-context: no relevant memories found");
+        // Coverage signal (proposal 15): one event per turn (not per lane), with
+        // per-lane detail so "personal lane was down" is never misread as
+        // "personal memory is empty". Written only when at least one lane
+        // fulfilled — every-lane-failed is an availability event (#39), already
+        // logged by logSearchError above, and "unknown" is not "zero".
+        if (cfg.coverageLog) {
+            const lanes = [];
+            if (personalSearch)
+                lanes.push(personalOk
+                    ? {
+                        lane: "personal",
+                        status: "ok",
+                        candidates: personalResults.length,
+                        topScore: topScoreOf(personalResults),
+                    }
+                    : { lane: "personal", status: "error" });
+            if (sharedSearch)
+                lanes.push(sharedOk
+                    ? {
+                        lane: "shared",
+                        status: "ok",
+                        candidates: sharedResults.length,
+                        topScore: topScoreOf(sharedResults),
+                    }
+                    : { lane: "shared", status: "error" });
+            if (lanes.some((l) => l.status === "ok")) {
+                const candidates = personalResults.length + sharedResults.length;
+                const fetched = rawPersonalCount + rawSharedCount;
+                recordCoverageEvent({
+                    outcome: candidates > 0 ? "below_threshold" : "empty",
+                    prompt,
+                    fetched,
+                    candidates,
+                    droppedCurrentSession: fetched - candidates,
+                    topScore: topScoreOf([...personalResults, ...sharedResults]),
+                    threshold: cfg.relevanceThreshold,
+                    ranking: cfg.ranking.enabled,
+                    sessionId: currentSessionId,
+                    userId: resolved?.userId,
+                    lanes,
+                }, stateRoot);
+            }
+        }
         if (isKnownSender && resolved) {
             const contextLine = resolved.context ? ` ${resolved.context}` : "";
             return {

package/dist/hooks/emotional-state.js

@@ -58,7 +58,7 @@ const sessionMoods = new Map();
  * hundred tokens of repeated wrapper per turn.
  *
  * Lifecycle:
- *  - first before_agent_start in a session: fetch, inject, mark.
+ *  - first injection-hook fire in a session: fetch, inject, mark.
  *  - subsequent turns in same session: skip (return undefined).
  *  - after_compaction: clear the mark so the next turn re-injects (the
  *    initial injection may have been compacted out of history).
@@ -185,7 +185,7 @@ export function buildEmotionalContext(states) {
  * context. On later turns of the same session, return undefined — the
  * injection from the first turn is already in the conversation history.
  *
- * Runs on `before_agent_start` (which fires every turn).
+ * Runs on the session injection hook (fires every turn).
  */
 export function buildEmotionalStateFetchHandler(client, cfg, deps = {}) {
     const now = deps.now ?? Date.now;

package/dist/hooks/memory-sync.js

@@ -1,3 +1,4 @@
+import * as fs from "node:fs";
 import * as path from "node:path";
 import { getWorkspaceDir } from "../config.js";
 import { log } from "../logger.js";
@@ -128,6 +129,64 @@ export function buildFileSyncHandler(client, cfg) {
         }
     };
 }
+/**
+ * Plugin-owned file watcher feeding the file-sync handler.
+ *
+ * OpenClaw 2026.7.2 removed the host `file_changed` hook with no replacement,
+ * so live sync must come from the plugin itself. Used on EVERY host version
+ * (old hosts still expose `file_changed`, but registering both would
+ * double-sync) — one canonical path. Events are forwarded in the old hook's
+ * `{ file_path }` shape; the handler already owns syncability filtering and
+ * debounce, so the watcher stays dumb.
+ */
+export function buildMemorySyncWatcher(cfg, onFileChanged) {
+    const workspaceDir = getWorkspaceDir();
+    const roots = [
+        path.join(workspaceDir, "memory"),
+        ...(cfg.syncMemoriesConfig.watchPaths ?? []).map((wp) => resolveWatchPath(workspaceDir, wp.path)),
+    ];
+    const watchers = [];
+    const start = () => {
+        let watched = 0;
+        for (const root of roots) {
+            let isDirectory;
+            try {
+                isDirectory = fs.statSync(root).isDirectory();
+            }
+            catch {
+                log.debug(`memory-sync watcher: root missing, skipping: ${root}`);
+                continue;
+            }
+            // Watching a file directly breaks on editor rename-replace cycles;
+            // watch the parent and filter to the file's own events instead.
+            const dir = isDirectory ? root : path.dirname(root);
+            try {
+                const watcher = fs.watch(dir, { recursive: isDirectory }, (_type, filename) => {
+                    if (!filename)
+                        return;
+                    const filePath = path.join(dir, filename.toString());
+                    if (!isDirectory && filePath !== root)
+                        return;
+                    onFileChanged({ file_path: filePath });
+                });
+                watchers.push(watcher);
+                watched += 1;
+            }
+            catch (err) {
+                log.error(`memory-sync watcher failed for ${dir}`, err);
+            }
+        }
+        if (watched > 0) {
+            log.info(`memory-sync: watching ${watched} root(s) with plugin-owned watchers`);
+        }
+    };
+    const stop = () => {
+        for (const watcher of watchers)
+            watcher.close();
+        watchers.length = 0;
+    };
+    return { start, stop };
+}
 /**
  * Sync all existing memory files on startup.
  * Uses section-level sync when sectionize is enabled.

package/dist/hooks/startup-orientation.js

@@ -194,7 +194,7 @@ async function fetchRecentConversations(client, limit, userId) {
 }
 /**
  * The fetch+format core of startup orientation, shared by the real
- * before_agent_start handler and the read-only /previewcontext command.
+ * session-start injection handler and the read-only /previewcontext command.
  * Pure with respect to session lifecycle: no inject-once cache, no retry
  * counting — callers own that policy. Keeping one formatter here keeps the
  * preview byte-identical to real injection.
@@ -207,7 +207,7 @@ export async function gatherOrientation(client, cfg, userId) {
     // off agents). Fall back to agent_end traces only when there's no hot
     // buffer but auto-trace is on. Otherwise skip: there's nothing to fetch,
     // and the trace-source list is expensive (observed ~12s + failing/turn),
-    // blocking before_agent_start and slowing the reply.
+    // blocking the injection hook and slowing the reply.
     const recentSource = cfg.hotBuffer.enabled
         ? "hotBuffer"
         : cfg.autoTrace.enabled

package/dist/index.js

@@ -1,11 +1,11 @@
 import { HyperspellClient } from "./client.js";
 import { registerCommands } from "./commands/slash.js";
 import { registerCliCommands } from "./commands/setup.js";
-import { parseConfig, hyperspellConfigSchema, getWorkspaceDir } from "./config.js";
+import { parseConfig, hyperspellConfigSchema, getWorkspaceDir, VALID_SOURCES } from "./config.js";
 import { buildAutoContextHandler } from "./hooks/auto-context.js";
 import { buildAutoTraceHandler } from "./hooks/auto-trace.js";
 import { buildEmotionalStateCompactionHandler, buildEmotionalStateFetchHandler, buildEmotionalStateSessionCleanupHandler, buildEmotionalStateStoreHandler, } from "./hooks/emotional-state.js";
-import { buildFileSyncHandler, syncMemoriesOnStartup } from "./hooks/memory-sync.js";
+import { buildFileSyncHandler, buildMemorySyncWatcher, syncMemoriesOnStartup, } from "./hooks/memory-sync.js";
 import { buildHotBufferHandler, buildHotBufferSessionCleanupHandler, } from "./hooks/hot-buffer.js";
 import { buildStartupOrientationCompactionHandler, buildStartupOrientationHandler, buildStartupOrientationSessionCleanupHandler, } from "./hooks/startup-orientation.js";
 import { isExcludedChannel } from "./lib/exclude-channels.js";
@@ -79,10 +79,17 @@ export default {
         }
         const cfg = parseConfig(api.pluginConfig);
         initLogger(api.logger, cfg.debug);
+        // sourceWeights keys are deliberately not schema-validated (new backend
+        // sources must not fail manifest validation), so a typo is a silent
+        // neutral no-op — surface it once at startup instead.
+        const unknownWeightKeys = Object.keys(cfg.ranking.sourceWeights).filter((k) => !VALID_SOURCES.includes(k));
+        if (unknownWeightKeys.length > 0) {
+            log.diag(`ranking.sourceWeights keys not in the known source list (typo? they weight nothing): ${unknownWeightKeys.join(", ")}`);
+        }
         const client = new HyperspellClient(cfg);
         // Channel quarantine (cfg.excludeChannels): excluded conversations get no
         // memory surface in either direction. Guard the shared choke points here —
-        // before_agent_start (all injection), agent_end (all writes), and the tool
+        // the injection hook (all injection), agent_end (all writes), and the tool
         // factories — so individual hooks stay quarantine-unaware.
         const quarantined = (ctx) => {
             if (!isExcludedChannel(ctx, cfg))
@@ -130,8 +137,19 @@ export default {
             api.on("after_compaction", buildStartupOrientationCompactionHandler());
             api.on("session_end", buildStartupOrientationSessionCleanupHandler());
         }
+        // Injection hook selection: OpenClaw 2026.7.2 removed the plugin-facing
+        // `before_agent_start`; its replacement `agent_turn_prepare` shipped in the
+        // same core commit as `enqueueNextTurnInjection` (openclaw#72287, 2026-04),
+        // so probing that api member tells us exactly which hook this host knows.
+        // Register exactly ONE of the two: cores between 2026-04 and 2026-07
+        // accept both and would double-inject. Both hooks share the same
+        // { prependContext } result contract and provide event.prompt.
+        const injectionHook = typeof api
+            .enqueueNextTurnInjection === "function"
+            ? "agent_turn_prepare"
+            : "before_agent_start";
         if (startHandlers.length > 0) {
-            api.on("before_agent_start", async (event, ctx) => {
+            api.on(injectionHook, async (event, ctx) => {
                 // Quarantined channels get no injected memory of any kind.
                 if (quarantined(ctx))
                     return undefined;
@@ -160,10 +178,16 @@ export default {
             api.on("agent_end", unlessQuarantined(buildHotBufferHandler(client, cfg)));
             api.on("session_end", buildHotBufferSessionCleanupHandler());
         }
-        // Register memory sync hook
+        // Memory sync live watcher. Plugin-owned on every host version:
+        // 2026.7.2 removed the host `file_changed` hook, and on older hosts
+        // registering both paths would double-sync each edit. Started/stopped
+        // by the lifecycle service below.
+        let memorySyncWatcher;
         if (cfg.syncMemories) {
             const fileSyncHandler = buildFileSyncHandler(client, cfg);
-            api.on("file_changed", fileSyncHandler);
+            memorySyncWatcher = buildMemorySyncWatcher(cfg, (event) => {
+                void fileSyncHandler(event);
+            });
             api.logger.info(`hyperspell: memory sync enabled (sectionize=${cfg.syncMemoriesConfig.sectionize}, watchPaths=${cfg.syncMemoriesConfig.watchPaths.length})`);
         }
         // Register memory network tools
@@ -212,8 +236,10 @@ export default {
                         api.logger.error("hyperspell: background memory sync failed", err);
                     });
                 }
+                memorySyncWatcher?.start();
             },
             stop: () => {
+                memorySyncWatcher?.stop();
                 api.logger.info("hyperspell: stopped");
             },
         });