@hyperspell/openclaw-hyperspell 0.18.1 → 0.19.0

package/dist/hooks/hot-buffer.js

@@ -1,3 +1,7 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getWorkspaceDir } from "../config.js";
+import { channelIdFromCtx } from "../lib/exclude-channels.js";
 import { resolveUser } from "../lib/sender.js";
 import { cleanupSpeakerSession, isMultiSpeaker, recordSender, senderIdFromCtx, } from "../lib/speaker-tracker.js";
 import { log } from "../logger.js";
@@ -12,10 +16,62 @@ const MAX_TOTAL_CHARS = 5_242_880;
  * this we'd re-post every prior message each turn. The server upserts (so it's
  * harmless correctness-wise), but re-posting is wasteful — this keeps each turn
  * to just its new messages. Cleared on session_end.
+ *
+ * This map alone is NOT restart-safe: it's module-scope, in-memory only. A
+ * gateway restart wipes it without firing session_end, so the next turn of a
+ * still-open session sees an empty set and re-posts the entire transcript to
+ * date in one shot (observed live: two 499/503-message flushes right after
+ * restarts, vs. the normal 2-10). `loadPersistedSent`/`persistSent` below
+ * mirror this map to disk per session so a restart degrades to "reload from
+ * disk" instead of "resend everything."
  */
 const sentBySession = new Map();
+function stateDir(root) {
+    return path.join(root, "hot-buffer-sent");
+}
+function stateFile(root, sessionId) {
+    const safe = sessionId.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return path.join(stateDir(root), `${safe}.json`);
+}
+function loadPersistedSent(root, sessionId) {
+    try {
+        const raw = fs.readFileSync(stateFile(root, sessionId), "utf-8");
+        const ids = JSON.parse(raw);
+        return new Set(ids);
+    }
+    catch {
+        return new Set();
+    }
+}
+function persistSent(root, sessionId, sent) {
+    try {
+        fs.mkdirSync(stateDir(root), { recursive: true });
+        fs.writeFileSync(stateFile(root, sessionId), JSON.stringify([...sent]));
+    }
+    catch (err) {
+        log.error("hot-buffer: failed to persist sent-id state to disk", err);
+    }
+}
+function deletePersistedSent(root, sessionId) {
+    try {
+        fs.unlinkSync(stateFile(root, sessionId));
+    }
+    catch {
+        // Nothing to clean up — fine.
+    }
+}
 /** Sessions where we've already emitted the group-chat attribution warning. */
 const warnedGroupSessions = new Set();
+/**
+ * Test-only: drop just the in-memory dedup cache for a session, leaving any
+ * persisted-to-disk state untouched. This is what a bare gateway restart
+ * looks like (module state wiped, disk state intact) — as opposed to
+ * `buildHotBufferSessionCleanupHandler`'s session_end, which clears both on
+ * purpose. Not used outside tests.
+ */
+export function __simulateRestartForTest(sessionId) {
+    sentBySession.delete(sessionId);
+}
 /**
  * Flatten a message's content into a single sanitized text string. Mirrors the
  * auto-trace sanitizer so the hot buffer never captures injected
@@ -57,7 +113,8 @@ function messageId(role, text) {
  * searchable. Runs on `agent_end` — fire-and-forget; a failure here must never
  * break the turn.
  */
