@gamaze/hicortex 0.15.1 → 0.15.3

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/init.js

@@ -31,6 +31,7 @@ exports.installRecallHooks = installRecallHooks;
 exports.runInit = runInit;
 exports.resolveNightlyHour = resolveNightlyHour;
 const paths_js_1 = require("./paths.js");
+const telemetry_js_1 = require("./telemetry.js");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
@@ -40,6 +41,24 @@ const node_crypto_1 = require("node:crypto");
 const claude_md_js_1 = require("./claude-md.js");
 const context_store_js_1 = require("./context-store.js");
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
+/** This package's version, for the install lifecycle ping (0.15.2). */
+function pkgVersion() {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "..", "package.json"), "utf-8")).version;
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+/** Read the just-written config so the install ping honours an opt-out. */
+function readHomeConfig(home) {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(home, "config.json"), "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
 const CC_SETTINGS = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "settings.json");
 const CC_COMMANDS_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "commands");
 const OC_CONFIG = (0, node_path_1.join)((0, node_os_1.homedir)(), ".openclaw", "openclaw.json");
@@ -1301,6 +1320,10 @@ async function runInit(options = {}) {
     console.log("Anonymous usage telemetry (aggregate counts only, no content) is on by default —");
     console.log("see exactly what is sent with `hicortex telemetry`; to opt out, add");
     console.log('"telemetry": false to ~/.hicortex/config.json or set HICORTEX_TELEMETRY=off.\n');
+    // Install ping (0.15.2) — sent AFTER the disclosure above, opt-out aware, so
+    // the install → first-nightly → retained funnel is measurable. Never blocks:
+    // failures are swallowed inside sendLifecycleEvent.
+    await (0, telemetry_js_1.sendLifecycleEvent)("install", HICORTEX_HOME, readHomeConfig(HICORTEX_HOME), pkgVersion());
     console.log("Next steps:");
     console.log("  1. Restart Claude Code to pick up the new MCP server and SessionStart hook");
     if (d.hermesFound) {
@@ -1471,6 +1494,10 @@ async function runClientInit(serverUrl, agentName) {
     console.log("Anonymous usage telemetry (aggregate counts only, no content) is on by default —");
     console.log("see exactly what is sent with `hicortex telemetry`; to opt out, add");
     console.log('"telemetry": false to ~/.hicortex/config.json or set HICORTEX_TELEMETRY=off.\n');
+    // Install ping (0.15.2) — sent AFTER the disclosure above, opt-out aware, so
+    // the install → first-nightly → retained funnel is measurable. Never blocks:
+    // failures are swallowed inside sendLifecycleEvent.
+    await (0, telemetry_js_1.sendLifecycleEvent)("install", HICORTEX_HOME, readHomeConfig(HICORTEX_HOME), pkgVersion());
     console.log("How it works:");
     console.log("  • MCP tools (search, context, ingest) talk to the remote server");
     console.log("  • Nightly pipeline denoises CC transcripts, POSTs to server for distillation");

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)
@@ -487,8 +487,15 @@ async function startServer(options = {}) {
     // so calibration is a config edit + restart, never a release.
     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}`);
+        `/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}` +
+        `, intent w=${sessionIntentCfg.weight}` +
+        (sessionIntentCfg.weight === 0 ? " (disabled)" : ""));
     recallRegistry = new recall_registry_js_1.SessionRecallRegistry({
         reshowTurns: savedConfig?.recallReshowTurns,
     });
@@ -664,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/nightly.js

@@ -214,6 +214,7 @@ async function runNightly(options = {}) {
     // the server's retrieval path (config decayHalfLifeDays, default 365).
     (0, retrieval_js_1.configureDecay)({ halfLifeDays: savedConfig?.decayHalfLifeDays });
     (0, retrieval_js_1.configureRecall)(savedConfig);
+    (0, retrieval_js_1.configureScoring)(savedConfig);
     const modeLabel = captureOnly ? " (capture-only)" : dryRun ? " (dry run)" : "";
     console.log(`[hicortex] Nightly pipeline starting${modeLabel}`);
     if (captureOnly) {
@@ -393,7 +394,6 @@ async function runNightly(options = {}) {
                 }, {
                     minSimilarity: savedConfig?.supersessionMinSimilarity,
                     maxCalls: savedConfig?.supersessionMaxCalls,
-                    penalty: savedConfig?.supersessionPenalty,
                 });
                 console.log(`[hicortex] Consolidation ${report.status} in ${report.elapsed_seconds}s` +
                     (report.stages.reflection ? ` (${report.stages.reflection.lessons_generated} lessons)` : ""));
@@ -436,6 +436,7 @@ async function runNightly(options = {}) {
                 id: (0, telemetry_js_1.getTelemetryId)(stateDir),
                 v: VERSION,
                 pv: telemetry_js_1.TELEMETRY_PAYLOAD_VERSION,
+                event: "nightly",
                 mode: "server",
                 agent: agentType,
                 mem: storage.countMemories(db),
@@ -568,6 +569,7 @@ async function runClientNightly(config, dryRun, stateDir = HICORTEX_HOME, recapt
             id: (0, telemetry_js_1.getTelemetryId)(stateDir),
             v: VERSION,
             pv: telemetry_js_1.TELEMETRY_PAYLOAD_VERSION,
+            event: "nightly",
             mode: "client",
             agent: agentType,
             mem: memoriesIngested,

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

@@ -2,8 +2,11 @@
  * Retrieval layer with composite scoring, RRF fusion, and graph traversal.
  * Ported from hicortex/retrieval.py — same scoring model and weights.
  *
- * Scoring model:
- *   score = similarity * 0.4 + effective_strength * 0.3 + connection_score * 0.2 + recency * 0.1
+ * Scoring model (weights are config-driven since 0.15.2 — see configureScoring):
+ *   score = similarity * 0.50 + effective_strength * 0.20
+ *         + connection_score * 0.15 + recency * 0.15
+ *         + fresh-memory bonus (≤ 0.15, linear over the first 7 days)
+ *         then × 0.50 if the memory was superseded by a later decision
  *
  * Decay model (B+E+D):
  *   base_decay = derived from decayHalfLifeDays (config; default 365 → ~1-year
@@ -49,6 +52,59 @@ interface RecallDefaults {
  * Returns the resolved values (for logging + tests).
  */
 export declare function configureRecall(config?: Record<string, unknown> | null): RecallDefaults;
+interface ScoringWeights {
+    similarity: number;
+    strength: number;
+    connections: number;
+    recency: number;
+    freshnessBoostDays: number;
+    freshnessBoostWeight: number;
+    supersededDemotion: 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.
+ */
+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
+ * old → new). One query, not per-candidate.
+ */
+export declare function findSupersededIds(db: Database.Database, candidateIds: string[]): Set<string>;
 /**
  * Convert an L2 distance (as returned by sqlite-vec's vec0 `distance`) to
  * cosine similarity. Valid because our embeddings are L2-normalized
@@ -72,7 +128,9 @@ 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).
  */
-export declare function computeScore(memory: Memory, distance: number, connectionCount: number, maxConnections: number, now: Date): number;
+export declare function computeScore(memory: Memory, distance: number, connectionCount: number, maxConnections: number, now: Date, options?: {
+    superseded?: boolean;
+}): number;
 export interface EmbedFn {
     (text: string): Promise<Float32Array>;
 }
@@ -88,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.