@hyperspell/openclaw-hyperspell 0.18.1 → 0.19.0

package/README.md

@@ -102,6 +102,27 @@ Check your current configuration and connection status.
 
 Open the Hyperspell connect page to link your accounts (Notion, Slack, Google Drive, etc.). After connecting, your sources are automatically updated in the config.
 
+### `openclaw openclaw-hyperspell purge-channel <channelId>`
+
+Find — and with `--yes`, delete — memories that were synced from a specific conversation/channel. Use it for retroactive cleanup after adding a channel to `excludeChannels`, which is [forward-only](#excludechannels-is-forward-only).
+
+```
+openclaw openclaw-hyperspell purge-channel 1521620672726438171          # dry run: list what would be deleted
+openclaw openclaw-hyperspell purge-channel 1521620672726438171 --yes    # actually delete
+```
+
+| Flag | Description |
+|------|-------------|
+| `--source <sources>` | Comma-separated Hyperspell sources to scan. Default `vault` — the hot-buffer consolidation target and default `hotBuffer.source`. |
+| `--user <userId>` | `X-As-User` to scan/delete under. Default: the configured `userId`. In `multiUser` deployments, run once per mapped userId. |
+| `--session <ids>` | Comma-separated OpenClaw session ids — matches legacy **untagged** hot-buffer resources through the `resource_id === session id` identity. |
+| `--resource <ids>` | Explicit resource ids to delete (escape hatch for traces or `/remember` memories you identified manually, e.g. via `hyperspell_search`). |
+| `--yes` | Actually delete. Without it the command is a **dry run** that prints the matches and exits. |
+
+Matching uses the same semantics as the quarantine check itself: exact id or thread suffix (`<channelId>:...`), case-insensitive. Discovery enumerates memories and filters client-side on the `openclaw_channel_id` metadata tag — deleted rows are reported per resource, and a resource that is already gone counts as deleted.
+
+**Finding session ids for `--session`:** OpenClaw session keys embed the conversation id (`agent:<agentId>:<provider>:channel:<channelId>[...]` — the same format the plugin's quarantine matching parses). Look up the quarantined conversation's sessions in OpenClaw's session store and pass their session ids; each hot-buffer resource id equals its session id.
+
 ## Configuration Options
 
 | Option | Type | Default | Description |
@@ -109,9 +130,12 @@ Open the Hyperspell connect page to link your accounts (Notion, Slack, Google Dr
 | `apiKey` | string | `${HYPERSPELL_API_KEY}` | Hyperspell API key |
 | `userId` | string | - | User ID for multi-tenant memory (can be your email) |
 | `autoContext` | boolean | `true` | Auto-inject relevant memories before each AI turn |
+| `emotionalContext` | boolean | `false` | Persist an emotional-state register at session end and inject the recent arc at session start |
+| `moodWeatherChance` | number | `0` | Probability (0–1) that a fresh session rolls exogenous "mood weather". `0` disables. Suggested starting value: `0.03`–`0.05` — rare enough to read as weather, not a gimmick. Requires `emotionalContext`. |
 | `syncMemories` | boolean | `false` | Sync markdown files in `workspace/memory/` to Hyperspell |
 | `sources` | string | - | Comma-separated sources to search (e.g., `vault,notion,slack`) |
 | `maxResults` | number | `10` | Maximum memories per context injection |
+| `excludeChannels` | string[] | `[]` | Conversation/channel ids fully quarantined from memory: no context injection, no memory writes, no memory tools. Threads inherit. **Forward-only** — see [below](#excludechannels-is-forward-only). |
 | `debug` | boolean | `false` | Enable verbose logging |
 | `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). |
 
@@ -141,6 +165,16 @@ Manually sync all markdown files in `workspace/memory/` to Hyperspell.
 /sync
 ```
 
+### `/previewcontext`
+
+Show exactly what Hyperspell would inject at the start of the next session — the emotional-context arc, the auto-context setting, and the startup-orientation blocks — without starting a session or touching any session state. Read-only and idempotent: run it twice and you get the same report.
+
+Mood weather is shown as its configured chance only (e.g. "configured chance 8% per session") and is **never rolled by the preview** — each real session rolls independently at injection time, so the actual mood (if any) is only observable in the live session.
+
+```
+/previewcontext
+```
+
 ## Memory Sync
 
 When `syncMemories: true`, the plugin syncs markdown files from your agent's workspace memory directory (e.g., `~/.openclaw/workspace/memory/`) to Hyperspell. This includes all `.md` files in subdirectories.
@@ -186,6 +220,7 @@ The plugin registers tools that the AI can use autonomously:
 
 - **hyperspell_search** - Search through connected sources
 - **hyperspell_remember** - Save information to memory
+- **hyperspell_emotional_arc** - Re-fetch the recent emotional arc mid-conversation (requires `emotionalContext: true`); returns the same block injected at session start, e.g. after compaction removed it
 
 ## Auto-Context
 
@@ -197,6 +232,17 @@ When `autoContext: true` (default), the plugin automatically:
 
 This ensures the AI always has access to relevant information from your connected sources.
 
+### `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.
+
+- **Hot-buffer content** written by plugin versions since 2026-07 is tagged with `openclaw_channel_id` and can be removed with [`openclaw openclaw-hyperspell purge-channel <id>`](#openclaw-openclaw-hyperspell-purge-channel-channelid). Older hot-buffer rows are untagged, but each row's resource id equals its OpenClaw session id, so they are reachable via the purge command's `--session` flag.
+- **Auto-trace resources and `/remember` memories** written by current versions carry the same `openclaw_channel_id` tag going forward. Ones written by older versions are not channel-tagged and cannot be automatically purged — identify them manually (e.g. via `hyperspell_search`) and use the purge command's `--resource` escape hatch.
+- **Emotional-state registers** are keyed by relationship, not channel, and live behind the `/emotional-state` API rather than the memories store this command scans — they are never matched by `purge-channel`, and deletion of them is per-relationship, all-or-nothing. (Newer plugin versions tag registers with a `channelId` metadata field for analysis, but that does not make them purgeable per channel.)
+- **Server-side extractions** derived from traces (`extract: ["procedure", "memory", "mood"]`) are created backend-side; whether deleting the parent trace removes them is an open backend question (see `docs/hyperspell-backend-followups.md`).
+
+The purge command prints these standing limitations on every run.
+
 ## Available Sources
 
 ### Documents & Storage

package/dist/commands/preview.js

@@ -0,0 +1,93 @@
+import { buildEmotionalContext, fetchRecentOrLatest, looksLikeRawTranscript, } from "../hooks/emotional-state.js";
+import { gatherOrientation, personalUserId } from "../hooks/startup-orientation.js";
+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
+ * 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
+ * (a debug command must not consume or reveal a mood roll; the roll happens
+ * once, in the real injection path, per session).
+ */
+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.
+    if (isExcludedChannel({ channelId: ctx.channel }, cfg)) {
+        return "This channel is quarantined (excludeChannels): no context would be injected here and no memory would be written.";
+    }
+    const sections = [];
+    // ---- 1. Emotional context (registration order in index.ts: first) ----
+    if (!cfg.emotionalContext) {
+        sections.push("Emotional context: OFF (emotionalContext=false) — no register/arc would be injected.");
+    }
+    else {
+        try {
+            const states = await fetchRecentOrLatest(client, cfg);
+            const usable = states.filter((s) => s.summary && !looksLikeRawTranscript(s.summary));
+            if (usable.length > 0) {
+                const pending = states.length - usable.length;
+                const pendingNote = pending > 0
+                    ? `\n(${pending} more register(s) still extracting — excluded, same as the real hook.)`
+                    : "";
+                sections.push(`Emotional context: would inject ${usable.length} register(s):\n\n${buildEmotionalContext(usable)}${pendingNote}`);
+            }
+            else if (states.length > 0) {
+                sections.push("Emotional context: register(s) exist but are still extracting (raw-transcript placeholder) — the real hook would skip this turn and retry next turn.");
+            }
+            else {
+                sections.push("Emotional context: ON, but no prior emotional state found — nothing to inject yet (first conversation, or register deleted).");
+            }
+        }
+        catch (err) {
+            log.error("/previewcontext: emotional fetch failed", err);
+            sections.push("Emotional context: fetch FAILED — the real hook would log this and inject nothing. Check logs.");
+        }
+        // Mood weather: report configuration only. Deliberately NOT rolled — see
+        // function doc comment. Preview must be idempotent and non-revealing.
+        sections.push(cfg.moodWeatherChance > 0
+            ? `Mood weather: configured chance ${Math.round(cfg.moodWeatherChance * 100)}% per session — NOT rolled by this preview. Each real session rolls independently at injection time; the actual mood (if any) is only observable in the live session.`
+            : "Mood weather: OFF (moodWeatherChance=0).");
+    }
+    // ---- 2. Auto-context (second in registration order) ----
+    sections.push(cfg.autoContext
+        ? "Auto-context: ON — will search memories using the text of your next message. Query-dependent, so not previewable here; use /getcontext <your message> to simulate."
+        : "Auto-context: OFF.");
+    // ---- 3. Startup orientation (third in registration order) ----
+    const so = cfg.startupOrientation;
+    if (!so.enabled) {
+        sections.push("Startup orientation: OFF (startupOrientation.enabled=false).");
+    }
+    else {
+        const { skip, userId } = personalUserId(cfg, ctx);
+        if (skip) {
+            sections.push("Startup orientation: ON, but you are an unknown sender in multi-user mode — the real hook would skip injection for you.");
+        }
+        else {
+            const g = await gatherOrientation(client, cfg, userId);
+            const parts = [];
+            if (g.recentSource === "none") {
+                parts.push("recent-interactions: no source (hotBuffer and autoTrace both off) — block would be empty.");
+            }
+            else if (!g.recentOk) {
+                parts.push(`recent-interactions: fetch FAILED (source=${g.recentSource}) — real hook would retry next turn.`);
+            }
+            else {
+                parts.push(g.recentBlock ?? `recent-interactions: source=${g.recentSource}, 0 results — block omitted.`);
+            }
+            if (!g.loopsOk) {
+                parts.push("unfinished-loops: search FAILED — real hook would retry next turn.");
+            }
+            else {
+                parts.push(g.loopsBlock ??
+                    `unfinished-loops: 0 results for loopsQuery ("${so.loopsQuery}") — block omitted.`);
+            }
+            sections.push(`Startup orientation: ON.\n\n${parts.join("\n\n")}`);
+        }
+    }
+    return [
+        "What the next session would inject (read-only preview — no session state touched, no mood rolled):",
+        "",
+        sections.join("\n\n---\n\n"),
+    ].join("\n");
+}

package/dist/commands/purge-channel.js

@@ -0,0 +1,54 @@
+import { conversationMatchesChannel } from "../lib/exclude-channels.js";
+/**
+ * Enumerate the given sources and return every memory attributable to
+ * `channelId` — via the `openclaw_channel_id` metadata tag (exact or
+ * thread-suffix, same semantics as the quarantine check), or via the
+ * hot-buffer `resourceId === sessionId` identity for legacy untagged rows.
+ */
+export async function findChannelMemories(client, channelId, opts) {
+    const matches = [];
+    const sessionIds = new Set((opts.sessionIds ?? []).map((s) => s.toLowerCase()));
+    for (const source of opts.sources) {
+        for await (const m of client.listMemories({ source, userId: opts.userId })) {
+            const tagged = m.metadata.openclaw_channel_id;
+            if (typeof tagged === "string" && conversationMatchesChannel(tagged, channelId)) {
+                matches.push({ resourceId: m.resourceId, source: m.source, title: m.title, via: "channel_tag" });
+            }
+            else if (sessionIds.has(m.resourceId.toLowerCase())) {
+                // Hot-buffer resource_id === sessionId — rows written before channel
+                // tagging existed are reachable only through this identity.
+                matches.push({ resourceId: m.resourceId, source: m.source, title: m.title, via: "session_id" });
+            }
+        }
+    }
+    return matches;
+}
+/** Delete every match. `deleteMemory` is already 404-tolerant (absent = deleted). */
+export async function deleteMatches(client, matches, opts) {
+    let deleted = 0;
+    let failed = 0;
+    for (const m of matches) {
+        const r = await client.deleteMemory(m.resourceId, { source: m.source, userId: opts.userId });
+        if (r.deleted)
+            deleted++;
+        else
+            failed++;
+    }
+    return { matched: matches, deleted, failed };
+}
+/** Render matches as an aligned `resourceId  source  via  title` table. */
+export function formatMatchTable(matches) {
+    const rows = [
+        ["RESOURCE ID", "SOURCE", "VIA", "TITLE"],
+        ...matches.map((m) => [m.resourceId, m.source, m.via, m.title ?? "-"]),
+    ];
+    const widths = [0, 1, 2].map((i) => Math.max(...rows.map((r) => r[i].length)));
+    return rows
+        .map((r) => `${r[0].padEnd(widths[0])}  ${r[1].padEnd(widths[1])}  ${r[2].padEnd(widths[2])}  ${r[3]}`)
+        .join("\n");
+}
+/** Standing limitations — printed on every run so operators aren't surprised. */
+export const PURGE_LIMITATIONS_FOOTER = "Note: not everything is channel-tagged. Auto-trace resources and /remember memories written by older plugin versions, " +
+    "hot-buffer rows written before 2026-07, and emotional-state registers are NOT matched by this command. " +
+    "Use --session for legacy hot-buffer rows and --resource for manually identified resources; " +
+    'see the "excludeChannels is forward-only" section of the README.';

package/dist/commands/setup.js

@@ -12,6 +12,7 @@ import { getWorkspaceDir, parseConfig, resolveConfigPath } from "../config.js";
 import { buildExtractionPrompt, CRON_JOB_NAME } from "../graph/cron.js";
 import { NetworkStateManager } from "../graph/state.js";
 import { scanMemories, formatScanResults, completeMemories } from "../graph/ops.js";
+import { deleteMatches, findChannelMemories, formatMatchTable, PURGE_LIMITATIONS_FOOTER, } from "./purge-channel.js";
 async function fetchConnectionSources(client, userId) {
     try {
         const userClient = new Hyperspell({
@@ -524,6 +525,54 @@ export function registerCliCommands(program, pluginConfig) {
         .action(async () => {
         await runConnect(pluginConfig);
     });
+    // Retroactive cleanup for quarantined channels. Dry run by default — no
+    // interactive prompt, so it stays usable from cron/exec like `network`.
+    hyperspellCmd
+        .command("purge-channel <channelId>")
+        .description("Find (and with --yes delete) memories synced from a channel — retroactive cleanup for excludeChannels, which is forward-only")
+        .option("--source <sources>", "Comma-separated Hyperspell sources to scan (default: vault, the hot-buffer consolidation target)", "vault")
+        .option("--user <userId>", "X-As-User to scan/delete under (default: configured userId). In multiUser deployments run once per mapped userId.")
+        .option("--session <ids>", "Comma-separated OpenClaw session ids — matches legacy untagged hot-buffer resources (resource_id === session id)")
+        .option("--resource <ids>", "Comma-separated explicit resource ids to include (escape hatch for traces / remember memories identified manually)")
+        .option("--yes", "Actually delete. Without this flag the command is a dry run.")
+        .action(async (channelId, opts) => {
+        const splitCsv = (v) => typeof v === "string" ? v.split(",").map((s) => s.trim()).filter(Boolean) : [];
+        try {
+            const cfg = parseConfig(pluginConfig);
+            const client = new HyperspellClient(cfg);
+            const sources = splitCsv(opts.source).map((s) => s.toLowerCase());
+            const userId = opts.user ?? cfg.userId;
+            const matches = await findChannelMemories(client, channelId, {
+                sources: sources.length > 0 ? sources : ["vault"],
+                userId,
+                sessionIds: splitCsv(opts.session),
+            });
+            // Explicit ids are operator-asserted; append any not already found.
+            const found = new Set(matches.map((m) => m.resourceId));
+            for (const id of splitCsv(opts.resource)) {
+                if (!found.has(id)) {
+                    matches.push({ resourceId: id, source: sources[0] ?? "vault", title: null, via: "explicit" });
+                }
+            }
+            if (matches.length === 0) {
+                process.stdout.write(`No memories matched channel ${channelId}.\n\n${PURGE_LIMITATIONS_FOOTER}\n`);
+                return;
+            }
+            process.stdout.write(formatMatchTable(matches) + "\n\n");
+            if (!opts.yes) {
+                process.stdout.write(`Dry run: ${matches.length} memor${matches.length === 1 ? "y" : "ies"} would be deleted. Re-run with --yes to delete.\n\n${PURGE_LIMITATIONS_FOOTER}\n`);
+                return;
+            }
+            const result = await deleteMatches(client, matches, { userId });
+            process.stdout.write(`Deleted ${result.deleted} of ${result.matched.length} matched memories (${result.failed} failed).\n\n${PURGE_LIMITATIONS_FOOTER}\n`);
+            if (result.failed > 0)
+                process.exit(1);
+        }
+        catch (err) {
+            process.stderr.write(`Purge failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
     // Memory Network CLI commands (used by isolated cron sessions via exec)
     const networkCmd = hyperspellCmd
         .command("network")

package/dist/commands/slash.js

@@ -2,6 +2,7 @@ import { getWorkspaceDir } from "../config.js";
 import { buildScopeFilter, getCanReadScopes, getDefaultWriteScope, resolveRole, resolveUser, routeWrite, } from "../lib/sender.js";
 import { log } from "../logger.js";
 import { syncAllMemoryFiles } from "../sync/markdown.js";
+import { buildPreviewReport } from "./preview.js";
 /**
  * Strip a `#scope-name` prefix from free text. Returns the scope and the
  * remainder. Used by /remember and /getcontext to let users narrow or route
@@ -156,4 +157,21 @@ export function registerCommands(api, client, cfg) {
             }
         },
     });
+    // /previewcontext - Show what would be injected into the next session
+    api.registerCommand({
+        name: "previewcontext",
+        description: "Preview what Hyperspell would inject at the next session start",
+        acceptsArgs: false,
+        requireAuth: true,
+        handler: async (ctx) => {
+            log.debug("/previewcontext command");
+            try {
+                return { text: await buildPreviewReport(client, cfg, ctx) };
+            }
+            catch (err) {
+                log.error("/previewcontext failed", err);
+                return { text: "Failed to build preview. Check logs for details." };
+            }
+        },
+    });
 }

package/dist/hooks/auto-context.js

@@ -1,6 +1,7 @@
+import { appendFileSync } from "node:fs";
 import { buildScopeFilter, getCanReadScopes, resolveUser, } from "../lib/sender.js";
 import { excludeFilterFor, mergeWithExclude } from "../lib/filters.js";
-import { rerank, selectRanked } from "../lib/ranking.js";
+import { explainSelection, rerank, } from "../lib/ranking.js";
 import { classifySearchError, logSearchError } from "../lib/search-error.js";
 import { resolveCurrentSessionId } from "../lib/session.js";
 import { recordSender, senderIdFromCtx } from "../lib/speaker-tracker.js";
@@ -79,6 +80,49 @@ function formatSelected(selected, threshold) {
         return null;
     return sections.join("\n\n");
 }
+/**
+ * Opt-in score sampling for relevanceThreshold tuning (proposal 02 §3b).
+ * Writes one JSONL line per candidate when HYPERSPELL_SCORE_LOG names a file;
+ * review/analyze with docs/score-review.mjs and docs/score-analyze.mjs.
+ *
+ * The lines carry an 80-char prompt prefix and memory snippets — sensitive
+ * plaintext on disk — so this is OFF by default and never config-driven:
+ * it writes nothing unless the operator explicitly sets the env var (setting
+ * it IS the opt-in), and the log should be deleted after the tuning window.
+ * The env var is read at call time (not module load) so tests can set it.
+ * Must never throw into the retrieval path.
+ */
+function logScoreSamples(prompt, sessionId, scope, explained, threshold) {
+    const path = process.env.HYPERSPELL_SCORE_LOG;
+    if (!path || explained.length === 0)
+        return;
+    const ts = new Date().toISOString();
+    const lines = explained.map((e) => {
+        const r = e.result;
+        const top = [...r.highlights].sort((a, b) => (b.score ?? 0) - (a.score ?? 0))[0];
+        return JSON.stringify({
+            ts,
+            sessionId,
+            scope,
+            prompt: prompt.slice(0, 80),
+            resourceId: r.resourceId,
+            title: (r.title ?? "").slice(0, 60),
+            kind: r._kind,
+            base: Number(r._base.toFixed(4)),
+            composite: Number(r._composite.toFixed(4)),
+            threshold,
+            selected: e.selected,
+            cut: e.cut,
+            snippet: (top?.text ?? "").replace(/\s+/g, " ").slice(0, 120),
+        });
+    });
+    try {
+        appendFileSync(path, `${lines.join("\n")}\n`);
+    }
+    catch {
+        // instrumentation must never break retrieval
+    }
+}
 const INTRO = "The following is surfaced from the user's memory and connected sources, including past conversations. Reference it as recalled context, only when relevant to the conversation.";
 const DISCLAIMER = "Draw on it when relevant — including indirect connections — but don't force it into every response or make assumptions beyond what's stated.";
 // A short, CONDITIONAL reminder appended only to a real memory block (not a
@@ -157,11 +201,27 @@ export function buildAutoContextHandler(client, cfg) {
                 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 selected = selectRanked(ranked, cfg.maxResults, cfg.relevanceThreshold, ranking.chatterQuota);
+                const explained = explainSelection(ranked, cfg.maxResults, cfg.relevanceThreshold, ranking.chatterQuota);
+                logScoreSamples(prompt, currentSessionId, "single", explained, cfg.relevanceThreshold);
+                const selected = explained.filter((e) => e.selected).map((e) => e.result);
+                // Cut-reason visibility (proposal 02, absorbs proposal 03): logged
+                // BEFORE the `formatted` check so quota drops stay visible even when
+                // 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.
+                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), {});
+                    const topQuotaDrop = cuts.find((e) => e.cut === "chatter-quota");
+                    const quotaNote = topQuotaDrop
+                        ? `, top quota-dropped composite ${topQuotaDrop.result._composite.toFixed(2)}`
+                        : "";
+                    log.debug(`auto-context: cut ${cuts.length} of ${ranked.length} candidates ${JSON.stringify(cutTally)}${quotaNote}`);
+                }
                 formatted = formatSelected(selected, cfg.relevanceThreshold);
                 if (formatted) {
                     const tally = selected.reduce((acc, r) => ((acc[r._kind] = (acc[r._kind] ?? 0) + 1), acc), {});
-                    log.debug(`auto-context: injecting (ranked) ${JSON.stringify(tally)} from ${results.length} candidates (chatter cap ${ranking.chatterQuota})`);
+                    log.debug(`auto-context: injecting (ranked) ${JSON.stringify(tally)} from ${results.length} candidates (chatter cap ${ranking.chatterQuota}, composite ${selected.at(-1)?._composite.toFixed(2)}–${selected[0]?._composite.toFixed(2)})`);
                 }
             }
             else {
@@ -188,6 +248,10 @@ export function buildAutoContextHandler(client, cfg) {
         }
     };
 }
+// Score logging / cut attribution (proposal 02) applies to the ranked
+// 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) {
     const multiUser = cfg.multiUser;
     const isKnownSender = !!resolved?.resolved;

package/dist/hooks/auto-trace.js

@@ -1,3 +1,4 @@
+import { channelIdFromCtx } from "../lib/exclude-channels.js";
 import { resolveUser } from "../lib/sender.js";
 import { isMultiSpeaker } from "../lib/speaker-tracker.js";
 import { log } from "../logger.js";
@@ -113,7 +114,14 @@ export function buildAutoTraceHandler(client, cfg) {
             log.debug(`auto-trace: skipping — conversation too short (${estimate} chars)`);
             return;
         }
-        const sessionId = event.sessionId ?? crypto.randomUUID();
+        // The session id lives on the hook CONTEXT, not the agent_end event (same
+        // contract issue #42 hit in hot-buffer): reading only event.sessionId
+        // yields a fresh random UUID per turn, which breaks multi-speaker
+        // detection keying and makes the openclaw_session_id tag useless for
+        // cleanup. Prefer ctx; keep event/random as fallbacks.
+        const sessionId = ctx?.sessionId ??
+            event.sessionId ??
+            crypto.randomUUID();
         const history = messagesToJSONL(messages, sessionId);
         // Warn once per session when multiple speakers have no multiUser config:
         // all turns collapse into a single undifferentiated trace under cfg.userId.
@@ -131,12 +139,22 @@ export function buildAutoTraceHandler(client, cfg) {
         // Falls back to sharedUserId for unknown senders (or undefined in single-user mode).
         const resolved = resolveUser(ctx, cfg);
         const userId = resolved?.userId;
+        // Tag traces with the conversation they came from. channelIdFromCtx is the
+        // same resolver the quarantine check uses, so tag-time identity matches
+        // quarantine-time identity — the purge-channel CLI relies on that parity.
+        // session_id is a first-class trace field but is NOT exposed by
+        // listMemories, so it's mirrored into metadata for enumeration.
+        const channelId = channelIdFromCtx(ctx);
         try {
             const result = await client.sendTrace(history, {
                 sessionId,
                 title,
                 extract: cfg.autoTrace.extract,
-                metadata: cfg.autoTrace.metadata,
+                metadata: {
+                    ...cfg.autoTrace.metadata,
+                    ...(channelId ? { openclaw_channel_id: channelId } : {}),
+                    openclaw_session_id: sessionId,
+                },
                 userId,
                 // Auto-trace captures full conversation text — the most sensitive class
                 // of memory. Default to private; users opt into family-visible recall

package/dist/hooks/emotional-state.js

@@ -1,10 +1,11 @@
+import { channelIdFromCtx } from "../lib/exclude-channels.js";
 import { resolveCurrentSessionId } from "../lib/session.js";
 import { isMultiSpeaker } from "../lib/speaker-tracker.js";
 import { log } from "../logger.js";
 import { sanitizeTraceText } from "./auto-trace.js";
 import { buildMoodWeatherContext, rollMood } from "./mood-weather.js";
 /** How many recent registers to surface as the "arc" at session start. */
-const EMOTIONAL_ARC_LIMIT = 3;
+export const EMOTIONAL_ARC_LIMIT = 3;
 const MIN_MESSAGES = 3;
 const MIN_CONVERSATION_LENGTH = 100;
 /**
@@ -24,6 +25,25 @@ const NON_CONVERSATIONAL_TRIGGERS = new Set(["cron", "heartbeat", "memory"]);
 const STORE_DEBOUNCE_MS = 3 * 60 * 1000;
 /** relationshipId → last successful store time (ms). Module-scoped, per process. */
 const lastStoreAt = new Map();
+/**
+ * Cross-session cooldown for mood weather: once weather actually LANDS, no new
+ * roll for this long, no matter how many sessions start. "Rare per session"
+ * isn't "rare" when sessions cluster — five short same-day sessions would
+ * otherwise get five independent rolls and can whiplash silly → spiky → flat
+ * in one afternoon. Weather changes on the scale of days, not sessions.
+ * Misses do NOT start the cooldown — only landed weather does, so effective
+ * frequency for unclustered sessions still tracks moodWeatherChance.
+ */
+export const MOOD_WEATHER_COOLDOWN_MS = 6 * 60 * 60 * 1000;
+/** relationshipId → when weather last actually landed (ms). Module-scoped, per process (mirrors lastStoreAt). */
+const lastMoodRollAt = new Map();
+/**
+ * sessionKey → the mood that landed for that session. Post-compaction
+ * re-injection must replay the SAME weather — not roll new dice (mood must
+ * stay stable for a whole session) and not silently drop it (the cooldown
+ * would otherwise suppress the re-roll mid-session).
+ */
+const sessionMoods = new Map();
 /**
  * Sessions where emotional context has already been injected this run.
  * Emotional state doesn't change within a session (it's extracted at
@@ -120,9 +140,14 @@ function relativeWhen(iso) {
  * backend doesn't expose `/emotional-state/recent` yet (returns null) or errors
  * — so this works before AND after that endpoint deploys.
  */
-async function fetchRecentOrLatest(client, cfg) {
+export async function fetchRecentOrLatest(client, cfg, limit) {
+    // An explicit caller-supplied limit (the hyperspell_emotional_arc tool) must
+    // always win outright; only the *default* when no limit is passed may depend
+    // on config (see #68's depth-weighted default) — a model's explicit ask
+    // should never be silently overridden by an unrelated config knob.
+    const fetchLimit = limit ?? EMOTIONAL_ARC_LIMIT;
     try {
-        const recent = await client.getRecentEmotionalStates(cfg.relationshipId, EMOTIONAL_ARC_LIMIT);
+        const recent = await client.getRecentEmotionalStates(cfg.relationshipId, fetchLimit);
         if (recent !== null)
             return recent; // endpoint available (may be empty)
     }
@@ -133,7 +158,7 @@ async function fetchRecentOrLatest(client, cfg) {
     return single ? [single] : [];
 }
 /** Build the injected emotional-context block from one or more registers. */
-function buildEmotionalContext(states) {
+export function buildEmotionalContext(states) {
     const intro = states.length > 1
         ? "How your relationship with this user has felt across your recent conversations, most recent first. Let the trajectory inform your tone — don't reference it explicitly."
         : "The emotional register of your relationship with this user from your last interaction. Let it inform your tone — don't reference it explicitly.";
@@ -156,7 +181,8 @@ function buildEmotionalContext(states) {
  *
  * Runs on `before_agent_start` (which fires every turn).
  */
-export function buildEmotionalStateFetchHandler(client, cfg) {
+export function buildEmotionalStateFetchHandler(client, cfg, deps = {}) {
+    const now = deps.now ?? Date.now;
     return async (_event, ctx) => {
         const sessionKey = ctx?.sessionKey;
         if (sessionKey && injectedSessions.has(sessionKey)) {
@@ -168,25 +194,45 @@ export function buildEmotionalStateFetchHandler(client, cfg) {
             // after a store the register can be the RAW input transcript, not the
             // distilled feeling. Injecting that is useless and pollutes tone.
             const usable = states.filter((s) => s.summary && !looksLikeRawTranscript(s.summary));
+            if (usable.length === 0 && states.length > 0) {
+                // State(s) exist but are all still extracting — don't cache, so a
+                // later turn re-fetches once extraction completes. Runs BEFORE the
+                // mood roll so a discarded turn can't land weather or burn the
+                // cross-session cooldown.
+                log.debug("emotional-context: state(s) still extracting — skipping injection this turn");
+                return;
+            }
             // Mood weather: an exogenous, uncaused session mood that OVERRIDES the
-            // arc's tone for this session only. Rolled once per session (gated by
-            // the same inject-once cache). Lives purely in the injection path — it is
+            // arc's tone for this session only. Lives purely in the injection path —
             // never written back via the store handler, so one random morning can't
             // calcify into the baseline. May clash with the room on purpose.
-            const mood = cfg.moodWeatherChance > 0 ? rollMood(cfg.moodWeatherChance) : null;
-            const moodBlock = mood ? buildMoodWeatherContext(mood) : "";
-            if (mood) {
+            // Rolled once per session (inject-once cache) AND at most once per
+            // MOOD_WEATHER_COOLDOWN_MS across sessions (a landed roll suppresses new
+            // rolls; post-compaction re-injection replays the same mood instead).
+            const relId = cfg.relationshipId ?? "";
+            const priorMood = sessionKey ? sessionMoods.get(sessionKey) : undefined;
+            // Missing map entry means weather never landed this process — always
+            // eligible (don't subtract from an epoch the injectable clock may predate).
+            const lastLanded = lastMoodRollAt.get(relId);
+            const cooledDown = lastLanded === undefined || now() - lastLanded >= MOOD_WEATHER_COOLDOWN_MS;
+            const mood = priorMood ??
+                (cfg.moodWeatherChance > 0 && cooledDown
+                    ? rollMood(cfg.moodWeatherChance, deps.rng)
+                    : null);
+            if (mood && !priorMood) {
+                lastMoodRollAt.set(relId, now());
+                if (sessionKey)
+                    sessionMoods.set(sessionKey, mood);
                 log.info(`mood-weather: rolled "${mood.id}" this session`);
+                // Coordination with issue #71 (mood-weather observability): if #71's
+                // recordMoodRoll(client, mood, {...}) has landed, its call belongs
+                // HERE — inside this `!priorMood` guard — not on a bare `if (mood)`
+                // at the two return sites below. A priorMood replay (post-compaction
+                // re-injection of an already-rolled mood) is not a new roll; calling
+                // recordMoodRoll on replay would log the same event twice.
             }
+            const moodBlock = mood ? buildMoodWeatherContext(mood) : "";
             if (usable.length === 0) {
-                if (states.length > 0) {
-                    // State(s) exist but are all still extracting — don't cache, so a
-                    // later turn re-fetches once extraction completes. (We re-roll the
-                    // mood then too, which is fine — still at most once per *injected*
-                    // session, since extraction settles within seconds.)
-                    log.debug("emotional-context: state(s) still extracting — skipping injection this turn");
-                    return;
-                }
                 // No arc yet — but weather can still land on a blank slate.
                 log.debug("emotional-context: no prior emotional state found");
                 if (sessionKey)
@@ -228,8 +274,12 @@ export function buildEmotionalStateCompactionHandler() {
 export function buildEmotionalStateSessionCleanupHandler() {
     return async (_event, ctx) => {
         const sessionKey = ctx?.sessionKey;
-        if (sessionKey)
+        if (sessionKey) {
             injectedSessions.delete(sessionKey);
+            // Session over — its mood memo is dead weight. NOT cleared on
+            // compaction: surviving compaction is what makes the mood replay.
+            sessionMoods.delete(sessionKey);
+        }
     };
 }
 /**
@@ -276,9 +326,16 @@ export function buildEmotionalStateStoreHandler(client, cfg) {
             return;
         }
         try {
+            // Tag the register with the medium it was extracted from (voice vs Discord vs
+            // DM), mirroring hot-buffer's openclaw_channel_id tag. Capture-only: analysis/
+            // debugging metadata, deliberately NOT surfaced in the injected prose (#74).
+            const channelId = channelIdFromCtx(ctx);
             const result = await client.storeEmotionalState(transcript, {
                 relationshipId: cfg.relationshipId,
-                metadata: { source: "openclaw_agent_end" },
+                metadata: {
+                    source: "openclaw_agent_end",
+                    ...(channelId ? { channelId } : {}),
+                },
             });
             lastStoreAt.set(relId, Date.now());
             log.info(`emotional-state: stored ${result.resourceId}`);