@hyperspell/openclaw-hyperspell 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# OpenClaw Hyperspell Plugin
+
+OpenClaw plugin for [Hyperspell](https://hyperspell.com) - Context and memory for your AI agents.
+
+## Installation
+
+```bash
+openclaw plugins install @hyperspell/openclaw-hyperspell
+```
+
+## Configuration
+
+Add to your `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "openclaw-hyperspell": {
+      "apiKey": "${HYPERSPELL_API_KEY}",
+      "autoContext": true
+    }
+  }
+}
+```
+
+Or set the environment variable:
+
+```bash
+export HYPERSPELL_API_KEY=hs_...
+```
+
+### 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) |
+| `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 |
+| `debug` | boolean | `false` | Enable verbose logging |
+
+## Slash Commands
+
+### `/context <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
+```
+
+### `/remember <text>`
+
+Save something to memory.
+
+```
+/remember Meeting with Alice: discussed Q1 budget, need to follow up on headcount
+```
+
+## AI Tools
+
+The plugin registers tools that the AI can use autonomously:
+
+- **hyperspell_search** - Search through connected sources
+- **hyperspell_remember** - Save information to memory
+
+## Auto-Context
+
+When `autoContext: true` (default), the plugin automatically:
+
+1. Intercepts each user message before the AI responds
+2. Searches Hyperspell for relevant memories
+3. Injects matching context into the AI's prompt
+
+This ensures the AI always has access to relevant information from your connected sources.
+
+## Available Sources
+
+- `collections` - User-created collections
+- `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

@@ -0,0 +1,113 @@
+import Hyperspell from "hyperspell"
+import type { HyperspellConfig, HyperspellSource } from "./config.ts"
+import { log } from "./logger.ts"
+
+export type SearchResult = {
+  resourceId: string
+  title: string | null
+  source: HyperspellSource
+  score: number | null
+  url: string | null
+  createdAt: string | null
+}
+
+export type Integration = {
+  id: string
+  name: string
+  provider: HyperspellSource
+  icon: string
+}
+
+export class HyperspellClient {
+  private client: Hyperspell
+  private config: HyperspellConfig
+
+  constructor(config: HyperspellConfig) {
+    this.config = config
+    this.client = new Hyperspell({
+      apiKey: config.apiKey,
+    })
+    log.info("client initialized")
+  }
+
+  async search(
+    query: string,
+    options?: { limit?: number; sources?: HyperspellSource[] },
+  ): Promise<SearchResult[]> {
+    const limit = options?.limit ?? this.config.maxResults
+    const sources =
+      options?.sources ?? (this.config.sources.length > 0 ? this.config.sources : undefined)
+
+    log.debugRequest("memories.search", { query, limit, sources })
+
+    const response = await this.client.memories.search({
+      query,
+      sources,
+      options: {
+        max_results: limit,
+      },
+    })
+
+    const results: 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", { count: results.length })
+    return results
+  }
+
+  async addMemory(
+    text: string,
+    options?: { title?: string; metadata?: Record<string, string | number | boolean> },
+  ): Promise<{ resourceId: string }> {
+    log.debugRequest("memories.add", {
+      textLength: text.length,
+      title: options?.title,
+    })
+
+    const result = await this.client.memories.add({
+      text,
+      title: options?.title,
+      metadata: {
+        ...options?.metadata,
+        openclaw_source: "command",
+      },
+    })
+
+    log.debugResponse("memories.add", { resourceId: result.resource_id })
+    return { resourceId: result.resource_id }
+  }
+
+  async listIntegrations(): Promise<Integration[]> {
+    log.debugRequest("integrations.list", {})
+
+    const response = await this.client.integrations.list()
+
+    const integrations: Integration[] = response.integrations.map((int) => ({
+      id: int.id,
+      name: int.name,
+      provider: int.provider as HyperspellSource,
+      icon: int.icon,
+    }))
+
+    log.debugResponse("integrations.list", { count: integrations.length })
+    return integrations
+  }
+
+  async getConnectUrl(integrationId: string): Promise<{ url: string; expiresAt: string }> {
+    log.debugRequest("integrations.connect", { integrationId })
+
+    const response = await this.client.integrations.connect(integrationId)
+
+    log.debugResponse("integrations.connect", { url: response.url })
+    return {
+      url: response.url,
+      expiresAt: response.expires_at,
+    }
+  }
+}

package/commands/slash.ts

@@ -0,0 +1,139 @@
+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 {
+  if (text.length <= maxLength) return text
+  return `${text.slice(0, maxLength)}…`
+}
+
+function formatScore(score: number | null): string {
+  if (score === null) return ""
+  return ` (${Math.round(score * 100)}%)`
+}
+
+export function registerCommands(
+  api: OpenClawPluginApi,
+  client: HyperspellClient,
+  _cfg: HyperspellConfig,
+): void {
+  // /context <query> - Search memories and show summaries
+  api.registerCommand({
+    name: "context",
+    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>" }
+      }
+
+      log.debug(`/context command: "${query}"`)
+
+      try {
+        const results = await client.search(query, { limit: 5 })
+
+        if (results.length === 0) {
+          return { text: `No memories found for: "${query}"` }
+        }
+
+        const lines = results.map((r, i) => {
+          const title = r.title ? truncate(r.title, 60) : `[${r.source}]`
+          const score = formatScore(r.score)
+          return `${i + 1}. ${title}${score}`
+        })
+
+        return {
+          text: `Found ${results.length} memories:\n\n${lines.join("\n")}`,
+        }
+      } catch (err) {
+        log.error("/context 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",
+    description: "Save something to memory",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: async (ctx: { args?: string }) => {
+      const text = ctx.args?.trim()
+      if (!text) {
+        return { text: "Usage: /remember <text to remember>" }
+      }
+
+      log.debug(`/remember command: "${truncate(text, 50)}"`)
+
+      try {
+        await client.addMemory(text, {
+          metadata: { source: "openclaw_command" },
+        })
+
+        const preview = truncate(text, 60)
+        return { text: `Remembered: "${preview}"` }
+      } catch (err) {
+        log.error("/remember failed", err)
+        return { text: "Failed to save memory. Check logs for details." }
+      }
+    },
+  })
+}

package/config.ts

@@ -0,0 +1,119 @@
+export type HyperspellSource =
+  | "collections"
+  | "reddit"
+  | "notion"
+  | "slack"
+  | "google_calendar"
+  | "google_mail"
+  | "box"
+  | "google_drive"
+  | "vault"
+  | "web_crawler"
+
+export type HyperspellConfig = {
+  apiKey: string
+  userId?: string
+  autoContext: boolean
+  sources: HyperspellSource[]
+  maxResults: number
+  debug: boolean
+}
+
+const ALLOWED_KEYS = [
+  "apiKey",
+  "userId",
+  "autoContext",
+  "sources",
+  "maxResults",
+  "debug",
+]
+
+const VALID_SOURCES: HyperspellSource[] = [
+  "collections",
+  "reddit",
+  "notion",
+  "slack",
+  "google_calendar",
+  "google_mail",
+  "box",
+  "google_drive",
+  "vault",
+  "web_crawler",
+]
+
+function assertAllowedKeys(
+  value: Record<string, unknown>,
+  allowed: string[],
+  label: string,
+): void {
+  const unknown = Object.keys(value).filter((k) => !allowed.includes(k))
+  if (unknown.length > 0) {
+    throw new Error(`${label} has unknown keys: ${unknown.join(", ")}`)
+  }
+}
+
+function resolveEnvVars(value: string): string {
+  return value.replace(/\$\{([^}]+)\}/g, (_, envVar: string) => {
+    const envValue = process.env[envVar]
+    if (!envValue) {
+      throw new Error(`Environment variable ${envVar} is not set`)
+    }
+    return envValue
+  })
+}
+
+function parseSources(raw: string | undefined): HyperspellSource[] {
+  if (!raw || raw.trim() === "") {
+    return []
+  }
+
+  const sources = raw
+    .split(",")
+    .map((s) => 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
+}
+
+export function parseConfig(raw: unknown): HyperspellConfig {
+  const cfg =
+    raw && typeof raw === "object" && !Array.isArray(raw)
+      ? (raw as Record<string, unknown>)
+      : {}
+
+  if (Object.keys(cfg).length > 0) {
+    assertAllowedKeys(cfg, ALLOWED_KEYS, "hyperspell config")
+  }
+
+  const apiKey =
+    typeof cfg.apiKey === "string" && cfg.apiKey.length > 0
+      ? resolveEnvVars(cfg.apiKey)
+      : process.env.HYPERSPELL_API_KEY
+
+  if (!apiKey) {
+    throw new Error(
+      "hyperspell: apiKey is required (set in plugin config or HYPERSPELL_API_KEY env var)",
+    )
+  }
+
+  return {
+    apiKey,
+    userId: cfg.userId as string | undefined,
+    autoContext: (cfg.autoContext as boolean) ?? true,
+    sources: parseSources(cfg.sources as string | undefined),
+    maxResults: (cfg.maxResults as number) ?? 10,
+    debug: (cfg.debug as boolean) ?? false,
+  }
+}
+
+export const hyperspellConfigSchema = {
+  parse: parseConfig,
+}

package/hooks/auto-context.ts

@@ -0,0 +1,76 @@
+import type { HyperspellClient, SearchResult } from "../client.ts"
+import type { HyperspellConfig } from "../config.ts"
+import { log } from "../logger.ts"
+
+function formatRelativeTime(isoTimestamp: string): string {
+  try {
+    const dt = new Date(isoTimestamp)
+    const now = new Date()
+    const seconds = (now.getTime() - dt.getTime()) / 1000
+    const minutes = seconds / 60
+    const hours = seconds / 3600
+    const days = seconds / 86400
+
+    if (minutes < 30) return "just now"
+    if (minutes < 60) return `${Math.floor(minutes)}mins ago`
+    if (hours < 24) return `${Math.floor(hours)} hrs ago`
+    if (days < 7) return `${Math.floor(days)}d ago`
+
+    const month = dt.toLocaleString("en", { month: "short" })
+    if (dt.getFullYear() === now.getFullYear()) {
+      return `${dt.getDate()} ${month}`
+    }
+    return `${dt.getDate()} ${month}, ${dt.getFullYear()}`
+  } catch {
+    return ""
+  }
+}
+
+function formatContext(results: SearchResult[], maxResults: number): string | null {
+  const limited = results.slice(0, maxResults)
+
+  if (limited.length === 0) return null
+
+  const lines = limited.map((r) => {
+    const title = r.title ?? `[${r.source}]`
+    const timeStr = r.createdAt ? formatRelativeTime(r.createdAt) : ""
+    const pct = r.score != null ? `[${Math.round(r.score * 100)}%]` : ""
+    const prefix = timeStr ? `[${timeStr}]` : ""
+    return `- ${prefix} ${title} ${pct}`.trim()
+  })
+
+  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## Relevant Memories (with relevance %)\n${lines.join("\n")}\n\n${disclaimer}\n</hyperspell-context>`
+}
+
+export function buildAutoContextHandler(
+  client: HyperspellClient,
+  cfg: HyperspellConfig,
+) {
+  return async (event: Record<string, unknown>) => {
+    const prompt = event.prompt as string | undefined
+    if (!prompt || prompt.length < 5) return
+
+    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)
+
+      if (!context) {
+        log.debug("auto-context: no relevant memories found")
+        return
+      }
+
+      log.debug(`auto-context: injecting ${results.length} memories`)
+      return { prependContext: context }
+    } catch (err) {
+      log.error("auto-context failed", err)
+      return
+    }
+  }
+}

