@gamaze/hicortex 0.19.2 → 0.19.4

package/dist/recall-index.js

@@ -19,6 +19,33 @@
  * 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).
+ *
+ * #329 item 3 — the pure search is SKIPPED when it would be byte-identical
+ * to the blended one: turn 1 (no centroid yet — nothing to blend) or
+ * sessionIntentWeight 0 (blend disabled). The blended result IS the pure
+ * result there, so the floor is trivially satisfied by the blended picks and
+ * the second search (embeds aside, its whole DB + FTS half) is pure waste.
+ *
+ * #329 item 4 — novelty backfill: when the blended picks are empty/short,
+ * unclaimed maxItems slots are filled from the remaining filtered
+ * pure-prompt tail (gate + suppression already applied). Without it the
+ * topic-switch turn — the one the floor exists for — got the MOST truncated
+ * menu: novelty slots + a diluted remainder, while further pure candidates
+ * that had already passed every gate sat unused.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -54,15 +81,19 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SESSION_ID_CHARS = 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,12 +105,40 @@ 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
  *  gate is correct, not a defect); raise only if blocks are persistently
  *  under-filled in production. */
 const CANDIDATE_MULTIPLIER = 3;
+/**
+ * Hard cap on `session_id` length (#328 item 2a). The id is retained as a Map
+ * key by SessionRecallRegistry for the process lifetime (maxSessions=500 LRU
+ * + a per-session shown-set + intent centroid), so an unbounded id is an OOM
+ * vector: ~4.9MB ids × 500 sessions ≈ 2.4GB of retained keys from an
+ * authenticated-but-hostile tenant. Real session ids (CC UUIDs, plugin
+ * session keys) are ≤64 chars — 128 is generous headroom. Longer → 400 with
+ * a clear error; the client treats it like any bad request.
+ */
+exports.MAX_SESSION_ID_CHARS = 128;
 /** First content line, de-markdowned and truncated — the index line title. */
 function memoryTitle(content, maxLen = DEFAULT_TITLE_CHARS) {
     const firstLine = content
@@ -139,6 +198,78 @@ 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).
+ *
+ * #329 CR finding 1b: the FTS candidate list is ALSO computed once per
+ * request (ftsOnce, keyed on query + candidate window) and threaded into both
+ * retrieve() calls via the ftsCandidates provider — the blended and pure
+ * searches of one request carry identical query text and window, so their FTS
+ * halves were byte-identical SQL executed twice. `ftsFn` is the DI seam for
+ * tests (production: storage.searchFts); a throwing FTS computation memoizes
+ * to an empty shared list — the same vector-only degradation retrieve()'s
+ * catch always produced, never an error.
+ */
+function createRecallRetrieveFn(deps) {
+    let embMemo = null;
+    const embedOnce = (query) => {
+        if (!embMemo || embMemo.query !== query) {
+            embMemo = { query, p: deps.embedFn(query) };
+        }
+        return embMemo.p;
+    };
+    const ftsResolve = deps.ftsFn ?? storage.searchFts;
+    let ftsMemo = null;
+    const ftsOnce = (query, limit) => {
+        if (!ftsMemo || ftsMemo.query !== query || ftsMemo.limit !== limit) {
+            try {
+                ftsMemo = { query, limit, rows: ftsResolve(deps.db, query, limit) };
+            }
+            catch {
+                // Same degradation retrieve()'s own catch always produced — the FTS
+                // list is dropped and the search proceeds vector-only.
+                ftsMemo = { query, limit, rows: [] };
+            }
+        }
+        return ftsMemo.rows;
+    };
+    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,
+            // #329: shared per-request FTS list. The recall path never passes
+            // sourceAgent, so the memo is keyed on (query, fetchLimit) only —
+            // exactly the two things retrieve() would pass to searchFts.
+            ftsCandidates: (fetchLimit) => ftsOnce(query, fetchLimit),
+        });
+    };
+}
 /** 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
@@ -162,6 +293,16 @@ async function handleRecallIndex(deps, body) {
     if (!sessionId) {
         return { status: 400, body: { error: "Missing 'session_id'" } };
     }
+    // Length cap (#328 item 2a) — BEFORE the reset branch so an oversized id
+    // never reaches ANY registry call (reset() itself only deletes, but the
+    // next non-reset call with the same id would beginTurn it into a retained
+    // Map key). Clear error so a misbehaving client can self-diagnose.
+    if (sessionId.length > exports.MAX_SESSION_ID_CHARS) {
+        return {
+            status: 400,
+            body: { error: `'session_id' too long (max ${exports.MAX_SESSION_ID_CHARS} chars, got ${sessionId.length})` },
+        };
+    }
     // Reset: SessionStart (startup/resume/clear/compact) — fresh context, so the
     // shown-set is stale by definition.
     if (req.reset === true) {
@@ -176,6 +317,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 +331,33 @@ async function handleRecallIndex(deps, body) {
         project: typeof req.project === "string" && req.project ? req.project : undefined,
         mission_domains: parseStringListParam(req.mission_domains),
     };
+    // #324 + #329 item 3: when the floor is armed AND would differ from the
+    // blended search, 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 SKIP (#329 item 3): on turn 1 the registry has no centroid yet (the
+    // blended call reads-before-fold — recallQueryVector), and at
+    // sessionIntentWeight 0 the centroid is never read at all. In both cases
+    // the blended query vector IS the pure prompt vector, so the second search
+    // would return byte-identical candidates — skip it (the floor is trivially
+    // satisfied: every pure hit is by construction among the blended picks).
+    // The decision is made BEFORE any retrieveFn call, i.e. on the centroid
+    // state of the PREVIOUS turns — exactly the turn-1/turn-2 distinction.
+    const runPureSearch = noveltySlots > 0 &&
+        (0, retrieval_js_1.getSessionIntent)().weight > 0 &&
+        deps.registry.getCentroid(sessionId) !== undefined;
     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 = runPureSearch
+            ? deps.retrieveFn(prompt, maxItems * CANDIDATE_MULTIPLIER, filters, sessionId, true)
+            : Promise.resolve([]);
+        [results, pureResults] = await Promise.all([blended, pure]);
     }
     catch (err) {
         return {
@@ -197,10 +365,57 @@ 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.
+    //
+    // The gate + suppression are applied ONCE to the pure list: the head feeds
+    // the novelty floor, the tail feeds the #329 backfill below.
+    const pureFiltered = pureResults
+        .filter((r) => passesRelevanceGate(r, minSimilarity))
+        .filter((r) => deps.registry.isShowable(sessionId, r.id));
+    const blendedIds = new Set(blendedPicks.map((r) => r.id));
+    const noveltyPicks = pureFiltered
+        .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.
+    let picked = [
+        ...noveltyPicks,
+        ...blendedPicks.slice(0, Math.max(0, maxItems - noveltyPicks.length)),
+    ];
+    // #329 item 4 — backfill: a topic-switch turn dilutes the blended picks, so
+    // picked can land below maxItems even though FURTHER pure candidates have
+    // already passed the gate + suppression + dedup (they sit in the pure tail
+    // beyond the first noveltyFloorSlots). Fill the unclaimed slots from that
+    // tail — without it, the turn the floor exists for got the most truncated
+    // menu. Continuing-intent sessions are untouched: blended picks full →
+    // nothing to backfill (zero-delta output preserved).
+    if (picked.length < maxItems) {
+        const pickedIds = new Set(picked.map((r) => r.id));
+        const backfill = pureFiltered
+            .filter((r) => !pickedIds.has(r.id))
+            .slice(0, maxItems - picked.length);
+        picked = [...picked, ...backfill];
+    }
     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
@@ -205,6 +231,17 @@ export declare function retrieve(db: Database.Database, embedFn: EmbedFn, query:
      *  and get pure-prompt behavior (the query string is embedded here). The
      *  FTS path still uses the raw `query` text regardless. */
     queryEmbedding?: Float32Array;
