@hyperspell/openclaw-hyperspell 0.8.0 → 0.9.0

package/README.md

@@ -7,9 +7,11 @@ OpenClaw plugin for [Hyperspell](https://hyperspell.com) - Context and memory fo
 ## Installation
 
 ```bash
-openclaw plugins install @hyperspell/openclaw-hyperspell
+openclaw plugins install --dangerously-force-unsafe-install @hyperspell/openclaw-hyperspell
 ```
 
+> **Note:** The `--dangerously-force-unsafe-install` flag is required because OpenClaw's automated install scanner detects standard operations that are essential to how the plugin works — opening your browser during setup, scheduling background jobs, and securely communicating with the Hyperspell API. These are normal, expected behaviors and the plugin does not execute arbitrary code or access data beyond what is needed to function. The source is fully open and auditable in this repository.
+
 ## Quick Start
 
 Run the interactive setup wizard:

package/client.ts

@@ -27,7 +27,7 @@ export type Integration = {
 	id: string;
 	name: string;
 	provider: HyperspellSource;
-	icon: string;
+	icon: string | null;
 };
 
 export type Connection = {
@@ -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 },
@@ -149,6 +179,7 @@ export class HyperspellClient {
 			score: doc.score ?? null,
 			url: (doc.metadata?.url as string | null) ?? null,
 			createdAt: (doc.metadata?.created_at as string | null) ?? null,
+			highlights: [],
 		}));
 
 		log.debugResponse("memories.search (with answer)", {
@@ -290,7 +321,12 @@ export class HyperspellClient {
 			session_id: options?.sessionId,
 			title: options?.title,
 			format: "openclaw",
-			extract: options?.extract ?? ["procedure"],
+			// Cast: SDK 0.35 typing accepts only ["procedure" | "memory"], but the
+			// backend's mood extractor (hyperspell/hyperspell#581) accepts "mood".
+			// Remove this cast once the OpenAPI spec is updated.
+			extract: (options?.extract ?? ["procedure"]) as Array<
+				"procedure" | "memory"
+			>,
 			metadata: {
 				...options?.metadata,
 				openclaw_source: "agent_end",
@@ -319,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

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

package/config.ts

@@ -1,5 +1,4 @@
 export type HyperspellSource =
-	| "collections"
 	| "reddit"
 	| "notion"
 	| "slack"
@@ -8,7 +7,11 @@ export type HyperspellSource =
 	| "box"
 	| "google_drive"
 	| "vault"
-	| "web_crawler";
+	| "web_crawler"
+	| "dropbox"
+	| "github"
+	| "trace"
+	| "microsoft_teams";
 
 export type KnowledgeGraphConfig = {
 	enabled: boolean;
@@ -27,6 +30,8 @@ export type HyperspellConfig = {
 	userId?: string;
 	autoContext: boolean;
 	autoTrace: AutoTraceConfig;
+	emotionalContext: boolean;
+	relationshipId?: string;
 	syncMemories: boolean;
 	sources: HyperspellSource[];
 	maxResults: number;
@@ -40,6 +45,8 @@ const ALLOWED_KEYS = [
 	"userId",
 	"autoContext",
 	"autoTrace",
+	"emotionalContext",
+	"relationshipId",
 	"syncMemories",
 	"sources",
 	"maxResults",
@@ -49,7 +56,6 @@ const ALLOWED_KEYS = [
 ];
 
 const VALID_SOURCES: HyperspellSource[] = [
-	"collections",
 	"reddit",
 	"notion",
 	"slack",
@@ -59,6 +65,10 @@ const VALID_SOURCES: HyperspellSource[] = [
 	"google_drive",
 	"vault",
 	"web_crawler",
+	"dropbox",
+	"github",
+	"trace",
+	"microsoft_teams",
 ];
 
 function assertAllowedKeys(
@@ -162,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

@@ -1,5 +1,8 @@
 {
 	"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",
 	"kind": "memory",
 	"uiHints": {
 		"apiKey": {
@@ -24,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",
@@ -79,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.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "OpenClaw Hyperspell memory plugin",
   "license": "MIT",
@@ -17,6 +17,8 @@
     "openclaw.plugin.json",
     "README.md"
   ],
+  "author": "Hyperspell <hello@hyperspell.com> (https://hyperspell.com)",
+  "homepage": "https://hyperspell.com",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/hyperspell/hyperspell-openclaw.git"
@@ -32,7 +34,7 @@
   "dependencies": {
     "@clack/prompts": "^1.0.0",
     "@sinclair/typebox": "^0.34.0",
-    "hyperspell": "^0.30.0"
+    "hyperspell": "^0.35.1"
   },
   "peerDependencies": {
     "openclaw": ">=2026.1.29"
@@ -46,7 +48,15 @@
     "extensions": [
       "./index.ts"
     ],
-    "hooks": []
+    "hooks": [],
+    "compat": {
+      "pluginApi": ">=2026.1.29",
+      "minGatewayVersion": "2026.1.29"
+    },
+    "build": {
+      "openclawVersion": "2026.3.24-beta.2",
+      "pluginSdkVersion": "2026.3.24-beta.2"
+    }
   },
   "devDependencies": {
     "typescript": "^5.9.3"