package/index.ts

@@ -0,0 +1,48 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import { HyperspellClient } from "./client.ts"
+import { registerCommands } from "./commands/slash.ts"
+import { parseConfig, hyperspellConfigSchema } from "./config.ts"
+import { buildAutoContextHandler } from "./hooks/auto-context.ts"
+import { initLogger } from "./logger.ts"
+import { registerRememberTool } from "./tools/remember.ts"
+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",
+  kind: "memory" as const,
+  configSchema: hyperspellConfigSchema,
+
+  register(api: OpenClawPluginApi) {
+    const cfg = parseConfig(api.pluginConfig)
+
+    initLogger(api.logger, cfg.debug)
+
+    const client = new HyperspellClient(cfg)
+
+    // Register AI tools
+    registerSearchTool(api, client, cfg)
+    registerRememberTool(api, client, cfg)
+
+    // Register auto-context hook
+    if (cfg.autoContext) {
+      const autoContextHandler = buildAutoContextHandler(client, cfg)
+      api.on("before_agent_start", autoContextHandler)
+    }
+
+    // Register slash commands
+    registerCommands(api, client, cfg)
+
+    // Register service for lifecycle management
+    api.registerService({
+      id: "openclaw-hyperspell",
+      start: () => {
+        api.logger.info("hyperspell: connected")
+      },
+      stop: () => {
+        api.logger.info("hyperspell: stopped")
+      },
+    })
+  },
+}

