@hyperspell/openclaw-hyperspell 0.8.1 → 0.9.0

package/client.ts

@@ -37,6 +37,25 @@ export type Connection = {
 	provider: HyperspellSource;
 };
 
+export type EmotionalStateResponse = {
+  resourceId: string
+  summary: string
+  extractedAt: string
+  sessionId: string | null
+  relationshipId: string | null
+  status: string
+}
+
+export type EmotionalStateLatest = {
+  resourceId: string
+  summary: string
+  extractedAt: string
+  sessionId: string | null
+  relationshipId: string | null
+}
+
+const API_BASE_URL = "https://api.hyperspell.com"
+
 export class HyperspellClient {
 	private client: Hyperspell;
 	private config: HyperspellConfig;
@@ -52,6 +71,17 @@ export class HyperspellClient {
 		);
 	}
 
+	private rawHeaders(): Record<string, string> {
+		const headers: Record<string, string> = {
+			"Content-Type": "application/json",
+			Authorization: `Bearer ${this.config.apiKey}`,
+		};
+		if (this.config.userId) {
+			headers["X-As-User"] = this.config.userId;
+		}
+		return headers;
+	}
+
 	async search(
 		query: string,
 		options?: { limit?: number; sources?: HyperspellSource[]; after?: string; before?: string },
@@ -325,4 +355,106 @@ export class HyperspellClient {
 		log.debugResponse("connections.list", { count: connections.length });
 		return connections;
 	}
+
+	// -- Emotional State (raw fetch -- not in public SDK) -----------------------
+
+	async storeEmotionalState(
+		conversation: string,
+		options?: {
+			sessionId?: string;
+			relationshipId?: string;
+			metadata?: Record<string, string | number | boolean>;
+		},
+	): Promise<EmotionalStateResponse> {
+		log.debugRequest("emotional-state.store", {
+			conversationLength: conversation.length,
+			relationshipId: options?.relationshipId,
+		});
+
+		const body: Record<string, unknown> = { conversation };
+		if (options?.sessionId) body.session_id = options.sessionId;
+		if (options?.relationshipId) body.relationship_id = options.relationshipId;
+		if (options?.metadata) body.metadata = options.metadata;
+
+		const res = await fetch(`${API_BASE_URL}/emotional-state`, {
+			method: "POST",
+			headers: this.rawHeaders(),
+			body: JSON.stringify(body),
+		});
+
+		if (!res.ok) {
+			const text = await res.text().catch(() => "");
+			throw new Error(`POST /emotional-state failed (${res.status}): ${text}`);
+		}
+
+		const data = await res.json();
+		const result: EmotionalStateResponse = {
+			resourceId: data.resource_id,
+			summary: data.summary,
+			extractedAt: data.extracted_at,
+			sessionId: data.session_id ?? null,
+			relationshipId: data.relationship_id ?? null,
+			status: data.status,
+		};
+
+		log.debugResponse("emotional-state.store", { resourceId: result.resourceId });
+		return result;
+	}
+
+	async getEmotionalState(relationshipId?: string): Promise<EmotionalStateLatest | null> {
+		log.debugRequest("emotional-state.get", { relationshipId });
+
+		const url = new URL(`${API_BASE_URL}/emotional-state`);
+		if (relationshipId) url.searchParams.set("relationship_id", relationshipId);
+
+		const res = await fetch(url.toString(), {
+			method: "GET",
+			headers: this.rawHeaders(),
+		});
+
+		if (!res.ok) {
+			const text = await res.text().catch(() => "");
+			throw new Error(`GET /emotional-state failed (${res.status}): ${text}`);
+		}
+
+		const data = await res.json();
+		if (data === null) {
+			log.debugResponse("emotional-state.get", { found: false });
+			return null;
+		}
+
+		const result: EmotionalStateLatest = {
+			resourceId: data.resource_id,
+			summary: data.summary,
+			extractedAt: data.extracted_at,
+			sessionId: data.session_id ?? null,
+			relationshipId: data.relationship_id ?? null,
+		};
+
+		log.debugResponse("emotional-state.get", { found: true, resourceId: result.resourceId });
+		return result;
+	}
+
+	async deleteEmotionalState(relationshipId?: string): Promise<{ deletedCount: number }> {
+		log.debugRequest("emotional-state.delete", { relationshipId });
+
+		const url = new URL(`${API_BASE_URL}/emotional-state`);
+		if (relationshipId) url.searchParams.set("relationship_id", relationshipId);
+
+		const res = await fetch(url.toString(), {
+			method: "DELETE",
+			headers: this.rawHeaders(),
+		});
+
+		if (!res.ok) {
+			const text = await res.text().catch(() => "");
+			throw new Error(`DELETE /emotional-state failed (${res.status}): ${text}`);
+		}
+
+		const data = await res.json();
+		const result = { deletedCount: data.deleted_count };
+
+		log.debugResponse("emotional-state.delete", result);
+		return result;
+	}
 }