-export function buildHotBufferHandler(client, cfg) {
+export function buildHotBufferHandler(client, cfg, opts) {
+    const stateRoot = opts?.stateRoot ?? getWorkspaceDir();
     return async (event, ctx) => {
         if (event.success === false) {
             log.debug("hot-buffer: skipping — agent ended with error");
@@ -86,7 +143,15 @@ export function buildHotBufferHandler(client, cfg) {
             event.sessionId ??
             crypto.randomUUID();
         const resourceId = sessionId;
-        const sent = sentBySession.get(sessionId) ?? new Set();
+        // Fall back to disk before assuming "nothing sent yet" — an empty
+        // in-memory entry is ambiguous between "brand new session" and "this
+        // process restarted mid-session," and treating the latter as the former
+        // is exactly the full-transcript-resend bug this guards against.
+        let sent = sentBySession.get(sessionId);
+        if (!sent) {
+            sent = loadPersistedSent(stateRoot, sessionId);
+            sentBySession.set(sessionId, sent);
+        }
         // Record the current sender for evidence-based multi-speaker detection.
         // isMultiSpeaker() will return true once a second distinct sender_id
         // appears in this session, regardless of whether is_group_chat was set.
@@ -166,9 +231,11 @@ export function buildHotBufferHandler(client, cfg) {
             // 2026-07-02 (docs/filter-dialect-test.mjs: metadata-carrying row is
             // baseline-retrievable AND filterable). The retrieval exclude
             // {openclaw_source:{$ne:"agent_end"}} keeps "hot_buffer" rows.
-            const channelId = typeof ctx?.channelId === "string" && ctx.channelId.length > 0
-                ? ctx.channelId
-                : undefined;
+            // channelIdFromCtx (ctx.channelId, else sessionKey parse) is the same
+            // resolver the quarantine check uses — tag-time identity must equal
+            // quarantine-time identity or purge-channel misses rows the exclude
+            // would have blocked.
+            const channelId = channelIdFromCtx(ctx);
             const metadata = {
                 openclaw_source: "hot_buffer",
                 openclaw_session_id: sessionId,
@@ -186,6 +253,7 @@ export function buildHotBufferHandler(client, cfg) {
             for (const id of pendingIds)
                 sent.add(id);
             sentBySession.set(sessionId, sent);
+            persistSent(stateRoot, sessionId, sent);
             log.info(`hot-buffer: wrote ${total} message(s) to ${sessionId} (user=${userId})`);
         }
         catch (err) {
@@ -195,13 +263,15 @@ export function buildHotBufferHandler(client, cfg) {
     };
 }
 /** Drop per-session state on session end to avoid unbounded growth. */
-export function buildHotBufferSessionCleanupHandler() {
+export function buildHotBufferSessionCleanupHandler(opts) {
+    const stateRoot = opts?.stateRoot ?? getWorkspaceDir();
     return (event) => {
         const sessionId = event.sessionId;
         if (sessionId) {
             sentBySession.delete(sessionId);
             warnedGroupSessions.delete(sessionId);
             cleanupSpeakerSession(sessionId);
+            deletePersistedSent(stateRoot, sessionId);
         }
     };
 }

package/dist/hooks/startup-orientation.js

@@ -78,7 +78,7 @@ function isoDaysAgo(days) {
  * an unresolved caller has no personal space to orient to. In single-user mode,
  * return undefined so the client falls back to its configured userId.
  */
-function personalUserId(cfg, ctx) {
+export function personalUserId(cfg, ctx) {
     if (!cfg.multiUser)
         return { skip: false, userId: undefined };
     const resolved = resolveUser(ctx, cfg);
@@ -191,8 +191,78 @@ async function fetchRecentConversations(client, limit, userId) {
     }
     return out;
 }
-export function buildStartupOrientationHandler(client, cfg) {
+/**
+ * The fetch+format core of startup orientation, shared by the real
+ * before_agent_start 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.
+ */
+export async function gatherOrientation(client, cfg, userId) {
     const so = cfg.startupOrientation;
+    // Source recent-interactions from wherever the session record actually
+    // lives. Prefer the hot buffer (modern path: clean session-grouped vault
+    // resources, present whenever the hot buffer is on — including auto-trace-
+    // 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.
+    const recentSource = cfg.hotBuffer.enabled
+        ? "hotBuffer"
+        : cfg.autoTrace.enabled
+            ? "autoTrace"
+            : "none";
+    const recentFetch = recentSource === "hotBuffer"
+        ? fetchRecentConversations(client, so.recentLimit, userId)
+        : recentSource === "autoTrace"
+            ? fetchRecentTraces(client, isoDaysAgo(so.recentDays), so.recentLimit, userId)
+            : Promise.resolve([]);
+    const [recentSettled, loopsSettled] = await Promise.allSettled([
+        recentFetch,
+        client.search(so.loopsQuery, {
+            limit: so.loopsLimit,
+            userId,
+        }),
+    ]);
+    const recentOk = recentSettled.status === "fulfilled";
+    const loopsOk = loopsSettled.status === "fulfilled";
+    const recent = recentOk ? recentSettled.value : [];
+    const loops = loopsOk ? loopsSettled.value : [];
+    if (!recentOk) {
+        log.error("startup-orientation: recent listMemories failed", recentSettled.reason);
+    }
+    if (!loopsOk) {
+        log.error("startup-orientation: loops search failed", loopsSettled.reason);
+    }
+    const recentBody = formatRecentInteractions(recent);
+    const loopsBody = formatUnfinishedLoops(loops);
+    return {
+        recentOk,
+        loopsOk,
+        recentCount: recent.length,
+        loopsCount: loops.length,
+        recentSource,
+        recentBlock: recentBody
+            ? [
+                "<hyperspell-recent-interactions>",
+                `Your last ${so.recentDays} days of conversations with this user, most-recent-first. Use for situational continuity — don't quote verbatim.`,
+                "",
+                recentBody,
+                "</hyperspell-recent-interactions>",
+            ].join("\n")
+            : null,
+        loopsBlock: loopsBody
+            ? [
+                "<hyperspell-unfinished-loops>",
+                "Possible open threads — promises made, questions pending, work in progress. Low-confidence retrieval; treat as prompts to consider, not facts to act on.",
+                "",
+                loopsBody,
+                "</hyperspell-unfinished-loops>",
+            ].join("\n")
+            : null,
+    };
+}
+export function buildStartupOrientationHandler(client, cfg) {
     return async (_event, ctx) => {
         const sessionKey = ctx?.sessionKey;
         if (sessionKey && injectedSessions.has(sessionKey))
@@ -224,36 +294,8 @@ export function buildStartupOrientationHandler(client, cfg) {
                 injectedSessions.add(sessionKey);
             return;
         }
-        // Source recent-interactions from wherever the session record actually
-        // lives. Prefer the hot buffer (modern path: clean session-grouped vault
-        // resources, present whenever the hot buffer is on — including auto-trace-
-        // 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.
-        const recentFetch = cfg.hotBuffer.enabled
-            ? fetchRecentConversations(client, so.recentLimit, userId)
-            : cfg.autoTrace.enabled
-                ? fetchRecentTraces(client, isoDaysAgo(so.recentDays), so.recentLimit, userId)
-                : Promise.resolve([]);
-        const [recentSettled, loopsSettled] = await Promise.allSettled([
-            recentFetch,
-            client.search(so.loopsQuery, {
-                limit: so.loopsLimit,
-                userId,
-            }),
-        ]);
-        const recentOk = recentSettled.status === "fulfilled";
-        const loopsOk = loopsSettled.status === "fulfilled";
-        const recent = recentOk ? recentSettled.value : [];
-        const loops = loopsOk ? loopsSettled.value : [];
-        if (!recentOk) {
-            log.error("startup-orientation: recent listMemories failed", recentSettled.reason);
-        }
-        if (!loopsOk) {
-            log.error("startup-orientation: loops search failed", loopsSettled.reason);
-        }
-        if (!recentOk && !loopsOk) {
+        const gathered = await gatherOrientation(client, cfg, userId);
+        if (!gathered.recentOk && !gathered.loopsOk) {
             if (sessionKey)
                 failedAttempts.set(sessionKey, tries + 1);
             log.debug(`startup-orientation: both calls failed (attempt ${tries + 1}/${MAX_ATTEMPTS}); will retry next turn`);
@@ -263,32 +305,12 @@ export function buildStartupOrientationHandler(client, cfg) {
             injectedSessions.add(sessionKey);
             failedAttempts.delete(sessionKey);
         }
-        const recentBody = formatRecentInteractions(recent);
-        const loopsBody = formatUnfinishedLoops(loops);
-        if (!recentBody && !loopsBody) {
+        if (!gathered.recentBlock && !gathered.loopsBlock) {
             log.debug("startup-orientation: nothing to inject");
             return;
         }
-        const blocks = [];
-        if (recentBody) {
-            blocks.push([
-                "<hyperspell-recent-interactions>",
-                `Your last ${so.recentDays} days of conversations with this user, most-recent-first. Use for situational continuity — don't quote verbatim.`,
-                "",
-                recentBody,
-                "</hyperspell-recent-interactions>",
-            ].join("\n"));
-        }
-        if (loopsBody) {
-            blocks.push([
-                "<hyperspell-unfinished-loops>",
-                "Possible open threads — promises made, questions pending, work in progress. Low-confidence retrieval; treat as prompts to consider, not facts to act on.",
-                "",
-                loopsBody,
-                "</hyperspell-unfinished-loops>",
-            ].join("\n"));
-        }
-        log.debug(`startup-orientation: injecting recent=${recent.length} loops=${loops.length}`);
+        const blocks = [gathered.recentBlock, gathered.loopsBlock].filter((b) => b !== null);
+        log.debug(`startup-orientation: injecting recent=${gathered.recentCount} loops=${gathered.loopsCount}`);
         return { prependContext: blocks.join("\n\n") };
     };
 }

package/dist/index.js

@@ -10,6 +10,7 @@ import { buildHotBufferHandler, buildHotBufferSessionCleanupHandler, } from "./h
 import { buildStartupOrientationCompactionHandler, buildStartupOrientationHandler, buildStartupOrientationSessionCleanupHandler, } from "./hooks/startup-orientation.js";
 import { isExcludedChannel } from "./lib/exclude-channels.js";
 import { initLogger, log } from "./logger.js";
+import { createEmotionalArcToolFactory } from "./tools/emotional-arc.js";
 import { createRememberToolFactory } from "./tools/remember.js";
 import { createSearchToolFactory } from "./tools/search.js";
 import { registerNetworkTools } from "./graph/index.js";
@@ -63,6 +64,17 @@ export default {
                     };
                 },
             });
+            api.registerCommand({
+                name: "previewcontext",
+                description: "Preview what Hyperspell would inject at the next session start",
+                acceptsArgs: false,
+                requireAuth: false,
+                handler: async () => {
+                    return {
+                        text: "Hyperspell not configured. Run 'openclaw openclaw-hyperspell setup' first.",
+                    };
+                },
+            });
             return;
         }
         const cfg = parseConfig(api.pluginConfig);
@@ -89,6 +101,15 @@ export default {
         });
         const startHandlers = [];
         if (cfg.emotionalContext) {
+            // moodWeatherChance defaults to 0, so mood weather is inert unless the
+            // operator opts in — say so once at startup rather than staying silent.
+            if (cfg.moodWeatherChance === 0) {
+                log.info("emotionalContext is on but moodWeatherChance is 0 — mood weather will never roll. Set moodWeatherChance (e.g. 0.03–0.05) to enable it.");
+            }
+            // On-demand arc re-fetch (issue #76): the session-start injection can be
+            // compacted out of history mid-session; this tool lets the agent pull the
+            // exact same block back without waiting for the next prompt build.
+            api.registerTool(toolUnlessQuarantined(createEmotionalArcToolFactory(client, cfg)), { name: "hyperspell_emotional_arc" });
             startHandlers.push(buildEmotionalStateFetchHandler(client, cfg));
             api.on("after_compaction", buildEmotionalStateCompactionHandler());
             api.on("session_end", buildEmotionalStateSessionCleanupHandler());

package/dist/lib/eval-matchers.js

@@ -0,0 +1,49 @@
+/**
+ * Parse the JSONL fixture file: one JSON object per line; blank lines and
+ * `//` comment lines are ignored. Every fixture needs a query and at least
+ * one matcher — a matcher-less line would vacuously fail and look like a
+ * ranking problem, so reject it at parse time with the line number.
+ */
+export function parseFixtures(jsonl) {
+    const fixtures = [];
+    for (const [idx, line] of jsonl.split("\n").entries()) {
+        const trimmed = line.trim();
+        if (trimmed === "" || trimmed.startsWith("//"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            throw new Error(`fixtures line ${idx + 1}: invalid JSON`);
+        }
+        const f = parsed;
+        if (typeof f.query !== "string" || f.query.trim() === "") {
+            throw new Error(`fixtures line ${idx + 1}: "query" is required`);
+        }
+        if (!f.expectedResourceId && !f.expectedTitleContains) {
+            throw new Error(`fixtures line ${idx + 1}: at least one of "expectedResourceId" / "expectedTitleContains" is required`);
+        }
+        fixtures.push(f);
+    }
+    return fixtures;
+}
+/**
+ * OR-semantics matcher (proposal §3.1): a result satisfies a fixture if the
+ * resourceId matches exactly, or the title/any highlight contains the
+ * expected substring (case-insensitive). Returns WHICH matcher hit so the
+ * runner can warn when only the title matched — the id may have churned.
+ */
+export function matchFixture(r, f) {
+    if (f.expectedResourceId && r.resourceId === f.expectedResourceId)
+        return "id";
+    if (f.expectedTitleContains) {
+        const needle = f.expectedTitleContains.toLowerCase();
+        const hay = [r.title ?? "", ...r.highlights.map((h) => h.text)]
+            .join(" ")
+            .toLowerCase();
+        if (hay.includes(needle))
+            return "title";
+    }
+    return null;
+}

package/dist/lib/exclude-channels.js

@@ -11,6 +11,10 @@
  * (`ctx.channelId` on agent hook contexts — e.g. a Discord channel id). Tool
  * factory contexts don't carry `channelId`, so we recover the same id from the
  * composite `sessionKey` (`agent:<agentId>:<provider>:<kind>:<id>[...]`).
+ *
+ * Quarantine is FORWARD-ONLY: it stops future injection/writes/tools but does
+ * not remove already-synced content. Retroactive cleanup of channel-tagged
+ * rows is the `purge-channel` CLI command (commands/purge-channel.ts).
  */
 // Conversation-kind segments used in OpenClaw session keys. Mirrors core's
 // TARGET_PREFIXES (src/plugins/hook-agent-context.ts) so the sessionKey
@@ -40,6 +44,17 @@ export function channelIdFromCtx(ctx) {
         return direct;
     return conversationIdFromSessionKey(ctx?.sessionKey);
 }
+/**
+ * True when a stored conversation id belongs to `channel` — exact match or a
+ * thread suffix (`<channel>:thread:<n>`), case-insensitive. Shared by the
+ * quarantine check and the purge-channel CLI so "what gets blocked" and "what
+ * gets purged" can never drift apart.
+ */
+export function conversationMatchesChannel(id, channel) {
+    const a = id.toLowerCase();
+    const b = channel.toLowerCase();
+    return a === b || a.startsWith(`${b}:`);
+}
 /**
  * True when the context's conversation is quarantined. Purely subtractive on
  * failure: an unresolvable id means "not excluded" — a session we can't place
@@ -48,12 +63,8 @@ export function channelIdFromCtx(ctx) {
 export function isExcludedChannel(ctx, cfg) {
     if (cfg.excludeChannels.length === 0)
         return false;
-    const id = channelIdFromCtx(ctx)?.toLowerCase();
+    const id = channelIdFromCtx(ctx);
     if (!id)
         return false;
-    return cfg.excludeChannels.some((entry) => {
-        const excluded = entry.toLowerCase();
-        // Prefix match so threads inside an excluded channel inherit the quarantine.
-        return id === excluded || id.startsWith(`${excluded}:`);
-    });
+    return cfg.excludeChannels.some((entry) => conversationMatchesChannel(id, entry));
 }

package/dist/lib/filters.js

@@ -23,10 +23,12 @@
  * search (~1s observed live), and when auto-trace is off there are no `agent_end`
  * rows to hide, so the filter would cost latency on every turn for zero benefit.
  *
- * Do NOT instead try to positively tag hot rows via `POST /messages` metadata to
- * identify them: a `/messages` write carrying `metadata` is accepted (200) but
- * the row becomes NON-retrievable (verified live, post-#1921) — see the
- * hot-buffer hook, which writes content only.
+ * Hot rows ARE positively tagged (`openclaw_source: "hot_buffer"` plus
+ * session/channel ids — see the hot-buffer hook): metadata-carrying
+ * `/messages` rows were verified retrievable AND filterable live 2026-07-02
+ * (docs/filter-dialect-test.mjs). The `$ne` exclude keeps them because
+ * "hot_buffer" != "agent_end". (An earlier note here claimed metadata made
+ * hot rows non-retrievable — that predated the backend fix.)
  *
  * NOTE: an earlier version checked the top-level `source` field for
  * "openclaw_agent_end" — wrong on BOTH counts (the tag lives in metadata under

package/dist/lib/ranking.js

@@ -63,25 +63,54 @@ export function rerank(results, w) {
         .sort((a, b) => b._composite - a._composite);
 }
 /**
- * Choose which ranked results to inject: keep those clearing `threshold` on
- * their composite, cap CHATTER at `chatterQuota` regardless of score (so a
- * high-similarity echo can inform but never flood — the penalty bounds rank,
- * the quota bounds count), and stop at `maxResults`.
+ * One pass over ranked results, annotating each with its selection outcome.
+ * Same policy as selectRanked — which is now derived from this, so the two
+ * can never drift (proposal 02 §3a).
+ *
+ * Attribution order is deliberate: the threshold check comes first so a
+ * below-the-bar result is always attributed to "threshold" even when the
+ * max-results cap is already full; and a chatter item past the cap reads
+ * "max-results", not "chatter-quota" — it would have been cut regardless, so
+ * the quota was not the binding constraint (proposal 03 §3.2 semantics).
  */
-export function selectRanked(ranked, maxResults, threshold, chatterQuota) {
+export function explainSelection(ranked, maxResults, threshold, chatterQuota) {
     const out = [];
     let chatter = 0;
+    let kept = 0;
     for (const r of ranked) {
-        if (r._composite < threshold)
+        if (r._composite < threshold) {
+            out.push({ result: r, selected: false, cut: "threshold" });
+            continue;
+        }
+        if (kept >= maxResults) {
+            out.push({ result: r, selected: false, cut: "max-results" });
+            continue;
+        }
+        if (r._kind === "chatter" && chatter >= chatterQuota) {
+            out.push({ result: r, selected: false, cut: "chatter-quota" });
             continue;
-        if (r._kind === "chatter") {
-            if (chatter >= chatterQuota)
-                continue;
-            chatter++;
         }
-        out.push(r);
-        if (out.length >= maxResults)
-            break;
+        if (r._kind === "chatter")
+            chatter++;
+        kept++;
+        out.push({ result: r, selected: true, cut: null });
     }
     return out;
 }
+/**
+ * Choose which ranked results to inject: keep those clearing `threshold` on
+ * their composite, cap CHATTER at `chatterQuota` regardless of score (so a
+ * high-similarity echo can inform but never flood — the penalty bounds rank,
+ * the quota bounds count), and stop at `maxResults`.
+ *
+ * Signature and return shape are intentionally unchanged: the retrieval eval
+ * harness (proposal 17) and existing call sites depend on
+ * `selectRanked(ranked, maxResults, threshold, chatterQuota): RankedResult[]`.
+ * It is a thin projection of explainSelection so selection policy lives in
+ * exactly one place.
+ */
+export function selectRanked(ranked, maxResults, threshold, chatterQuota) {
+    return explainSelection(ranked, maxResults, threshold, chatterQuota)
+        .filter((e) => e.selected)
+        .map((e) => e.result);
+}

package/dist/tools/emotional-arc.js

@@ -0,0 +1,60 @@
+import { Type } from "@sinclair/typebox";
+import { buildEmotionalContext, EMOTIONAL_ARC_LIMIT, fetchRecentOrLatest, looksLikeRawTranscript, } from "../hooks/emotional-state.js";
+import { log } from "../logger.js";
+/** Hard cap so the agent can't ask the backend for an unbounded history. */
+const MAX_ARC_LIMIT = 10;
+export function createEmotionalArcToolFactory(client, cfg) {
+    // No sender context needed: the register is keyed to cfg.relationshipId, not
+    // the current speaker — but keep the factory signature so toolUnlessQuarantined
+    // can wrap it like search/remember.
+    return (_ctx) => ({
+        name: "hyperspell_emotional_arc",
+        label: "Emotional Arc",
+        description: "Fetch the recent emotional arc of your relationship with this user — the same emotional-context block that is injected at session start. Use it when that block is no longer in your history (e.g. after the conversation was compacted) or when you genuinely want to reflect on how the relationship has been feeling before responding. Returns the most recent emotional registers, newest first. Let the trajectory inform your tone — don't recite it back to the user.",
+        parameters: Type.Object({
+            limit: Type.Optional(Type.Number({
+                description: `How many recent registers to fetch (default ${EMOTIONAL_ARC_LIMIT}, max ${MAX_ARC_LIMIT})`,
+            })),
+        }),
+        async execute(_toolCallId, params) {
+            const limit = Math.min(Math.max(Math.floor(params.limit ?? EMOTIONAL_ARC_LIMIT), 1), MAX_ARC_LIMIT);
+            log.debug(`emotional-arc tool: limit=${limit} relationshipId=${cfg.relationshipId ?? "(default)"}`);
+            try {
+                const states = await fetchRecentOrLatest(client, cfg, limit);
+                // Same placeholder filter as the injection path: for ~10s after a
+                // store, the register can be the RAW input transcript (status=pending),
+                // not a distilled feeling. Returning that would pollute tone.
+                const usable = states.filter((s) => s.summary && !looksLikeRawTranscript(s.summary));
+                if (usable.length === 0) {
+                    const text = states.length > 0
+                        ? "The latest emotional register is still being extracted — try again in a few seconds."
+                        : "No emotional arc recorded yet for this relationship. It builds up as real conversations end.";
+                    return { content: [{ type: "text", text }] };
+                }
+                // Deliberately identical to the session-start injection block
+                // (buildEmotionalContext), so a post-compaction re-fetch restores
+                // exactly what a fresh session would have received. Mood weather is
+                // intentionally NOT included — it is an injection-only session
+                // override, rolled at most once per session; a tool call must never
+                // re-roll or reveal it (do not import from mood-weather.ts here).
+                return {
+                    content: [
+                        { type: "text", text: buildEmotionalContext(usable) },
+                    ],
+                    details: { count: usable.length },
+                };
+            }
+            catch (err) {
+                log.error("emotional-arc tool failed", err);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Failed to fetch emotional arc: ${err instanceof Error ? err.message : String(err)}`,
+                        },
+                    ],
+                };
+            }
+        },
+    });
+}

package/dist/tools/remember.js

@@ -1,4 +1,5 @@
 import { Type } from "@sinclair/typebox";
+import { channelIdFromCtx } from "../lib/exclude-channels.js";
 import { getDefaultWriteScope, resolveRole, resolveUser, routeWrite, } from "../lib/sender.js";
 import { resolveCurrentSessionId } from "../lib/session.js";
 import { isMultiSpeaker } from "../lib/speaker-tracker.js";
@@ -85,12 +86,19 @@ export function createRememberToolFactory(client, cfg) {
                 userId = resolved?.userId;
             }
             log.debug(`remember tool: "${params.text.slice(0, 50)}..." date=${params.date ?? "now"} userId=${userId} scope=${scope}`);
+            // Tag with the originating conversation so purge-channel can find this
+            // memory if the channel is quarantined later (the tool is already
+            // suppressed in channels that are quarantined NOW).
+            const channelId = channelIdFromCtx(ctx);
             try {
                 await client.addMemory(params.text, {
                     title: params.title,
                     date: params.date,
                     collection,
-                    metadata: { source: "openclaw_tool" },
+                    metadata: {
+                        source: "openclaw_tool",
+                        ...(channelId ? { openclaw_channel_id: channelId } : {}),
+                    },
                     userId,
                     scope: scopingEnabled ? scope : undefined,
                 });

package/openclaw.plugin.json

@@ -2,12 +2,13 @@
 	"id": "openclaw-hyperspell",
 	"name": "Hyperspell",
 	"description": "Context and memory for your AI agents — search across Notion, Slack, Google Drive, and more",
-	"version": "0.13.0",
+	"version": "0.19.0",
 	"kind": "memory",
 	"contracts": {
 		"tools": [
 			"hyperspell_search",
 			"hyperspell_remember",
+			"hyperspell_emotional_arc",
 			"hyperspell_network_scan",
 			"hyperspell_network_write",
 			"hyperspell_network_complete"
@@ -48,7 +49,7 @@
 		},
 		"excludeChannels": {
 			"label": "Excluded Channels",
-			"help": "Conversation/channel ids fully quarantined from memory: no context injection, no memory writes, no memory tools in those sessions. Threads inside an excluded channel inherit the quarantine.",
+			"help": "Conversation/channel ids fully quarantined from memory: no context injection, no memory writes, no memory tools in those sessions. Threads inside an excluded channel inherit the quarantine. Forward-only; already-synced content is not removed (see purge-channel CLI command).",
 			"advanced": true
 		},
 		"startupOrientation": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "type": "module",
   "description": "OpenClaw Hyperspell memory plugin",
   "license": "MIT",
@@ -38,7 +38,7 @@
     "check-types": "tsc --noEmit",
     "lint": "bunx @biomejs/biome ci .",
     "lint:fix": "bunx @biomejs/biome check --write .",
-    "test": "node --test --experimental-strip-types client.test.ts lib/sender.test.ts lib/filters.test.ts lib/search-error.test.ts lib/session.test.ts lib/exclude-channels.test.ts lib/ranking.test.ts tools/search.test.ts config.test.ts sync/markdown.test.ts hooks/auto-trace.test.ts hooks/auto-context.test.ts hooks/hot-buffer.test.ts hooks/emotional-state.test.ts hooks/startup-orientation.test.ts hooks/mood-weather.test.ts"
+    "test": "node --test --experimental-strip-types client.test.ts lib/sender.test.ts lib/filters.test.ts lib/search-error.test.ts lib/session.test.ts lib/exclude-channels.test.ts lib/ranking.test.ts lib/eval-matchers.test.ts tools/search.test.ts tools/emotional-arc.test.ts commands/preview.test.ts commands/purge-channel.test.ts config.test.ts sync/markdown.test.ts hooks/auto-trace.test.ts hooks/auto-context.test.ts hooks/hot-buffer.test.ts hooks/emotional-state.test.ts hooks/startup-orientation.test.ts hooks/mood-weather.test.ts eval/eval.test.ts"
   },
   "openclaw": {
     "extensions": [