@gamaze/hicortex 0.19.2 → 0.19.3

package/README.md

@@ -260,11 +260,12 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `searchLimit` / `recentLimit` | Default result counts for search (8) and recent (12) |
 | `recentWindowDays` | Candidate window for recent recall (default: 180) |
 | `coldExposureSlots` | Top-k slots reservable for never-accessed memories so the long tail gets exposure (default: 2) |
-| `recallMaxItems` | Max lines in the pushed recall index (default: 6) |
-| `recallMinSimilarity` | Relevance floor for index entries (default: 0.55; text-search matches always pass) |
+| `recallMaxItems` | Max lines in the pushed recall index (default: 5) |
+| `noveltyFloorSlots` | Slots of `recallMaxItems` guaranteed to the top passing hit(s) of the pure-prompt (unblended) search — the novelty floor. Keeps a session whose earlier turns set a strong intent from burying a topic-switching prompt's best matches: the floor's picks render first, turn-based re-show suppression still applies, and the total never exceeds `recallMaxItems` (default: 2; set 0 to disable) |
+| `recallMinSimilarity` | Relevance floor for index entries (default: 0.62; text-search matches always pass) |
 | `recallReshowTurns` | Turns before an already-shown memory may reappear in the same session (default: 30) |
 | `recallMinPromptChars` | Prompts shorter than this skip the recall index (default: 20) |
-| `recallTitleChars` | Chars of each memory's first line shown in an index entry (default: 150, range 40–400). Raised from 100 on 2026-08-02: with topic-first memory titles, 150 chars carries the subject *and* its claim, where 100 cut the claim mid-sentence. Costs roughly +74 tokens per 6-line block |
+| `recallTitleChars` | Chars of each memory's first line shown in an index entry (default: 100, range 40–400). Reverted from 150 on 2026-08-03: a full-corpus relevance eval found 100 and 150 statistically identical while 100 saves ~13% of the block's tokens |
 | `sessionIntentWeight` | Blend weight of the session-intent rolling centroid in the recall search vector: `query = (1-w)·prompt + w·centroid` (default: 0.33; set 0 to disable — pure-prompt recall, the kill-switch). The first turn of a session searches with pure prompt and seeds the centroid; subsequent turns blend so recall follows the session's intent instead of being query-literal. The EMA rate (0.4) is a shipped constant, not configurable |
 | `dedupMergeThreshold` | Minimum cosine similarity for `hicortex dedup` to cluster memories as near-duplicates (default: 0.92) |
 | `supersessionMinSimilarity` | Minimum cosine similarity for a nightly supersession candidate pair (default: 0.80) |

package/dist/mcp-server.js