package/lib/browser.ts

@@ -0,0 +1,27 @@
+import { exec } from "node:child_process"
+import { platform } from "node:os"
+
+export function openInBrowser(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()
+      }
+    })
+  })
+}

package/logger.ts

@@ -0,0 +1,41 @@
+type 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
+}
+
+let _logger: Logger = console
+let _debug = false
+
+export function initLogger(logger: Logger, debug: boolean): void {
+  _logger = logger
+  _debug = debug
+}
+
+export const log = {
+  info: (message: string, ...args: unknown[]) => {
+    _logger.info(`hyperspell: ${message}`, ...args)
+  },
+  warn: (message: string, ...args: unknown[]) => {
+    _logger.warn(`hyperspell: ${message}`, ...args)
+  },
+  error: (message: string, ...args: unknown[]) => {
+    _logger.error(`hyperspell: ${message}`, ...args)
+  },
+  debug: (message: string, ...args: unknown[]) => {
+    if (_debug) {
+      _logger.debug(`hyperspell: ${message}`, ...args)
+    }
+  },
+  debugRequest: (method: string, params: unknown) => {
+    if (_debug) {
+      _logger.debug(`hyperspell: [${method}] request`, params)
+    }
+  },
+  debugResponse: (method: string, result: unknown) => {
+    if (_debug) {
+      _logger.debug(`hyperspell: [${method}] response`, result)
+    }
+  },
+}

