@hyperspell/openclaw-hyperspell 0.21.0 → 0.21.1

package/dist/commands/preview.js

@@ -3,7 +3,7 @@ import { gatherOrientation, personalUserId } from "../hooks/startup-orientation.
 import { isExcludedChannel } from "../lib/exclude-channels.js";
 import { log } from "../logger.js";
 /**
- * Assemble a read-only report of what before_agent_start WOULD inject at the
+ * Assemble a read-only report of what the injection hook WOULD inject at the
  * start of the next session. Calls only the pure fetch/format functions the
  * real hooks are composed from — never the hook handlers themselves — so it
  * cannot touch the inject-once session caches, and it never calls rollMood
@@ -12,7 +12,7 @@ import { log } from "../logger.js";
  */
 export async function buildPreviewReport(client, cfg, ctx) {
     // Quarantined channels get no injected memory of any kind (index.ts guards
-    // before_agent_start with the same check) — report that instead of a bundle.
+    // the injection hook with the same check) — report that instead of a bundle.
     if (isExcludedChannel({ channelId: ctx.channel }, cfg)) {
         return "This channel is quarantined (excludeChannels): no context would be injected here and no memory would be written.";
     }

package/dist/hooks/emotional-state.js

@@ -58,7 +58,7 @@ const sessionMoods = new Map();
  * hundred tokens of repeated wrapper per turn.
  *
  * Lifecycle:
- *  - first before_agent_start in a session: fetch, inject, mark.
+ *  - first injection-hook fire in a session: fetch, inject, mark.
  *  - subsequent turns in same session: skip (return undefined).
  *  - after_compaction: clear the mark so the next turn re-injects (the
  *    initial injection may have been compacted out of history).
@@ -185,7 +185,7 @@ export function buildEmotionalContext(states) {
  * context. On later turns of the same session, return undefined — the
  * injection from the first turn is already in the conversation history.
  *
- * Runs on `before_agent_start` (which fires every turn).
+ * Runs on the session injection hook (fires every turn).
  */
 export function buildEmotionalStateFetchHandler(client, cfg, deps = {}) {
     const now = deps.now ?? Date.now;

package/dist/hooks/memory-sync.js

@@ -1,3 +1,4 @@
+import * as fs from "node:fs";
 import * as path from "node:path";
 import { getWorkspaceDir } from "../config.js";
 import { log } from "../logger.js";
@@ -128,6 +129,64 @@ export function buildFileSyncHandler(client, cfg) {
         }
     };
 }
+/**
+ * Plugin-owned file watcher feeding the file-sync handler.
+ *
+ * OpenClaw 2026.7.2 removed the host `file_changed` hook with no replacement,
+ * so live sync must come from the plugin itself. Used on EVERY host version
+ * (old hosts still expose `file_changed`, but registering both would
+ * double-sync) — one canonical path. Events are forwarded in the old hook's
+ * `{ file_path }` shape; the handler already owns syncability filtering and
+ * debounce, so the watcher stays dumb.
+ */
+export function buildMemorySyncWatcher(cfg, onFileChanged) {
+    const workspaceDir = getWorkspaceDir();
+    const roots = [
+        path.join(workspaceDir, "memory"),
+        ...(cfg.syncMemoriesConfig.watchPaths ?? []).map((wp) => resolveWatchPath(workspaceDir, wp.path)),
+    ];
+    const watchers = [];
+    const start = () => {
+        let watched = 0;
+        for (const root of roots) {
+            let isDirectory;
+            try {
+                isDirectory = fs.statSync(root).isDirectory();
+            }
+            catch {
+                log.debug(`memory-sync watcher: root missing, skipping: ${root}`);
+                continue;
+            }
+            // Watching a file directly breaks on editor rename-replace cycles;
+            // watch the parent and filter to the file's own events instead.
+            const dir = isDirectory ? root : path.dirname(root);
+            try {
+                const watcher = fs.watch(dir, { recursive: isDirectory }, (_type, filename) => {
+                    if (!filename)
+                        return;
+                    const filePath = path.join(dir, filename.toString());
+                    if (!isDirectory && filePath !== root)
+                        return;
+                    onFileChanged({ file_path: filePath });
+                });
+                watchers.push(watcher);
+                watched += 1;
+            }
+            catch (err) {
+                log.error(`memory-sync watcher failed for ${dir}`, err);
+            }
+        }
+        if (watched > 0) {
+            log.info(`memory-sync: watching ${watched} root(s) with plugin-owned watchers`);
+        }
+    };
+    const stop = () => {
+        for (const watcher of watchers)
+            watcher.close();
+        watchers.length = 0;
+    };
+    return { start, stop };
+}
 /**
  * Sync all existing memory files on startup.
  * Uses section-level sync when sectionize is enabled.

package/dist/hooks/startup-orientation.js

@@ -194,7 +194,7 @@ async function fetchRecentConversations(client, limit, userId) {
 }
 /**
  * The fetch+format core of startup orientation, shared by the real
- * before_agent_start handler and the read-only /previewcontext command.
+ * session-start injection handler and the read-only /previewcontext command.
  * Pure with respect to session lifecycle: no inject-once cache, no retry
  * counting — callers own that policy. Keeping one formatter here keeps the
  * preview byte-identical to real injection.
@@ -207,7 +207,7 @@ export async function gatherOrientation(client, cfg, userId) {
     // off agents). Fall back to agent_end traces only when there's no hot
     // buffer but auto-trace is on. Otherwise skip: there's nothing to fetch,
     // and the trace-source list is expensive (observed ~12s + failing/turn),
-    // blocking before_agent_start and slowing the reply.
+    // blocking the injection hook and slowing the reply.
     const recentSource = cfg.hotBuffer.enabled
         ? "hotBuffer"
         : cfg.autoTrace.enabled

package/dist/index.js

@@ -5,7 +5,7 @@ import { parseConfig, hyperspellConfigSchema, getWorkspaceDir, VALID_SOURCES } f
 import { buildAutoContextHandler } from "./hooks/auto-context.js";
 import { buildAutoTraceHandler } from "./hooks/auto-trace.js";
 import { buildEmotionalStateCompactionHandler, buildEmotionalStateFetchHandler, buildEmotionalStateSessionCleanupHandler, buildEmotionalStateStoreHandler, } from "./hooks/emotional-state.js";
-import { buildFileSyncHandler, syncMemoriesOnStartup } from "./hooks/memory-sync.js";
+import { buildFileSyncHandler, buildMemorySyncWatcher, syncMemoriesOnStartup, } from "./hooks/memory-sync.js";
 import { buildHotBufferHandler, buildHotBufferSessionCleanupHandler, } from "./hooks/hot-buffer.js";
 import { buildStartupOrientationCompactionHandler, buildStartupOrientationHandler, buildStartupOrientationSessionCleanupHandler, } from "./hooks/startup-orientation.js";
 import { isExcludedChannel } from "./lib/exclude-channels.js";
@@ -89,7 +89,7 @@ export default {
         const client = new HyperspellClient(cfg);
         // Channel quarantine (cfg.excludeChannels): excluded conversations get no
         // memory surface in either direction. Guard the shared choke points here —
-        // before_agent_start (all injection), agent_end (all writes), and the tool
+        // the injection hook (all injection), agent_end (all writes), and the tool
         // factories — so individual hooks stay quarantine-unaware.
         const quarantined = (ctx) => {
             if (!isExcludedChannel(ctx, cfg))
@@ -137,8 +137,19 @@ export default {
             api.on("after_compaction", buildStartupOrientationCompactionHandler());
             api.on("session_end", buildStartupOrientationSessionCleanupHandler());
         }
+        // Injection hook selection: OpenClaw 2026.7.2 removed the plugin-facing
+        // `before_agent_start`; its replacement `agent_turn_prepare` shipped in the
+        // same core commit as `enqueueNextTurnInjection` (openclaw#72287, 2026-04),
+        // so probing that api member tells us exactly which hook this host knows.
+        // Register exactly ONE of the two: cores between 2026-04 and 2026-07
+        // accept both and would double-inject. Both hooks share the same
+        // { prependContext } result contract and provide event.prompt.
+        const injectionHook = typeof api
+            .enqueueNextTurnInjection === "function"
+            ? "agent_turn_prepare"
+            : "before_agent_start";
         if (startHandlers.length > 0) {
-            api.on("before_agent_start", async (event, ctx) => {
+            api.on(injectionHook, async (event, ctx) => {
                 // Quarantined channels get no injected memory of any kind.
                 if (quarantined(ctx))
                     return undefined;
@@ -167,10 +178,16 @@ export default {
             api.on("agent_end", unlessQuarantined(buildHotBufferHandler(client, cfg)));
             api.on("session_end", buildHotBufferSessionCleanupHandler());
         }
-        // Register memory sync hook
+        // Memory sync live watcher. Plugin-owned on every host version:
+        // 2026.7.2 removed the host `file_changed` hook, and on older hosts
+        // registering both paths would double-sync each edit. Started/stopped
+        // by the lifecycle service below.
+        let memorySyncWatcher;
         if (cfg.syncMemories) {
             const fileSyncHandler = buildFileSyncHandler(client, cfg);
-            api.on("file_changed", fileSyncHandler);
+            memorySyncWatcher = buildMemorySyncWatcher(cfg, (event) => {
+                void fileSyncHandler(event);
+            });
             api.logger.info(`hyperspell: memory sync enabled (sectionize=${cfg.syncMemoriesConfig.sectionize}, watchPaths=${cfg.syncMemoriesConfig.watchPaths.length})`);
         }
         // Register memory network tools
@@ -219,8 +236,10 @@ export default {
                         api.logger.error("hyperspell: background memory sync failed", err);
                     });
                 }
+                memorySyncWatcher?.start();
             },
             stop: () => {
+                memorySyncWatcher?.stop();
                 api.logger.info("hyperspell: stopped");
             },
         });

package/dist/lib/speaker-tracker.js

@@ -10,7 +10,7 @@
  *
  * Lifecycle:
  *   - record() on every turn that has a resolvable senderId (hot-buffer agent_end,
- *     auto-context before_agent_start)
+ *     auto-context injection hook)
  *   - isMultiSpeaker() checked by any hook or tool that needs to guard behaviour
  *   - cleanup() on session_end, called from the hot-buffer cleanup handler
  */

package/dist/sync/markdown.js

@@ -210,7 +210,7 @@ export function saveManifest(workspaceDir, manifest) {
 }
 /**
  * Serializes manifest read-modify-write across the whole process. Startup bulk
- * sync and the live file_changed handler (plus independent per-file debounce
+ * sync and the live file-watch handler (plus independent per-file debounce
  * timers) would otherwise interleave load → await addMemory → save and lose
  * resourceId entries, causing the next sync to re-upload sections as brand-new
  * memories. Every load→sync→save runs inside this critical section.
@@ -583,7 +583,7 @@ export async function syncAllFilesSectionized(client, workspaceDir, options) {
     // not changing — re-parsing/hashing/diffing it every startup is pure churn.
     // Files NOT yet in the manifest are always processed regardless of age, so
     // a genuinely cold start (or a never-synced old file) still ingests once.
-    // The live file_changed handler is unaffected: an edit bumps mtime, so
+    // The live file-watch handler is unaffected: an edit bumps mtime, so
     // edited-but-old files re-enter the window naturally.
     const maxAgeDays = options?.maxAgeDays ?? 0;
     let candidates = files;

package/package.json

@@ -1,60 +1,60 @@
 {
-  "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.21.0",
-  "type": "module",
-  "description": "OpenClaw Hyperspell memory plugin",
-  "license": "MIT",
-  "main": "./dist/index.js",
-  "files": [
-    "dist/",
-    "openclaw.plugin.json",
-    "README.md"
-  ],
-  "author": "Hyperspell <hello@hyperspell.com> (https://hyperspell.com)",
-  "homepage": "https://hyperspell.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/hyperspell/hyperspell-openclaw.git"
-  },
-  "keywords": [
-    "openclaw",
-    "hyperspell",
-    "memory",
-    "rag",
-    "ai",
-    "plugin"
-  ],
-  "dependencies": {
-    "@clack/prompts": "^1.0.0",
-    "@sinclair/typebox": "^0.34.0",
-    "hyperspell": "^0.35.1"
-  },
-  "peerDependencies": {
-    "openclaw": ">=2026.1.29"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "prepublishOnly": "npm run build",
-    "check-types": "tsc --noEmit",
-    "lint": "bunx @biomejs/biome ci .",
-    "lint:fix": "bunx @biomejs/biome check --write .",
-    "test": "node --test --experimental-strip-types client.test.ts logger.test.ts lib/sender.test.ts lib/filters.test.ts lib/search-error.test.ts lib/coverage-log.test.ts lib/session.test.ts lib/exclude-channels.test.ts lib/ranking.test.ts lib/eval-matchers.test.ts lib/loops-audit.test.ts lib/mood-skew-audit.test.ts tools/search.test.ts tools/emotional-arc.test.ts commands/preview.test.ts commands/purge-channel.test.ts config.test.ts sync/markdown.test.ts graph/ops.test.ts hooks/auto-trace.test.ts hooks/auto-context.test.ts hooks/hot-buffer.test.ts hooks/emotional-state.test.ts hooks/startup-orientation.test.ts hooks/mood-weather.test.ts eval/eval.test.ts"
-  },
-  "openclaw": {
-    "extensions": [
-      "./dist/index.js"
-    ],
-    "hooks": [],
-    "compat": {
-      "pluginApi": ">=2026.1.29",
-      "minGatewayVersion": "2026.1.29"
-    },
-    "build": {
-      "openclawVersion": "2026.3.24-beta.2",
-      "pluginSdkVersion": "2026.3.24-beta.2"
-    }
-  },
-  "devDependencies": {
-    "typescript": "^5.9.3"
-  }
+	"name": "@hyperspell/openclaw-hyperspell",
+	"version": "0.21.1",
+	"type": "module",
+	"description": "OpenClaw Hyperspell memory plugin",
+	"license": "MIT",
+	"main": "./dist/index.js",
+	"files": [
+		"dist/",
+		"openclaw.plugin.json",
+		"README.md"
+	],
+	"author": "Hyperspell <hello@hyperspell.com> (https://hyperspell.com)",
+	"homepage": "https://hyperspell.com",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/hyperspell/hyperspell-openclaw.git"
+	},
+	"keywords": [
+		"openclaw",
+		"hyperspell",
+		"memory",
+		"rag",
+		"ai",
+		"plugin"
+	],
+	"dependencies": {
+		"@clack/prompts": "^1.0.0",
+		"@sinclair/typebox": "^0.34.0",
+		"hyperspell": "^0.35.1"
+	},
+	"peerDependencies": {
+		"openclaw": ">=2026.1.29"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"prepublishOnly": "npm run build",
+		"check-types": "tsc --noEmit",
+		"lint": "bunx @biomejs/biome ci .",
+		"lint:fix": "bunx @biomejs/biome check --write .",
+		"test": "node --test --experimental-strip-types client.test.ts logger.test.ts lib/sender.test.ts lib/filters.test.ts lib/search-error.test.ts lib/coverage-log.test.ts lib/session.test.ts lib/exclude-channels.test.ts lib/ranking.test.ts lib/eval-matchers.test.ts lib/loops-audit.test.ts lib/mood-skew-audit.test.ts tools/search.test.ts tools/emotional-arc.test.ts commands/preview.test.ts commands/purge-channel.test.ts config.test.ts sync/markdown.test.ts graph/ops.test.ts hooks/memory-sync.watcher.test.ts hooks/auto-trace.test.ts hooks/auto-context.test.ts hooks/hot-buffer.test.ts hooks/emotional-state.test.ts hooks/startup-orientation.test.ts hooks/mood-weather.test.ts eval/eval.test.ts"
+	},
+	"openclaw": {
+		"extensions": [
+			"./dist/index.js"
+		],
+		"hooks": [],
+		"compat": {
+			"pluginApi": ">=2026.1.29",
+			"minGatewayVersion": "2026.1.29"
+		},
+		"build": {
+			"openclawVersion": "2026.3.24-beta.2",
+			"pluginSdkVersion": "2026.3.24-beta.2"
+		}
+	},
+	"devDependencies": {
+		"typescript": "^5.9.3"
+	}
 }