@hyperspell/openclaw-hyperspell 0.16.0 → 0.17.1

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,21 @@ 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)),
+        chatterQuota: Math.max(0, num(r.chatterQuota, DEFAULT_RANKING.chatterQuota)),
+    };
+}
 function parseSources(raw) {
     if (!raw) {
         return [];
@@ -309,6 +326,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, selectRanked } 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,43 @@ function formatHighlightBullets(results, maxResults, threshold) {
         return null;
     return sections.join("\n\n");
 }
+/**
+ * Format already-SELECTED composite-ranked results (threshold + chatter quota
+ * applied upstream by selectRanked). Highlights are floored at the lower of
+ * (threshold, the result's own base relevance), so we don't hide the very lines
+ * that define a boosted-but-quiet memory.
+ */
+function formatSelected(selected, threshold) {
+    const sections = [];
+    for (const r of selected) {
+        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 === 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>`;
+// A short, CONDITIONAL reminder appended only to a real memory block (not a
+// standing every-turn imperative — that reads as ambient framing and trains
+// search-as-ritual; the agent's own instructions carry the standing rule). The
+// point here is just: what surfaced is a passive match, not all of memory.
+const SEARCH_REMINDER = "This is a passive match, not all of memory — if the answer turns on a specific past decision, promise, name, or something recorded, search for it directly before concluding, and say so plainly if it isn't there.";
+/** Wrap a real memory block. No memory → no injection (caller returns nothing);
+ * the standing search rule lives in the agent's own instructions, not here. */
+function wrapContext(memorySection) {
+    return `<hyperspell-context>\n${INTRO}\n\n${memorySection}\n\n${DISCLAIMER}\n\n${SEARCH_REMINDER}\n</hyperspell-context>`;
 }
 /**
  * Drop results belonging to the CURRENT session. The hot buffer writes the live
@@ -93,17 +127,38 @@ 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);
+                // Threshold + chatter quota applied here, so a high-similarity echo can
+                // inform but never flood (the quota bounds count; the penalty bounds rank).
+                const selected = selectRanked(ranked, cfg.maxResults, cfg.relevanceThreshold, ranking.chatterQuota);
+                formatted = formatSelected(selected, cfg.relevanceThreshold);
+                if (formatted) {
+                    const tally = selected.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 (chatter cap ${ranking.chatterQuota})`);
+                }
+            }
+            else {
+                formatted = formatHighlightBullets(results, cfg.maxResults, cfg.relevanceThreshold);
+                if (formatted)
+                    log.debug(`auto-context: injecting ${results.length} memories`);
+            }
+            // No memory cleared the bar → no injection. The standing "search before you
+            // conclude" rule lives in the agent's own instructions, not an ambient
+            // every-turn banner (which reads as framing and trains search-as-ritual).
             if (!formatted) {
                 log.debug("auto-context: no relevant memories found");
                 return;
             }
-            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,87 @@
+export const DEFAULT_RANKING = {
+    enabled: true,
+    curationBoost: 0.2,
+    chatterPenalty: 0.2,
+    storyBoost: 0.15,
+    storyTerms: [],
+    candidateMultiplier: 3,
+    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;
+/** 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);
+}
+/**
+ * Choose which ranked results to inject: keep those clearing `threshold` on
+ * their composite, cap CHATTER at `chatterQuota` regardless of score (so a
+ * high-similarity echo can inform but never flood — the penalty bounds rank,
+ * the quota bounds count), and stop at `maxResults`.
+ */
+export function selectRanked(ranked, maxResults, threshold, chatterQuota) {
+    const out = [];
+    let chatter = 0;
+    for (const r of ranked) {
+        if (r._composite < threshold)
+            continue;
+        if (r._kind === "chatter") {
+            if (chatter >= chatterQuota)
+                continue;
+            chatter++;
+        }
+        out.push(r);
+        if (out.length >= maxResults)
+            break;
+    }
+    return out;
+}

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, not only when asked — but on content, not as ritual: 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,20 @@
 				"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 },
+					"chatterQuota": { "type": "number", "minimum": 0, "maximum": 20 }
+				}
+			},
 			"debug": {
 				"type": "boolean"
 			},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "type": "module",
   "description": "OpenClaw Hyperspell memory plugin",
   "license": "MIT",
@@ -38,7 +38,7 @@
     "check-types": "tsc --noEmit",
     "lint": "bunx @biomejs/biome ci .",
     "lint:fix": "bunx @biomejs/biome check --write .",
-    "test": "node --test --experimental-strip-types 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": [