@hyperspell/openclaw-hyperspell 0.1.1 → 0.3.0

package/config.ts

@@ -14,6 +14,7 @@ export type HyperspellConfig = {
   apiKey: string
   userId?: string
   autoContext: boolean
+  syncMemories: boolean
   sources: HyperspellSource[]
   maxResults: number
   debug: boolean
@@ -23,6 +24,7 @@ const ALLOWED_KEYS = [
   "apiKey",
   "userId",
   "autoContext",
+  "syncMemories",
   "sources",
   "maxResults",
   "debug",
@@ -62,8 +64,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 +132,8 @@ 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),
+    syncMemories: (cfg.syncMemories as boolean) ?? false,
+    sources: parseSources(cfg.sources as string | string[] | undefined),
     maxResults: (cfg.maxResults as number) ?? 10,
     debug: (cfg.debug as boolean) ?? false,
   }
@@ -117,3 +142,50 @@ export function parseConfig(raw: unknown): HyperspellConfig {
 export const hyperspellConfigSchema = {
   parse: parseConfig,
 }
+
+/**
+ * Get the workspace directory from OpenClaw config
+ */
+export function getWorkspaceDir(): string {
+  const { homedir } = require("node:os")
+  const fs = require("node:fs")
+  const path = require("node:path")
+
+  // Resolve config path
+  const override = process.env.OPENCLAW_CONFIG_PATH?.trim() || process.env.CLAWDBOT_CONFIG_PATH?.trim()
+  let configPath: string
+  if (override) {
+    configPath = override.startsWith("~")
+      ? override.replace(/^~(?=$|[\\/])/, homedir())
+      : path.resolve(override)
+  } else {
+    const stateDir = process.env.OPENCLAW_STATE_DIR?.trim() || process.env.CLAWDBOT_STATE_DIR?.trim()
+    const resolvedStateDir = stateDir
+      ? (stateDir.startsWith("~") ? stateDir.replace(/^~(?=$|[\\/])/, homedir()) : path.resolve(stateDir))
+      : path.join(homedir(), ".openclaw")
+    configPath = path.join(resolvedStateDir, "openclaw.json")
+  }
+
+  // Read workspace from config
+  if (fs.existsSync(configPath)) {
+    try {
+      const content = fs.readFileSync(configPath, "utf-8")
+      const config = JSON.parse(content)
+      const workspace = config?.agents?.defaults?.workspace
+      if (workspace) {
+        return workspace.startsWith("~")
+          ? workspace.replace(/^~(?=$|[\\/])/, homedir())
+          : workspace
+      }
+    } catch (_e) {
+      // Fall back to default
+    }
+  }
+
+  // Default workspace
+  const stateDir = process.env.OPENCLAW_STATE_DIR?.trim() || process.env.CLAWDBOT_STATE_DIR?.trim()
+  const resolvedStateDir = stateDir
+    ? (stateDir.startsWith("~") ? stateDir.replace(/^~(?=$|[\\/])/, homedir()) : path.resolve(stateDir))
+    : path.join(homedir(), ".openclaw")
+  return path.join(resolvedStateDir, "workspace")
+}

package/hooks/memory-sync.ts

@@ -0,0 +1,63 @@
+import * as path from "node:path"
+import type { HyperspellClient } from "../client.ts"
+import type { HyperspellConfig } from "../config.ts"
+import { getWorkspaceDir } from "../config.ts"
+import { log } from "../logger.ts"
+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) {
+  const workspaceDir = getWorkspaceDir()
+  const memoryDir = path.join(workspaceDir, "memory")
+
+  return async (event: Record<string, unknown>) => {
+    const filePath = event.file_path as string | undefined
+    if (!filePath) return
+
+    // Only process markdown files in the workspace's memory directory
+    if (!filePath.startsWith(memoryDir) || !filePath.endsWith(".md")) {
+      return
+    }
+
+    const fileName = path.basename(filePath)
+    log.info(`Memory file changed: ${fileName}`)
+
+    try {
+      const result = await syncMarkdownFile(client, filePath)
+      if (result.success) {
+        log.info(`Synced ${fileName} -> ${result.resourceId}`)
+      } else {
+        log.error(`Failed to sync ${fileName}: ${result.error}`)
+      }
+    } catch (err) {
+      log.error(`Error syncing ${fileName}`, err)
+    }
+  }
+}
+
+/**
+ * Sync all existing memory files on startup
+ */
+export async function syncMemoriesOnStartup(
+  client: HyperspellClient,
+  workspaceDir: string,
+): Promise<void> {
+  log.info("Syncing existing memory files...")
+
+  const result = await syncAllMemoryFiles(client, workspaceDir)
+
+  if (result.synced > 0) {
+    log.info(`Synced ${result.synced} memory files`)
+  }
+  if (result.failed > 0) {
+    log.error(`Failed to sync ${result.failed} files:`)
+    for (const error of result.errors) {
+      log.error(`  - ${error}`)
+    }
+  }
+  if (result.synced === 0 && result.failed === 0) {
+    log.info("No memory files found in memory/ directory")
+  }
+}

package/index.ts

@@ -1,8 +1,10 @@
 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 { registerCliCommands } from "./commands/setup.ts"
+import { parseConfig, hyperspellConfigSchema, getWorkspaceDir } from "./config.ts"
 import { buildAutoContextHandler } from "./hooks/auto-context.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"
@@ -10,11 +12,56 @@ 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." }
+        },
+      })
+      api.registerCommand({
+        name: "sync",
+        description: "Sync memory/*.md files with Hyperspell",
+        acceptsArgs: false,
+        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)
@@ -31,14 +78,26 @@ export default {
       api.on("before_agent_start", autoContextHandler)
     }
 
+    // Register memory sync hook
+    if (cfg.syncMemories) {
+      const fileSyncHandler = buildFileSyncHandler(client, cfg)
+      api.on("file_changed", fileSyncHandler)
+    }
+
     // Register slash commands
     registerCommands(api, client, cfg)
 
     // Register service for lifecycle management
     api.registerService({
       id: "openclaw-hyperspell",
-      start: () => {
+      start: async () => {
         api.logger.info("hyperspell: connected")
+
+        // Sync memories on startup if enabled
+        if (cfg.syncMemories) {
+          const workspaceDir = getWorkspaceDir()
+          await syncMemoriesOnStartup(client, workspaceDir)
+        }
       },
       stop: () => {
         api.logger.info("hyperspell: stopped")

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.1",
+  "version": "0.3.0",
   "type": "module",
   "description": "OpenClaw Hyperspell memory plugin",
   "license": "MIT",
@@ -17,7 +17,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/hyperspell/openclaw-hyperspell.git"
+    "url": "git+https://github.com/hyperspell/openclaw-hyperspell.git"
   },
   "keywords": [
     "openclaw",
@@ -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,7 +41,9 @@
     "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,6 +1,23 @@
 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
+    workspaceDir?: string
     logger: {
       info: (message: string, ...args: unknown[]) => void
       warn: (message: string, ...args: unknown[]) => void
@@ -14,6 +31,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