@hyperspell/openclaw-hyperspell 0.16.0 → 0.17.0

package/dist/commands/setup.js

@@ -6,6 +6,7 @@ import * as p from "@clack/prompts";
 import Hyperspell from "hyperspell";
 import { syncAllFilesSectionized, syncAllMemoryFiles, getMemoryFiles, } from "../sync/markdown.js";
 import { openInBrowser } from "../lib/browser.js";
+import { DEFAULT_RANKING } from "../lib/ranking.js";
 import { HyperspellClient } from "../client.js";
 import { getWorkspaceDir, parseConfig, resolveConfigPath } from "../config.js";
 import { buildExtractionPrompt, CRON_JOB_NAME } from "../graph/cron.js";
@@ -288,6 +289,7 @@ async function runSetup() {
                 sources: [],
                 maxResults: 10,
                 relevanceThreshold: 0.6,
+                ranking: DEFAULT_RANKING,
                 debug: false,
                 knowledgeGraph: { enabled: false, scanIntervalMinutes: 60, batchSize: 20 },
                 startupOrientation: {

package/dist/config.js

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { DEFAULT_RANKING } from "./lib/ranking.js";
 /**
  * Convert user-facing scope names (which may contain hyphens) to SDK-safe
  * metadata values (alphanumeric + underscore only). Must be applied at every
@@ -23,6 +24,7 @@ const ALLOWED_KEYS = [
     "sources",
     "maxResults",
     "relevanceThreshold",
+    "ranking",
     "debug",
     "knowledgeGraph",
     "multiUser",
@@ -58,6 +60,20 @@ function resolveEnvVars(value) {
         return envValue;
     });
 }
+function parseRanking(raw) {
+    const r = (raw ?? {});
+    const num = (v, d) => (typeof v === "number" ? v : d);
+    return {
+        enabled: r.enabled ?? DEFAULT_RANKING.enabled,
+        curationBoost: num(r.curationBoost, DEFAULT_RANKING.curationBoost),
+        chatterPenalty: num(r.chatterPenalty, DEFAULT_RANKING.chatterPenalty),
+        storyBoost: num(r.storyBoost, DEFAULT_RANKING.storyBoost),
+        storyTerms: Array.isArray(r.storyTerms)
+            ? r.storyTerms.map((t) => String(t)).filter((t) => t.length > 0)
+            : DEFAULT_RANKING.storyTerms,
+        candidateMultiplier: Math.max(1, num(r.candidateMultiplier, DEFAULT_RANKING.candidateMultiplier)),
+    };
+}
 function parseSources(raw) {
     if (!raw) {
         return [];
@@ -309,6 +325,7 @@ export function parseConfig(raw) {
         sources: parseSources(cfg.sources),
         maxResults: cfg.maxResults ?? 10,
         relevanceThreshold: cfg.relevanceThreshold ?? 0.6,
+        ranking: parseRanking(cfg.ranking),
         debug: cfg.debug ?? false,
         knowledgeGraph: {
             enabled: kgRaw.enabled ?? false,

package/dist/hooks/auto-context.js

@@ -1,5 +1,6 @@
 import { buildScopeFilter, getCanReadScopes, resolveUser, } from "../lib/sender.js";
 import { excludeFilterFor, mergeWithExclude } from "../lib/filters.js";
+import { rerank } from "../lib/ranking.js";
 import { classifySearchError, logSearchError } from "../lib/search-error.js";
 import { resolveCurrentSessionId } from "../lib/session.js";
 import { log } from "../logger.js";
@@ -51,10 +52,52 @@ function formatHighlightBullets(results, maxResults, threshold) {
         return null;
     return sections.join("\n\n");
 }
+/**
+ * Like formatHighlightBullets, but for composite-RANKED results: a result is
+ * kept on its composite score (relevance + curation/story boost − chatter), not
+ * raw relevance — so a deliberately-kept memory that's quietly relevant clears
+ * the bar where a louder conversation echo doesn't. Highlights are floored at
+ * the lower of (threshold, the result's own base relevance), so we don't then
+ * hide the very lines that define a boosted-but-quiet memory.
+ */
+function formatRankedBullets(ranked, maxResults, threshold) {
+    const sections = [];
+    for (const r of ranked) {
+        if (r._composite < threshold)
+            continue;
+        const hiFloor = Math.min(threshold, r._base);
+        const chosen = [...r.highlights]
+            .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
+            .filter((h) => (h.score ?? 0) >= hiFloor)
+            .slice(0, 2);
+        if (chosen.length === 0)
+            continue;
+        const title = r.title ?? `[${r.source}]`;
+        const bullets = chosen
+            .map((h) => `- ${h.text.replace(/\n/g, " ")} [${Math.round((h.score ?? 0) * 100)}%]`)
+            .join("\n");
+        sections.push(`### ${title} (resource_id: ${r.resourceId}, source: ${r.source})\n\n${bullets}`);
+        if (sections.length >= maxResults)
+            break;
+    }
+    if (sections.length === 0)
+        return null;
+    return sections.join("\n\n");
+}
 const INTRO = "The following is surfaced from the user's memory and connected sources, including past conversations. Reference it as recalled context, only when relevant to the conversation.";
 const DISCLAIMER = "Draw on it when relevant — including indirect connections — but don't force it into every response or make assumptions beyond what's stated.";
-function wrapSingle(body) {
-    return `<hyperspell-context>\n${INTRO}\n\n${body}\n\n${DISCLAIMER}\n</hyperspell-context>`;
+// Injected EVERY turn (even when nothing cleared the bar): this passive match is
+// a starting point, not the whole of memory. The point is to make her LOOK —
+// actively search before concluding — rather than answer from whatever happened
+// to surface, which is what lets an agent invent instead of recall.
+const SEARCH_DIRECTIVE = "This is a passive match and may miss what matters. Before answering anything that touches your shared history, a past decision, a name, a promise, or something you may have recorded, run hyperspell_search with a specific query and look — even if something is already shown above. Don't answer from impression when you can check. If a search returns nothing, say so plainly; never fill the gap with something invented.";
+/** Wrap the per-turn context: the standing search directive always, plus the
+ * surfaced memory when anything cleared the bar. */
+function wrapContext(memorySection) {
+    if (memorySection) {
+        return `<hyperspell-context>\n${INTRO}\n\n${memorySection}\n\n${DISCLAIMER}\n\n${SEARCH_DIRECTIVE}\n</hyperspell-context>`;
+    }
+    return `<hyperspell-context>\n${SEARCH_DIRECTIVE}\n</hyperspell-context>`;
 }
 /**
  * Drop results belonging to the CURRENT session. The hot buffer writes the live
@@ -93,17 +136,35 @@ export function buildAutoContextHandler(client, cfg) {
         // Single-user path — preserves main's highlights + threshold behavior
         log.debug(`auto-context: searching for "${prompt.slice(0, 50)}..."`);
         try {
-            const results = dropCurrentSession(await client.search(prompt, {
-                limit: cfg.maxResults,
-                filter: excludeFilterFor(cfg),
-            }), currentSessionId);
-            const formatted = formatHighlightBullets(results, cfg.maxResults, cfg.relevanceThreshold);
+            const ranking = cfg.ranking;
+            // When composite ranking is on, fetch a WIDER candidate pool so quiet-but-
+            // true memory is present to be re-ranked, not cut off below the fetch limit.
+            const limit = ranking.enabled
+                ? cfg.maxResults * ranking.candidateMultiplier
+                : cfg.maxResults;
+            const results = dropCurrentSession(await client.search(prompt, { limit, filter: excludeFilterFor(cfg) }), currentSessionId);
+            let formatted;
+            if (ranking.enabled) {
+                const ranked = rerank(results, ranking);
+                formatted = formatRankedBullets(ranked, cfg.maxResults, cfg.relevanceThreshold);
+                if (formatted) {
+                    const kept = ranked.filter((r) => r._composite >= cfg.relevanceThreshold);
+                    const tally = kept.slice(0, cfg.maxResults).reduce((acc, r) => ((acc[r._kind] = (acc[r._kind] ?? 0) + 1), acc), {});
+                    log.debug(`auto-context: injecting (ranked) ${JSON.stringify(tally)} from ${results.length} candidates`);
+                }
+            }
+            else {
+                formatted = formatHighlightBullets(results, cfg.maxResults, cfg.relevanceThreshold);
+                if (formatted)
+                    log.debug(`auto-context: injecting ${results.length} memories`);
+            }
+            // Always inject the standing search directive so she's prompted to LOOK
+            // every turn — with the surfaced memory appended when anything cleared the
+            // bar. (#issue: passive injection alone let her answer from impression.)
             if (!formatted) {
-                log.debug("auto-context: no relevant memories found");
-                return;
+                log.debug("auto-context: nothing cleared the bar — injecting search directive only");
             }
-            log.debug(`auto-context: injecting ${results.length} memories`);
-            return { prependContext: wrapSingle(formatted) };
+            return { prependContext: wrapContext(formatted) };
         }
         catch (err) {
             // A transient backend throttle (429 / Retry-After) must not be swallowed

package/dist/lib/ranking.js

@@ -0,0 +1,63 @@
+export const DEFAULT_RANKING = {
+    enabled: true,
+    curationBoost: 0.2,
+    chatterPenalty: 0.2,
+    storyBoost: 0.15,
+    storyTerms: [],
+    candidateMultiplier: 3,
+};
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** 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);
+    return Math.max(r.score ?? 0, topHighlight);
+}
+/**
+ * Classify a result by what KIND of memory it is — using only fields the search
+ * already returns (title shape + resource id), so no extra round-trip:
+ *  - story:   matches a configured story term (manuscript / its notes & threads)
+ *  - chatter: untitled or "Unnamed Conversation" AND keyed by a bare session
+ *             UUID — i.e. a hot-buffer conversation fragment (the dreamy echoes)
+ *  - curated: has a real, human title and is not a raw session row — a journal,
+ *             a writing note, a synced memory section (deliberately kept)
+ */
+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())))
+            return "story";
+    }
+    const untitled = title === "" || /^unnamed conversation$/i.test(title);
+    if (untitled && UUID_RE.test(r.resourceId))
+        return "chatter";
+    if (title !== "" && !UUID_RE.test(r.resourceId))
+        return "curated";
+    return "other";
+}
+/** Composite score + classification for one result. */
+export function scoreResult(r, w) {
+    const kind = classifyResult(r, w.storyTerms);
+    const base = baseScore(r);
+    let composite = base;
+    if (kind === "story")
+        composite += w.storyBoost + w.curationBoost; // the story is kept memory too
+    else if (kind === "curated")
+        composite += w.curationBoost;
+    else if (kind === "chatter")
+        composite -= w.chatterPenalty;
+    return { kind, base, composite };
+}
+/** Re-rank results by composite score (descending). Pure; stable enough. */
+export function rerank(results, w) {
+    return results
+        .map((r) => {
+        const s = scoreResult(r, w);
+        return Object.assign({}, r, {
+            _kind: s.kind,
+            _base: s.base,
+            _composite: s.composite,
+        });
+    })
+        .sort((a, b) => b._composite - a._composite);
+}

