@gamaze/hicortex 0.15.2 → 0.15.3

package/README.md

@@ -225,6 +225,7 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `recallMinSimilarity` | Relevance floor for index entries (default: 0.55; text-search matches always pass) |
 | `recallReshowTurns` | Turns before an already-shown memory may reappear in the same session (default: 30) |
 | `recallMinPromptChars` | Prompts shorter than this skip the recall index (default: 20) |
+| `sessionIntentWeight` | Blend weight of the session-intent rolling centroid in the recall search vector: `query = (1-w)·prompt + w·centroid` (default: 0.33; set 0 to disable — pure-prompt recall, the kill-switch). The first turn of a session searches with pure prompt and seeds the centroid; subsequent turns blend so recall follows the session's intent instead of being query-literal. The EMA rate (0.4) is a shipped constant, not configurable |
 | `dedupMergeThreshold` | Minimum cosine similarity for `hicortex dedup` to cluster memories as near-duplicates (default: 0.92) |
 | `supersessionMinSimilarity` | Minimum cosine similarity for a nightly supersession candidate pair (default: 0.80) |
 | `supersessionMaxCalls` | Max classify-tier LLM calls the nightly's supersession stage spends per run (default: 30) |

package/dist/eval/recall-sweep.d.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * Recall@k sweep eval for session-intent keying (#192, commit 0867d6c).
+ *
+ * SHIP GATE: does blending the prompt with the per-session EMA centroid
+ * (retrieval.blendQueryVector) improve recall across rephrased turns, AND
+ * what does it COST when a session shifts topics mid-stream? Picks the
+ * default `sessionIntentWeight`.
+ *
+ * Two scenario families, same corpus:
+ *
+ *   FOCUSED — 6 sessions (one per topic), 4 turns each of GENUINE REPHRASES
+ *   of one intent. Tests the UPSIDE: does the centroid pull drifting
+ *   rephrases back on-topic? (recall@5 / p@5 should rise with w.)
+ *
+ *   SHIFT — 5 sessions, each 2 turns on topic A then 2 turns on topic B (a
+ *   clean mid-session topic change). Tests the DOWNSIDE that focused-only
+ *   can't see: a higher weight leaves the centroid partly A right after the
+ *   shift, so the first turn(s) on B may LAG (lower recall@5 for B). The
+ *   load-bearing read-out is post-shift recovery at turn-3 (first B turn)
+ *   and turn-4, plus turns-to-recover.
+ *
+ * Method (both families):
+ *   - Synthetic corpus of 30 memories across 6 well-separated topics (5 each),
+ *     embedded with the REAL bge-small-en-v1.5 model (the production embedder).
+ *   - For each weight w in {0.0, 0.2, 0.4, 0.5, 0.6, 0.8}: fresh
+ *     SessionRecallRegistry per session; per turn, embed the prompt ONCE,
+ *     blend with the live centroid, pass the blended vector to retrieve() via
+ *     queryEmbedding, record recall@5 + p@5 for the turn's CURRENT topic,
+ *     then fold the prompt into the centroid (EMA α=0.4).
+ *
+ * Fairness controls (load-bearing — the eval is useless if these slip):
+ *   - `noStrengthen: true` on every retrieve(): the DB stays STATIC across all
+ *     retrieve calls. Strengthening would mutate effective_strength/access_count
+ *     between runs and contaminate cross-weight comparisons.
+ *   - Uniform memory metadata: every memory has base_strength=0.5, created_at
+ *     ≈ now, access_count=0, and NO links. So effective_strength, recency,
+ *     connections, and the freshness boost are all uniform → the ONLY
+ *     discriminator is vector cosine + RRF rank. That isolates the blend.
+ *   - Cold-exposure slots are a no-op here (all candidates equally cold),
+ *     so the top-k is the plain score order.
+ *   - The centroid update is weight-INDEPENDENT (EMA of prompts at α=0.4), so
+ *     the per-turn centroid is identical across all weights for a given
+ *     session; only the blend differs. Embeddings are precomputed once.
+ *
+ * Metrics (per turn, for the turn's CURRENT topic):
+ *   - recall@5  — did >=1 same-topic memory surface in the top-5? (coarse; the
+ *     requested ship-gate metric — saturates on a small corpus.)
+ *   - p@5       — on-topic count in the top-5 (0..5, finer).
+ *   - recall@1  — was the SINGLE top result on-topic? (finest; focused only.)
+ *
+ * Honest by construction: it prints whatever the numbers are, including
+ * w=0 winning, the blend hurting a focused scenario, or high weights lagging
+ * badly post-shift. Report written to data/eval-recall-sweep/report.md and
+ * printed to stdout.
+ *
+ * Run:  npm run eval:recall-sweep   (==  node dist/eval/recall-sweep.js)
+ */
+export {};

package/dist/eval/recall-sweep.js

@@ -0,0 +1,715 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Recall@k sweep eval for session-intent keying (#192, commit 0867d6c).
+ *
+ * SHIP GATE: does blending the prompt with the per-session EMA centroid
+ * (retrieval.blendQueryVector) improve recall across rephrased turns, AND
+ * what does it COST when a session shifts topics mid-stream? Picks the
+ * default `sessionIntentWeight`.
+ *
+ * Two scenario families, same corpus:
+ *
+ *   FOCUSED — 6 sessions (one per topic), 4 turns each of GENUINE REPHRASES
+ *   of one intent. Tests the UPSIDE: does the centroid pull drifting
+ *   rephrases back on-topic? (recall@5 / p@5 should rise with w.)
+ *
+ *   SHIFT — 5 sessions, each 2 turns on topic A then 2 turns on topic B (a
+ *   clean mid-session topic change). Tests the DOWNSIDE that focused-only
+ *   can't see: a higher weight leaves the centroid partly A right after the
+ *   shift, so the first turn(s) on B may LAG (lower recall@5 for B). The
+ *   load-bearing read-out is post-shift recovery at turn-3 (first B turn)
+ *   and turn-4, plus turns-to-recover.
+ *
+ * Method (both families):
+ *   - Synthetic corpus of 30 memories across 6 well-separated topics (5 each),
+ *     embedded with the REAL bge-small-en-v1.5 model (the production embedder).
+ *   - For each weight w in {0.0, 0.2, 0.4, 0.5, 0.6, 0.8}: fresh
+ *     SessionRecallRegistry per session; per turn, embed the prompt ONCE,
+ *     blend with the live centroid, pass the blended vector to retrieve() via
+ *     queryEmbedding, record recall@5 + p@5 for the turn's CURRENT topic,
+ *     then fold the prompt into the centroid (EMA α=0.4).
+ *
+ * Fairness controls (load-bearing — the eval is useless if these slip):
+ *   - `noStrengthen: true` on every retrieve(): the DB stays STATIC across all
+ *     retrieve calls. Strengthening would mutate effective_strength/access_count
+ *     between runs and contaminate cross-weight comparisons.
+ *   - Uniform memory metadata: every memory has base_strength=0.5, created_at
+ *     ≈ now, access_count=0, and NO links. So effective_strength, recency,
+ *     connections, and the freshness boost are all uniform → the ONLY
+ *     discriminator is vector cosine + RRF rank. That isolates the blend.
+ *   - Cold-exposure slots are a no-op here (all candidates equally cold),
+ *     so the top-k is the plain score order.
+ *   - The centroid update is weight-INDEPENDENT (EMA of prompts at α=0.4), so
+ *     the per-turn centroid is identical across all weights for a given
+ *     session; only the blend differs. Embeddings are precomputed once.
+ *
+ * Metrics (per turn, for the turn's CURRENT topic):
+ *   - recall@5  — did >=1 same-topic memory surface in the top-5? (coarse; the
+ *     requested ship-gate metric — saturates on a small corpus.)
+ *   - p@5       — on-topic count in the top-5 (0..5, finer).
+ *   - recall@1  — was the SINGLE top result on-topic? (finest; focused only.)
+ *
+ * Honest by construction: it prints whatever the numbers are, including
+ * w=0 winning, the blend hurting a focused scenario, or high weights lagging
+ * badly post-shift. Report written to data/eval-recall-sweep/report.md and
+ * printed to stdout.
+ *
+ * Run:  npm run eval:recall-sweep   (==  node dist/eval/recall-sweep.js)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const db_js_1 = require("../db.js");
+const storage = __importStar(require("../storage.js"));
+const embedder_js_1 = require("../embedder.js");
+const retrieval_js_1 = require("../retrieval.js");
+const recall_registry_js_1 = require("../recall-registry.js");
+const TOPICS = ["auth", "database", "ui", "deploy", "testing", "networking"];
+/**
+ * 30 memories, 5 per topic. Each 2-4 sentences of concrete on-topic prose.
+ * Generic verbs/adjectives (fix, broken, failed, wrong, timeout, test) recur
+ * ACROSS topics to create realistic cross-topic competition for the top-5 —
+ * without that, recall@5 trivially saturates at 1.0 and the eval can't
+ * discriminate.
+ */
+const CORPUS = [
+    // --- auth (login / authentication / OAuth / sessions) ---
+    {
+        topic: "auth",
+        text: "Debugging the login form: the password field validation rejected valid credentials because the regex was too strict. Users with special characters in their passwords couldn't authenticate. Relaxed the character class and re-ran the auth test suite.",
+    },
+    {
+        topic: "auth",
+        text: "OAuth 2.0 token refresh flow: the refresh token wasn't persisted to the session store, so users got logged out after an hour. Moved token persistence into the auth middleware so it survives across requests.",
+    },
+    {
+        topic: "auth",
+        text: "Session management bug: the JWT expiry claim was set in seconds but the library expected milliseconds, causing immediate token invalidation. Every authenticated request returned 401 right after login.",
+    },
+    {
+        topic: "auth",
+        text: "Password reset endpoint: the email token was signed with the wrong secret, so reset links 404'd on confirmation. Regenerated the secret and invalidated all outstanding reset tokens.",
+    },
+    {
+        topic: "auth",
+        text: "Rate limiting on the login route: brute-force attempts locked out real users because the limiter counted by IP and the office NAT shares one address. Switched to per-account limiting with a CAPTCHA fallback.",
+    },
+    // --- database (SQL / Postgres / ORM / queries) ---
+    {
+        topic: "database",
+        text: "Slow query on the orders table: a missing index on created_at made the dashboard date-range scan do a full table scan. Added a composite index on (user_id, created_at) and the query dropped from 4s to 12ms.",
+    },
+    {
+        topic: "database",
+        text: "Postgres connection pool exhaustion: the ORM wasn't releasing connections after read transactions, so the pool hit its ceiling under load and requests queued. Added explicit transaction boundaries and a leak detector.",
+    },
+    {
+        topic: "database",
+        text: "N+1 query in the catalog serializer: each product fetched its categories separately, generating hundreds of round trips. Rewrote it as a single JOIN and used the ORM's eager-load hint.",
+    },
+    {
+        topic: "database",
+        text: "SQL migration deadlock: two deployments ran ALTER TABLE concurrently and Postgres serialized them, timing out the second. Switched to advisory locks in the migration runner.",
+    },
+    {
+        topic: "database",
+        text: "Wrong aggregate results: the revenue report double-counted refunded orders because the JOIN to the refunds table didn't exclude cancelled refunds. Added a status filter and a regression test.",
+    },
+    // --- ui (frontend / CSS / layout / rendering) ---
+    {
+        topic: "ui",
+        text: "Broken grid layout on Safari: CSS grid's auto-fit collapsed to a single column because the minmax lower bound was zero. Set a sensible minimum and added a flexbox fallback for older browsers.",
+    },
+    {
+        topic: "ui",
+        text: "Button not rendering: the component's conditional render checked a prop that was undefined rather than null, so the truthy branch never fired. Standardized on nullish coalescing across the component tree.",
+    },
+    {
+        topic: "ui",
+        text: "Responsive nav overflow: the hamburger menu pushed content off-screen on phones in landscape because the viewport meta tag was missing. Added the meta tag and a max-width on the header.",
+    },
+    {
+        topic: "ui",
+        text: "Theme flash on load: the CSS variables weren't set before the first paint, causing a white-then-dark flicker. Inlined the theme bootstrap script in the document head.",
+    },
+    {
+        topic: "ui",
+        text: "Form validation UX: error messages appeared on every keystroke, which felt jarring. Debounced the validation to fire on blur, or after the user paused typing.",
+    },
+    // --- deploy (CI / release / rollback) ---
+    {
+        topic: "deploy",
+        text: "Deploy failed at the asset compilation step: webpack ran out of memory on the CI runner. Raised the Node heap to 4GB and split the vendor bundle so the build stays under the limit.",
+    },
+    {
+        topic: "deploy",
+        text: "GitHub Actions workflow broke after the runner image updated: the preinstalled Python changed minor versions and our pinned dependency wouldn't install. Pinned the toolchain explicitly in the workflow.",
+    },
+    {
+        topic: "deploy",
+        text: "Blue-green deploy rollback: the new version had a migration that wasn't backward-compatible, so rolling back left half the schema on the new version. Added a deploy-time migration compatibility check.",
+    },
+    {
+        topic: "deploy",
+        text: "Container registry rate limit: CI pulled the base image on every run and hit Docker Hub's anonymous pull cap. Set up a pull-through cache and authenticated the registry.",
+    },
+    {
+        topic: "deploy",
+        text: "Canary deploy caught a memory leak: the new build's steady-state RSS crept up under synthetic traffic. The canary's OOM-kills metric failed the promotion gate and the deploy auto-rolled back.",
+    },
+    // --- testing (unit / integration / TDD) ---
+    {
+        topic: "testing",
+        text: "Flaky integration test: the test assumed a clean database but ran in parallel with the orders suite, so it saw phantom rows. Gave each test its own schema and a transactional rollback fixture.",
+    },
+    {
+        topic: "testing",
+        text: "Unit test for the pricing module: the pure-function test didn't cover the bulk-discount branch. Added cases for the boundary quantities and a property-based test for rounding.",
+    },
+    {
+        topic: "testing",
+        text: "Mocking the database in tests: the suite hit a real Postgres and timed out in CI. Introduced a repository seam and swapped in an in-memory fake for the fast path.",
+    },
+    {
+        topic: "testing",
+        text: "Test suite runtime: the full suite took nine minutes, mostly from synchronous waits. Parallelized with a sharded runner and dropped the wall clock to under two minutes.",
+    },
+    {
+        topic: "testing",
+        text: "Snapshot test churn: every cosmetic change updated fifty snapshots and reviewers stopped reading them. Replaced the brittle snapshots with explicit assertions on the relevant fields.",
+    },
+    // --- networking (HTTP / API / CORS / webhooks) ---
+    {
+        topic: "networking",
+        text: "API returning 500s: the upstream service started sending a new error envelope and our deserializer threw on the unknown field. Switched to lenient parsing and added a regression test for the new shape.",
+    },
+    {
+        topic: "networking",
+        text: "CORS preflight failing: the OPTIONS handler didn't echo back the request's Origin header, so browsers blocked the response. Fixed the header reflection and tightened the allowed-methods list.",
+    },
+    {
+        topic: "networking",
+        text: "HTTP request timeout: the client's default timeout was 30s but the upstream's P99 was 45s under load. Tuned the timeout per endpoint and added a circuit breaker for sustained failures.",
+    },
+    {
+        topic: "networking",
+        text: "Webhook delivery failures: retries used a fixed delay and the receiving endpoint rate-limited us after the first burst. Moved to exponential backoff with jitter and a dead-letter queue.",
+    },
+    {
+        topic: "networking",
+        text: "TLS handshake errors: the server's certificate chain was missing the intermediate, so mobile clients failed the trust check. Bundled the full chain in the PEM and renewed via ACME.",
+    },
+];
+/**
+ * 4-turn rephrase set per topic — GENUINE REPHRASES of one intent: same
+ * meaning, different surface wording, deliberately spanning terse/oblique to
+ * descriptive. The vocabulary shift is the focused-scenario fairness lever
+ * (pure-prompt ranking should plausibly move turn-to-turn). Turn order is a
+ * realistic session flow; the EMA centroid (α=0.4) weights the most recent
+ * turn most and retains geometrically-decaying signal from earlier ones, so
+ * ordering a strong matcher early keeps it in the centroid as turns accumulate.
+ * (The shipped default 0.33 sits in the eval-supported 0.3–0.4 band but is
+ * not swept directly — the sweep validates the band, not the exact default.)
+ *
+ * Shift sessions reuse turns[0..1] of A then turns[0..1] of B — so the same
+ * rephrases drive both families (no separate, easier shift corpus).
+ */
+const FOCUSED_TURNS = {
+    auth: [
+        "fix the login bug", // terse; "login" lexical, "bug" generic
+        "why is authentication failing", // "authenticate" vs "login"; "failing" generic
+        "the signin page is broken", // "signin"/"page" loose; "broken" generic
+        "users can't log in", // terse; "log in" vs "login"/"authenticate"
+    ],
+    database: [
+        "the database query is slow", // direct: "query"/"slow"
+        "optimize this SQL statement", // "SQL"/"optimize" vs "slow"
+        "postgres is returning wrong results", // "postgres"/"wrong" generic
+        "the ORM is generating bad queries", // "ORM"/"queries"
+    ],
+    ui: [
+        "the layout is broken on mobile", // "layout"/"mobile"; "broken" generic
+        "fix the CSS grid", // "CSS"/"grid"
+        "the button doesn't render", // "button"/"render"
+        "responsive design is off", // "responsive"; "off" terse/generic
+    ],
+    deploy: [
+        "the deploy failed", // terse; "deploy"/"failed" generic
+        "CI pipeline is red", // "CI"; "red" = failing
+        "the GitHub Actions workflow broke", // "GitHub Actions"/"workflow"/"broke"
+        "rollback the production release", // "rollback"/"release"
+    ],
+    testing: [
+        "write a unit test for this", // "unit test"
+        "the test suite is flaky", // "test suite"/"flaky"
+        "fix the failing assertion", // "assertion"; "failing" generic
+        "mock the database in tests", // "mock"/"tests"
+    ],
+    networking: [
+        "the API returns 500 errors", // "API"/"500"
+        "fix the CORS issue", // "CORS"; "issue" generic
+        "the HTTP request times out", // "HTTP"/"times out"
+        "webhook delivery is failing", // "webhook"; "failing" generic
+    ],
+};
+/**
+ * Shift pairs: 2 turns on A → 2 turns on B. A and B are deliberately different
+ * so the A-seeded centroid actively opposes the first B turn(s) at high w.
+ * Five pairs cover each topic once or twice on each side of a shift.
+ */
+const SHIFT_PAIRS = [
+    ["auth", "database"],
+    ["ui", "deploy"],
+    ["testing", "networking"],
+    ["database", "ui"],
+    ["deploy", "testing"],
+];
+const WEIGHTS = [0.0, 0.2, 0.4, 0.5, 0.6, 0.8];
+function buildSessions() {
+    const focused = TOPICS.map((t) => ({
+        kind: "focused",
+        id: `focused-${t}`,
+        label: t,
+        turns: FOCUSED_TURNS[t].map((p) => ({ prompt: p, topic: t })),
+    }));
+    const shifts = SHIFT_PAIRS.map(([a, b], i) => ({
+        kind: "shift",
+        id: `shift-${i}-${a}-${b}`,
+        label: `${a}->${b}`,
+        topicA: a,
+        topicB: b,
+        turns: [
+            { prompt: FOCUSED_TURNS[a][0], topic: a },
+            { prompt: FOCUSED_TURNS[a][1], topic: a },
+            { prompt: FOCUSED_TURNS[b][0], topic: b },
+            { prompt: FOCUSED_TURNS[b][1], topic: b },
+        ],
+    }));
+    return [...focused, ...shifts];
+}
+// ---------------------------------------------------------------------------
+// DB construction
+// ---------------------------------------------------------------------------
+async function buildCorpusDb(dbPath) {
+    const db = (0, db_js_1.initDb)(dbPath);
+    const idToTopic = new Map();
+    for (const mem of CORPUS) {
+        const vec = await (0, embedder_js_1.embed)(mem.text);
+        const id = storage.insertMemory(db, mem.text, vec, {
+            sourceAgent: "eval-corpus",
+            memoryType: "episode",
+            baseStrength: 0.5, // uniform — strength is NOT a discriminator here
+        });
+        idToTopic.set(id, mem.topic);
+    }
+    return { db, idToTopic };
+}
+/** Embed every distinct prompt once; return a cache keyed by prompt text. */
+async function embedAllPrompts(sessions) {
+    const cache = new Map();
+    for (const s of sessions) {
+        for (const t of s.turns) {
+            if (!cache.has(t.prompt))
+                cache.set(t.prompt, await (0, embedder_js_1.embed)(t.prompt));
+        }
+    }
+    return cache;
+}
+/**
+ * Run the full sweep. Prompts are pre-embedded once (the centroid update is
+ * weight-independent, so the per-turn centroid is identical across weights;
+ * only the blend differs). A fresh SessionRecallRegistry per (weight,session)
+ * keeps each centroid seeded only by that session's own turns.
+ */
+async function runSweep(db, idToTopic, sessions) {
+    const promptEmb = await embedAllPrompts(sessions);
+    // Fail-explicit embedFn: we ALWAYS supply queryEmbedding, so retrieve()
+    // must never call this. If it does, the sweep is measuring the wrong thing.
+    const neverCalledEmbed = async () => {
+        throw new Error("recall-sweep: retrieve() called the embedFn — queryEmbedding was not honored. Eval aborted (results would be invalid).");
+    };
+    const records = [];
+    for (const w of WEIGHTS) {
+        for (const s of sessions) {
+            const registry = new recall_registry_js_1.SessionRecallRegistry();
+            const sessionId = `w${w}-${s.id}`;
+            for (let i = 0; i < s.turns.length; i++) {
+                const turnDef = s.turns[i];
+                const promptText = turnDef.prompt;
+                const promptVec = promptEmb.get(promptText);
+                const centroid = registry.getCentroid(sessionId);
+                const queryVec = (0, retrieval_js_1.blendQueryVector)(promptVec, centroid, w);
+                const results = await (0, retrieval_js_1.retrieve)(db, neverCalledEmbed, promptText, {
+                    limit: 5,
+                    queryEmbedding: queryVec,
+                    noStrengthen: true,
+                });
+                const topIds = results.map((r) => r.id);
+                const onTopic = topIds.filter((id) => idToTopic.get(id) === turnDef.topic);
+                const topTopic = topIds.length > 0 ? idToTopic.get(topIds[0]) : undefined;
+                records.push({
+                    weight: w,
+                    sessionId: s.id,
+                    kind: s.kind,
+                    label: s.label,
+                    topicA: s.topicA,
+                    topicB: s.topicB,
+                    turn: i + 1,
+                    currentTopic: turnDef.topic,
+                    recallAt5: onTopic.length > 0 ? 1 : 0,
+                    recallAt1: topTopic === turnDef.topic ? 1 : 0,
+                    precisionAt5: onTopic.length,
+                    topIds,
+                });
+                // Fold this prompt into the centroid AFTER the search (seeds on turn 1,
+                // blends after). α is the shipped constant.
+                registry.updateCentroid(sessionId, promptVec, retrieval_js_1.SESSION_INTENT_ALPHA);
+            }
+        }
+    }
+    return records;
+}
+// ---------------------------------------------------------------------------
+// Aggregation helpers
+// ---------------------------------------------------------------------------
+function avg(rs, field) {
+    if (rs.length === 0)
+        return 0;
+    return rs.reduce((s, r) => s + r[field], 0) / rs.length;
+}
+function pct(x) {
+    return `${(x * 100).toFixed(1)}%`;
+}
+function fmtW(w) {
+    return w.toFixed(1);
+}
+function summarizeFocused(records, sessions) {
+    const focusedSessions = sessions.filter((s) => s.kind === "focused");
+    return WEIGHTS.map((w) => {
+        const wr = records.filter((r) => r.weight === w && r.kind === "focused");
+        const turnN = (n) => wr.filter((r) => r.turn === n);
+        const byScenario = focusedSessions.map((s) => avg(wr.filter((r) => r.sessionId === s.id), "recallAt5"));
+        return {
+            weight: w,
+            recallAt5All: avg(wr, "recallAt5"),
+            recallAt5Turn1: avg(turnN(1), "recallAt5"),
+            recallAt5Turn4: avg(turnN(4), "recallAt5"),
+            recallAt1All: avg(wr, "recallAt1"),
+            precisionAt5All: avg(wr, "precisionAt5"),
+            byScenario,
+        };
+    });
+}
+function summarizeShift(records) {
+    return WEIGHTS.map((w) => {
+        const wr = records.filter((r) => r.weight === w && r.kind === "shift");
+        const pre = wr.filter((r) => r.turn <= 2);
+        const t3 = wr.filter((r) => r.turn === 3);
+        const t4 = wr.filter((r) => r.turn === 4);
+        // Recovery per session: recall@5 for B at turn 3 (and turn 4).
+        const sessionLabels = Array.from(new Set(wr.map((r) => r.sessionId)));
+        let recByT3 = 0;
+        let recByT4 = 0;
+        for (const sid of sessionLabels) {
+            const t3r = wr.find((r) => r.sessionId === sid && r.turn === 3);
+            const t4r = wr.find((r) => r.sessionId === sid && r.turn === 4);
+            if (t3r && t3r.recallAt5 === 1)
+                recByT3++;
+            if ((t3r && t3r.recallAt5 === 1) || (t4r && t4r.recallAt5 === 1))
+                recByT4++;
+        }
+        const n = sessionLabels.length || 1;
+        return {
+            weight: w,
+            preRecallAt5: avg(pre, "recallAt5"),
+            prePrecisionAt5: avg(pre, "precisionAt5"),
+            postT3RecallAt5: avg(t3, "recallAt5"),
+            postT3PrecisionAt5: avg(t3, "precisionAt5"),
+            postT4RecallAt5: avg(t4, "recallAt5"),
+            postT4PrecisionAt5: avg(t4, "precisionAt5"),
+            recoveredByT3: recByT3 / n,
+            recoveredByT4: recByT4 / n,
+        };
+    });
+}
+function renderReport(focused, shifts, records, sessions, meta) {
+    const L = [];
+    const nFocused = sessions.filter((s) => s.kind === "focused").length;
+    const nShift = sessions.filter((s) => s.kind === "shift").length;
+    L.push("# Recall@k Sweep — session-intent keying (#192, 0867d6c)\n");
+    L.push(`Corpus: ${meta.memoryCount} memories across ${TOPICS.length} topics (5 each), embedded with the ` +
+        `real bge-small-en-v1.5 model. ${nFocused} focused scenarios x 4 turns + ${nShift} shift scenarios ` +
+        `x 4 turns (2 on A -> 2 on B).\n`);
+    L.push("_Static DB across all retrieve() calls (`noStrengthen: true`); uniform memory metadata " +
+        "(base_strength=0.5, created_at~now, no links) so vector cosine + RRF is the only discriminator; " +
+        "cold-exposure slots are a no-op (all candidates equally cold). Centroid EMA at α=0.4. " +
+        "Per-turn metrics are vs the turn's CURRENT topic (A then B for shifts)._\n");
+    // ---- 1. Focused ----
+    L.push("## 1. Focused recall@5 / p@5 by weight (upside)\n");
+    L.push("Does the centroid pull same-intent rephrases back on-topic? recall@5 = >=1 on-topic in top-5; " +
+        "recall@1 = TOP result on-topic; p@5 = mean on-topic count in top-5 (0..5).\n");
+    L.push("| weight | recall@5 (all) | recall@5 turn-1 | recall@5 turn-4 | recall@1 (all) | p@5 (all) |");
+    L.push("|---|---|---|---|---|---|");
+    for (const s of focused) {
+        L.push(`| ${fmtW(s.weight)} | ${pct(s.recallAt5All)} | ${pct(s.recallAt5Turn1)} | ${pct(s.recallAt5Turn4)} | ${pct(s.recallAt1All)} | ${s.precisionAt5All.toFixed(2)} |`);
+    }
+    L.push("");
+    const f0 = focused.find((s) => s.weight === 0);
+    const fOthers = focused.filter((s) => s.weight > 0);
+    const fBestOverall = focused.reduce((a, b) => (b.recallAt5All > a.recallAt5All + 1e-9 ? b : a));
+    const fBeatR5 = fOthers.some((s) => s.recallAt5All > f0.recallAt5All + 1e-9);
+    const fBeatR1 = fOthers.some((s) => s.recallAt1All > f0.recallAt1All + 1e-9);
+    const fBeatP5 = fOthers.some((s) => s.precisionAt5All > f0.precisionAt5All + 1e-9);
+    L.push("### Focused verdict\n");
+    L.push(`- Best overall recall@5: w=${fmtW(fBestOverall.weight)} (${pct(fBestOverall.recallAt5All)})`);
+    L.push(`- Any w>0 beat w=0 on recall@5: **${fBeatR5 ? "YES" : "NO"}**`);
+    L.push(`- Any w>0 beat w=0 on recall@1: **${fBeatR1 ? "YES" : "NO"}**`);
+    L.push(`- Any w>0 beat w=0 on p@5: **${fBeatP5 ? "YES" : "NO"}**`);
+    // Focused regressions (blend hurt a focused scenario vs w=0)
+    const fRegs = [];
+    for (let si = 0; si < focused[0].byScenario.length; si++) {
+        const v0 = focused.find((x) => x.weight === 0).byScenario[si];
+        for (const s of focused) {
+            if (s.weight === 0)
+                continue;
+            const v = s.byScenario[si];
+            if (v < v0 - 1e-9) {
+                const lbl = sessions.filter((x) => x.kind === "focused")[si].label;
+                fRegs.push(`- ${lbl} at w=${fmtW(s.weight)}: ${pct(v)} vs w=0 ${pct(v0)}`);
+            }
+        }
+    }
+    L.push(`- Focused regressions (blend HURT vs w=0): ${fRegs.length > 0 ? fRegs.join("; ") : "_(none)_"}\n`);
+    // ---- 2. Shift recovery ----
+    L.push("## 2. Shift recovery by weight (downside)\n");
+    L.push("2 turns on topic A, then 2 turns on topic B (clean mid-session shift). Metrics are vs the turn's " +
+        "CURRENT topic. **Turn-3 = first turn on B, right after the shift** — the load-bearing read-out: " +
+        "a higher weight leaves the centroid partly A, so B recall@5 should DROP at high w. Turn-4 = second " +
+        "B turn — has the EMA recovered toward B?\n");
+    L.push("| weight | pre recall@5 (A, t1-2) | pre p@5 | **post recall@5 (B, t3)** | post p@5 (t3) | post recall@5 (B, t4) | post p@5 (t4) | recovered by t3 | recovered by t4 |");
+    L.push("|---|---|---|---|---|---|---|---|---|");
+    for (const s of shifts) {
+        L.push(`| ${fmtW(s.weight)} | ${pct(s.preRecallAt5)} | ${s.prePrecisionAt5.toFixed(2)} | ` +
+            `**${pct(s.postT3RecallAt5)}** | ${s.postT3PrecisionAt5.toFixed(2)} | ` +
+            `${pct(s.postT4RecallAt5)} | ${s.postT4PrecisionAt5.toFixed(2)} | ` +
+            `${pct(s.recoveredByT3)} | ${pct(s.recoveredByT4)} |`);
+    }
+    L.push("");
+    // Per-shift-scenario post-shift recall@5 (turn-3) by weight — where does lag show up?
+    L.push("### Per-shift-scenario post-shift recall@5 (first turn on B = turn-3)\n");
+    L.push("Each cell = recall@5 for the NEW topic at the first post-shift turn. w=0 column = pure-prompt baseline (no centroid lag). Drops below the w=0 column = the centroid LAGGING the shift.\n");
+    const shiftSessions = sessions.filter((s) => s.kind === "shift");
+    const head = ["shift (A->B)", ...WEIGHTS.map((w) => `w=${fmtW(w)}`)];
+    L.push("| " + head.join(" | ") + " |");
+    L.push("|" + head.map(() => "---").join("|") + "|");
+    for (const s of shiftSessions) {
+        const cells = WEIGHTS.map((w) => {
+            const rec = records.find((r) => r.weight === w && r.kind === "shift" && r.sessionId === s.id && r.turn === 3);
+            return rec && rec.recallAt5 === 1 ? "1" : "0";
+        });
+        L.push(`| ${s.label} | ${cells.join(" | ")} |`);
+    }
+    L.push("");
+    // Shift verdict — does any weight lag vs w=0?
+    const sh0 = shifts.find((s) => s.weight === 0);
+    const laggersT3 = [];
+    const laggersT4 = [];
+    for (const s of shifts) {
+        if (s.weight === 0)
+            continue;
+        if (s.postT3RecallAt5 < sh0.postT3RecallAt5 - 1e-9) {
+            laggersT3.push(`w=${fmtW(s.weight)}: ${pct(s.postT3RecallAt5)} (vs w=0 ${pct(sh0.postT3RecallAt5)}, −${(sh0.postT3RecallAt5 - s.postT3RecallAt5).toFixed(2)})`);
+        }
+        if (s.postT4RecallAt5 < sh0.postT4RecallAt5 - 1e-9) {
+            laggersT4.push(`w=${fmtW(s.weight)}: ${pct(s.postT4RecallAt5)} (vs w=0 ${pct(sh0.postT4RecallAt5)}, −${(sh0.postT4RecallAt5 - s.postT4RecallAt5).toFixed(2)})`);
+        }
+    }
+    L.push("### Shift verdict\n");
+    L.push(`- Baseline (w=0) post-shift recall@5: turn-3 ${pct(sh0.postT3RecallAt5)}, turn-4 ${pct(sh0.postT4RecallAt5)}`);
+    L.push(`- Weights that LAG at turn-3 (B recall@5 < w=0): ${laggersT3.length > 0 ? laggersT3.join("; ") : "_(none — no shift lag at any weight)_"}`);
+    L.push(`- Weights still lagging at turn-4: ${laggersT4.length > 0 ? laggersT4.join("; ") : "_(none — all recovered by turn-4)_"}\n`);
+    // ---- 3. Combined verdict ----
+    L.push("## 3. Combined verdict (focused upside vs shift cost)\n");
+    L.push("Two recommendations, deliberately side by side. recall@5 is BINARY (>=1 on-topic) so it hides the " +
+        "steady p@5 erosion the shift table shows — read both. The p@5-aware pick is the finer signal.\n");
+    // (a) recall@5-based: highest weight with NO turn-3 recall@5 lag AND maximal
+    // focused recall@5. Coarse — a weight can pass this while halving the
+    // on-topic count in the top-5 (p@5), because one survivor still flips
+    // recall@5 to 1.
+    const noLagT3 = shifts.filter((s) => s.postT3RecallAt5 >= sh0.postT3RecallAt5 - 1e-9);
+    const noLagWeights = noLagT3.map((s) => s.weight).filter((w) => w > 0);
+    const focusedCeiling = Math.max(...focused.map((s) => s.recallAt5All));
+    const r5Cands = noLagWeights.filter((w) => {
+        const f = focused.find((x) => x.weight === w);
+        return f.recallAt5All >= focusedCeiling - 1e-9;
+    });
+    const recR5 = r5Cands.length > 0 ? Math.max(...r5Cands) : null;
+    // (b) p@5-aware: among weights that capture the focused p@5 upside (within
+    // 5% of the plateau), pick the one with the HIGHEST turn-3 shift p@5 (least
+    // shift cost). p@5 is non-saturating on this corpus, so this respects BOTH
+    // the focused upside and the shift cost — the recommendation to actually ship.
+    const p5Plateau = Math.max(...focused.map((s) => s.precisionAt5All));
+    const p5Cands = WEIGHTS.filter((w) => w > 0 &&
+        focused.find((x) => x.weight === w).precisionAt5All >= 0.95 * p5Plateau - 1e-9);
+    let recP5 = null;
+    let bestT3p5 = -Infinity;
+    for (const w of p5Cands) {
+        const t3p5 = shifts.find((x) => x.weight === w).postT3PrecisionAt5;
+        if (t3p5 > bestT3p5 + 1e-9) {
+            bestT3p5 = t3p5;
+            recP5 = w;
+        }
+    }
+    L.push(`- **recall@5-based recommendation: w=${recR5 !== null ? fmtW(recR5) : "n/a"}** — highest weight with ` +
+        `no turn-3 recall@5 lag and maximal focused recall@5 (${pct(focusedCeiling)}). Coarse: it does NOT ` +
+        `see the p@5 erosion.`);
+    L.push(`- **p@5-aware recommendation: w=${recP5 !== null ? fmtW(recP5) : "n/a"}** — among weights capturing ` +
+        `>=95% of the focused p@5 plateau (${p5Plateau.toFixed(2)}), the one with the highest turn-3 shift ` +
+        `p@5 (${bestT3p5.toFixed(2)} on-topic in the top-5 at the first post-shift turn). This is the pick ` +
+        `that respects both upside and shift cost.\n`);
+    // Plain-English summary line — honest about the divergence.
+    const maxLagT3r5 = Math.max(0, ...shifts.filter((s) => s.weight > 0).map((s) => sh0.postT3RecallAt5 - s.postT3RecallAt5));
+    // Worst p@5 erosion at turn-3 vs the w=0 baseline (the finer, earlier signal).
+    const maxP5drop = Math.max(0, ...shifts
+        .filter((s) => s.weight > 0)
+        .map((s) => sh0.postT3PrecisionAt5 - s.postT3PrecisionAt5));
+    const diverge = recR5 !== null && recP5 !== null && Math.abs(recR5 - recP5) > 1e-9;
+    let plain;
+    if (!fBeatR5 && !fBeatR1 && !fBeatP5 && maxLagT3r5 <= 0 && maxP5drop <= 0) {
+        plain =
+            "The blend shows no focused benefit and no shift cost — on this corpus it is a no-op. w=0 is the honest default.";
+    }
+    else if (diverge) {
+        plain =
+            `The recall@5-based pick (w=${fmtW(recR5)}) and the p@5-aware pick (w=${fmtW(recP5)}) DIVERGE — ` +
+                `recall@5 stays at 100% through w=${fmtW(recR5)} but p@5 at the first post-shift turn erodes steadily ` +
+                `(down up to ${maxP5drop.toFixed(2)} on-topic memories in the top-5 vs w=0), and collapses at w=0.8 ` +
+                `(recall@5 ${pct(shifts.find((s) => s.weight === 0.8).postT3RecallAt5)} — the new topic misses the ` +
+                `top-5 entirely in 3/5 shift scenarios). The finer metric argues for the lower default w=${fmtW(recP5)}: ` +
+                `it captures the focused upside (p@5 within 5% of plateau) with the least shift cost. Ship w=${fmtW(recP5)}.`;
+    }
+    else if (maxLagT3r5 > 0) {
+        plain =
+            `The blend buys focused recall but costs recall@5 lag at turn-3 at the highest weight ` +
+                `(up to −${maxLagT3r5.toFixed(2)}). Recommended w=${recP5 !== null ? fmtW(recP5) : recR5 !== null ? fmtW(recR5) : "?"} keeps the upside without the lag.`;
+    }
+    else {
+        plain =
+            `The blend helps focused recall with NO recall@5 shift lag at any tested weight — ship a non-zero ` +
+                `default (recommended w=${recP5 !== null ? fmtW(recP5) : recR5 !== null ? fmtW(recR5) : "0.4"}).`;
+    }
+    L.push(`**${plain}**\n`);
+    // Sanity: w=0 per-turn recall@5 for focused (did pure-prompt actually diverge?)
+    L.push("## Appendix: w=0 per-turn recall@5 — did pure-prompt diverge across rephrases?\n");
+    L.push("| scenario | turn-1 | turn-2 | turn-3 | turn-4 |");
+    L.push("|---|---|---|---|---|");
+    for (const s of sessions.filter((x) => x.kind === "focused")) {
+        const cells = [1, 2, 3, 4].map((n) => {
+            const r = records.find((r) => r.weight === 0 && r.sessionId === s.id && r.turn === n);
+            return r.recallAt5 === 1 ? "1" : "0";
+        });
+        L.push(`| ${s.label} | ${cells.join(" | ")} |`);
+    }
+    L.push("");
+    return L.join("\n");
+}
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+async function main() {
+    // Pin all module-level knobs to shipped defaults so a host config can't
+    // leak into the sweep. The blend weight is varied per-run via blendQueryVector
+    // directly (NOT via configureSessionIntent), so the global sessionIntentWeight
+    // is irrelevant here.
+    (0, retrieval_js_1.configureScoring)();
+    (0, retrieval_js_1.configureDecay)();
+    (0, retrieval_js_1.configureRecall)();
+    (0, retrieval_js_1.configureSessionIntent)();
+    const sessions = buildSessions();
+    const tmpDir = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `hicortex-recall-sweep-${(0, node_crypto_1.randomUUID)().slice(0, 8)}`);
+    (0, node_fs_1.mkdirSync)(tmpDir, { recursive: true });
+    const dbPath = (0, node_path_1.join)(tmpDir, "sweep.db");
+    const reportDir = (0, node_path_1.join)(process.cwd(), "data", "eval-recall-sweep");
+    console.log(`[recall-sweep] temp DB: ${dbPath}`);
+    console.log(`[recall-sweep] report dir: ${reportDir}`);
+    console.log(`[recall-sweep] ${sessions.filter((s) => s.kind === "focused").length} focused + ` +
+        `${sessions.filter((s) => s.kind === "shift").length} shift sessions; ` +
+        `${WEIGHTS.length} weights = ${sessions.length * WEIGHTS.length} sweeps x 4 turns = ` +
+        `${sessions.length * WEIGHTS.length * 4} retrieves`);
+    let db = null;
+    try {
+        console.log("[recall-sweep] building corpus (embedding 30 memories)...");
+        const t0 = Date.now();
+        const { db: opened, idToTopic } = await buildCorpusDb(dbPath);
+        db = opened;
+        console.log(`[recall-sweep] corpus ready in ${Date.now() - t0}ms (${idToTopic.size} memories)`);
+        console.log("[recall-sweep] running sweep...");
+        const t1 = Date.now();
+        const records = await runSweep(db, idToTopic, sessions);
+        console.log(`[recall-sweep] sweep done in ${Date.now() - t1}ms (${records.length} turn records)`);
+        const focused = summarizeFocused(records, sessions);
+        const shifts = summarizeShift(records);
+        const report = renderReport(focused, shifts, records, sessions, {
+            memoryCount: CORPUS.length,
+        });
+        (0, node_fs_1.mkdirSync)(reportDir, { recursive: true });
+        const reportPath = (0, node_path_1.join)(reportDir, "report.md");
+        (0, node_fs_1.writeFileSync)(reportPath, report, "utf-8");
+        console.log("\n" + report);
+        console.log(`[recall-sweep] report written to ${reportPath}`);
+    }
+    finally {
+        if (db) {
+            try {
+                db.close();
+            }
+            catch { /* already closed */ }
+        }
+        if ((0, node_fs_1.existsSync)(tmpDir)) {
+            try {
+                (0, node_fs_1.rmSync)(tmpDir, { recursive: true, force: true });
+            }
+            catch { /* non-fatal */ }
+        }
+    }
+}
+main().catch((err) => {
+    console.error("[recall-sweep] FAILED:", err instanceof Error ? err.stack : String(err));
+    process.exitCode = 1;
+});

package/dist/index.js

@@ -378,7 +378,7 @@ exports.default = {
         }), { name: "hicortex_search" });
         api.registerTool((_ctx) => ({
             name: "hicortex_get",
-            description: "Fetch ONE memory's full content by id — use this to lazy-load entries from the '## Memory recall (auto)' index or from search results whose snippet was not enough. Fetching a memory marks it as used (strengthens it), so only fetch what you actually need. When the memory shapes your answer, cite it as given in the response.",
+            description: "Fetch ONE memory's full content by id — use this to lazy-load entries from the '## Memory recall (auto)' index or from search results whose snippet was not enough. Fetching a memory marks it as used (strengthens it), so fetch entries that could change your action — not every shown one. When the memory shapes your answer, cite it as given in the response.",
             parameters: {
                 type: "object",
                 properties: {

package/dist/mcp-server.js

@@ -128,7 +128,7 @@ function createMcpServer() {
         }
     });
     // -- hicortex_get --
-    server.tool("hicortex_get", "Fetch ONE memory's full content by id — use this to lazy-load entries from the '## Memory recall (auto)' index or from search results whose snippet was not enough. Fetching a memory marks it as used (strengthens it), so only fetch what you actually need. When the memory shapes your answer, cite it to the user (id + date + origin agent).", {
+    server.tool("hicortex_get", "Fetch ONE memory's full content by id — use this to lazy-load entries from the '## Memory recall (auto)' index or from search results whose snippet was not enough. Fetching a memory marks it as used (strengthens it), so fetch entries that could change your action — not every shown one. When the memory shapes your answer, cite it to the user (id + date + origin agent).", {
         id: zod_1.z.string().describe("Memory id (as shown in recall index/search results)"),
     }, async ({ id }) => {
         if (!db)
@@ -488,11 +488,14 @@ async function startServer(options = {}) {
     retrieval.configureDecay({ halfLifeDays: savedConfig?.decayHalfLifeDays });
     const recallCfg = retrieval.configureRecall(savedConfig);
     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} · ` +
         `score sim=${scoringCfg.similarity}/str=${scoringCfg.strength}/conn=${scoringCfg.connections}` +
         `/rec=${scoringCfg.recency}, fresh=${scoringCfg.freshnessBoostWeight}@${scoringCfg.freshnessBoostDays}d, ` +
-        `superseded×${scoringCfg.supersededDemotion}`);
+        `superseded×${scoringCfg.supersededDemotion}` +
+        `, intent w=${sessionIntentCfg.weight}` +
+        (sessionIntentCfg.weight === 0 ? " (disabled)" : ""));
     recallRegistry = new recall_registry_js_1.SessionRecallRegistry({
         reshowTurns: savedConfig?.recallReshowTurns,
     });
@@ -668,12 +671,29 @@ async function startServer(options = {}) {
             registry: recallRegistry,
             // Client-pushed project/privacy scoping (F1) rides through to
             // retrieval, which handles the filtered over-fetch itself.
-            retrieveFn: (query, limit, filters) => retrieval.retrieve(db, embedder_js_1.embed, query, {
-                limit,
-                noStrengthen: true,
-                project: filters?.project,
-                privacy: filters?.privacy,
-            }),
+            // #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,
+                    project: filters?.project,
+                    privacy: filters?.privacy,
+                    queryEmbedding: queryVec,
+                });
+            },
             options: recallIndexOptions,
         }, req.body);
         res.status(r.status).json(r.body);

package/dist/memory-instructions.js

@@ -31,7 +31,7 @@ exports.MEMORY_SECTION_NAME = "memory";
 function renderMemoryInstructions() {
     return [
         "Your long-term memory is Hicortex — shared across all agents and sessions.",
-        "- A `## Memory recall (auto)` index may arrive with prompts: it is a MENU, not content. Fetch a full memory with `hicortex_get(id)` only when the entry is relevant to your current task.",
+        "- A `## Memory recall (auto)` index may arrive with prompts: it is a MENU, not content. Fetch a full memory with `hicortex_get(id)` when the entry could change how you handle the current task.",
         "- Recall before assuming: `hicortex_search` for prior decisions/facts/preferences, `hicortex_recent` to catch up on a project.",
         "- Cite any memory you rely on (id, date); on conflicts, newer memories supersede older.",
         "- Capture is automatic (nightly). Do not manually ingest routine content — `hicortex_ingest` is for explicitly requested learnings only.",

package/dist/recall-index.d.ts

@@ -52,7 +52,10 @@ export interface RecallFilters {
 export interface RecallIndexDeps {
     db: Database.Database;
     registry: SessionRecallRegistry;
-    retrieveFn: (query: string, limit: number, filters?: RecallFilters) => Promise<MemorySearchResult[]>;
+    /** 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[]>;
     options?: RecallIndexOptions;
 }
 /** Normalize a request-supplied privacy filter: array of strings or a CSV

package/dist/recall-index.js

@@ -142,7 +142,7 @@ async function handleRecallIndex(deps, body) {
     };
     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 {
@@ -170,7 +170,7 @@ async function handleRecallIndex(deps, body) {
         // 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):",
+        "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):",
         ...lines,
     ].join("\n");
     return { status: 200, body: { block, shown: ids, turn } };

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

@@ -70,6 +70,35 @@ interface ScoringWeights {
 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
@@ -117,6 +146,13 @@ export declare function retrieve(db: Database.Database, embedFn: EmbedFn, query:
     /** #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.

package/dist/retrieval.js

@@ -52,12 +52,15 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_DECAY_HALF_LIFE_DAYS = void 0;
+exports.SESSION_INTENT_ALPHA = exports.DEFAULT_DECAY_HALF_LIFE_DAYS = void 0;
 exports.decayConstantForHalfLife = decayConstantForHalfLife;
 exports.configureDecay = configureDecay;
 exports.configureRecall = configureRecall;
 exports.configureScoring = configureScoring;
 exports.getScoringWeights = getScoringWeights;
+exports.configureSessionIntent = configureSessionIntent;
+exports.getSessionIntent = getSessionIntent;
+exports.blendQueryVector = blendQueryVector;
 exports.findSupersededIds = findSupersededIds;
 exports.l2ToCosine = l2ToCosine;
 exports.effectiveStrength = effectiveStrength;
@@ -65,6 +68,7 @@ exports.computeScore = computeScore;
 exports.retrieve = retrieve;
 exports.searchRecent = searchRecent;
 const storage = __importStar(require("./storage.js"));
+const schema_prototypes_js_1 = require("./schema-prototypes.js");
 /** Default decay half-life (days) at importance 0.5. #192: was 0.0005/h
  *  (~115-day half-life at base 0.5) — aggressive enough to bury the long tail
  *  in ranking. Long-term remembering is the product; time preference stays,
@@ -152,6 +156,59 @@ function configureScoring(config) {
 function getScoringWeights() {
     return { ...scoringWeights };
 }
+// ---------------------------------------------------------------------------
+// Session-intent keying (#192, 0.15.3). ONE config knob:
+//   sessionIntentWeight  0.33  blend weight of the rolling centroid in the
+//                              search vector: query = (1-w)·prompt + w·centroid.
+//                              0 = DISABLED (pure prompt, the kill-switch —
+//                              current behavior). Range [0, 1].
+//
+// The EMA rate α is a shipped constant (SESSION_INTENT_ALPHA, 0.4), not a
+// second knob — owner directive 0.15.3: one knob is enough to tune/disable;
+// exposing α was speculative generality.
+//
+// The centroid itself lives on SessionRecallRegistry; retrieval only needs to
+// ACCEPT a pre-blended query vector (options.queryEmbedding) so the recall
+// closure can do the one-embed-per-recall + blend without retrieve()
+// re-embedding. /search and other unblended callers omit queryEmbedding and
+// get pure-prompt behavior unchanged.
+// ---------------------------------------------------------------------------
+/** EMA rate for the session-intent centroid: centroid_new = (1-α)·old + α·prompt. */
+exports.SESSION_INTENT_ALPHA = 0.4;
+const SESSION_INTENT_DEFAULT_WEIGHT = 0.33;
+let sessionIntentWeight = SESSION_INTENT_DEFAULT_WEIGHT;
+/**
+ * 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.
+ */
+function configureSessionIntent(config) {
+    const v = Number(config?.sessionIntentWeight);
+    sessionIntentWeight =
+        Number.isFinite(v) && v >= 0 && v <= 1 ? v : SESSION_INTENT_DEFAULT_WEIGHT;
+    return { weight: sessionIntentWeight, alpha: exports.SESSION_INTENT_ALPHA };
+}
+/** Current resolved session-intent weight + the shipped alpha (closure + tests). */
+function getSessionIntent() {
+    return { weight: sessionIntentWeight, alpha: exports.SESSION_INTENT_ALPHA };
+}
+/**
+ * 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.
+ */
+function blendQueryVector(promptEmb, centroid, weight) {
+    return centroid && weight > 0
+        ? (0, schema_prototypes_js_1.l2Normalize)((0, schema_prototypes_js_1.weightedAdd)(promptEmb, 1 - weight, centroid, weight))
+        : promptEmb;
+}
 /**
  * Ids among `candidateIds` that have been superseded by a later memory — i.e.
  * they are the SOURCE of a `superseded_by` link (stageSupersession links
@@ -370,8 +427,8 @@ async function retrieve(db, embedFn, query, options) {
     const privacy = options?.privacy;
     const sourceAgent = options?.sourceAgent;
     const now = new Date();
-    // 1. Embed
-    const queryEmbedding = await embedFn(query);
+    // 1. Embed — or reuse the caller-provided vector (session-intent blend).
+    const queryEmbedding = options?.queryEmbedding ?? (await embedFn(query));
     // 2. Dual retrieval — vector + BM25.
     // #192: sqlite-vec can't push filters into the KNN, so filtered queries must
     // over-fetch — the old flat limit*3 intersected a global top-15 with (for the

package/dist/schema-prototypes.d.ts

@@ -38,6 +38,21 @@ export declare function blobToVec(buf: Buffer): Float32Array;
  * is returned as an all-zero copy rather than dividing by zero.
  */
 export declare function l2Normalize(vec: Float32Array): Float32Array;
+/**
+ * Weighted sum of two vectors into a NEW Float32Array (inputs untouched). The
+ * result is NOT renormalized — callers normalize explicitly via `l2Normalize`
+ * when they need a unit vector (both call sites below do, because embeddings
+ * are L2-normalized and the blend must stay on the unit sphere to keep cosine
+ * meaningful). Throws on a dimension mismatch rather than silently truncating:
+ * the embedding dim is fixed at 384 in practice, so a mismatch signals a
+ * mid-process model swap or a bug, which must surface (CLAUDE.md: fail
+ * explicitly), not get quietly papered over.
+ *
+ * Used by the session-intent centroid EMA and the recall query blend (#192
+ * session-intent keying): `weightedAdd(a, 1-α, b, α)` is the EMA step,
+ * `weightedAdd(prompt, 1-w, centroid, w)` is the blended search vector.
+ */
+export declare function weightedAdd(a: Float32Array, wA: number, b: Float32Array, wB: number): Float32Array;
 /**
  * Association weight of a memory for a tag = cosine(memory embedding, domain
  * prototype). Both inputs are L2-normalized (embedder.ts normalizes memory

package/dist/schema-prototypes.js

@@ -28,6 +28,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PROTOTYPE_MIN_MEMBERS = void 0;
 exports.blobToVec = blobToVec;
 exports.l2Normalize = l2Normalize;
+exports.weightedAdd = weightedAdd;
 exports.tagWeight = tagWeight;
 exports.compartmentSet = compartmentSet;
 exports.derivePrimary = derivePrimary;
@@ -70,6 +71,29 @@ function l2Normalize(vec) {
         out[i] = vec[i] / norm;
     return out;
 }
+/**
+ * Weighted sum of two vectors into a NEW Float32Array (inputs untouched). The
+ * result is NOT renormalized — callers normalize explicitly via `l2Normalize`
+ * when they need a unit vector (both call sites below do, because embeddings
+ * are L2-normalized and the blend must stay on the unit sphere to keep cosine
+ * meaningful). Throws on a dimension mismatch rather than silently truncating:
+ * the embedding dim is fixed at 384 in practice, so a mismatch signals a
+ * mid-process model swap or a bug, which must surface (CLAUDE.md: fail
+ * explicitly), not get quietly papered over.
+ *
+ * Used by the session-intent centroid EMA and the recall query blend (#192
+ * session-intent keying): `weightedAdd(a, 1-α, b, α)` is the EMA step,
+ * `weightedAdd(prompt, 1-w, centroid, w)` is the blended search vector.
+ */
+function weightedAdd(a, wA, b, wB) {
+    if (a.length !== b.length) {
+        throw new Error(`weightedAdd: dimension mismatch (${a.length} vs ${b.length}) — expected equal-length L2-normalized embeddings`);
+    }
+    const out = new Float32Array(a.length);
+    for (let i = 0; i < a.length; i++)
+        out[i] = a[i] * wA + b[i] * wB;
+    return out;
+}
 /**
  * Association weight of a memory for a tag = cosine(memory embedding, domain
  * prototype). Both inputs are L2-normalized (embedder.ts normalizes memory

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.15.2",
+  "version": "0.15.3",
   "description": "Self-learning memory for AI agents — experience captured automatically, distilled into lessons overnight, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, and Pi.",
   "main": "dist/index.js",
   "bin": {
@@ -38,6 +38,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "eval": "node dist/eval/run-eval.js",
+    "eval:recall-sweep": "node dist/eval/recall-sweep.js",
     "prepack": "npm run build && rm -rf ./hermes-plugin && mkdir -p ./hermes-plugin && cp -r ../../hermes-plugin/hicortex ./hermes-plugin/ && find ./hermes-plugin -name __pycache__ -type d -exec rm -rf {} + 2>/dev/null || true",
     "prepublishOnly": "npm run build && rm -rf ./hermes-plugin && mkdir -p ./hermes-plugin && cp -r ../../hermes-plugin/hicortex ./hermes-plugin/ && find ./hermes-plugin -name __pycache__ -type d -exec rm -rf {} + 2>/dev/null || true"
   },