@hyperspell/openclaw-hyperspell 0.3.1 → 0.4.2

package/README.md

@@ -23,10 +23,12 @@ The setup wizard will guide you through:
 2. Configuring your API key
 3. Setting up your User ID for multi-tenant memory
 4. Connecting your apps (Notion, Slack, Google Drive, etc.)
+5. Enabling memory sync for local markdown files
+6. Syncing existing memory files to Hyperspell
 
 ## Manual Configuration
 
-Alternatively, add to your `openclaw.json`:
+Add to your `openclaw.json`:
 
 ```json
 {
@@ -37,26 +39,27 @@ Alternatively, add to your `openclaw.json`:
         "config": {
           "apiKey": "${HYPERSPELL_API_KEY}",
           "userId": "your-email",
-          "autoContext": true
+          "autoContext": true,
+          "syncMemories": true,
+          "sources": "vault,notion,slack"
         }
       }
     }
   }
 }
-
 ```
 
-Or set the environment variable:
+Set the environment variable in `~/.openclaw/.env`:
 
 ```bash
-export HYPERSPELL_API_KEY=hs_...
+HYPERSPELL_API_KEY=hs_...
 ```
 
 ## CLI Commands
 
 ### `openclaw openclaw-hyperspell setup`
 
-Interactive setup wizard that walks you through configuration.
+Interactive setup wizard that walks you through configuration, connecting apps, and syncing memory files.
 
 ### `openclaw openclaw-hyperspell status`
 
@@ -64,16 +67,17 @@ 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.)
+Open the Hyperspell connect page to link your accounts (Notion, Slack, Google Drive, etc.). After connecting, your sources are automatically updated in the config.
 
