@hyperspell/openclaw-hyperspell 0.12.0 → 0.13.1

package/dist/hooks/auto-trace.js

@@ -0,0 +1,143 @@
+import { resolveUser } from "../lib/sender.js";
+import { log } from "../logger.js";
+const MIN_MESSAGES = 3;
+const MIN_CONVERSATION_LENGTH = 100;
+/**
+ * Strip transport/injection metadata from a text blob before it's stored as a
+ * trace memory. Without this the auto-context and emotional-state hooks'
+ * prepended wrappers get captured verbatim, extracted as "memory content",
+ * and then surface again on the next session's retrieval — a self-amplifying
+ * pollution loop.
+ */
+export function sanitizeTraceText(input) {
+    let out = input;
+    out = out.replace(/<hyperspell-context>[\s\S]*?<\/hyperspell-context>\n?/g, "");
+    out = out.replace(/<hyperspell-emotional-context>[\s\S]*?<\/hyperspell-emotional-context>\n?/g, "");
+    out = out.replace(/<hyperspell-recent-interactions>[\s\S]*?<\/hyperspell-recent-interactions>\n?/g, "");
+    out = out.replace(/<hyperspell-unfinished-loops>[\s\S]*?<\/hyperspell-unfinished-loops>\n?/g, "");
+    out = out.replace(/Sender \(untrusted metadata\):\s*```json[\s\S]*?```\n?/g, "");
+    out = out.replace(/\[Bootstrap pending\][\s\S]*?(?=\n{2,}|\nSystem:|\nSender|$)/g, "");
+    out = out.replace(/\[Startup context loaded by runtime\][\s\S]*?(?:\n\n|$)/g, "");
+    out = out.replace(/\[Untrusted daily memory:[^\]]*\][\s\S]*?END_QUOTED_NOTES\n?/g, "");
+    out = out.replace(/^System(?:\s+\(untrusted\))?:\s*\[[^\]]+\][^\n]*\n?/gm, "");
+    out = out.replace(/\n{3,}/g, "\n\n").trim();
+    return out;
+}
+function sanitizeContent(content) {
+    const items = typeof content === "string"
+        ? [{ type: "text", text: content }]
+        : Array.isArray(content)
+            ? content
+            : [{ type: "text", text: JSON.stringify(content) }];
+    const cleaned = [];
+    for (const item of items) {
+        if (item?.type === "text" && typeof item.text === "string") {
+            const text = sanitizeTraceText(item.text);
+            if (text.length > 0)
+                cleaned.push({ ...item, text });
+        }
+        else if (item) {
+            cleaned.push(item);
+        }
+    }
+    return cleaned;
+}
+/**
+ * Convert event.messages into OpenClaw JSONL format for the trace API.
+ */
+function messagesToJSONL(messages, sessionId) {
+    const lines = [];
+    lines.push(JSON.stringify({
+        type: "session",
+        version: 3,
+        id: sessionId,
+        timestamp: new Date().toISOString(),
+    }));
+    for (const raw of messages) {
+        if (!raw.role || !raw.content)
+            continue;
+        if (raw.role === "system")
+            continue;
+        const content = sanitizeContent(raw.content);
+        if (content.length === 0)
+            continue;
+        const id = crypto.randomUUID().slice(0, 8);
+        if (raw.role === "tool" || raw.role === "toolResult") {
+            lines.push(JSON.stringify({
+                type: "message",
+                id,
+                timestamp: new Date().toISOString(),
+                message: {
+                    role: "toolResult",
+                    toolCallId: raw.toolCallId ?? id,
+                    toolName: raw.toolName ?? "unknown",
+                    content,
+                    isError: raw.isError ?? false,
+                },
+            }));
+        }
+        else {
+            lines.push(JSON.stringify({
+                type: "message",
+                id,
+                timestamp: new Date().toISOString(),
+                message: { role: raw.role, content },
+            }));
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Extract and store conversation trace at session end.
+ * Runs on `agent_end` — fire-and-forget.
+ */
+export function buildAutoTraceHandler(client, cfg) {
+    return async (event, ctx) => {
+        if (event.success === false) {
+            log.debug("auto-trace: skipping — agent ended with error");
+            return;
+        }
+        const messages = event.messages;
+        if (!messages || messages.length < MIN_MESSAGES) {
+            log.debug(`auto-trace: skipping — too few messages (${messages?.length ?? 0})`);
+            return;
+        }
+        // Quick content length check
+        const estimate = messages
+            .filter((m) => m.content)
+            .reduce((acc, m) => acc + String(m.content).length, 0);
+        if (estimate < MIN_CONVERSATION_LENGTH) {
+            log.debug(`auto-trace: skipping — conversation too short (${estimate} chars)`);
+            return;
+        }
+        const sessionId = event.sessionId ?? crypto.randomUUID();
+        const history = messagesToJSONL(messages, sessionId);
+        // Title from first user message
+        const firstUser = messages.find((m) => m.role === "user");
+        const title = firstUser?.content
+            ? String(firstUser.content).slice(0, 80).replace(/\n/g, " ")
+            : undefined;
+        // Resolve sender → userId so traces land in the right user's space.
+        // Falls back to sharedUserId for unknown senders (or undefined in single-user mode).
+        const resolved = resolveUser(ctx, cfg);
+        const userId = resolved?.userId;
+        try {
+            const result = await client.sendTrace(history, {
+                sessionId,
+                title,
+                extract: cfg.autoTrace.extract,
+                metadata: cfg.autoTrace.metadata,
+                userId,
+                // Auto-trace captures full conversation text — the most sensitive class
+                // of memory. Default to private; users opt into family-visible recall
+                // via explicit /remember.
+                scope: "private",
+            });
+            log.info(`auto-trace: sent ${result.resourceId} (${messages.length} messages${userId ? `, user=${userId}` : ""})`);
+        }
+        catch (err) {
+            // Fire-and-forget — never break the session
+            log.error("auto-trace failed", err);
+        }
+    };
+}

package/dist/hooks/emotional-state.js

@@ -0,0 +1,155 @@
+import { log } from "../logger.js";
+import { sanitizeTraceText } from "./auto-trace.js";
+const MIN_MESSAGES = 3;
+const MIN_CONVERSATION_LENGTH = 100;
+/**
+ * Sessions where emotional context has already been injected this run.
+ * Emotional state doesn't change within a session (it's extracted at
+ * agent_end and surfaces on the *next* session), so re-fetching and
+ * re-injecting on every turn is pure cost — one API call and a few
+ * hundred tokens of repeated wrapper per turn.
+ *
+ * Lifecycle:
+ *  - first before_agent_start in a session: fetch, inject, mark.
+ *  - subsequent turns in same session: skip (return undefined).
+ *  - after_compaction: clear the mark so the next turn re-injects (the
+ *    initial injection may have been compacted out of history).
+ *  - session_end: clean up to prevent unbounded Set growth.
+ */
+const injectedSessions = new Set();
+/**
+ * Extract readable text from a message content, unwrapping the common
+ * `[{ type: "text", text: "..." }]` array shape so sanitizeTraceText can
+ * operate on real text (not JSON-stringified content where newlines would
+ * be escaped and regex line-anchors wouldn't match).
+ */
+function contentToText(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        const texts = [];
+        for (const item of content) {
+            if (item &&
+                typeof item === "object" &&
+                item.type === "text" &&
+                typeof item.text === "string") {
+                texts.push(item.text);
+            }
+        }
+        if (texts.length > 0)
+            return texts.join("\n");
+    }
+    return "";
+}
+function messagesToTranscript(messages) {
+    const lines = [];
+    for (const m of messages) {
+        if (!m.role || !m.content)
+            continue;
+        if (m.role === "system")
+            continue;
+        const raw = contentToText(m.content);
+        if (!raw)
+            continue;
+        const cleaned = sanitizeTraceText(raw);
+        if (cleaned.length === 0)
+            continue;
+        lines.push(`${m.role}: ${cleaned}`);
+    }
+    return lines.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
+ * injection from the first turn is already in the conversation history.
+ *
+ * Runs on `before_agent_start` (which fires every turn).
+ */
+export function buildEmotionalStateFetchHandler(client, cfg) {
+    return async (_event, ctx) => {
+        const sessionKey = ctx?.sessionKey;
+        if (sessionKey && injectedSessions.has(sessionKey)) {
+            return;
+        }
+        try {
+            const state = await client.getEmotionalState(cfg.relationshipId);
+            if (!state) {
+                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");
+            if (sessionKey)
+                injectedSessions.add(sessionKey);
+            return { prependContext: context };
+        }
+        catch (err) {
+            log.error("emotional-context fetch failed", err);
+            return;
+        }
+    };
+}
+/**
+ * After compaction, the emotional-context block from the first turn may have
+ * been trimmed out of history. Clear the cache so the next turn re-injects.
+ */
+export function buildEmotionalStateCompactionHandler() {
+    return async (_event, ctx) => {
+        const sessionKey = ctx?.sessionKey;
+        if (sessionKey && injectedSessions.delete(sessionKey)) {
+            log.debug(`emotional-context: cache cleared after compaction (session=${sessionKey})`);
+        }
+    };
+}
+/**
+ * Remove session from the inject-once cache when the session ends, to keep the
+ * Set from growing unbounded over process lifetime.
+ */
+export function buildEmotionalStateSessionCleanupHandler() {
+    return async (_event, ctx) => {
+        const sessionKey = ctx?.sessionKey;
+        if (sessionKey)
+            injectedSessions.delete(sessionKey);
+    };
+}
+/**
+ * Extract and store emotional state at session end.
+ * Runs on `agent_end` — fire-and-forget.
+ */
+export function buildEmotionalStateStoreHandler(client, cfg) {
+    return async (event) => {
+        if (event.success === false) {
+            log.debug("emotional-state: skipping — agent ended with error");
+            return;
+        }
+        const messages = event.messages;
+        if (!messages || messages.length < MIN_MESSAGES) {
+            log.debug(`emotional-state: skipping — too few messages (${messages?.length ?? 0})`);
+            return;
+        }
+        const transcript = messagesToTranscript(messages);
+        if (transcript.length < MIN_CONVERSATION_LENGTH) {
+            log.debug(`emotional-state: skipping — conversation too short (${transcript.length} chars)`);
+            return;
+        }
+        try {
+            const result = await client.storeEmotionalState(transcript, {
+                relationshipId: cfg.relationshipId,
+                metadata: { source: "openclaw_agent_end" },
+            });
+            log.info(`emotional-state: stored ${result.resourceId}`);
+        }
+        catch (err) {
+            // Fire-and-forget — never let this break the session
+            log.error("emotional-state store failed", err);
+        }
+    };
+}

package/dist/hooks/memory-sync.js

@@ -0,0 +1,54 @@
+import * as path from "node:path";
+import { getWorkspaceDir } from "../config.js";
+import { log } from "../logger.js";
+import { syncMarkdownFile, syncAllMemoryFiles } from "../sync/markdown.js";
+/**
+ * Build a handler for file change events that syncs markdown files to Hyperspell
+ */
+export function buildFileSyncHandler(client, cfg) {
+    const workspaceDir = getWorkspaceDir();
+    const memoryDir = path.join(workspaceDir, "memory");
+    const syncUserId = cfg.multiUser?.sharedUserId;
+    return async (event) => {
+        const filePath = event.file_path;
+        if (!filePath)
+            return;
+        // Only process markdown files in the workspace's memory directory
+        if (!filePath.startsWith(memoryDir) || !filePath.endsWith(".md")) {
+            return;
+        }
+        const fileName = path.basename(filePath);
+        log.info(`Memory file changed: ${fileName}`);
+        try {
+            const result = await syncMarkdownFile(client, filePath, { userId: syncUserId });
+            if (result.success) {
+                log.info(`Synced ${fileName} -> ${result.resourceId}`);
+            }
+            else {
+                log.error(`Failed to sync ${fileName}: ${result.error}`);
+            }
+        }
+        catch (err) {
+            log.error(`Error syncing ${fileName}`, err);
+        }
+    };
+}
+/**
+ * Sync all existing memory files on startup
+ */
+export async function syncMemoriesOnStartup(client, workspaceDir, options) {
+    log.info("Syncing existing memory files...");
+    const result = await syncAllMemoryFiles(client, workspaceDir, { userId: options?.userId });
+    if (result.synced > 0) {
+        log.info(`Synced ${result.synced} memory files`);
+    }
+    if (result.failed > 0) {
+        log.error(`Failed to sync ${result.failed} files:`);
+        for (const error of result.errors) {
+            log.error(`  - ${error}`);
+        }
+    }
+    if (result.synced === 0 && result.failed === 0) {
+        log.info("No memory files found in memory/ directory");
+    }
+}

package/dist/hooks/startup-orientation.js

@@ -0,0 +1,236 @@
+import { resolveUser } from "../lib/sender.js";
+import { log } from "../logger.js";
+const MAX_ATTEMPTS = 2;
+const RECENT_BUFFER_LIMIT = 100;
+/**
+ * Sessions where the orientation block was already injected (or where we
+ * deliberately decided not to inject — unknown sender, exhausted retries).
+ * Re-checked at the top of every turn; on hit, we skip.
+ *
+ * Lifecycle mirrors the emotional-context hook: `after_compaction` clears
+ * (the original injection may have been trimmed out of history) and
+ * `session_end` cleans up to keep both structures bounded.
+ */
+const injectedSessions = new Set();
+/**
+ * Counts attempts for sessions where every call has failed so far. We only
+ * count failures here, so a session that succeeds on retry will never appear.
+ * Capped at MAX_ATTEMPTS — past that we give up and add to injectedSessions.
+ */
+const failedAttempts = new Map();
+function formatRelativeTime(iso) {
+    if (!iso)
+        return "";
+    try {
+        const dt = new Date(iso);
+        const now = new Date();
+        const hours = (now.getTime() - dt.getTime()) / 3_600_000;
+        if (hours < 1)
+            return "just now";
+        if (hours < 24)
+            return `${Math.floor(hours)}h ago`;
+        const days = hours / 24;
+        if (days < 7)
+            return `${Math.floor(days)}d ago`;
+        const month = dt.toLocaleString("en", { month: "short" });
+        return `${dt.getDate()} ${month}`;
+    }
+    catch {
+        return "";
+    }
+}
+function formatRecentInteractions(results) {
+    if (results.length === 0)
+        return null;
+    const lines = results.map((r) => {
+        const when = formatRelativeTime(r.createdAt);
+        const title = r.title || `[${r.source}]`;
+        const prefix = when ? `[${when}] ` : "";
+        const top = r.highlights[0]?.text?.replace(/\n/g, " ").slice(0, 140);
+        const tail = top ? ` — ${top}` : "";
+        return `- ${prefix}${title}${tail}`;
+    });
+    return lines.join("\n");
+}
+function formatUnfinishedLoops(results) {
+    const bullets = [];
+    for (const r of results) {
+        const top = r.highlights[0];
+        if (!top)
+            continue;
+        const title = r.title || `[${r.source}]`;
+        bullets.push(`- ${title}: ${top.text.replace(/\n/g, " ")}`);
+    }
+    return bullets.length > 0 ? bullets.join("\n") : null;
+}
+function isoDaysAgo(days) {
+    const d = new Date();
+    d.setUTCDate(d.getUTCDate() - days);
+    return d;
+}
+/**
+ * Resolve the userId to use for personal searches. In multi-user mode, skip
+ * entirely for unknown senders — orientation is "what have *I* been doing", and
+ * an unresolved caller has no personal space to orient to. In single-user mode,
+ * return undefined so the client falls back to its configured userId.
+ */
+function personalUserId(cfg, ctx) {
+    if (!cfg.multiUser)
+        return { skip: false, userId: undefined };
+    const resolved = resolveUser(ctx, cfg);
+    if (!resolved?.resolved)
+        return { skip: true };
+    return { skip: false, userId: resolved.userId };
+}
+/**
+ * Pull recent agent_end traces via listMemories, sorted chronologically.
+ *
+ * Why list, not search: a date-window + relevance search ranks results by
+ * lexical similarity to a generic query, which is approximately random
+ * within a 7-day slice and can easily exclude yesterday in favor of a
+ * 5-day-old session. listMemories gives us true chronological recall.
+ *
+ * The SDK's list endpoint doesn't expose date or metadata filters in our
+ * wrapper, so we filter client-side. Buffer is capped at
+ * RECENT_BUFFER_LIMIT to bound wire cost; if a user has more than that
+ * many traces in the cutoff window we'll still get the newest ones,
+ * since the underlying API returns recency-ordered pages.
+ */
+async function fetchRecentTraces(client, cutoff, limit, userId) {
+    const buffer = [];
+    let scanned = 0;
+    const cutoffMs = cutoff.getTime();
+    for await (const memory of client.listMemories({
+        source: "trace",
+        userId,
+        pageSize: 50,
+    })) {
+        scanned++;
+        if (scanned > RECENT_BUFFER_LIMIT)
+            break;
+        const meta = memory.metadata;
+        if (meta.openclaw_source !== "agent_end")
+            continue;
+        const createdRaw = meta.created_at;
+        if (typeof createdRaw !== "string")
+            continue;
+        const createdMs = new Date(createdRaw).getTime();
+        if (Number.isNaN(createdMs) || createdMs < cutoffMs)
+            continue;
+        buffer.push({
+            resourceId: memory.resourceId,
+            title: memory.title,
+            source: memory.source,
+            score: null,
+            url: null,
+            createdAt: createdRaw,
+            highlights: [],
+        });
+    }
+    buffer.sort((a, b) => {
+        const at = a.createdAt ? new Date(a.createdAt).getTime() : 0;
+        const bt = b.createdAt ? new Date(b.createdAt).getTime() : 0;
+        return bt - at;
+    });
+    return buffer.slice(0, limit);
+}
+export function buildStartupOrientationHandler(client, cfg) {
+    const so = cfg.startupOrientation;
+    return async (_event, ctx) => {
+        const sessionKey = ctx?.sessionKey;
+        if (sessionKey && injectedSessions.has(sessionKey))
+            return;
+        const tries = (sessionKey && failedAttempts.get(sessionKey)) || 0;
+        if (tries >= MAX_ATTEMPTS) {
+            log.debug(`startup-orientation: giving up after ${tries} failed attempt(s)`);
+            if (sessionKey) {
+                injectedSessions.add(sessionKey);
+                failedAttempts.delete(sessionKey);
+            }
+            return;
+        }
+        const { skip, userId } = personalUserId(cfg, ctx);
+        if (skip) {
+            log.debug("startup-orientation: skipping — unknown sender in multi-user mode");
+            if (sessionKey)
+                injectedSessions.add(sessionKey);
+            return;
+        }
+        const cutoff = isoDaysAgo(so.recentDays);
+        const [recentSettled, loopsSettled] = await Promise.allSettled([
+            fetchRecentTraces(client, cutoff, so.recentLimit, userId),
+            client.search(so.loopsQuery, {
+                limit: so.loopsLimit,
+                userId,
+            }),
+        ]);
+        const recentOk = recentSettled.status === "fulfilled";
+        const loopsOk = loopsSettled.status === "fulfilled";
+        const recent = recentOk ? recentSettled.value : [];
+        const loops = loopsOk ? loopsSettled.value : [];
+        if (!recentOk) {
+            log.error("startup-orientation: recent listMemories failed", recentSettled.reason);
+        }
+        if (!loopsOk) {
+            log.error("startup-orientation: loops search failed", loopsSettled.reason);
+        }
+        if (!recentOk && !loopsOk) {
+            if (sessionKey)
+                failedAttempts.set(sessionKey, tries + 1);
+            log.debug(`startup-orientation: both calls failed (attempt ${tries + 1}/${MAX_ATTEMPTS}); will retry next turn`);
+            return;
+        }
+        if (sessionKey) {
+            injectedSessions.add(sessionKey);
+            failedAttempts.delete(sessionKey);
+        }
+        const recentBody = formatRecentInteractions(recent);
+        const loopsBody = formatUnfinishedLoops(loops);
+        if (!recentBody && !loopsBody) {
+            log.debug("startup-orientation: nothing to inject");
+            return;
+        }
+        const blocks = [];
+        if (recentBody) {
+            blocks.push([
+                "<hyperspell-recent-interactions>",
+                `Your last ${so.recentDays} days of conversations with this user, most-recent-first. Use for situational continuity — don't quote verbatim.`,
+                "",
+                recentBody,
+                "</hyperspell-recent-interactions>",
+            ].join("\n"));
+        }
+        if (loopsBody) {
+            blocks.push([
+                "<hyperspell-unfinished-loops>",
+                "Possible open threads — promises made, questions pending, work in progress. Low-confidence retrieval; treat as prompts to consider, not facts to act on.",
+                "",
+                loopsBody,
+                "</hyperspell-unfinished-loops>",
+            ].join("\n"));
+        }
+        log.debug(`startup-orientation: injecting recent=${recent.length} loops=${loops.length}`);
+        return { prependContext: blocks.join("\n\n") };
+    };
+}
+export function buildStartupOrientationCompactionHandler() {
+    return async (_event, ctx) => {
+        const sessionKey = ctx?.sessionKey;
+        if (!sessionKey)
+            return;
+        const dropped = injectedSessions.delete(sessionKey);
+        failedAttempts.delete(sessionKey);
+        if (dropped) {
+            log.debug(`startup-orientation: cache cleared after compaction (session=${sessionKey})`);
+        }
+    };
+}
+export function buildStartupOrientationSessionCleanupHandler() {
+    return async (_event, ctx) => {
+        const sessionKey = ctx?.sessionKey;
+        if (!sessionKey)
+            return;
+        injectedSessions.delete(sessionKey);
+        failedAttempts.delete(sessionKey);
+    };
+}