@hyperspell/openclaw-hyperspell 0.19.0 → 0.20.0

package/dist/lib/loops-audit.js

@@ -0,0 +1,438 @@
+/**
+ * Pure logic for the unfinished-loops audit
+ * (docs/proposals/04-startup-orientation-loops-tuning.md) — extracted here so
+ * parsing/formatting/summary logic joins the hermetic unit suite while the
+ * live runner (scripts/audit-loops.ts) stays out of `npm test`, mirroring the
+ * lib/eval-matchers.ts + scripts/eval-retrieval.ts split.
+ *
+ * Nothing here touches the network or the production hook: the audit is
+ * read-only observation of what `gatherOrientation`'s loops search returns.
+ */
+/**
+ * Candidate reworded default queries from proposal 04 §3.3 (Candidate A).
+ * These are audit probes only — the shipped default in config.ts is untouched
+ * until a variant graduates via the rubric's paired-day gate.
+ */
+export const CANDIDATE_QUERIES = {
+    a1: "I'll get back to you, still need to, waiting on, didn't finish, let's pick this up later, promised to follow up",
+    a2: "unresolved follow-up: promised, waiting on an answer, blocked, next step, revisit, unfinished task, open question",
+};
+/**
+ * Caps from PR #107's `buildLoopsQuery` sketch
+ * (docs/plans/issue-73-static-loops-query.md) — reproduced here ONLY to
+ * simulate that candidate remedy side by side with the static query. This is
+ * deliberately not imported from production code: #107 is unimplemented by
+ * decision (audit-first), so the simulation owns its own copy of the shape.
+ */
+const LOOPS_TITLE_MAX = 80;
+const LOOPS_TOPICS_MAX = 300;
+/**
+ * Simulate #107's dynamic query: static intent base + recent conversation
+ * titles. Empty titles collapse to exactly the base — same graceful
+ * degradation the candidate specifies.
+ */
+export function deriveDynamicQuery(base, titles) {
+    const topics = [];
+    let used = 0;
+    for (const raw of titles) {
+        const title = raw.replace(/\s+/g, " ").trim().slice(0, LOOPS_TITLE_MAX);
+        if (title.length === 0)
+            continue;
+        if (used + title.length > LOOPS_TOPICS_MAX)
+            break;
+        topics.push(title);
+        used += title.length;
+    }
+    if (topics.length === 0)
+        return base;
+    return `${base} — recent topics: ${topics.join("; ")}`;
+}
+/**
+ * Recover titles from a formatted <hyperspell-recent-interactions> block
+ * (`- [3d ago] Title — snippet` / hot-buffer shape `- Title`). Parsing the
+ * rendered block instead of re-running a private fetch keeps the runner on
+ * gatherOrientation's real output; the trade-off (a title containing " — "
+ * gets truncated) is acceptable for a simulation input and documented in the
+ * rubric.
+ */
+export function titlesFromRecentBlock(recentBlock) {
+    if (!recentBlock)
+        return [];
+    const titles = [];
+    for (const line of recentBlock.split("\n")) {
+        const m = /^- (?:\[[^\]]*\] )?(.*)$/.exec(line);
+        if (!m)
+            continue;
+        const title = m[1].split(" — ")[0].trim();
+        if (title.length > 0)
+            titles.push(title);
+    }
+    return titles;
+}
+export const SIMULATE_NAMES = [
+    "a1",
+    "a2",
+    "dynamic",
+    "after30",
+    "after60",
+];
+/** Parse CLI args; throws with a usable message on anything malformed. */
+export function parseAuditArgs(argv) {
+    const args = { json: false, simulate: [] };
+    const take = (flag, i) => {
+        const v = argv[i];
+        if (v === undefined)
+            throw new Error(`${flag} requires a value`);
+        return v;
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        switch (a) {
+            case "-o": {
+                const fmt = take(a, ++i);
+                if (fmt !== "json")
+                    throw new Error(`unsupported output format "${fmt}" (only: json)`);
+                args.json = true;
+                break;
+            }
+            case "--query":
+                args.query = take(a, ++i);
+                break;
+            case "--limit": {
+                const n = Number(take(a, ++i));
+                if (!Number.isInteger(n) || n < 1)
+                    throw new Error("--limit must be a positive integer");
+                args.limit = n;
+                break;
+            }
+            case "--after":
+                args.after = take(a, ++i);
+                break;
+            case "--user":
+                args.user = take(a, ++i);
+                break;
+            case "--simulate": {
+                for (const name of take(a, ++i).split(",").map((s) => s.trim()).filter(Boolean)) {
+                    if (!SIMULATE_NAMES.includes(name)) {
+                        throw new Error(`unknown --simulate variant "${name}" (known: ${SIMULATE_NAMES.join(", ")})`);
+                    }
+                    args.simulate.push(name);
+                }
+                break;
+            }
+            case "--summary":
+                args.summary = { ledger: take(a, ++i), labels: take(a, ++i) };
+                break;
+            default:
+                throw new Error(`unknown argument "${a}"`);
+        }
+    }
+    return args;
+}
+/** `--after 30` = 30 days before `now`; anything else must parse as a date. */
+export function resolveAfter(value, now = new Date()) {
+    if (/^\d+$/.test(value)) {
+        const d = new Date(now);
+        d.setUTCDate(d.getUTCDate() - Number(value));
+        return d.toISOString();
+    }
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime()))
+        throw new Error(`--after "${value}" is neither a day count nor a date`);
+    return d.toISOString();
+}
+/**
+ * The variant list for one invocation. The first entry is always the audited
+ * primary: named "baseline" only when it is exactly the production values, so
+ * ledger lines can't silently mix overridden runs into the baseline series.
+ */
+export function buildVariants(baseQuery, args, recentTitles, now = new Date()) {
+    const overridden = args.query !== undefined || args.after !== undefined || args.limit !== undefined;
+    const primary = {
+        name: overridden ? "custom" : "baseline",
+        query: baseQuery,
+        ...(args.after ? { after: resolveAfter(args.after, now) } : {}),
+    };
+    const variants = [primary];
+    for (const name of args.simulate) {
+        if (name === "a1" || name === "a2") {
+            variants.push({ name, query: CANDIDATE_QUERIES[name] });
+        }
+        else if (name === "dynamic") {
+            variants.push({ name, query: deriveDynamicQuery(baseQuery, recentTitles) });
+        }
+        else {
+            const days = name === "after30" ? "30" : "60";
+            variants.push({ name, query: baseQuery, after: resolveAfter(days, now) });
+        }
+    }
+    return variants;
+}
+const round4 = (n) => Number(n.toFixed(4));
+export function toAuditRow(r, rank, includeContent) {
+    // Mirror formatUnfinishedLoops: it renders highlights[0] as returned, not
+    // the top-scored highlight, and silently drops no-highlight results.
+    const top = r.highlights[0];
+    return {
+        rank,
+        resourceId: r.resourceId,
+        title: r.title === null ? null : r.title.slice(0, 120),
+        source: r.source,
+        score: r.score === null ? null : round4(r.score),
+        createdAt: r.createdAt,
+        highlightCount: r.highlights.length,
+        rendered: top !== undefined,
+        ...(includeContent && top ? { snippet: top.text.replace(/\s+/g, " ").slice(0, 160) } : {}),
+    };
+}
+/** Count rendered bullets in a formatted loops/recent block. */
+export function countBlockBullets(block) {
+    if (!block)
+        return 0;
+    return block.split("\n").filter((l) => l.startsWith("- ")).length;
+}
+export function buildRunRecord(input) {
+    const rows = input.results.map((r, i) => toAuditRow(r, i + 1, input.includeContent));
+    const renderedCount = rows.filter((r) => r.rendered).length;
+    const blockConsistent = input.gatherLoopsCount === null
+        ? null
+        : input.gatherLoopsCount === input.results.length &&
+            countBlockBullets(input.asInjectedBlock) === renderedCount;
+    return {
+        ts: input.ts,
+        variant: input.variant.name,
+        query: input.variant.query,
+        limit: input.limit,
+        after: input.variant.after ?? null,
+        userId: input.userId ?? null,
+        contentEnabled: input.includeContent,
+        resultCount: rows.length,
+        renderedCount,
+        wastedSlots: rows.length - renderedCount,
+        blockConsistent,
+        results: rows,
+        asInjected: input.includeContent ? input.asInjectedBlock : null,
+    };
+}
+/** Set-diff of surfaced resourceIds, rank order preserved within each list. */
+export function compareVariantSets(baseline, variant) {
+    const baseIds = baseline.results.map((r) => r.resourceId);
+    const varIds = variant.results.map((r) => r.resourceId);
+    const baseSet = new Set(baseIds);
+    const varSet = new Set(varIds);
+    return {
+        overlap: baseIds.filter((id) => varSet.has(id)),
+        onlyBaseline: baseIds.filter((id) => !varSet.has(id)),
+        onlyVariant: varIds.filter((id) => !baseSet.has(id)),
+    };
+}
+/** JSONL with blank lines and `//` comment lines allowed (fixture-file style). */
+export function parseJsonl(text) {
+    const out = [];
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (line.length === 0 || line.startsWith("//"))
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            throw new Error(`invalid JSON on line ${i + 1}`);
+        }
+    }
+    return out;
+}
+export const LOOP_VERDICTS = [
+    "still-open",
+    "resolved",
+    "not-a-loop",
+];
+const labelKey = (ts, variant, resourceId) => `${ts}|${variant}|${resourceId}`;
+function emptyVerdictCounts() {
+    return { "still-open": 0, resolved: 0, "not-a-loop": 0 };
+}
+function dayHitRate(records, labels) {
+    let open = 0;
+    let labeled = 0;
+    for (const rec of records) {
+        for (const row of rec.results) {
+            if (!row.rendered)
+                continue;
+            const label = labels.get(labelKey(rec.ts, rec.variant, row.resourceId));
+            if (!label)
+                continue;
+            labeled++;
+            if (label.verdict === "still-open")
+                open++;
+        }
+    }
+    return labeled === 0 ? null : open / labeled;
+}
+/** Compute the rubric's metrics from ledger records plus hand labels. */
+export function summarizeAudit(records, labels) {
+    const labelIndex = new Map();
+    for (const l of labels)
+        labelIndex.set(labelKey(l.ts, l.variant, l.resourceId), l);
+    const byVariant = new Map();
+    for (const rec of records) {
+        const list = byVariant.get(rec.variant) ?? [];
+        list.push(rec);
+        byVariant.set(rec.variant, list);
+    }
+    const perDay = (recs) => {
+        const days = new Map();
+        for (const rec of recs) {
+            const day = rec.ts.slice(0, 10);
+            const list = days.get(day) ?? [];
+            list.push(rec);
+            days.set(day, list);
+        }
+        return days;
+    };
+    const baselineDays = perDay(byVariant.get("baseline") ?? []);
+    const summaries = [];
+    for (const [variant, recs] of byVariant) {
+        const verdicts = emptyVerdictCounts();
+        const ageDaysByVerdict = {
+            "still-open": [],
+            resolved: [],
+            "not-a-loop": [],
+        };
+        let bullets = 0;
+        let wastedSlots = 0;
+        let labeled = 0;
+        let snippetInsufficient = 0;
+        const seenInRun = new Map();
+        for (const rec of recs) {
+            bullets += rec.renderedCount;
+            wastedSlots += rec.wastedSlots;
+            for (const id of new Set(rec.results.map((r) => r.resourceId))) {
+                seenInRun.set(id, (seenInRun.get(id) ?? 0) + 1);
+            }
+            for (const row of rec.results) {
+                if (!row.rendered)
+                    continue;
+                const label = labelIndex.get(labelKey(rec.ts, rec.variant, row.resourceId));
+                if (!label)
+                    continue;
+                labeled++;
+                verdicts[label.verdict]++;
+                if (label.snippetInsufficient)
+                    snippetInsufficient++;
+                if (row.createdAt) {
+                    const age = (new Date(rec.ts).getTime() - new Date(row.createdAt).getTime()) / 86_400_000;
+                    if (Number.isFinite(age))
+                        ageDaysByVerdict[label.verdict].push(Math.max(0, Math.round(age)));
+                }
+            }
+        }
+        let repeatRate = null;
+        if (recs.length >= 2 && seenInRun.size > 0) {
+            const repeating = [...seenInRun.values()].filter((n) => n > recs.length / 2).length;
+            repeatRate = round4(repeating / seenInRun.size);
+        }
+        let pairedDays = null;
+        let pairedWins = null;
+        if (variant !== "baseline") {
+            pairedDays = 0;
+            pairedWins = 0;
+            for (const [day, dayRecs] of perDay(recs)) {
+                const baseRecs = baselineDays.get(day);
+                if (!baseRecs)
+                    continue;
+                const baseRate = dayHitRate(baseRecs, labelIndex);
+                const varRate = dayHitRate(dayRecs, labelIndex);
+                if (baseRate === null || varRate === null)
+                    continue;
+                pairedDays++;
+                if (varRate > baseRate)
+                    pairedWins++;
+            }
+        }
+        summaries.push({
+            variant,
+            runs: recs.length,
+            bullets,
+            wastedSlots,
+            labeled,
+            verdicts,
+            snippetInsufficient,
+            hitRate: labeled === 0 ? null : round4(verdicts["still-open"] / labeled),
+            repeatRate,
+            ageDaysByVerdict,
+            pairedDays,
+            pairedWins,
+        });
+    }
+    // Baseline first, then alphabetical — stable regardless of ledger order.
+    summaries.sort((a, b) => a.variant === "baseline" ? -1 : b.variant === "baseline" ? 1 : a.variant.localeCompare(b.variant));
+    return summaries;
+}
+function median(values) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+export function formatRunHuman(rec) {
+    const lines = [
+        `=== loops audit — ${rec.variant} ===`,
+        `query: ${JSON.stringify(rec.query)}`,
+        `limit: ${rec.limit}   after: ${rec.after ?? "(none)"}   userId: ${rec.userId ?? "(config default)"}`,
+    ];
+    if (rec.results.length === 0)
+        lines.push("  (no results)");
+    for (const r of rec.results) {
+        const score = r.score === null ? "     —" : r.score.toFixed(4);
+        const when = r.createdAt ? r.createdAt.slice(0, 10) : "          ";
+        const state = r.rendered ? "rendered" : "DROPPED: no highlights (wasted slot)";
+        lines.push(`  ${r.rank}. ${score}  ${when}  ${r.title ?? `[${r.source}]`}  (${r.resourceId})  [${state}]`);
+        if (r.snippet)
+            lines.push(`       ${r.snippet}`);
+    }
+    lines.push(`rendered: ${rec.renderedCount}/${rec.resultCount}   wasted slots: ${rec.wastedSlots}`);
+    if (rec.blockConsistent !== null) {
+        lines.push(rec.blockConsistent
+            ? "as-injected block agrees with the diagnostic search"
+            : "WARNING: as-injected block and diagnostic search DIVERGED — corpus moved between calls; rerun");
+    }
+    if (rec.asInjected)
+        lines.push("", rec.asInjected);
+    else if (rec.blockConsistent !== null && !rec.contentEnabled) {
+        lines.push("(set HYPERSPELL_AUDIT_CONTENT=1 to include snippets + the as-injected block)");
+    }
+    return lines.join("\n");
+}
+export function formatComparisonHuman(variant, cmp) {
+    return [
+        `--- ${variant} vs baseline ---`,
+        `  overlap:       ${cmp.overlap.length === 0 ? "(none)" : cmp.overlap.join(", ")}`,
+        `  only baseline: ${cmp.onlyBaseline.length === 0 ? "(none)" : cmp.onlyBaseline.join(", ")}`,
+        `  only ${variant}: ${cmp.onlyVariant.length === 0 ? "(none)" : cmp.onlyVariant.join(", ")}`,
+    ].join("\n");
+}
+export function formatSummaryHuman(summaries) {
+    const lines = ["loops audit — summary (rubric: docs/loops-audit-rubric.md)", ""];
+    for (const s of summaries) {
+        lines.push(`${s.variant}: ${s.runs} run(s), ${s.bullets} bullet(s), ${s.wastedSlots} wasted slot(s)`);
+        if (s.labeled === 0) {
+            lines.push("  no labeled bullets yet");
+        }
+        else {
+            lines.push(`  hit rate: ${((s.hitRate ?? 0) * 100).toFixed(0)}%  (${s.verdicts["still-open"]} still-open / ${s.labeled} labeled)`, `  verdicts: still-open=${s.verdicts["still-open"]} resolved=${s.verdicts.resolved} not-a-loop=${s.verdicts["not-a-loop"]} snippet-insufficient=${s.snippetInsufficient}`);
+            for (const v of LOOP_VERDICTS) {
+                const m = median(s.ageDaysByVerdict[v]);
+                if (m !== null)
+                    lines.push(`  median age (${v}): ${m}d over ${s.ageDaysByVerdict[v].length} item(s)`);
+            }
+        }
+        if (s.repeatRate !== null)
+            lines.push(`  repeat rate: ${(s.repeatRate * 100).toFixed(0)}% of surfaced ids appear in >half the runs`);
+        if (s.pairedDays !== null)
+            lines.push(`  paired days vs baseline: ${s.pairedWins}/${s.pairedDays} win(s)`);
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd();
+}

package/dist/lib/ranking.js

@@ -8,6 +8,38 @@ export const DEFAULT_RANKING = {
     chatterQuota: 2,
 };
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+// Compiled story-term matchers, cached per storyTerms array instance — the
+// config array is built once in parseConfig and stable for the process
+// lifetime, so this avoids per-result regex compilation on the hot path.
+const matcherCache = new WeakMap();
+/**
+ * One regex per term, anchored at word boundaries so short terms can't
+ * false-positive inside longer words ("ada" no longer matches "adaptation";
+ * "mira" no longer matches "admiral"). Boundaries are word↔non-word
+ * transitions, so possessives and punctuation still match: "mira" hits
+ * "Mira's" and "mira-class". `\b` only anchors against word characters, so
+ * terms whose edges are punctuation get no anchor there and still match.
+ */
+function storyMatchers(storyTerms) {
+    let ms = matcherCache.get(storyTerms);
+    if (!ms) {
+        ms = storyTerms
+            .map((t) => t.trim().toLowerCase())
+            .filter((t) => t.length > 0)
+            .map((term) => {
+            const lead = /^\w/.test(term) ? "\\b" : "";
+            const tail = /\w$/.test(term) ? "\\b" : "";
+            return new RegExp(`${lead}${escapeRe(term)}${tail}`);
+        });
+        matcherCache.set(storyTerms, ms);
+    }
+    return ms;
+}
+/** Count ranked results by kind — the debug-tally shape auto-context logs. */
+export function kindTally(results) {
+    return results.reduce((acc, r) => ((acc[r._kind] = (acc[r._kind] ?? 0) + 1), acc), {});
+}
 /** Highest available relevance for a result (doc score or its best highlight). */
 export function baseScore(r) {
     const topHighlight = r.highlights.reduce((m, h) => Math.max(m, h.score ?? 0), 0);
@@ -25,8 +57,11 @@ export function baseScore(r) {
 export function classifyResult(r, storyTerms) {
     const title = (r.title ?? "").trim();
     if (storyTerms.length > 0) {
-        const hay = `${title} ${r.highlights.map((h) => h.text).join(" ")}`.toLowerCase();
-        if (storyTerms.some((t) => t && hay.includes(t.toLowerCase())))
+        // \n-joined (not space-joined) so a multi-word phrase term can never
+        // spuriously match across the seam of two unrelated highlights (terms are
+        // escaped literals, so a phrase's inner space cannot match the \n).
+        const hay = `${title}\n${r.highlights.map((h) => h.text).join("\n")}`.toLowerCase();
+        if (storyMatchers(storyTerms).some((re) => re.test(hay)))
             return "story";
     }
     const untitled = title === "" || /^unnamed conversation$/i.test(title);

package/dist/logger.js

@@ -19,6 +19,22 @@ export const log = {
             _logger.debug(`hyperspell: ${message}`, ...args);
         }
     },
+    /**
+     * Operator-meaningful diagnostics (one line per event: injection summaries,
+     * cut attribution, ranked tallies). Emits via the host's INFO channel when the
+     * plugin's own `debug: true` is set, and stays silent otherwise.
+     *
+     * Why not `debug`: the host drops plugin debug-channel output from gateway.log
+     * even at `logging.level: "debug"` (issue #118 — 2,026 info lines vs zero debug
+     * lines, live). The plugin's `debug` flag is explicit operator intent, so these
+     * diagnostics must not depend on host debug-channel plumbing. Truly-verbose
+     * output (per-request dumps, per-candidate lines) stays on `debug`.
+     */
+    diag: (message, ...args) => {
+        if (_debug) {
+            _logger.info(`hyperspell: ${message}`, ...args);
+        }
+    },
     debugRequest: (method, params) => {
         if (_debug) {
             _logger.debug(`hyperspell: [${method}] request`, params);

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/openclaw.plugin.json

@@ -2,7 +2,7 @@
 	"id": "openclaw-hyperspell",
 	"name": "Hyperspell",
 	"description": "Context and memory for your AI agents — search across Notion, Slack, Google Drive, and more",
-	"version": "0.19.0",
+	"version": "0.20.0",
 	"kind": "memory",
 	"contracts": {
 		"tools": [
@@ -75,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.19.0",
+  "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 lib/eval-matchers.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 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"
+    "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": [