@hyperspell/openclaw-hyperspell 0.14.2 → 0.16.0

package/dist/client.js

@@ -270,6 +270,62 @@ export class HyperspellClient {
         });
         return { resourceId: result.resource_id, status: result.status };
     }
+    /**
+     * POST /messages — the real-time hot buffer. Rows are full-text searchable
+     * the instant they're inserted (a Postgres GENERATED tsvector, no embedding
+     * wait) and auto-consolidated server-side into vault Resources within ~60s.
+     * The existing search path already unions this buffer with vector results,
+     * so once we write here our turns become searchable immediately.
+     *
+     * Auth: api key + `X-As-User` (REQUIRED — the endpoint 422s without it).
+     * Upsert key is (app_id, user_id, resource_id, message_id), so re-posting an
+     * identical message_id updates `content` only — safe to retry, no duplicates.
+     *
+     * Server-side limits (return 422): per-message content 1..512,000 chars;
+     * batch 1..1,000 messages. Callers should pre-enforce these.
+     */
+    async sendMessages(messages, options) {
+        const userId = options?.userId ?? this.config.userId;
+        if (!userId) {
+            // X-As-User is mandatory for /messages. Fail loud rather than firing a
+            // request we know will 422.
+            throw new Error("sendMessages requires a userId (X-As-User) — none configured");
+        }
+        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", {
+            source,
+            count: messages.length,
+            userId,
+        });
+        const res = await fetch(`${API_BASE_URL}/messages`, {
+            method: "POST",
+            headers: { ...this.rawHeaders(), "X-As-User": userId },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`POST /messages failed (${res.status}): ${text}`);
+        }
+        const data = await res.json();
+        const count = data?.count ?? messages.length;
+        log.debugResponse("messages.create", { count });
+        return { count };
+    }
     async listConnections(options) {
         log.debugRequest("connections.list", { userId: options?.userId });
         const response = await this.client.connections.list(this.requestOptions(options?.userId));
@@ -344,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/commands/setup.js

@@ -269,6 +269,12 @@ async function runSetup() {
                 userId,
                 autoContext: true,
                 autoTrace: { enabled: false, extract: ["procedure"] },
+                hotBuffer: {
+                    enabled: false,
+                    source: "vault",
+                    writeUser: true,
+                    writeAssistant: true,
+                },
                 emotionalContext: false,
                 syncMemories: true,
                 syncMemoriesConfig: {

package/dist/config.js

@@ -15,6 +15,7 @@ const ALLOWED_KEYS = [
     "userId",
     "autoContext",
     "autoTrace",
+    "hotBuffer",
     "emotionalContext",
     "relationshipId",
     "startupOrientation",
@@ -235,6 +236,11 @@ export function parseConfig(raw) {
     const kgRaw = (cfg.knowledgeGraph ?? {});
     const atRaw = (cfg.autoTrace ?? {});
     const soRaw = (cfg.startupOrientation ?? {});
+    const hbRaw = (cfg.hotBuffer ?? {});
+    if (cfg.hotBuffer && typeof cfg.hotBuffer === "object" && !Array.isArray(cfg.hotBuffer)) {
+        assertAllowedKeys(hbRaw, ["enabled", "source", "writeUser", "writeAssistant"], "hyperspell.hotBuffer");
+    }
+    const hbSource = parseSources(hbRaw.source)[0] ?? "vault";
     // syncMemories can be a boolean (legacy) or an object (new)
     const smRaw = cfg.syncMemories;
     const syncMemoriesEnabled = typeof smRaw === "boolean"
@@ -269,6 +275,14 @@ export function parseConfig(raw) {
             ],
             metadata: atRaw.metadata,
         },
+        hotBuffer: {
+            // Default OFF so shipping the plugin never changes existing installs'
+            // behavior; opt in per-install via plugin config.
+            enabled: hbRaw.enabled ?? false,
+            source: hbSource,
+            writeUser: hbRaw.writeUser ?? true,
+            writeAssistant: hbRaw.writeAssistant ?? true,
+        },
         emotionalContext: cfg.emotionalContext ?? false,
         relationshipId: cfg.relationshipId,
         startupOrientation: {

package/dist/hooks/auto-context.js

@@ -1,5 +1,7 @@
 import { buildScopeFilter, getCanReadScopes, resolveUser, } from "../lib/sender.js";
-import { EXCLUDE_SESSION_END_FILTER, mergeWithExclude } from "../lib/filters.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 {
@@ -49,28 +51,52 @@ function formatHighlightBullets(results, maxResults, threshold) {
         return null;
     return sections.join("\n\n");
 }
-const INTRO = "The following is context from the user's connected sources. Reference it only when relevant to the conversation.";
-const DISCLAIMER = "Use this context naturally when relevant — including indirect connections — but don't force it into every response or make assumptions beyond what's stated.";
+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.";
 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: EXCLUDE_SESSION_END_FILTER,
-            });
+                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;
@@ -104,7 +134,7 @@ async function multiUserSearch(client, cfg, prompt, resolved) {
         ? client.search(prompt, {
             limit: cfg.maxResults,
             userId: resolved.userId,
-            filter: EXCLUDE_SESSION_END_FILTER,
+            filter: excludeFilterFor(cfg),
         })
         : null;
     // Always search shared for unknown senders, even if includeSharedInSearch is false
@@ -115,7 +145,7 @@ async function multiUserSearch(client, cfg, prompt, resolved) {
         ? client.search(prompt, {
             limit: sharedLimit,
             userId: multiUser.sharedUserId,
-            filter: mergeWithExclude(scopeFilter),
+            filter: mergeWithExclude(scopeFilter, cfg),
         })
         : null;
     const searches = [personalSearch, sharedSearch].filter(Boolean);
@@ -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/hot-buffer.js

@@ -0,0 +1,169 @@
+import { resolveUser } from "../lib/sender.js";
+import { log } from "../logger.js";
+import { sanitizeTraceText } from "./auto-trace.js";
+/** Server-side limits from POST /messages (return 422 if exceeded). */
+const MAX_CONTENT_CHARS = 512_000;
+const MAX_BATCH = 1_000;
+const MAX_TOTAL_CHARS = 5_242_880;
+/**
+ * Per-session set of message_ids already written to the hot buffer this run.
+ * `agent_end` fires once per turn with the *full* session history, so without
+ * 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.
+ */
+const sentBySession = new Map();
+/**
+ * Flatten a message's content into a single sanitized text string. Mirrors the
+ * auto-trace sanitizer so the hot buffer never captures injected
+ * <hyperspell-context>/emotional/orientation wrappers (which would otherwise be
+ * consolidated as "memory" and pollute future retrieval).
+ */
+function extractText(content) {
+    let raw;
+    if (typeof content === "string") {
+        raw = content;
+    }
+    else if (Array.isArray(content)) {
+        raw = content
+            .filter((i) => i?.type === "text" && typeof i.text === "string")
+            .map((i) => i.text)
+            .join("\n");
+    }
+    else {
+        raw = "";
+    }
+    return sanitizeTraceText(raw);
+}
+/**
+ * Deterministic, stable id for a message so retries upsert rather than
+ * duplicate. FNV-1a over role+text; prefixed with the role initial to keep
+ * user/assistant lines distinct even when content collides.
+ */
+function messageId(role, text) {
+    let h = 0x811c9dc5;
+    const s = `${role} ${text}`;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return `${role[0] ?? "x"}-${(h >>> 0).toString(16).padStart(8, "0")}`;
+}
+/**
+ * Write each completed turn to the Hyperspell hot buffer so it's instantly
+ * searchable. Runs on `agent_end` — fire-and-forget; a failure here must never
+ * break the turn.
+ */
+export function buildHotBufferHandler(client, cfg) {
+    return async (event, ctx) => {
+        if (event.success === false) {
+            log.debug("hot-buffer: skipping — agent ended with error");
+            return;
+        }
+        const messages = event.messages;
+        if (!messages || messages.length === 0)
+            return;
+        // X-As-User is mandatory for /messages. Resolve the owner up front and
+        // skip (with a clear warning) rather than firing requests that 422.
+        const userId = resolveUser(ctx, cfg)?.userId;
+        if (!userId) {
+            log.warn("hot-buffer: no userId resolved (X-As-User required) — skipping write");
+            return;
+        }
+        // The session id lives on the hook CONTEXT, not the agent_end event
+        // (PluginHookAgentEndEvent = { messages, success, error?, durationMs? };
+        // PluginHookAgentContext carries sessionId). Reading event.sessionId
+        // always yielded undefined → a fresh random resourceId every turn, which
+        // (a) defeated the sentBySession dedup so each turn re-posted the entire
+        // growing transcript, and (b) scattered a session’s turns across
+        // per-turn resources, so nothing could exclude "the current session"
+        // (issue #42). Prefer ctx.sessionId; keep event/random as fallbacks.
+        const sessionId = ctx?.sessionId ??
+            event.sessionId ??
+            crypto.randomUUID();
+        const resourceId = sessionId;
+        const sent = sentBySession.get(sessionId) ?? new Set();
+        const pending = [];
+        const pendingIds = [];
+        for (const m of messages) {
+            const role = m.role;
+            if (role === "user") {
+                if (!cfg.hotBuffer.writeUser)
+                    continue;
+            }
+            else if (role === "assistant") {
+                if (!cfg.hotBuffer.writeAssistant)
+                    continue;
+            }
+            else {
+                // Skip system / tool / toolResult — only conversational turns.
+                continue;
+            }
+            let text = extractText(m.content);
+            if (text.length === 0)
+                continue;
+            if (text.length > MAX_CONTENT_CHARS) {
+                log.warn(`hot-buffer: truncating ${role} message ${text.length} -> ${MAX_CONTENT_CHARS} chars`);
+                text = text.slice(0, MAX_CONTENT_CHARS);
+            }
+            const id = messageId(role, text);
+            if (sent.has(id))
+                continue;
+            pending.push({ resourceId, messageId: id, content: text });
+            pendingIds.push(id);
+        }
+        if (pending.length === 0)
+            return;
+        // Chunk by count AND cumulative content size to stay under the 422 limits.
+        const batches = [];
+        let batch = [];
+        let batchChars = 0;
+        for (const item of pending) {
+            if (batch.length >= MAX_BATCH ||
+                (batch.length > 0 && batchChars + item.content.length > MAX_TOTAL_CHARS)) {
+                batches.push(batch);
+                batch = [];
+                batchChars = 0;
+            }
+            batch.push(item);
+            batchChars += item.content.length;
+        }
+        if (batch.length > 0)
+            batches.push(batch);
+        try {
+            let total = 0;
+            for (const b of batches) {
+                // Do NOT tag hot rows with metadata: a POST /messages write that
+                // carries `metadata` is accepted (200) but the row never becomes
+                // retrievable (verified live, post-Hyperspell #1921) — tagging
+                // silently breaks hot-buffer recall. The tag isn't needed anyway:
+                // untagged rows survive the unconditional {$ne:"agent_end"} exclude
+                // (absent-field semantics, #1921) AND are full-text searchable. So
+                // we write content only. (Backend follow-up: make /messages metadata
+                // not suppress indexing, then this can be reinstated.)
+                const result = await client.sendMessages(b, {
+                    userId,
+                    source: cfg.hotBuffer.source,
+                });
+                total += result.count;
+            }
+            // Only mark as sent after a successful write so a failure retries next turn.
+            for (const id of pendingIds)
+                sent.add(id);
+            sentBySession.set(sessionId, sent);
+            log.info(`hot-buffer: wrote ${total} message(s) to ${sessionId} (user=${userId})`);
+        }
+        catch (err) {
+            // Fire-and-forget — never break the turn.
+            log.error("hot-buffer write failed", err);
+        }
+    };
+}
+/** Drop the per-session sent-set on session end to avoid unbounded growth. */
+export function buildHotBufferSessionCleanupHandler() {
+    return (event) => {
+        const sessionId = event.sessionId;
+        if (sessionId)
+            sentBySession.delete(sessionId);
+    };
+}

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

@@ -6,8 +6,9 @@ import { buildAutoContextHandler } from "./hooks/auto-context.js";
 import { buildAutoTraceHandler } from "./hooks/auto-trace.js";
 import { buildEmotionalStateCompactionHandler, buildEmotionalStateFetchHandler, buildEmotionalStateSessionCleanupHandler, buildEmotionalStateStoreHandler, } from "./hooks/emotional-state.js";
 import { buildFileSyncHandler, syncMemoriesOnStartup } from "./hooks/memory-sync.js";
+import { 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";
@@ -73,33 +74,55 @@ 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));
         }
+        // Register hot-buffer hook: write each turn to POST /messages so it's
+        // instantly full-text searchable (vs. the slow /memories embedding path).
+        if (cfg.hotBuffer.enabled) {
+            api.on("agent_end", buildHotBufferHandler(client, cfg));
+            api.on("session_end", buildHotBufferSessionCleanupHandler());
+        }
         // Register memory sync hook
         if (cfg.syncMemories) {
             const fileSyncHandler = buildFileSyncHandler(client, cfg);

package/dist/lib/filters.js

@@ -7,24 +7,57 @@
  * convention `buildScopeFilter` uses (`openclaw_scope`, `openclaw_user`).
  */
 /**
- * Memories produced by session-end hooks (auto-trace, emotional-state) are
- * tagged in metadata as `openclaw_source: "agent_end"` (see `sendTrace` in
- * client.ts). Those should NOT surface via generic retrieval: the
- * emotional-state hook injects them through its own dedicated path, and
- * replaying whole sanitized transcripts back into context creates a
- * self-amplifying pollution loop. Exclude them at the search filter.
+ * Memories produced by the auto-trace session-end hook are tagged in metadata
+ * as `openclaw_source: "agent_end"` (see `sendTrace` in client.ts). Those should
+ * NOT surface via generic retrieval — replaying whole sanitized transcripts back
+ * into context creates a self-amplifying pollution loop. Exclude them here.
  *
- * NOTE: an earlier version of this filter checked the top-level `source` field
- * for the value `"openclaw_agent_end"` — wrong on BOTH counts (the tag lives in
- * metadata under `openclaw_source`, and its value is `"agent_end"`), so it
- * silently matched nothing and excluded no traces.
+ * 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
+ * `openclaw_source`, value `"agent_end"`), so it silently matched nothing.
  */
 export const EXCLUDE_SESSION_END_FILTER = {
     openclaw_source: { $ne: "agent_end" },
 };
-/** Combine a caller-supplied filter with the session-end exclude via `$and`. */
-export function mergeWithExclude(base) {
+/**
+ * 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).
+ *
+ * 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;
+}
+/**
+ * Combine a caller-supplied filter with the session-end exclude via `$and`.
+ * Returns `undefined` when neither a base filter nor an exclude applies.
+ */
+export function mergeWithExclude(base, cfg) {
+    const exclude = excludeFilterFor(cfg);
+    if (!exclude)
+        return base;
     if (!base)
-        return EXCLUDE_SESSION_END_FILTER;
-    return { $and: [base, EXCLUDE_SESSION_END_FILTER] };
+        return exclude;
+    return { $and: [base, exclude] };
 }

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) {
@@ -11,7 +12,7 @@ export function createSearchToolFactory(client, cfg) {
     return (ctx) => ({
         name: "hyperspell_search",
         label: "Memory Search",
-        description: "Search through the user's connected sources (Notion, Slack, Gmail, Google Drive, etc.) for relevant information.",
+        description: "Search the user's long-term memory and connected sources for anything not already in the current conversation. Covers: saved memories and notes; past conversations — including ones from earlier or parallel sessions you have no transcript for; and connected sources (Notion, Slack, Gmail, Google Drive, etc.). Reach for this whenever the user refers to something from before, asks what was said / decided / remembered, or when relevant context likely exists but isn't in front of you — search before concluding you don't know.",
         parameters: Type.Object({
             query: Type.String({ description: "Search query" }),
             limit: Type.Optional(Type.Number({ description: "Max results (default: 5)" })),
@@ -41,7 +42,7 @@ export function createSearchToolFactory(client, cfg) {
             }
             // Keep session-end trace memories out of agent-facing search, matching
             // the auto-context hook so both retrieval paths filter identically.
-            filter = mergeWithExclude(filter);
+            filter = mergeWithExclude(filter, cfg);
             log.debug(`search tool: query="${params.query}" limit=${limit} after=${params.after ?? "none"} before=${params.before ?? "none"} userId=${userId} scope=${params.scope ?? "any"}`);
             try {
                 const response = await client.searchRaw(params.query, {
@@ -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/openclaw.plugin.json

@@ -36,6 +36,11 @@
 			"help": "Automatically send conversation traces to Hyperspell for memory extraction (procedural, mood) at the end of each session",
 			"advanced": true
 		},
+		"hotBuffer": {
+			"label": "Hot Buffer",
+			"help": "Write each turn to the realtime message buffer (POST /messages) so it is instantly full-text searchable, then auto-consolidated into vault Resources. Requires userId. { enabled, source, writeUser, writeAssistant }",
+			"advanced": true
+		},
 		"emotionalContext": {
 			"label": "Emotional Context",
 			"help": "Maintain emotional continuity across sessions — remembers not just what happened, but how it felt",
@@ -116,6 +121,15 @@
 					"metadata": { "type": "object" }
 				}
 			},
+			"hotBuffer": {
+				"type": "object",
+				"properties": {
+					"enabled": { "type": "boolean" },
+					"source": { "type": "string" },
+					"writeUser": { "type": "boolean" },
+					"writeAssistant": { "type": "boolean" }
+				}
+			},
 			"emotionalContext": {
 				"type": "boolean"
 			},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.14.2",
+  "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/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": [