@hyperspell/openclaw-hyperspell 0.14.0 → 0.14.1

package/README.md

@@ -151,6 +151,22 @@ When `syncMemories: true`, the plugin syncs markdown files from your agent's wor
 - 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
+- Startup sync runs in the **background** — the agent boots immediately and sync proceeds without blocking it
+- A per-section content hash is tracked in `<workspace>/.hyperspell-sync-hashes.json`, so unchanged sections are skipped on subsequent syncs (no re-ingestion)
+
+**Tuning sync (object form):**
+
+```jsonc
+"syncMemories": {
+  "enabled": true,
+  "sectionize": true,     // split files on ## headings into separate memories
+  "watchPaths": [],        // extra files/dirs to sync beyond memory/
+  "debounceMs": 2000,      // wait for writes to settle before syncing
+  "maxAgeDays": 30          // startup skips already-synced files older than this
+}
+```
+
+`maxAgeDays` bounds steady-state load: on startup, files whose mtime is older than the cutoff **and** already recorded in the sync manifest are skipped without re-reading. Files not yet in the manifest are always synced once regardless of age, and editing an old file bumps its mtime back into the window. Set to `0` to disable the cutoff.
 
 **Example frontmatter after sync:**
 

package/dist/commands/setup.js

@@ -276,6 +276,7 @@ async function runSetup() {
                     sectionize: true,
                     watchPaths: [],
                     debounceMs: 2000,
+                    maxAgeDays: 30,
                 },
                 sources: [],
                 maxResults: 10,

package/dist/config.js