@@ -643,7 +643,9 @@ async function startServer(options = {}) {
     const scoringCfg = retrieval.configureScoring(savedConfig);
     const sessionIntentCfg = retrieval.configureSessionIntent(savedConfig);
     console.log(`[hicortex] Recall: k=${recallCfg.searchLimit}/recent=${recallCfg.recentLimit}` +
-        `/window=${recallCfg.recentWindowDays}d/cold=${recallCfg.coldExposureSlots} · ` +
+        `/window=${recallCfg.recentWindowDays}d/cold=${recallCfg.coldExposureSlots}` +
+        `/novelty=${(0, recall_index_js_1.resolveNoveltyFloorSlots)(savedConfig?.noveltyFloorSlots, savedConfig?.recallMaxItems)}` +
+        ` · ` +
         `score sim=${scoringCfg.similarity}/str=${scoringCfg.strength}/conn=${scoringCfg.connections}` +
         `/rec=${scoringCfg.recency}, fresh=${scoringCfg.freshnessBoostWeight}@${scoringCfg.freshnessBoostDays}d, ` +
         `superseded×${scoringCfg.supersededDemotion}` +
@@ -657,6 +659,9 @@ async function startServer(options = {}) {
         maxItems: savedConfig?.recallMaxItems,
         minPromptLength: savedConfig?.recallMinPromptChars,
         titleChars: savedConfig?.recallTitleChars,
+        // #324 novelty floor: slots of recallMaxItems guaranteed to the
+        // pure-prompt (unblended) search's top passing hit(s). 0 disables.
+        noveltyFloorSlots: savedConfig?.noveltyFloorSlots,
     };
     memoryInstructionsEnabled = savedConfig?.memoryInstructions !== false;
     if (resolvedAgents.dropped.length > 0) {
@@ -877,37 +882,23 @@ async function startServer(options = {}) {
             res.status(503).json({ error: "Server not initialized" });
             return;
         }
+        // Client-pushed project/privacy scoping (F1) rides through to retrieval,
+        // which handles the filtered over-fetch itself. The search closure itself
+        // lives in recall-index.ts (createRecallRetrieveFn): per-request prompt
+        // embed memo (ONE embed for the blended + pure-prompt searches), the
+        // session-intent centroid blend/EMA fold via retrieval.recallQueryVector
+        // (#192 session-intent keying, 0.15.3), and the #324 pure-prompt branch
+        // that searches unblended and touches no centroid state. Extracted so the
+        // exact behavior is unit-testable without HTTP (blendQueryVector
+        // precedent); this adapter stays thin.
         const r = await (0, recall_index_js_1.handleRecallIndex)({
             db,
             registry: recallRegistry,
-            // Client-pushed project/privacy scoping (F1) rides through to
-            // retrieval, which handles the filtered over-fetch itself.
-            // #192 session-intent keying (0.15.3): embed the prompt ONCE here,
-            // blend with the session's rolling centroid, and pass the blended
-            // vector to retrieve() via queryEmbedding so retrieve() does NOT
-            // re-embed. Turn 1 (no centroid yet) and weight=0 both reduce to a
-            // pure-prompt search (the kill-switch). The centroid is updated AFTER
-            // reading the prior one — so turn 1 searches with pure prompt, then
-            // seeds the centroid for turn 2+ to blend against.
-            retrieveFn: async (query, limit, filters, sessionId) => {
-                const { weight, alpha } = retrieval.getSessionIntent();
-                const promptEmb = await (0, embedder_js_1.embed)(query);
-                // weight=0 (kill-switch): the centroid is neither read nor written.
-                const centroid = weight > 0 ? recallRegistry.getCentroid(sessionId) : undefined;
-                const queryVec = retrieval.blendQueryVector(promptEmb, centroid, weight);
-                if (weight > 0)
-                    recallRegistry.updateCentroid(sessionId, promptEmb, alpha);
-                return retrieval.retrieve(db, embedder_js_1.embed, query, {
-                    limit,
-                    noStrengthen: true,
-                    // #203: project + mission_domains are SOFT affinity (zero-boost
-                    // neutral), threaded into computeScore. 0.16.x: privacy is no
-                    // longer threaded (vestigial column, never filtered).
-                    project: filters?.project,
-                    missionDomains: filters?.mission_domains,
-                    queryEmbedding: queryVec,
-                });
-            },
+            retrieveFn: (0, recall_index_js_1.createRecallRetrieveFn)({
+                db,
+                registry: recallRegistry,
+                embedFn: embedder_js_1.embed,
+            }),
             options: recallIndexOptions,
         }, req.body);
         res.status(r.status).json(r.body);

package/dist/recall-index.d.ts

@@ -18,6 +18,20 @@
  * per-session TURN-based dedup (SessionRecallRegistry), short-prompt skip,
  * and a hard item cap. On a prompt with no relevant memories the block is
  * null and the hook prints nothing.
+ *
+ * Novelty floor (#324): the session-intent blend (#192 session-intent keying)
+ * can dilute a topic-switching prompt below the relevance floor — the live
+ * failure was a technically-primed session asking about "my Sargo" and getting
+ * ZERO relevant memories while a fresh session with the identical prompt got
+ * the perfect top hit. So a second, PURE-prompt search (no centroid blend,
+ * SAME candidate window as the blended search) runs alongside the blended
+ * one, and its top hit(s) that pass the floor are GUARANTEED slots in the
+ * index (dedup by id against the blended picks, capped by
+ * `noveltyFloorSlots`; rendered first). When the pure top hits are already
+ * among the blended picks — the common continuing-intent case — the output is
+ * unchanged. Turn suppression still wins: a recently shown novelty pick is
+ * suppressed like any other (the guarantee is about candidate inclusion, not
+ * forcing re-shows).
  */
 import type Database from "better-sqlite3";
 import type { MemorySearchResult } from "./types.js";
@@ -50,7 +64,26 @@ export interface RecallIndexOptions {
      *  identical (0.6pts apart, N=40, full CI overlap); 100 saves ~13% tokens
      *  per block. */
     titleChars?: number;
+    /** Slots of `maxItems` guaranteed to the pure-prompt (unblended) search's
+     *  top passing hit(s) — the #324 novelty floor. Config `noveltyFloorSlots`,
+     *  default 2 (mirrors coldExposureSlots sizing: small, a floor not a
+     *  takeover). 0 disables the pure-prompt search entirely (the kill-switch).
+     *  Clamped to [0, maxItems]. */
+    noveltyFloorSlots?: number;
 }
+/** Default #324 novelty-floor slots (config `noveltyFloorSlots`). 2 mirrors
+ *  coldExposureSlots sizing — enough to guarantee the pure-prompt top hit
+ *  plus a runner-up, never a takeover of the index. The floor only SPENDS
+ *  slots when a pure-prompt hit differs from the blended picks (topic
+ *  switch); continuing-intent sessions pay nothing. Exported for the boot
+ *  log's knob line (mcp-server resolves config-vs-default here, once). */
+export declare const DEFAULT_NOVELTY_FLOOR_SLOTS = 2;
+/** Resolve the EFFECTIVE novelty floor (raw ?? default, clamped to
+ *  [0, maxItems]) — one definition shared by the handler and the boot knob
+ *  line so the logged value is what handleRecallIndex actually uses.
+ *  maxItems may be the handler's already-resolved number OR raw config
+ *  (boot-log site) — raw is resolved with the handler's exact constants. */
+export declare function resolveNoveltyFloorSlots(rawSlots: unknown, rawMaxItems: unknown): number;
 export interface RecallIndexResult {
     status: number;
     body: Record<string, unknown>;
@@ -97,15 +130,48 @@ export interface RecallFilters {
      *  affinity in computeScore via max overlapping memory_tags.weight. */
     mission_domains?: string[];
 }
+/** The search-closure contract handleRecallIndex consumes (see
+ *  RecallIndexDeps.retrieveFn). Named so the production factory
+ *  (createRecallRetrieveFn) and test doubles share one type. */
+export type RecallRetrieveFn = (query: string, limit: number, filters: RecallFilters | undefined, sessionId: string, purePrompt?: boolean) => Promise<MemorySearchResult[]>;
 export interface RecallIndexDeps {
     db: Database.Database;
     registry: SessionRecallRegistry;
-    /** Search closure. `sessionId` is forwarded so the closure (in mcp-server)
-     *  can resolve/update the session-intent centroid and pass a blended query
-     *  vector into retrieve() — see #192 session-intent keying (0.15.3). */
-    retrieveFn: (query: string, limit: number, filters: RecallFilters | undefined, sessionId: string) => Promise<MemorySearchResult[]>;
+    /** Search closure. `sessionId` is forwarded so the closure resolves/updates
+     *  the session-intent centroid and passes a blended query vector into
+     *  retrieve() — see #192 session-intent keying (0.15.3).
+     *
+     *  `purePrompt` (#324 novelty floor): request the PURE-prompt search — the
+     *  closure must search with the prompt embedding UNBLENDED (no session
+     *  centroid) and must NOT fold the prompt into the centroid a second time
+     *  (the blended call owns this turn's EMA update). Older closures that
+     *  ignore the flag degrade to blended-only recall — no novelty floor, but
+     *  no breakage. */
+    retrieveFn: RecallRetrieveFn;
     options?: RecallIndexOptions;
 }
+/**
+ * The PRODUCTION /recall-index retrieveFn (what mcp-server wires into
+ * handleRecallIndex), extracted from the route handler so the #324 path is
+ * testable without HTTP — same precedent as blendQueryVector/recallQueryVector
+ * ("extracted from the /recall-index closure so the exact decision is
+ * unit-testable").
+ *
+ * Per call:
+ *   - embed the prompt ONCE per request — a single-entry promise memo keyed
+ *     on the query text. The blended and pure-prompt searches of one request
+ *     carry the same prompt, so they share one embed; the factory is built
+ *     per request, so the memo never outlives it.
+ *   - resolve the search vector via retrieval.recallQueryVector (blend + EMA
+ *     fold, or the pure prompt with NO centroid state for #324);
+ *   - retrieve() with noStrengthen (exposure is recorded by
+ *     handleRecallIndex via touchMemoriesShown, never here).
+ */
+export declare function createRecallRetrieveFn(deps: {
+    db: Database.Database;
+    registry: SessionRecallRegistry;
+    embedFn: (text: string) => Promise<Float32Array>;
+}): RecallRetrieveFn;
 /** Normalize a request-supplied string-list param: array of strings or a CSV
  *  string → string[] | undefined. Anything else (or an empty result) means
  *  "absent" — never a partial guess. Used by `mission_domains` (#203) so it

package/dist/recall-index.js

@@ -19,6 +19,20 @@
  * per-session TURN-based dedup (SessionRecallRegistry), short-prompt skip,
  * and a hard item cap. On a prompt with no relevant memories the block is
  * null and the hook prints nothing.
+ *
+ * Novelty floor (#324): the session-intent blend (#192 session-intent keying)
+ * can dilute a topic-switching prompt below the relevance floor — the live
+ * failure was a technically-primed session asking about "my Sargo" and getting
+ * ZERO relevant memories while a fresh session with the identical prompt got
+ * the perfect top hit. So a second, PURE-prompt search (no centroid blend,
+ * SAME candidate window as the blended search) runs alongside the blended
+ * one, and its top hit(s) that pass the floor are GUARANTEED slots in the
+ * index (dedup by id against the blended picks, capped by
+ * `noveltyFloorSlots`; rendered first). When the pure top hits are already
+ * among the blended picks — the common continuing-intent case — the output is
+ * unchanged. Turn suppression still wins: a recently shown novelty pick is
+ * suppressed like any other (the guarantee is about candidate inclusion, not
+ * forcing re-shows).
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -54,15 +68,19 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_NOVELTY_FLOOR_SLOTS = void 0;
+exports.resolveNoveltyFloorSlots = resolveNoveltyFloorSlots;
 exports.memoryTitle = memoryTitle;
 exports.formatIndexLine = formatIndexLine;
 exports.passesRelevanceGate = passesRelevanceGate;
+exports.createRecallRetrieveFn = createRecallRetrieveFn;
 exports.parseStringListParam = parseStringListParam;
 exports.handleRecallIndex = handleRecallIndex;
 exports.handleMemoryGet = handleMemoryGet;
 exports.formatMemoryGetText = formatMemoryGetText;
 const storage = __importStar(require("./storage.js"));
 const type_labels_js_1 = require("./type-labels.js");
+const retrieval_js_1 = require("./retrieval.js");
 /** Relevance-gate floor for vector-only candidates (config `recallMinSimilarity`).
  *  0.62 (was 0.55; raised 2026-08-03 on the fine-grain floor sweep — see the
  *  minSimilarity doc above). */
@@ -74,6 +92,24 @@ const DEFAULT_MIN_PROMPT_LENGTH = 20;
 /** Default index-line title length. 100 (reverted from 150 on 2026-08-03:
  *  eval #3 §5 showed 100 vs 150 statistically identical; 100 saves ~13% tokens). */
 const DEFAULT_TITLE_CHARS = 100;
+/** Default #324 novelty-floor slots (config `noveltyFloorSlots`). 2 mirrors
+ *  coldExposureSlots sizing — enough to guarantee the pure-prompt top hit
+ *  plus a runner-up, never a takeover of the index. The floor only SPENDS
+ *  slots when a pure-prompt hit differs from the blended picks (topic
+ *  switch); continuing-intent sessions pay nothing. Exported for the boot
+ *  log's knob line (mcp-server resolves config-vs-default here, once). */
+exports.DEFAULT_NOVELTY_FLOOR_SLOTS = 2;
+/** Resolve the EFFECTIVE novelty floor (raw ?? default, clamped to
+ *  [0, maxItems]) — one definition shared by the handler and the boot knob
+ *  line so the logged value is what handleRecallIndex actually uses.
+ *  maxItems may be the handler's already-resolved number OR raw config
+ *  (boot-log site) — raw is resolved with the handler's exact constants. */
+function resolveNoveltyFloorSlots(rawSlots, rawMaxItems) {
+    const maxItems = typeof rawMaxItems === "number"
+        ? rawMaxItems
+        : clampInt(rawMaxItems, DEFAULT_MAX_ITEMS, 1, 20);
+    return clampInt(rawSlots, exports.DEFAULT_NOVELTY_FLOOR_SLOTS, 0, maxItems);
+}
 /** Over-fetch multiplier: retrieve `maxItems × 3` candidates so gating + dedup
  *  still leave a full menu. Kept at 3 after maxItems 6→5 and the higher floor —
  *  permit-short is intended (returning fewer than maxItems when fewer clear the
@@ -139,6 +175,50 @@ function passesRelevanceGate(r, minSimilarity) {
         return true;
     return typeof r.similarity === "number" && r.similarity >= minSimilarity;
 }
+/**
+ * The PRODUCTION /recall-index retrieveFn (what mcp-server wires into
+ * handleRecallIndex), extracted from the route handler so the #324 path is
+ * testable without HTTP — same precedent as blendQueryVector/recallQueryVector
+ * ("extracted from the /recall-index closure so the exact decision is
+ * unit-testable").
+ *
+ * Per call:
+ *   - embed the prompt ONCE per request — a single-entry promise memo keyed
+ *     on the query text. The blended and pure-prompt searches of one request
+ *     carry the same prompt, so they share one embed; the factory is built
+ *     per request, so the memo never outlives it.
+ *   - resolve the search vector via retrieval.recallQueryVector (blend + EMA
+ *     fold, or the pure prompt with NO centroid state for #324);
+ *   - retrieve() with noStrengthen (exposure is recorded by
+ *     handleRecallIndex via touchMemoriesShown, never here).
+ */
+function createRecallRetrieveFn(deps) {
+    let embMemo = null;
+    const embedOnce = (query) => {
+        if (!embMemo || embMemo.query !== query) {
+            embMemo = { query, p: deps.embedFn(query) };
+        }
+        return embMemo.p;
+    };
+    return async (query, limit, filters, sessionId, purePrompt) => {
+        const { weight, alpha } = (0, retrieval_js_1.getSessionIntent)();
+        const promptEmb = await embedOnce(query);
+        const queryVec = (0, retrieval_js_1.recallQueryVector)(deps.registry, sessionId, promptEmb, {
+            weight,
+            alpha,
+            purePrompt,
+        });
+        return (0, retrieval_js_1.retrieve)(deps.db, deps.embedFn, query, {
+            limit,
+            noStrengthen: true,
+            // #203: project + mission_domains are SOFT affinity (zero-boost
+            // neutral), threaded into computeScore.
+            project: filters?.project,
+            missionDomains: filters?.mission_domains,
+            queryEmbedding: queryVec,
+        });
+    };
+}
 /** Normalize a request-supplied string-list param: array of strings or a CSV
  *  string → string[] | undefined. Anything else (or an empty result) means
  *  "absent" — never a partial guess. Used by `mission_domains` (#203) so it
@@ -176,6 +256,9 @@ async function handleRecallIndex(deps, body) {
     const maxItems = clampInt(deps.options?.maxItems, DEFAULT_MAX_ITEMS, 1, 20);
     const titleChars = clampInt(deps.options?.titleChars, DEFAULT_TITLE_CHARS, 40, 400);
     const minSimilarity = clampNumber(deps.options?.minSimilarity, DEFAULT_MIN_SIMILARITY, 0, 1);
+    // #324: clamped to [0, maxItems] — the floor is a reservation inside the
+    // item cap, never an expansion of it.
+    const noveltySlots = resolveNoveltyFloorSlots(deps.options?.noveltyFloorSlots, maxItems);
     const turn = deps.registry.beginTurn(sessionId);
     // Optional client-side scoping (F1 + #203): project + mission_domains (soft
     // affinity) ride the body and are pushed into retrieval. project is cwd-
@@ -187,9 +270,29 @@ async function handleRecallIndex(deps, body) {
         project: typeof req.project === "string" && req.project ? req.project : undefined,
         mission_domains: parseStringListParam(req.mission_domains),
     };
+    // #324: when the floor is armed, TWO searches run per recall — the blended
+    // (session-intent) query that has always run, and a PURE-prompt query with
+    // no centroid blend. Issued together so the second adds no wall-clock
+    // latency beyond its own DB work (the prompt is embedded once — the closure
+    // memoizes). Same failure domain (same db + embedder): either failing fails
+    // the request explicitly; no silent blended-only degradation.
+    //
+    // The pure call fetches the SAME candidate window as the blended call
+    // (maxItems × 3). A narrower window would break the guarantee at the edge:
+    // sqlite-vec KNN candidates are fetched at limit × 3 and re-ranked by
+    // composite score, so a memory the fresh-session path ranks #1 by
+    // strength/recency but that sits at raw-vector rank 19+ would never enter
+    // a small window's candidate set — the #324 failure shape surviving at the
+    // edge. The guarantee is therefore: the top passing pure-prompt hit WITHIN
+    // the shared candidate window always survives into the index.
     let results;
+    let pureResults;
     try {
-        results = await deps.retrieveFn(prompt, maxItems * CANDIDATE_MULTIPLIER, filters, sessionId);
+        const blended = deps.retrieveFn(prompt, maxItems * CANDIDATE_MULTIPLIER, filters, sessionId);
+        const pure = noveltySlots > 0
+            ? deps.retrieveFn(prompt, maxItems * CANDIDATE_MULTIPLIER, filters, sessionId, true)
+            : Promise.resolve([]);
+        [results, pureResults] = await Promise.all([blended, pure]);
     }
     catch (err) {
         return {
@@ -197,10 +300,39 @@ async function handleRecallIndex(deps, body) {
             body: { error: err instanceof Error ? err.message : String(err) },
         };
     }
-    const picked = results
+    // Blended (session-intent) picks: relevance gate + turn-based suppression,
+    // top maxItems — exactly what the index would show with no novelty floor.
+    const blendedPicks = results
         .filter((r) => passesRelevanceGate(r, minSimilarity))
         .filter((r) => deps.registry.isShowable(sessionId, r.id))
         .slice(0, maxItems);
+    // #324 novelty floor: the best match(es) for the CURRENT PROMPT ALONE are
+    // guaranteed a place in the index. The blend exists to follow session
+    // intent, not to veto the prompt — so pure-prompt hits that pass the floor
+    // enter even when the blended query diluted them out of `results`
+    // entirely. Dedup is against the blended PICKS (the no-floor outcome): when
+    // the pure top hit is already shown by the blended path — the common
+    // continuing-intent case — the floor costs nothing and the output is
+    // unchanged. Suppression applies BEFORE the guarantee (suppression wins:
+    // the floor is about candidate inclusion, not forcing re-shows). FTS-sourced
+    // pure hits pass the gate unconditionally, same as the blended path.
+    const blendedIds = new Set(blendedPicks.map((r) => r.id));
+    const noveltyPicks = pureResults
+        .filter((r) => passesRelevanceGate(r, minSimilarity))
+        .filter((r) => deps.registry.isShowable(sessionId, r.id))
+        .filter((r) => !blendedIds.has(r.id))
+        .slice(0, noveltySlots);
+    // The floor takes precedence (#324 vs #192 cold slots): novelty picks hold
+    // their slots; blended picks keep the remainder, evicted from the TAIL
+    // (lowest rank first) so the session-intent head survives. Cold-exposure
+    // slots continue to apply inside each retrieve()'s own top-k. Total never
+    // exceeds maxItems. Render order: novelty picks FIRST — on a topic switch
+    // they are the most relevant lines to the CURRENT turn, and the head of the
+    // block carries the most weight for a reader scanning the menu.
+    const picked = [
+        ...noveltyPicks,
+        ...blendedPicks.slice(0, Math.max(0, maxItems - noveltyPicks.length)),
+    ];
     if (picked.length === 0) {
         return { status: 200, body: { block: null, shown: [], turn } };
     }

package/dist/retrieval.d.ts

@@ -115,6 +115,32 @@ export declare function getSessionIntent(): {
  * closure-integration harness.
  */
 export declare function blendQueryVector(promptEmb: Float32Array, centroid: Float32Array | undefined, weight: number): Float32Array;
+/**
+ * The /recall-index closure's PER-CALL search-vector decision (#199 + #324),
+ * extracted next to blendQueryVector (same precedent: the exact decision must
+ * be unit-testable without a closure-integration harness).
+ *
+ *   - purePrompt (#324 novelty floor): return the prompt embedding UNBLENDED
+ *     and touch NO centroid state — neither read nor the EMA fold. The folded
+ *     turn is owned by the blended call; a second fold here would double-count
+ *     the prompt and skew every later turn's blend (the single worst
+ *     regression this extraction exists to lock out).
+ *   - blended (default): read the prior centroid (weight>0 only), blend, then
+ *     fold this turn's prompt ONCE (weight>0 only) — read-before-update so
+ *     turn 1 searches pure and seeds the centroid for turn 2.
+ *
+ * `registry` is the structural surface needed (SessionRecallRegistry
+ * satisfies it) — keeps this module decoupled from the registry class.
+ */
+export interface CentroidStore {
+    getCentroid(sessionId: string): Float32Array | undefined;
+    updateCentroid(sessionId: string, promptEmbedding: Float32Array, alpha: number): Float32Array;
+}
+export declare function recallQueryVector(registry: CentroidStore, sessionId: string, promptEmb: Float32Array, opts: {
+    weight: number;
+    alpha: number;
+    purePrompt?: boolean;
+}): Float32Array;
 /**
  * Ids among `candidateIds` that have been superseded by a later memory — i.e.
  * they are the SOURCE of a `superseded_by` link (stageSupersession links

package/dist/retrieval.js

@@ -61,6 +61,7 @@ exports.getScoringWeights = getScoringWeights;
 exports.configureSessionIntent = configureSessionIntent;
 exports.getSessionIntent = getSessionIntent;
 exports.blendQueryVector = blendQueryVector;
+exports.recallQueryVector = recallQueryVector;
 exports.findSupersededIds = findSupersededIds;
 exports.l2ToCosine = l2ToCosine;
 exports.effectiveStrength = effectiveStrength;
@@ -250,6 +251,16 @@ function blendQueryVector(promptEmb, centroid, weight) {
         ? (0, schema_prototypes_js_1.l2Normalize)((0, schema_prototypes_js_1.weightedAdd)(promptEmb, 1 - weight, centroid, weight))
         : promptEmb;
 }
+function recallQueryVector(registry, sessionId, promptEmb, opts) {
+    if (opts.purePrompt)
+        return promptEmb;
+    // weight=0 (kill-switch): the centroid is neither read nor written.
+    const centroid = opts.weight > 0 ? registry.getCentroid(sessionId) : undefined;
+    const queryVec = blendQueryVector(promptEmb, centroid, opts.weight);
+    if (opts.weight > 0)
+        registry.updateCentroid(sessionId, promptEmb, opts.alpha);
+    return queryVec;
+}
 /**
  * Ids among `candidateIds` that have been superseded by a later memory — i.e.
  * they are the SOURCE of a `superseded_by` link (stageSupersession links

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hicortex",
   "name": "Hicortex — Long-term Memory That Learns",
   "description": "Your agents remember past decisions, avoid repeated mistakes, and get smarter every day. Nightly reflection generates actionable lessons that automatically update agent behavior.",
-  "version": "0.19.2",
+  "version": "0.19.3",
   "kind": "lifecycle",
   "skills": ["./skills/hicortex-memory"],
   "configSchema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.19.2",
+  "version": "0.19.3",
   "description": "Persistent agent identity for AI agents \u2014 a hand-edited identity layer, nightly-distilled experience, and lessons injected every session, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, and Pi.",
   "main": "dist/index.js",
   "bin": {