@hyperspell/openclaw-hyperspell 0.2.0 → 0.3.1

package/client.ts

@@ -138,16 +138,25 @@ export class HyperspellClient {
 
   async addMemory(
     text: string,
-    options?: { title?: string; metadata?: Record<string, string | number | boolean> },
+    options?: {
+      title?: string
+      resourceId?: string
+      collection?: string
+      metadata?: Record<string, string | number | boolean>
+    },
   ): Promise<{ resourceId: string }> {
     log.debugRequest("memories.add", {
       textLength: text.length,
       title: options?.title,
+      resourceId: options?.resourceId,
+      collection: options?.collection,
     })
 
     const result = await this.client.memories.add({
       text,
       title: options?.title,
+      resource_id: options?.resourceId,
+      collection: options?.collection,
       metadata: {
         ...options?.metadata,
         openclaw_source: "command",

package/commands/setup.ts

@@ -5,6 +5,9 @@ import { homedir, platform, userInfo } from "node:os"
 import * as p from "@clack/prompts"
 import type { Command } from "commander"
 import Hyperspell from "hyperspell"
+import { syncAllMemoryFiles, getMemoryFiles } from "../sync/markdown.ts"
+import { HyperspellClient } from "../client.ts"
+import { getWorkspaceDir } from "../config.ts"
 
 /**
  * Resolve OpenClaw state directory, matching OpenClaw's logic.
@@ -241,6 +244,26 @@ async function runSetup(): Promise<void> {
   const sources = await fetchConnectionSources(client, userId)
   s1.stop(`Found ${sources.length} sources: ${sources.join(", ")}`)
 
+  // Step 5: Ask about memory sync
+  p.note(
+    "OpenClaw can automatically sync markdown files in your workspace's\n" +
+      "memory/ directory with Hyperspell. This allows you to:\n\n" +
+      "• Store notes and context that persist across sessions\n" +
+      "• Have the AI reference your local documentation\n" +
+      "• Keep local files in sync with Hyperspell's search",
+    "Memory Sync",
+  )
+
+  const syncMemories = await p.confirm({
+    message: "Enable automatic memory sync for markdown files?",
+    initialValue: true,
+  })
+
+  if (p.isCancel(syncMemories)) {
+    p.cancel("Setup cancelled")
+    return
+  }
+
   // Step 5: Save configuration
   const s2 = p.spinner()
   s2.start("Saving configuration")
@@ -278,6 +301,7 @@ async function runSetup(): Promise<void> {
         userId,
         sources: sources.join(","),
         autoContext: true,
+        syncMemories,
       },
     }
 
@@ -322,6 +346,7 @@ async function runSetup(): Promise<void> {
                 userId,
                 sources: sources.join(","),
                 autoContext: true,
+                syncMemories,
               },
             },
           },
@@ -338,12 +363,52 @@ async function runSetup(): Promise<void> {
     )
   }
 
+  // Step 7: Sync existing memories if enabled
+  if (syncMemories) {
+    const workspaceDir = getWorkspaceDir()
+    const memoryFiles = getMemoryFiles(workspaceDir)
+
+    if (memoryFiles.length > 0) {
+      const s3 = p.spinner()
+      s3.start(`Syncing ${memoryFiles.length} memory file(s)`)
+
+      const hyperspellClient = new HyperspellClient({
+        apiKey,
+        userId,
+        autoContext: true,
+        syncMemories: true,
+        sources: [],
+        maxResults: 10,
+        debug: false,
+      })
+
+      const result = await syncAllMemoryFiles(hyperspellClient, workspaceDir)
+
+      if (result.failed > 0) {
+        s3.stop(`Synced ${result.synced} files, ${result.failed} failed`)
+        for (const error of result.errors) {
+          p.log.error(`  ${error}`)
+        }
+      } else {
+        s3.stop(`Synced ${result.synced} memory files`)
+      }
+    } else {
+      p.log.info("No memory files found in memory/ directory")
+    }
+  }
+
+  const syncNote = syncMemories
+    ? "\n\nMemory sync is enabled — markdown files in memory/ will be\n" +
+      "automatically synced to Hyperspell when they change."
+    : ""
+
   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.",
+      "automatically injected before each AI response." +
+      syncNote,
     "How to use Hyperspell",
   )
 
@@ -417,6 +482,7 @@ async function runStatus(pluginConfig: unknown): Promise<void> {
   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(`Memory Sync: ${config.syncMemories ? "Enabled" : "Disabled"}`)
   p.log.info(`Sources Filter: ${config.sources || "(all sources)"}`)
   p.log.info(`Max Results: ${config.maxResults || 10}`)
 

package/commands/slash.ts

@@ -1,7 +1,9 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import type { HyperspellClient } from "../client.ts"
 import type { HyperspellConfig } from "../config.ts"
+import { getWorkspaceDir } from "../config.ts"
 import { log } from "../logger.ts"
+import { syncAllMemoryFiles } from "../sync/markdown.ts"
 
 function truncate(text: string, maxLength: number): string {
   if (text.length <= maxLength) return text
@@ -82,4 +84,36 @@ export function registerCommands(
       }
     },
   })
+
+  // /sync - Manually sync memory files
+  api.registerCommand({
+    name: "sync",
+    description: "Sync memory/*.md files with Hyperspell",
+    acceptsArgs: false,
+    requireAuth: true,
+    handler: async () => {
+      log.debug("/sync command")
+
+      try {
+        const workspaceDir = getWorkspaceDir()
+        const result = await syncAllMemoryFiles(client, workspaceDir)
+
+        if (result.synced === 0 && result.failed === 0) {
+          return { text: "No memory files found in memory/ directory." }
+        }
+
+        if (result.failed > 0) {
+          const errors = result.errors.map((e) => `  • ${e}`).join("\n")
+          return {
+            text: `Synced ${result.synced} files, ${result.failed} failed:\n${errors}`,
+          }
+        }
+
+        return { text: `Synced ${result.synced} memory file(s) to Hyperspell.` }
+      } catch (err) {
+        log.error("/sync failed", err)
+        return { text: "Failed to sync memory files. Check logs for details." }
+      }
+    },
+  })
 }

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",
@@ -130,6 +132,7 @@ export function parseConfig(raw: unknown): HyperspellConfig {
     apiKey,
     userId: cfg.userId as string | undefined,
     autoContext: (cfg.autoContext as boolean) ?? true,
+    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,
@@ -139,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

@@ -2,8 +2,9 @@ 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 { 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"
@@ -49,6 +50,15 @@ export default {
           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
     }
 
@@ -68,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

@@ -35,6 +35,11 @@
       "label": "Debug Logging",
       "help": "Enable verbose debug logs for API calls and responses",
       "advanced": true
+    },
+    "syncMemories": {
+      "label": "Sync Memory Files",
+      "help": "Automatically sync markdown files in workspace/memory/ to Hyperspell",
+      "advanced": true
     }
   },
   "configSchema": {
@@ -60,6 +65,9 @@
       },
       "debug": {
         "type": "boolean"
+      },
+      "syncMemories": {
+        "type": "boolean"
       }
     },
     "required": []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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",
@@ -48,4 +48,4 @@
   "devDependencies": {
     "typescript": "^5.9.3"
   }
-}
+}

package/types/openclaw.d.ts

@@ -17,6 +17,7 @@ declare module "openclaw/plugin-sdk" {
 
   export interface OpenClawPluginApi {
     pluginConfig: unknown
+    workspaceDir?: string
     logger: {
       info: (message: string, ...args: unknown[]) => void
       warn: (message: string, ...args: unknown[]) => void