package/commands/setup.ts

@@ -333,6 +333,7 @@ async function runSetup(): Promise<void> {
         userId,
         autoContext: true,
         autoTrace: { enabled: false, extract: ["procedure"] },
+        emotionalContext: false,
         syncMemories: true,
         sources: [],
         maxResults: 10,

package/config.ts

@@ -30,6 +30,8 @@ export type HyperspellConfig = {
 	userId?: string;
 	autoContext: boolean;
 	autoTrace: AutoTraceConfig;
+	emotionalContext: boolean;
+	relationshipId?: string;
 	syncMemories: boolean;
 	sources: HyperspellSource[];
 	maxResults: number;
@@ -43,6 +45,8 @@ const ALLOWED_KEYS = [
 	"userId",
 	"autoContext",
 	"autoTrace",
+	"emotionalContext",
+	"relationshipId",
 	"syncMemories",
 	"sources",
 	"maxResults",
@@ -168,6 +172,8 @@ export function parseConfig(raw: unknown): HyperspellConfig {
 				| Record<string, string | number | boolean>
 				| undefined,
 		},
+		emotionalContext: (cfg.emotionalContext as boolean) ?? false,
+		relationshipId: cfg.relationshipId as string | undefined,
 		syncMemories: (cfg.syncMemories as boolean) ?? false,
 		sources: parseSources(cfg.sources as string | string[] | undefined),
 		maxResults: (cfg.maxResults as number) ?? 10,

package/hooks/emotional-state.ts

@@ -0,0 +1,97 @@
+import type { HyperspellClient } from "../client.ts";
+import type { HyperspellConfig } from "../config.ts";
+import { log } from "../logger.ts";
+
+type Message = { role?: string; content?: string | unknown };
+
+const MIN_MESSAGES = 3;
+const MIN_CONVERSATION_LENGTH = 100;
+
+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");
+}
+
+/**
+ * Fetch emotional state at session start and inject into context.
+ * Runs on `before_agent_start`.
+ */
+export function buildEmotionalStateFetchHandler(
+	client: HyperspellClient,
+	cfg: HyperspellConfig,
+) {
+	return async (_event: Record<string, unknown>) => {
+		try {
+			const state = await client.getEmotionalState(cfg.relationshipId);
+
+			if (!state) {
+				log.debug("emotional-context: no prior emotional state found");
+				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");
+
+			return { prependContext: context };
+		} catch (err) {
+			log.error("emotional-context fetch failed", err);
+			return;
+		}
+	};
+}
+
+/**
+ * Extract and store emotional state at session end.
+ * Runs on `agent_end` — fire-and-forget.
+ */
+export function buildEmotionalStateStoreHandler(
+	client: HyperspellClient,
+	cfg: HyperspellConfig,
+) {
+	return async (event: Record<string, unknown>) => {
+		if (event.success === false) {
+			log.debug("emotional-state: skipping — agent ended with error");
+			return;
+		}
+
+		const messages = event.messages as unknown[] | undefined;
+		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/index.ts

@@ -5,6 +5,7 @@ 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 { buildFileSyncHandler, syncMemoriesOnStartup } from "./hooks/memory-sync.ts"
 import { initLogger } from "./logger.ts"
 import { registerRememberTool } from "./tools/remember.ts"
@@ -83,6 +84,12 @@ export default {
 		registerSearchTool(api, client, cfg);
 		registerRememberTool(api, client, cfg);
 
+		// Register emotional context hooks (fetch on start, store on end)
+		if (cfg.emotionalContext) {
+			api.on("before_agent_start", buildEmotionalStateFetchHandler(client, cfg));
+			api.on("agent_end", buildEmotionalStateStoreHandler(client, cfg));
+		}
+
 		// Register auto-context hook
 		if (cfg.autoContext) {
 			const autoContextHandler = buildAutoContextHandler(client, cfg);

package/openclaw.plugin.json

@@ -27,6 +27,17 @@
 			"help": "Automatically send conversation traces to Hyperspell for memory extraction (procedural, mood) at the end of each session",
 			"advanced": true
 		},
+		"emotionalContext": {
+			"label": "Emotional Context",
+			"help": "Maintain emotional continuity across sessions — remembers not just what happened, but how it felt",
+			"advanced": true
+		},
+		"relationshipId": {
+			"label": "Relationship ID",
+			"placeholder": "partner-anna",
+			"help": "Optional identifier for per-relationship emotional state (e.g. different registers for different people)",
+			"advanced": true
+		},
 		"sources": {
 			"label": "Sources",
 			"placeholder": "notion,slack,google_drive",
@@ -82,6 +93,12 @@
 					"metadata": { "type": "object" }
 				}
 			},
+			"emotionalContext": {
+				"type": "boolean"
+			},
+			"relationshipId": {
+				"type": "string"
+			},
 			"sources": {
 				"type": "string"
 			},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "type": "module",
   "description": "OpenClaw Hyperspell memory plugin",
   "license": "MIT",