@hyperspell/openclaw-hyperspell 0.9.0 → 0.11.0

package/client.ts

@@ -1,5 +1,10 @@
 import Hyperspell from "hyperspell";
-import type { HyperspellConfig, HyperspellSource } from "./config.ts";
+import type {
+	HyperspellConfig,
+	HyperspellSource,
+	ScopeName,
+} from "./config.ts";
+import { normalizeScope } from "./config.ts";
 import { log } from "./logger.ts";
 
 export type Highlight = {
@@ -82,29 +87,55 @@ 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;
+			filter?: Record<string, unknown>;
+		},
 	): 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,
+			filter: options?.filter,
 		});
 
+		const response = await this.client.memories.search(
+			{
+				query,
+				sources,
+				options: {
+					max_results: limit,
+					...(options?.after ? { after: options.after } : {}),
+					...(options?.before ? { before: options.before } : {}),
+					...(options?.filter ? { filter: options.filter } : {}),
+				},
+			},
+			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 +143,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 +157,44 @@ 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;
+			filter?: Record<string, unknown>;
+		},
 	): 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,
+			filter: options?.filter,
 		});
 
+		const response = await this.client.memories.search(
+			{
+				query,
+				sources,
+				options: {
+					max_results: limit,
+					...(options?.after ? { after: options.after } : {}),
+					...(options?.before ? { before: options.before } : {}),
+					...(options?.filter ? { filter: options.filter } : {}),
+				},
+			},
+			this.requestOptions(options?.userId),
+		);
+
 		log.debugResponse("memories.search (raw)", {
 			count: response.documents.length,
 		});
@@ -150,7 +204,12 @@ export class HyperspellClient {
 
 	async searchWithAnswer(
 		query: string,
-		options?: { limit?: number; sources?: HyperspellSource[] },
+		options?: {
+			limit?: number;
+			sources?: HyperspellSource[];
+			userId?: string;
+			filter?: Record<string, unknown>;
+		},
 	): Promise<SearchWithAnswerResult> {
 		const limit = options?.limit ?? this.config.maxResults;
 		const sources =
@@ -161,16 +220,22 @@ export class HyperspellClient {
 			query,
 			limit,
 			sources,
+			userId: options?.userId,
+			filter: options?.filter,
 		});
 
-		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,
+					...(options?.filter ? { filter: options.filter } : {}),
+				},
 			},
-		});
+			this.requestOptions(options?.userId),
+		);
 
 		const documents: SearchResult[] = response.documents.map((doc) => ({
 			resourceId: doc.resource_id,
@@ -201,6 +266,8 @@ export class HyperspellClient {
 			collection?: string;
 			date?: string;
 			metadata?: Record<string, string | number | boolean>;
+			userId?: string;
+			scope?: ScopeName;
 		},
 	): Promise<{ resourceId: string }> {
 		log.debugRequest("memories.add", {
@@ -209,19 +276,28 @@ export class HyperspellClient {
 			resourceId: options?.resourceId,
 			collection: options?.collection,
 			date: options?.date,
+			userId: options?.userId,
+			scope: options?.scope,
 		});
 
-		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: {
+					openclaw_source: "command",
+					...options?.metadata,
+					...(options?.userId ? { openclaw_user: options.userId } : {}),
+					...(options?.scope
+						? { openclaw_scope: normalizeScope(options.scope) }
+						: {}),
+				},
 			},
-		});
+			this.requestOptions(options?.userId),
+		);
 
 		log.debugResponse("memories.add", { resourceId: result.resource_id });
 		return { resourceId: result.resource_id };
