@hyperspell/openclaw-hyperspell 0.17.0 → 0.17.1

package/dist/config.js

@@ -72,6 +72,7 @@ function parseRanking(raw) {
             ? 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) {

package/dist/hooks/auto-context.js

@@ -1,6 +1,6 @@
 import { buildScopeFilter, getCanReadScopes, resolveUser, } from "../lib/sender.js";
 import { excludeFilterFor, mergeWithExclude } from "../lib/filters.js";
-import { rerank } from "../lib/ranking.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";
@@ -53,18 +53,14 @@ function formatHighlightBullets(results, maxResults, threshold) {
     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.
+ * 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 formatRankedBullets(ranked, maxResults, threshold) {
+function formatSelected(selected, threshold) {
     const sections = [];
-    for (const r of ranked) {
-        if (r._composite < threshold)
-            continue;
+    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))
@@ -77,8 +73,6 @@ function formatRankedBullets(ranked, maxResults, threshold) {
             .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;
@@ -86,18 +80,15 @@ function formatRankedBullets(ranked, maxResults, threshold) {
 }
 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.";
-// 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. */
+// 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) {
-    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>`;
+    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
@@ -146,11 +137,13 @@ export function buildAutoContextHandler(client, cfg) {
             let formatted;
             if (ranking.enabled) {
                 const ranked = rerank(results, ranking);
-                formatted = formatRankedBullets(ranked, cfg.maxResults, cfg.relevanceThreshold);
+                // 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 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`);
+                    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 {
@@ -158,11 +151,12 @@ export function buildAutoContextHandler(client, cfg) {
                 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.)
+            // 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: nothing cleared the bar — injecting search directive only");
+                log.debug("auto-context: no relevant memories found");
+                return;
             }
             return { prependContext: wrapContext(formatted) };
         }

package/dist/lib/ranking.js

@@ -5,6 +5,7 @@ export const DEFAULT_RANKING = {
     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). */
@@ -61,3 +62,26 @@ export function rerank(results, w) {
     })
         .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: 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.",
+        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

@@ -164,7 +164,8 @@
 					"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 }
+					"candidateMultiplier": { "type": "number", "minimum": 1, "maximum": 10 },
+					"chatterQuota": { "type": "number", "minimum": 0, "maximum": 20 }
 				}
 			},
 			"debug": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "type": "module",
   "description": "OpenClaw Hyperspell memory plugin",
   "license": "MIT",