@hyperspell/openclaw-hyperspell 0.13.1 → 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/client.js

@@ -214,6 +214,30 @@ export class HyperspellClient {
         log.debugResponse("memories.get", { resourceId, hasData: "data" in raw });
         return raw;
     }
+    /**
+     * Delete a memory by resource id. Memory-sync uploads land in the "vault"
+     * source (user-added documents), so that is the default. Best-effort: a
+     * 404 (already gone) is treated as success so callers can prune their
+     * local manifest unconditionally.
+     */
+    async deleteMemory(resourceId, options) {
+        const source = options?.source ?? "vault";
+        log.debugRequest("memories.delete", { resourceId, source });
+        try {
+            await this.client.memories.delete(resourceId, { source }, this.requestOptions(options?.userId));
+            log.debugResponse("memories.delete", { resourceId, deleted: true });
+            return { deleted: true };
+        }
+        catch (err) {
+            const status = err?.status;
+            if (status === 404) {
+                log.debug(`Memory ${resourceId} already absent (404) — treating as deleted`);
+                return { deleted: true };
+            }
+            log.error(`Failed to delete memory ${resourceId}`, err);
+            return { deleted: false };
+        }
+    }
     async sendTrace(history, options) {
         log.debugRequest("sessions.add", {
             historyLength: history.length,

package/dist/commands/setup.js

@@ -4,7 +4,7 @@ import * as path from "node:path";
 import { userInfo } from "node:os";
 import * as p from "@clack/prompts";
 import Hyperspell from "hyperspell";
-import { syncAllMemoryFiles, getMemoryFiles } from "../sync/markdown.js";
+import { syncAllFilesSectionized, syncAllMemoryFiles, getMemoryFiles, } from "../sync/markdown.js";
 import { openInBrowser } from "../lib/browser.js";
 import { HyperspellClient } from "../client.js";
 import { getWorkspaceDir, parseConfig, resolveConfigPath } from "../config.js";
@@ -271,6 +271,13 @@ async function runSetup() {
                 autoTrace: { enabled: false, extract: ["procedure"] },
                 emotionalContext: false,
                 syncMemories: true,
+                syncMemoriesConfig: {
+                    enabled: true,
+                    sectionize: true,
+                    watchPaths: [],
+                    debounceMs: 2000,
+                    maxAgeDays: 30,
+                },
                 sources: [],
                 maxResults: 10,
                 relevanceThreshold: 0.6,
@@ -284,15 +291,18 @@ async function runSetup() {
                     loopsQuery: "open tasks pending questions unfinished promised need to follow up",
                 },
             });
-            const result = await syncAllMemoryFiles(hyperspellClient, workspaceDir);
+            // Use the same sectionized path the runtime uses, so a fresh setup
+            // doesn't whole-file-upload everything and then get re-synced as
+            // sections on first gateway start (= duplicate memories).
+            const result = await syncAllFilesSectionized(hyperspellClient, workspaceDir);
             if (result.failed > 0) {
-                s3.stop(`Synced ${result.synced} files, ${result.failed} failed`);
+                s3.stop(`Synced ${result.synced} section(s), ${result.skipped} unchanged, ${result.failed} failed`);
                 for (const error of result.errors) {
                     p.log.error(`  ${error}`);
                 }
             }
             else {
-                s3.stop(`Synced ${result.synced} memory files`);
+                s3.stop(`Synced ${result.synced} section(s) (${result.skipped} unchanged)`);
             }
         }
         else {
@@ -552,7 +562,12 @@ export function registerCliCommands(program, pluginConfig) {
             const cfg = parseConfig(pluginConfig);
             const client = new HyperspellClient(cfg);
             const workspaceDir = getWorkspaceDir();
-            const result = await syncAllMemoryFiles(client, workspaceDir);
+            // Mirror the runtime's sync mode so this manual command can't
+            // produce whole-file blobs that the gateway then re-syncs as
+            // sections (= duplicate memories).
+            const result = cfg.syncMemoriesConfig.sectionize
+                ? await syncAllFilesSectionized(client, workspaceDir)
+                : await syncAllMemoryFiles(client, workspaceDir);
             process.stdout.write(`Synced ${result.synced} files, ${result.failed} failed\n`);
             if (result.errors.length > 0) {
                 for (const error of result.errors) {

package/dist/config.js

@@ -235,6 +235,22 @@ export function parseConfig(raw) {
     const kgRaw = (cfg.knowledgeGraph ?? {});
     const atRaw = (cfg.autoTrace ?? {});
     const soRaw = (cfg.startupOrientation ?? {});
+    // syncMemories can be a boolean (legacy) or an object (new)
+    const smRaw = cfg.syncMemories;
+    const syncMemoriesEnabled = typeof smRaw === "boolean"
+        ? smRaw
+        : typeof smRaw === "object" && smRaw !== null
+            ? smRaw.enabled ?? true
+            : false;
+    const smObj = typeof smRaw === "object" && smRaw !== null
+        ? smRaw
+        : {};
+    // The rest of parseConfig is strict about unknown keys; the syncMemories
+    // 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", "maxAgeDays"], "hyperspell.syncMemories");
+    }
     return {
         apiKey,
         userId: cfg.userId,
@@ -256,7 +272,16 @@ export function parseConfig(raw) {
             loopsQuery: soRaw.loopsQuery ??
                 "open tasks pending questions unfinished promised need to follow up",
         },
-        syncMemories: cfg.syncMemories ?? false,
+        syncMemories: syncMemoriesEnabled,
+        syncMemoriesConfig: {
+            enabled: syncMemoriesEnabled,
+            sectionize: smObj.sectionize ?? true,
+            watchPaths: Array.isArray(smObj.watchPaths)
+                ? smObj.watchPaths
+                : [],
+            debounceMs: smObj.debounceMs ?? 2000,
+            maxAgeDays: smObj.maxAgeDays ?? 30,
+        },
         sources: parseSources(cfg.sources),
         maxResults: cfg.maxResults ?? 10,
         relevanceThreshold: cfg.relevanceThreshold ?? 0.6,

package/dist/hooks/memory-sync.js

@@ -1,54 +1,135 @@
 import * as path from "node:path";
 import { getWorkspaceDir } from "../config.js";
 import { log } from "../logger.js";
-import { syncMarkdownFile, syncAllMemoryFiles } from "../sync/markdown.js";
+import { syncMarkdownFile, syncMarkdownFileSectionized, syncAllMemoryFiles, syncAllFilesSectionized, } from "../sync/markdown.js";
 /**
- * Build a handler for file change events that syncs markdown files to Hyperspell
+ * Build a handler for file change events that syncs markdown files to Hyperspell.
+ *
+ * When `sectionize` is enabled (default for new config), files are split by
+ * ## headings and each section is synced as a separate memory. Unchanged
+ * sections (tracked by content hash) are skipped.
+ *
+ * When `sectionize` is false (legacy mode), entire files are uploaded as
+ * single memories.
  */
 export function buildFileSyncHandler(client, cfg) {
     const workspaceDir = getWorkspaceDir();
     const memoryDir = path.join(workspaceDir, "memory");
     const syncUserId = cfg.multiUser?.sharedUserId;
-    return async (event) => {
-        const filePath = event.file_path;
-        if (!filePath)
-            return;
-        // Only process markdown files in the workspace's memory directory
-        if (!filePath.startsWith(memoryDir) || !filePath.endsWith(".md")) {
-            return;
+    const sectionize = cfg.syncMemoriesConfig.sectionize;
+    const watchPaths = cfg.syncMemoriesConfig.watchPaths;
+    const debounceMs = cfg.syncMemoriesConfig.debounceMs;
+    // Resolve additional watch paths to absolute paths for matching
+    const resolvedWatchPaths = (watchPaths ?? []).map((wp) => wp.startsWith("/") ? wp : path.join(workspaceDir, wp));
+    // Debounce map: filePath -> timeout handle
+    const debounceTimers = new Map();
+    /**
+     * Check whether a file path is syncable (in memory/ or in a watchPath).
+     */
+    function isSyncable(filePath) {
+        if (!filePath.endsWith(".md"))
+            return false;
+        // Always sync memory/ files
+        if (filePath.startsWith(memoryDir + path.sep))
+            return true;
+        // Check additional watch paths
+        for (const wp of resolvedWatchPaths) {
+            if (filePath === wp || filePath.startsWith(wp + "/")) {
+                return true;
+            }
         }
+        return false;
+    }
+    async function doSync(filePath) {
         const fileName = path.basename(filePath);
         log.info(`Memory file changed: ${fileName}`);
         try {
-            const result = await syncMarkdownFile(client, filePath, { userId: syncUserId });
-            if (result.success) {
-                log.info(`Synced ${fileName} -> ${result.resourceId}`);
+            if (sectionize) {
+                const result = await syncMarkdownFileSectionized(client, filePath, workspaceDir, { userId: syncUserId });
+                if (result.synced > 0 || result.removed > 0) {
+                    log.info(`Section-synced ${fileName}: ${result.synced} synced, ${result.skipped} unchanged, ${result.removed} removed`);
+                }
+                else if (result.skipped > 0) {
+                    log.debug(`${fileName}: all ${result.skipped} sections unchanged`);
+                }
+                if (result.failed > 0) {
+                    log.error(`${fileName}: ${result.failed} sections failed:`);
+                    for (const err of result.errors) {
+                        log.error(`  - ${err}`);
+                    }
+                }
             }
             else {
-                log.error(`Failed to sync ${fileName}: ${result.error}`);
+                // Legacy whole-file sync
+                const result = await syncMarkdownFile(client, filePath, { userId: syncUserId });
+                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);
         }
+    }
+    return async (event) => {
+        const filePath = event.file_path;
+        if (!filePath)
+            return;
+        if (!isSyncable(filePath))
+            return;
+        // Debounce: if the file changes rapidly (agent writing in chunks),
+        // wait until writes settle before syncing.
+        if (debounceMs > 0) {
+            const existing = debounceTimers.get(filePath);
+            if (existing)
+                clearTimeout(existing);
+            debounceTimers.set(filePath, setTimeout(() => {
+                debounceTimers.delete(filePath);
+                doSync(filePath).catch((err) => log.error("Debounced sync failed", err));
+            }, debounceMs));
+        }
+        else {
+            await doSync(filePath);
+        }
     };
 }
 /**
- * Sync all existing memory files on startup
+ * Sync all existing memory files on startup.
+ * Uses section-level sync when sectionize is enabled.
  */
 export async function syncMemoriesOnStartup(client, workspaceDir, options) {
     log.info("Syncing existing memory files...");
-    const result = await syncAllMemoryFiles(client, workspaceDir, { userId: options?.userId });
-    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 (options?.sectionize) {
+        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.agedOut} aged-out, ${result.removed} removed, ${result.failed} failed`);
+        if (result.failed > 0) {
+            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");
+    else {
+        const result = await syncAllMemoryFiles(client, workspaceDir, {
+            userId: options?.userId,
+        });
+        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/dist/index.js

@@ -104,6 +104,7 @@ export default {
         if (cfg.syncMemories) {
             const fileSyncHandler = buildFileSyncHandler(client, cfg);
             api.on("file_changed", fileSyncHandler);
+            api.logger.info(`hyperspell: memory sync enabled (sectionize=${cfg.syncMemoriesConfig.sectionize}, watchPaths=${cfg.syncMemoriesConfig.watchPaths.length})`);
         }
         // Register memory network tools
         if (cfg.knowledgeGraph.enabled) {
@@ -116,11 +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

@@ -1,10 +1,13 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import * as crypto from "node:crypto";
 import { log } from "../logger.js";
 const FRONTMATTER_REGEX = /^---\n([\s\S]*?)\n---\n?/;
-/**
- * Parse frontmatter from markdown content
- */
+const MANIFEST_VERSION = 1;
+const HASH_FILE_NAME = ".hyperspell-sync-hashes.json";
+// ---------------------------------------------------------------------------
+// Frontmatter helpers (unchanged from original)
+// ---------------------------------------------------------------------------
 function parseFrontmatter(content) {
     const match = content.match(FRONTMATTER_REGEX);
     if (!match) {
@@ -23,16 +26,10 @@ function parseFrontmatter(content) {
     }
     return { frontmatter, body };
 }
-/**
- * Serialize frontmatter back to string
- */
 function serializeFrontmatter(frontmatter) {
     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) {
     try {
         const content = fs.readFileSync(filePath, "utf-8");
@@ -50,9 +47,6 @@ function readMarkdownFile(filePath) {
         return null;
     }
 }
-/**
- * Update the hyperspell_id in the frontmatter of a markdown file
- */
 function updateFrontmatterId(filePath, hyperspellId) {
     try {
         const content = fs.readFileSync(filePath, "utf-8");
@@ -66,9 +60,169 @@ function updateFrontmatterId(filePath, hyperspellId) {
         log.error(`Failed to update frontmatter in ${filePath}`, err);
     }
 }
+// ---------------------------------------------------------------------------
+// Section-level parsing
+// ---------------------------------------------------------------------------
+function contentHash(text) {
+    return crypto.createHash("sha256").update(text.trim()).digest("hex").slice(0, 16);
+}
+/**
+ * Split markdown content into sections delimited by ## headings.
+ * Content before the first ## heading becomes a section titled after the
+ * file-level # heading (or the filename).
+ *
+ * Sections shorter than `minLength` characters are merged into the previous
+ * section to avoid noisy micro-memories.
+ */
+export function parseMarkdownSections(content, fallbackTitle, minLength = 80) {
+    const lines = content.split("\n");
+    const raw = [];
+    let fileTitle = fallbackTitle;
+    let currentSection = null;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // Capture file-level title from # heading
+        if (/^# /.test(line) && currentSection === null) {
+            fileTitle = line.replace(/^# /, "").trim();
+            continue;
+        }
+        // New section on ## heading
+        if (/^## /.test(line)) {
+            if (currentSection) {
+                raw.push(currentSection);
+            }
+            currentSection = {
+                title: line.replace(/^## /, "").trim(),
+                lines: [],
+                startLine: i + 1,
+            };
+            continue;
+        }
+        if (currentSection) {
+            currentSection.lines.push(line);
+        }
+        else {
+            // Content before any ## heading — becomes preamble section
+            if (!raw.length) {
+                currentSection = { title: fileTitle, lines: [line], startLine: i + 1 };
+            }
+        }
+    }
+    if (currentSection) {
+        raw.push(currentSection);
+    }
+    // Merge short sections into the previous one
+    const merged = [];
+    for (const section of raw) {
+        const text = section.lines.join("\n").trim();
+        if (!text)
+            continue;
+        if (text.length < minLength && merged.length > 0) {
+            // Append to previous section
+            const prev = merged[merged.length - 1];
+            prev.content += `\n\n### ${section.title}\n${text}`;
+            prev.contentHash = contentHash(prev.content);
+            prev.endLine = section.startLine + section.lines.length;
+        }
+        else {
+            merged.push({
+                title: section.title,
+                content: text,
+                contentHash: contentHash(text),
+                startLine: section.startLine,
+                endLine: section.startLine + section.lines.length,
+            });
+        }
+    }
+    return merged;
+}
+/**
+ * Section titles key the manifest per file, so two sections sharing the same
+ * ## heading in one file would collide — one resourceId tracked, the other
+ * silently orphaned and re-uploaded on every sync. Disambiguate repeats so
+ * each section maps to a stable, unique key.
+ */
+export function dedupeTitles(sections) {
+    const seen = new Map();
+    return sections.map((s) => {
+        const n = (seen.get(s.title) ?? 0) + 1;
+        seen.set(s.title, n);
+        return n === 1 ? s : { ...s, title: `${s.title} (${n})` };
+    });
+}
+// ---------------------------------------------------------------------------
+// Sync manifest (persisted to workspace, workspace-relative keys)
+// ---------------------------------------------------------------------------
+function manifestPath(workspaceDir) {
+    return path.join(workspaceDir, HASH_FILE_NAME);
+}
+/** Workspace-relative, posix-normalized key so the manifest is portable. */
+export function fileKey(workspaceDir, filePath) {
+    return path.relative(workspaceDir, filePath).split(path.sep).join("/");
+}
+function emptyManifest() {
+    return { version: MANIFEST_VERSION, files: {} };
+}
+export function loadManifest(workspaceDir) {
+    const p = manifestPath(workspaceDir);
+    try {
+        if (fs.existsSync(p)) {
+            const parsed = JSON.parse(fs.readFileSync(p, "utf-8"));
+            // 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 };
+            }
+        }
+    }
+    catch (err) {
+        log.error("Failed to read sync manifest", err);
+    }
+    return emptyManifest();
+}
+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(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 */
+        }
+    }
+}
 /**
- * Get all markdown files from the memory directory, including subdirectories
+ * Serializes manifest read-modify-write across the whole process. Startup bulk
+ * sync and the live file_changed 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.
  */
+let syncChain = Promise.resolve();
+export function withSyncLock(fn) {
+    const run = syncChain.then(fn, fn);
+    syncChain = run.then(() => undefined, () => undefined);
+    return run;
+}
+// ---------------------------------------------------------------------------
+// Public API — file-level sync (original, kept for backward compat)
+// ---------------------------------------------------------------------------
 export function getMemoryFiles(workspaceDir) {
     const memoryDir = path.join(workspaceDir, "memory");
     if (!fs.existsSync(memoryDir)) {
@@ -95,7 +249,47 @@ export function getMemoryFiles(workspaceDir) {
     return results;
 }
 /**
- * Sync a single markdown file to Hyperspell
+ * Collect all syncable files based on configuration.
+ * Includes memory/*.md by default, plus any additional watchPaths.
+ */
+export function getSyncableFiles(workspaceDir, watchPaths) {
+    const files = getMemoryFiles(workspaceDir);
+    if (watchPaths) {
+        for (const wp of watchPaths) {
+            const resolved = wp.startsWith("/") ? wp : path.join(workspaceDir, wp);
+            if (!fs.existsSync(resolved))
+                continue;
+            const stat = fs.statSync(resolved);
+            if (stat.isFile() && resolved.endsWith(".md")) {
+                if (!files.includes(resolved)) {
+                    files.push(resolved);
+                }
+            }
+            else if (stat.isDirectory()) {
+                // Walk directory for .md files
+                const walk = (dir) => {
+                    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") && !files.includes(fullPath)) {
+                                files.push(fullPath);
+                            }
+                        }
+                    }
+                    catch (_err) { /* skip unreadable dirs */ }
+                };
+                walk(resolved);
+            }
+        }
+    }
+    return files;
+}
+/**
+ * Original whole-file sync (kept for backward compatibility when
+ * sectionize is false).
  */
 export async function syncMarkdownFile(client, filePath, options) {
     const file = readMarkdownFile(filePath);
@@ -116,7 +310,6 @@ export async function syncMarkdownFile(client, filePath, options) {
             },
             userId: options?.userId,
         });
-        // Update frontmatter with new resource ID if it changed or was newly created
         if (result.resourceId !== file.hyperspellId) {
             updateFrontmatterId(filePath, result.resourceId);
         }
@@ -128,9 +321,156 @@ export async function syncMarkdownFile(client, filePath, options) {
         return { success: false, error: errorMsg };
     }
 }
+// ---------------------------------------------------------------------------
+// Section-level sync (new)
+// ---------------------------------------------------------------------------
 /**
- * Sync all markdown files in the memory directory
+ * Sync a single markdown file to Hyperspell at section granularity.
+ * Each ## section becomes a separate memory. Content hashes are tracked
+ * so unchanged sections are skipped on subsequent syncs.
+ *
+ * The section title is prepended with the file-level context (e.g.
+ * "2026-05-09 — The day David's mum got sick") for better retrieval.
  */
+export async function syncMarkdownFileSectionized(client, filePath, workspaceDir, options) {
+    return withSyncLock(async () => {
+        const empty = { synced: 0, skipped: 0, failed: 0, removed: 0, errors: [] };
+        try {
+            const file = readMarkdownFile(filePath);
+            if (!file || !file.content) {
+                return file ? empty : { ...empty, errors: ["Failed to read file"] };
+            }
+            const sections = dedupeTitles(parseMarkdownSections(file.content, file.title));
+            if (sections.length === 0) {
+                return empty;
+            }
+            const manifest = loadManifest(workspaceDir);
+            const key = fileKey(workspaceDir, filePath);
+            const prevSections = manifest.files[key]?.sections ?? {};
+            const fileName = path.basename(filePath, ".md");
+            let synced = 0;
+            let skipped = 0;
+            let failed = 0;
+            let removed = 0;
+            let dirty = false;
+            const errors = [];
+            const currentTitles = new Set(sections.map((s) => s.title));
+            // Sections in the manifest but absent from the current parse are either
+            // renames (same content hash resurfacing under a new title) or true
+            // deletions. Index leftovers by content hash so a renamed section can
+            // reclaim its existing Hyperspell resource instead of creating a
+            // duplicate + orphan. Hash collisions among removed sections are rare
+            // and resolved best-effort (last writer wins).
+            const orphanByHash = new Map();
+            for (const [title, rec] of Object.entries(prevSections)) {
+                if (!currentTitles.has(title)) {
+                    orphanByHash.set(rec.hash, { title, resourceId: rec.resourceId });
+                }
+            }
+            const newSections = {};
+            for (const section of sections) {
+                const prev = prevSections[section.title];
+                // Unchanged: keep the record, skip the upload.
+                if (prev && prev.hash === section.contentHash) {
+                    newSections[section.title] = prev;
+                    skipped++;
+                    continue;
+                }
+                // New title: if identical content was just removed under a different
+                // heading, this is a rename — reuse the resource and claim it so it is
+                // not also deleted as an orphan below.
+                let reuseResourceId = prev?.resourceId;
+                if (!prev) {
+                    const renamedFrom = orphanByHash.get(section.contentHash);
+                    if (renamedFrom) {
+                        reuseResourceId = renamedFrom.resourceId;
+                        orphanByHash.delete(section.contentHash);
+                        log.info(`Section renamed: "${renamedFrom.title}" -> "${section.title}" (${fileName}) — updating in place`);
+                    }
+                }
+                const memoryTitle = file.title !== section.title ? `${file.title} — ${section.title}` : section.title;
+                try {
+                    const result = await client.addMemory(section.content, {
+                        title: memoryTitle,
+                        resourceId: reuseResourceId,
+                        collection: "openclaw",
+                        metadata: {
+                            openclaw_source: "memory_sync_section",
+                            file_path: filePath,
+                            file_name: fileName,
+                            section_title: section.title,
+                            content_hash: section.contentHash,
+                        },
+                        userId: options?.userId,
+                    });
+                    newSections[section.title] = {
+                        hash: section.contentHash,
+                        resourceId: result.resourceId,
+                    };
+                    synced++;
+                    dirty = true;
+                    log.info(`Synced section: ${memoryTitle} -> ${result.resourceId}`);
+                }
+                catch (err) {
+                    const errorMsg = err instanceof Error ? err.message : String(err);
+                    errors.push(`${memoryTitle}: ${errorMsg}`);
+                    failed++;
+                    // Preserve the prior record so a transient failure does not drop the
+                    // resourceId and force a duplicate upload next run.
+                    if (prev)
+                        newSections[section.title] = prev;
+                }
+            }
+            // Whatever remains is a genuine deletion: gone from source, no rename
+            // reclaimed it. Delete the remote memory so retrieval does not keep
+            // serving content the user removed.
+            for (const { title, resourceId } of orphanByHash.values()) {
+                if (!resourceId) {
+                    // Never got a resourceId — nothing to delete, just drop the record.
+                    dirty = true;
+                    continue;
+                }
+                const { deleted } = await client.deleteMemory(resourceId, {
+                    userId: options?.userId,
+                });
+                if (deleted) {
+                    removed++;
+                    dirty = true;
+                    log.info(`Removed deleted section "${title}" (${fileName}) -> ${resourceId}`);
+                }
+                else {
+                    // Keep the record so the delete is retried next run rather than
+                    // silently leaking the orphan into the retrieval layer. Count it
+                    // as a failure so the stats are consistent and callers that gate
+                    // logging on `failed > 0` actually surface it.
+                    newSections[title] = prevSections[title];
+                    failed++;
+                    errors.push(`delete "${title}": failed`);
+                }
+            }
+            if (Object.keys(newSections).length > 0) {
+                manifest.files[key] = { sections: newSections };
+            }
+            else {
+                delete manifest.files[key];
+            }
+            if (dirty) {
+                saveManifest(workspaceDir, manifest);
+            }
+            return { synced, skipped, failed, removed, errors };
+        }
+        catch (err) {
+            // The body is defensive everywhere above; this guards the lock chain
+            // against an unexpected throw so one bad file cannot wedge the queue.
+            const msg = err instanceof Error ? err.message : String(err);
+            log.error(`Sectionized sync crashed for ${filePath}`, err);
+            return { ...empty, errors: [msg] };
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// Bulk sync (original whole-file approach)
+// ---------------------------------------------------------------------------
 export async function syncAllMemoryFiles(client, workspaceDir, options) {
     const files = getMemoryFiles(workspaceDir);
     let synced = 0;
@@ -149,3 +489,68 @@ export async function syncAllMemoryFiles(client, workspaceDir, options) {
     }
     return { synced, failed, errors };
 }
+// ---------------------------------------------------------------------------
+// Bulk sync (section-level approach)
+// ---------------------------------------------------------------------------
+/**
+ * Sync all syncable files at section granularity.
+ * Unchanged sections (by content hash) are skipped.
+ */
+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 candidates) {
+        const result = await syncMarkdownFileSectionized(client, filePath, workspaceDir, {
+            userId: options?.userId,
+        });
+        totalSynced += result.synced;
+        totalSkipped += result.skipped;
+        totalFailed += result.failed;
+        totalRemoved += result.removed;
+        allErrors.push(...result.errors);
+    }
+    return {
+        synced: totalSynced,
+        skipped: totalSkipped,
+        failed: totalFailed,
+        removed: totalRemoved,
+        agedOut,
+        errors: allErrors,
+    };
+}

package/openclaw.plugin.json

@@ -71,7 +71,7 @@
 		},
 		"syncMemories": {
 			"label": "Sync Memory Files",
-			"help": "Automatically sync markdown files in workspace/memory/ to Hyperspell",
+			"help": "Automatically sync markdown files to Hyperspell. Set to true for defaults, or use an object for fine-grained control: { sectionize: true, watchPaths: ['MEMORY.md', 'notes/'], debounceMs: 2000 }",
 			"advanced": true
 		},
 		"knowledgeGraph": {
@@ -144,7 +144,30 @@
 				"type": "boolean"
 			},
 			"syncMemories": {
-				"type": "boolean"
+				"oneOf": [
+					{ "type": "boolean" },
+					{
+						"type": "object",
+						"properties": {
+							"enabled": { "type": "boolean" },
+							"sectionize": {
+								"type": "boolean",
+								"description": "Split files by ## headings into separate memories for better retrieval granularity (default: true)"
+							},
+							"watchPaths": {
+								"type": "array",
+								"items": { "type": "string" },
+								"description": "Additional paths to watch beyond memory/ (relative to workspace or absolute)"
+							},
+							"debounceMs": {
+								"type": "number",
+								"minimum": 0,
+								"maximum": 30000,
+								"description": "Debounce file changes in ms to avoid syncing mid-write (default: 2000)"
+							}
+						}
+					}
+				]
 			},
 			"knowledgeGraph": {
 				"type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "type": "module",
   "description": "OpenClaw Hyperspell memory plugin",
   "license": "MIT",
@@ -38,7 +38,7 @@
     "check-types": "tsc --noEmit",
     "lint": "bunx @biomejs/biome ci .",
     "lint:fix": "bunx @biomejs/biome check --write .",
-    "test": "node --test --experimental-strip-types lib/sender.test.ts config.test.ts hooks/auto-trace.test.ts hooks/emotional-state.test.ts hooks/startup-orientation.test.ts"
+    "test": "node --test --experimental-strip-types lib/sender.test.ts config.test.ts sync/markdown.test.ts hooks/auto-trace.test.ts hooks/emotional-state.test.ts hooks/startup-orientation.test.ts"
   },
   "openclaw": {
     "extensions": [