@hyperspell/openclaw-hyperspell 0.9.0 → 0.10.0

package/hooks/auto-context.ts

@@ -1,5 +1,6 @@
 import type { HyperspellClient, SearchResult } from "../client.ts"
 import type { HyperspellConfig } from "../config.ts"
+import { resolveUser } from "../lib/sender.ts"
 import { log } from "../logger.ts"
 
 function formatRelativeTime(isoTimestamp: string): string {
@@ -26,7 +27,15 @@ function formatRelativeTime(isoTimestamp: string): string {
   }
 }
 
-function formatContext(results: SearchResult[], maxResults: number, threshold: number): string | null {
+/**
+ * Format a list of search results as per-highlight bullets, filtered by relevance threshold.
+ * Returns null if nothing passes the threshold.
+ */
+function formatHighlightBullets(
+  results: SearchResult[],
+  maxResults: number,
+  threshold: number,
+): string | null {
   const sections: string[] = []
 
   for (const r of results.slice(0, maxResults)) {
@@ -44,39 +53,183 @@ function formatContext(results: SearchResult[], maxResults: number, threshold: n
   }
 
   if (sections.length === 0) return null
+  return sections.join("\n\n")
+}
 
-  const intro =
-    "The following is context from the user's connected sources. Reference it only when relevant to the conversation."
-  const disclaimer =
-    "Use this context naturally when relevant — including indirect connections — but don't force it into every response or make assumptions beyond what's stated."
+const INTRO =
+  "The following is context from the user's connected sources. Reference it only when relevant to the conversation."
+const DISCLAIMER =
+  "Use this context naturally when relevant — including indirect connections — but don't force it into every response or make assumptions beyond what's stated."
 
-  return `<hyperspell-context>\n${intro}\n\n${sections.join("\n\n")}\n\n${disclaimer}\n</hyperspell-context>`
+function wrapSingle(body: string): string {
+  return `<hyperspell-context>\n${INTRO}\n\n${body}\n\n${DISCLAIMER}\n</hyperspell-context>`
 }
 
 export function buildAutoContextHandler(
   client: HyperspellClient,
   cfg: HyperspellConfig,
 ) {
-  return async (event: Record<string, unknown>) => {
+  return async (
+    event: Record<string, unknown>,
+    ctx?: Record<string, unknown>,
+  ) => {
     const prompt = event.prompt as string | undefined
     if (!prompt || prompt.length < 5) return
 
+    // Multi-user path
+    if (cfg.multiUser) {
+      const resolved = resolveUser(ctx, cfg)
+      return multiUserSearch(client, cfg, prompt, resolved)
+    }
+
+    // Single-user path — preserves main's highlights + threshold behavior
     log.debug(`auto-context: searching for "${prompt.slice(0, 50)}..."`)
 
     try {
       const results = await client.search(prompt, { limit: cfg.maxResults })
-      const context = formatContext(results, cfg.maxResults, cfg.relevanceThreshold)
+      const formatted = formatHighlightBullets(
+        results,
+        cfg.maxResults,
+        cfg.relevanceThreshold,
+      )
 
-      if (!context) {
+      if (!formatted) {
         log.debug("auto-context: no relevant memories found")
         return
       }
 
       log.debug(`auto-context: injecting ${results.length} memories`)
-      return { prependContext: context }
+      return { prependContext: wrapSingle(formatted) }
     } catch (err) {
       log.error("auto-context failed", err)
       return
     }
   }
 }
+
+async function multiUserSearch(
+  client: HyperspellClient,
+  cfg: HyperspellConfig,
+  prompt: string,
+  resolved:
+    | { userId: string; name: string; context?: string; resolved: boolean }
+    | undefined,
+) {
+  const multiUser = cfg.multiUser!
+  const isKnownSender = !!resolved?.resolved
+  const includeShared = multiUser.includeSharedInSearch
+
+  log.debug(
+    `auto-context: searching for "${prompt.slice(0, 50)}..." user=${resolved?.userId ?? "unknown"}`,
+  )
+
+  // Build parallel searches — personal (known senders only) + shared
+  const personalSearch = isKnownSender
+    ? client.search(prompt, {
+        limit: cfg.maxResults,
+        userId: resolved!.userId,
+      })
+    : null
+
+  // Always search shared for unknown senders, even if includeSharedInSearch is false
+  const sharedLimit = isKnownSender
+    ? Math.ceil(cfg.maxResults / 2)
+    : cfg.maxResults
+  const sharedSearch =
+    includeShared || !isKnownSender
+      ? client.search(prompt, {
+          limit: sharedLimit,
+          userId: multiUser.sharedUserId,
+        })
+      : null
+
+  const searches = [personalSearch, sharedSearch].filter(Boolean) as Promise<
+    SearchResult[]
+  >[]
+  const settled = await Promise.allSettled(searches)
+
+  let idx = 0
+  let personalResults: SearchResult[] = []
+  let sharedResults: SearchResult[] = []
+
+  if (personalSearch) {
+    const r = settled[idx++]
+    if (r.status === "fulfilled") {
+      personalResults = r.value
+    } else {
+      log.error("auto-context: personal search failed", r.reason)
+    }
+  }
+  if (sharedSearch) {
+    const r = settled[idx++]
+    if (r.status === "fulfilled") {
+      sharedResults = r.value
+    } else {
+      log.error("auto-context: shared search failed", r.reason)
+    }
+  }
+
+  const sections: string[] = []
+
+  // User identity preamble
+  if (isKnownSender && resolved) {
+    const contextLine = resolved.context ? ` ${resolved.context}` : ""
+    sections.push(`You are speaking with ${resolved.name}.${contextLine}`)
+  }
+
+  // Personal section (threshold-filtered per PR #11/#12 format)
+  if (isKnownSender && personalResults.length > 0 && resolved) {
+    const formatted = formatHighlightBullets(
+      personalResults,
+      cfg.maxResults,
+      cfg.relevanceThreshold,
+    )
+    if (formatted) {
+      sections.push(
+        `<personal-context>\nMemories from ${resolved.name}'s personal sources and history.\n\n${formatted}\n</personal-context>`,
+      )
+    }
+  }
+
+  // Shared section
+  if (sharedResults.length > 0) {
+    const sharedDisplayLimit = isKnownSender
+      ? Math.ceil(cfg.maxResults / 2)
+      : cfg.maxResults
+    const formatted = formatHighlightBullets(
+      sharedResults,
+      sharedDisplayLimit,
+      cfg.relevanceThreshold,
+    )
+    if (formatted) {
+      sections.push(
+        `<shared-context>\nShared memories available to all users.\n\n${formatted}\n</shared-context>`,
+      )
+    }
+  }
+
+  // If only the identity preamble is present (no memory sections), still inject identity
+  const haveMemorySections = sections.some(
+    (s) => s.startsWith("<personal-context>") || s.startsWith("<shared-context>"),
+  )
+
+  if (!haveMemorySections) {
+    log.debug("auto-context: no relevant memories found")
+    if (isKnownSender && resolved) {
+      const contextLine = resolved.context ? ` ${resolved.context}` : ""
+      return {
+        prependContext: `<hyperspell-context>\nYou are speaking with ${resolved.name}.${contextLine}\n</hyperspell-context>`,
+      }
+    }
+    return
+  }
+
+  const totalCount = personalResults.length + sharedResults.length
+  log.debug(
+    `auto-context: injecting ${totalCount} memories (${personalResults.length} personal, ${sharedResults.length} shared)`,
+  )
+
+  return {
+    prependContext: `<hyperspell-context>\n${sections.join("\n\n")}\n\n${DISCLAIMER}\n</hyperspell-context>`,
+  }
+}

package/hooks/auto-trace.ts

@@ -1,5 +1,6 @@
 import type { HyperspellClient } from "../client.ts";
 import type { HyperspellConfig } from "../config.ts";
+import { resolveUser } from "../lib/sender.ts";
 import { log } from "../logger.ts";
 
 type Message = { role?: string; content?: string | unknown };
@@ -75,7 +76,10 @@ export function buildAutoTraceHandler(
 	client: HyperspellClient,
 	cfg: HyperspellConfig,
 ) {
-	return async (event: Record<string, unknown>) => {
+	return async (
+		event: Record<string, unknown>,
+		ctx?: Record<string, unknown>,
+	) => {
 		if (event.success === false) {
 			log.debug("auto-trace: skipping — agent ended with error");
 			return;
@@ -109,15 +113,21 @@ export function buildAutoTraceHandler(
 			? String(firstUser.content).slice(0, 80).replace(/\n/g, " ")
 			: undefined;
 
+		// Resolve sender → userId so traces land in the right user's space.
+		// Falls back to sharedUserId for unknown senders (or undefined in single-user mode).
+		const resolved = resolveUser(ctx, cfg);
+		const userId = resolved?.userId;
+
 		try {
 			const result = await client.sendTrace(history, {
 				sessionId,
 				title,
 				extract: cfg.autoTrace.extract,
 				metadata: cfg.autoTrace.metadata,
+				userId,
 			});
 			log.info(
-				`auto-trace: sent ${result.resourceId} (${messages.length} messages)`,
+				`auto-trace: sent ${result.resourceId} (${messages.length} messages${userId ? `, user=${userId}` : ""})`,
 			);
 		} catch (err) {
 			// Fire-and-forget — never break the session

package/hooks/memory-sync.ts

@@ -8,9 +8,10 @@ import { syncMarkdownFile, syncAllMemoryFiles } from "../sync/markdown.ts"
 /**
  * Build a handler for file change events that syncs markdown files to Hyperspell
  */
-export function buildFileSyncHandler(client: HyperspellClient, _cfg: HyperspellConfig) {
+export function buildFileSyncHandler(client: HyperspellClient, cfg: HyperspellConfig) {
   const workspaceDir = getWorkspaceDir()
   const memoryDir = path.join(workspaceDir, "memory")
+  const syncUserId = cfg.multiUser?.sharedUserId
 
   return async (event: Record<string, unknown>) => {
     const filePath = event.file_path as string | undefined
@@ -25,7 +26,7 @@ export function buildFileSyncHandler(client: HyperspellClient, _cfg: HyperspellC
     log.info(`Memory file changed: ${fileName}`)
 
     try {
-      const result = await syncMarkdownFile(client, filePath)
+      const result = await syncMarkdownFile(client, filePath, { userId: syncUserId })
       if (result.success) {
         log.info(`Synced ${fileName} -> ${result.resourceId}`)
       } else {
@@ -43,10 +44,11 @@ export function buildFileSyncHandler(client: HyperspellClient, _cfg: HyperspellC
 export async function syncMemoriesOnStartup(
   client: HyperspellClient,
   workspaceDir: string,
+  options?: { userId?: string },
 ): Promise<void> {
   log.info("Syncing existing memory files...")
 
-  const result = await syncAllMemoryFiles(client, workspaceDir)
+  const result = await syncAllMemoryFiles(client, workspaceDir, { userId: options?.userId })
 
   if (result.synced > 0) {
     log.info(`Synced ${result.synced} memory files`)

package/index.ts

@@ -8,8 +8,8 @@ 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"
-import { registerSearchTool } from "./tools/search.ts"
+import { createRememberToolFactory } from "./tools/remember.ts"
+import { createSearchToolFactory } from "./tools/search.ts"
 import { registerNetworkTools } from "./graph/index.ts"
 
 export default {
@@ -80,9 +80,13 @@ export default {
 
 		const client = new HyperspellClient(cfg);
 
-		// Register AI tools
-		registerSearchTool(api, client, cfg);
-		registerRememberTool(api, client, cfg);
+		// Register AI tools (factory pattern for sender context)
+		api.registerTool(createSearchToolFactory(client, cfg), {
+			name: "hyperspell_search",
+		});
+		api.registerTool(createRememberToolFactory(client, cfg), {
+			name: "hyperspell_remember",
+		});
 
 		// Register emotional context hooks (fetch on start, store on end)
 		if (cfg.emotionalContext) {
@@ -124,7 +128,9 @@ export default {
 				// Sync memories on startup if enabled
 				if (cfg.syncMemories) {
 					const workspaceDir = getWorkspaceDir();
-					await syncMemoriesOnStartup(client, workspaceDir);
+					await syncMemoriesOnStartup(client, workspaceDir, {
+						userId: cfg.multiUser?.sharedUserId,
+					});
 				}
 			},
 			stop: () => {

package/lib/sender.ts

@@ -0,0 +1,76 @@
+import type { HyperspellConfig } from "../config.ts"
+import { log } from "../logger.ts"
+
+export interface ResolvedUser {
+  userId: string
+  name: string
+  context?: string
+  /** True if the sender was matched in senderMap; false if falling back to sharedUserId */
+  resolved: boolean
+}
+
+/**
+ * Resolve the sender's Hyperspell user from hook or tool context.
+ *
+ * Matches sender handles in the multiUser.senderMap against the sessionKey
+ * using substring matching. Handles are sorted longest-first to prevent
+ * partial matches (e.g., Discord ID "123" matching inside "1234567").
+ *
+ * Falls back to sharedUserId for unrecognized senders.
+ */
+export function resolveUser(
+  ctx: Record<string, unknown> | undefined,
+  cfg: HyperspellConfig,
+): ResolvedUser | undefined {
+  const multiUser = cfg.multiUser
+  if (!multiUser) {
+    // Single-user mode: return config.userId if set
+    return cfg.userId ? { userId: cfg.userId, name: cfg.userId, resolved: true } : undefined
+  }
+
+  // Try direct senderId lookup (available in slash command contexts;
+  // tool factory contexts do NOT include senderId — they have sessionKey instead)
+  const senderId = (ctx?.senderId as string) ?? (ctx?.requesterSenderId as string) ?? undefined
+  if (senderId && multiUser.senderMap[senderId]) {
+    const profile = multiUser.senderMap[senderId]
+    log.debug(`sender resolved via senderId: ${senderId} -> ${profile.userId}`)
+    return { ...profile, resolved: true }
+  }
+
+  // Try sessionKey substring matching (works in both hook and tool factory contexts)
+  const sessionKey = ctx?.sessionKey as string | undefined
+  if (sessionKey) {
+    const sortedEntries = Object.entries(multiUser.senderMap)
+      .sort(([a], [b]) => b.length - a.length)
+    for (const [handle, profile] of sortedEntries) {
+      if (sessionKey.includes(handle)) {
+        log.debug(`sender resolved via sessionKey: ${handle} -> ${profile.userId}`)
+        return { ...profile, resolved: true }
+      }
+    }
+  }
+
+  // Fallback: use sharedUserId for unknown senders
+  log.debug("sender unresolved, falling back to sharedUserId")
+  return {
+    userId: multiUser.sharedUserId,
+    name: multiUser.sharedUserId,
+    resolved: false,
+  }
+}
+
+/**
+ * Get all unique userIds from the multiUser config (for knowledge graph scanning).
+ */
+export function getAllUserIds(cfg: HyperspellConfig): string[] {
+  if (!cfg.multiUser) {
+    return cfg.userId ? [cfg.userId] : []
+  }
+
+  const userIds = new Set<string>()
+  for (const profile of Object.values(cfg.multiUser.senderMap)) {
+    userIds.add(profile.userId)
+  }
+  userIds.add(cfg.multiUser.sharedUserId)
+  return [...userIds]
+}

package/package.json

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

package/sync/markdown.ts

@@ -122,6 +122,7 @@ export function getMemoryFiles(workspaceDir: string): string[] {
 export async function syncMarkdownFile(
   client: HyperspellClient,
   filePath: string,
+  options?: { userId?: string },
 ): Promise<{ success: boolean; resourceId?: string; error?: string }> {
   const file = readMarkdownFile(filePath)
   if (!file) {
@@ -141,6 +142,7 @@ export async function syncMarkdownFile(
         openclaw_source: "memory_sync",
         file_path: filePath,
       },
+      userId: options?.userId,
     })
 
     // Update frontmatter with new resource ID if it changed or was newly created
@@ -162,6 +164,7 @@ export async function syncMarkdownFile(
 export async function syncAllMemoryFiles(
   client: HyperspellClient,
   workspaceDir: string,
+  options?: { userId?: string },
 ): Promise<{ synced: number; failed: number; errors: string[] }> {
   const files = getMemoryFiles(workspaceDir)
   let synced = 0
@@ -169,7 +172,7 @@ export async function syncAllMemoryFiles(
   const errors: string[] = []
 
   for (const filePath of files) {
-    const result = await syncMarkdownFile(client, filePath)
+    const result = await syncMarkdownFile(client, filePath, { userId: options?.userId })
     if (result.success) {
       synced++
       log.info(`Synced: ${path.basename(filePath)} -> ${result.resourceId}`)

package/tools/remember.ts

@@ -1,60 +1,68 @@
 import { Type } from "@sinclair/typebox"
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import type { HyperspellClient } from "../client.ts"
 import type { HyperspellConfig } from "../config.ts"
+import { resolveUser } from "../lib/sender.ts"
 import { log } from "../logger.ts"
 
-export function registerRememberTool(
-  api: OpenClawPluginApi,
+export function createRememberToolFactory(
   client: HyperspellClient,
-  _cfg: HyperspellConfig,
-): void {
-  api.registerTool(
-    {
-      name: "hyperspell_remember",
-      label: "Memory Store",
-      description: "Save important information to the user's memory.",
-      parameters: Type.Object({
-        text: Type.String({ description: "Information to remember" }),
-        title: Type.Optional(
-          Type.String({ description: "Optional title for the memory" }),
-        ),
-        date: Type.Optional(
-          Type.String({ description: "Date of the memory (ISO 8601 or YYYY-MM-DD). Helps ranking and enables date-range filtering. Defaults to now if omitted." }),
-        ),
-      }),
-      async execute(
-        _toolCallId: string,
-        params: { text: string; title?: string; date?: string },
-      ) {
-        log.debug(`remember tool: "${params.text.slice(0, 50)}..." date=${params.date ?? "now"}`)
+  cfg: HyperspellConfig,
+) {
+  return (ctx: Record<string, unknown>) => ({
+    name: "hyperspell_remember",
+    label: "Memory Store",
+    description: "Save important information to the user's memory.",
+    parameters: Type.Object({
+      text: Type.String({ description: "Information to remember" }),
+      title: Type.Optional(
+        Type.String({ description: "Optional title for the memory" }),
+      ),
+      date: Type.Optional(
+        Type.String({ description: "Date of the memory (ISO 8601 or YYYY-MM-DD). Helps ranking and enables date-range filtering. Defaults to now if omitted." }),
+      ),
+      userId: Type.Optional(
+        Type.String({
+          description:
+            "Store for a specific user or 'shared' for everyone. Omit to store for current sender.",
+        }),
+      ),
+    }),
+    async execute(
+      _toolCallId: string,
+      params: { text: string; title?: string; date?: string; userId?: string },
+    ) {
+      // Resolve userId: explicit param > sender resolution > config default
+      const resolved = resolveUser(ctx, cfg)
+      const userId = params.userId ?? resolved?.userId
+      log.debug(
+        `remember tool: "${params.text.slice(0, 50)}..." date=${params.date ?? "now"} userId=${userId}`,
+      )
 
-        try {
-          await client.addMemory(params.text, {
-            title: params.title,
-            date: params.date,
-            metadata: { source: "openclaw_tool" },
-          })
+      try {
+        await client.addMemory(params.text, {
+          title: params.title,
+          date: params.date,
+          metadata: { source: "openclaw_tool" },
+          userId,
+        })
 
-          const preview =
-            params.text.length > 80 ? `${params.text.slice(0, 80)}…` : params.text
+        const preview =
+          params.text.length > 80 ? `${params.text.slice(0, 80)}…` : params.text
 
-          return {
-            content: [{ type: "text" as const, text: `Stored: "${preview}"` }],
-          }
-        } catch (err) {
-          log.error("remember tool failed", err)
-          return {
-            content: [
-              {
-                type: "text" as const,
-                text: `Failed to store memory: ${err instanceof Error ? err.message : String(err)}`,
-              },
-            ],
-          }
+        return {
+          content: [{ type: "text" as const, text: `Stored: "${preview}"` }],
         }
-      },
+      } catch (err) {
+        log.error("remember tool failed", err)
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Failed to store memory: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+        }
+      }
     },
-    { name: "hyperspell_remember" },
-  )
+  })
 }