@hyperspell/openclaw-hyperspell 0.18.1 → 0.20.0

package/dist/sync/markdown.js

@@ -40,6 +40,7 @@ function readMarkdownFile(filePath) {
             title,
             content: body.trim(),
             hyperspellId: frontmatter.hyperspell_id || null,
+            graphEntity: frontmatter.graph_entity === "true",
         };
     }
     catch (err) {
@@ -271,6 +272,39 @@ export function getMemoryFiles(workspaceDir, ignorePaths) {
     walk(memoryDir);
     return results;
 }
+/** Resolve a watchPath (workspace-relative or absolute) to an absolute path. */
+export function resolveWatchPath(workspaceDir, p) {
+    return path.isAbsolute(p) ? p : path.join(workspaceDir, p);
+}
+/** Slug for unlabeled watchPaths: "notes/brainstem" -> "notes_brainstem". */
+function watchPathSlug(workspaceDir, resolved) {
+    const rel = path.relative(workspaceDir, resolved);
+    const base = rel.startsWith("..") ? path.basename(resolved) : rel;
+    return base.split(path.sep).join("_").replace(/[^a-zA-Z0-9_]/g, "_");
+}
+/**
+ * Provenance for a syncable file: the longest-prefix-matching watchPath's
+ * label (explicit `source` or derived slug), else "memory" for memory/ files.
+ * Longest prefix wins so a watchPath nested inside another (or inside memory/)
+ * keeps its more specific label.
+ */
+export function resolveSyncSource(filePath, workspaceDir, watchPaths) {
+    let best;
+    for (const wp of watchPaths) {
+        const resolved = resolveWatchPath(workspaceDir, wp.path);
+        if (filePath === resolved || filePath.startsWith(resolved + path.sep)) {
+            if (!best || resolved.length > best.len) {
+                best = { len: resolved.length, label: wp.source ?? watchPathSlug(workspaceDir, resolved) };
+            }
+        }
+    }
+    if (best)
+        return best.label;
+    const memoryDir = path.join(workspaceDir, "memory");
+    if (filePath.startsWith(memoryDir + path.sep))
+        return "memory";
+    return undefined;
+}
 /**
  * Collect all syncable files based on configuration.
  * Includes memory/*.md by default, plus any additional watchPaths.
@@ -280,7 +314,7 @@ export function getSyncableFiles(workspaceDir, watchPaths, ignorePaths) {
     const files = getMemoryFiles(workspaceDir, ignorePaths);
     if (watchPaths) {
         for (const wp of watchPaths) {
-            const resolved = wp.startsWith("/") ? wp : path.join(workspaceDir, wp);
+            const resolved = resolveWatchPath(workspaceDir, wp.path);
             if (!fs.existsSync(resolved))
                 continue;
             const stat = fs.statSync(resolved);
@@ -333,6 +367,13 @@ export async function syncMarkdownFile(client, filePath, options) {
             metadata: {
                 openclaw_source: "memory_sync",
                 file_path: filePath,
+                // Content origin (memory/ vs a labeled watchPath). Additive key —
+                // openclaw_source stays the pipeline discriminator that retrieval
+                // filters and startup-orientation dedupe depend on.
+                ...(options?.syncSource ? { openclaw_sync_source: options.syncSource } : {}),
+                // Honor the extraction prompt's contract: entity files synced back
+                // to Hyperspell must be skippable by the Memory Network scan.
+                ...(file.graphEntity ? { graph_entity: "true" } : {}),
             },
             userId: options?.userId,
         });
@@ -426,6 +467,14 @@ export async function syncMarkdownFileSectionized(client, filePath, workspaceDir
                             file_name: fileName,
                             section_title: section.title,
                             content_hash: section.contentHash,
+                            // Content origin (memory/ vs a labeled watchPath). Additive key —
+                            // openclaw_source stays the pipeline discriminator that retrieval
+                            // filters and startup-orientation dedupe depend on.
+                            ...(options?.syncSource ? { openclaw_sync_source: options.syncSource } : {}),
+                            // Honor the extraction prompt's contract: entity files synced
+                            // back to Hyperspell must be skippable by the Memory Network
+                            // scan, or the extractor is re-fed its own output every cycle.
+                            ...(file.graphEntity ? { graph_entity: "true" } : {}),
                         },
                         userId: options?.userId,
                     });
@@ -503,7 +552,12 @@ export async function syncAllMemoryFiles(client, workspaceDir, options) {
     let failed = 0;
     const errors = [];
     for (const filePath of files) {
-        const result = await syncMarkdownFile(client, filePath, { userId: options?.userId });
+        // Legacy bulk mode only walks memory/, so everything it uploads is
+        // memory-origin by construction.
+        const result = await syncMarkdownFile(client, filePath, {
+            userId: options?.userId,
+            syncSource: "memory",
+        });
         if (result.success) {
             synced++;
             log.info(`Synced: ${path.basename(filePath)} -> ${result.resourceId}`);
@@ -564,6 +618,7 @@ export async function syncAllFilesSectionized(client, workspaceDir, options) {
     for (const filePath of candidates) {
         const result = await syncMarkdownFileSectionized(client, filePath, workspaceDir, {
             userId: options?.userId,
+            syncSource: resolveSyncSource(filePath, workspaceDir, options?.watchPaths ?? []),
         });
         totalSynced += result.synced;
         totalSkipped += result.skipped;

package/dist/tools/emotional-arc.js

@@ -0,0 +1,60 @@
+import { Type } from "@sinclair/typebox";
+import { buildEmotionalContext, EMOTIONAL_ARC_LIMIT, fetchRecentOrLatest, looksLikeRawTranscript, } from "../hooks/emotional-state.js";
+import { log } from "../logger.js";
+/** Hard cap so the agent can't ask the backend for an unbounded history. */
+const MAX_ARC_LIMIT = 10;
+export function createEmotionalArcToolFactory(client, cfg) {
+    // No sender context needed: the register is keyed to cfg.relationshipId, not
+    // the current speaker — but keep the factory signature so toolUnlessQuarantined
+    // can wrap it like search/remember.
+    return (_ctx) => ({
+        name: "hyperspell_emotional_arc",
+        label: "Emotional Arc",
+        description: "Fetch the recent emotional arc of your relationship with this user — the same emotional-context block that is injected at session start. Use it when that block is no longer in your history (e.g. after the conversation was compacted) or when you genuinely want to reflect on how the relationship has been feeling before responding. Returns the most recent emotional registers, newest first. Let the trajectory inform your tone — don't recite it back to the user.",
+        parameters: Type.Object({
+            limit: Type.Optional(Type.Number({
+                description: `How many recent registers to fetch (default ${EMOTIONAL_ARC_LIMIT}, max ${MAX_ARC_LIMIT})`,
+            })),
+        }),
+        async execute(_toolCallId, params) {
+            const limit = Math.min(Math.max(Math.floor(params.limit ?? EMOTIONAL_ARC_LIMIT), 1), MAX_ARC_LIMIT);
+            log.debug(`emotional-arc tool: limit=${limit} relationshipId=${cfg.relationshipId ?? "(default)"}`);
+            try {
+                const states = await fetchRecentOrLatest(client, cfg, limit);
+                // Same placeholder filter as the injection path: for ~10s after a
+                // store, the register can be the RAW input transcript (status=pending),
+                // not a distilled feeling. Returning that would pollute tone.
+                const usable = states.filter((s) => s.summary && !looksLikeRawTranscript(s.summary));
+                if (usable.length === 0) {
+                    const text = states.length > 0
+                        ? "The latest emotional register is still being extracted — try again in a few seconds."
+                        : "No emotional arc recorded yet for this relationship. It builds up as real conversations end.";
+                    return { content: [{ type: "text", text }] };
+                }
+                // Deliberately identical to the session-start injection block
+                // (buildEmotionalContext), so a post-compaction re-fetch restores
+                // exactly what a fresh session would have received. Mood weather is
+                // intentionally NOT included — it is an injection-only session
+                // override, rolled at most once per session; a tool call must never
+                // re-roll or reveal it (do not import from mood-weather.ts here).
+                return {
+                    content: [
+                        { type: "text", text: buildEmotionalContext(usable) },
+                    ],
+                    details: { count: usable.length },
+                };
+            }
+            catch (err) {
+                log.error("emotional-arc tool failed", err);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Failed to fetch emotional arc: ${err instanceof Error ? err.message : String(err)}`,
+                        },
+                    ],
+                };
+            }
+        },
+    });
+}

package/dist/tools/remember.js

@@ -1,4 +1,5 @@
 import { Type } from "@sinclair/typebox";
+import { channelIdFromCtx } from "../lib/exclude-channels.js";
 import { getDefaultWriteScope, resolveRole, resolveUser, routeWrite, } from "../lib/sender.js";
 import { resolveCurrentSessionId } from "../lib/session.js";
 import { isMultiSpeaker } from "../lib/speaker-tracker.js";
@@ -85,12 +86,19 @@ export function createRememberToolFactory(client, cfg) {
                 userId = resolved?.userId;
             }
             log.debug(`remember tool: "${params.text.slice(0, 50)}..." date=${params.date ?? "now"} userId=${userId} scope=${scope}`);
+            // Tag with the originating conversation so purge-channel can find this
+            // memory if the channel is quarantined later (the tool is already
+            // suppressed in channels that are quarantined NOW).
+            const channelId = channelIdFromCtx(ctx);
             try {
                 await client.addMemory(params.text, {
                     title: params.title,
                     date: params.date,
                     collection,
-                    metadata: { source: "openclaw_tool" },
+                    metadata: {
+                        source: "openclaw_tool",
+                        ...(channelId ? { openclaw_channel_id: channelId } : {}),
+                    },
                     userId,
                     scope: scopingEnabled ? scope : undefined,
                 });

package/openclaw.plugin.json

@@ -2,12 +2,13 @@
 	"id": "openclaw-hyperspell",
 	"name": "Hyperspell",
 	"description": "Context and memory for your AI agents — search across Notion, Slack, Google Drive, and more",
-	"version": "0.13.0",
+	"version": "0.20.0",
 	"kind": "memory",
 	"contracts": {
 		"tools": [
 			"hyperspell_search",
 			"hyperspell_remember",
+			"hyperspell_emotional_arc",
 			"hyperspell_network_scan",
 			"hyperspell_network_write",
 			"hyperspell_network_complete"
@@ -48,7 +49,7 @@
 		},
 		"excludeChannels": {
 			"label": "Excluded Channels",
-			"help": "Conversation/channel ids fully quarantined from memory: no context injection, no memory writes, no memory tools in those sessions. Threads inside an excluded channel inherit the quarantine.",
+			"help": "Conversation/channel ids fully quarantined from memory: no context injection, no memory writes, no memory tools in those sessions. Threads inside an excluded channel inherit the quarantine. Forward-only; already-synced content is not removed (see purge-channel CLI command).",
 			"advanced": true
 		},
 		"startupOrientation": {
@@ -74,6 +75,11 @@
 			"help": "Maximum memories injected into context per turn",
 			"advanced": true
 		},
+		"ranking": {
+			"label": "Composite Ranking",
+			"help": "Rank memories by more than raw relevance: boost curated memory and the active story, penalize auto-saved conversation fragments. Set storyTerms to 3-15 distinctive names/terms of the active thread (characters, codenames, invented words; matched case-insensitively at word boundaries) so it outranks chatter; update the list when the active story changes. { enabled, storyTerms, curationBoost, storyBoost, chatterPenalty, candidateMultiplier, chatterQuota }",
+			"advanced": true
+		},
 		"debug": {
 			"label": "Debug Logging",
 			"help": "Enable verbose debug logs for API calls and responses",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.18.1",
+  "version": "0.20.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 client.test.ts lib/sender.test.ts lib/filters.test.ts lib/search-error.test.ts lib/session.test.ts lib/exclude-channels.test.ts lib/ranking.test.ts tools/search.test.ts config.test.ts sync/markdown.test.ts hooks/auto-trace.test.ts hooks/auto-context.test.ts hooks/hot-buffer.test.ts hooks/emotional-state.test.ts hooks/startup-orientation.test.ts hooks/mood-weather.test.ts"
+    "test": "node --test --experimental-strip-types client.test.ts logger.test.ts lib/sender.test.ts lib/filters.test.ts lib/search-error.test.ts lib/session.test.ts lib/exclude-channels.test.ts lib/ranking.test.ts lib/eval-matchers.test.ts lib/loops-audit.test.ts tools/search.test.ts tools/emotional-arc.test.ts commands/preview.test.ts commands/purge-channel.test.ts config.test.ts sync/markdown.test.ts graph/ops.test.ts hooks/auto-trace.test.ts hooks/auto-context.test.ts hooks/hot-buffer.test.ts hooks/emotional-state.test.ts hooks/startup-orientation.test.ts hooks/mood-weather.test.ts eval/eval.test.ts"
   },
   "openclaw": {
     "extensions": [