@hyperspell/openclaw-hyperspell 0.9.0 → 0.11.0

package/hooks/auto-context.ts

@@ -1,5 +1,11 @@
 import type { HyperspellClient, SearchResult } from "../client.ts"
-import type { HyperspellConfig } from "../config.ts"
+import type { CanReadScope, HyperspellConfig } from "../config.ts"
+import {
+  buildScopeFilter,
+  getCanReadScopes,
+  resolveUser,
+  type ResolvedUser,
+} from "../lib/sender.ts"
 import { log } from "../logger.ts"
 
 function formatRelativeTime(isoTimestamp: string): string {
@@ -26,7 +32,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 +58,192 @@ 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: ResolvedUser | undefined,
+) {
+  const multiUser = cfg.multiUser!
+  const isKnownSender = !!resolved?.resolved
+  const includeShared = multiUser.includeSharedInSearch
+
+  // Determine scope filter for the shared-space search based on caller's role.
+  // Unknown senders fall back to least-sensitive scopes; absent scoping config →
+  // filter is undefined → PR #6 behavior preserved.
+  const canRead: CanReadScope[] = multiUser.scoping
+    ? isKnownSender
+      ? getCanReadScopes(resolved, cfg)
+      : ["family", "kid_shared"]
+    : ["*"]
+  const scopeFilter = buildScopeFilter(canRead, resolved?.userId ?? "")
+
+  log.debug(
+    `auto-context: searching for "${prompt.slice(0, 50)}..." user=${resolved?.userId ?? "unknown"} canRead=${JSON.stringify(canRead)}`,
+  )
+
+  // 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,
+          filter: scopeFilter,
+        })
+      : 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,25 @@ 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,
+				// Auto-trace captures full conversation text — the most sensitive class
+				// of memory. Default to private; users opt into family-visible recall
+				// via explicit /remember.
+				scope: "private",
 			});
 			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.test.ts