+    /** #329 CR finding 1b: caller-provided FTS candidate resolution, called
+     *  INSTEAD of running storage.searchFts here. The /recall-index closure
+     *  passes a per-request memoized provider so the blended and pure
+     *  searches of ONE request — same query text, same candidate window —
+     *  execute the FTS half exactly once and share the list. The provider
+     *  receives the fetchLimit/sourceAgent THIS call would have used, so the
+     *  shared list is always computed with the right window. Callers that
+     *  omit it get the previous behavior (retrieve runs searchFts itself). */
+    ftsCandidates?: (fetchLimit: number, sourceAgent?: string) => Array<Memory & {
+        rank: number;
+    }>;
 }): Promise<MemorySearchResult[]>;
 /**
  * Get recent context, optionally filtered by project.

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
@@ -545,8 +556,12 @@ async function retrieve(db, embedFn, query, options) {
     try {
         // sourceAgent is pushed into the FTS SQL (hard filter). project is NOT (it
         // is a soft affinity boost in computeScore as of #203). privacy is NOT
-        // (0.16.x: vestigial column, never filtered).
-        ftsCandidates = storage.searchFts(db, query, fetchLimit, sourceAgent);
+        // (0.16.x: vestigial column, never filtered). With a caller-provided
+        // provider (#329 request-level memo) the same list is shared across the
+        // retrieves of one recall request instead of re-executed.
+        ftsCandidates = options?.ftsCandidates
+            ? options.ftsCandidates(fetchLimit, sourceAgent)
+            : storage.searchFts(db, query, fetchLimit, sourceAgent);
     }
     catch {
         // FTS5 search can fail on special characters; fall back to vector-only

package/dist/storage.d.ts

@@ -137,6 +137,36 @@ export interface Bm25Weights {
 export declare function configureBm25Fts(config?: Record<string, unknown> | null): Bm25Weights;
 /** Current resolved weights (tests + status output). */
 export declare function getBm25Weights(): Bm25Weights;
