@unblocklabs/unblock-memory 0.3.29 → 0.4.0

package/README.md

@@ -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,7 +64,6 @@ export type UnblockMemoryConfig = {
         enabled: boolean;
         complementaryHints: boolean;
         corpora: readonly string[];
-        historyMessages: number;
         minUsefulness: number;
         maxHints: number;
         cooldownTurns: number;

package/dist/src/config.js

@@ -81,7 +81,7 @@ 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,
 };
 function resolveMemoryWhisperer(value, corpora) {
@@ -116,11 +116,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,7 +125,7 @@ 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 } : {}),

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 { 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");
 }
@@ -16,7 +16,7 @@ export function registerMemoryWhisperer(api, runtime, config, typesafe, diagnost
     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"));
+            void generator.start().catch(() => api.logger.warn("unblock-memory MLX worker unavailable; automatic memory skipped"));
         });
     const beforePrompt = async (event, context) => {
         const { agentId, runId, sessionId, sessionKey } = context;
@@ -31,6 +31,7 @@ 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;
@@ -68,11 +69,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 = generator ? judgeTrainingInput(conversation, apiKey, gateSignal)
                 .then(result => {
                 if (signal.aborted)
                     return false;
@@ -98,21 +99,24 @@ export function registerMemoryWhisperer(api, runtime, config, typesafe, diagnost
             }) : Promise.resolve(true);
             const retrieveAndJudge = async () => {
                 let queries;
-                if (generator && conversation) {
+                if (generator) {
                     stage = "generation";
                     const generationStarted = performance.now();
                     try {
                         queries = await generator.generate(conversation, signal);
                         if (signal.aborted)
                             return;
-                        queryCount = queries.length;
+                        queryCount = 2;
                         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");
+                        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;
@@ -128,7 +132,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 (queries && !manager.searchWhisperer)
+                    throw new Error("V2 Whisperer retrieval is unavailable");
+                const hits = queries ? await manager.searchWhisperer(queries, { corpora, signal, maxSnippetChars: MAX_EXCERPT_CHARS }) : await manager.search(JSON.stringify(conversation), { corpora, maxResults: 8, minScore: -1, signal, maxSnippetChars: MAX_EXCERPT_CHARS });
                 if (signal.aborted)
                     return;
                 measurement.retrievalMs = performance.now() - retrievalStarted;
@@ -144,9 +150,7 @@ 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)
@@ -161,8 +165,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 +174,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)

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

@@ -1,13 +1,7 @@
 import type { UnblockMemoryConfig } from "./config.js";
-type Conversation = {
-    history: {
-        role: "user" | "assistant";
-        content: string;
-    }[];
-    currentRequest: string;
-};
+import { type QueryConversation, type QueryPair } from "./query-contract.js";
 /** Preserve whole visible messages and the complete current request, never tool/thinking text. */
-export declare function queryConversation(prompt: string, messages: readonly unknown[], historyMessages: number): Conversation;
+export declare function queryConversation(prompt: string, messages: readonly unknown[]): QueryConversation;
 export declare class MlxQueryGenerator {
     #private;
     private readonly config;
@@ -16,7 +10,6 @@ export declare class MlxQueryGenerator {
     constructor(config: NonNullable<UnblockMemoryConfig["memoryWhisperer"]["mlx"]>);
     get closed(): boolean;
     start(): Promise<void>;
-    generate(conversation: Conversation, signal: AbortSignal): Promise<string[]>;
+    generate(conversation: QueryConversation, signal: AbortSignal): Promise<QueryPair>;
     close(): void;
 }
-export {};

package/dist/src/mlx-query.js

@@ -6,32 +6,63 @@ import { createInterface } from "node:readline";
 import { abortable } from "./abortable.js";
 import { messageText } from "./whisperer-context.js";
 import { conversationUserText } from "./response-text.js";
+import { parseQueryPair, prepareQueryConversation } from "./query-contract.js";
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
 /** Preserve whole visible messages and the complete current request, never tool/thinking text. */
-export function queryConversation(prompt, messages, historyMessages) {
+export function queryConversation(prompt, messages) {
     const currentRequest = conversationUserText(prompt)?.text ?? "";
-    const visible = messages.flatMap(message => {
+    const visible = [];
+    const assistantTexts = new Map();
+    for (const item of messages) {
+        const event = record(item), message = record(event?.type === "message" ? event.message : item);
+        if (event?.type === "compaction" || message?.role === "compactionSummary") {
+            visible.length = 0;
+            assistantTexts.clear();
+            continue;
+        }
+        if (!message || message.role === "toolResult" || message.role === "tool")
+            continue;
+        const meta = record(message.__openclaw);
+        if (message.provenance !== undefined || (message.role === "user" && record(meta?.senderIdentity)?.senderKind === "bot")) {
+            visible.length = 0;
+            assistantTexts.clear();
+            continue;
+        }
+        const mirror = message.provider === "openclaw" && message.model === "delivery-mirror";
+        if (message.role === "assistant" && (message.channel === "analysis" || message.stopReason === "error" ||
+            message.stopReason === "aborted" || (message.provider === "openclaw" && message.model === "gateway-injected") ||
+            (mirror && record(message.openclawDeliveryMirror)?.kind === "channel-final-suppressed")))
+            continue;
         const text = messageText(message);
-        const content = text?.role === "user" ? conversationUserText(text.text)?.text : text?.text;
-        return text && content ? [{ role: text.role, content }] : [];
-    });
+        const raw = text?.role === "user" && typeof meta?.upstreamUserText === "string" ? meta.upstreamUserText : text?.text;
+        const content = text?.role === "user" && raw ? conversationUserText(raw, meta?.senderId ?? message.senderId)?.text : raw;
+        if (message.role === "user") {
+            assistantTexts.clear();
+            if (!content || /^(?:\[OpenClaw heartbeat poll\]|\[Queued messages while agent was busy\]|\[Subagent Context\]|<relevant-memories>)/.test(content)) {
+                visible.length = 0;
+                continue;
+            }
+        }
+        if (!text || !content || (text.role === "assistant" && (content === "NO_REPLY" || content === "HEARTBEAT_OK")))
+            continue;
+        if (text.role === "assistant") {
+            const previous = assistantTexts.get(content);
+            assistantTexts.set(content, mirror);
+            if (previous !== undefined && (mirror || previous))
+                continue;
+        }
+        visible.push({ role: text.role, content });
+    }
     if (visible.at(-1)?.role === "user" && visible.at(-1)?.content === currentRequest)
         visible.pop();
-    const history = historyMessages ? visible.slice(-historyMessages) : [];
-    while (history.length && Buffer.byteLength(JSON.stringify({ history, currentRequest })) > 24_000)
-        history.shift();
-    if (!currentRequest)
-        throw new Error("Missing or unparseable current request");
-    if (Buffer.byteLength(JSON.stringify({ history, currentRequest })) > 24_000) {
-        throw new Error("Query input exceeds context budget");
-    }
-    return { history, currentRequest };
+    return prepareQueryConversation(visible, currentRequest).conversation;
 }
 export class MlxQueryGenerator {
     config;
     /** Gateway hook and tool registries can evaluate/register this plugin separately. */
     static shared(config) {
         const scope = globalThis;
-        const symbol = Symbol.for("unblock-memory.mlx-workers.v1");
+        const symbol = Symbol.for("unblock-memory.mlx-workers.v2");
         const workers = (scope[symbol] ??= new Map());
         const key = JSON.stringify([config.pythonPath, config.modelPath]);
         let worker = workers.get(key);
@@ -104,19 +135,12 @@ export class MlxQueryGenerator {
                         request.reject(new Error("Query generation failed"));
                         return;
                     }
-                    let queries;
                     try {
-                        queries = JSON.parse(value.text).queries;
+                        request.resolve(parseQueryPair(JSON.parse(value.text)));
                     }
-                    catch { /* reject below */ }
-                    const usable = Array.isArray(queries) ? [...new Set(queries
-                            .filter((query) => typeof query === "string")
-                            .map(query => query.trim()).filter(Boolean))] : [];
-                    if (!usable.length) {
-                        request.reject(new Error("No usable generated queries"));
-                        return;
+                    catch {
+                        request.reject(new Error("Invalid generated lex/vec query pair"));
                     }
-                    request.resolve(usable);
                 }
                 catch {
                     child.kill();

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;
+};