@hyperspell/openclaw-hyperspell 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,7 @@
 # OpenClaw Hyperspell Plugin
 
+![Hyperspell x OpenClaw](https://github.com/user-attachments/assets/5ac86aab-0f0f-4f14-bde5-0652e625aa86)
+
 OpenClaw plugin for [Hyperspell](https://hyperspell.com) - Context and memory for your AI agents.
 
 ## Installation
@@ -8,19 +10,40 @@ OpenClaw plugin for [Hyperspell](https://hyperspell.com) - Context and memory fo
 openclaw plugins install @hyperspell/openclaw-hyperspell
 ```
 
-## Configuration
+## Quick Start
+
+Run the interactive setup wizard:
+
+```bash
+openclaw openclaw-hyperspell setup
+```
+
+The setup wizard will guide you through:
+1. Creating a Hyperspell account (if you don't have one)
+2. Configuring your API key
+3. Setting up your User ID for multi-tenant memory
+4. Connecting your apps (Notion, Slack, Google Drive, etc.)
+
+## Manual Configuration
 
-Add to your `openclaw.json`:
+Alternatively, add to your `openclaw.json`:
 
 ```json
 {
   "plugins": {
-    "openclaw-hyperspell": {
-      "apiKey": "${HYPERSPELL_API_KEY}",
-      "autoContext": true
+    "entries": {
+      "openclaw-hyperspell": {
+        "enabled": true,
+        "config": {
+          "apiKey": "${HYPERSPELL_API_KEY}",
+          "userId": "your-email",
+          "autoContext": true
+        }
+      }
     }
   }
 }
+
 ```
 
 Or set the environment variable:
@@ -29,12 +52,26 @@ Or set the environment variable:
 export HYPERSPELL_API_KEY=hs_...
 ```
 
+## CLI Commands
+
+### `openclaw openclaw-hyperspell setup`
+
+Interactive setup wizard that walks you through configuration.
+
+### `openclaw openclaw-hyperspell status`
+
+Check your current configuration and connection status.
+
+### `openclaw openclaw-hyperspell connect`
+
+Open the Hyperspell connect page to link your accounts (Notion, Slack, Google Drive, etc.)
+
 ### Options
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `apiKey` | string | `${HYPERSPELL_API_KEY}` | Hyperspell API key |
-| `userId` | string | - | User ID to scope searches (for non-JWT API keys) |
+| `userId` | string | - | User ID (can be your email) |
 | `autoContext` | boolean | `true` | Auto-inject relevant memories before each AI turn |
 | `sources` | string | - | Comma-separated sources to search (e.g., `notion,slack`) |
 | `maxResults` | number | `10` | Maximum memories per context injection |
@@ -42,22 +79,12 @@ export HYPERSPELL_API_KEY=hs_...
 
 ## Slash Commands
 
-### `/context <query>`
+### `/getcontext <query>`
 
 Search your memories for relevant context.
 
 ```
-/context Q1 budget planning
-```
-
-### `/connect <source>`
-
-Connect an account to Hyperspell. Opens the OAuth flow in your browser.
-
-```
-/connect notion
-/connect slack
-/connect google_drive
+/getcontext Q1 budget planning
 ```
 
 ### `/remember <text>`
@@ -87,12 +114,11 @@ This ensures the AI always has access to relevant information from your connecte
 
 ## Available Sources
 
-- `collections` - User-created collections
+- `vault` - User-created memories
 - `notion` - Notion pages and databases
 - `slack` - Slack messages
 - `google_calendar` - Google Calendar events
 - `google_mail` - Gmail messages
 - `google_drive` - Google Drive files
 - `box` - Box files
-- `vault` - Vault documents
 - `web_crawler` - Crawled web pages

package/client.ts

@@ -11,6 +11,11 @@ export type SearchResult = {
   createdAt: string | null
 }
 
+export type SearchWithAnswerResult = {
+  answer: string | null
+  documents: SearchResult[]
+}
+
 export type Integration = {
   id: string
   name: string
@@ -18,6 +23,13 @@ export type Integration = {
   icon: string
 }
 
+export type Connection = {
+  id: string
+  integrationId: string
+  label: string | null
+  provider: HyperspellSource
+}
+
 export class HyperspellClient {
   private client: Hyperspell
   private config: HyperspellConfig
@@ -26,8 +38,9 @@ export class HyperspellClient {
     this.config = config
     this.client = new Hyperspell({
       apiKey: config.apiKey,
+      userID: config.userId,
     })
-    log.info("client initialized")
+    log.info(`client initialized${config.userId ? ` for user ${config.userId}` : ""}`)
   }
 
   async search(
@@ -61,6 +74,68 @@ export class HyperspellClient {
     return results
   }
 
+  async searchRaw(
+    query: string,
+    options?: { limit?: number; sources?: HyperspellSource[] },
+  ): 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 })
+
+    const response = await this.client.memories.search({
+      query,
+      sources,
+      options: {
+        max_results: limit,
+      },
+    })
+
+    log.debugResponse("memories.search (raw)", { count: response.documents.length })
+
+    return response as unknown as Record<string, unknown>
+  }
+
+  async searchWithAnswer(
+    query: string,
+    options?: { limit?: number; sources?: HyperspellSource[] },
+  ): Promise<SearchWithAnswerResult> {
+    const limit = options?.limit ?? this.config.maxResults
+    const sources =
+      options?.sources ?? (this.config.sources.length > 0 ? this.config.sources : undefined)
+
+    log.debugRequest("memories.search (with answer)", { query, limit, sources })
+
+    const response = await this.client.memories.search({
+      query,
+      sources,
+      answer: true,
+      options: {
+        max_results: limit,
+      },
+    })
+
+    const documents: SearchResult[] = response.documents.map((doc) => ({
+      resourceId: doc.resource_id,
+      title: doc.title ?? null,
+      source: doc.source as HyperspellSource,
+      score: doc.score ?? null,
+      url: doc.metadata?.url as string | null ?? null,
+      createdAt: doc.metadata?.created_at as string | null ?? null,
+    }))
+
+    log.debugResponse("memories.search (with answer)", {
+      count: documents.length,
+      hasAnswer: !!response.answer,
+    })
+
+    return {
+      answer: response.answer ?? null,
+      documents,
+    }
+  }
+
   async addMemory(
     text: string,
     options?: { title?: string; metadata?: Record<string, string | number | boolean> },
@@ -110,4 +185,20 @@ export class HyperspellClient {
       expiresAt: response.expires_at,
     }
   }
+
+  async listConnections(): Promise<Connection[]> {
+    log.debugRequest("connections.list", {})
+
+    const response = await this.client.connections.list()
+
+    const connections: Connection[] = response.connections.map((conn) => ({
+      id: conn.id,
+      integrationId: conn.integration_id,
+      label: conn.label,
+      provider: conn.provider as HyperspellSource,
+    }))
+
+    log.debugResponse("connections.list", { count: connections.length })
+    return connections
+  }
 }

package/commands/setup.ts

@@ -0,0 +1,470 @@
+import { exec } from "node:child_process"
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { homedir, platform, userInfo } from "node:os"
+import * as p from "@clack/prompts"
+import type { Command } from "commander"
+import Hyperspell from "hyperspell"
+
+/**
+ * Resolve OpenClaw state directory, matching OpenClaw's logic.
+ * Checks OPENCLAW_STATE_DIR env var, falls back to ~/.openclaw
+ */
+function resolveStateDir(): string {
+  const override = process.env.OPENCLAW_STATE_DIR?.trim() || process.env.CLAWDBOT_STATE_DIR?.trim()
+  if (override) {
+    return override.startsWith("~")
+      ? override.replace(/^~(?=$|[\\/])/, homedir())
+      : path.resolve(override)
+  }
+  return path.join(homedir(), ".openclaw")
+}
+
+/**
+ * Resolve OpenClaw config path, matching OpenClaw's logic.
+ * Checks OPENCLAW_CONFIG_PATH env var, falls back to $STATE_DIR/openclaw.json
+ */
+function resolveConfigPath(): string {
+  const override = process.env.OPENCLAW_CONFIG_PATH?.trim() || process.env.CLAWDBOT_CONFIG_PATH?.trim()
+  if (override) {
+    return override.startsWith("~")
+      ? override.replace(/^~(?=$|[\\/])/, homedir())
+      : path.resolve(override)
+  }
+  return path.join(resolveStateDir(), "openclaw.json")
+}
+
+async function fetchConnectionSources(client: Hyperspell, userId: string): Promise<string[]> {
+  try {
+    const userClient = new Hyperspell({
+      apiKey: client.apiKey,
+      userID: userId,
+    })
+    const response = await userClient.connections.list()
+    const providers = response.connections.map((conn) => conn.provider)
+    // Add vault and deduplicate
+    const sources = [...new Set(["vault", ...providers])]
+    return sources
+  } catch (_error) {
+    return ["vault"]
+  }
+}
+
+function updateConfigSources(configPath: string, sources: string[]): void {
+  if (!fs.existsSync(configPath)) return
+
+  const content = fs.readFileSync(configPath, "utf-8")
+  const config = JSON.parse(content)
+
+  const pluginConfig = config?.plugins?.entries?.["openclaw-hyperspell"]?.config
+  if (pluginConfig) {
+    pluginConfig.sources = sources.join(",")
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n")
+  }
+}
+
+function openUrl(url: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let command: string
+    switch (platform()) {
+      case "darwin":
+        command = `open "${url}"`
+        break
+      case "win32":
+        command = `start "" "${url}"`
+        break
+      default:
+        command = `xdg-open "${url}"`
+    }
+    exec(command, (error) => {
+      if (error) reject(error)
+      else resolve()
+    })
+  })
+}
+
+async function runSetup(): Promise<void> {
+  p.intro("Hyperspell Setup")
+
+  // Step 1: Check if they have an account
+  const hasAccount = await p.confirm({
+    message: "Do you already have a Hyperspell account?",
+  })
+
+  if (p.isCancel(hasAccount)) {
+    p.cancel("Setup cancelled")
+    return
+  }
+
+  if (!hasAccount) {
+    p.note(
+      "1. Go to https://app.hyperspell.com to create a free account\n" +
+        "2. Create a new app for your AI agent\n" +
+        "3. Select which integrations you want to connect (Notion, Slack, etc.)",
+      "Create an account",
+    )
+
+    const openSignup = await p.confirm({
+      message: "Open app.hyperspell.com in your browser?",
+    })
+
+    if (p.isCancel(openSignup)) {
+      p.cancel("Setup cancelled")
+      return
+    }
+
+    if (openSignup) {
+      await openUrl("https://app.hyperspell.com")
+      p.log.info("Browser opened. Come back when you've created your account.")
+    }
+
+    await p.confirm({
+      message: "Ready to continue?",
+      active: "Yes",
+      inactive: "No",
+    })
+  }
+
+  // Step 2: Get API Key
+  p.note(
+    "1. Go to your app in https://app.hyperspell.com\n" +
+      "2. Navigate to Settings > API Keys\n" +
+      "3. Create a new API key",
+    "API Key",
+  )
+
+  const apiKey = await p.text({
+    message: "Paste your API key",
+    placeholder: "hs_...",
+    validate: (value) => {
+      if (!value) return "API key is required"
+    },
+  })
+
+  if (p.isCancel(apiKey)) {
+    p.cancel("Setup cancelled")
+    return
+  }
+
+  // Validate API key
+  const s = p.spinner()
+  s.start("Validating API key")
+
+  let client: Hyperspell
+  try {
+    client = new Hyperspell({ apiKey })
+    await client.integrations.list()
+    s.stop("API key is valid")
+  } catch (_error) {
+    s.stop("API key validation failed")
+    p.log.error("Please check that your API key is correct and try again.")
+    return
+  }
+
+  // Step 3: User ID
+  p.note(
+    "Hyperspell is a multi-tenant memory platform. Each user's memories\n" +
+      "are stored separately, identified by a User ID.\n\n" +
+      "For a personal agent, use your email address or username.",
+    "User ID",
+  )
+
+  const systemUser = userInfo().username
+  const userId = await p.text({
+    message: "Enter a User ID for this agent",
+    placeholder: systemUser || "your-email@example.com",
+    defaultValue: systemUser,
+  })
+
+  if (p.isCancel(userId)) {
+    p.cancel("Setup cancelled")
+    return
+  }
+
+  // Step 4: List and connect integrations
+  let integrations: Awaited<ReturnType<typeof client.integrations.list>>
+  try {
+    integrations = await client.integrations.list()
+  } catch (_error) {
+    integrations = { integrations: [] }
+  }
+
+  if (integrations.integrations.length === 0) {
+    p.note(
+      "No integrations are configured in your app yet.\n" +
+        "Go to https://app.hyperspell.com to add integrations,\n" +
+        "then use /connect <source> to connect them.",
+      "Connect Your Apps",
+    )
+  } else {
+    const integrationList = integrations.integrations
+      .map((int) => `• ${int.name} (${int.provider})`)
+      .join("\n")
+
+    // Get a user token for the connect page
+    let connectUrl: string
+    try {
+      const tokenResponse = await client.auth.userToken({ user_id: userId })
+      connectUrl = `https://connect.hyperspell.com?token=${tokenResponse.token}`
+    } catch (_error) {
+      p.log.error("Could not generate connect URL. You can connect apps later using /connect.")
+      connectUrl = ""
+    }
+
+    p.note(
+      `Available integrations:\n${integrationList}` +
+        (connectUrl ? `\n\nConnect your accounts at:\n${connectUrl}` : ""),
+      "Connect Your Apps",
+    )
+
+    if (connectUrl) {
+      const openConnect = await p.confirm({
+        message: "Open connection page in your browser?",
+      })
+
+      if (!p.isCancel(openConnect) && openConnect) {
+        await openUrl(connectUrl)
+        p.log.info("Browser opened. Connect your accounts and come back when done.")
+
+        await p.confirm({
+          message: "Finished connecting accounts?",
+          active: "Yes",
+          inactive: "Not yet",
+        })
+      }
+    }
+  }
+
+  // Fetch connected sources
+  const s1 = p.spinner()
+  s1.start("Fetching connected sources")
+  const sources = await fetchConnectionSources(client, userId)
+  s1.stop(`Found ${sources.length} sources: ${sources.join(", ")}`)
+
+  // Step 5: Save configuration
+  const s2 = p.spinner()
+  s2.start("Saving configuration")
+
+  try {
+    const configPath = resolveConfigPath()
+    const openclawDir = path.dirname(configPath)
+    const envPath = path.join(openclawDir, ".env")
+
+    // Ensure directory exists
+    if (!fs.existsSync(openclawDir)) {
+      fs.mkdirSync(openclawDir, { recursive: true })
+    }
+
+    // Read existing config or create new one
+    let config: Record<string, unknown> = {}
+    if (fs.existsSync(configPath)) {
+      const existing = fs.readFileSync(configPath, "utf-8")
+      config = JSON.parse(existing)
+    }
+
+    // Merge in plugin configuration
+    if (!config.plugins) {
+      config.plugins = {}
+    }
+    const plugins = config.plugins as Record<string, unknown>
+    if (!plugins.entries) {
+      plugins.entries = {}
+    }
+    const entries = plugins.entries as Record<string, unknown>
+    entries["openclaw-hyperspell"] = {
+      enabled: true,
+      config: {
+        apiKey: "${HYPERSPELL_API_KEY}",
+        userId,
+        sources: sources.join(","),
+        autoContext: true,
+      },
+    }
+
+    // Write config
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n")
+
+    // Write or append to .env
+    const envLine = `HYPERSPELL_API_KEY=${apiKey}`
+    if (fs.existsSync(envPath)) {
+      const envContent = fs.readFileSync(envPath, "utf-8")
+      if (envContent.includes("HYPERSPELL_API_KEY=")) {
+        // Replace existing line
+        const updated = envContent.replace(/^HYPERSPELL_API_KEY=.*$/m, envLine)
+        fs.writeFileSync(envPath, updated)
+      } else {
+        // Append new line
+        fs.appendFileSync(envPath, (envContent.endsWith("\n") ? "" : "\n") + envLine + "\n")
+      }
+    } else {
+      fs.writeFileSync(envPath, envLine + "\n")
+    }
+
+    s2.stop("Configuration saved")
+
+    p.note(
+      `Config: ${configPath}\n` +
+        `API Key: ${envPath}`,
+      "Files updated",
+    )
+  } catch (error) {
+    s2.stop("Failed to save configuration")
+
+    // Fall back to showing manual instructions
+    const configJson = JSON.stringify(
+      {
+        plugins: {
+          entries: {
+            "openclaw-hyperspell": {
+              enabled: true,
+              config: {
+                apiKey: "${HYPERSPELL_API_KEY}",
+                userId,
+                sources: sources.join(","),
+                autoContext: true,
+              },
+            },
+          },
+        },
+      },
+      null,
+      2,
+    )
+
+    p.note(
+      `Add to your openclaw.json:\n\n${configJson}\n\n` +
+        `Set the environment variable:\n  export HYPERSPELL_API_KEY=${apiKey}`,
+      "Manual configuration required",
+    )
+  }
+
+  p.note(
+    "/getcontext <query>  Search your memories for relevant context\n" +
+      "/remember <text>     Save something directly to your vault\n\n" +
+      "To connect more apps, run: openclaw openclaw-hyperspell connect\n\n" +
+      "Auto-context is enabled by default — relevant memories are\n" +
+      "automatically injected before each AI response.",
+    "How to use Hyperspell",
+  )
+
+  p.outro("Setup complete!")
+}
+
+async function runConnect(pluginConfig: unknown): Promise<void> {
+  const config = pluginConfig as Record<string, unknown> | undefined
+
+  p.intro("Hyperspell Connect")
+
+  if (!config?.apiKey) {
+    p.log.error("Not configured")
+    p.note("Run 'openclaw openclaw-hyperspell setup' to configure Hyperspell first.")
+    p.outro("")
+    return
+  }
+
+  const s = p.spinner()
+  s.start("Generating connect URL")
+
+  let client: Hyperspell
+  let userId: string
+  try {
+    client = new Hyperspell({ apiKey: config.apiKey as string })
+    userId = (config.userId as string) || userInfo().username || "user"
+    const tokenResponse = await client.auth.userToken({ user_id: userId })
+    const connectUrl = `https://connect.hyperspell.com?token=${tokenResponse.token}`
+
+    s.stop("Connect URL ready")
+
+    await openUrl(connectUrl)
+    p.log.success("Browser opened to connect.hyperspell.com")
+
+    await p.confirm({
+      message: "Finished connecting accounts?",
+      active: "Yes",
+      inactive: "Not yet",
+    })
+
+    // Fetch and update sources
+    const s2 = p.spinner()
+    s2.start("Updating sources configuration")
+
+    const sources = await fetchConnectionSources(client, userId)
+    const configPath = resolveConfigPath()
+    updateConfigSources(configPath, sources)
+
+    s2.stop(`Sources updated: ${sources.join(", ")}`)
+
+    p.outro("Done! Restart OpenClaw to apply changes.")
+  } catch (_error) {
+    s.stop("Failed to generate connect URL")
+    p.log.error("Check your API key and try again.")
+    p.outro("")
+  }
+}
+
+async function runStatus(pluginConfig: unknown): Promise<void> {
+  const config = pluginConfig as Record<string, unknown> | undefined
+
+  p.intro("Hyperspell Status")
+
+  if (!config?.apiKey) {
+    p.log.warn("Not configured")
+    p.note("Run 'openclaw openclaw-hyperspell setup' to configure Hyperspell.")
+    p.outro("")
+    return
+  }
+
+  p.log.success("Configured")
+  p.log.info(`User ID: ${config.userId || "(not set)"}`)
+  p.log.info(`Auto-Context: ${config.autoContext !== false ? "Enabled" : "Disabled"}`)
+  p.log.info(`Sources Filter: ${config.sources || "(all sources)"}`)
+  p.log.info(`Max Results: ${config.maxResults || 10}`)
+
+  const s = p.spinner()
+  s.start("Testing connection")
+
+  try {
+    const client = new Hyperspell({ apiKey: config.apiKey as string })
+    const integrations = await client.integrations.list()
+    s.stop(`Connection OK (${integrations.integrations.length} integrations available)`)
+
+    if (integrations.integrations.length > 0) {
+      const list = integrations.integrations
+        .map((int) => `• ${int.name} (${int.provider})`)
+        .join("\n")
+      p.note(list, "Available integrations")
+    }
+  } catch (_error) {
+    s.stop("Connection failed")
+    p.log.error("Check your API key and try again.")
+  }
+
+  p.outro("")
+}
+
+export function registerCliCommands(program: Command, pluginConfig: unknown): void {
+  const hyperspellCmd = program
+    .command("openclaw-hyperspell")
+    .description("Hyperspell — Memory and context for your AI agent")
+
+  hyperspellCmd
+    .command("setup")
+    .description("Interactive setup wizard for Hyperspell")
+    .action(async () => {
+      await runSetup()
+    })
+
+  hyperspellCmd
+    .command("status")
+    .description("Show Hyperspell connection status")
+    .action(async () => {
+      await runStatus(pluginConfig)
+    })
+
+  hyperspellCmd
+    .command("connect")
+    .description("Open the Hyperspell connect page to link your accounts")
+    .action(async () => {
+      await runConnect(pluginConfig)
+    })
+}

package/commands/slash.ts

@@ -1,7 +1,6 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import type { HyperspellClient } from "../client.ts"
 import type { HyperspellConfig } from "../config.ts"
-import { openInBrowser } from "../lib/browser.ts"
 import { log } from "../logger.ts"
 
 function truncate(text: string, maxLength: number): string {
@@ -19,19 +18,19 @@ export function registerCommands(
   client: HyperspellClient,
   _cfg: HyperspellConfig,
 ): void {
-  // /context <query> - Search memories and show summaries
+  // /getcontext <query> - Search memories and show summaries
   api.registerCommand({
-    name: "context",
+    name: "getcontext",
     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: /context <search query>" }
+        return { text: "Usage: /getcontext <search query>" }
       }
 
-      log.debug(`/context command: "${query}"`)
+      log.debug(`/getcontext command: "${query}"`)
 
       try {
         const results = await client.search(query, { limit: 5 })
@@ -50,65 +49,12 @@ export function registerCommands(
           text: `Found ${results.length} memories:\n\n${lines.join("\n")}`,
         }
       } catch (err) {
-        log.error("/context failed", err)
+        log.error("/getcontext failed", err)
         return { text: "Failed to search memories. Check logs for details." }
       }
     },
   })
 
-  // /connect <source> - Open connection URL for an integration
-  api.registerCommand({
-    name: "connect",
-    description: "Connect an account to Hyperspell",
-    acceptsArgs: true,
-    requireAuth: true,
-    handler: async (ctx: { args?: string }) => {
-      const source = ctx.args?.trim().toLowerCase()
-      if (!source) {
-        return { text: "Usage: /connect <source>\n\nExamples: /connect notion, /connect slack" }
-      }
-
-      log.debug(`/connect command: "${source}"`)
-
-      try {
-        const integrations = await client.listIntegrations()
-
-        // Find matching integration by provider or name
-        const integration = integrations.find(
-          (int) =>
-            int.provider.toLowerCase() === source ||
-            int.name.toLowerCase() === source ||
-            int.id.toLowerCase() === source,
-        )
-
-        if (!integration) {
-          const available = integrations.map((i) => i.provider).join(", ")
-          return {
-            text: `Integration "${source}" not found.\n\nAvailable: ${available}`,
-          }
-        }
-
-        const { url } = await client.getConnectUrl(integration.id)
-
-        // Auto-open in browser
-        try {
-          await openInBrowser(url)
-          return {
-            text: `Opening ${integration.name} connection in your browser...`,
-          }
-        } catch {
-          // Fall back to showing the URL if browser open fails
-          return {
-            text: `Connect your ${integration.name} account:\n${url}`,
-          }
-        }
-      } catch (err) {
-        log.error("/connect failed", err)
-        return { text: "Failed to get connect URL. Check logs for details." }
-      }
-    },
-  })
-
   // /remember <text> - Add a new memory
   api.registerCommand({
     name: "remember",

package/config.ts

@@ -62,8 +62,30 @@ function resolveEnvVars(value: string): string {
   })
 }
 
-function parseSources(raw: string | undefined): HyperspellSource[] {
-  if (!raw || raw.trim() === "") {
+function parseSources(raw: string | string[] | undefined): HyperspellSource[] {
+  if (!raw) {
+    return []
+  }
+
+  // Handle array input
+  if (Array.isArray(raw)) {
+    const sources = raw
+      .map((s) => String(s).trim().toLowerCase())
+      .filter((s) => s.length > 0) as HyperspellSource[]
+
+    for (const source of sources) {
+      if (!VALID_SOURCES.includes(source)) {
+        throw new Error(
+          `Invalid source "${source}". Valid sources: ${VALID_SOURCES.join(", ")}`,
+        )
+      }
+    }
+
+    return sources
+  }
+
+  // Handle string input (comma-separated)
+  if (typeof raw === "string" && raw.trim() === "") {
     return []
   }
 
@@ -108,7 +130,7 @@ export function parseConfig(raw: unknown): HyperspellConfig {
     apiKey,
     userId: cfg.userId as string | undefined,
     autoContext: (cfg.autoContext as boolean) ?? true,
-    sources: parseSources(cfg.sources as string | undefined),
+    sources: parseSources(cfg.sources as string | string[] | undefined),
     maxResults: (cfg.maxResults as number) ?? 10,
     debug: (cfg.debug as boolean) ?? false,
   }

package/index.ts

@@ -1,6 +1,7 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import { HyperspellClient } from "./client.ts"
 import { registerCommands } from "./commands/slash.ts"
+import { registerCliCommands } from "./commands/setup.ts"
 import { parseConfig, hyperspellConfigSchema } from "./config.ts"
 import { buildAutoContextHandler } from "./hooks/auto-context.ts"
 import { initLogger } from "./logger.ts"
@@ -10,11 +11,47 @@ import { registerSearchTool } from "./tools/search.ts"
 export default {
   id: "openclaw-hyperspell",
   name: "Hyperspell",
-  description: "OpenClaw powered by Hyperspell - RAG-as-a-service for your connected sources",
+  description: "Hyperspell gives your Molty context and memory from all your existing data",
   kind: "memory" as const,
   configSchema: hyperspellConfigSchema,
 
   register(api: OpenClawPluginApi) {
+    // Register CLI commands (openclaw openclaw-hyperspell setup|status|connect)
+    api.registerCli(
+      (ctx) => {
+        registerCliCommands(ctx.program, api.pluginConfig)
+      },
+      { commands: ["openclaw-hyperspell"] },
+    )
+
+    // Check if configured
+    const rawConfig = api.pluginConfig as Record<string, unknown> | undefined
+    const hasConfig = rawConfig?.apiKey || process.env.HYPERSPELL_API_KEY
+
+    if (!hasConfig) {
+      api.logger.info("hyperspell: not configured - run 'openclaw openclaw-hyperspell setup'")
+      // Still register slash commands so they show up, but they'll return an error
+      api.registerCommand({
+        name: "getcontext",
+        description: "Search your memories for relevant context",
+        acceptsArgs: true,
+        requireAuth: false,
+        handler: async () => {
+          return { text: "Hyperspell not configured. Run 'openclaw openclaw-hyperspell setup' first." }
+        },
+      })
+      api.registerCommand({
+        name: "remember",
+        description: "Save something to memory",
+        acceptsArgs: true,
+        requireAuth: false,
+        handler: async () => {
+          return { text: "Hyperspell not configured. Run 'openclaw openclaw-hyperspell setup' first." }
+        },
+      })
+      return
+    }
+
     const cfg = parseConfig(api.pluginConfig)
 
     initLogger(api.logger, cfg.debug)

package/openclaw.plugin.json

@@ -11,12 +11,13 @@
     "userId": {
       "label": "User ID",
       "placeholder": "user_123",
-      "help": "Optional user ID to scope searches. Required for non-JWT API keys.",
-      "advanced": true
+      "help": "User ID (can be your email)",
+      "advanced": false
     },
     "autoContext": {
       "label": "Auto-Context",
-      "help": "Inject relevant memories before every AI turn"
+      "help": "Inject relevant memories before every AI turn",
+      "advanced": true
     },
     "sources": {
       "label": "Sources",
@@ -40,13 +41,27 @@
     "type": "object",
     "additionalProperties": false,
     "properties": {
-      "apiKey": { "type": "string" },
-      "userId": { "type": "string" },
-      "autoContext": { "type": "boolean" },
-      "sources": { "type": "string" },
-      "maxResults": { "type": "number", "minimum": 1, "maximum": 20 },
-      "debug": { "type": "boolean" }
+      "apiKey": {
+        "type": "string"
+      },
+      "userId": {
+        "type": "string"
+      },
+      "autoContext": {
+        "type": "boolean"
+      },
+      "sources": {
+        "type": "string"
+      },
+      "maxResults": {
+        "type": "number",
+        "minimum": 1,
+        "maximum": 20
+      },
+      "debug": {
+        "type": "boolean"
+      }
     },
     "required": []
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "OpenClaw Hyperspell memory plugin",
   "license": "MIT",
@@ -28,8 +28,9 @@
     "plugin"
   ],
   "dependencies": {
-    "hyperspell": "^0.30.0",
-    "@sinclair/typebox": "^0.34.0"
+    "@clack/prompts": "^1.0.0",
+    "@sinclair/typebox": "^0.34.0",
+    "hyperspell": "^0.30.0"
   },
   "peerDependencies": {
     "openclaw": ">=2026.1.29"
@@ -40,9 +41,11 @@
     "lint:fix": "bunx @biomejs/biome check --write ."
   },
   "openclaw": {
-    "extensions": ["./index.ts"]
+    "extensions": [
+      "./index.ts"
+    ]
   },
   "devDependencies": {
     "typescript": "^5.9.3"
   }
-}
+}

package/tools/remember.ts

@@ -26,16 +26,28 @@ export function registerRememberTool(
       ) {
         log.debug(`remember tool: "${params.text.slice(0, 50)}..."`)
 
-        await client.addMemory(params.text, {
-          title: params.title,
-          metadata: { source: "openclaw_tool" },
-        })
+        try {
+          await client.addMemory(params.text, {
+            title: params.title,
+            metadata: { source: "openclaw_tool" },
+          })
 
-        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}"` }],
+          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)}`,
+              },
+            ],
+          }
         }
       },
     },

package/tools/search.ts

@@ -28,42 +28,62 @@ export function registerSearchTool(
         const limit = params.limit ?? 5
         log.debug(`search tool: query="${params.query}" limit=${limit}`)
 
-        const results = await client.search(params.query, { limit })
+        try {
+          const response = await client.searchRaw(params.query, { limit })
+          const documents = (response.documents ?? []) as Array<{
+            source: string
+            resource_id: string
+            score?: number
+            summary?: string
+            title?: string
+            metadata?: Record<string, unknown>
+            highlights?: Array<{ text: string }>
+            data?: Array<{ text: string }>
+          }>
 
-        if (results.length === 0) {
-          return {
-            content: [
-              { type: "text" as const, text: "No relevant memories found." },
-            ],
+          if (documents.length === 0) {
+            return {
+              content: [
+                { type: "text" as const, text: "No relevant memories found." },
+              ],
+            }
           }
-        }
 
-        const text = results
-          .map((r, i) => {
-            const title = r.title ?? `[${r.source}]`
-            const score = r.score
-              ? ` (${Math.round(r.score * 100)}%)`
-              : ""
-            return `${i + 1}. ${title}${score}`
-          })
-          .join("\n")
+          const formattedDocs = documents
+            .map((doc, i) => {
+              const relevance = doc.score
+                ? `${Math.round(doc.score * 100)}%`
+                : "N/A"
+              const title = doc.title || "(untitled)"
+              const summary = doc.summary || "(no summary)"
+              return `${i + 1}. Source: ${doc.source}\n   Title: ${title}\n   Summary: ${summary}\n   Relevance: ${relevance}`
+            })
+            .join("\n\n")
 
-        return {
-          content: [
-            {
-              type: "text" as const,
-              text: `Found ${results.length} memories:\n\n${text}`,
+          const text = `Found ${documents.length} memories:\n\n${formattedDocs}`
+
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text,
+              },
+            ],
+            details: {
+              count: documents.length,
+              documents,
             },
-          ],
-          details: {
-            count: results.length,
-            memories: results.map((r) => ({
-              resourceId: r.resourceId,
-              title: r.title,
-              source: r.source,
-              score: r.score,
-            })),
-          },
+          }
+        } catch (err) {
+          log.error("search tool failed", err)
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Search failed: ${err instanceof Error ? err.message : String(err)}`,
+              },
+            ],
+          }
         }
       },
     },

package/types/openclaw.d.ts

@@ -1,4 +1,20 @@
 declare module "openclaw/plugin-sdk" {
+  import type { Command } from "commander"
+
+  export interface OpenClawPluginCliContext {
+    program: Command
+    config: unknown
+    workspaceDir?: string
+    logger: {
+      info: (message: string, ...args: unknown[]) => void
+      warn: (message: string, ...args: unknown[]) => void
+      error: (message: string, ...args: unknown[]) => void
+      debug: (message: string, ...args: unknown[]) => void
+    }
+  }
+
+  export type OpenClawPluginCliRegistrar = (ctx: OpenClawPluginCliContext) => void | Promise<void>
+
   export interface OpenClawPluginApi {
     pluginConfig: unknown
     logger: {
@@ -14,6 +30,7 @@ declare module "openclaw/plugin-sdk" {
       requireAuth: boolean
       handler: (ctx: { args?: string; senderId?: string; channel?: string }) => Promise<{ text: string }>
     }): void
+    registerCli(registrar: OpenClawPluginCliRegistrar, opts?: { commands?: string[] }): void
     registerTool<T = unknown>(
       options: {
         name: string