package/dist/tools/search.js

@@ -12,7 +12,7 @@ export function createSearchToolFactory(client, cfg) {
     return (ctx) => ({
         name: "hyperspell_search",
         label: "Memory Search",
-        description: "Search the user's long-term memory and connected sources for anything not already in the current conversation. Covers: saved memories and notes; past conversations — including ones from earlier or parallel sessions you have no transcript for; and connected sources (Notion, Slack, Gmail, Google Drive, etc.). Reach for this whenever the user refers to something from before, asks what was said / decided / remembered, or when relevant context likely exists but isn't in front of you — search before concluding you don't know.",
+        description: "Search the user's long-term memory and connected sources: saved memories and notes; past conversations — including earlier or parallel sessions you have no transcript for; and connected sources (Notion, Slack, Gmail, Google Drive, etc.). Use this PROACTIVELY and by default, as a routine step — not only when asked. Before answering anything that touches the user's history, a past decision, a name, a promise, or something you might have recorded, search FIRST with a specific query and look. Don't answer from impression when you can check. If a search comes back empty, say so plainly — never fill the gap with something invented.",
         parameters: Type.Object({
             query: Type.String({ description: "Search query" }),
             limit: Type.Optional(Type.Number({ description: "Max results (default: 5)" })),

package/openclaw.plugin.json

@@ -154,6 +154,19 @@
 				"minimum": 1,
 				"maximum": 20
 			},
+			"ranking": {
+				"type": "object",
+				"additionalProperties": false,
+				"description": "Composite retrieval ranking — rank memories by more than raw relevance so kept memory (notes, journals, the active story) surfaces above auto-saved conversation fragments.",
+				"properties": {
+					"enabled": { "type": "boolean" },
+					"curationBoost": { "type": "number", "minimum": 0, "maximum": 1 },
+					"chatterPenalty": { "type": "number", "minimum": 0, "maximum": 1 },
+					"storyBoost": { "type": "number", "minimum": 0, "maximum": 1 },
+					"storyTerms": { "type": "array", "items": { "type": "string" } },
+					"candidateMultiplier": { "type": "number", "minimum": 1, "maximum": 10 }
+				}
+			},
 			"debug": {
 				"type": "boolean"
 			},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.16.0",
+  "version": "0.17.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 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"
+    "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/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"
   },
   "openclaw": {
     "extensions": [