@hyperspell/openclaw-hyperspell 0.9.0 → 0.11.0

package/lib/sender.ts

@@ -0,0 +1,234 @@
+import type {
+  CanReadScope,
+  HyperspellConfig,
+  Role,
+  ScopeName,
+} from "../config.ts"
+import { normalizeScope } from "../config.ts"
+import { log } from "../logger.ts"
+import { getVoiceIdentifier } from "./voice-id.ts"
+
+export interface ResolvedUser {
+  userId: string
+  name: string
+  context?: string
+  /** Profile-level role override from senderMap. Falls back to scoping.users[userId].role. */
+  role?: string
+  /** True if the sender was matched in senderMap; false if falling back to sharedUserId */
+  resolved: boolean
+}
+
+function matchFromSenderMap(
+  ctx: Record<string, unknown> | undefined,
+  cfg: HyperspellConfig,
+): ResolvedUser | undefined {
+  const multiUser = cfg.multiUser
+  if (!multiUser) {
+    return cfg.userId
+      ? { userId: cfg.userId, name: cfg.userId, resolved: true }
+      : undefined
+  }
+
+  // Try direct senderId lookup (slash command contexts)
+  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 (longest-first to avoid partial matches)
+  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,
+  }
+}
+
+/**
+ * Synchronous sender resolution from sessionKey + senderMap. Use this for
+ * hooks and tools that don't receive audio — the voice-ID path is skipped.
+ */
+export function resolveUser(
+  ctx: Record<string, unknown> | undefined,
+  cfg: HyperspellConfig,
+): ResolvedUser | undefined {
+  return matchFromSenderMap(ctx, cfg)
+}
+
+/**
+ * Asynchronous sender resolution. Checks voice-ID first (if enabled and
+ * audio is in ctx), then falls back to the synchronous path. Callers that
+ * never receive audio should use `resolveUser` to avoid unnecessary async
+ * overhead.
+ */
+export async function resolveUserAsync(
+  ctx: Record<string, unknown> | undefined,
+  cfg: HyperspellConfig,
+): Promise<ResolvedUser | undefined> {
+  const voiceCfg = cfg.multiUser?.scoping?.voiceId
+  const audio = ctx?.audio as Buffer | string | undefined
+  if (voiceCfg?.enabled && audio && cfg.multiUser) {
+    try {
+      const identifier = getVoiceIdentifier(cfg)
+      const result = await identifier.identify(audio)
+      const threshold = voiceCfg.confidenceThreshold ?? 0.7
+      if (result && result.confidence >= threshold) {
+        // Find profile for the voice-identified userId
+        for (const profile of Object.values(cfg.multiUser.senderMap)) {
+          if (profile.userId === result.userId) {
+            log.debug(
+              `sender resolved via voice: ${result.userId} (conf=${result.confidence.toFixed(2)})`,
+            )
+            return { ...profile, resolved: true }
+          }
+        }
+      }
+    } catch (err) {
+      log.error("voice-id identification failed", err)
+    }
+  }
+  return matchFromSenderMap(ctx, cfg)
+}
+
+/**
+ * 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]
+}
+
+/**
+ * Resolve the Role for a user. Looks first at the profile-level `role`
+ * override, then at `scoping.users[userId].role`. Returns undefined if
+ * scoping is disabled or the user has no role assignment.
+ */
+export function resolveRole(
+  user: ResolvedUser | undefined,
+  cfg: HyperspellConfig,
+): Role | undefined {
+  const scoping = cfg.multiUser?.scoping
+  if (!scoping || !user) return undefined
+  const roleName = user.role ?? scoping.users[user.userId]?.role
+  if (!roleName) return undefined
+  return scoping.roles[roleName]
+}
+
+/**
+ * Readable scopes for this user. If scoping is disabled, returns ["*"] so
+ * `buildScopeFilter` produces no filter and PR #6 behavior is preserved.
+ */
+export function getCanReadScopes(
+  user: ResolvedUser | undefined,
+  cfg: HyperspellConfig,
+): CanReadScope[] {
+  if (!cfg.multiUser?.scoping) return ["*"]
+  const role = resolveRole(user, cfg)
+  return role?.canRead ?? []
+}
+
+/**
+ * Default write scope for this user — explicit param > role default > global default.
+ */
+export function getDefaultWriteScope(
+  user: ResolvedUser | undefined,
+  cfg: HyperspellConfig,
+): ScopeName {
+  const role = resolveRole(user, cfg)
+  return (
+    role?.defaultWriteScope ??
+    cfg.multiUser?.scoping?.defaultScope ??
+    "private"
+  )
+}
+
+/**
+ * Build a MongoDB-style metadata filter for Hyperspell's `options.filter`.
+ *
+ * Contract:
+ * - `["*"]` (wildcard) → returns `undefined` (no filter).
+ * - `[]` (empty) → returns a **match-nothing** filter, NOT `undefined`. An
+ *   empty `canRead` is a deliberate "no access" signal and must not silently
+ *   return all results.
+ * - Otherwise: `$or` of named-scope clause and (if "self" present) an
+ *   own-user clause keyed by `openclaw_user`.
+ */
+export function buildScopeFilter(
+  canRead: CanReadScope[],
+  userId: string,
+): Record<string, unknown> | undefined {
+  if (canRead.includes("*")) return undefined
+  if (canRead.length === 0) {
+    // Deliberate "no access" — match nothing.
+    return { openclaw_scope: "__never__" }
+  }
+
+  const namedScopes = canRead.filter((s) => s !== "self" && s !== "*")
+  const includeSelf = canRead.includes("self")
+
+  const clauses: Array<Record<string, unknown>> = []
+  if (namedScopes.length > 0) {
+    clauses.push({
+      openclaw_scope: { $in: namedScopes.map((s) => normalizeScope(s)) },
+    })
+  }
+  if (includeSelf && userId) {
+    clauses.push({ openclaw_user: userId })
+  }
+
+  if (clauses.length === 0) {
+    return { openclaw_scope: "__never__" }
+  }
+  if (clauses.length === 1) {
+    return clauses[0]
+  }
+  return { $or: clauses }
+}
+
+/**
+ * Route a write: private scope stays in the user's own Hyperspell space
+ * (defense-in-depth); shared scopes go to `sharedUserId` with optional
+ * per-scope collection.
+ */
+export function routeWrite(
+  user: ResolvedUser | undefined,
+  scope: ScopeName,
+  cfg: HyperspellConfig,
+): { userId: string | undefined; collection: string | undefined } {
+  const scoping = cfg.multiUser?.scoping
+  if (scope === "private") {
+    return { userId: user?.userId, collection: undefined }
+  }
+  const sharedUserId = cfg.multiUser?.sharedUserId ?? user?.userId
+  const collection = scoping?.collections?.[scope]
+  return { userId: sharedUserId, collection }
+}

