@hyperspell/openclaw-hyperspell 0.9.0 → 0.10.0

package/client.ts

@@ -82,29 +82,52 @@ export class HyperspellClient {
 		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,
@@ -112,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,
+				})),
 			};
 		});
 
@@ -122,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,
 		});
@@ -150,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 =
@@ -161,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,
@@ -201,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", {
@@ -209,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 };
@@ -245,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 {
@@ -261,6 +322,7 @@ export class HyperspellClient {
 		source?: HyperspellSource;
 		collection?: string;
 		pageSize?: number;
+		userId?: string;
 	}): AsyncGenerator<{
 		resourceId: string;
 		source: HyperspellSource;
@@ -270,6 +332,7 @@ export class HyperspellClient {
 		log.debugRequest("memories.list", {
 			source: options?.source,
 			collection: options?.collection,
+			userId: options?.userId,
 		});
 
 		const params: Record<string, unknown> = {
@@ -278,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,
@@ -291,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 });
@@ -308,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,
@@ -340,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,

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,6 +25,18 @@ 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;
@@ -38,6 +50,7 @@ export type HyperspellConfig = {
 	relevanceThreshold: number;
 	debug: boolean;
 	knowledgeGraph: KnowledgeGraphConfig;
+	multiUser?: MultiUserConfig;
 };
 
 const ALLOWED_KEYS = [
@@ -53,6 +66,7 @@ const ALLOWED_KEYS = [
 	"relevanceThreshold",
 	"debug",
 	"knowledgeGraph",
+	"multiUser",
 ];
 
 const VALID_SOURCES: HyperspellSource[] = [
@@ -135,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)
@@ -184,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),
 	};
 }
 

package/graph/ops.ts

@@ -1,6 +1,8 @@
 import * as fs from "node:fs"
 import * as path from "node:path"
 import type { HyperspellClient } from "../client.ts"
+import type { HyperspellConfig } from "../config.ts"
+import { getAllUserIds } from "../lib/sender.ts"
 import { log } from "../logger.ts"
 import { NetworkStateManager } from "./state.ts"
 
@@ -93,38 +95,42 @@ export async function scanMemories(
   client: HyperspellClient,
   stateManager: NetworkStateManager,
   batchSize: number,
+  cfg?: HyperspellConfig,
 ): Promise<ScannedMemory[]> {
   const unprocessed: ScannedMemory[] = []
+  const userIds = cfg ? getAllUserIds(cfg) : [undefined]
+
+  outer: for (const userId of userIds) {
+    for await (const mem of client.listMemories({ userId })) {
+      if (stateManager.isProcessed(mem.resourceId)) continue
+      if (mem.metadata?.graph_entity === "true" || mem.metadata?.graph_entity === true) continue
+      if ((mem.metadata?.status as string) !== "completed") continue
+
+      let summary = ""
+      try {
+        const full = await client.getMemory(mem.resourceId, mem.source as import("../config.ts").HyperspellSource, { userId })
+        const data = full.data as unknown[] | undefined
+
+        const participants = full.participants as Array<{ name?: string; email?: string }> | undefined
+        const participantLine = participants?.length
+          ? `Participants: ${participants.map((p) => `${p.name || ""} <${p.email || ""}>`).join(", ")}`
+          : ""
+
+        const dataSummary = data ? summarizeMemoryData(data, mem.source) : ""
+        summary = [participantLine, dataSummary].filter(Boolean).join("\n\n")
+      } catch {
+        summary = "(content unavailable)"
+      }
 
-  for await (const mem of client.listMemories()) {
-    if (stateManager.isProcessed(mem.resourceId)) continue
-    if (mem.metadata?.graph_entity === "true" || mem.metadata?.graph_entity === true) continue
-    if ((mem.metadata?.status as string) !== "completed") continue
-
-    let summary = ""
-    try {
-      const full = await client.getMemory(mem.resourceId, mem.source)
-      const data = full.data as unknown[] | undefined
-
-      const participants = full.participants as Array<{ name?: string; email?: string }> | undefined
-      const participantLine = participants?.length
-        ? `Participants: ${participants.map((p) => `${p.name || ""} <${p.email || ""}>`).join(", ")}`
-        : ""
-
-      const dataSummary = data ? summarizeMemoryData(data, mem.source) : ""
-      summary = [participantLine, dataSummary].filter(Boolean).join("\n\n")
-    } catch {
-      summary = "(content unavailable)"
-    }
+      unprocessed.push({
+        resourceId: mem.resourceId,
+        source: mem.source,
+        title: mem.title,
+        summary: summary.slice(0, 1000),
+      })
 
-    unprocessed.push({
-      resourceId: mem.resourceId,
-      source: mem.source,
-      title: mem.title,
-      summary: summary.slice(0, 1000),
-    })
-
-    if (unprocessed.length >= batchSize) break
+      if (unprocessed.length >= batchSize) break outer
+    }
   }
 
   return unprocessed

package/graph/tools.ts

@@ -32,7 +32,7 @@ export function registerNetworkTools(
       async execute(_toolCallId: string, params: { batchSize?: number }) {
         const batchSize = params.batchSize ?? cfg.knowledgeGraph.batchSize
         try {
-          const memories = await scanMemories(client, stateManager, batchSize)
+          const memories = await scanMemories(client, stateManager, batchSize, cfg)
           const text = formatScanResults(memories, stateManager.getProcessedCount(), stateManager.getLastScanAt())
           return {
             content: [{ type: "text" as const, text }],