@gamaze/hicortex 0.15.2 → 0.16.0

package/dist/recall-index.js

@@ -56,9 +56,11 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.memoryTitle = memoryTitle;
 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;
@@ -87,7 +89,15 @@ function formatDate(iso) {
     return `${dd}.${mm}.${d.getFullYear()}`;
 }
 function formatIndexLine(r) {
-    const meta = [formatDate(r.created_at), r.domain ?? r.project ?? undefined, r.memory_type]
+    // 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})` : ""}`;
@@ -98,10 +108,11 @@ function passesRelevanceGate(r, minSimilarity) {
         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 +121,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.
@@ -134,15 +152,19 @@ async function handleRecallIndex(deps, body) {
     const maxItems = clampInt(deps.options?.maxItems, DEFAULT_MAX_ITEMS, 1, 20);
     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 {
-        results = await deps.retrieveFn(prompt, maxItems * CANDIDATE_MULTIPLIER, filters);
+        results = await deps.retrieveFn(prompt, maxItems * CANDIDATE_MULTIPLIER, filters, sessionId);
     }
     catch (err) {
         return {
@@ -164,13 +186,15 @@ async function handleRecallIndex(deps, body) {
     const lines = picked.map((r) => formatIndexLine(r));
     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)` only when relevant; 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 +236,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/recall-registry.d.ts

@@ -1,6 +1,7 @@
 /**
  * SessionRecallRegistry — per-session, TURN-based dedup for pushed recall
- * (#192, POST /recall-index).
+ * (#192, POST /recall-index), and owner of the session-intent rolling
+ * centroid (#192 session-intent keying, 0.15.3).
  *
  * Why turn-based, not time-based: suppression must track the session's
  * CONTEXT, not the wall clock. A multi-day CC session with a 1M window can
@@ -17,6 +18,19 @@
  *     SessionStart hook — which includes source=compact, i.e. after
  *     compaction the fresh context may legitimately re-receive everything).
  *
+ * Session-intent centroid (0.15.3): a rolling EMA of the session's prompt
+ * embeddings lives on SessionState. The recall path blends the current prompt
+ * with this centroid before the vector search so recall follows the session's
+ * intent instead of being query-literal. reset() deletes the whole session
+ * entry, so the centroid is cleared for free on SessionStart/compact — the
+ * next recall re-seeds.
+ *
+ * Concurrency: the registry assumes ONE in-flight recall per session at a time
+ * (CC's UserPromptSubmit fires once per turn; Hermes/OC plugins call per-turn
+ * too). Two concurrent same-session calls could race updateCentroid and drop
+ * one EMA step — harmless (self-correcting on the next turn) and not worth a
+ * lock for a path that does not fire concurrently in any current harness.
+ *
  * Purely in-memory: a server restart forgets shown-state, worst case a few
  * early re-shows (~15 tokens each) — harmless by design. Sessions are pruned
  * LRU beyond maxSessions so long-running servers don't accumulate state.
@@ -41,6 +55,30 @@ export declare class SessionRecallRegistry {
     markShown(sessionId: string, memoryIds: string[]): void;
     /** Forget a session's shown-set (SessionStart / compaction). */
     reset(sessionId: string): void;
+    /**
+     * Current session-intent centroid, or undefined when no prompt has seeded it
+     * yet (first turn / after a reset). The recall path reads this BEFORE
+     * updateCentroid to decide whether to blend — a missing centroid means
+     * "first turn, pure prompt, no behavior change".
+     */
+    getCentroid(sessionId: string): Float32Array | undefined;
+    /**
+     * Fold this turn's prompt embedding into the session-intent centroid via
+     * EMA: `centroid_new = l2Normalize((1-α)·centroid_old + α·prompt)`.
+     *
+     * First call (no centroid yet) SEEDS the centroid = l2Normalize(prompt) —
+     * this is the "after that first recall" step in the design: turn 1's search
+     * runs with pure prompt, then the centroid is seeded so turn 2+ can blend.
+     *
+     * `alpha` is the EMA rate (a shipped constant — retrieval.SESSION_INTENT_ALPHA,
+     * 0.4; NOT a config knob per the 0.15.3 scope). Callers (the recall closure)
+     * read it from retrieval.getSessionIntent(). We do not re-clamp here — the
+     * registry is a pure data owner, not a config interpreter.
+     *
+     * Returns the new centroid. The centroid lives on SessionState, so reset()
+     * (which deletes the session entry) clears it for free.
+     */
+    updateCentroid(sessionId: string, promptEmbedding: Float32Array, alpha: number): Float32Array;
     /** Number of tracked sessions (for /recall-index introspection + tests). */
     size(): number;
     private getOrCreate;

package/dist/recall-registry.js

@@ -1,7 +1,8 @@
 "use strict";
 /**
  * SessionRecallRegistry — per-session, TURN-based dedup for pushed recall
- * (#192, POST /recall-index).
+ * (#192, POST /recall-index), and owner of the session-intent rolling
+ * centroid (#192 session-intent keying, 0.15.3).
  *
  * Why turn-based, not time-based: suppression must track the session's
  * CONTEXT, not the wall clock. A multi-day CC session with a 1M window can
@@ -18,12 +19,26 @@
  *     SessionStart hook — which includes source=compact, i.e. after
  *     compaction the fresh context may legitimately re-receive everything).
  *
+ * Session-intent centroid (0.15.3): a rolling EMA of the session's prompt
+ * embeddings lives on SessionState. The recall path blends the current prompt
+ * with this centroid before the vector search so recall follows the session's
+ * intent instead of being query-literal. reset() deletes the whole session
+ * entry, so the centroid is cleared for free on SessionStart/compact — the
+ * next recall re-seeds.
+ *
+ * Concurrency: the registry assumes ONE in-flight recall per session at a time
+ * (CC's UserPromptSubmit fires once per turn; Hermes/OC plugins call per-turn
+ * too). Two concurrent same-session calls could race updateCentroid and drop
+ * one EMA step — harmless (self-correcting on the next turn) and not worth a
+ * lock for a path that does not fire concurrently in any current harness.
+ *
  * Purely in-memory: a server restart forgets shown-state, worst case a few
  * early re-shows (~15 tokens each) — harmless by design. Sessions are pruned
  * LRU beyond maxSessions so long-running servers don't accumulate state.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SessionRecallRegistry = exports.DEFAULT_RESHOW_TURNS = void 0;
+const schema_prototypes_js_1 = require("./schema-prototypes.js");
 exports.DEFAULT_RESHOW_TURNS = 30;
 const DEFAULT_MAX_SESSIONS = 500;
 class SessionRecallRegistry {
@@ -68,6 +83,42 @@ class SessionRecallRegistry {
     reset(sessionId) {
         this.sessions.delete(sessionId);
     }
+    /**
+     * Current session-intent centroid, or undefined when no prompt has seeded it
+     * yet (first turn / after a reset). The recall path reads this BEFORE
+     * updateCentroid to decide whether to blend — a missing centroid means
+     * "first turn, pure prompt, no behavior change".
+     */
+    getCentroid(sessionId) {
+        return this.sessions.get(sessionId)?.centroid;
+    }
+    /**
+     * Fold this turn's prompt embedding into the session-intent centroid via
+     * EMA: `centroid_new = l2Normalize((1-α)·centroid_old + α·prompt)`.
+     *
+     * First call (no centroid yet) SEEDS the centroid = l2Normalize(prompt) —
+     * this is the "after that first recall" step in the design: turn 1's search
+     * runs with pure prompt, then the centroid is seeded so turn 2+ can blend.
+     *
+     * `alpha` is the EMA rate (a shipped constant — retrieval.SESSION_INTENT_ALPHA,
+     * 0.4; NOT a config knob per the 0.15.3 scope). Callers (the recall closure)
+     * read it from retrieval.getSessionIntent(). We do not re-clamp here — the
+     * registry is a pure data owner, not a config interpreter.
+     *
+     * Returns the new centroid. The centroid lives on SessionState, so reset()
+     * (which deletes the session entry) clears it for free.
+     */
+    updateCentroid(sessionId, promptEmbedding, alpha) {
+        const s = this.getOrCreate(sessionId);
+        if (!s.centroid) {
+            s.centroid = (0, schema_prototypes_js_1.l2Normalize)(promptEmbedding);
+        }
+        else {
+            s.centroid = (0, schema_prototypes_js_1.l2Normalize)((0, schema_prototypes_js_1.weightedAdd)(s.centroid, 1 - alpha, promptEmbedding, alpha));
+        }
+        s.lastUsedAt = Date.now();
+        return s.centroid;
+    }
     /** Number of tracked sessions (for /recall-index introspection + tests). */
     size() {
         return this.sessions.size;

package/dist/retrieval.d.ts

@@ -60,16 +60,61 @@ 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). */
 export declare function getScoringWeights(): ScoringWeights;
+/** EMA rate for the session-intent centroid: centroid_new = (1-α)·old + α·prompt. */
+export declare const SESSION_INTENT_ALPHA = 0.4;
+/**
+ * Configure session-intent keying from config. Called at server boot next to
+ * configureScoring (the nightly does no recall, so it does not need this).
+ * Reads only `sessionIntentWeight` ([0,1]; 0 = disabled). Invalid/out-of-range
+ * values keep the shipped default. Returns `{ weight, alpha }` — alpha is the
+ * fixed constant, surfaced so the recall closure passes it to the registry in
+ * one call.
+ */
+export declare function configureSessionIntent(config?: Record<string, unknown> | null): {
+    weight: number;
+    alpha: number;
+};
+/** Current resolved session-intent weight + the shipped alpha (closure + tests). */
+export declare function getSessionIntent(): {
+    weight: number;
+    alpha: number;
+};
+/**
+ * Blend the prompt embedding with the session-intent centroid for the vector
+ * search: `query = l2Normalize((1-w)·prompt + w·centroid)`. Returns the prompt
+ * UNCHANGED when `centroid` is undefined (first turn — no behavior change) or
+ * `weight` is 0 (the kill-switch — pure prompt). Extracted from the
+ * /recall-index closure (mcp-server.ts) so the exact blend decision is
+ * unit-testable directly, locking the ternary against a refactor without a
+ * closure-integration harness.
+ */
+export declare function blendQueryVector(promptEmb: Float32Array, centroid: Float32Array | undefined, weight: number): 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
@@ -98,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>;
@@ -108,15 +175,35 @@ 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;
+    /** #192 session-intent keying (0.15.3): a pre-computed query embedding
+     *  (e.g. the session-centroid blend from the /recall-index closure). When
+     *  provided, the internal embed() call is SKIPPED — the caller owns the
+     *  one embed per recall. /search and other unblended callers omit this
+     *  and get pure-prompt behavior (the query string is embedded here). The
+     *  FTS path still uses the raw `query` text regardless. */
+    queryEmbedding?: Float32Array;
 }): Promise<MemorySearchResult[]>;
 /**
  * Get recent context, optionally filtered by project and privacy.