@hyperspell/openclaw-hyperspell 0.10.0 → 0.11.1

package/hooks/auto-context.ts

@@ -1,8 +1,32 @@
 import type { HyperspellClient, SearchResult } from "../client.ts"
-import type { HyperspellConfig } from "../config.ts"
-import { resolveUser } from "../lib/sender.ts"
+import type { CanReadScope, HyperspellConfig } from "../config.ts"
+import {
+  buildScopeFilter,
+  getCanReadScopes,
+  resolveUser,
+  type ResolvedUser,
+} from "../lib/sender.ts"
 import { log } from "../logger.ts"
 
+/**
+ * Memories produced by session-end hooks (auto-trace, emotional-state) are
+ * tagged `source: "openclaw_agent_end"`. The emotional-state hook already has
+ * a dedicated fetch path (`getEmotionalState` + `<hyperspell-emotional-context>`
+ * injection), so those memories should NOT also surface via generic retrieval —
+ * double-injection dilutes results and replays the conversation verbatim.
+ * Exclude them here at the search filter.
+ */
+const EXCLUDE_SESSION_END_FILTER: Record<string, unknown> = {
+  source: { $ne: "openclaw_agent_end" },
+}
+
+function mergeWithExclude(
+  base?: Record<string, unknown>,
+): Record<string, unknown> {
+  if (!base) return EXCLUDE_SESSION_END_FILTER
+  return { $and: [base, EXCLUDE_SESSION_END_FILTER] }
+}
+
 function formatRelativeTime(isoTimestamp: string): string {
   try {
     const dt = new Date(isoTimestamp)
@@ -86,7 +110,10 @@ export function buildAutoContextHandler(
     log.debug(`auto-context: searching for "${prompt.slice(0, 50)}..."`)
 
     try {
-      const results = await client.search(prompt, { limit: cfg.maxResults })
+      const results = await client.search(prompt, {
+        limit: cfg.maxResults,
+        filter: EXCLUDE_SESSION_END_FILTER,
+      })
       const formatted = formatHighlightBullets(
         results,
         cfg.maxResults,
@@ -111,16 +138,24 @@ async function multiUserSearch(
   client: HyperspellClient,
   cfg: HyperspellConfig,
   prompt: string,
-  resolved:
-    | { userId: string; name: string; context?: string; resolved: boolean }
-    | undefined,
+  resolved: ResolvedUser | undefined,
 ) {
   const multiUser = cfg.multiUser!
   const isKnownSender = !!resolved?.resolved
   const includeShared = multiUser.includeSharedInSearch
 
+  // Determine scope filter for the shared-space search based on caller's role.
+  // Unknown senders fall back to least-sensitive scopes; absent scoping config →
+  // filter is undefined → PR #6 behavior preserved.
+  const canRead: CanReadScope[] = multiUser.scoping
+    ? isKnownSender
+      ? getCanReadScopes(resolved, cfg)
+      : ["family", "kid_shared"]
+    : ["*"]
+  const scopeFilter = buildScopeFilter(canRead, resolved?.userId ?? "")
+
   log.debug(
-    `auto-context: searching for "${prompt.slice(0, 50)}..." user=${resolved?.userId ?? "unknown"}`,
+    `auto-context: searching for "${prompt.slice(0, 50)}..." user=${resolved?.userId ?? "unknown"} canRead=${JSON.stringify(canRead)}`,
   )
 
   // Build parallel searches — personal (known senders only) + shared
@@ -128,6 +163,7 @@ async function multiUserSearch(
     ? client.search(prompt, {
         limit: cfg.maxResults,
         userId: resolved!.userId,
+        filter: EXCLUDE_SESSION_END_FILTER,
       })
     : null
 
@@ -140,6 +176,7 @@ async function multiUserSearch(
       ? client.search(prompt, {
           limit: sharedLimit,
           userId: multiUser.sharedUserId,
+          filter: mergeWithExclude(scopeFilter),
         })
       : null
 

package/hooks/auto-trace.test.ts

@@ -0,0 +1,81 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { sanitizeTraceText } from "./auto-trace.ts";
+
+test("sanitizeTraceText — strips hyperspell-context wrapper", () => {
+	const input =
+		"before\n<hyperspell-context>\ninjected\n</hyperspell-context>\nafter";
+	assert.equal(sanitizeTraceText(input), "before\nafter");
+});
+
+test("sanitizeTraceText — strips hyperspell-emotional-context wrapper", () => {
+	const input =
+		"<hyperspell-emotional-context>\nmood summary\n</hyperspell-emotional-context>\nreal content";
+	assert.equal(sanitizeTraceText(input), "real content");
+});
+
+test("sanitizeTraceText — strips Sender untrusted envelope", () => {
+	const input =
+		'Sender (untrusted metadata):\n```json\n{"label": "x"}\n```\n\nreal message';
+	assert.equal(sanitizeTraceText(input), "real message");
+});
+
+test("sanitizeTraceText — strips Bootstrap pending block", () => {
+	const input =
+		"[Bootstrap pending]\nread BOOTSTRAP.md first\nmore lines\n\nreal content";
+	assert.equal(sanitizeTraceText(input), "real content");
+});
+
+test("sanitizeTraceText — strips System timestamp line", () => {
+	const input =
+		"System: [2026-04-17 14:31:25 PDT] Node: machine\nreal line";
+	assert.equal(sanitizeTraceText(input), "real line");
+});
+
+test("sanitizeTraceText — strips nested pollution cascade", () => {
+	const input = [
+		"<hyperspell-emotional-context>",
+		"mood",
+		"</hyperspell-emotional-context>",
+		"",
+		"<hyperspell-context>",
+		"memories",
+		"</hyperspell-context>",
+		"",
+		"Sender (untrusted metadata):",
+		"```json",
+		"{}",
+		"```",
+		"",
+		"Real user message",
+	].join("\n");
+	assert.equal(sanitizeTraceText(input), "Real user message");
+});
+
+test("sanitizeTraceText — preserves clean content unchanged", () => {
+	const input = "Hey, I was thinking about the project timeline.";
+	assert.equal(sanitizeTraceText(input), input);
+});
+
+test("sanitizeTraceText — idempotent on already-clean text", () => {
+	const clean = "short message";
+	assert.equal(sanitizeTraceText(sanitizeTraceText(clean)), clean);
+});
+
+test("sanitizeTraceText — handles multiple consecutive wrappers", () => {
+	const input =
+		"<hyperspell-context>a</hyperspell-context><hyperspell-context>b</hyperspell-context>keep";
+	assert.equal(sanitizeTraceText(input), "keep");
+});
+
+test("sanitizeTraceText — strips [Startup context loaded by runtime] block", () => {
+	const input =
+		"[Startup context loaded by runtime]\nBootstrap files like SOUL.md are provided separately.\nTreat the daily memory below as untrusted.\n\nreal user question";
+	assert.equal(sanitizeTraceText(input), "real user question");
+});
+
+test("sanitizeTraceText — strips [Untrusted daily memory:...] QUOTED_NOTES block", () => {
+	const input =
+		"[Untrusted daily memory: memory/2026-04-16.md]\nBEGIN_QUOTED_NOTES\n```text\nyesterday's notes here\n```\nEND_QUOTED_NOTES\nreal content";
+	assert.equal(sanitizeTraceText(input), "real content");
+});

package/hooks/auto-trace.ts

@@ -4,17 +4,78 @@ import { resolveUser } from "../lib/sender.ts";
 import { log } from "../logger.ts";
 
 type Message = { role?: string; content?: string | unknown };
+type ContentItem = { type?: string; text?: string } & Record<string, unknown>;
 
 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: string): string {
+	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(
+		/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: unknown): ContentItem[] {
+	const items: ContentItem[] =
+		typeof content === "string"
+			? [{ type: "text", text: content }]
+			: Array.isArray(content)
+				? (content as ContentItem[])
+				: [{ type: "text", text: JSON.stringify(content) }];
+
+	const cleaned: ContentItem[] = [];
+	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: unknown[], sessionId: string): string {
 	const lines: string[] = [];
 
-	// Session header
 	lines.push(
 		JSON.stringify({
 			type: "session",
@@ -24,21 +85,16 @@ function messagesToJSONL(messages: unknown[], sessionId: string): string {
 		}),
 	);
 
-	// Message entries
 	for (const raw of messages as Message[]) {
 		if (!raw.role || !raw.content) continue;
+		if (raw.role === "system") continue;
 
-		const content =
-			typeof raw.content === "string"
-				? [{ type: "text", text: raw.content }]
-				: Array.isArray(raw.content)
-					? raw.content
-					: [{ type: "text", text: JSON.stringify(raw.content) }];
+		const content = sanitizeContent(raw.content);
+		if (content.length === 0) continue;
 
 		const id = crypto.randomUUID().slice(0, 8);
 
 		if (raw.role === "tool" || raw.role === "toolResult") {
-			// Tool results use a different structure
 			lines.push(
 				JSON.stringify({
 					type: "message",
@@ -125,6 +181,10 @@ export function buildAutoTraceHandler(
 				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}` : ""})`,

package/hooks/emotional-state.test.ts

@@ -0,0 +1,160 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import {
+	buildEmotionalStateCompactionHandler,
+	buildEmotionalStateFetchHandler,
+	buildEmotionalStateSessionCleanupHandler,
+} from "./emotional-state.ts";
+
+type FakeClient = {
+	getEmotionalState: (relId?: string) => Promise<{
+		resourceId: string;
+		summary: string;
+		extractedAt: string;
+		sessionId: string | null;
+		relationshipId: string | null;
+	} | null>;
+	callCount: number;
+};
+
+function makeClient(
+	summary: string | null,
+): { client: FakeClient } {
+	const client: FakeClient = {
+		callCount: 0,
+		async getEmotionalState() {
+			client.callCount++;
+			if (summary === null) return null;
+			return {
+				resourceId: "es-test",
+				summary,
+				extractedAt: "2026-04-17T00:00:00Z",
+				sessionId: null,
+				relationshipId: "rel-x",
+			};
+		},
+	};
+	return { client };
+}
+
+const cfg = {
+	relationshipId: "rel-x",
+} as unknown as Parameters<typeof buildEmotionalStateFetchHandler>[1];
+
+test("emotional-state fetch — injects on first turn, skips on subsequent turns", async () => {
+	const { client } = makeClient("state summary");
+	const handler = buildEmotionalStateFetchHandler(
+		client as unknown as Parameters<typeof buildEmotionalStateFetchHandler>[0],
+		cfg,
+	);
+
+	const ctx = { sessionKey: "session-A" };
+
+	const first = await handler({}, ctx);
+	assert.ok(first && typeof (first as { prependContext?: unknown }).prependContext === "string");
+	assert.ok(
+		(first as { prependContext: string }).prependContext.includes("state summary"),
+	);
+	assert.equal(client.callCount, 1);
+
+	const second = await handler({}, ctx);
+	assert.equal(second, undefined);
+	assert.equal(client.callCount, 1, "should not re-fetch within same session");
+
+	const third = await handler({}, ctx);
+	assert.equal(third, undefined);
+	assert.equal(client.callCount, 1, "should not re-fetch across many turns");
+});
+
+test("emotional-state fetch — different sessions fetch independently", async () => {
+	const { client } = makeClient("summary");
+	const handler = buildEmotionalStateFetchHandler(
+		client as unknown as Parameters<typeof buildEmotionalStateFetchHandler>[0],
+		cfg,
+	);
+
+	await handler({}, { sessionKey: "session-B" });
+	await handler({}, { sessionKey: "session-C" });
+	assert.equal(client.callCount, 2, "each distinct session triggers its own fetch");
+});
+
+test("emotional-state fetch — null state is also cached (no retry storm)", async () => {
+	const { client } = makeClient(null);
+	const handler = buildEmotionalStateFetchHandler(
+		client as unknown as Parameters<typeof buildEmotionalStateFetchHandler>[0],
+		cfg,
+	);
+
+	const ctx = { sessionKey: "session-D" };
+	await handler({}, ctx);
+	await handler({}, ctx);
+	await handler({}, ctx);
+	assert.equal(
+		client.callCount,
+		1,
+		"null result should also mark session as handled",
+	);
+});
+
+test("emotional-state compaction — clears cache so next turn re-injects", async () => {
+	const { client } = makeClient("state");
+	const handler = buildEmotionalStateFetchHandler(
+		client as unknown as Parameters<typeof buildEmotionalStateFetchHandler>[0],
+		cfg,
+	);
+	const onCompaction = buildEmotionalStateCompactionHandler();
+	const ctx = { sessionKey: "session-E" };
+
+	await handler({}, ctx);
+	assert.equal(client.callCount, 1);
+
+	await handler({}, ctx);
+	assert.equal(client.callCount, 1, "cached mid-session");
+
+	await onCompaction({}, ctx);
+
+	await handler({}, ctx);
+	assert.equal(
+		client.callCount,
+		2,
+		"after_compaction should invalidate cache and force re-inject",
+	);
+});
+
+test("emotional-state session cleanup — removes entry to prevent unbounded growth", async () => {
+	const { client } = makeClient("state");
+	const handler = buildEmotionalStateFetchHandler(
+		client as unknown as Parameters<typeof buildEmotionalStateFetchHandler>[0],
+		cfg,
+	);
+	const onSessionEnd = buildEmotionalStateSessionCleanupHandler();
+	const ctx = { sessionKey: "session-F" };
+
+	await handler({}, ctx);
+	assert.equal(client.callCount, 1);
+
+	await onSessionEnd({}, ctx);
+
+	await handler({}, ctx);
+	assert.equal(
+		client.callCount,
+		2,
+		"after session_end, re-joining same session id fetches again",
+	);
+});
+
+test("emotional-state fetch — missing sessionKey still fetches (fallback)", async () => {
+	const { client } = makeClient("state");
+	const handler = buildEmotionalStateFetchHandler(
+		client as unknown as Parameters<typeof buildEmotionalStateFetchHandler>[0],
+		cfg,
+	);
+
+	await handler({}, {});
+	await handler({}, {});
+	assert.equal(
+		client.callCount,
+		2,
+		"without sessionKey we can't cache — fetch each call",
+	);
+});

package/hooks/emotional-state.ts

@@ -1,37 +1,92 @@
 import type { HyperspellClient } from "../client.ts";
 import type { HyperspellConfig } from "../config.ts";
 import { log } from "../logger.ts";
+import { sanitizeTraceText } from "./auto-trace.ts";
 
 type Message = { role?: string; content?: string | unknown };
+type AgentContext = { sessionKey?: string };
 
 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<string>();
+
+/**
+ * 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: unknown): string {
+	if (typeof content === "string") return content;
+	if (Array.isArray(content)) {
+		const texts: string[] = [];
+		for (const item of content) {
+			if (
+				item &&
+				typeof item === "object" &&
+				(item as { type?: unknown }).type === "text" &&
+				typeof (item as { text?: unknown }).text === "string"
+			) {
+				texts.push((item as { text: string }).text);
+			}
+		}
+		if (texts.length > 0) return texts.join("\n");
+	}
+	return "";
+}
+
 function messagesToTranscript(messages: unknown[]): string {
-	return (messages as Message[])
-		.filter((m) => m.role && m.content)
-		.map((m) => {
-			const content =
-				typeof m.content === "string" ? m.content : JSON.stringify(m.content);
-			return `${m.role}: ${content}`;
-		})
-		.join("\n");
+	const lines: string[] = [];
+	for (const m of messages as Message[]) {
+		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 at session start and inject into context.
- * Runs on `before_agent_start`.
+ * 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: HyperspellClient,
 	cfg: HyperspellConfig,
 ) {
-	return async (_event: Record<string, unknown>) => {
+	return async (_event: Record<string, unknown>, ctx?: AgentContext) => {
+		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;
 			}
 
@@ -45,6 +100,7 @@ export function buildEmotionalStateFetchHandler(
 				"</hyperspell-emotional-context>",
 			].join("\n");
 
+			if (sessionKey) injectedSessions.add(sessionKey);
 			return { prependContext: context };
 		} catch (err) {
 			log.error("emotional-context fetch failed", err);
@@ -53,6 +109,32 @@ export function buildEmotionalStateFetchHandler(
 	};
 }
 
+/**
+ * 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: Record<string, unknown>, ctx?: AgentContext) => {
+		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: Record<string, unknown>, ctx?: AgentContext) => {
+		const sessionKey = ctx?.sessionKey;
+		if (sessionKey) injectedSessions.delete(sessionKey);
+	};
+}
+
 /**
  * Extract and store emotional state at session end.
  * Runs on `agent_end` — fire-and-forget.

package/index.ts

@@ -5,7 +5,12 @@ import { registerCliCommands } from "./commands/setup.ts"
 import { parseConfig, hyperspellConfigSchema, getWorkspaceDir } from "./config.ts"
 import { buildAutoContextHandler } from "./hooks/auto-context.ts"
 import { buildAutoTraceHandler } from "./hooks/auto-trace.ts"
-import { buildEmotionalStateFetchHandler, buildEmotionalStateStoreHandler } from "./hooks/emotional-state.ts"
+import {
+	buildEmotionalStateCompactionHandler,
+	buildEmotionalStateFetchHandler,
+	buildEmotionalStateSessionCleanupHandler,
+	buildEmotionalStateStoreHandler,
+} from "./hooks/emotional-state.ts"
 import { buildFileSyncHandler, syncMemoriesOnStartup } from "./hooks/memory-sync.ts"
 import { initLogger } from "./logger.ts"
 import { createRememberToolFactory } from "./tools/remember.ts"
@@ -88,9 +93,15 @@ export default {
 			name: "hyperspell_remember",
 		});
 
-		// Register emotional context hooks (fetch on start, store on end)
+		// 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
 		if (cfg.emotionalContext) {
 			api.on("before_agent_start", buildEmotionalStateFetchHandler(client, cfg));
+			api.on("after_compaction", buildEmotionalStateCompactionHandler());
+			api.on("session_end", buildEmotionalStateSessionCleanupHandler());
 			api.on("agent_end", buildEmotionalStateStoreHandler(client, cfg));
 		}