-### Options
+## Configuration Options
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `apiKey` | string | `${HYPERSPELL_API_KEY}` | Hyperspell API key |
-| `userId` | string | - | User ID (can be your email) |
+| `userId` | string | - | User ID for multi-tenant memory (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`) |
+| `syncMemories` | boolean | `false` | Sync markdown files in `workspace/memory/` to Hyperspell |
+| `sources` | string | - | Comma-separated sources to search (e.g., `vault,notion,slack`) |
 | `maxResults` | number | `10` | Maximum memories per context injection |
 | `debug` | boolean | `false` | Enable verbose logging |
 
@@ -95,6 +99,37 @@ Save something to memory.
 /remember Meeting with Alice: discussed Q1 budget, need to follow up on headcount
 ```
 
+### `/sync`
+
+Manually sync all markdown files in `workspace/memory/` to Hyperspell.
+
+```
+/sync
+```
+
+## Memory Sync
+
+When `syncMemories: true`, the plugin syncs markdown files from your agent's workspace memory directory (e.g., `~/.openclaw/workspace/memory/`) to Hyperspell. This includes all `.md` files in subdirectories.
+
+**How it works:**
+
+- Each markdown file is uploaded to Hyperspell as a memory in the `openclaw` collection
+- The returned `resource_id` is stored in the file's YAML frontmatter as `hyperspell_id`
+- On subsequent syncs, files with an existing `hyperspell_id` are updated rather than duplicated
+- Files are synced automatically on startup and when they change
+
+**Example frontmatter after sync:**
+
+```markdown
+---
+title: Meeting Notes
+hyperspell_id: abc123-def456
+---
+
+# Meeting Notes
+...
+```
+
 ## AI Tools
 
 The plugin registers tools that the AI can use autonomously:
@@ -114,7 +149,7 @@ This ensures the AI always has access to relevant information from your connecte
 
 ## Available Sources
 
-- `vault` - User-created memories
+- `vault` - User-created or synced memories
 - `notion` - Notion pages and databases
 - `slack` - Slack messages
 - `google_calendar` - Google Calendar events

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.3.1",
+  "version": "0.4.2",
   "type": "module",
   "description": "OpenClaw Hyperspell memory plugin",
   "license": "MIT",
@@ -10,6 +10,7 @@
     "commands/",
     "hooks/",
     "tools/",
+    "sync/",
     "lib/",
     "types/",
     "openclaw.plugin.json",

package/sync/markdown.ts

@@ -0,0 +1,183 @@
+import * as fs from "node:fs"
+import * as path from "node:path"
+import type { HyperspellClient } from "../client.ts"
+import { log } from "../logger.ts"
+
+const FRONTMATTER_REGEX = /^---\n([\s\S]*?)\n---\n?/
+
+interface MarkdownFile {
+  filePath: string
+  title: string
+  content: string
+  hyperspellId: string | null
+}
+
+/**
+ * Parse frontmatter from markdown content
+ */
+function parseFrontmatter(content: string): { frontmatter: Record<string, string>; body: string } {
+  const match = content.match(FRONTMATTER_REGEX)
+  if (!match) {
+    return { frontmatter: {}, body: content }
+  }
+
+  const frontmatterText = match[1]
+  const body = content.slice(match[0].length)
+  const frontmatter: Record<string, string> = {}
+
+  for (const line of frontmatterText.split("\n")) {
+    const colonIndex = line.indexOf(":")
+    if (colonIndex > 0) {
+      const key = line.slice(0, colonIndex).trim()
+      const value = line.slice(colonIndex + 1).trim()
+      frontmatter[key] = value
+    }
+  }
+
+  return { frontmatter, body }
+}
+
+/**
+ * Serialize frontmatter back to string
+ */
+function serializeFrontmatter(frontmatter: Record<string, string>): string {
+  const lines = Object.entries(frontmatter).map(([key, value]) => `${key}: ${value}`)
+  return `---\n${lines.join("\n")}\n---\n`
+}
+
+/**
+ * Read a markdown file and parse its content
+ */
+function readMarkdownFile(filePath: string): MarkdownFile | null {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8")
+    const { frontmatter, body } = parseFrontmatter(content)
+    const title = frontmatter.title || path.basename(filePath, ".md")
+
+    return {
+      filePath,
+      title,
+      content: body.trim(),
+      hyperspellId: frontmatter.hyperspell_id || null,
+    }
+  } catch (err) {
+    log.error(`Failed to read markdown file: ${filePath}`, err)
+    return null
+  }
+}
+
+/**
+ * Update the hyperspell_id in the frontmatter of a markdown file
+ */
+function updateFrontmatterId(filePath: string, hyperspellId: string): void {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8")
+    const { frontmatter, body } = parseFrontmatter(content)
+
+    frontmatter.hyperspell_id = hyperspellId
+
+    const newContent = serializeFrontmatter(frontmatter) + body
+    fs.writeFileSync(filePath, newContent)
+
+    log.debug(`Updated frontmatter in ${filePath} with hyperspell_id: ${hyperspellId}`)
+  } catch (err) {
+    log.error(`Failed to update frontmatter in ${filePath}`, err)
+  }
+}
+
+/**
+ * Get all markdown files from the memory directory, including subdirectories
+ */
+export function getMemoryFiles(workspaceDir: string): string[] {
+  const memoryDir = path.join(workspaceDir, "memory")
+
+  if (!fs.existsSync(memoryDir)) {
+    return []
+  }
+
+  const results: string[] = []
+
+  function walk(dir: string): void {
+    try {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const fullPath = path.join(dir, entry.name)
+        if (entry.isDirectory()) {
+          walk(fullPath)
+        } else if (entry.name.endsWith(".md")) {
+          results.push(fullPath)
+        }
+      }
+    } catch (err) {
+      log.error(`Failed to read directory: ${dir}`, err)
+    }
+  }
+
+  walk(memoryDir)
+  return results
+}
+
+/**
+ * Sync a single markdown file to Hyperspell
+ */
+export async function syncMarkdownFile(
+  client: HyperspellClient,
+  filePath: string,
+): Promise<{ success: boolean; resourceId?: string; error?: string }> {
+  const file = readMarkdownFile(filePath)
+  if (!file) {
+    return { success: false, error: "Failed to read file" }
+  }
+
+  if (!file.content) {
+    return { success: false, error: "File has no content" }
+  }
+
+  try {
+    const result = await client.addMemory(file.content, {
+      title: file.title,
+      resourceId: file.hyperspellId || undefined,
+      collection: "openclaw",
+      metadata: {
+        openclaw_source: "memory_sync",
+        file_path: filePath,
+      },
+    })
+
+    // Update frontmatter with new resource ID if it changed or was newly created
+    if (result.resourceId !== file.hyperspellId) {
+      updateFrontmatterId(filePath, result.resourceId)
+    }
+
+    return { success: true, resourceId: result.resourceId }
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err)
+    log.error(`Failed to sync ${filePath}`, err)
+    return { success: false, error: errorMsg }
+  }
+}
+
+/**
+ * Sync all markdown files in the memory directory
+ */
+export async function syncAllMemoryFiles(
+  client: HyperspellClient,
+  workspaceDir: string,
+): Promise<{ synced: number; failed: number; errors: string[] }> {
+  const files = getMemoryFiles(workspaceDir)
+  let synced = 0
+  let failed = 0
+  const errors: string[] = []
+
+  for (const filePath of files) {
+    const result = await syncMarkdownFile(client, filePath)
+    if (result.success) {
+      synced++
+      log.info(`Synced: ${path.basename(filePath)} -> ${result.resourceId}`)
+    } else {
+      failed++
+      errors.push(`${path.basename(filePath)}: ${result.error}`)
+    }
+  }
+
+  return { synced, failed, errors }
+}