@dn-inc/openclaw-seahorse 0.2.1 → 0.2.2

package/README.md

@@ -3,17 +3,23 @@
 Drop-in replacement for OpenClaw's built-in memory search, powered by [Seahorse](https://seahorse.dnotitia.ai).
 
 - Uploads local memory files (`MEMORY.md`, `memory/**/*.md`) to Seahorse Storage
-- Optionally syncs the entire workspace for full semantic search over all files
+- Syncs the entire workspace for full semantic search (`syncWorkspace: true`)
 - Routes `memory_search` to Seahorse's vector search API
 - Keeps `memory_get` reading from local files (same as native)
 
+## Why Seahorse?
+
+OpenClaw's built-in memory only indexes markdown notes the agent explicitly writes (`MEMORY.md` and `memory/**/*.md`). But agents produce far more than markdown — JSON data, YAML configs, PDF reports, images, spreadsheets, and other artifacts accumulate in the workspace over time, invisible to memory search.
+
+With `syncWorkspace: true`, Seahorse indexes every supported file in the workspace automatically. The agent can semantically search across all of its own output — not just what it remembered to write down. Documents, data files, images, and markup (37 supported extensions) all become searchable through the same `memory_search` tool, with no API or workflow changes.
+
 ## Requirements
 
 - Node.js 20+
 - OpenClaw >= 2026.1.26
 - Seahorse account (Storage + Table tenants)
 
-## Quick Start (Zero Config)
+## Quick Start
 
 1. Install the plugin:
 