package/lib/voice-id.ts

@@ -0,0 +1,39 @@
+import type { HyperspellConfig } from "../config.ts"
+
+export interface VoiceIdResult {
+  userId: string
+  confidence: number
+}
+
+export interface VoiceIdentifier {
+  identify(audio: Buffer | string): Promise<VoiceIdResult | null>
+}
+
+const NO_OP: VoiceIdentifier = {
+  async identify() {
+    return null
+  },
+}
+
+const registry = new Map<string, VoiceIdentifier>()
+
+/**
+ * Register a voice-ID adapter implementation under a name that can be
+ * referenced from `cfg.multiUser.scoping.voiceId.adapter`. Call this from
+ * downstream code that wants to plug in a real speaker diarization model;
+ * Phase 1 ships with no adapters registered — the no-op is used.
+ */
+export function registerVoiceIdentifier(
+  name: string,
+  impl: VoiceIdentifier,
+): void {
+  registry.set(name, impl)
+}
+
+export function getVoiceIdentifier(cfg: HyperspellConfig): VoiceIdentifier {
+  const name = cfg.multiUser?.scoping?.voiceId?.adapter
+  if (name && registry.has(name)) {
+    return registry.get(name) as VoiceIdentifier
+  }
+  return NO_OP
+}

package/openclaw.plugin.json

@@ -64,6 +64,11 @@
 			"label": "Memory Network",
 			"help": "Extract entities (people, projects, orgs, topics) from memories into structured markdown files. Requires a cron job for periodic scanning.",
 			"advanced": true
+		},
+		"multiUser": {
+			"label": "Multi-User Support",
+			"help": "Per-sender context isolation for household or shared-device setups. Maps senders to user IDs; supports optional role-based privacy scopes (private/family/parent-only/etc).",
+			"advanced": true
 		}
 	},
 	"configSchema": {
@@ -124,6 +129,38 @@
 					},
 					"batchSize": { "type": "number", "minimum": 5, "maximum": 100 }
 				}