@@ -245,10 +321,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 +342,7 @@ export class HyperspellClient {
 		source?: HyperspellSource;
 		collection?: string;
 		pageSize?: number;
+		userId?: string;
 	}): AsyncGenerator<{
 		resourceId: string;
 		source: HyperspellSource;
@@ -270,6 +352,7 @@ export class HyperspellClient {
 		log.debugRequest("memories.list", {
 			source: options?.source,
 			collection: options?.collection,
+			userId: options?.userId,
 		});
 
 		const params: Record<string, unknown> = {
@@ -278,7 +361,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 +377,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 +399,41 @@ export class HyperspellClient {
 			title?: string;
 			extract?: Array<"procedure" | "memory" | "mood">;
 			metadata?: Record<string, string | number | boolean>;
+			userId?: string;
+			scope?: ScopeName;
 		},
 	): Promise<{ resourceId: string; status: string }> {
 		log.debugRequest("sessions.add", {
 			historyLength: history.length,
 			sessionId: options?.sessionId,
 			extract: options?.extract,
+			userId: options?.userId,
+			scope: options?.scope,
 		});
 
-		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: {
+					openclaw_source: "agent_end",
+					...options?.metadata,
+					...(options?.userId ? { openclaw_user: options.userId } : {}),
+					...(options?.scope
+						? { openclaw_scope: normalizeScope(options.scope) }
+						: {}),
+				},
 			},
-		});
+			this.requestOptions(options?.userId),
+		);
 
 		log.debugResponse("sessions.add", {
 			resourceId: result.resource_id,
@@ -340,10 +442,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

@@ -1,10 +1,29 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import type { HyperspellClient } from "../client.ts"
-import type { HyperspellConfig } from "../config.ts"
+import type { CanReadScope, HyperspellConfig } from "../config.ts"
 import { getWorkspaceDir } from "../config.ts"
+import {
+  buildScopeFilter,
+  getCanReadScopes,
+  getDefaultWriteScope,
+  resolveRole,
+  resolveUser,
+  routeWrite,
+} from "../lib/sender.ts"
 import { log } from "../logger.ts"
 import { syncAllMemoryFiles } from "../sync/markdown.ts"
 
+/**
+ * Strip a `#scope-name` prefix from free text. Returns the scope and the
+ * remainder. Used by /remember and /getcontext to let users narrow or route
+ * via a single keystroke.
+ */
+function parseScopePrefix(text: string): { scope?: string; rest: string } {
+  const m = text.match(/^#(\S+)\s+(.*)$/)
+  if (!m) return { rest: text }
+  return { scope: m[1], rest: m[2] }
+}
+
 function truncate(text: string, maxLength: number): string {
   if (text.length <= maxLength) return text
   return `${text.slice(0, maxLength)}…`
@@ -18,7 +37,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 +45,34 @@ export function registerCommands(
     description: "Search your memories for relevant context",
     acceptsArgs: true,
     requireAuth: true,
-    handler: async (ctx: { args?: string }) => {
-      const query = ctx.args?.trim()
-      if (!query) {
-        return { text: "Usage: /getcontext <search query>" }
+    handler: async (ctx: { args?: string; senderId?: string; channel?: string }) => {
+      const rawArgs = ctx.args?.trim()
+      if (!rawArgs) {
+        return { text: "Usage: /getcontext [#scope] <search query>" }
+      }
+      const { scope: requestedScope, rest: query } = parseScopePrefix(rawArgs)
+
+      const resolved = resolveUser(ctx as Record<string, unknown>, cfg)
+      const userId = resolved?.userId
+
+      // Build scope filter: intersect requested scope (if any) with caller's canRead.
+      let filter: Record<string, unknown> | undefined
+      if (cfg.multiUser?.scoping) {
+        const canRead = getCanReadScopes(resolved, cfg)
+        const allowed: CanReadScope[] = requestedScope
+          ? canRead.includes("*") || canRead.includes(requestedScope)
+            ? [requestedScope]
+            : []
+          : canRead
+        filter = buildScopeFilter(allowed, resolved?.userId ?? "")
       }
 
-      log.debug(`/getcontext command: "${query}"`)
+      log.debug(
+        `/getcontext command: "${query}" userId=${userId} scope=${requestedScope ?? "any"}`,
+      )
 
       try {
-        const results = await client.search(query, { limit: 5 })
+        const results = await client.search(query, { limit: 5, userId, filter })
 
         if (results.length === 0) {
           return { text: `No memories found for: "${query}"` }
@@ -63,21 +100,61 @@ export function registerCommands(
     description: "Save something to memory",
     acceptsArgs: true,
     requireAuth: true,
-    handler: async (ctx: { args?: string }) => {
-      const text = ctx.args?.trim()
-      if (!text) {
-        return { text: "Usage: /remember <text to remember>" }
+    handler: async (ctx: { args?: string; senderId?: string; channel?: string }) => {
+      const rawArgs = ctx.args?.trim()
+      if (!rawArgs) {
+        return { text: "Usage: /remember [#scope] <text to remember>" }
+      }
+      const { scope: requestedScope, rest: text } = parseScopePrefix(rawArgs)
+
+      const resolved = resolveUser(ctx as Record<string, unknown>, cfg)
+      const scopingEnabled = !!cfg.multiUser?.scoping
+      const availableScopes = cfg.multiUser?.scoping?.scopes ?? []
+
+      // Scope resolution: prefix > role default > global default > "private"
+      const scope = scopingEnabled
+        ? (requestedScope ?? getDefaultWriteScope(resolved, cfg))
+        : "private"
+
+      // Validate scope is in declared vocabulary
+      if (
+        scopingEnabled &&
+        requestedScope &&
+        availableScopes.length > 0 &&
+        !availableScopes.includes(scope)
+      ) {
+        return {
+          text: `Unknown scope "${scope}". Available: ${availableScopes.join(", ")}.`,
+        }
       }
 
-      log.debug(`/remember command: "${truncate(text, 50)}"`)
+      // canWriteScopes enforcement
+      if (scopingEnabled) {
+        const role = resolveRole(resolved, cfg)
+        if (role?.canWriteScopes && !role.canWriteScopes.includes(scope)) {
+          return { text: `You cannot write to scope "${scope}".` }
+        }
+      }
+
+      const { userId, collection } = scopingEnabled
+        ? routeWrite(resolved, scope, cfg)
+        : { userId: resolved?.userId, collection: undefined }
+
+      log.debug(
+        `/remember command: "${truncate(text, 50)}" userId=${userId} scope=${scope}`,
+      )
 
       try {
         await client.addMemory(text, {
           metadata: { source: "openclaw_command" },
+          collection,
+          userId,
+          scope: scopingEnabled ? scope : undefined,
         })
 
         const preview = truncate(text, 60)
-        return { text: `Remembered: "${preview}"` }
+        const scopeHint = scopingEnabled ? ` [${scope}]` : ""
+        return { text: `Remembered${scopeHint}: "${preview}"` }
       } catch (err) {
         log.error("/remember failed", err)
         return { text: "Failed to save memory. Check logs for details." }
@@ -96,7 +173,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." }