@@ -0,0 +1,234 @@
+import assert from "node:assert/strict"
+import { test } from "node:test"
+import type { HyperspellConfig } from "../config.ts"
+import {
+  buildScopeFilter,
+  getCanReadScopes,
+  getDefaultWriteScope,
+  resolveRole,
+  routeWrite,
+} from "./sender.ts"
+
+function cfg(overrides: Partial<HyperspellConfig["multiUser"]> = {}): HyperspellConfig {
+  return {
+    apiKey: "test",
+    autoContext: false,
+    autoTrace: { enabled: false, extract: ["procedure"] },
+    emotionalContext: false,
+    syncMemories: false,
+    sources: [],
+    maxResults: 5,
+    relevanceThreshold: 0.6,
+    debug: false,
+    knowledgeGraph: { enabled: false, scanIntervalMinutes: 60, batchSize: 20 },
+    multiUser: overrides.scoping
+      ? {
+          sharedUserId: "shared",
+          includeSharedInSearch: true,
+          senderMap: overrides.senderMap ?? {},
+          scoping: overrides.scoping,
+        }
+      : undefined,
+  }
+}
+
+test("buildScopeFilter — wildcard returns undefined", () => {
+  assert.equal(buildScopeFilter(["*"], "u1"), undefined)
+})
+
+test("buildScopeFilter — empty returns match-nothing filter (not undefined)", () => {
+  const f = buildScopeFilter([], "u1")
+  assert.deepEqual(f, { openclaw_scope: "__never__" })
+})
+
+test("buildScopeFilter — single named scope collapses $or", () => {
+  const f = buildScopeFilter(["family"], "u1")
+  assert.deepEqual(f, { openclaw_scope: { $in: ["family"] } })
+})
+
+test("buildScopeFilter — multiple named scopes", () => {
+  const f = buildScopeFilter(["family", "kid_shared"], "u1")
+  assert.deepEqual(f, { openclaw_scope: { $in: ["family", "kid_shared"] } })
+})
+
+test("buildScopeFilter — scopes plus self produces $or", () => {
+  const f = buildScopeFilter(["family", "self"], "u1")
+  assert.deepEqual(f, {
+    $or: [
+      { openclaw_scope: { $in: ["family"] } },
+      { openclaw_user: "u1" },
+    ],
+  })
+})
+
+test("buildScopeFilter — hyphenated scope normalized in metadata", () => {
+  const f = buildScopeFilter(["parent-only"], "u1")
+  assert.deepEqual(f, { openclaw_scope: { $in: ["parent_only"] } })
+})
+
+test("buildScopeFilter — self only (no named scopes)", () => {
+  const f = buildScopeFilter(["self"], "u1")
+  assert.deepEqual(f, { openclaw_user: "u1" })
+})
+
+test("buildScopeFilter — self only with empty userId → match-nothing", () => {
+  const f = buildScopeFilter(["self"], "")
+  // Empty userId cannot build a self clause; no named scopes either → match-nothing
+  assert.deepEqual(f, { openclaw_scope: "__never__" })
+})
+
+test("getCanReadScopes — scoping absent returns wildcard", () => {
+  const c = cfg()
+  const canRead = getCanReadScopes(
+    { userId: "u1", name: "U1", resolved: true },
+    c,
+  )
+  assert.deepEqual(canRead, ["*"])
+})
+
+test("getCanReadScopes — role from scoping.users", () => {
+  const c = cfg({
+    senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+    scoping: {
+      enabled: true,
+      defaultScope: "private",
+      scopes: ["private", "family"],
+      roles: {
+        kid: { canRead: ["family"], defaultWriteScope: "family" },
+      },
+      users: { u1: { role: "kid" } },
+    },
+  })
+  const canRead = getCanReadScopes(
+    { userId: "u1", name: "U1", resolved: true },
+    c,
+  )
+  assert.deepEqual(canRead, ["family"])
+})
+
+test("getCanReadScopes — missing role returns empty (no access)", () => {
+  const c = cfg({
+    senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+    scoping: {
+      enabled: true,
+      defaultScope: "private",
+      scopes: ["private", "family"],
+      roles: {
+        kid: { canRead: ["family"], defaultWriteScope: "family" },
+      },
+      users: {}, // u1 has no role assignment
+    },
+  })
+  const canRead = getCanReadScopes(
+    { userId: "u1", name: "U1", resolved: true },
+    c,
+  )
+  assert.deepEqual(canRead, [])
+})
+
+test("getDefaultWriteScope — role default wins", () => {
+  const c = cfg({
+    senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+    scoping: {
+      enabled: true,
+      defaultScope: "private",
+      scopes: ["private", "family"],
+      roles: {
+        kid: { canRead: ["family"], defaultWriteScope: "family" },
+      },
+      users: { u1: { role: "kid" } },
+    },
+  })
+  const scope = getDefaultWriteScope(
+    { userId: "u1", name: "U1", resolved: true },
+    c,
+  )
+  assert.equal(scope, "family")
+})
+
+test("getDefaultWriteScope — falls back to global default when no role", () => {
+  const c = cfg({
+    senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+    scoping: {
+      enabled: true,
+      defaultScope: "private",
+      scopes: ["private", "family"],
+      roles: {},
+      users: {},
+    },
+  })
+  const scope = getDefaultWriteScope(
+    { userId: "u1", name: "U1", resolved: true },
+    c,
+  )
+  assert.equal(scope, "private")
+})
+
+test("getDefaultWriteScope — profile-level role override", () => {
+  const c = cfg({
+    senderMap: { "u1-phone": { userId: "u1", name: "U1", role: "parent" } },
+    scoping: {
+      enabled: true,
+      defaultScope: "private",
+      scopes: ["private", "family"],
+      roles: {
+        parent: { canRead: ["*"], defaultWriteScope: "private" },
+        kid: { canRead: ["family"], defaultWriteScope: "family" },
+      },
+      users: { u1: { role: "kid" } }, // users table says kid but profile override is parent
+    },
+  })
+  const scope = getDefaultWriteScope(
+    { userId: "u1", name: "U1", resolved: true, role: "parent" },
+    c,
+  )
+  assert.equal(scope, "private")
+})
+
+test("resolveRole — returns undefined when scoping absent", () => {
+  const c = cfg()
+  const role = resolveRole(
+    { userId: "u1", name: "U1", resolved: true },
+    c,
+  )
+  assert.equal(role, undefined)
+})
+
+test("routeWrite — private goes to user's own space", () => {
+  const c = cfg({
+    senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+    scoping: {
+      enabled: true,
+      defaultScope: "private",
+      scopes: ["private", "family"],
+      roles: { kid: { canRead: ["family"], defaultWriteScope: "family" } },
+      users: { u1: { role: "kid" } },
+    },
+  })
+  const r = routeWrite(
+    { userId: "u1", name: "U1", resolved: true },
+    "private",
+    c,
+  )
+  assert.deepEqual(r, { userId: "u1", collection: undefined })
+})
+
+test("routeWrite — non-private goes to sharedUserId with optional collection", () => {
+  const c = cfg({
+    senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+    scoping: {
+      enabled: true,
+      defaultScope: "private",
+      scopes: ["private", "family"],
+      roles: { kid: { canRead: ["family"], defaultWriteScope: "family" } },
+      users: { u1: { role: "kid" } },
+      collections: { family: "household-shared" },
+    },
+  })
+  const r = routeWrite(
+    { userId: "u1", name: "U1", resolved: true },
+    "family",
+    c,
+  )
+  assert.deepEqual(r, { userId: "shared", collection: "household-shared" })
+})