@gamaze/hicortex 0.15.3 → 0.16.1

package/dist/recall-index.d.ts

@@ -25,13 +25,31 @@ import { SessionRecallRegistry } from "./recall-registry.js";
 export interface RecallIndexOptions {
     /** Minimum measured cosine for vector-only candidates (config
      *  `recallMinSimilarity`). FTS-matched candidates pass regardless — a BM25
-     *  text match is direct evidence of relevance. Default 0.55 (the neutral
-     *  placeholder similarity is 0.5; anything at/below that is noise). */
+     *  text match is direct evidence of relevance. Default 0.62 (raised from 0.55
+     *  on 2026-08-03 per a 0.01-step floor sweep on the rewritten corpus): steady
+     *  ~3:1 noise:signal removal with no knee; 0.62 = +2.2pts precision, 10/98
+     *  prompts silent, sits below the 0.63 local pessimum. The floor is a noise
+     *  dial, NOT a silence mechanism — at 0.62 each correctly-silenced empty prompt
+     *  comes with ~1.5 wrongly-silenced (real signal); a non-cosine gate is the
+     *  real silence fix (eval #3 §4). */
     minSimilarity?: number;
-    /** Max index lines per response (config `recallMaxItems`). Default 6. */
+    /** Max index lines per response (config `recallMaxItems`). Default 5
+     *  (lowered from 6 on 2026-08-03). Per-slot decomposition at floor 0.62:
+     *  slot 6 gives NO prompt its first relevant memory — "6 is wrong" is the
+     *  robust, prompt-set-independent finding, and 5 captures it. The K-sweep
+     *  is monotone (precision@4 33.7% > @6 30.6% > @8 28.3%), so 4 is
+     *  lower-noise — but the 4-vs-5 distinction rests on 5 of 98 prompts and is
+     *  overfitting-fragile (K and the floor were tuned on the same set); 5 hedges
+     *  with coverage at modest cost. Lower to 4 if a fresh-prompt eval replicates. */
     maxItems?: number;
     /** Prompts shorter than this are skipped (continuations, "yes", "do it"). */
     minPromptLength?: number;
+    /** Max chars of the memory's first line shown in an index entry (config
+     *  `recallTitleChars`). Default 100 (reverted from 150 on 2026-08-03): the
+     *  full-corpus relevance eval (#3, §5) found 100 vs 150 statistically
+     *  identical (0.6pts apart, N=40, full CI overlap); 100 saves ~13% tokens
+     *  per block. */
+    titleChars?: number;
 }
 export interface RecallIndexResult {
     status: number;
@@ -39,15 +57,44 @@ export interface RecallIndexResult {
 }
 /** First content line, de-markdowned and truncated — the index line title. */
 export declare function memoryTitle(content: string, maxLen?: number): string;
-/** Relevance gate: real text match, or measured cosine above the floor. */
+/**
+ * Render one production index line. Exported (2026-08-02, relevance eval #v2)
+ * so the eval can measure the REAL rendered surface instead of reimplementing
+ * it — `maxLen` threads through to `memoryTitle` unchanged (default
+ * DEFAULT_TITLE_CHARS = 100, config `recallTitleChars`) so the eval's snippet-length
+ * sweep (spec §4.2) can call this SAME function at 100/150/title1sent without
+ * duplicating the date/scope/agent/type meta-line logic.
+ */
+export declare function formatIndexLine(r: MemorySearchResult & {
+    domain?: string | null;
+}, maxLen?: number): string;
+/**
+ * Relevance gate: a real BM25 text match (FTS) passes unconditionally; a
+ * vector-only candidate must clear `minSimilarity`.
+ *
+ * NOTE: FTS hits BYPASS the similarity floor, so raising the floor shifts
+ * weight toward FTS-sourced entries. In practice FTS is currently inert on
+ * real prompts — eval #3 had 0 FTS rows / 2,208 (2,203 vector + 5 graph), and
+ * a 12-prompt live bedrock sample returned 96/96 vector — so the floor change
+ * is safe as measured. But FTS quality is unmeasured; if FTS starts firing
+ * (e.g. as #205's fielded-BM25 retune beds in), give it its own eval.
+ */
 export declare function passesRelevanceGate(r: MemorySearchResult, minSimilarity: number): boolean;
 /** Recall filters a client may push per request (#193 review F1): a scoped
  *  plugin (Hermes privacy_filter / default_project) must be able to narrow
  *  recall exactly like the legacy /search prefetch did — dropping them
- *  silently would leak out-of-scope memory titles into the injected index. */
+ *  silently would leak out-of-scope memory titles into the injected index.
+ *
+ *  #203: `project` and `mission_domains` are now SOFT affinity signals in
+ *  retrieval (zero-boost neutral, never a filter / penalty); `privacy` stays a
+ *  hard filter (security boundary). They ride the body → retrieveFn →
+ *  retrieve() → computeScore path unchanged in shape. */
 export interface RecallFilters {
     project?: string;
     privacy?: string[];
+    /** #203: Hermes mission domains (declared in plugin config). Soft domain
+     *  affinity in computeScore via max overlapping memory_tags.weight. */
+    mission_domains?: string[];
 }
 export interface RecallIndexDeps {
     db: Database.Database;
@@ -58,9 +105,15 @@ export interface RecallIndexDeps {
     retrieveFn: (query: string, limit: number, filters: RecallFilters | undefined, sessionId: string) => Promise<MemorySearchResult[]>;
     options?: RecallIndexOptions;
 }
+/** 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. Shared by `parsePrivacyParam` and
+ *  `mission_domains` (#203) so both accept `["A","B"]` and `"A, B"` alike. */
+export declare function parseStringListParam(v: unknown): string[] | undefined;
 /** Normalize a request-supplied privacy filter: array of strings or a CSV
  *  string → string[] | undefined. Anything else (or an empty result) means
- *  "no filter" — never a partial guess. */
+ *  "no filter" — never a partial guess. Delegates to parseStringListParam;
+ *  kept as a named export for tests and handleMemoryGet callers. */
 export declare function parsePrivacyParam(v: unknown): string[] | undefined;
 /**
  * Handle a /recall-index request body. Thin Express adapter in mcp-server.ts;
@@ -83,3 +136,20 @@ export declare function handleMemoryGet(db: Database.Database, query: {
     id?: unknown;
     privacy?: unknown;
 }): RecallIndexResult;
+/**
+ * MCP `hicortex_get` presentation: handleMemoryGet's result framed as the
+ * text block the MCP tool returns (provenance header + the SHARED citation +
+ * content). Extracted from the MCP tool handler so its output — incl. the
+ * #204 FETCHED marker, which rides on handleMemoryGet's citation — is unit-
+ * testable. The citation string is built ONCE (handleMemoryGet); this only
+ * frames it, mirroring how /recall-index is shared across harnesses. The
+ * extraction closes the #207 gap (CC's MCP path had a marker-less citation
+ * built inline, while the REST path used handleMemoryGet — same contract, two
+ * implementations, one updated).
+ */
+export declare function formatMemoryGetText(db: Database.Database, query: {
+    id?: unknown;
+}): {
+    status: number;
+    text: string;
+};

package/dist/recall-index.js

@@ -55,18 +55,33 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.memoryTitle = memoryTitle;
+exports.formatIndexLine = formatIndexLine;
 exports.passesRelevanceGate = passesRelevanceGate;
+exports.parseStringListParam = parseStringListParam;
 exports.parsePrivacyParam = parsePrivacyParam;
 exports.handleRecallIndex = handleRecallIndex;
 exports.handleMemoryGet = handleMemoryGet;
+exports.formatMemoryGetText = formatMemoryGetText;
 const storage = __importStar(require("./storage.js"));
-const DEFAULT_MIN_SIMILARITY = 0.55;
-const DEFAULT_MAX_ITEMS = 6;
+/** 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). */
+const DEFAULT_MIN_SIMILARITY = 0.62;
+/** Max index lines per pushed recall block (config `recallMaxItems`).
+ *  5 (was 6; lowered 2026-08-03 — slot 6 is pure padding at floor 0.62). */
+const DEFAULT_MAX_ITEMS = 5;
 const DEFAULT_MIN_PROMPT_LENGTH = 20;
-/** Retrieve more than maxItems so gating + dedup still leave a full menu. */
+/** 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;
+/** 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;
 /** First content line, de-markdowned and truncated — the index line title. */
-function memoryTitle(content, maxLen = 100) {
+function memoryTitle(content, maxLen = DEFAULT_TITLE_CHARS) {
     const firstLine = content
         .split("\n")
         .map((l) => l.trim())
@@ -86,22 +101,49 @@ function formatDate(iso) {
     const mm = String(d.getMonth() + 1).padStart(2, "0");
     return `${dd}.${mm}.${d.getFullYear()}`;
 }
-function formatIndexLine(r) {
-    const meta = [formatDate(r.created_at), r.domain ?? r.project ?? undefined, r.memory_type]
+/**
+ * Render one production index line. Exported (2026-08-02, relevance eval #v2)
+ * so the eval can measure the REAL rendered surface instead of reimplementing
+ * it — `maxLen` threads through to `memoryTitle` unchanged (default
+ * DEFAULT_TITLE_CHARS = 100, config `recallTitleChars`) so the eval's snippet-length
+ * sweep (spec §4.2) can call this SAME function at 100/150/title1sent without
+ * duplicating the date/scope/agent/type meta-line logic.
+ */
+function formatIndexLine(r, maxLen = DEFAULT_TITLE_CHARS) {
+    // Provenance (#202): date, scope (domain else project), ORIGIN AGENT, type.
+    // The origin agent lets a reader calibrate trust — "from my session" vs
+    // another agent/project — before fetching or acting on an entry.
+    const meta = [
+        formatDate(r.created_at),
+        r.domain ?? r.project ?? undefined,
+        r.source_agent ?? undefined,
+        r.memory_type,
+    ]
         .filter(Boolean)
         .join(", ");
-    return `- [${r.id}] ${memoryTitle(r.content)}${meta ? ` (${meta})` : ""}`;
+    return `- [${r.id}] ${memoryTitle(r.content, maxLen)}${meta ? ` (${meta})` : ""}`;
 }
-/** Relevance gate: real text match, or measured cosine above the floor. */
+/**
+ * Relevance gate: a real BM25 text match (FTS) passes unconditionally; a
+ * vector-only candidate must clear `minSimilarity`.
+ *
+ * NOTE: FTS hits BYPASS the similarity floor, so raising the floor shifts
+ * weight toward FTS-sourced entries. In practice FTS is currently inert on
+ * real prompts — eval #3 had 0 FTS rows / 2,208 (2,203 vector + 5 graph), and
+ * a 12-prompt live bedrock sample returned 96/96 vector — so the floor change
+ * is safe as measured. But FTS quality is unmeasured; if FTS starts firing
+ * (e.g. as #205's fielded-BM25 retune beds in), give it its own eval.
+ */
 function passesRelevanceGate(r, minSimilarity) {
     if (r.source === "fts" || r.source === "both")
         return true;
     return typeof r.similarity === "number" && r.similarity >= minSimilarity;
 }
-/** Normalize a request-supplied privacy filter: array of strings or a CSV
+/** Normalize a request-supplied string-list param: array of strings or a CSV
  *  string → string[] | undefined. Anything else (or an empty result) means
- *  "no filter" — never a partial guess. */
-function parsePrivacyParam(v) {
+ *  "absent" — never a partial guess. Shared by `parsePrivacyParam` and
+ *  `mission_domains` (#203) so both accept `["A","B"]` and `"A, B"` alike. */
+function parseStringListParam(v) {
     const items = Array.isArray(v)
         ? v.filter((x) => typeof x === "string")
         : typeof v === "string"
@@ -110,6 +152,13 @@ function parsePrivacyParam(v) {
     const cleaned = items.map((s) => s.trim()).filter(Boolean);
     return cleaned.length > 0 ? cleaned : undefined;
 }
+/** Normalize a request-supplied privacy filter: array of strings or a CSV
+ *  string → string[] | undefined. Anything else (or an empty result) means
+ *  "no filter" — never a partial guess. Delegates to parseStringListParam;
+ *  kept as a named export for tests and handleMemoryGet callers. */
+function parsePrivacyParam(v) {
+    return parseStringListParam(v);
+}
 /**
  * Handle a /recall-index request body. Thin Express adapter in mcp-server.ts;
  * all behavior lives here so tests exercise it directly.
@@ -132,13 +181,18 @@ async function handleRecallIndex(deps, body) {
         return { status: 200, body: { block: null, skipped: "short-prompt" } };
     }
     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);
     const turn = deps.registry.beginTurn(sessionId);
-    // Optional client-side scoping (F1): project + privacy ride the body and
-    // are pushed into retrieval (which handles filtered over-fetch itself).
+    // Optional client-side scoping (F1 + #203): project + mission_domains (soft
+    // affinity) and privacy (hard filter) ride the body and are pushed into
+    // retrieval. project is cwd-derived (CC/OC) or gateway-supplied; mission_domains
+    // is Hermes-declared (plugin config). Neither excludes anything — both are
+    // zero-boost-neutral score terms in computeScore.
     const filters = {
         project: typeof req.project === "string" && req.project ? req.project : undefined,
         privacy: parsePrivacyParam(req.privacy),
+        mission_domains: parseStringListParam(req.mission_domains),
     };
     let results;
     try {
@@ -161,16 +215,18 @@ async function handleRecallIndex(deps, body) {
     deps.registry.markShown(sessionId, ids);
     // Exposure signal: shown_count + last_accessed refresh, NOT access_count.
     storage.touchMemoriesShown(deps.db, ids, new Date().toISOString());
-    const lines = picked.map((r) => formatIndexLine(r));
+    const lines = picked.map((r) => formatIndexLine(r, titleChars));
     const block = [
         "## Memory recall (auto)",
-        // Provenance is BUILT IN, split by function (owner decision 27.07,
-        // option D): this header carries only the SELECTION-time rules —
-        // supersession (the one moment competing dates are visible side by side)
-        // and cite-what-you-rely-on (covers snippet-only use, the common case per
-        // the 0.14.0 field test). The full citation format + origin agent ride on
-        // the hicortex_get response / GET /memory `citation` field (use-time).
-        "Possibly relevant memories — dates matter, newer supersedes older. Fetch full content with `hicortex_get(id)` when an entry could change your action; cite any memory you rely on (id, date):",
+        // Provenance is BUILT IN (owner decision 27.07, option D; extended #202/#204):
+        //   - #202: origin agent in each one-liner (formatIndexLine) — trust calibration.
+        //   - #204: confidence levels — FETCHED (read in full) vs SNIPPET (one-line entry only),
+        //     so "the agent cited a memory" can no longer pass as "the agent read it".
+        // This header carries the SELECTION-time rules: supersession (the one moment
+        // competing dates are visible side by side) and cite-with-confidence. The
+        // full citation format rides on the hicortex_get response / GET /memory
+        // `citation` field (use-time, marked FETCHED).
+        "Possibly relevant memories — dates matter, newer supersedes older. Fetch with `hicortex_get(id)` when an entry could change your action. Cite what you rely on by id + date, and mark it `FETCHED` if you read the full memory or `SNIPPET` if you're citing the one-line entry unread — don't pass a SNIPPET citation off as established fact.",
         ...lines,
     ].join("\n");
     return { status: 200, body: { block, shown: ids, turn } };
@@ -212,10 +268,33 @@ function handleMemoryGet(db, query) {
         status: 200,
         body: {
             memory: mem,
-            citation: `(memory ${String(mem.id).slice(0, 8)}, ${date}, from ${mem.source_agent ?? "unknown"})`,
+            citation: `(memory ${String(mem.id).slice(0, 8)}, ${date}, from ${mem.source_agent ?? "unknown"}, FETCHED)`,
         },
     };
 }
+/**
+ * MCP `hicortex_get` presentation: handleMemoryGet's result framed as the
+ * text block the MCP tool returns (provenance header + the SHARED citation +
+ * content). Extracted from the MCP tool handler so its output — incl. the
+ * #204 FETCHED marker, which rides on handleMemoryGet's citation — is unit-
+ * testable. The citation string is built ONCE (handleMemoryGet); this only
+ * frames it, mirroring how /recall-index is shared across harnesses. The
+ * extraction closes the #207 gap (CC's MCP path had a marker-less citation
+ * built inline, while the REST path used handleMemoryGet — same contract, two
+ * implementations, one updated).
+ */
+function formatMemoryGetText(db, query) {
+    const r = handleMemoryGet(db, query);
+    if (r.status !== 200) {
+        return { status: r.status, text: String(r.body.error ?? `No memory with id ${query.id ?? ""}`) };
+    }
+    const mem = r.body.memory;
+    const citation = r.body.citation; // carries FETCHED (#204)
+    const date = (mem.created_at ?? "").slice(0, 10);
+    const header = `[memory ${mem.id} | ${mem.memory_type ?? "episode"} | ${mem.project ?? "-"} | from ${mem.source_agent ?? "unknown"} | ${date}]\n` +
+        `Cite as ${citation} where this shapes your answer; it may be stale — newer memories supersede older.`;
+    return { status: 200, text: `${header}\n\n${mem.content ?? ""}` };
+}
 function clampInt(v, dflt, min, max) {
     const n = Number(v);
     if (!Number.isFinite(n))

package/dist/retrieval.d.ts

@@ -60,12 +60,28 @@ interface ScoringWeights {
     freshnessBoostDays: number;
     freshnessBoostWeight: number;
     supersededDemotion: number;
+    /** #203 soft affinity boost on exact project match. */
+    projectAffinity: number;
+    /** #203 soft affinity boost multiplier on max overlapping domain-tag weight. */
+    domainAffinity: number;
+    /** #205 RRF k parameter (1/(k+rank+1)). Larger ⇒ shallower rank curve. */
+    rrfK: number;
+    /** #205 composite-score share of the final blend (RRF gets the remainder). */
+    rrfCompositeWeight: number;
+    /** #205 per-list RRF weight for the FTS list (BM25-driven candidates). */
+    rrfFtsWeight: number;
+    /** #205 per-list RRF weight for the vector list (KNN-driven candidates). */
+    rrfVectorWeight: number;
 }
 /**
  * Configure scoring weights + ranking knobs from config. Called at boot by the
  * server and the nightly (alongside configureDecay/configureRecall) so
  * retrieval and consolidation rank identically. Invalid/absent values keep the
- * shipped default per key. Returns the resolved set for logging/tests.
+ * shipped default per key. Returns the resolved set for logging/tests. Also
+ * pushes the #205 BM25F field weights into storage (storage.configureBm25Fts)
+ * so searchFts ranks with the same config — BM25F weights live in storage.ts
+ * (next to the FTS column declaration they mirror) but are read here from the
+ * SAME config object for one-place tuning.
  */
 export declare function configureScoring(config?: Record<string, unknown> | null): ScoringWeights;
 /** Current resolved weights (tests + status output). */
@@ -127,9 +143,31 @@ export declare function effectiveStrength(baseStrength: number, lastAccessed: st
 /**
  * Return a composite relevance score in [0, 1] for a candidate memory.
  * Exported for exact-value tests of the similarity component (#145).
+ *
+ * #203 soft affinity (options.scope + options.tagWeights): two additive,
+ * graded, zero-boost-neutral terms — project affinity (exact project match)
+ * and domain affinity (max overlapping memory_tags.weight × scope). Both are
+ * 0 when the scope is absent (byte-identical to pre-#203) and NEVER negative
+ * (a foreign memory adds 0, never a penalty — penalties re-introduce
+ * soft-exclusion). See `AffinityScope`.
  */
+export interface AffinityScope {
+    /** Exact-match project from the client (CC/OC cwd-derived; /search project). */
+    project?: string | null;
+    /** Hermes mission domains declared in plugin config. Drawn from the same
+     *  vocabulary as memory_tags (config `domains`). */
+    missionDomains?: string[];
+}
 export declare function computeScore(memory: Memory, distance: number, connectionCount: number, maxConnections: number, now: Date, options?: {
     superseded?: boolean;
+    /** #203: when present, project/domain affinity boosts are applied. */
+    scope?: AffinityScope;
+    /** Candidate's graded domain tags (memory_tags rows). Loaded batched for
+     *  the whole candidate set in retrieve(); used for domain affinity. */
+    tagWeights?: Array<{
+        tag: string;
+        weight: number | null;
+    }>;
 }): number;
 export interface EmbedFn {
     (text: string): Promise<Float32Array>;
@@ -137,12 +175,25 @@ export interface EmbedFn {
 /**
  * Main retrieval: BM25 + vector search with RRF fusion, graph traversal,
  * and composite scoring. Strengthens accessed memories.
+ *
+ * #203 retrieval scoping: `project` and `missionDomains` are SOFT affinity
+ * terms in computeScore (zero-boost neutral, never a penalty), NOT filters.
+ * `privacy` remains a hard filter (security boundary). `sourceAgent` remains a
+ * hard filter (kept for completeness; no production caller currently passes
+ * it). When neither project nor missionDomains is sent, scoring is byte-
+ * identical to pre-#203 — the kill-switch / no-op guarantee.
  */
 export declare function retrieve(db: Database.Database, embedFn: EmbedFn, query: string, options?: {
     limit?: number;
+    /** #203: soft project affinity (exact match boost in computeScore).
+     *  Formerly a hard WHERE filter (#192); softening removes cross-scope
+     *  starvation without excluding anything. */
     project?: string | null;
     privacy?: string[];
     sourceAgent?: string;
+    /** #203: Hermes mission domains (declared in plugin config). Soft domain
+     *  affinity in computeScore via max overlapping memory_tags.weight. */
+    missionDomains?: string[];
     /** #192: skip access strengthening — for pushed recall (/recall-index),
      *  where appearing in results must not count as use. */
     noStrengthen?: boolean;