+			},
+			"multiUser": {
+				"type": "object",
+				"additionalProperties": true,
+				"properties": {
+					"senderMap": { "type": "object" },
+					"sharedUserId": { "type": "string" },
+					"includeSharedInSearch": { "type": "boolean" },
+					"scoping": {
+						"type": "object",
+						"additionalProperties": true,
+						"properties": {
+							"enabled": { "type": "boolean" },
+							"defaultScope": { "type": "string" },
+							"scopes": {
+								"type": "array",
+								"items": { "type": "string" }
+							},
+							"roles": { "type": "object" },
+							"users": { "type": "object" },
+							"collections": { "type": "object" },
+							"voiceId": {
+								"type": "object",
+								"properties": {
+									"enabled": { "type": "boolean" },
+									"adapter": { "type": "string" },
+									"confidenceThreshold": { "type": "number" }
+								}
+							}
+						}
+					}
+				}
 			}
 		},
 		"required": []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "OpenClaw Hyperspell memory plugin",
   "license": "MIT",
@@ -42,7 +42,8 @@
   "scripts": {
     "check-types": "tsc --noEmit",
     "lint": "bunx @biomejs/biome ci .",
-    "lint:fix": "bunx @biomejs/biome check --write ."
+    "lint:fix": "bunx @biomejs/biome check --write .",
+    "test": "node --test --experimental-strip-types lib/sender.test.ts config.test.ts"
   },
   "openclaw": {
     "extensions": [

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,132 @@
 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 {
+  getDefaultWriteScope,
+  resolveRole,
+  resolveUser,
+  routeWrite,
+} 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,
+) {
+  const scopingEnabled = !!cfg.multiUser?.scoping
+  const availableScopes = cfg.multiUser?.scoping?.scopes ?? []
+  const scopeDescription = scopingEnabled
+    ? `Privacy scope for this memory. Available: ${availableScopes.join(", ")}. Defaults to the user's role default.`
+    : "Privacy scope (only used when scoping is enabled in config)."
 
-        try {
-          await client.addMemory(params.text, {
-            title: params.title,
-            date: params.date,
-            metadata: { source: "openclaw_tool" },
-          })
+  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.",
+        }),
+      ),
+      scope: Type.Optional(
+        Type.String({ description: scopeDescription }),
+      ),
+    }),
+    async execute(
+      _toolCallId: string,
+      params: { text: string; title?: string; date?: string; userId?: string; scope?: string },
+    ) {
+      const resolved = resolveUser(ctx, cfg)
 
-          const preview =
-            params.text.length > 80 ? `${params.text.slice(0, 80)}…` : params.text
+      // Scope resolution: explicit param > role default > global default > "private"
+      const scope =
+        params.scope ??
+        (scopingEnabled ? getDefaultWriteScope(resolved, cfg) : "private")
 
-          return {
-            content: [{ type: "text" as const, text: `Stored: "${preview}"` }],
-          }
-        } catch (err) {
-          log.error("remember tool failed", err)
+      // Validate scope is in declared vocabulary (if scoping is enabled)
+      if (
+        scopingEnabled &&
+        availableScopes.length > 0 &&
+        !availableScopes.includes(scope)
+      ) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Unknown scope "${scope}". Available: ${availableScopes.join(", ")}.`,
+            },
+          ],
+        }
+      }
+
+      // canWriteScopes enforcement (role-level deny list)
+      if (scopingEnabled) {
+        const role = resolveRole(resolved, cfg)
+        if (role?.canWriteScopes && !role.canWriteScopes.includes(scope)) {
           return {
             content: [
               {
                 type: "text" as const,
-                text: `Failed to store memory: ${err instanceof Error ? err.message : String(err)}`,
+                text: `You cannot write to scope "${scope}".`,
               },
             ],
           }
         }
-      },
+      }
+
+      // Route: explicit userId override takes precedence; otherwise derive from scope
+      let userId: string | undefined
+      let collection: string | undefined
+      if (params.userId) {
+        userId = params.userId
+      } else if (scopingEnabled) {
+        const routed = routeWrite(resolved, scope, cfg)
+        userId = routed.userId
+        collection = routed.collection
+      } else {
+        userId = resolved?.userId
+      }
+
+      log.debug(
+        `remember tool: "${params.text.slice(0, 50)}..." date=${params.date ?? "now"} userId=${userId} scope=${scope}`,
+      )
+
+      try {
+        await client.addMemory(params.text, {
+          title: params.title,
+          date: params.date,
+          collection,
+          metadata: { source: "openclaw_tool" },
+          userId,
+          scope: scopingEnabled ? scope : undefined,
+        })
+
+        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)}`,
+            },
+          ],
+        }
+      }
     },
-    { name: "hyperspell_remember" },
-  )
+  })
 }