@hyperspell/openclaw-hyperspell 0.15.0 → 0.16.0

package/dist/client.js

@@ -294,12 +294,17 @@ export class HyperspellClient {
         if (messages.length === 0)
             return { count: 0 };
         const source = (options?.source ?? "vault").toLowerCase();
+        const metadata = options?.metadata;
         const body = {
             source,
             messages: messages.map((m) => ({
                 resource_id: m.resourceId,
                 message_id: m.messageId,
                 content: m.content,
+                // Per-message metadata (Hyperspell #1921): tags hot-buffer rows so
+                // retrieval can identify/filter them like /memories/add rows. Persists
+                // on the live hot row and is unioned onto the consolidated Resource.
+                ...(metadata ? { metadata } : {}),
             })),
         };
         log.debugRequest("messages.create", {
@@ -395,6 +400,43 @@ export class HyperspellClient {
         log.debugResponse("emotional-state.get", { found: true, resourceId: result.resourceId });
         return result;
     }
+    /**
+     * The most recent emotional states (newest first), up to `limit` — for
+     * surfacing the recent ARC of how a relationship has felt, not just one
+     * snapshot. Returns `null` when the backend doesn't expose
+     * `/emotional-state/recent` yet (404) so callers can fall back to
+     * `getEmotionalState`. Other non-OK responses throw.
+     */
+    async getRecentEmotionalStates(relationshipId, limit = 3) {
+        log.debugRequest("emotional-state.recent", { relationshipId, limit });
+        const url = new URL(`${API_BASE_URL}/emotional-state/recent`);
+        if (relationshipId)
+            url.searchParams.set("relationship_id", relationshipId);
+        url.searchParams.set("limit", String(limit));
+        const res = await fetch(url.toString(), {
+            method: "GET",
+            headers: this.rawHeaders(),
+        });
+        if (res.status === 404) {
+            // Endpoint not deployed yet — signal the caller to fall back.
+            log.debug("emotional-state.recent unavailable (404) — caller falls back to latest");
+            return null;
+        }
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`GET /emotional-state/recent failed (${res.status}): ${text}`);
+        }
+        const data = (await res.json());
+        const list = (data ?? []).map((d) => ({
+            resourceId: d.resource_id,
+            summary: d.summary ?? "",
+            extractedAt: d.extracted_at ?? "",
+            sessionId: d.session_id ?? null,
+            relationshipId: d.relationship_id ?? null,
+        }));
+        log.debugResponse("emotional-state.recent", { count: list.length });
+        return list;
+    }
     async deleteEmotionalState(relationshipId) {
         log.debugRequest("emotional-state.delete", { relationshipId });
         const url = new URL(`${API_BASE_URL}/emotional-state`);

package/dist/hooks/auto-context.js

@@ -1,5 +1,7 @@
 import { buildScopeFilter, getCanReadScopes, resolveUser, } from "../lib/sender.js";
 import { excludeFilterFor, mergeWithExclude } from "../lib/filters.js";
+import { classifySearchError, logSearchError } from "../lib/search-error.js";
+import { resolveCurrentSessionId } from "../lib/session.js";
 import { log } from "../logger.js";
 function formatRelativeTime(isoTimestamp) {
     try {
@@ -54,23 +56,47 @@ const DISCLAIMER = "Draw on it when relevant — including indirect connections
 function wrapSingle(body) {
     return `<hyperspell-context>\n${INTRO}\n\n${body}\n\n${DISCLAIMER}\n</hyperspell-context>`;
 }
+/**
+ * Drop results belonging to the CURRENT session. The hot buffer writes the live
+ * conversation to the vault every turn (`resourceId = sessionId`), and those
+ * rows are the highest-scoring matches for whatever the agent is currently
+ * saying — so without this the agent gets its own just-written turns injected
+ * back as "recalled memory," crowding out older context (issue #42).
+ *
+ * Purely subtractive: with no resolvable session id we return results unchanged,
+ * and a wrong id can only fail to hide the echo — never hide genuine
+ * cross-session memories, which live under a different `resource_id`.
+ */
+export function dropCurrentSession(results, currentSessionId) {
+    if (!currentSessionId)
+        return results;
+    const kept = results.filter((r) => r.resourceId !== currentSessionId);
+    const dropped = results.length - kept.length;
+    if (dropped > 0) {
+        log.debug(`auto-context: excluded ${dropped} result(s) from current session ${currentSessionId}`);
+    }
+    return kept;
+}
 export function buildAutoContextHandler(client, cfg) {
     return async (event, ctx) => {
         const prompt = event.prompt;
         if (!prompt || prompt.length < 5)
             return;
+        // The live session's own just-written turns must not be surfaced back as
+        // "recalled memory" (issue #42) — resolve its id once and exclude it below.
+        const currentSessionId = resolveCurrentSessionId(event, ctx);
         // Multi-user path
         if (cfg.multiUser) {
             const resolved = resolveUser(ctx, cfg);
-            return multiUserSearch(client, cfg, prompt, resolved);
+            return multiUserSearch(client, cfg, prompt, resolved, currentSessionId);
         }
         // Single-user path — preserves main's highlights + threshold behavior
         log.debug(`auto-context: searching for "${prompt.slice(0, 50)}..."`);
         try {
-            const results = await client.search(prompt, {
+            const results = dropCurrentSession(await client.search(prompt, {
                 limit: cfg.maxResults,
                 filter: excludeFilterFor(cfg),
-            });
+            }), currentSessionId);
             const formatted = formatHighlightBullets(results, cfg.maxResults, cfg.relevanceThreshold);
             if (!formatted) {
                 log.debug("auto-context: no relevant memories found");
@@ -80,12 +106,16 @@ export function buildAutoContextHandler(client, cfg) {
             return { prependContext: wrapSingle(formatted) };
         }
         catch (err) {
-            log.error("auto-context failed", err);
+            // A transient backend throttle (429 / Retry-After) must not be swallowed
+            // as a generic failure — log it at warn, distinguished from real errors,
+            // so the degraded auto-context is observable (issue #39). The hook stays
+            // silent (no injection) either way; the agent didn't explicitly ask.
+            logSearchError(log, "auto-context", classifySearchError(err), err);
             return;
         }
     };
 }
-async function multiUserSearch(client, cfg, prompt, resolved) {
+async function multiUserSearch(client, cfg, prompt, resolved, currentSessionId) {
     const multiUser = cfg.multiUser;
     const isKnownSender = !!resolved?.resolved;
     const includeShared = multiUser.includeSharedInSearch;
@@ -126,19 +156,19 @@ async function multiUserSearch(client, cfg, prompt, resolved) {
     if (personalSearch) {
         const r = settled[idx++];
         if (r.status === "fulfilled") {
-            personalResults = r.value;
+            personalResults = dropCurrentSession(r.value, currentSessionId);
         }
         else {
-            log.error("auto-context: personal search failed", r.reason);
+            logSearchError(log, "auto-context: personal search", classifySearchError(r.reason), r.reason);
         }
     }
     if (sharedSearch) {
         const r = settled[idx++];
         if (r.status === "fulfilled") {
-            sharedResults = r.value;
+            sharedResults = dropCurrentSession(r.value, currentSessionId);
         }
         else {
-            log.error("auto-context: shared search failed", r.reason);
+            logSearchError(log, "auto-context: shared search", classifySearchError(r.reason), r.reason);
         }
     }
     const sections = [];

package/dist/hooks/emotional-state.js

@@ -1,7 +1,26 @@
 import { log } from "../logger.js";
 import { sanitizeTraceText } from "./auto-trace.js";
+/** How many recent registers to surface as the "arc" at session start. */
+const EMOTIONAL_ARC_LIMIT = 3;
 const MIN_MESSAGES = 3;
 const MIN_CONVERSATION_LENGTH = 100;
+/**
+ * Only REAL human conversations should shape her emotional register. Automated
+ * runs — cron check-ins, heartbeats, internal memory passes — are not "how the
+ * relationship feels"; counting them lets a throwaway "how's your afternoon?"
+ * heartbeat overwrite the register from a deep conversation (the whipsaw).
+ * `ctx.trigger` is one of cron|heartbeat|manual|memory|overflow|user; we store
+ * only for user-driven turns (and `overflow`, a continuation of a user run).
+ */
+const NON_CONVERSATIONAL_TRIGGERS = new Set(["cron", "heartbeat", "memory"]);
+/**
+ * Debounce window: don't re-extract the register on every turn of an active
+ * conversation (each store is a backend LLM call, and the latest already carries
+ * the full transcript). One snapshot per ~few minutes of real talk is plenty.
+ */
+const STORE_DEBOUNCE_MS = 3 * 60 * 1000;
+/** relationshipId → last successful store time (ms). Module-scoped, per process. */
+const lastStoreAt = new Map();
 /**
  * Sessions where emotional context has already been injected this run.
  * Emotional state doesn't change within a session (it's extracted at
@@ -58,6 +77,75 @@ function messagesToTranscript(messages) {
     }
     return lines.join("\n");
 }
+/**
+ * True if a fetched emotional-state `summary` is actually the raw transcript
+ * placeholder returned during the async extraction window (status=pending),
+ * rather than a distilled emotional register. Real summaries are second-person
+ * prose ("Your relationship with this user…"); the placeholder echoes the input
+ * conversation, which has role-prefixed lines.
+ */
+export function looksLikeRawTranscript(summary) {
+    return /(^|\n)\s*(user|assistant)\s*:/i.test(summary);
+}
+/** Compact relative time for the arc labels (e.g. "just now", "3h ago", "2d ago"). */
+function relativeWhen(iso) {
+    if (!iso)
+        return "";
+    try {
+        const mins = (Date.now() - new Date(iso).getTime()) / 60000;
+        if (Number.isNaN(mins))
+            return "";
+        if (mins < 2)
+            return "just now";
+        if (mins < 60)
+            return `${Math.floor(mins)}m ago`;
+        const hrs = mins / 60;
+        if (hrs < 24)
+            return `${Math.floor(hrs)}h ago`;
+        const days = hrs / 24;
+        if (days < 7)
+            return `${Math.floor(days)}d ago`;
+        return new Date(iso).toLocaleDateString("en", { month: "short", day: "numeric" });
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Prefer the recent ARC (last N registers) so a single shallow read can't
+ * misrepresent the relationship. Falls back to the single latest when the
+ * 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) {
+    try {
+        const recent = await client.getRecentEmotionalStates(cfg.relationshipId, EMOTIONAL_ARC_LIMIT);
+        if (recent !== null)
+            return recent; // endpoint available (may be empty)
+    }
+    catch (err) {
+        log.debug("emotional-context: /recent unavailable — falling back to latest", err);
+    }
+    const single = await client.getEmotionalState(cfg.relationshipId);
+    return single ? [single] : [];
+}
+/** Build the injected emotional-context block from one or more registers. */
+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.";
+    const lines = states.map((s) => {
+        const when = relativeWhen(s.extractedAt);
+        return when ? `- [${when}] ${s.summary}` : `- ${s.summary}`;
+    });
+    return [
+        "<hyperspell-emotional-context>",
+        intro,
+        "",
+        ...lines,
+        "</hyperspell-emotional-context>",
+    ].join("\n");
+}
 /**
  * Fetch emotional state on the first agent turn of a session and inject into
  * context. On later turns of the same session, return undefined — the
@@ -72,21 +160,25 @@ export function buildEmotionalStateFetchHandler(client, cfg) {
             return;
         }
         try {
-            const state = await client.getEmotionalState(cfg.relationshipId);
-            if (!state) {
+            const states = await fetchRecentOrLatest(client, cfg);
+            // Drop raw-transcript placeholders: extraction is async, so for ~10s
+            // 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) {
+                if (states.length > 0) {
+                    // State(s) exist but are all still extracting — don't cache, so a
+                    // later turn re-fetches once extraction completes.
+                    log.debug("emotional-context: state(s) still extracting — skipping injection this turn");
+                    return;
+                }
                 log.debug("emotional-context: no prior emotional state found");
                 if (sessionKey)
                     injectedSessions.add(sessionKey);
                 return;
             }
-            log.debug(`emotional-context: injecting state from ${state.extractedAt}`);
-            const context = [
-                "<hyperspell-emotional-context>",
-                "The following captures the emotional register of your relationship with this user from your last interaction. Let it inform your tone — don't reference it explicitly.",
-                "",
-                state.summary,
-                "</hyperspell-emotional-context>",
-            ].join("\n");
+            log.debug(`emotional-context: injecting ${usable.length} recent register(s)`);
+            const context = buildEmotionalContext(usable);
             if (sessionKey)
                 injectedSessions.add(sessionKey);
             return { prependContext: context };
@@ -125,11 +217,18 @@ export function buildEmotionalStateSessionCleanupHandler() {
  * Runs on `agent_end` — fire-and-forget.
  */
 export function buildEmotionalStateStoreHandler(client, cfg) {
-    return async (event) => {
+    return async (event, ctx) => {
         if (event.success === false) {
             log.debug("emotional-state: skipping — agent ended with error");
             return;
         }
+        // Only real human conversations count — skip cron/heartbeat/memory runs so
+        // an automated check-in can't overwrite the register from a real talk.
+        const trigger = ctx?.trigger;
+        if (trigger && NON_CONVERSATIONAL_TRIGGERS.has(trigger)) {
+            log.debug(`emotional-state: skipping — non-conversational trigger (${trigger})`);
+            return;
+        }
         const messages = event.messages;
         if (!messages || messages.length < MIN_MESSAGES) {
             log.debug(`emotional-state: skipping — too few messages (${messages?.length ?? 0})`);
@@ -140,11 +239,19 @@ export function buildEmotionalStateStoreHandler(client, cfg) {
             log.debug(`emotional-state: skipping — conversation too short (${transcript.length} chars)`);
             return;
         }
+        // Debounce: at most one snapshot per STORE_DEBOUNCE_MS of active talk.
+        const relId = cfg.relationshipId ?? "";
+        const since = Date.now() - (lastStoreAt.get(relId) ?? 0);
+        if (since < STORE_DEBOUNCE_MS) {
+            log.debug(`emotional-state: skipping — debounced (${Math.round(since / 1000)}s since last store)`);
+            return;
+        }
         try {
             const result = await client.storeEmotionalState(transcript, {
                 relationshipId: cfg.relationshipId,
                 metadata: { source: "openclaw_agent_end" },
             });
+            lastStoreAt.set(relId, Date.now());
             log.info(`emotional-state: stored ${result.resourceId}`);
         }
         catch (err) {

package/dist/hooks/startup-orientation.js

@@ -2,6 +2,8 @@ import { resolveUser } from "../lib/sender.js";
 import { log } from "../logger.js";
 const MAX_ATTEMPTS = 2;
 const RECENT_BUFFER_LIMIT = 100;
+/** Hot-buffer conversation resources are keyed by the session id (a UUID). */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /**
  * Sessions where the orientation block was already injected (or where we
  * deliberately decided not to inject — unknown sender, exhausted retries).
@@ -134,6 +136,59 @@ async function fetchRecentTraces(client, cutoff, limit, userId) {
     });
     return buffer.slice(0, limit);
 }
+/**
+ * Pull recent conversation sessions from the hot buffer's vault resources — the
+ * modern source of "recent interactions" (the agent_end-trace path only works
+ * when auto-trace is on, which it usually isn't). The hot buffer writes one
+ * session-grouped Resource per conversation: `resource_id` = the session id (a
+ * UUID), untagged (no `openclaw_source`), with a generated title. We rely on
+ * `listMemories` returning resources newest-first (verified live) and take the
+ * newest `limit` conversation resources — their metadata carries no date to
+ * filter on, so order is our recency signal.
+ *
+ * Excludes: tagged rows (memory_sync_section / command / agent_end), non-UUID
+ * resources (synced docs), automated cron sessions, and untitled rows.
+ */
+async function fetchRecentConversations(client, limit, userId) {
+    const out = [];
+    const seenTitles = new Set();
+    let scanned = 0;
+    for await (const memory of client.listMemories({
+        source: "vault",
+        userId,
+        pageSize: 50,
+    })) {
+        scanned++;
+        if (scanned > RECENT_BUFFER_LIMIT)
+            break;
+        if (!UUID_RE.test(memory.resourceId))
+            continue;
+        if (memory.metadata?.openclaw_source)
+            continue;
+        const title = memory.title ?? "";
+        if (title.length === 0 || /^\[cron:/i.test(title))
+            continue;
+        // The backend sometimes generates the same title for distinct sessions
+        // (e.g. repeated daily-summary chats); collapse those so the block isn't
+        // padded with duplicates.
+        const titleKey = title.trim().toLowerCase();
+        if (seenTitles.has(titleKey))
+            continue;
+        seenTitles.add(titleKey);
+        out.push({
+            resourceId: memory.resourceId,
+            title: memory.title,
+            source: memory.source,
+            score: null,
+            url: null,
+            createdAt: null,
+            highlights: [],
+        });
+        if (out.length >= limit)
+            break; // newest-first → first N are most recent
+    }
+    return out;
+}
 export function buildStartupOrientationHandler(client, cfg) {
     const so = cfg.startupOrientation;
     return async (_event, ctx) => {
@@ -156,9 +211,20 @@ export function buildStartupOrientationHandler(client, cfg) {
                 injectedSessions.add(sessionKey);
             return;
         }
-        const cutoff = isoDaysAgo(so.recentDays);
+        // 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([
-            fetchRecentTraces(client, cutoff, so.recentLimit, userId),
+            recentFetch,
             client.search(so.loopsQuery, {
                 limit: so.loopsLimit,
                 userId,

package/dist/index.js

@@ -8,7 +8,7 @@ import { buildEmotionalStateCompactionHandler, buildEmotionalStateFetchHandler,
 import { buildFileSyncHandler, syncMemoriesOnStartup } from "./hooks/memory-sync.js";
 import { buildHotBufferHandler, buildHotBufferSessionCleanupHandler, } from "./hooks/hot-buffer.js";
 import { buildStartupOrientationCompactionHandler, buildStartupOrientationHandler, buildStartupOrientationSessionCleanupHandler, } from "./hooks/startup-orientation.js";
-import { initLogger } from "./logger.js";
+import { initLogger, log } from "./logger.js";
 import { createRememberToolFactory } from "./tools/remember.js";
 import { createSearchToolFactory } from "./tools/search.js";
 import { registerNetworkTools } from "./graph/index.js";
@@ -74,29 +74,45 @@ export default {
         api.registerTool(createRememberToolFactory(client, cfg), {
             name: "hyperspell_remember",
         });
-        // Register emotional context hooks.
-        // - fetch: inject once per session on first turn (cached thereafter)
-        // - compaction: clear cache so the next turn re-injects after trim
-        // - session cleanup: drop Set entry on session end
-        // - store: extract new emotional state from the finished session
+        const startHandlers = [];
         if (cfg.emotionalContext) {
-            api.on("before_agent_start", buildEmotionalStateFetchHandler(client, cfg));
+            startHandlers.push(buildEmotionalStateFetchHandler(client, cfg));
             api.on("after_compaction", buildEmotionalStateCompactionHandler());
             api.on("session_end", buildEmotionalStateSessionCleanupHandler());
             api.on("agent_end", buildEmotionalStateStoreHandler(client, cfg));
         }
-        // Register auto-context hook
         if (cfg.autoContext) {
-            const autoContextHandler = buildAutoContextHandler(client, cfg);
-            api.on("before_agent_start", autoContextHandler);
+            startHandlers.push(buildAutoContextHandler(client, cfg));
         }
-        // Register startup-orientation hooks: recent-interactions + unfinished-loops
-        // injected once per session on first turn. Lifecycle mirrors emotional-context.
         if (cfg.startupOrientation.enabled) {
-            api.on("before_agent_start", buildStartupOrientationHandler(client, cfg));
+            // recent-interactions reads conversation sessions from the hot buffer
+            // when it's on, else falls back to auto-trace's agent_end traces. With
+            // BOTH off there's no source to read — warn so the operator knows the
+            // block will be empty rather than wondering why there's no continuity.
+            if (!cfg.hotBuffer.enabled && !cfg.autoTrace.enabled) {
+                log.warn("startup-orientation is enabled but neither hotBuffer nor autoTrace is on — recent-interactions will be empty (no conversation source to read).");
+            }
+            startHandlers.push(buildStartupOrientationHandler(client, cfg));
             api.on("after_compaction", buildStartupOrientationCompactionHandler());
             api.on("session_end", buildStartupOrientationSessionCleanupHandler());
         }
+        if (startHandlers.length > 0) {
+            api.on("before_agent_start", async (event, ctx) => {
+                const results = await Promise.all(startHandlers.map((h) => Promise.resolve()
+                    .then(() => h(event, ctx))
+                    .catch((err) => {
+                    // One injector failing must not break the others or the turn.
+                    log.error("session-start handler failed", err);
+                    return undefined;
+                })));
+                const parts = results
+                    .map((r) => r?.prependContext)
+                    .filter((p) => typeof p === "string" && p.length > 0);
+                return parts.length > 0
+                    ? { prependContext: parts.join("\n\n") }
+                    : undefined;
+            });
+        }
         // Register auto-trace hook (send conversations to Hyperspell on session end)
         if (cfg.autoTrace.enabled) {
             api.on("agent_end", buildAutoTraceHandler(client, cfg));

package/dist/lib/filters.js

@@ -12,17 +12,21 @@
  * NOT surface via generic retrieval — replaying whole sanitized transcripts back
  * into context creates a self-amplifying pollution loop. Exclude them here.
  *
- * THE #40 TENSION: hot-buffer rows written via `POST /messages` carry NO
- * `openclaw_source`, and the backend evaluates absent-field metadata predicates
- * in SQL three-valued logic — `metadata->>'openclaw_source'` is NULL for a
- * missing key, and `NULL != 'agent_end'` is NULL (not TRUE) — so this filter
- * also drops every untagged hot-buffer row. We could not work around that at the
- * filter layer: `docs/filter-dialect-test.mjs` against the live backend showed
- * that NO `openclaw_source` predicate returns untagged rows ($exists/$or/$nin/
- * $not all fail), AND that `POST /messages` silently ignores a `metadata` field,
- * so the rows can't be positively tagged either. See `excludeFilterFor` for the
- * fix we ship (gate on auto-trace), and issue #40 for the backend follow-up
- * (make `/messages` accept metadata, or make the filter NULL-tolerant).
+ * Since backend Hyperspell #1921, `$ne` follows MongoDB absent-field semantics:
+ * it KEEPS rows whose `openclaw_source` is absent (untagged hot-buffer rows) and
+ * drops only `agent_end`. So applying this filter is now SAFE for hot rows — the
+ * old #40 tension (where `NULL != 'agent_end'` dropped untagged rows) is resolved
+ * at the backend.
+ *
+ * We nonetheless GATE the filter on auto-trace (see `excludeFilterFor`) for
+ * PERFORMANCE, not correctness: a `{$ne}` predicate measurably slows the vector
+ * 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.
  *
  * NOTE: an earlier version checked the top-level `source` field for
  * "openclaw_agent_end" — wrong on BOTH counts (the tag lives in metadata under
@@ -32,17 +36,15 @@ export const EXCLUDE_SESSION_END_FILTER = {
     openclaw_source: { $ne: "agent_end" },
 };
 /**
- * The exclude clause to apply for a given config — or `undefined` to skip
- * filtering entirely (issue #40, Option 4 — the only viable plugin-side fix).
- * `openclaw_source: "agent_end"` rows are written ONLY by the auto-trace hook;
- * when auto-trace is disabled there are none to hide, so we skip the filter
- * entirely — which is also the ONLY way to keep untagged hot-buffer rows
- * visible, since (per the dialect test) no filter and no write-tag can do it.
+ * The exclude clause to apply for a given config — or `undefined` to skip the
+ * filter. `agent_end` rows are written ONLY by the auto-trace hook, so when
+ * auto-trace is OFF there are none to hide and we skip the filter to avoid its
+ * ~1s/search latency cost (pure overhead otherwise — verified live against an
+ * auto-trace-off agent with zero `agent_end` rows).
  *
- * LIMITATION: when auto-trace IS enabled, this still applies `$ne agent_end`,
- * which drops untagged hot-buffer rows along with the traces. There is no
- * plugin-side fix for that combination today; it needs the backend change
- * tracked in #40. (The common single-feature install has auto-trace off.)
+ * When auto-trace is ON we apply `{$ne:"agent_end"}`, which post-#1921 drops the
+ * traces while KEEPING untagged hot-buffer rows — so that path is correct now
+ * (the old #40 hot-row-drop is fixed by the backend, not by gating).
  */
 export function excludeFilterFor(cfg) {
     return cfg.autoTrace.enabled ? EXCLUDE_SESSION_END_FILTER : undefined;

package/dist/lib/search-error.js

@@ -0,0 +1,125 @@
+/**
+ * Shared classification of read-path (search/retrieval) failures, used by every
+ * retrieval path (the `hyperspell_search` tool + the auto-context hook) so both
+ * surface a transient backend throttle the same way — mirroring how
+ * `lib/filters.ts` keeps filtering consistent across them.
+ *
+ * Why this exists (issue #39): under load the Hyperspell backend sheds requests
+ * with a `Retry-After` header advertising a multi-second cooldown (~55s observed)
+ * — surfaced as a 429 and, when shedding hard, attached to 5xx responses too.
+ * The `hyperspell` SDK already retries 429/5xx with bounded exponential backoff
+ * (maxRetries=2), but no in-turn backoff can ride out a ~55s cooldown, so the
+ * call still throws. The bug is what happens NEXT: the read path collapsed the
+ * error to "Search failed" / injected nothing, so a session reads it as "no
+ * memories" and confabulates around an empty result.
+ *
+ * The fix is to DISTINGUISH a throttle (429 / `Retry-After`) from a generic
+ * transient 5xx and a permanent 4xx, surface it EXPLICITLY to the agent, and log
+ * it at `warn` with the cooldown so the throttle is observable. We deliberately
+ * do NOT add our own retry — the SDK already does, and a longer in-turn sleep
+ * would just hang the turn.
+ */
+/** Pull a numeric HTTP status off an unknown thrown value (SDK `APIError.status`). */
+function statusOf(err) {
+    const s = err?.status;
+    return typeof s === "number" ? s : undefined;
+}
+/**
+ * Read the `Retry-After` header (in seconds) off a thrown SDK `APIError`.
+ * `APIError.headers` is a `Headers` instance; we also tolerate a plain object so
+ * this stays robust to SDK shape changes and is trivial to unit-test. Per RFC,
+ * `Retry-After` is either delta-seconds or an HTTP-date — handle both.
+ */
+function retryAfterSecondsOf(err) {
+    const headers = err?.headers;
+    let raw;
+    if (headers && typeof headers.get === "function") {
+        raw = headers.get("retry-after");
+    }
+    else if (headers && typeof headers === "object") {
+        const obj = headers;
+        raw = obj["retry-after"] ?? obj["Retry-After"];
+    }
+    const trimmed = raw?.trim();
+    if (!trimmed)
+        return undefined;
+    const asSeconds = Number(trimmed);
+    if (Number.isFinite(asSeconds))
+        return Math.max(0, Math.round(asSeconds));
+    const asDate = Date.parse(trimmed);
+    if (!Number.isNaN(asDate)) {
+        return Math.max(0, Math.round((asDate - Date.now()) / 1000));
+    }
+    return undefined;
+}
+/**
+ * Cap, in seconds, beyond which we will NOT echo a literal Retry-After value to
+ * the agent. A backend advertising minutes is plausible; one advertising
+ * "~99999999999s" (or a far-future HTTP-date) is not, and interpolating it
+ * verbatim next to "try again shortly" is exactly the misleading signal #39
+ * exists to avoid. Above this we fall back to generic wording. The accurate
+ * value is still logged.
+ */
+const MAX_SURFACED_RETRY_SECONDS = 600;
+export function classifySearchError(err) {
+    const status = statusOf(err);
+    const retryAfterSeconds = retryAfterSecondsOf(err);
+    const detail = err instanceof Error ? err.message : String(err);
+    // A 429, or any status carrying Retry-After (the backend attaches it to the
+    // 5xx it sheds under load too), means an active cooldown window — flag it as
+    // a throttle regardless of the exact status code.
+    if (status === 429 || retryAfterSeconds !== undefined) {
+        return { kind: "throttled", status, retryAfterSeconds, detail };
+    }
+    if (status !== undefined && status >= 500) {
+        return { kind: "transient", status, detail };
+    }
+    if (status !== undefined && status >= 400) {
+        return { kind: "client", status, detail };
+    }
+    return { kind: "unknown", detail };
+}
+/**
+ * Agent-facing text for a failed `hyperspell_search` tool call. For a throttle or
+ * transient error the wording is deliberate: it tells the agent this is a backend
+ * condition and NOT an empty memory, so it doesn't conclude "nothing was found"
+ * (issue #39's core symptom).
+ */
+export function searchErrorToolText(info) {
+    switch (info.kind) {
+        case "throttled": {
+            const s = info.retryAfterSeconds;
+            if (s !== undefined && s <= MAX_SURFACED_RETRY_SECONDS) {
+                return `Memory search is temporarily rate-limited by the backend (retry in ~${s}s). This is a transient throttle, NOT an empty memory — do not conclude nothing was found; try again shortly.`;
+            }
+            // Unknown or implausibly long cooldown — don't echo an absurd number.
+            return `Memory search is temporarily rate-limited by the backend. This is a transient throttle, NOT an empty memory — do not conclude nothing was found; retry later rather than assuming nothing exists.`;
+        }
+        case "transient":
+            return `Memory search hit a transient backend error (HTTP ${info.status}) and automatic retries were exhausted. This is NOT an empty memory — do not conclude nothing was found; try again shortly.`;
+        default:
+            return `Search failed: ${info.detail}`;
+    }
+}
+/** One-line summary for logs. */
+function summarize(info) {
+    const parts = [`kind=${info.kind}`];
+    if (info.status !== undefined)
+        parts.push(`status=${info.status}`);
+    if (info.retryAfterSeconds !== undefined)
+        parts.push(`retry-after≈${info.retryAfterSeconds}s`);
+    return parts.join(" ");
+}
+/**
+ * Log a read-path failure consistently across both retrieval paths. Throttles and
+ * transient 5xx are expected-under-load and log at `warn` (with the cooldown, so
+ * blips are observable); genuine errors log at `error` with the raw cause.
+ */
+export function logSearchError(log, where, info, err) {
+    if (info.kind === "throttled" || info.kind === "transient") {
+        log.warn(`${where}: backend unavailable — ${summarize(info)}`);
+    }
+    else {
+        log.error(`${where} failed (${summarize(info)})`, err);
+    }
+}

package/dist/lib/session.js

@@ -0,0 +1,44 @@
+/**
+ * Resolve the CURRENT session's id — the value the hot buffer keys its rows by
+ * (`resourceId = event.sessionId`, see `hooks/hot-buffer.ts`). The auto-context
+ * hook uses this to exclude the live session's own just-written turns from its
+ * retrieval, so the agent isn't fed its own recent messages back as "recalled
+ * memory" (issue #42).
+ *
+ * The wrinkle: hooks see `ctx.sessionKey`, which is a COMPOSITE — e.g.
+ * `agent:main:cron:<cronId>:run:<sessionId>` — not the bare `sessionId` the hot
+ * buffer writes. So we prefer an explicit `sessionId` field when present and
+ * otherwise recover the bare id from the `:run:` suffix (or a trailing UUID).
+ *
+ * Returns `undefined` when no id can be determined — callers MUST treat that as
+ * "don't exclude" so retrieval degrades to its prior behavior rather than
+ * dropping anything by accident. The exclusion is purely subtractive: a wrong or
+ * missing id can only fail to hide the echo, never hide real cross-session
+ * memories (those live under a different resource_id).
+ */
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+const RUN_SEP = ":run:";
+export function resolveCurrentSessionId(event, ctx) {
+    // Prefer an explicit sessionId — this is exactly what the hot buffer uses.
+    const direct = (typeof event?.sessionId === "string" && event.sessionId) ||
+        (typeof ctx?.sessionId === "string" && ctx.sessionId);
+    if (direct)
+        return direct;
+    const key = ctx?.sessionKey;
+    if (typeof key !== "string" || key.length === 0)
+        return undefined;
+    // Composite key — the bare session id is the `:run:` suffix.
+    const runIdx = key.lastIndexOf(RUN_SEP);
+    if (runIdx >= 0) {
+        const tail = key.slice(runIdx + RUN_SEP.length);
+        if (tail.length > 0)
+            return tail;
+    }
+    // No `:run:` segment — accept the key only if it IS (ends with) a bare UUID;
+    // anything else (a phone handle, etc.) can't match a resource_id, so bail out
+    // rather than return a value that would silently never match.
+    const m = key.match(UUID_RE);
+    if (m && key.endsWith(m[0]))
+        return m[0];
+    return undefined;
+}

package/dist/tools/search.js

@@ -1,5 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import { mergeWithExclude } from "../lib/filters.js";
+import { classifySearchError, logSearchError, searchErrorToolText, } from "../lib/search-error.js";
 import { buildScopeFilter, getCanReadScopes, resolveUser } from "../lib/sender.js";
 import { log } from "../logger.js";
 export function createSearchToolFactory(client, cfg) {
@@ -76,14 +77,13 @@ export function createSearchToolFactory(client, cfg) {
                 };
             }
             catch (err) {
-                log.error("search tool failed", err);
+                // Distinguish a transient backend throttle (429 / Retry-After) from a
+                // real failure and surface it explicitly, so the agent doesn't read a
+                // backend hiccup as "no memories" and confabulate around it (issue #39).
+                const info = classifySearchError(err);
+                logSearchError(log, "search tool", info, err);
                 return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `Search failed: ${err instanceof Error ? err.message : String(err)}`,
-                        },
-                    ],
+                    content: [{ type: "text", text: searchErrorToolText(info) }],
                 };
             }
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.15.0",
+  "version": "0.16.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 lib/sender.test.ts lib/filters.test.ts config.test.ts sync/markdown.test.ts hooks/auto-trace.test.ts hooks/hot-buffer.test.ts hooks/emotional-state.test.ts hooks/startup-orientation.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 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"
   },
   "openclaw": {
     "extensions": [