@hyperspell/openclaw-hyperspell 0.8.1 → 0.10.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,29 +71,63 @@ 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;
+	}
+
+	private requestOptions(userId?: string) {
+		if (!userId) return undefined;
+		return { headers: { "X-As-User": userId } };
+	}
+
 	async search(
 		query: string,
-		options?: { limit?: number; sources?: HyperspellSource[]; after?: string; before?: string },
+		options?: {
+			limit?: number;
+			sources?: HyperspellSource[];
+			after?: string;
+			before?: string;
+			userId?: string;
+		},
 	): Promise<SearchResult[]> {
 		const limit = options?.limit ?? this.config.maxResults;
 		const sources =
 			options?.sources ??
 			(this.config.sources.length > 0 ? this.config.sources : undefined);
 
-		log.debugRequest("memories.search", { query, limit, sources, after: options?.after, before: options?.before });
-
-		const response = await this.client.memories.search({
+		log.debugRequest("memories.search", {
 			query,
+			limit,
 			sources,
-			options: {
-				max_results: limit,
-				...(options?.after ? { after: options.after } : {}),
-				...(options?.before ? { before: options.before } : {}),
-			},
+			after: options?.after,
+			before: options?.before,
+			userId: options?.userId,
 		});
 
+		const response = await this.client.memories.search(
+			{
+				query,
+				sources,
+				options: {
+					max_results: limit,
+					...(options?.after ? { after: options.after } : {}),
+					...(options?.before ? { before: options.before } : {}),
+				},
+			},
+			this.requestOptions(options?.userId),
+		);
+
 		const results: SearchResult[] = response.documents.map((doc) => {
-			const raw = doc as typeof doc & { highlights?: Array<{ id: string; score: number; text: string }> };
+			const raw = doc as typeof doc & {
+				highlights?: Array<{ id: string; score: number; text: string }>;
+			};
 			return {
 				resourceId: doc.resource_id,
 				title: doc.title ?? null,
@@ -82,7 +135,11 @@ 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: (raw.highlights ?? []).map((h) => ({ id: h.id, score: h.score, text: h.text })),
+				highlights: (raw.highlights ?? []).map((h) => ({
+					id: h.id,
+					score: h.score,
+					text: h.text,
+				})),
 			};
 		});
 
@@ -92,25 +149,41 @@ export class HyperspellClient {
 
 	async searchRaw(
 		query: string,
-		options?: { limit?: number; sources?: HyperspellSource[]; after?: string; before?: string },
+		options?: {
+			limit?: number;
+			sources?: HyperspellSource[];
+			after?: string;
+			before?: string;
+			userId?: string;
+		},
 	): Promise<Record<string, unknown>> {
 		const limit = options?.limit ?? this.config.maxResults;
 		const sources =
 			options?.sources ??
 			(this.config.sources.length > 0 ? this.config.sources : undefined);
 
-		log.debugRequest("memories.search (raw)", { query, limit, sources, after: options?.after, before: options?.before });
-
-		const response = await this.client.memories.search({
+		log.debugRequest("memories.search (raw)", {
 			query,
+			limit,
 			sources,
-			options: {
-				max_results: limit,
-				...(options?.after ? { after: options.after } : {}),
-				...(options?.before ? { before: options.before } : {}),
-			},
+			after: options?.after,
+			before: options?.before,
+			userId: options?.userId,
 		});
 
+		const response = await this.client.memories.search(
+			{
+				query,
+				sources,
+				options: {
+					max_results: limit,
+					...(options?.after ? { after: options.after } : {}),
+					...(options?.before ? { before: options.before } : {}),
+				},
+			},
+			this.requestOptions(options?.userId),
+		);
+
 		log.debugResponse("memories.search (raw)", {
 			count: response.documents.length,
 		});
@@ -120,7 +193,11 @@ export class HyperspellClient {
 
 	async searchWithAnswer(
 		query: string,
-		options?: { limit?: number; sources?: HyperspellSource[] },
+		options?: {
+			limit?: number;
+			sources?: HyperspellSource[];
+			userId?: string;
+		},
 	): Promise<SearchWithAnswerResult> {
 		const limit = options?.limit ?? this.config.maxResults;
 		const sources =
@@ -131,16 +208,20 @@ export class HyperspellClient {
 			query,
 			limit,
 			sources,
+			userId: options?.userId,
 		});
 
-		const response = await this.client.memories.search({
-			query,
-			sources,
-			answer: true,
-			options: {
-				max_results: limit,
+		const response = await this.client.memories.search(
+			{
+				query,
+				sources,
+				answer: true,
+				options: {
+					max_results: limit,
+				},
 			},
-		});
+			this.requestOptions(options?.userId),
+		);
 
 		const documents: SearchResult[] = response.documents.map((doc) => ({
 			resourceId: doc.resource_id,
@@ -171,6 +252,7 @@ export class HyperspellClient {
 			collection?: string;
 			date?: string;
 			metadata?: Record<string, string | number | boolean>;
+			userId?: string;
 		},
 	): Promise<{ resourceId: string }> {
 		log.debugRequest("memories.add", {
@@ -179,19 +261,23 @@ export class HyperspellClient {
 			resourceId: options?.resourceId,
 			collection: options?.collection,
 			date: options?.date,
+			userId: options?.userId,
 		});
 
-		const result = await this.client.memories.add({
-			text,
-			title: options?.title,
-			resource_id: options?.resourceId,
-			collection: options?.collection,
-			date: options?.date,
-			metadata: {
-				...options?.metadata,
-				openclaw_source: "command",
+		const result = await this.client.memories.add(
+			{
+				text,
+				title: options?.title,
+				resource_id: options?.resourceId,
+				collection: options?.collection,
+				date: options?.date,
+				metadata: {
+					...options?.metadata,
+					openclaw_source: "command",
+				},
 			},
-		});
+			this.requestOptions(options?.userId),
+		);
 
 		log.debugResponse("memories.add", { resourceId: result.resource_id });
 		return { resourceId: result.resource_id };
@@ -215,10 +301,15 @@ export class HyperspellClient {
 
 	async getConnectUrl(
 		integrationId: string,
+		options?: { userId?: string },
 	): Promise<{ url: string; expiresAt: string }> {
 		log.debugRequest("integrations.connect", { integrationId });
 
-		const response = await this.client.integrations.connect(integrationId);
+		const response = await this.client.integrations.connect(
+			integrationId,
+			undefined,
+			this.requestOptions(options?.userId),
+		);
 
 		log.debugResponse("integrations.connect", { url: response.url });
 		return {
@@ -231,6 +322,7 @@ export class HyperspellClient {
 		source?: HyperspellSource;
 		collection?: string;
 		pageSize?: number;
+		userId?: string;
 	}): AsyncGenerator<{
 		resourceId: string;
 		source: HyperspellSource;
@@ -240,6 +332,7 @@ export class HyperspellClient {
 		log.debugRequest("memories.list", {
 			source: options?.source,
 			collection: options?.collection,
+			userId: options?.userId,
 		});
 
 		const params: Record<string, unknown> = {
@@ -248,7 +341,10 @@ export class HyperspellClient {
 		if (options?.source) params.source = options.source;
 		if (options?.collection) params.collection = options.collection;
 
-		for await (const memory of this.client.memories.list(params as any)) {
+		for await (const memory of this.client.memories.list(
+			params as any,
+			this.requestOptions(options?.userId),
+		)) {
 			yield {
 				resourceId: memory.resource_id,
 				source: memory.source as HyperspellSource,
@@ -261,10 +357,15 @@ export class HyperspellClient {
 	async getMemory(
 		resourceId: string,
 		source: HyperspellSource,
+		options?: { userId?: string },
 	): Promise<Record<string, unknown>> {
 		log.debugRequest("memories.get", { resourceId, source });
 
-		const response = await this.client.memories.get(resourceId, { source });
+		const response = await this.client.memories.get(
+			resourceId,
+			{ source },
+			this.requestOptions(options?.userId),
+		);
 		const raw = response as unknown as Record<string, unknown>;
 
 		log.debugResponse("memories.get", { resourceId, hasData: "data" in raw });
@@ -278,30 +379,35 @@ export class HyperspellClient {
 			title?: string;
 			extract?: Array<"procedure" | "memory" | "mood">;
 			metadata?: Record<string, string | number | boolean>;
+			userId?: string;
 		},
 	): Promise<{ resourceId: string; status: string }> {
 		log.debugRequest("sessions.add", {
 			historyLength: history.length,
 			sessionId: options?.sessionId,
 			extract: options?.extract,
+			userId: options?.userId,
 		});
 
-		const result = await this.client.sessions.add({
-			history,
-			session_id: options?.sessionId,
-			title: options?.title,
-			format: "openclaw",
-			// 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",
+		const result = await this.client.sessions.add(
+			{
+				history,
+				session_id: options?.sessionId,
+				title: options?.title,
+				format: "openclaw",
+				// 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",
+				},
 			},
-		});
+			this.requestOptions(options?.userId),
+		);
 
 		log.debugResponse("sessions.add", {
 			resourceId: result.resource_id,
@@ -310,10 +416,14 @@ export class HyperspellClient {
 		return { resourceId: result.resource_id, status: result.status };
 	}
 
-	async listConnections(): Promise<Connection[]> {
-		log.debugRequest("connections.list", {});
+	async listConnections(options?: {
+		userId?: string;
+	}): Promise<Connection[]> {
+		log.debugRequest("connections.list", { userId: options?.userId });
 
-		const response = await this.client.connections.list();
+		const response = await this.client.connections.list(
+			this.requestOptions(options?.userId),
+		);
 
 		const connections: Connection[] = response.connections.map((conn) => ({
 			id: conn.id,
@@ -325,4 +435,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/commands/slash.ts

@@ -2,6 +2,7 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import type { HyperspellClient } from "../client.ts"
 import type { HyperspellConfig } from "../config.ts"
 import { getWorkspaceDir } from "../config.ts"
+import { resolveUser } from "../lib/sender.ts"
 import { log } from "../logger.ts"
 import { syncAllMemoryFiles } from "../sync/markdown.ts"
 
@@ -18,7 +19,7 @@ function formatScore(score: number | null): string {
 export function registerCommands(
   api: OpenClawPluginApi,
   client: HyperspellClient,
-  _cfg: HyperspellConfig,
+  cfg: HyperspellConfig,
 ): void {
   // /getcontext <query> - Search memories and show summaries
   api.registerCommand({
@@ -26,16 +27,18 @@ export function registerCommands(
     description: "Search your memories for relevant context",
     acceptsArgs: true,
     requireAuth: true,
-    handler: async (ctx: { args?: string }) => {
+    handler: async (ctx: { args?: string; senderId?: string; channel?: string }) => {
       const query = ctx.args?.trim()
       if (!query) {
         return { text: "Usage: /getcontext <search query>" }
       }
 
-      log.debug(`/getcontext command: "${query}"`)
+      const resolved = resolveUser(ctx as Record<string, unknown>, cfg)
+      const userId = resolved?.userId
+      log.debug(`/getcontext command: "${query}" userId=${userId}`)
 
       try {
-        const results = await client.search(query, { limit: 5 })
+        const results = await client.search(query, { limit: 5, userId })
 
         if (results.length === 0) {
           return { text: `No memories found for: "${query}"` }
@@ -63,17 +66,20 @@ export function registerCommands(
     description: "Save something to memory",
     acceptsArgs: true,
     requireAuth: true,
-    handler: async (ctx: { args?: string }) => {
+    handler: async (ctx: { args?: string; senderId?: string; channel?: string }) => {
       const text = ctx.args?.trim()
       if (!text) {
         return { text: "Usage: /remember <text to remember>" }
       }
 
-      log.debug(`/remember command: "${truncate(text, 50)}"`)
+      const resolved = resolveUser(ctx as Record<string, unknown>, cfg)
+      const userId = resolved?.userId
+      log.debug(`/remember command: "${truncate(text, 50)}" userId=${userId}`)
 
       try {
         await client.addMemory(text, {
           metadata: { source: "openclaw_command" },
+          userId,
         })
 
         const preview = truncate(text, 60)
@@ -96,7 +102,9 @@ export function registerCommands(
 
       try {
         const workspaceDir = getWorkspaceDir()
-        const result = await syncAllMemoryFiles(client, workspaceDir)
+        const result = await syncAllMemoryFiles(client, workspaceDir, {
+          userId: cfg.multiUser?.sharedUserId,
+        })
 
         if (result.synced === 0 && result.failed === 0) {
           return { text: "No memory files found in memory/ directory." }

package/config.ts

@@ -25,17 +25,32 @@ export type AutoTraceConfig = {
 	metadata?: Record<string, string | number | boolean>;
 };
 
+export type UserProfile = {
+	userId: string;
+	name: string;
+	context?: string;
+};
+
+export type MultiUserConfig = {
+	senderMap: Record<string, UserProfile>;
+	sharedUserId: string;
+	includeSharedInSearch: boolean;
+};
+
 export type HyperspellConfig = {
 	apiKey: string;
 	userId?: string;
 	autoContext: boolean;
 	autoTrace: AutoTraceConfig;
+	emotionalContext: boolean;
+	relationshipId?: string;
 	syncMemories: boolean;
 	sources: HyperspellSource[];
 	maxResults: number;
 	relevanceThreshold: number;
 	debug: boolean;
 	knowledgeGraph: KnowledgeGraphConfig;
+	multiUser?: MultiUserConfig;
 };
 
 const ALLOWED_KEYS = [
@@ -43,12 +58,15 @@ const ALLOWED_KEYS = [
 	"userId",
 	"autoContext",
 	"autoTrace",
+	"emotionalContext",
+	"relationshipId",
 	"syncMemories",
 	"sources",
 	"maxResults",
 	"relevanceThreshold",
 	"debug",
 	"knowledgeGraph",
+	"multiUser",
 ];
 
 const VALID_SOURCES: HyperspellSource[] = [
@@ -131,6 +149,40 @@ function parseSources(raw: string | string[] | undefined): HyperspellSource[] {
 	return sources;
 }
 
+function parseMultiUser(raw: unknown): MultiUserConfig | undefined {
+	if (!raw || typeof raw !== "object") return undefined;
+	const mu = raw as Record<string, unknown>;
+
+	const senderMap: Record<string, UserProfile> = {};
+	const rawMap = mu.senderMap as Record<string, unknown> | undefined;
+	if (rawMap && typeof rawMap === "object") {
+		for (const [handle, profile] of Object.entries(rawMap)) {
+			if (profile && typeof profile === "object") {
+				const p = profile as Record<string, unknown>;
+				if (typeof p.userId === "string" && typeof p.name === "string") {
+					senderMap[handle] = {
+						userId: p.userId,
+						name: p.name,
+						context: typeof p.context === "string" ? p.context : undefined,
+					};
+				}
+			}
+		}
+	}
+
+	if (Object.keys(senderMap).length === 0) return undefined;
+
+	return {
+		senderMap,
+		sharedUserId:
+			typeof mu.sharedUserId === "string" ? mu.sharedUserId : "shared",
+		includeSharedInSearch:
+			typeof mu.includeSharedInSearch === "boolean"
+				? mu.includeSharedInSearch
+				: true,
+	};
+}
+
 export function parseConfig(raw: unknown): HyperspellConfig {
 	const cfg =
 		raw && typeof raw === "object" && !Array.isArray(raw)
@@ -168,6 +220,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,
@@ -178,6 +232,7 @@ export function parseConfig(raw: unknown): HyperspellConfig {
 			scanIntervalMinutes: (kgRaw.scanIntervalMinutes as number) ?? 60,
 			batchSize: (kgRaw.batchSize as number) ?? 20,
 		},
+		multiUser: parseMultiUser(cfg.multiUser),
 	};
 }