package/openclaw.plugin.json

@@ -0,0 +1,52 @@
+{
+  "id": "openclaw-hyperspell",
+  "kind": "memory",
+  "uiHints": {
+    "apiKey": {
+      "label": "Hyperspell API Key",
+      "sensitive": true,
+      "placeholder": "hs_...",
+      "help": "Your API key from app.hyperspell.com (or use ${HYPERSPELL_API_KEY})"
+    },
+    "userId": {
+      "label": "User ID",
+      "placeholder": "user_123",
+      "help": "Optional user ID to scope searches. Required for non-JWT API keys.",
+      "advanced": true
+    },
+    "autoContext": {
+      "label": "Auto-Context",
+      "help": "Inject relevant memories before every AI turn"
+    },
+    "sources": {
+      "label": "Sources",
+      "placeholder": "notion,slack,google_drive",
+      "help": "Comma-separated list of sources to search. Leave empty for all sources.",
+      "advanced": true
+    },
+    "maxResults": {
+      "label": "Max Results",
+      "placeholder": "10",
+      "help": "Maximum memories injected into context per turn",
+      "advanced": true
+    },
+    "debug": {
+      "label": "Debug Logging",
+      "help": "Enable verbose debug logs for API calls and responses",
+      "advanced": true
+    }
+  },
+  "configSchema": {
+    "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" }
+    },
+    "required": []
+  }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@hyperspell/openclaw-hyperspell",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "OpenClaw Hyperspell memory plugin",
+  "license": "MIT",
+  "main": "./index.ts",
+  "files": [
+    "*.ts",
+    "commands/",
+    "hooks/",
+    "tools/",
+    "lib/",
+    "types/",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hyperspell/openclaw-hyperspell.git"
+  },
+  "keywords": [
+    "openclaw",
+    "hyperspell",
+    "memory",
+    "rag",
+    "ai",
+    "plugin"
+  ],
+  "dependencies": {
+    "hyperspell": "^0.30.0",
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.29"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit",
+    "lint": "bunx @biomejs/biome ci .",
+    "lint:fix": "bunx @biomejs/biome check --write ."
+  },
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/tools/remember.ts

