@hyperspell/openclaw-hyperspell 0.11.0 → 0.12.0

package/hooks/auto-context.ts

@@ -8,6 +8,25 @@ import {
 } 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)
@@ -91,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,
@@ -141,6 +163,7 @@ async function multiUserSearch(
     ? client.search(prompt, {
         limit: cfg.maxResults,
         userId: resolved!.userId,
+        filter: EXCLUDE_SESSION_END_FILTER,
       })
     : null
 
@@ -153,7 +176,7 @@ async function multiUserSearch(
       ? client.search(prompt, {
           limit: sharedLimit,
           userId: multiUser.sharedUserId,
-          filter: scopeFilter,
+          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",

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));
 		}
 

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
 	"id": "openclaw-hyperspell",
 	"name": "Hyperspell",
 	"description": "Context and memory for your AI agents — search across Notion, Slack, Google Drive, and more",
-	"version": "0.7.2",
+	"version": "0.12.0",
 	"kind": "memory",
 	"uiHints": {
 		"apiKey": {
@@ -69,6 +69,10 @@
 			"label": "Multi-User Support",
 			"help": "Per-sender context isolation for household or shared-device setups. Maps senders to user IDs; supports optional role-based privacy scopes (private/family/parent-only/etc).",
 			"advanced": true
+		},
+		"dreaming": {
+			"label": "Dreaming",
+			"help": "Optional dreaming config consumed by memory-core when this plugin owns the memory slot. Lets memory-core's dreaming engine consolidate local session transcripts into workspace/MEMORY.md on cron."
 		}
 	},
 	"configSchema": {
@@ -161,6 +165,9 @@
 						}
 					}
 				}
+			},
+			"dreaming": {
+				"type": "object"
 			}
 		},
 		"required": []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
   "description": "OpenClaw Hyperspell memory plugin",
   "license": "MIT",
@@ -43,7 +43,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 config.test.ts"
+    "test": "node --test --experimental-strip-types lib/sender.test.ts config.test.ts hooks/auto-trace.test.ts hooks/emotional-state.test.ts"
   },
   "openclaw": {
     "extensions": [