@unblocklabs/unblock-memory 0.3.30 → 0.5.0

package/README.md

@@ -41,7 +41,7 @@ Optional installation from source:
 | [Search and reads](docs/retrieval.md#search-and-read) | Vector recall, then exact indexed source reads | Available with the memory plugin; files only unless more corpora are configured |
 | [Session indexing](docs/retrieval.md#sessions) | Makes past user/assistant exchanges searchable | Opt-in corpus; channel/group by default, DMs explicitly included |
 | [Skill Whisperer](docs/retrieval.md#skill-whisperer) | Suggests one relevant skill; never invokes it | Off; explicit skills corpus; TypeSafe optional |
-| [Memory Whisperer](docs/retrieval.md#memory-whisperer) | Injects up to two useful historical excerpts | Off; approved corpora + TypeSafe |
+| [Memory Whisperer](docs/retrieval.md#memory-whisperer) | Injects up to two useful historical excerpts; query generation via resident API | Off; approved corpora + TypeSafe + query API credential |
 | [People dossiers](docs/peoplesql.md) | Stores agent-authored, evidence-backed recognition snippets | Off; `people.enabled` |
 | [People Primer](docs/peoplesql.md#optional-people-dossier-primer) | Selects evidence and reviews proposed blurbs; never generates/saves dossiers itself | Off; people + approved corpora + TypeSafe |
 | [People Whisperer](docs/peoplesql.md#injection-and-person-state) | Injects a saved blurb for an exact Slack identity | Off; separate global/per-person gates; no model call |
@@ -66,8 +66,8 @@ They have separate configuration/index boundaries. See
 - [Response audit](docs/response-audit.md): operator commands, cadence, sentiment,
   evidence-linked reports and their limits.
 - [Memory training](docs/memory-training.md): resumable, operator-only conversation
-  collection, TypeSafe recall gating, xhigh Luna queries and conversation-only grading of historical QMD hits
-  for the LFM query-generator project.
+  collection, TypeSafe recall gating, independent lex/vector Luna candidates, one
+  score-feedback revision, and the runtime's shared passage grader for LFM targets.
 
 The shared TypeSafe integration defaults on, but its features are opt-in.
 A key activates only features already enabled. Ordinary search and People

package/dist/src/config.d.ts

@@ -64,14 +64,13 @@ export type UnblockMemoryConfig = {
         enabled: boolean;
         complementaryHints: boolean;
         corpora: readonly string[];
-        historyMessages: number;
         minUsefulness: number;
         maxHints: number;
         cooldownTurns: number;
         timeoutMs: number;
-        mlx?: {
-            pythonPath: string;
-            modelPath: string;
+        api: {
+            endpoint: string;
+            apiKeyFile?: string;
         };
     };
 };

package/dist/src/config.js

@@ -81,18 +81,43 @@ const DEFAULT_SKILL_WHISPERER = {
     cooldownTurns: 10,
 };
 const DEFAULT_MEMORY_WHISPERER = {
-    enabled: false, complementaryHints: false, corpora: [], historyMessages: 5, minUsefulness: 0.7,
+    enabled: false, complementaryHints: false, corpora: [], minUsefulness: 0.7,
     maxHints: 2, cooldownTurns: 10, timeoutMs: 3000,
+    api: { endpoint: "http://192.168.1.191:18087" },
 };
+function resolveQueryApi(value) {
+    if (value === undefined)
+        return { ...DEFAULT_MEMORY_WHISPERER.api };
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("memoryWhisperer.api must be an object");
+    const config = value;
+    assertOnlyKeys(config, ["endpoint", "apiKeyFile"], "memoryWhisperer.api");
+    const endpoint = config.endpoint ?? DEFAULT_MEMORY_WHISPERER.api.endpoint;
+    let url;
+    try {
+        url = new URL(typeof endpoint === "string" ? endpoint : "");
+    }
+    catch {
+        throw new Error("memoryWhisperer.api.endpoint must be an HTTP(S) URL");
+    }
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+        throw new Error("memoryWhisperer.api.endpoint must be an HTTP(S) URL without credentials, query or fragment");
+    }
+    const apiKeyFile = config.apiKeyFile;
+    if (apiKeyFile !== undefined && (typeof apiKeyFile !== "string" || !isAbsolute(apiKeyFile))) {
+        throw new Error("memoryWhisperer.api.apiKeyFile must be an absolute path");
+    }
+    return { endpoint: url.href.replace(/\/$/u, ""), ...(apiKeyFile ? { apiKeyFile } : {}) };
+}
 function resolveMemoryWhisperer(value, corpora) {
     if (value === undefined)
-        return { ...DEFAULT_MEMORY_WHISPERER };
+        return { ...DEFAULT_MEMORY_WHISPERER, api: resolveQueryApi(undefined) };
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw new Error("unblock-memory memoryWhisperer must be an object");
     }
     const config = value;
     assertOnlyKeys(config, [...Object.keys(DEFAULT_MEMORY_WHISPERER), "mlx"], "memoryWhisperer");
-    let mlx;
+    // Accept old fleet configs during migration, but never launch a local worker.
     if (config.mlx !== undefined) {
         if (!config.mlx || typeof config.mlx !== "object" || Array.isArray(config.mlx))
             throw new Error("memoryWhisperer.mlx must be an object");
@@ -102,7 +127,6 @@ function resolveMemoryWhisperer(value, corpora) {
             typeof value.modelPath !== "string" || !isAbsolute(value.modelPath)) {
             throw new Error("memoryWhisperer.mlx requires absolute pythonPath and modelPath");
         }
-        mlx = { pythonPath: value.pythonPath, modelPath: value.modelPath };
     }
     const enabled = config.enabled ?? false;
     if (typeof enabled !== "boolean")
@@ -116,11 +140,7 @@ function resolveMemoryWhisperer(value, corpora) {
     }
     if (enabled && !selected.length)
         throw new Error("unblock-memory enabled memoryWhisperer requires explicit corpora");
-    const historyMessages = config.historyMessages ?? 5;
     const cooldownTurns = config.cooldownTurns ?? 10;
-    if (typeof historyMessages !== "number" || !Number.isInteger(historyMessages) || historyMessages < 0 || historyMessages > 50) {
-        throw new Error("unblock-memory memoryWhisperer.historyMessages must be an integer between 0 and 50");
-    }
     if (typeof cooldownTurns !== "number" || !Number.isInteger(cooldownTurns) || cooldownTurns < 0 || cooldownTurns > 1000) {
         throw new Error("unblock-memory memoryWhisperer.cooldownTurns must be an integer between 0 and 1000");
     }
@@ -129,10 +149,10 @@ function resolveMemoryWhisperer(value, corpora) {
         throw new Error("unblock-memory memoryWhisperer.minUsefulness must be between 0 and 1");
     }
     return {
-        enabled, complementaryHints, corpora: [...new Set(selected)], historyMessages, cooldownTurns, minUsefulness,
+        enabled, complementaryHints, corpora: [...new Set(selected)], cooldownTurns, minUsefulness,
         maxHints: positiveInteger(config.maxHints, 2, "memoryWhisperer.maxHints", 2),
         timeoutMs: positiveInteger(config.timeoutMs, 3000, "memoryWhisperer.timeoutMs", 10_000),
-        ...(mlx ? { mlx } : {}),
+        api: resolveQueryApi(config.api),
     };
 }
 function assertOnlyKeys(value, allowed, label) {
@@ -281,7 +301,7 @@ export function resolveConfig(value) {
             peoplePrimer: resolvePeoplePrimer(undefined, DEFAULT_CORPORA, false),
             people: DEFAULT_PEOPLE_CONFIG,
             skillWhisperer: DEFAULT_SKILL_WHISPERER,
-            memoryWhisperer: { ...DEFAULT_MEMORY_WHISPERER },
+            memoryWhisperer: { ...DEFAULT_MEMORY_WHISPERER, api: resolveQueryApi(undefined) },
         };
     }
     if (typeof value !== "object" || Array.isArray(value)) {

package/dist/src/diagnostics.d.ts

@@ -1,6 +1,6 @@
 import { RetrievalTelemetry } from "./retrieval-telemetry.js";
 type Whisperer = "skill" | "memory";
-type Outcome = "missing_key" | "typesafe_disabled" | "no_candidates" | "rejected" | "cooldown" | "emitted" | "failed" | "timed_out" | "cancelled" | "unavailable" | "payload_limit" | "redundancy_unavailable" | "recall_not_needed" | "queries_generated" | "query_fallback" | "judge_candidate_failed";
+type Outcome = "missing_key" | "typesafe_disabled" | "no_candidates" | "rejected" | "cooldown" | "emitted" | "failed" | "timed_out" | "cancelled" | "unavailable" | "payload_limit" | "redundancy_unavailable" | "recall_not_needed" | "queries_generated" | "judge_candidate_failed";
 /** Process-local, content-free and bounded. Agent IDs are keys, never included in snapshots. */
 export declare class WhispererDiagnostics {
     #private;
@@ -23,7 +23,6 @@ export declare class WhispererDiagnostics {
             redundancy_unavailable?: number | undefined;
             recall_not_needed?: number | undefined;
             queries_generated?: number | undefined;
-            query_fallback?: number | undefined;
             judge_candidate_failed?: number | undefined;
         };
         memory: {
@@ -41,7 +40,6 @@ export declare class WhispererDiagnostics {
             redundancy_unavailable?: number | undefined;
             recall_not_needed?: number | undefined;
             queries_generated?: number | undefined;
-            query_fallback?: number | undefined;
             judge_candidate_failed?: number | undefined;
         };
         telemetry: {

package/dist/src/manager.d.ts

@@ -1,15 +1,16 @@
-import type { QMDStore, VectorSearchResult } from "@unblocklabs/qmd";
+import type { QMDStore } from "@unblocklabs/qmd";
 import { type AnalysisRunner, type MemoryAnalysisSummary, type MemoryClusterDetail, type MemoryClusterList, type MemoryClusterSort, type MemoryReclusterOptions } from "./analysis.js";
 import type { CorpusMemorySearchResult, CorpusSearchOptions, MemoryEmbeddingProbeResult, MemoryProviderStatus, MemoryReadResult, MemoryRequestContext, MemorySearchManagerContract, MemorySyncParams } from "./contracts.js";
 import type { ChatType } from "./config.js";
 import { type MaintenanceStatus, type MaintenanceTask, type TemporalBasis } from "./curation.js";
 import { type SessionSyncResult } from "./session-sync.js";
-import { type SessionMessageSpan } from "./session-projector.js";
 import { type ResolvedSource } from "./sources.js";
 import { type QualityCursor } from "./quality-audit.js";
 import { qualityTaskPresence } from "./quality-triage.js";
 import { reviewIndexedClaim } from "./evidence-review.js";
 import { reviewClusterIngestion } from "./cluster-review.js";
+import type { QueryPair } from "./query-contract.js";
+export { expandSessionSearchHit } from "./memory-passage.js";
 export type ManagerStore = Pick<QMDStore, "update" | "embed" | "getStatus" | "listCollections" | "searchLex" | "vsearch" | "get" | "getDocumentBody" | "close">;
 export type ManagerSessionConfig = {
     agentId: string;
@@ -37,11 +38,6 @@ export declare function buildReadResult(params: {
     from?: number;
     lines?: number;
 }): MemoryReadResult;
-export declare function expandSessionSearchHit(result: Pick<VectorSearchResult, "body" | "bestChunk" | "chunkPos" | "chunkLen">, maxTokens: number, countTokens: (text: string) => Promise<number>, maxChars?: number, messages?: SessionMessageSpan[]): Promise<{
-    text: string;
-    position: number;
-    sourceText?: string;
-}>;
 export declare class QmdMemoryManager implements MemorySearchManagerContract {
     #private;
     diagnostics(): Promise<{
@@ -221,7 +217,7 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
     }): MaintenanceTask | undefined;
     search(query: string, opts?: CorpusSearchOptions): Promise<CorpusMemorySearchResult[]>;
     /** Whisperer-only discovery: exact trained recipe, no query-conditioned reranker or merged cap. */
-    searchWhisperer(queries: readonly string[], opts: Pick<CorpusSearchOptions, "corpora" | "signal" | "maxSnippetChars">): Promise<CorpusMemorySearchResult[]>;
+    searchWhisperer(queries: QueryPair, opts: Pick<CorpusSearchOptions, "corpora" | "signal" | "maxSnippetChars">): Promise<CorpusMemorySearchResult[]>;
     searchSkills(query: string, minScore: number, limit: number): Promise<SkillSearchCandidate[]>;
     readFile(params: {
         relPath: string;

package/dist/src/manager.js

@@ -4,7 +4,6 @@ import { mkdir, stat } from "node:fs/promises";
 import { basename, dirname, relative, resolve, sep } from "node:path";
 import chokidar from "chokidar";
 import picomatch from "picomatch";
-import { meetingRevisionAnnotation, meetingSpeakerSpans } from "./loggie-projection.js";
 import { ensureMemoryAnalysisSchema, latestAnalysisCollections, latestAnalysisRunId, markMemoryAnalysisStale, readAnalysisSummary, readCluster, readClusters, runAnalysisWorker, } from "./analysis.js";
 import { CurationStore, chunkFingerprint, } from "./curation.js";
 import { readSessionManifest, sessionMetadataByPath, syncSessionProjections, PROJECTOR_VERSION, } from "./session-sync.js";
@@ -17,6 +16,8 @@ import { reviewClusterIngestion } from "./cluster-review.js";
 import { abortable } from "./abortable.js";
 import { RetrievalTelemetry } from "./retrieval-telemetry.js";
 import { trainingCandidates } from "./training-candidates.js";
+import { expandSessionSearchHit, renderMemoryPassage } from "./memory-passage.js";
+export { expandSessionSearchHit } from "./memory-passage.js";
 const DEFAULT_READ_LINES = 120;
 const MAX_READ_CHARS = 12_000;
 const WATCH_DEBOUNCE_MS = 250;
@@ -190,35 +191,6 @@ function lineSpan(body, position, text) {
     const endLine = startLine + Math.max(0, text.split("\n").length - 1);
     return { startLine, endLine };
 }
-export async function expandSessionSearchHit(result, maxTokens, countTokens, maxChars = Infinity, messages) {
-    const leaf = { text: result.bestChunk, position: result.chunkPos };
-    const speaker = meetingSpeakerSpans(result.body, result.chunkPos, result.chunkPos + result.chunkLen);
-    const annotation = meetingRevisionAnnotation(result.body, result.chunkPos);
-    const spans = speaker ?? sessionContextSpans(result.body, result.chunkPos, messages);
-    if (!spans && !annotation)
-        return leaf;
-    const leafEnd = result.chunkPos + result.chunkLen;
-    for (const span of spans ? [spans.turn, spans.message] : []) {
-        if (span.start > result.chunkPos || span.end < leafEnd)
-            continue;
-        const sourceText = result.body.slice(span.start, span.end).trimEnd();
-        const text = annotation ? `${annotation}\n${sourceText}` : sourceText;
-        if (text.length > maxChars)
-            continue;
-        if (await countTokens(text) <= maxTokens)
-            return { text, position: span.start, ...(annotation ? { sourceText } : {}) };
-    }
-    if ((speaker && speaker.start < result.chunkPos) || annotation) {
-        const text = [annotation, speaker && speaker.start < result.chunkPos ? speaker.header : undefined, leaf.text].filter(Boolean).join("\n");
-        if (text.length <= maxChars && await countTokens(text) <= maxTokens) {
-            return { ...leaf, text, sourceText: leaf.text };
-        }
-    }
-    // Never silently strip supersession when the caller's snippet budget is tiny.
-    if (annotation)
-        return { ...leaf, text: "", sourceText: "" };
-    return leaf;
-}
 function lexicalResult(hit, corpus, session) {
     const body = hit.body ?? hit.title;
     const endLine = Math.max(1, body.split("\n").length);
@@ -845,21 +817,20 @@ export class QmdMemoryManager {
             const store = await this.#getAnalysisStore();
             const hits = new Map();
             // Serialize native QMD work. Cancellation prevents further queries/collections.
-            for (const query of queries)
-                for (const collection of collections) {
-                    opts.signal?.throwIfAborted();
-                    for (const hit of await trainingCandidates(store, query, collection, query, opts.signal)) {
-                        const key = JSON.stringify([hit.file, hit.bestChunkPos, hit.bestChunk]);
-                        if (!hits.has(key))
-                            hits.set(key, { file: hit.file, body: hit.body, bestChunk: hit.bestChunk,
-                                chunkPos: hit.bestChunkPos, chunkLen: hit.bestChunk.length, displayPath: hit.file, score: hit.score });
-                    }
+            for (const lane of ["lex", "vec"]) {
+                opts.signal?.throwIfAborted();
+                for (const hit of await trainingCandidates(store, queries[lane], collections, lane, opts.signal)) {
+                    const key = JSON.stringify([hit.file, hit.bestChunkPos, hit.bestChunk]);
+                    if (!hits.has(key))
+                        hits.set(key, { file: hit.file, body: hit.body, bestChunk: hit.bestChunk,
+                            chunkPos: hit.bestChunkPos, chunkLen: hit.bestChunk.length, displayPath: hit.file, score: hit.score });
                 }
+            }
             opts.signal?.throwIfAborted();
-            return this.#renderSearchHits([...hits.values()], store, opts);
+            return this.#renderSearchHits([...hits.values()], store, opts, true);
         });
     }
-    async #renderSearchHits(hits, store, opts) {
+    async #renderSearchHits(hits, store, opts, whisperer = false) {
         const tokenizer = store.internal?.llm;
         const results = [];
         for (const hit of hits) {
@@ -888,10 +859,11 @@ export class QmdMemoryManager {
             const messageTimestamp = messages
                 ? sessionContextSpans(hit.body, hit.chunkPos, messages)?.message.timestamp
                 : undefined;
-            const selected = corpus === "sessions" && this.#sessions && tokenizer
-                ? await expandSessionSearchHit(hit, this.#sessions.maxExpandedTokens, (text) => tokenizer.countTokens(text), opts?.maxSnippetChars, messages)
-                : { text: hit.bestChunk, position: hit.chunkPos };
-            if (!selected.text)
+            const selected = whisperer ? await renderMemoryPassage(hit, messages)
+                : corpus === "sessions" && this.#sessions && tokenizer
+                    ? await expandSessionSearchHit(hit, this.#sessions.maxExpandedTokens, (text) => tokenizer.countTokens(text), opts?.maxSnippetChars, messages)
+                    : { text: hit.bestChunk, position: hit.chunkPos };
+            if (!selected?.text)
                 continue;
             const span = lineSpan(hit.body, selected.position, selected.sourceText ?? selected.text);
             results.push({

package/dist/src/memory-passage.d.ts

@@ -0,0 +1,26 @@
+import type { VectorSearchResult } from "@unblocklabs/qmd";
+import { type SessionMessageSpan } from "./session-projector.js";
+export declare const MEMORY_PASSAGE_CHARS = 1200;
+export declare const MEMORY_PASSAGE_VERSION = "complete-excerpt-1200-v1";
+type Passage = Pick<VectorSearchResult, "body" | "bestChunk" | "chunkPos" | "chunkLen">;
+type LocatedPassage = {
+    path: string;
+    text: string;
+    startLine: number;
+    endLine: number;
+};
+/** Same passage eligibility in target scoring and runtime hint selection. */
+export declare function duplicateMemoryPassage(passage: LocatedPassage, previous: readonly LocatedPassage[]): boolean;
+/** Preserve a complete match and, when it fits, its whole turn/message context. */
+export declare function expandSessionSearchHit(result: Passage, maxTokens: number, countTokens: (text: string) => Promise<number>, maxChars?: number, messages?: SessionMessageSpan[]): Promise<{
+    text: string;
+    position: number;
+    sourceText?: string;
+}>;
+/** One fixed, model-independent renderer for offline and deployed Whisperer. */
+export declare function renderMemoryPassage(result: Passage, messages?: SessionMessageSpan[]): Promise<{
+    sourceText: string;
+    text: string;
+    position: number;
+} | undefined>;
+export {};

package/dist/src/memory-passage.js

@@ -0,0 +1,48 @@
+import { meetingRevisionAnnotation, meetingSpeakerSpans } from "./loggie-projection.js";
+import { sessionContextSpans } from "./session-projector.js";
+export const MEMORY_PASSAGE_CHARS = 1200;
+export const MEMORY_PASSAGE_VERSION = "complete-excerpt-1200-v1";
+/** Same passage eligibility in target scoring and runtime hint selection. */
+export function duplicateMemoryPassage(passage, previous) {
+    const normalized = (text) => text.replace(/\s+/gu, " ").trim();
+    return previous.some(other => normalized(other.text) === normalized(passage.text) ||
+        (other.path === passage.path && other.startLine <= passage.endLine && passage.startLine <= other.endLine));
+}
+/** Preserve a complete match and, when it fits, its whole turn/message context. */
+export async function expandSessionSearchHit(result, maxTokens, countTokens, maxChars = Infinity, messages) {
+    const leaf = { text: result.bestChunk, position: result.chunkPos };
+    const speaker = meetingSpeakerSpans(result.body, result.chunkPos, result.chunkPos + result.chunkLen);
+    const annotation = meetingRevisionAnnotation(result.body, result.chunkPos);
+    const spans = speaker ?? sessionContextSpans(result.body, result.chunkPos, messages);
+    if (!spans && !annotation)
+        return leaf;
+    const leafEnd = result.chunkPos + result.chunkLen;
+    for (const span of spans ? [spans.turn, spans.message] : []) {
+        if (span.start > result.chunkPos || span.end < leafEnd)
+            continue;
+        const sourceText = result.body.slice(span.start, span.end).trimEnd();
+        const text = annotation ? `${annotation}\n${sourceText}` : sourceText;
+        if (text.length > maxChars)
+            continue;
+        if (await countTokens(text) <= maxTokens)
+            return { text, position: span.start, ...(annotation ? { sourceText } : {}) };
+    }
+    if ((speaker && speaker.start < result.chunkPos) || annotation) {
+        const text = [annotation, speaker && speaker.start < result.chunkPos ? speaker.header : undefined, leaf.text].filter(Boolean).join("\n");
+        if (text.length <= maxChars && await countTokens(text) <= maxTokens) {
+            return { ...leaf, text, sourceText: leaf.text };
+        }
+    }
+    if (annotation)
+        return { ...leaf, text: "", sourceText: "" };
+    return leaf;
+}
+/** One fixed, model-independent renderer for offline and deployed Whisperer. */
+export async function renderMemoryPassage(result, messages) {
+    if (!result.bestChunk.trim() || result.bestChunk.length > MEMORY_PASSAGE_CHARS)
+        return;
+    const selected = messages ? await expandSessionSearchHit(result, Infinity, async () => 0, MEMORY_PASSAGE_CHARS, messages)
+        : { text: result.bestChunk, position: result.chunkPos };
+    return selected.text.trim() && selected.text.length <= MEMORY_PASSAGE_CHARS
+        ? { ...selected, sourceText: selected.sourceText ?? selected.text, text: selected.text.trim() } : undefined;
+}

package/dist/src/memory-whisperer.d.ts

@@ -2,6 +2,7 @@ import type { OpenClawConfig, OpenClawPluginApi } from "openclaw/plugin-sdk/plug
 import type { UnblockMemoryConfig } from "./config.js";
 import type { CorpusMemorySearchResult, CorpusSearchOptions } from "./contracts.js";
 import type { WhispererDiagnostics } from "./diagnostics.js";
+import type { QueryPair } from "./query-contract.js";
 type MemoryWhispererRuntime = {
     getMemorySearchManager(params: {
         cfg: OpenClawConfig;
@@ -9,7 +10,7 @@ type MemoryWhispererRuntime = {
     }): Promise<{
         manager: {
             search(query: string, opts?: CorpusSearchOptions): Promise<CorpusMemorySearchResult[]>;
-            searchWhisperer?(queries: readonly string[], opts: Pick<CorpusSearchOptions, "corpora" | "signal" | "maxSnippetChars">): Promise<CorpusMemorySearchResult[]>;
+            searchWhisperer?(queries: QueryPair, opts: Pick<CorpusSearchOptions, "corpora" | "signal" | "maxSnippetChars">): Promise<CorpusMemorySearchResult[]>;
         } | null;
     }>;
 };

package/dist/src/memory-whisperer.js

@@ -1,11 +1,11 @@
 import { createHash } from "node:crypto";
 import { judgeTypeSafeMemories } from "./typesafe.js";
 import { resolveTypeSafeApiKey, TypeSafeRequestError } from "./typesafe-client.js";
-import { buildSkillWhispererQuery, memoryConversation } from "./whisperer-context.js";
 import { complementaryIndices, reviewMemoryRedundancy } from "./typesafe-review.js";
-import { MlxQueryGenerator, queryConversation } from "./mlx-query.js";
+import { ApiQueryGenerator, QueryApiError, queryConversation } from "./query-generator.js";
 import { judgeTrainingInput, TRAINING_GATE_THRESHOLD } from "./training-gate.js";
-const MAX_EXCERPT_CHARS = 1200;
+import { MEMORY_PASSAGE_CHARS, duplicateMemoryPassage } from "./memory-passage.js";
+const MAX_EXCERPT_CHARS = MEMORY_PASSAGE_CHARS;
 function fingerprint(text) {
     return createHash("sha256").update(text.replace(/\s+/gu, " ").trim()).digest("hex");
 }
@@ -13,11 +13,7 @@ export function registerMemoryWhisperer(api, runtime, config, typesafe, diagnost
     if (!config.enabled || !typesafe.enabled)
         return;
     const sessions = new Map();
-    const generator = config.mlx ? MlxQueryGenerator.shared(config.mlx) : undefined;
-    if (generator)
-        api.on("gateway_start", () => {
-            void generator.start().catch(() => api.logger.warn("unblock-memory MLX worker unavailable; query fallback active"));
-        });
+    const generator = new ApiQueryGenerator(config.api);
     const beforePrompt = async (event, context) => {
         const { agentId, runId, sessionId, sessionKey } = context;
         const scope = sessionId || sessionKey;
@@ -31,12 +27,13 @@ export function registerMemoryWhisperer(api, runtime, config, typesafe, diagnost
         if (previous?.runId === runId)
             return previous.result;
         const started = performance.now();
+        const asOf = new Date().toISOString();
         const measurement = { outcome: "skipped", elapsedMs: 0 };
         let stage = "credentials", reason = "completed";
         let recallProbability, queryCount;
         let requestsSucceeded = 0, requestsFailed = 0;
         const log = (level, event, fields) => api.logger[level]("unblock-memory memory_whisperer " + JSON.stringify({ event, agentId, runId, sessionId, stage, ...fields }));
-        const failureFields = (error) => error instanceof TypeSafeRequestError
+        const failureFields = (error) => error instanceof TypeSafeRequestError || error instanceof QueryApiError
             ? { errorCode: error.code, httpStatus: error.status } : { errorCode: "unexpected" };
         previous?.controller.abort();
         const state = {
@@ -68,11 +65,11 @@ export function registerMemoryWhisperer(api, runtime, config, typesafe, diagnost
                 return;
             }
             stage = "input";
-            const conversation = generator ? queryConversation(event.prompt, event.messages, config.historyMessages) : undefined;
+            const conversation = queryConversation(event.prompt, event.messages);
             const gateStarted = performance.now();
             const gateSignal = AbortSignal.any([signal, AbortSignal.timeout(typesafe.timeoutMs)]);
             // Speculation is intentional: neither model generation nor QMD waits for the recall judgment.
-            const gate = conversation ? judgeTrainingInput(conversation, apiKey, gateSignal)
+            const gate = judgeTrainingInput(conversation, apiKey, gateSignal)
                 .then(result => {
                 if (signal.aborted)
                     return false;
@@ -95,28 +92,29 @@ export function registerMemoryWhisperer(api, runtime, config, typesafe, diagnost
                     state.controller.abort();
                 }
                 return false;
-            }) : Promise.resolve(true);
+            });
             const retrieveAndJudge = async () => {
                 let queries;
-                if (generator && conversation) {
-                    stage = "generation";
-                    const generationStarted = performance.now();
-                    try {
-                        queries = await generator.generate(conversation, signal);
-                        if (signal.aborted)
-                            return;
-                        queryCount = queries.length;
-                        diagnostics?.record(agentId, "memory", "queries_generated");
-                    }
-                    catch (error) {
-                        if (signal.aborted)
-                            return;
-                        log("warn", "query_fallback", { ...failureFields(error), elapsedMs: performance.now() - generationStarted });
-                        diagnostics?.record(agentId, "memory", "query_fallback");
-                    }
-                    finally {
-                        measurement.generationMs = performance.now() - generationStarted;
-                    }
+                stage = "generation";
+                const generationStarted = performance.now();
+                try {
+                    queries = await generator.generate(conversation, signal);
+                    if (signal.aborted)
+                        return;
+                    queryCount = 2;
+                    diagnostics?.record(agentId, "memory", "queries_generated");
+                }
+                catch (error) {
+                    if (signal.aborted)
+                        return;
+                    reason = "generation_failed";
+                    measurement.outcome = "failed";
+                    log("warn", "generation_failed", { ...failureFields(error), elapsedMs: performance.now() - generationStarted });
+                    diagnostics?.record(agentId, "memory", "failed");
+                    return;
+                }
+                finally {
+                    measurement.generationMs = performance.now() - generationStarted;
                 }
                 stage = "retrieval";
                 const { manager } = await runtime.getMemorySearchManager({ cfg: api.config, agentId });
@@ -128,7 +126,9 @@ export function registerMemoryWhisperer(api, runtime, config, typesafe, diagnost
                     return;
                 }
                 const retrievalStarted = performance.now();
-                const hits = queries && manager.searchWhisperer ? await manager.searchWhisperer(queries, { corpora, signal, maxSnippetChars: MAX_EXCERPT_CHARS }) : await manager.search(buildSkillWhispererQuery(event.prompt, event.messages, config.historyMessages), { corpora, maxResults: 8, minScore: -1, signal, maxSnippetChars: MAX_EXCERPT_CHARS });
+                if (!manager.searchWhisperer)
+                    throw new Error("V2 Whisperer retrieval is unavailable");
+                const hits = await manager.searchWhisperer(queries, { corpora, signal, maxSnippetChars: MAX_EXCERPT_CHARS });
                 if (signal.aborted)
                     return;
                 measurement.retrievalMs = performance.now() - retrievalStarted;
@@ -144,13 +144,9 @@ export function registerMemoryWhisperer(api, runtime, config, typesafe, diagnost
                     if (excerpt.length > MAX_EXCERPT_CHARS)
                         continue;
                     const id = fingerprint(excerpt);
-                    if (!excerpt || state.recent.has(id) || candidates.some(candidate => candidate.id === id ||
-                        (candidate.hit.path === hit.path && candidate.hit.startLine <= hit.endLine &&
-                            hit.startLine <= candidate.hit.endLine)))
+                    if (!excerpt || state.recent.has(id) || duplicateMemoryPassage({ ...hit, text: excerpt }, candidates.map(candidate => ({ ...candidate.hit, text: candidate.excerpt }))))
                         continue;
                     candidates.push({ hit, excerpt, id });
-                    if (!queries && candidates.length === 8)
-                        break;
                 }
                 measurement.eligible = candidates.length;
                 measurement.outcome = "empty";
@@ -161,8 +157,6 @@ export function registerMemoryWhisperer(api, runtime, config, typesafe, diagnost
                 }
                 stage = "judgment";
                 const judgeStarted = performance.now();
-                const judgeConversation = conversation ? { ...conversation, truncated: event.messages.length > conversation.history.length }
-                    : memoryConversation(event.prompt, event.messages);
                 // Every eligible passage gets its own request; no request sees another candidate.
                 const judged = (await Promise.all(candidates.map(async (candidate, candidateIndex) => {
                     const requestStarted = performance.now();
@@ -172,9 +166,11 @@ export function registerMemoryWhisperer(api, runtime, config, typesafe, diagnost
                         const { hit, excerpt } = candidate;
                         const [probability] = await judgeTypeSafeMemories({
                             apiKey, timeoutMs: typesafe.timeoutMs, signal,
-                            conversation: judgeConversation,
+                            conversation, asOf,
                             candidates: [{
-                                    excerpt, corpus: hit.corpus, ...(hit.messageTimestamp ? { messageTimestamp: hit.messageTimestamp } : {}),
+                                    excerpt, corpus: hit.corpus, sourcePath: hit.path,
+                                    dates: [...new Set(hit.sessionMessages?.flatMap(message => message.timestamp ? [message.timestamp] : [])
+                                            ?? (hit.messageTimestamp ? [hit.messageTimestamp] : []))],
                                 }],
                         });
                         if (signal.aborted)
@@ -302,7 +298,6 @@ export function registerMemoryWhisperer(api, runtime, config, typesafe, diagnost
         }
     });
     api.on("gateway_stop", () => {
-        generator?.close();
         for (const state of sessions.values())
             state.controller.abort();
         sessions.clear();

package/dist/src/query-contract.d.ts

@@ -0,0 +1,31 @@
+export type QueryLane = "lex" | "vec";
+export type QueryPair = Record<QueryLane, string>;
+export type QueryConversation = {
+    history: {
+        role: "user" | "assistant";
+        content: string;
+    }[];
+    currentRequest: string;
+};
+export declare const QUERY_CONTRACT: {
+    version: string;
+    model: string;
+    revision: string;
+    conversationTokens: number;
+    conversationBytes: number;
+    contextTokens: number;
+    outputTokens: number;
+    system: string;
+};
+export declare class QueryInputBudgetError extends Error {
+    constructor();
+}
+export declare function parseQueryPair(value: unknown): QueryPair;
+/** Escape template delimiters identically in the student worker and dataset preparation. */
+export declare function serializeQueryConversation(conversation: QueryConversation): string;
+export declare function queryTokenIds(text: string): number[];
+/** Never alter the current request or split a history message. */
+export declare function prepareQueryConversation(history: QueryConversation["history"], currentRequest: string): {
+    conversation: QueryConversation;
+    contextLimited: boolean;
+};