@@ -0,0 +1,44 @@
+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 { log } from "../logger.ts"
+
+export function registerRememberTool(
+  api: OpenClawPluginApi,
+  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" }),
+        ),
+      }),
+      async execute(
+        _toolCallId: string,
+        params: { text: string; title?: string },
+      ) {
+        log.debug(`remember tool: "${params.text.slice(0, 50)}..."`)
+
+        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
+
+        return {
+          content: [{ type: "text" as const, text: `Stored: "${preview}"` }],
+        }
+      },
+    },
+    { name: "hyperspell_remember" },
+  )
+}

package/tools/search.ts

@@ -0,0 +1,72 @@
+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 { log } from "../logger.ts"
+
+export function registerSearchTool(
+  api: OpenClawPluginApi,
+  client: HyperspellClient,
+  _cfg: HyperspellConfig,
+): void {
+  api.registerTool(
+    {
+      name: "hyperspell_search",
+      label: "Memory Search",
+      description:
+        "Search through the user's connected sources (Notion, Slack, Gmail, Google Drive, etc.) for relevant information.",
+      parameters: Type.Object({
+        query: Type.String({ description: "Search query" }),
+        limit: Type.Optional(
+          Type.Number({ description: "Max results (default: 5)" }),
+        ),
+      }),
+      async execute(
+        _toolCallId: string,
+        params: { query: string; limit?: number },
+      ) {
+        const limit = params.limit ?? 5
+        log.debug(`search tool: query="${params.query}" limit=${limit}`)
+
+        const results = await client.search(params.query, { limit })
+
+        if (results.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")
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Found ${results.length} memories:\n\n${text}`,
+            },
+          ],
+          details: {
+            count: results.length,
+            memories: results.map((r) => ({
+              resourceId: r.resourceId,
+              title: r.title,
+              source: r.source,
+              score: r.score,
+            })),
+          },
+        }
+      },
+    },
+    { name: "hyperspell_search" },
+  )
+}

package/types/openclaw.d.ts

@@ -0,0 +1,42 @@
+declare module "openclaw/plugin-sdk" {
+  export interface OpenClawPluginApi {
+    pluginConfig: unknown
+    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
+    }
+    registerCommand(options: {
+      name: string
+      description: string
+      acceptsArgs: boolean
+      requireAuth: boolean
+      handler: (ctx: { args?: string; senderId?: string; channel?: string }) => Promise<{ text: string }>
+    }): void
+    registerTool<T = unknown>(
+      options: {
+        name: string
+        label: string
+        description: string
+        parameters: unknown
+        execute: (
+          toolCallId: string,
+          params: T,
+        ) => Promise<{
+          content: Array<{ type: "text"; text: string }>
+          details?: Record<string, unknown>
+        }>
+      },
+      meta: { name: string },
+    ): void
+    on(event: string, handler: (event: Record<string, unknown>, ctx?: Record<string, unknown>) => Promise<{ prependContext?: string } | void> | void): void
+    registerService(options: {
+      id: string
+      start: () => void
+      stop: () => void
+    }): void
+  }
+
+  export function stringEnum<T extends string>(values: readonly T[]): unknown
+}