@hyperspell/openclaw-hyperspell 0.13.0 → 0.14.0

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,12 @@ async function runSetup() {
                 autoTrace: { enabled: false, extract: ["procedure"] },
                 emotionalContext: false,
                 syncMemories: true,
+                syncMemoriesConfig: {
+                    enabled: true,
+                    sectionize: true,
+                    watchPaths: [],
+                    debounceMs: 2000,
+                },
                 sources: [],
                 maxResults: 10,
                 relevanceThreshold: 0.6,
@@ -281,19 +287,21 @@ async function runSetup() {
                     recentDays: 7,
                     recentLimit: 5,
                     loopsLimit: 3,
-                    recentQuery: "conversation session interaction",
                     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 {
@@ -553,7 +561,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

@@ -25,6 +25,7 @@ const ALLOWED_KEYS = [
     "debug",
     "knowledgeGraph",
     "multiUser",
+    "dreaming",
 ];
 const VALID_SOURCES = [
     "reddit",
@@ -234,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"], "hyperspell.syncMemories");
+    }
     return {
         apiKey,
         userId: cfg.userId,
@@ -252,11 +269,18 @@ export function parseConfig(raw) {
             recentDays: soRaw.recentDays ?? 7,
             recentLimit: soRaw.recentLimit ?? 5,
             loopsLimit: soRaw.loopsLimit ?? 3,
-            recentQuery: soRaw.recentQuery ?? "conversation session interaction",
             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,
+        },
         sources: parseSources(cfg.sources),
         maxResults: cfg.maxResults ?? 10,
         relevanceThreshold: cfg.relevanceThreshold ?? 0.6,

package/dist/hooks/auto-trace.js

@@ -13,6 +13,8 @@ export function sanitizeTraceText(input) {
     let out = input;
     out = out.replace(/<hyperspell-context>[\s\S]*?<\/hyperspell-context>\n?/g, "");
     out = out.replace(/<hyperspell-emotional-context>[\s\S]*?<\/hyperspell-emotional-context>\n?/g, "");
+    out = out.replace(/<hyperspell-recent-interactions>[\s\S]*?<\/hyperspell-recent-interactions>\n?/g, "");
+    out = out.replace(/<hyperspell-unfinished-loops>[\s\S]*?<\/hyperspell-unfinished-loops>\n?/g, "");
     out = out.replace(/Sender \(untrusted metadata\):\s*```json[\s\S]*?```\n?/g, "");
     out = out.replace(/\[Bootstrap pending\][\s\S]*?(?=\n{2,}|\nSystem:|\nSender|$)/g, "");
     out = out.replace(/\[Startup context loaded by runtime\][\s\S]*?(?:\n\n|$)/g, "");

package/dist/hooks/memory-sync.js

@@ -1,54 +1,134 @@
 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,
+        });
+        log.info(`Section sync complete: ${result.synced} synced, ${result.skipped} unchanged, ${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/hooks/startup-orientation.js

@@ -1,15 +1,23 @@
 import { resolveUser } from "../lib/sender.js";
 import { log } from "../logger.js";
-const RECENT_FILTER = { openclaw_source: "agent_end" };
+const MAX_ATTEMPTS = 2;
+const RECENT_BUFFER_LIMIT = 100;
 /**
- * Track which sessions already received the orientation injection. The block is
- * expensive (two search calls + a few hundred tokens of wrapper) and its
- * contents don't change within a session, so inject-once is the right shape.
- * Lifecycle mirrors the emotional-context hook: first turn injects, later turns
- * skip, `after_compaction` clears (injection may have been trimmed), and
- * `session_end` deletes to keep the Set bounded.
+ * Sessions where the orientation block was already injected (or where we
+ * deliberately decided not to inject — unknown sender, exhausted retries).
+ * Re-checked at the top of every turn; on hit, we skip.
+ *
+ * Lifecycle mirrors the emotional-context hook: `after_compaction` clears
+ * (the original injection may have been trimmed out of history) and
+ * `session_end` cleans up to keep both structures bounded.
  */
 const injectedSessions = new Set();
+/**
+ * Counts attempts for sessions where every call has failed so far. We only
+ * count failures here, so a session that succeeds on retry will never appear.
+ * Capped at MAX_ATTEMPTS — past that we give up and add to injectedSessions.
+ */
+const failedAttempts = new Map();
 function formatRelativeTime(iso) {
     if (!iso)
         return "";
@@ -36,7 +44,7 @@ function formatRecentInteractions(results) {
         return null;
     const lines = results.map((r) => {
         const when = formatRelativeTime(r.createdAt);
-        const title = r.title ?? `[${r.source}]`;
+        const title = r.title || `[${r.source}]`;
         const prefix = when ? `[${when}] ` : "";
         const top = r.highlights[0]?.text?.replace(/\n/g, " ").slice(0, 140);
         const tail = top ? ` — ${top}` : "";
@@ -50,7 +58,7 @@ function formatUnfinishedLoops(results) {
         const top = r.highlights[0];
         if (!top)
             continue;
-        const title = r.title ?? `[${r.source}]`;
+        const title = r.title || `[${r.source}]`;
         bullets.push(`- ${title}: ${top.text.replace(/\n/g, " ")}`);
     }
     return bullets.length > 0 ? bullets.join("\n") : null;
@@ -58,7 +66,7 @@ function formatUnfinishedLoops(results) {
 function isoDaysAgo(days) {
     const d = new Date();
     d.setUTCDate(d.getUTCDate() - days);
-    return d.toISOString();
+    return d;
 }
 /**
  * Resolve the userId to use for personal searches. In multi-user mode, skip
@@ -74,12 +82,73 @@ function personalUserId(cfg, ctx) {
         return { skip: true };
     return { skip: false, userId: resolved.userId };
 }
+/**
+ * Pull recent agent_end traces via listMemories, sorted chronologically.
+ *
+ * Why list, not search: a date-window + relevance search ranks results by
+ * lexical similarity to a generic query, which is approximately random
+ * within a 7-day slice and can easily exclude yesterday in favor of a
+ * 5-day-old session. listMemories gives us true chronological recall.
+ *
+ * The SDK's list endpoint doesn't expose date or metadata filters in our
+ * wrapper, so we filter client-side. Buffer is capped at
+ * RECENT_BUFFER_LIMIT to bound wire cost; if a user has more than that
+ * many traces in the cutoff window we'll still get the newest ones,
+ * since the underlying API returns recency-ordered pages.
+ */
+async function fetchRecentTraces(client, cutoff, limit, userId) {
+    const buffer = [];
+    let scanned = 0;
+    const cutoffMs = cutoff.getTime();
+    for await (const memory of client.listMemories({
+        source: "trace",
+        userId,
+        pageSize: 50,
+    })) {
+        scanned++;
+        if (scanned > RECENT_BUFFER_LIMIT)
+            break;
+        const meta = memory.metadata;
+        if (meta.openclaw_source !== "agent_end")
+            continue;
+        const createdRaw = meta.created_at;
+        if (typeof createdRaw !== "string")
+            continue;
+        const createdMs = new Date(createdRaw).getTime();
+        if (Number.isNaN(createdMs) || createdMs < cutoffMs)
+            continue;
+        buffer.push({
+            resourceId: memory.resourceId,
+            title: memory.title,
+            source: memory.source,
+            score: null,
+            url: null,
+            createdAt: createdRaw,
+            highlights: [],
+        });
+    }
+    buffer.sort((a, b) => {
+        const at = a.createdAt ? new Date(a.createdAt).getTime() : 0;
+        const bt = b.createdAt ? new Date(b.createdAt).getTime() : 0;
+        return bt - at;
+    });
+    return buffer.slice(0, limit);
+}
 export function buildStartupOrientationHandler(client, cfg) {
     const so = cfg.startupOrientation;
     return async (_event, ctx) => {
         const sessionKey = ctx?.sessionKey;
         if (sessionKey && injectedSessions.has(sessionKey))
             return;
+        const tries = (sessionKey && failedAttempts.get(sessionKey)) || 0;
+        if (tries >= MAX_ATTEMPTS) {
+            log.debug(`startup-orientation: giving up after ${tries} failed attempt(s)`);
+            if (sessionKey) {
+                injectedSessions.add(sessionKey);
+                failedAttempts.delete(sessionKey);
+            }
+            return;
+        }
         const { skip, userId } = personalUserId(cfg, ctx);
         if (skip) {
             log.debug("startup-orientation: skipping — unknown sender in multi-user mode");
@@ -87,31 +156,36 @@ export function buildStartupOrientationHandler(client, cfg) {
                 injectedSessions.add(sessionKey);
             return;
         }
-        const after = isoDaysAgo(so.recentDays);
+        const cutoff = isoDaysAgo(so.recentDays);
         const [recentSettled, loopsSettled] = await Promise.allSettled([
-            client.search(so.recentQuery, {
-                limit: so.recentLimit,
-                after,
-                filter: RECENT_FILTER,
-                userId,
-            }),
+            fetchRecentTraces(client, cutoff, so.recentLimit, userId),
             client.search(so.loopsQuery, {
                 limit: so.loopsLimit,
                 userId,
             }),
         ]);
-        const recent = recentSettled.status === "fulfilled" ? recentSettled.value : [];
-        if (recentSettled.status === "rejected") {
-            log.error("startup-orientation: recent search failed", recentSettled.reason);
+        const recentOk = recentSettled.status === "fulfilled";
+        const loopsOk = loopsSettled.status === "fulfilled";
+        const recent = recentOk ? recentSettled.value : [];
+        const loops = loopsOk ? loopsSettled.value : [];
+        if (!recentOk) {
+            log.error("startup-orientation: recent listMemories failed", recentSettled.reason);
         }
-        const loops = loopsSettled.status === "fulfilled" ? loopsSettled.value : [];
-        if (loopsSettled.status === "rejected") {
+        if (!loopsOk) {
             log.error("startup-orientation: loops search failed", loopsSettled.reason);
         }
+        if (!recentOk && !loopsOk) {
+            if (sessionKey)
+                failedAttempts.set(sessionKey, tries + 1);
+            log.debug(`startup-orientation: both calls failed (attempt ${tries + 1}/${MAX_ATTEMPTS}); will retry next turn`);
+            return;
+        }
+        if (sessionKey) {
+            injectedSessions.add(sessionKey);
+            failedAttempts.delete(sessionKey);
+        }
         const recentBody = formatRecentInteractions(recent);
         const loopsBody = formatUnfinishedLoops(loops);
-        if (sessionKey)
-            injectedSessions.add(sessionKey);
         if (!recentBody && !loopsBody) {
             log.debug("startup-orientation: nothing to inject");
             return;
@@ -120,7 +194,7 @@ export function buildStartupOrientationHandler(client, cfg) {
         if (recentBody) {
             blocks.push([
                 "<hyperspell-recent-interactions>",
-                `Your last ${so.recentDays} days of conversations with this user, most-relevant-first. Use for situational continuity — don't quote verbatim.`,
+                `Your last ${so.recentDays} days of conversations with this user, most-recent-first. Use for situational continuity — don't quote verbatim.`,
                 "",
                 recentBody,
                 "</hyperspell-recent-interactions>",
@@ -142,7 +216,11 @@ export function buildStartupOrientationHandler(client, cfg) {
 export function buildStartupOrientationCompactionHandler() {
     return async (_event, ctx) => {
         const sessionKey = ctx?.sessionKey;
-        if (sessionKey && injectedSessions.delete(sessionKey)) {
+        if (!sessionKey)
+            return;
+        const dropped = injectedSessions.delete(sessionKey);
+        failedAttempts.delete(sessionKey);
+        if (dropped) {
             log.debug(`startup-orientation: cache cleared after compaction (session=${sessionKey})`);
         }
     };
@@ -150,7 +228,9 @@ export function buildStartupOrientationCompactionHandler() {
 export function buildStartupOrientationSessionCleanupHandler() {
     return async (_event, ctx) => {
         const sessionKey = ctx?.sessionKey;
-        if (sessionKey)
-            injectedSessions.delete(sessionKey);
+        if (!sessionKey)
+            return;
+        injectedSessions.delete(sessionKey);
+        failedAttempts.delete(sessionKey);
     };
 }

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) {
@@ -121,6 +122,8 @@ export default {
                     const workspaceDir = getWorkspaceDir();
                     await syncMemoriesOnStartup(client, workspaceDir, {
                         userId: cfg.multiUser?.sharedUserId,
+                        sectionize: cfg.syncMemoriesConfig.sectionize,
+                        watchPaths: cfg.syncMemoriesConfig.watchPaths,
                     });
                 }
             },

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,152 @@ 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);
+}
 /**
- * Get all markdown files from the memory directory, including subdirectories
+ * 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"));
+            // 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) {
+                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);
+    try {
+        fs.writeFileSync(p, JSON.stringify(manifest, null, 2));
+    }
+    catch (err) {
+        log.error("Failed to write sync manifest", err);
+    }
+}
+/**
+ * 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 +232,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 +293,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 +304,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 +472,35 @@ 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);
+    let totalSynced = 0;
+    let totalSkipped = 0;
+    let totalFailed = 0;
+    let totalRemoved = 0;
+    const allErrors = [];
+    for (const filePath of files) {
+        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,
+        errors: allErrors,
+    };
+}

package/openclaw.plugin.json

@@ -41,6 +41,11 @@
 			"help": "Maintain emotional continuity across sessions — remembers not just what happened, but how it felt",
 			"advanced": true
 		},
+		"startupOrientation": {
+			"label": "Startup Orientation",
+			"help": "Inject recent-interactions and unfinished-loops blocks once per session at startup. Costs two extra calls + ~500–800 tokens of injection per session; off by default.",
+			"advanced": true
+		},
 		"relationshipId": {
 			"label": "Relationship ID",
 			"placeholder": "partner-anna",
@@ -66,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": {
@@ -117,6 +122,16 @@
 			"relationshipId": {
 				"type": "string"
 			},
+			"startupOrientation": {
+				"type": "object",
+				"properties": {
+					"enabled": { "type": "boolean" },
+					"recentDays": { "type": "number", "minimum": 1, "maximum": 90 },
+					"recentLimit": { "type": "number", "minimum": 1, "maximum": 20 },
+					"loopsLimit": { "type": "number", "minimum": 1, "maximum": 20 },
+					"loopsQuery": { "type": "string" }
+				}
+			},
 			"sources": {
 				"type": "string"
 			},
@@ -129,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.0",
+  "version": "0.14.0",
   "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": [