@@ -35,9 +41,76 @@ openclaw plugins install @dn-inc/openclaw-seahorse
 }
 ```
 
-If you prefer not to store the key in config, you can set the `SEAHORSE_API_KEY` environment variable instead. The `apiKey` field also supports `${ENV_VAR}` syntax (e.g., `"${SEAHORSE_API_KEY}"`).
+The `apiKey` field supports `${ENV_VAR}` syntax (e.g., `"${SEAHORSE_API_KEY}"`), or you can omit it entirely and set the `SEAHORSE_API_KEY` environment variable.
+
+That's it. The plugin auto-syncs your files on startup and watches for changes in real time.
+
+## File Sync
+
+The plugin runs a background service (`seahorse-sync`) that keeps Seahorse Storage in sync:
+
+- **Initial sync**: scans files on startup, uploads only changed files
+- **Live watch**: detects file create/modify/delete via `fs.watch` (1.5s debounce)
+- **Dedup**: mtime-based state tracking prevents redundant uploads
+- **Delete sync**: local file deletion triggers Seahorse Storage deletion
+
+By default, only memory files (`MEMORY.md` + `memory/**/*.md`) are synced. Set `syncWorkspace: true` to sync the entire workspace — all supported files become searchable via `memory_search` without any tool or API changes.
+
+Supported file extensions (workspace sync):
 
-That's it. The plugin auto-syncs your files on startup and watches for changes in real time. With zero additional config, search behaves identically to OpenClaw's built-in memory search.
+| Category | Extensions |
+|----------|-----------|
+| Documents | `.doc`, `.docx`, `.hwp`, `.hwpx`, `.odg`, `.odp`, `.odt`, `.pdf`, `.ppt`, `.pptx`, `.rtf` |
+| Data | `.csv`, `.json`, `.ods`, `.toml`, `.tsv`, `.xls`, `.xlsx`, `.yaml`, `.yml` |
+| Images | `.bmp`, `.gif`, `.jpeg`, `.jpg`, `.png`, `.tif`, `.tiff`, `.webp` |
+| Text / Markup | `.epub`, `.htm`, `.html`, `.markdown`, `.md`, `.text`, `.txt`, `.xhtml`, `.xml` |
+
+When workspace sync is enabled, dotfiles/dotdirs (`.*`) are always excluded. Add further patterns via `syncBlacklist`:
+
+```json
+{
+  "storageUrl": "...", "tableUrl": "...", "apiKey": "...",
+  "syncWorkspace": true,
+  "syncBlacklist": ["node_modules/", "dist/", "*.log", "*.tmp"]
+}
+```
+
+Supported blacklist patterns:
+
+| Pattern | Example | Matches |
+|---------|---------|---------|
+| `"dir/"` | `"node_modules/"` | Directory with that exact name |
+| `"*.ext"` | `"*.tmp"` | Any segment ending with `.tmp` |
+| `"prefix*"` | `".*"` | Any segment starting with `.` (built-in) |
+| `"name"` | `"Thumbs.db"` | Exact filename in any directory |
+
+## Storage Layout
+
+All synced files are stored under the `openclaw/` prefix in Seahorse Storage (e.g., `MEMORY.md` → `openclaw/MEMORY.md`). This isolates plugin data from other data in the same Seahorse tenant. Search results are mapped back to workspace-relative paths automatically.
+
+## Tools
+
+### `memory_search`
+
+Semantic vector search over synced files via Seahorse.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | Yes | Search query |
+| `maxResults` | number | No | Max results (default: `topK` config) |
+| `minScore` | number | No | Min relevance score 0-1 (default: `minScore` config) |
+
+### `memory_get`
+
+Read a local file by path.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `path` | string | Yes | Relative path (e.g., `MEMORY.md`, `memory/notes.md`) |
+| `from` | number | No | Start line (1-based) |
+| `lines` | number | No | Number of lines to read |
+
+By default, allowed paths are `MEMORY.md` and files under `memory/` only. With `syncWorkspace: true`, any workspace file is accessible (except blacklisted paths).
 
 ## Config Reference
 
@@ -47,7 +120,7 @@ That's it. The plugin auto-syncs your files on startup and watches for changes i
 |-------|------|----------|-------------|
 | `storageUrl` | string | Yes | Seahorse Storage tenant URL |
 | `tableUrl` | string | Yes | Seahorse Table tenant URL |
-| `apiKey` | string | No | API key. Auto-reads from `SEAHORSE_API_KEY` env var if omitted. Also supports `${ENV_VAR}` syntax. |
+| `apiKey` | string | No | API key. Auto-reads from `SEAHORSE_API_KEY` env var if omitted. Supports `${ENV_VAR}` syntax. |
 
 ### Layer 1: Search & Sync Behavior (optional)
 
@@ -125,7 +198,7 @@ Example — hybrid with equal dense/sparse weighting (Seahorse native behavior):
 
 ## Defaults Comparison: OpenClaw vs Seahorse
 
-The plugin ships with OpenClaw-compatible defaults so it works as a drop-in replacement. The table below shows where these differ from Seahorse server defaults, so you can tune toward Seahorse-native behavior when desired.
+The plugin ships with OpenClaw-compatible defaults. The table below shows where these differ from Seahorse server defaults, so you can tune toward Seahorse-native behavior when desired.
 
 | Parameter | Plugin Default | OpenClaw Native | Seahorse Server | Notes |
 |-----------|---------------|-----------------|-----------------|-------|
@@ -142,61 +215,3 @@ The plugin ships with OpenClaw-compatible defaults so it works as a drop-in repl
 | Projection | `"id, text, metadata, distance, score"` | N/A | *(must specify)* | Requests both `distance` (dense) and `score` (hybrid) for proper normalization |
 
 > **Hybrid (RRF) Score Normalization**: In hybrid mode, Seahorse returns raw RRF scores (~0.01-0.03). The plugin normalizes these to a 0-1 scale by dividing by the theoretical maximum (`numRankers / (k + 1)`), making them compatible with the `minScore` threshold. With default k=60 and 2 rankers, a raw score of 0.016 becomes ~0.49 after normalization.
-
-## Tools
-
-### `memory_search`
-
-Semantic vector search over synced files via Seahorse.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `query` | string | Yes | Search query |
-| `maxResults` | number | No | Max results (default: `topK` config) |
-| `minScore` | number | No | Min relevance score 0-1 (default: `minScore` config) |
-
-### `memory_get`
-
-Read a local memory file by path.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `path` | string | Yes | Relative path (e.g., `MEMORY.md`, `memory/notes.md`) |
-| `from` | number | No | Start line (1-based) |
-| `lines` | number | No | Number of lines to read |
-
-Allowed paths: `MEMORY.md` (workspace root) and files under `memory/` only.
-
-## Storage Layout
-
-All memory files are stored under the `openclaw/` prefix in Seahorse Storage (e.g., `MEMORY.md` → `openclaw/MEMORY.md`). This isolates OpenClaw memory files from other data in the same tenant. Search results are mapped back to workspace-relative paths automatically.
-
-## File Sync
-
-The plugin runs a background service (`seahorse-sync`) that keeps Seahorse Storage in sync:
-
-- **Initial sync**: scans files on startup, uploads only changed files
-- **Live watch**: detects file create/modify/delete via `fs.watch` (1.5s debounce)
-- **Dedup**: mtime-based state tracking prevents redundant uploads
-- **Delete sync**: local file deletion triggers Seahorse Storage deletion
-
-By default, only memory files (`MEMORY.md` + `memory/**/*.md`) are synced. Set `syncWorkspace: true` to sync the entire workspace — all files become searchable via `memory_search` without any tool or API changes.
-
-When workspace sync is enabled, dotfiles/dotdirs (`.*`) are always excluded. Add further patterns via `syncBlacklist`:
-
-```json
-{
-  "storageUrl": "...", "tableUrl": "...", "apiKey": "...",
-  "syncWorkspace": true,
-  "syncBlacklist": ["node_modules/", "dist/", "*.log", "*.tmp"]
-}
-```
-
-Supported blacklist patterns:
-
-| Pattern | Example | Matches |
-|---------|---------|---------|
-| `"dir/"` | `"node_modules/"` | Directory with that exact name |
-| `"*.ext"` | `"*.tmp"` | Any segment ending with `.tmp` |
-| `"prefix*"` | `".*"` | Any segment starting with `.` (built-in) |
-| `"name"` | `"Thumbs.db"` | Exact filename in any directory |

package/index.ts

@@ -94,7 +94,7 @@ const plugin: OpenClawPluginDefinition = {
     const client = new SeahorseClient(config, api.logger);
 
     registerMemorySearchTool(api, config, client);
-    registerMemoryGetTool(api);
+    registerMemoryGetTool(api, config);
     registerSyncService(api, client, config);
 
     api.logger.info("[openclaw-seahorse] Plugin registered (memory_search, memory_get, sync service).");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dn-inc/openclaw-seahorse",
   "type": "module",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Seahorse memory plugin for OpenClaw",
   "license": "MIT",
   "main": "./index.ts",

package/src/helpers.ts

@@ -187,17 +187,20 @@ async function collectAllFiles(
   }
 }
 
-/** Check whether a resolved absolute path is within the allowed memory directories. */
-export function isAllowedMemoryPath(resolvedPath: string, workspaceDir: string): boolean {
+/** Check whether a resolved absolute path is within the workspace boundary. */
+export function isWithinWorkspace(resolvedPath: string, workspaceDir: string): boolean {
   const normalizedWorkspace = path.resolve(workspaceDir);
   const normalizedTarget = path.resolve(resolvedPath);
+  return normalizedTarget.startsWith(normalizedWorkspace + path.sep) || normalizedTarget === normalizedWorkspace;
+}
 
-  // Must be within the workspace directory
-  if (!normalizedTarget.startsWith(normalizedWorkspace + path.sep) && normalizedTarget !== normalizedWorkspace) {
+/** Check whether a resolved absolute path is within the allowed memory directories. */
+export function isAllowedMemoryPath(resolvedPath: string, workspaceDir: string): boolean {
+  if (!isWithinWorkspace(resolvedPath, workspaceDir)) {
     return false;
   }
 
-  const relative = path.relative(normalizedWorkspace, normalizedTarget);
+  const relative = path.relative(path.resolve(workspaceDir), path.resolve(resolvedPath));
 
   // Allow MEMORY.md at root
   if (relative === "MEMORY.md") return true;

package/src/tools.ts

@@ -5,7 +5,8 @@ import type { SeahorseConfig } from "./types.js";
 import type { OpenClawPluginApi, OpenClawPluginToolContext, AgentToolResult } from "openclaw/plugin-sdk";
 import { jsonResult } from "openclaw/plugin-sdk";
 import { SeahorseSearchError, type SeahorseClient } from "./client.js";
-import { sanitizeError, isAllowedMemoryPath, toPosixPath } from "./helpers.js";
+import { sanitizeError, isAllowedMemoryPath, isWithinWorkspace, isBlacklisted, toPosixPath } from "./helpers.js";
+import { DEFAULT_BLACKLIST } from "./types.js";
 
 type ToolResult = AgentToolResult;
 
@@ -82,8 +83,9 @@ export function registerMemorySearchTool(
     (_ctx: OpenClawPluginToolContext) => ({
       name: "memory_search",
       label: "Memory Search",
-      description:
-        "Search memories stored in MEMORY.md and memory/*.md files using semantic vector search powered by Seahorse.",
+      description: config.syncWorkspace
+        ? "Search across all workspace files using semantic vector search powered by Seahorse."
+        : "Search memories stored in MEMORY.md and memory/*.md files using semantic vector search powered by Seahorse.",
       parameters: Type.Object({
         query: Type.String({ description: "Search query" }),
         maxResults: Type.Optional(
@@ -171,14 +173,15 @@ export function registerMemorySearchTool(
 /**
  * Register the `memory_get` tool on the given plugin API.
  */
-export function registerMemoryGetTool(api: OpenClawPluginApi): void {
+export function registerMemoryGetTool(api: OpenClawPluginApi, config: SeahorseConfig): void {
   api.registerTool(
     (ctx: OpenClawPluginToolContext) => {
       return {
         name: "memory_get",
         label: "Memory Get",
-        description:
-          "Read a memory file by path. Returns the file content with optional line range.",
+        description: config.syncWorkspace
+          ? "Read a workspace file by path. Returns the file content with optional line range."
+          : "Read a memory file by path. Returns the file content with optional line range.",
         parameters: Type.Object({
           path: Type.String({ description: "Relative path to memory file" }),
           from: Type.Optional(
@@ -212,13 +215,33 @@ export function registerMemoryGetTool(api: OpenClawPluginApi): void {
 
           const resolvedPath = path.resolve(workspaceDir, relativePath);
 
-          if (!isAllowedMemoryPath(resolvedPath, workspaceDir)) {
-            api.logger.warn(`[openclaw-seahorse] memory_get: access denied for "${relativePath}"`);
-            return jsonResult({
-              path: relativePath,
-              text: "",
-              error: `Access denied. Path "${relativePath}" is outside the allowed memory directories (MEMORY.md, memory/).`,
-            });
+          if (config.syncWorkspace) {
+            if (!isWithinWorkspace(resolvedPath, workspaceDir)) {
+              api.logger.warn(`[openclaw-seahorse] memory_get: access denied for "${relativePath}"`);
+              return jsonResult({
+                path: relativePath,
+                text: "",
+                error: `Access denied. Path "${relativePath}" is outside the workspace.`,
+              });
+            }
+            const mergedBlacklist = [...DEFAULT_BLACKLIST, ...config.syncBlacklist];
+            if (isBlacklisted(toPosixPath(relativePath), mergedBlacklist)) {
+              api.logger.warn(`[openclaw-seahorse] memory_get: blacklisted path "${relativePath}"`);
+              return jsonResult({
+                path: relativePath,
+                text: "",
+                error: `Access denied. Path "${relativePath}" is blacklisted.`,
+              });
+            }
+          } else {
+            if (!isAllowedMemoryPath(resolvedPath, workspaceDir)) {
+              api.logger.warn(`[openclaw-seahorse] memory_get: access denied for "${relativePath}"`);
+              return jsonResult({
+                path: relativePath,
+                text: "",
+                error: `Access denied. Path "${relativePath}" is outside the allowed memory directories (MEMORY.md, memory/).`,
+              });
+            }
           }
 
           // Guard against symlink traversal: verify the real path stays within workspace