@gamaze/hicortex 0.19.1 → 0.19.3

package/dist/learnings-identity.d.ts

@@ -63,18 +63,25 @@ export declare function resolveConfig(): ResolvedConfig | null;
  */
 export declare function titleCaseSection(name: string): string;
 /**
- * Stable section ordering: `user` first, then `rules` (the seeded primary
- * sections, spec §8), then every other section alphabetically. Server-side
- * enumeration order (readdirSync) is FS-dependent, so we sort here for a
- * deterministic injection block. Exported for reuse by the OC plugin.
+ * Stable section ordering for the rendered `## Identity` block: the #313
+ * precedence contract — `agent_identity` (the agent's own self + role
+ * conduct) first, then `user` (the principal), then `rules` (fleet-wide house
+ * rules), then every other section alphabetically. The list is imported from
+ * identity-store (SECTION_PRECEDENCE) so the server's SERVED order and every
+ * client's RENDERED order are the same definition — they cannot drift.
+ * Server-side enumeration order (readdirSync) is FS-dependent, so we sort
+ * here for a deterministic injection block. Exported for reuse by the OC
+ * plugin; the Python Hermes plugin mirrors this helper — keep them in sync.
  */
 export declare function orderSectionNames(names: string[]): string[];
 /**
  * Render the `## Identity` block from a resolved section map, or null when there
  * is nothing to inject (no sections, or every section blank after trimming).
  * Pure — no gating, no I/O. Shared verbatim by the CC hook and the OC plugin so
- * both harnesses emit an identical block. Sections are ordered (user, rules,
- * then alphabetical) and rendered under title-cased `###` headings.
+ * both harnesses emit an identical block. Sections are ordered (agent_identity,
+ * user, rules, then alphabetical) and rendered under `###` headings labeled by
+ * the #313 scope map (SECTION_LABELS: "Agent identity" / "User" / "Global
+ * rules"); unknown section names fall back to title-case.
  */
 export declare function renderIdentityBlock(sections: Record<string, string>): string | null;
 /**
@@ -116,10 +123,12 @@ export interface IdentityToolResult {
  *     `agent` param forwarded so per-agent installs resolve the right scope
  *     (WARNING-2: previously the tool always passed `{}` → global, so an agent
  *     with an override saw the wrong identity).
- *  2. `injectMemorySection` — the synthetic product-owned `memory` section
- *     (WARNING-1: the REST route + SessionStart hook inject it; the tool did
- *     not, contradicting its "same data" docs).
- *  3. optional `name` filter, then `renderIdentityBlock` for the `### <Title>`
+ *  2. `serveIdentityBody` — the ONE composition helper (REST uses it too):
+ *     injects the synthetic product-owned `memory` section (WARNING-1: the
+ *     REST route + SessionStart hook inject it; the tool did not,
+ *     contradicting its "same data" docs) and applies the SECTION_PRECEDENCE
+ *     wire order.
+ *  3. optional `name` filter, then `renderIdentityBlock` for the `### <Label>`
  *     markdown the hook injects.
  *
  * Pure: no I/O of its own (the only I/O is `handleIdentityGet` reading the

package/dist/learnings-identity.js

@@ -39,7 +39,6 @@ exports.fetchLessonsIdentity = fetchLessonsIdentity;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const identity_store_js_1 = require("./identity-store.js");
-const memory_instructions_js_1 = require("./memory-instructions.js");
 const features_js_1 = require("./features.js");
 const extensions_js_1 = require("./extensions.js");
 const state_js_1 = require("./state.js");
@@ -152,22 +151,29 @@ function titleCaseSection(name) {
         .join(" ");
 }
 /**
- * Stable section ordering: `user` first, then `rules` (the seeded primary
- * sections, spec §8), then every other section alphabetically. Server-side
- * enumeration order (readdirSync) is FS-dependent, so we sort here for a
- * deterministic injection block. Exported for reuse by the OC plugin.
+ * Stable section ordering for the rendered `## Identity` block: the #313
+ * precedence contract — `agent_identity` (the agent's own self + role
+ * conduct) first, then `user` (the principal), then `rules` (fleet-wide house
+ * rules), then every other section alphabetically. The list is imported from
+ * identity-store (SECTION_PRECEDENCE) so the server's SERVED order and every
+ * client's RENDERED order are the same definition — they cannot drift.
+ * Server-side enumeration order (readdirSync) is FS-dependent, so we sort
+ * here for a deterministic injection block. Exported for reuse by the OC
+ * plugin; the Python Hermes plugin mirrors this helper — keep them in sync.
  */
 function orderSectionNames(names) {
-    const primaries = ["user", "rules"].filter((p) => names.includes(p));
-    const rest = names.filter((n) => n !== "user" && n !== "rules").sort();
+    const primaries = identity_store_js_1.SECTION_PRECEDENCE.filter((p) => names.includes(p));
+    const rest = names.filter((n) => !identity_store_js_1.SECTION_PRECEDENCE.includes(n)).sort();
     return [...primaries, ...rest];
 }
 /**
  * Render the `## Identity` block from a resolved section map, or null when there
  * is nothing to inject (no sections, or every section blank after trimming).
  * Pure — no gating, no I/O. Shared verbatim by the CC hook and the OC plugin so
- * both harnesses emit an identical block. Sections are ordered (user, rules,
- * then alphabetical) and rendered under title-cased `###` headings.
+ * both harnesses emit an identical block. Sections are ordered (agent_identity,
+ * user, rules, then alphabetical) and rendered under `###` headings labeled by
+ * the #313 scope map (SECTION_LABELS: "Agent identity" / "User" / "Global
+ * rules"); unknown section names fall back to title-case.
  */
 function renderIdentityBlock(sections) {
     if (!sections || typeof sections !== "object" || Array.isArray(sections))
@@ -178,7 +184,11 @@ function renderIdentityBlock(sections) {
         const body = sections[name];
         if (typeof body !== "string" || body.trim() === "")
             continue;
-        bodyParts.push(`### ${titleCaseSection(name)}`, "", body.trim());
+        // Own-property lookup (CR-A): "constructor" is allowlist-VALID, and a
+        // plain SECTION_LABELS[name] would resolve through the Object.prototype
+        // chain and render the inherited function's source as the heading.
+        const label = Object.hasOwn(identity_store_js_1.SECTION_LABELS, name) ? identity_store_js_1.SECTION_LABELS[name] : titleCaseSection(name);
+        bodyParts.push(`### ${label}`, "", body.trim());
     }
     if (bodyParts.length === 0)
         return null;
@@ -195,10 +205,12 @@ function renderIdentityBlock(sections) {
  *     `agent` param forwarded so per-agent installs resolve the right scope
  *     (WARNING-2: previously the tool always passed `{}` → global, so an agent
  *     with an override saw the wrong identity).
- *  2. `injectMemorySection` — the synthetic product-owned `memory` section
- *     (WARNING-1: the REST route + SessionStart hook inject it; the tool did
- *     not, contradicting its "same data" docs).
- *  3. optional `name` filter, then `renderIdentityBlock` for the `### <Title>`
+ *  2. `serveIdentityBody` — the ONE composition helper (REST uses it too):
+ *     injects the synthetic product-owned `memory` section (WARNING-1: the
+ *     REST route + SessionStart hook inject it; the tool did not,
+ *     contradicting its "same data" docs) and applies the SECTION_PRECEDENCE
+ *     wire order.
+ *  3. optional `name` filter, then `renderIdentityBlock` for the `### <Label>`
  *     markdown the hook injects.
  *
  * Pure: no I/O of its own (the only I/O is `handleIdentityGet` reading the
@@ -209,7 +221,10 @@ function buildIdentityToolResult(identityDir, identityClients, identityAgents, o
     // WARNING-2: forward `agent` so per-agent installs resolve the right scope.
     // An invalid id makes handleIdentityGet return a 400 → surfaced as isError.
     const query = opts.agent ? { agent: opts.agent } : {};
-    const r = (0, identity_store_js_1.handleIdentityGet)(identityDir, identityClients, query, identityAgents);
+    // WARNING-1: inject the synthetic `memory` section exactly like REST + the
+    // SessionStart hook — via the ONE composition helper (serveIdentityBody,
+    // #313 CR3) so the tool's served order is the routes' served order.
+    const r = (0, identity_store_js_1.serveIdentityBody)((0, identity_store_js_1.handleIdentityGet)(identityDir, identityClients, query, identityAgents), opts.memoryInstructionsEnabled);
     if (r.status !== 200) {
         const errBody = r.body;
         return {
@@ -217,10 +232,6 @@ function buildIdentityToolResult(identityDir, identityClients, identityAgents, o
             isError: true,
         };
     }
-    // WARNING-1: inject the synthetic `memory` section exactly like REST + the
-    // SessionStart hook. `injectMemorySection` is a no-op when disabled or when
-    // agent mode === "off".
-    (0, memory_instructions_js_1.injectMemorySection)(r.body, opts.memoryInstructionsEnabled);
     const sections = r.body.sections ?? {};
     const filtered = opts.name
         ? (sections[opts.name] !== undefined ? { [opts.name]: sections[opts.name] } : {})

package/dist/mcp-server.js

@@ -309,7 +309,7 @@ function createMcpServer() {
             const identityDir = (0, node_path_1.join)(stateDir, "identity");
             // Single pipeline shared with REST /identity + the SessionStart hook
             // (#264 CRITICAL + WARNING-1 + WARNING-2). The pure function owns
-            // handleIdentityGet → injectMemorySection → renderIdentityBlock.
+            // handleIdentityGet → serveIdentityBody → renderIdentityBlock.
             const result = (0, learnings_identity_js_1.buildIdentityToolResult)(identityDir, identityClients, identityAgents, {
                 name,
                 agent,
@@ -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);
@@ -975,14 +966,11 @@ async function startServer(options = {}) {
     const identityDir = (0, node_path_1.join)(stateDir, "identity");
     app.get("/identity", (req, res) => {
         try {
-            const r = (0, identity_store_js_1.handleIdentityGet)(identityDir, identityClients, req.query, identityAgents);
-            // #192: product-owned memory instructions ride as a synthetic read-only
-            // `memory` section (config memoryInstructions !== false; agent mode
-            // "off" respected inside the helper). Every harness renders it via the
-            // shared section renderer — zero client changes.
-            if (r.status === 200) {
-                (0, memory_instructions_js_1.injectMemorySection)(r.body, memoryInstructionsEnabled);
-            }
+            // serveIdentityBody (#192 + #313): the ONE composition — synthetic
+            // product-owned `memory` section, then the SECTION_PRECEDENCE wire
+            // order. Shared with GET /context and the MCP hicortex_identity tool so
+            // every surface serves byte-identical ordering.
+            const r = (0, identity_store_js_1.serveIdentityBody)((0, identity_store_js_1.handleIdentityGet)(identityDir, identityClients, req.query, identityAgents), memoryInstructionsEnabled);
             res.status(r.status).json(r.body);
         }
         catch (err) {
@@ -1013,10 +1001,9 @@ async function startServer(options = {}) {
     // difference in behaviour, only the URL.
     app.get("/context", (req, res) => {
         try {
-            const r = (0, identity_store_js_1.handleIdentityGet)(identityDir, identityClients, req.query, identityAgents);
-            if (r.status === 200) {
-                (0, memory_instructions_js_1.injectMemorySection)(r.body, memoryInstructionsEnabled);
-            }
+            // Same serveIdentityBody composition as GET /identity — the alias
+            // serves byte-equal behaviour by construction.
+            const r = (0, identity_store_js_1.serveIdentityBody)((0, identity_store_js_1.handleIdentityGet)(identityDir, identityClients, req.query, identityAgents), memoryInstructionsEnabled);
             res.status(r.status).json(r.body);
         }
         catch (err) {

package/dist/prompts.js

@@ -130,6 +130,8 @@ EXTRACT into this markdown format:
 
 ### Project State Changes
 - [D] [SUBJECT]: [what changed], [from → to] (${date})
+  (Durable shifts only — the model/tool/approach the project now uses. A
+   status flip or counter change is NEVER-RECORD ephemera, not a state change)
 
 ### Key Entities & Relationships
 - [K] [entity A] → [relationship] → [entity B] (${date})
@@ -179,6 +181,23 @@ label, a sentiment ("Strong Negative"), or "User rejected…" is unfindable —
 matches every emotionally-similar prompt and no topically-relevant one. Front-load
 the subject; put reaction, intensity and reasoning AFTER it.
 
+NEVER-RECORD — ephemera gate (critical):
+Every candidate must pass one test: will it still be TRUE and still MATTER in 3 months?
+Content whose entire value is a state that expires is NEVER recorded —
+do not score it lower and write it anyway: OMIT it. A closed category of never-record ephemera:
+- issue/PR/epic/merge status: "PR #173 merged", "Epic 2 CLOSED — all children merged"
+- version/deploy/test-count statistics: "v0.16.0 deployed to rc dist-tag",
+  "Test suite grew 616→749", "Main branch updated to <sha>"
+- session bookkeeping/outcomes: "Session closure: nothing remains to do",
+  todo deferrals ("parked until next week"), sync/replay states
+- transient readings/snapshots: "disk usage snapshot: 84% at 14:20",
+  "uptime counter passed 40 days"
+The durable part of the same event may still qualify — the CHOICE a change
+embodies ("standardize on model X", user-confirmed) is [D], a configuration
+that holds going forward is [K]; the version bump, merge, or count itself never is.
+If EVERY item in the transcript is never-record ephemera, output ONLY:
+"NO_EXTRACT" — zero memories is the correct result for a pure-status segment.
+
 RULES:
 - Extract MAX 20 items total (quality over quantity)
 - Use EXACT names/versions/paths/numbers as they appear in the transcript —
@@ -187,7 +206,8 @@ RULES:
 - Each must be useful if recalled in a future session
 - Skip: routine code edits, standard tool usage, trivial fixes
 - Include: architectural decisions, debugging breakthroughs, user preferences,
-  tool configurations, API discoveries, project milestones
+  tool configurations, API discoveries, durable project milestones (a status
+  flip — shipped/merged/closed — is NEVER-RECORD ephemera, not a milestone)
 - PRIORITIZE Corrections & Rejections — these are high-value signals for learning
   what the user does NOT want. Even a single "no" or style correction is worth extracting.
 - Strong language or profanity from the user is a high-intensity signal — it indicates

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