+/**
+ * Cap on tokens fed to an FTS5 MATCH expression (#329 CR finding 1a).
+ * Quoting made pasted term lists LEGAL queries — and an all-common-tokens AND
+ * is expensive: measured at 100K rows, a 50-token AND runs ~518ms and a
+ * 200-token one 6.3s, and the /recall-index hot path would pay it twice per
+ * prompt. Beyond ~24 tokens the implicit AND is semantic noise anyway (a
+ * memory matching 24+ ANDed prompt tokens is either the exact text or
+ * nothing), so the FIRST 24 tokens are used. 24 is a shipped bound, not a
+ * config knob — change it deliberately, with a perf measurement.
+ */
+export declare const FTS_MATCH_MAX_TOKENS = 24;
+/**
+ * FTS5 MATCH-safety quoting (#329 item 1). The raw prompt is NOT valid FTS5
+ * query syntax: ordinary prompt punctuation (?, -, (, :, URLs, apostrophes, a
+ * leading AND/OR) crashes the FTS5 parser, and retrieval.retrieve's catch then
+ * silently drops the ENTIRE FTS candidate list — the perf sweep measured 8/12
+ * realistic prompts affected, and it is why relevance eval #3 saw 0 FTS rows
+ * in 2,208 candidates. Fix: tokenize on whitespace, strip embedded double
+ * quotes (a raw `"` would terminate our own quoting), and wrap each token in
+ * double quotes — a quoted token is a phrase of LITERAL strings, immune to
+ * FTS5 query syntax (`"what" "is" "the" "deployment" "status"`). Punctuation
+ * INSIDE a token is kept: the tokenizer strips it identically on both sides,
+ * so `"status?"` still matches content containing "status". Joined with spaces
+ * (implicit AND — the same semantics clean prompts always had; a PROSE prompt
+ * whose content holds only most of the tokens matches nothing, which is why
+ * FTS fires on short keyword prompts, not prose recall). Capped at the first
+ * FTS_MATCH_MAX_TOKENS tokens. A query that quotes away to nothing yields ""
+ * and the caller skips the SQL entirely.
+ */
+export declare function buildFtsMatchExpression(query: string): string;
 /**
  * Full-text search using FTS5 fielded BM25 (BM25F) ranking.
  * Returns memories with a rank field (lower is better — see sign note below).

package/dist/storage.js

@@ -4,6 +4,7 @@
  * Ported from hicortex/storage.py. All functions are synchronous (better-sqlite3).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.FTS_MATCH_MAX_TOKENS = void 0;
 exports.embedToBlob = embedToBlob;
 exports.insertMemory = insertMemory;
 exports.resolveMemoryId = resolveMemoryId;
@@ -20,6 +21,7 @@ exports.getStoredEmbedding = getStoredEmbedding;
 exports.vectorSearch = vectorSearch;
 exports.configureBm25Fts = configureBm25Fts;
 exports.getBm25Weights = getBm25Weights;
+exports.buildFtsMatchExpression = buildFtsMatchExpression;
 exports.searchFts = searchFts;
 exports.addLink = addLink;
 exports.getLinks = getLinks;
@@ -345,6 +347,44 @@ function configureBm25Fts(config) {
 function getBm25Weights() {
     return { ...bm25Weights };
 }
+/**
+ * Cap on tokens fed to an FTS5 MATCH expression (#329 CR finding 1a).
+ * Quoting made pasted term lists LEGAL queries — and an all-common-tokens AND
+ * is expensive: measured at 100K rows, a 50-token AND runs ~518ms and a
+ * 200-token one 6.3s, and the /recall-index hot path would pay it twice per
+ * prompt. Beyond ~24 tokens the implicit AND is semantic noise anyway (a
+ * memory matching 24+ ANDed prompt tokens is either the exact text or
+ * nothing), so the FIRST 24 tokens are used. 24 is a shipped bound, not a
+ * config knob — change it deliberately, with a perf measurement.
+ */
+exports.FTS_MATCH_MAX_TOKENS = 24;
+/**
+ * FTS5 MATCH-safety quoting (#329 item 1). The raw prompt is NOT valid FTS5
+ * query syntax: ordinary prompt punctuation (?, -, (, :, URLs, apostrophes, a
+ * leading AND/OR) crashes the FTS5 parser, and retrieval.retrieve's catch then
+ * silently drops the ENTIRE FTS candidate list — the perf sweep measured 8/12
+ * realistic prompts affected, and it is why relevance eval #3 saw 0 FTS rows
+ * in 2,208 candidates. Fix: tokenize on whitespace, strip embedded double
+ * quotes (a raw `"` would terminate our own quoting), and wrap each token in
+ * double quotes — a quoted token is a phrase of LITERAL strings, immune to
+ * FTS5 query syntax (`"what" "is" "the" "deployment" "status"`). Punctuation
+ * INSIDE a token is kept: the tokenizer strips it identically on both sides,
+ * so `"status?"` still matches content containing "status". Joined with spaces
+ * (implicit AND — the same semantics clean prompts always had; a PROSE prompt
+ * whose content holds only most of the tokens matches nothing, which is why
+ * FTS fires on short keyword prompts, not prose recall). Capped at the first
+ * FTS_MATCH_MAX_TOKENS tokens. A query that quotes away to nothing yields ""
+ * and the caller skips the SQL entirely.
+ */
+function buildFtsMatchExpression(query) {
+    return query
+        .split(/\s+/)
+        .map((token) => token.replace(/"/g, ""))
+        .filter((token) => token.length > 0)
+        .slice(0, exports.FTS_MATCH_MAX_TOKENS)
+        .map((token) => `"${token}"`)
+        .join(" ");
+}
 /**
  * Full-text search using FTS5 fielded BM25 (BM25F) ranking.
  * Returns memories with a rank field (lower is better — see sign note below).
@@ -366,8 +406,13 @@ function getBm25Weights() {
  * caching is unaffected and the config path is the only editor.
  */
 function searchFts(db, query, limit = 10, sourceAgent) {
+    // #329: quote the query into literal phrases — a raw prompt crashes the
+    // FTS5 parser on punctuation and the caller's catch drops the whole list.
+    const matchExpr = buildFtsMatchExpression(query);
+    if (!matchExpr)
+        return [];
     const conditions = ["memories_fts MATCH ?"];
-    const params = [query];
+    const params = [matchExpr];
     if (sourceAgent) {
         conditions.push("m.source_agent = ?");
         params.push(sourceAgent);

package/dist/type-classify.js

@@ -84,7 +84,9 @@ function buildTypeClassifyPrompt(content) {
         `"adopted the graded-schema tag model"). Not knowledge (it can change) and ` +
         `not an experience (it persists). A bare AI recommendation or proposal is ` +
         `NEVER a decision — "AI proposed X → user declined/held" is experience ` +
-        `(#290).\n\n` +
+        `(#290). Even if carried out by the user, a version bump, merge, or count ` +
+        `is never a decision — only the durable user-confirmed standardization it ` +
+        `embodies is (#329).\n\n` +
         `IMPORTANCE (0.0–1.0):\n` +
         `- 0.8–1.0: load-bearing — a core piece of knowledge or a decision the ` +
         `agent must know.\n` +

package/dist/types.d.ts

@@ -413,6 +413,15 @@ export interface HicortexConfig {
      * accepts no client limit.
      */
     recallLimit?: number;
+    /**
+     * OC plugin (#326): auto-scaffold the dead-man guard line into the agent
+     * workspace bootstrap file (BOOTSTRAP.md) at service start — the #313
+     * SECONDARY layer under the injected IDENTITY UNAVAILABLE banner (which is
+     * the primary, plugin-side mechanism). Idempotent: a bootstrap already
+     * carrying the line is never rewritten. Default true; `false` disables both
+     * the write and any file creation entirely.
+     */
+    scaffoldDeadMan?: boolean;
     /**
      * Soft cap on the memory corpus (default 10000). When the corpus exceeds this,
      * the nightly's capacity-eviction stage (#245) removes the lowest-
@@ -465,6 +474,14 @@ export interface HicortexConfig {
      * Operator-owned: point at a mounted backup volume, a tmpfs, etc.
      */
     backupDir?: string;
+    /**
+     * Backup retention (#327): how many of the newest `hicortex-*.tar.gz`
+     * artifacts the backup dir keeps after each successful write. Default 7;
+     * 0 keeps everything. Without it every full nightly (and `hicortex backup`)
+     * adds an artifact forever — unbounded growth, per hosted tenant too. Only
+     * artifacts matching the product's own name pattern are ever pruned.
+     */
+    backupRetention?: number;
     /**
      * Post-backup offsite hook (#6). When set, `hicortex backup` and the nightly
      * backup stage invoke this command with the artifact path appended as the LAST

package/dist/uninstall.d.ts

@@ -14,4 +14,37 @@
 export declare const SESSION_START_HOOK_COMMAND_RE: RegExp;
 /** True when a CC hook `command` string runs the Hicortex SessionStart hook. */
 export declare function isHicortexSessionStartHook(command: string): boolean;
+/**
+ * Matches a CC hook `command` that runs the Hicortex recall hook — the
+ * `recall-hook` subcommand (#192). Same word-boundary discipline as the
+ * learnings matcher: an unrelated command that merely CONTAINS the substring
+ * ("my-recall-hook", "recall-hooks-old") is never swept up. Used for BOTH
+ * event arrays the installer writes (UserPromptSubmit + SessionStart).
+ */
+export declare const RECALL_HOOK_COMMAND_RE: RegExp;
+/** True when a CC hook `command` string runs the Hicortex recall hook. */
+export declare function isHicortexRecallHook(command: string): boolean;
+/** One hook group removed from settings.json (for per-group logging). */
+export interface RemovedHookGroup {
+    /** CC event array the entries were removed from ("SessionStart", "UserPromptSubmit"). */
+    event: string;
+    /** Which Hicortex hook set: "learnings" (learnings-identity/lessons-context) or "recall". */
+    kind: "learnings" | "recall";
+    /** Number of matcher entries removed. */
+    count: number;
+}
+/**
+ * Remove every Hicortex hook entry from a PARSED ~/.claude/settings.json
+ * (#327): the SessionStart learnings hook (canonical + legacy alias) AND the
+ * recall-hook pair (UserPromptSubmit + SessionStart, installed together by
+ * installRecallHooks — leaving either behind is a silent npx spawn per prompt
+ * forever). Mutates `settings` in place; returns what was removed (empty when
+ * nothing matched — a clean no-op). Exact-match discipline throughout: only
+ * entries whose `hooks[].command` matches a Hicortex subcommand are removed;
+ * foreign hooks (and prefix-colliding names) stay untouched.
+ *
+ * Pure on the parsed object so the uninstall behavior is unit-testable
+ * without spinning up CC; runUninstall owns the file I/O.
+ */
+export declare function removeHicortexCcHooks(settings: Record<string, unknown>): RemovedHookGroup[];
 export declare function runUninstall(): Promise<void>;