@@ -249,7 +249,7 @@ export function parseConfig(raw) {
     // object form must be too, or a typo (sectionise/debounceMS) is silently
     // ignored and the user gets default behavior they didn't ask for.
     if (typeof smRaw === "object" && smRaw !== null && !Array.isArray(smRaw)) {
-        assertAllowedKeys(smObj, ["enabled", "sectionize", "watchPaths", "debounceMs"], "hyperspell.syncMemories");
+        assertAllowedKeys(smObj, ["enabled", "sectionize", "watchPaths", "debounceMs", "maxAgeDays"], "hyperspell.syncMemories");
     }
     return {
         apiKey,
@@ -280,6 +280,7 @@ export function parseConfig(raw) {
                 ? smObj.watchPaths
                 : [],
             debounceMs: smObj.debounceMs ?? 2000,
+            maxAgeDays: smObj.maxAgeDays ?? 30,
         },
         sources: parseSources(cfg.sources),
         maxResults: cfg.maxResults ?? 10,

package/dist/hooks/memory-sync.js

@@ -106,8 +106,9 @@ export async function syncMemoriesOnStartup(client, workspaceDir, options) {
         const result = await syncAllFilesSectionized(client, workspaceDir, {
             userId: options.userId,
             watchPaths: options.watchPaths,
+            maxAgeDays: options.maxAgeDays,
         });
-        log.info(`Section sync complete: ${result.synced} synced, ${result.skipped} unchanged, ${result.removed} removed, ${result.failed} failed`);
+        log.info(`Section sync complete: ${result.synced} synced, ${result.skipped} unchanged, ${result.agedOut} aged-out, ${result.removed} removed, ${result.failed} failed`);
         if (result.failed > 0) {
             for (const error of result.errors) {
                 log.error(`  - ${error}`);

package/dist/index.js

@@ -117,13 +117,22 @@ export default {
             id: "openclaw-hyperspell",
             start: async () => {
                 api.logger.info("hyperspell: connected");
-                // Sync memories on startup if enabled
+                // Sync memories on startup if enabled.
+                //
+                // Deliberately NOT awaited: the bulk sync is sequential and
+                // network-bound (one request per changed section), so awaiting
+                // it here stalls the agent's startup until the entire corpus
+                // has been processed. Run it in the background and let the
+                // agent come up immediately; failures are logged, not fatal.
                 if (cfg.syncMemories) {
                     const workspaceDir = getWorkspaceDir();
-                    await syncMemoriesOnStartup(client, workspaceDir, {
+                    void syncMemoriesOnStartup(client, workspaceDir, {
                         userId: cfg.multiUser?.sharedUserId,
                         sectionize: cfg.syncMemoriesConfig.sectionize,
                         watchPaths: cfg.syncMemoriesConfig.watchPaths,
+                        maxAgeDays: cfg.syncMemoriesConfig.maxAgeDays,
+                    }).catch((err) => {
+                        api.logger.error("hyperspell: background memory sync failed", err);
                     });
                 }
             },

package/dist/sync/markdown.js

@@ -168,10 +168,14 @@ export function loadManifest(workspaceDir) {
     try {
         if (fs.existsSync(p)) {
             const parsed = JSON.parse(fs.readFileSync(p, "utf-8"));
-            // Self-healing: an unrecognized/legacy shape is discarded. This feature
-            // has never shipped a released on-disk format, so nothing to migrate —
-            // a mismatch just triggers one re-sync, which is idempotent.
-            if (parsed && parsed.version === MANIFEST_VERSION && parsed.files) {
+            // Forward-migrate rather than discard. Throwing the manifest away on a
+            // version bump means every section re-uploads on the next run — the
+            // exact full-re-ingest load this guard exists to prevent. As long as the
+            // `files` map is structurally a record we keep it: the per-section hash
+            // check still gates every upload, so a stale-but-readable manifest is
+            // strictly better than an empty one. Only a missing/corrupt `files`
+            // (truly unusable) falls back to empty.
+            if (parsed && typeof parsed.files === "object" && parsed.files !== null) {
                 return { version: MANIFEST_VERSION, files: parsed.files };
             }
         }
@@ -183,11 +187,24 @@ export function loadManifest(workspaceDir) {
 }
 export function saveManifest(workspaceDir, manifest) {
     const p = manifestPath(workspaceDir);
+    // Atomic write: a process killed mid-write (deploy/restart) would otherwise
+    // leave a truncated JSON file, which loadManifest can only treat as corrupt
+    // -> empty -> full re-ingest. Write to a temp sibling, then rename (atomic
+    // on the same filesystem) so readers only ever see a complete manifest.
+    const tmp = `${p}.${process.pid}.tmp`;
     try {
-        fs.writeFileSync(p, JSON.stringify(manifest, null, 2));
+        fs.writeFileSync(tmp, JSON.stringify(manifest, null, 2));
+        fs.renameSync(tmp, p);
     }
     catch (err) {
         log.error("Failed to write sync manifest", err);
+        try {
+            if (fs.existsSync(tmp))
+                fs.unlinkSync(tmp);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
     }
 }
 /**
@@ -481,12 +498,44 @@ export async function syncAllMemoryFiles(client, workspaceDir, options) {
  */
 export async function syncAllFilesSectionized(client, workspaceDir, options) {
     const files = getSyncableFiles(workspaceDir, options?.watchPaths);
+    // Age pre-filter: a file untouched for longer than maxAgeDays that is
+    // already recorded in the manifest has been ingested at least once and is
+    // 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
+    // edited-but-old files re-enter the window naturally.
+    const maxAgeDays = options?.maxAgeDays ?? 0;
+    let candidates = files;
+    let agedOut = 0;
+    if (maxAgeDays > 0) {
+        const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+        const manifest = loadManifest(workspaceDir);
+        candidates = files.filter((filePath) => {
+            const key = fileKey(workspaceDir, filePath);
+            const known = manifest.files[key] !== undefined;
+            if (!known)
+                return true;
+            try {
+                if (fs.statSync(filePath).mtimeMs >= cutoff)
+                    return true;
+            }
+            catch {
+                return true; // stat failed — be safe, process it
+            }
+            agedOut++;
+            return false;
+        });
+        if (agedOut > 0) {
+            log.info(`Skipping ${agedOut} unchanged file(s) older than ${maxAgeDays}d (already synced)`);
+        }
+    }
     let totalSynced = 0;
     let totalSkipped = 0;
     let totalFailed = 0;
     let totalRemoved = 0;
     const allErrors = [];
-    for (const filePath of files) {
+    for (const filePath of candidates) {
         const result = await syncMarkdownFileSectionized(client, filePath, workspaceDir, {
             userId: options?.userId,
         });
@@ -501,6 +550,7 @@ export async function syncAllFilesSectionized(client, workspaceDir, options) {
         skipped: totalSkipped,
         failed: totalFailed,
         removed: totalRemoved,
+        agedOut,
         errors: allErrors,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "type": "module",
   "description": "OpenClaw Hyperspell memory plugin",
   "license": "MIT",