@unblocklabs/unblock-memory 0.7.3 → 0.8.0

package/README.md

@@ -2,8 +2,9 @@
 
 Workspace-native memory for OpenClaw, powered internally by `@unblocklabs/qmd`.
 It keeps one warm QMD store per agent and exposes `memory_search` and `memory_get`.
-Ordinary recall is local vector search over semantic chunks: no query expansion,
-reranker or TypeSafe key is required.
+Recall combines BM25 and vector candidates, then independently ranks complete
+passages with TypeSafe. The agent supplies both queries; no query generation or
+"do we need memory?" gate runs for explicit search. A TypeSafe key is required.
 
 ## Start here
 
@@ -38,7 +39,7 @@ Optional installation from source:
 
 | Capability | What it does | Default / prerequisite |
 | --- | --- | --- |
-| [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 |
+| [Search and reads](docs/retrieval.md#search-and-read) | BM25 + vector recall with TypeSafe ranking, then exact indexed reads | Search requires TypeSafe; reads stay local; 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; query generation via resident API | Off; approved corpora + TypeSafe + query API credential |
@@ -52,10 +53,9 @@ Optional installation from source:
 | [Session memory extraction](docs/extraction.md) | Luna proposes lasting facts; Jev verifies them; optional QMD search | Off; approved session types + TypeSafe + host LLM permission; shadow-only by default |
 | [Compaction memory flush](docs/configuration.md#compaction-memory-writes) | Supplies the host an append-only daily-memory write plan | Offered unless the host's memory-flush setting is false; separate from whisperers |
 
-**Search is not one interchangeable API:** plugin `memory_search` is vector-only;
-standalone QMD `query` is hybrid vector + BM25 with TypeSafe ranking.
-They have separate configuration/index boundaries. See
-[search modes and the xsearch migration](docs/retrieval.md#qmd-search-modes).
+**One agent search pipeline:** `memory_search` and Memory Whisperer share
+candidate discovery, passage rendering, deduplication and TypeSafe ranking.
+Whisperer additionally generates queries and applies its automatic recall/delivery policy.
 
 ## Configuration and operating guides
 
@@ -73,9 +73,9 @@ They have separate configuration/index boundaries. See
 - [Session extraction](docs/extraction.md): incremental/backfill runs, configurable
   acceptance thresholds, shadow evaluation, and publishing lasting facts to search.
 
-The shared TypeSafe integration defaults on, but its features are opt-in.
-A key activates only features already enabled. Ordinary search and People
-Whisperer's injection stay local; Skill Whisperer has a local fallback.
+The shared TypeSafe integration defaults on. Ordinary search requires a key;
+other TypeSafe features remain opt-in. People Whisperer's injection stays local;
+Skill Whisperer has a local fallback.
 [Provider gates and failure behavior](docs/configuration.md#feature-gates-and-fallbacks)
 differ by feature.
 

package/dist/src/agent-transcript.d.ts

@@ -1,8 +1,39 @@
 import type { DatabaseSync } from "node:sqlite";
-/** The OpenClaw agent database versions whose transcript layout we read. */
+/** Identity fence, not a payload-format allowlist. Required capabilities are checked below. */
 export declare function agentTranscriptSchemaVersion(db: DatabaseSync, errorMessage?: string): number;
 export declare function assertAgentTranscriptIdentity(db: DatabaseSync, agentId: string, version: number, errorMessage?: string): void;
-export declare function assertAgentTranscriptSchema(db: DatabaseSync, agentId: string, errorMessage?: string): void;
-export declare const ACTIVE_EVENTS_FROM = "FROM session_transcript_active_events a\n  JOIN transcript_events e ON e.session_id=a.session_id AND e.seq=a.event_seq";
-export declare const ACTIVE_EVENT_COUNT_SQL = "SELECT COUNT(*) n,COALESCE(SUM(length(e.event_json)),0) bytes\n  FROM session_transcript_active_events a\n  JOIN transcript_events e ON e.session_id=a.session_id AND e.seq=a.event_seq WHERE a.session_id=?";
-export declare const ACTIVE_EVENT_ROWS_SQL = "SELECT e.seq,e.event_json eventJson,e.created_at createdAt\n  FROM session_transcript_active_events a\n  JOIN transcript_events e ON e.session_id=a.session_id AND e.seq=a.event_seq WHERE a.session_id=? ORDER BY a.active_position";
+type AgentTranscriptRow = {
+    seq: number;
+    eventJson: string;
+    createdAt: number;
+};
+type TranscriptSnapshot = {
+    kind: "ready";
+    rows: AgentTranscriptRow[];
+} | {
+    kind: "cold";
+} | {
+    kind: "oversized";
+} | {
+    kind: "unreadable";
+};
+/**
+ * One read-only storage boundary for full-fidelity active transcripts. The public
+ * SDK's full reader may restore cold archives; its read-only catalog truncates and
+ * redacts content. Neither currently provides the contract these consumers need.
+ * Keep payload SQL here until the SDK offers a bounded, full-fidelity read-only API.
+ */
+export declare class AgentTranscriptReader {
+    #private;
+    readonly db: DatabaseSync;
+    constructor(db: DatabaseSync, agentId: string, errorMessage?: string);
+    /** Include storage availability in incremental fingerprints, not just hot row counts. */
+    coldSql(sessionIdExpression: string): string;
+    /** Caller owns a transaction so metadata, cold marker, bounds and rows share one snapshot. */
+    read(sessionId: string, limits?: {
+        maxEvents?: number;
+        maxBytes?: number;
+        maxSeq?: number;
+    }): TranscriptSnapshot;
+}
+export {};

package/dist/src/agent-transcript.js

@@ -1,8 +1,9 @@
-/** The OpenClaw agent database versions whose transcript layout we read. */
+import { zstdDecompressSync } from "node:zlib";
+/** Identity fence, not a payload-format allowlist. Required capabilities are checked below. */
 export function agentTranscriptSchemaVersion(db, errorMessage) {
     const version = db.prepare("PRAGMA user_version").get()?.user_version;
-    if (typeof version !== "number" || ![17, 18, 19].includes(version)) {
-        throw new Error(errorMessage ?? "unsupported OpenClaw agent database schema: expected one of 17, 18, 19, " +
+    if (typeof version !== "number" || !Number.isSafeInteger(version) || version < 17) {
+        throw new Error(errorMessage ?? "unsupported OpenClaw agent database schema: expected 17 or newer, " +
             `found ${String(version ?? "unknown")}`);
     }
     return version;
@@ -18,12 +19,101 @@ export function assertAgentTranscriptIdentity(db, agentId, version, errorMessage
         fail(`OpenClaw agent database belongs to ${String(meta?.agentId)}, not ${agentId}`);
     }
 }
-export function assertAgentTranscriptSchema(db, agentId, errorMessage) {
-    assertAgentTranscriptIdentity(db, agentId, agentTranscriptSchemaVersion(db, errorMessage), errorMessage);
-}
-export const ACTIVE_EVENTS_FROM = `FROM session_transcript_active_events a
+const ACTIVE_EVENTS_FROM = `FROM session_transcript_active_events a
   JOIN transcript_events e ON e.session_id=a.session_id AND e.seq=a.event_seq`;
-export const ACTIVE_EVENT_COUNT_SQL = `SELECT COUNT(*) n,COALESCE(SUM(length(e.event_json)),0) bytes
-  ${ACTIVE_EVENTS_FROM} WHERE a.session_id=?`;
-export const ACTIVE_EVENT_ROWS_SQL = `SELECT e.seq,e.event_json eventJson,e.created_at createdAt
-  ${ACTIVE_EVENTS_FROM} WHERE a.session_id=? ORDER BY a.active_position`;
+const MAX_COMPRESSED_BYTES = 4 * 1024 * 1024;
+const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+/**
+ * One read-only storage boundary for full-fidelity active transcripts. The public
+ * SDK's full reader may restore cold archives; its read-only catalog truncates and
+ * redacts content. Neither currently provides the contract these consumers need.
+ * Keep payload SQL here until the SDK offers a bounded, full-fidelity read-only API.
+ */
+export class AgentTranscriptReader {
+    db;
+    #schemaVersion;
+    #compressed;
+    #cold;
+    #utf8Storage;
+    constructor(db, agentId, errorMessage) {
+        this.db = db;
+        const version = agentTranscriptSchemaVersion(db, errorMessage);
+        this.#schemaVersion = version;
+        this.#utf8Storage = db.prepare("PRAGMA encoding").get()?.encoding === "UTF-8";
+        assertAgentTranscriptIdentity(db, agentId, version, errorMessage);
+        const required = {
+            transcript_events: ["session_id", "seq", "event_json", "created_at"],
+            session_transcript_active_events: ["session_id", "active_position", "event_seq"],
+        };
+        const columns = (table) => new Set(db.prepare(`PRAGMA table_info(${table})`).all().map(row => row.name));
+        for (const [table, names] of Object.entries(required)) {
+            const found = columns(table);
+            if (names.some(name => !found.has(name)))
+                throw new Error(`Unsupported transcript capabilities: ${table}`);
+        }
+        const payload = columns("transcript_events");
+        this.#compressed = payload.has("event_zstd") && payload.has("event_utf8_bytes");
+        if ((version >= 23 || payload.has("event_zstd") || payload.has("event_utf8_bytes")) && !this.#compressed) {
+            throw new Error("Unsupported transcript compression capabilities");
+        }
+        this.#cold = columns("session_transcript_cold_archives").has("session_id");
+        if (version >= 20 && !this.#cold)
+            throw new Error("Unsupported transcript cold-storage capabilities");
+    }
+    /** Include storage availability in incremental fingerprints, not just hot row counts. */
+    coldSql(sessionIdExpression) {
+        return this.#cold ? `EXISTS (SELECT 1 FROM session_transcript_cold_archives cold WHERE cold.session_id=${sessionIdExpression})` : "0";
+    }
+    /** Caller owns a transaction so metadata, cold marker, bounds and rows share one snapshot. */
+    read(sessionId, limits = {}) {
+        if (!this.db.isTransaction)
+            throw new Error("Transcript read requires a snapshot transaction");
+        // Long-lived audit/source readers may outlive a host migration. Reopen before
+        // trusting cached capabilities; absence of old hot rows is not deletion proof.
+        if (this.db.prepare("PRAGMA user_version").get()?.user_version !== this.#schemaVersion)
+            return { kind: "unreadable" };
+        if (this.#cold && this.db.prepare("SELECT 1 FROM session_transcript_cold_archives WHERE session_id=?").get(sessionId)) {
+            return { kind: "cold" };
+        }
+        const maxEvents = limits.maxEvents ?? 50_000, maxBytes = limits.maxBytes ?? 64 * 1024 * 1024;
+        const maxSeq = limits.maxSeq ?? Number.MAX_SAFE_INTEGER;
+        // SQLite's BLOB length measures the database encoding, not decoded UTF-8.
+        // Non-UTF-8 stores still enforce the byte budget below during bounded iteration.
+        const bytes = !this.#utf8Storage ? "0" : this.#compressed
+            ? "COALESCE(length(CAST(e.event_json AS BLOB)),e.event_utf8_bytes,0)" : "length(CAST(e.event_json AS BLOB))";
+        const size = this.db.prepare(`SELECT COUNT(*) n,COALESCE(SUM(${bytes}),0) bytes
+      ${ACTIVE_EVENTS_FROM} WHERE a.session_id=? AND e.seq<=?`).get(sessionId, maxSeq);
+        if (Number(size.n) > maxEvents || Number(size.bytes) > maxBytes)
+            return { kind: "oversized" };
+        const rows = [];
+        let totalBytes = 0;
+        for (const row of this.db.prepare(`SELECT e.seq,e.event_json eventJson,e.created_at createdAt
+      ${this.#compressed ? ",e.event_zstd compressed,e.event_utf8_bytes rawBytes" : ""}
+      ${ACTIVE_EVENTS_FROM} WHERE a.session_id=? AND e.seq<=? ORDER BY a.active_position`).iterate(sessionId, maxSeq)) {
+            let eventJson;
+            if (typeof row.eventJson === "string")
+                eventJson = row.eventJson;
+            else {
+                const compressed = row.compressed, rawBytes = row.rawBytes;
+                if (!(compressed instanceof Uint8Array) || !compressed.byteLength || compressed.byteLength > MAX_COMPRESSED_BYTES ||
+                    typeof rawBytes !== "number" || !Number.isSafeInteger(rawBytes) || rawBytes <= 0 || rawBytes > MAX_COMPRESSED_BYTES) {
+                    return { kind: "unreadable" };
+                }
+                try {
+                    const decoded = zstdDecompressSync(compressed, { maxOutputLength: rawBytes });
+                    if (decoded.byteLength !== rawBytes)
+                        return { kind: "unreadable" };
+                    eventJson = utf8.decode(decoded);
+                }
+                catch {
+                    return { kind: "unreadable" };
+                }
+            }
+            totalBytes += Buffer.byteLength(eventJson);
+            if (totalBytes > maxBytes)
+                return { kind: "oversized" };
+            rows.push({ seq: Number(row.seq), eventJson, createdAt: Number(row.createdAt) });
+        }
+        return { kind: "ready", rows };
+    }
+}

package/dist/src/contracts.d.ts

@@ -31,7 +31,7 @@ export type SessionSearchFilter = {
 export type MemoryRequestContext = Pick<OpenClawPluginToolContext, "sessionKey" | "sessionId" | "messageChannel" | "agentAccountId" | "nativeChannelId" | "deliveryContext">;
 export type CorpusSearchOptions = Omit<NonNullable<Parameters<MemorySearchManagerContract["search"]>[1]>, "lexicalOnly"> & {
     corpora?: readonly string[];
-    /** Internal vector-hint budget; oversized matched chunks are omitted, never sliced. */
+    /** Internal passage budget; oversized matched chunks are omitted, never sliced. */
     maxSnippetChars?: number;
     sessionFilter?: SessionSearchFilter;
     requestContext?: MemoryRequestContext;

package/dist/src/diagnostics.d.ts

@@ -1,12 +1,13 @@
 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" | "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" | "input_too_large";
 /** Process-local, content-free and bounded. Agent IDs are keys, never included in snapshots. */
 export declare class WhispererDiagnostics {
     #private;
     static shared(): WhispererDiagnostics;
     record(agentId: string, whisperer: Whisperer, outcome: Outcome): void;
     measureMemory(agentId: string, observation: Parameters<RetrievalTelemetry["record"]>[1]): void;
+    measureSearch(agentId: string, observation: Parameters<RetrievalTelemetry["record"]>[1]): void;
     snapshot(agentId: string): {
         skill: {
             cancelled?: number | undefined;
@@ -24,6 +25,7 @@ export declare class WhispererDiagnostics {
             recall_not_needed?: number | undefined;
             queries_generated?: number | undefined;
             judge_candidate_failed?: number | undefined;
+            input_too_large?: number | undefined;
         };
         memory: {
             cancelled?: number | undefined;
@@ -41,6 +43,7 @@ export declare class WhispererDiagnostics {
             recall_not_needed?: number | undefined;
             queries_generated?: number | undefined;
             judge_candidate_failed?: number | undefined;
+            input_too_large?: number | undefined;
         };
         telemetry: {
             scope: string;
@@ -50,6 +53,7 @@ export declare class WhispererDiagnostics {
                     outcomes: {
                         ok?: number | undefined;
                         cancelled?: number | undefined;
+                        partial?: number | undefined;
                         skipped?: number | undefined;
                         failed?: number | undefined;
                         empty?: number | undefined;

package/dist/src/diagnostics.js

@@ -24,6 +24,9 @@ export class WhispererDiagnostics {
     measureMemory(agentId, observation) {
         this.#entry(agentId).telemetry.record("memoryWhisperer", observation);
     }
+    measureSearch(agentId, observation) {
+        this.#entry(agentId).telemetry.record("memorySearch", observation);
+    }
     snapshot(agentId) {
         const entry = this.#agents.get(agentId);
         return { skill: { ...entry?.counts.skill }, memory: { ...entry?.counts.memory },

package/dist/src/inside-out-sources.js

@@ -5,7 +5,7 @@ import { createZstdDecompress, zstdDecompressSync } from "node:zlib";
 import { createInterface } from "node:readline";
 import { PassThrough } from "node:stream";
 import { pipeline } from "node:stream/promises";
-import { ACTIVE_EVENTS_FROM, assertAgentTranscriptSchema } from "./agent-transcript.js";
+import { AgentTranscriptReader } from "./agent-transcript.js";
 /** Files contain branch trees; keep the selected leaf, not abandoned sibling conversations. */
 function selectedBranch(events) {
     const nodes = new Map(events.filter(e => e.id).map(e => [e.id, e]));
@@ -57,10 +57,11 @@ export async function* readInsideOutSources(paths, errors) {
         const db = new DatabaseSync(paths.databasePath, { readOnly: true });
         try {
             db.exec("PRAGMA busy_timeout=1000");
-            assertAgentTranscriptSchema(db, paths.agentId);
+            const transcripts = new AgentTranscriptReader(db, paths.agentId);
             const sessions = db.prepare(`SELECT w.session_id sessionId, COALESCE(w.channel,c.channel,'local') channel,
         COALESCE(w.account_id,c.account_id,'') account, COALESCE(r.generation,'') revision,
-        COALESCE((SELECT MAX(seq) FROM transcript_events WHERE session_id=w.session_id),0) tail FROM session_windows w
+        COALESCE((SELECT MAX(seq) FROM transcript_events WHERE session_id=w.session_id),0) tail,
+        ${transcripts.coldSql("w.session_id")} cold FROM session_windows w
         LEFT JOIN conversations c ON c.conversation_id=w.primary_conversation_id
         LEFT JOIN transcript_rewrite_watermarks r ON r.session_id=w.session_id
         WHERE (? IS NULL OR w.session_id=?) ORDER BY w.started_at,w.session_id`).all(paths.sessionId ?? null, paths.sessionId ?? null);
@@ -83,15 +84,23 @@ export async function* readInsideOutSources(paths, errors) {
             }
             for (const s of sessions) {
                 const sessionId = String(s.sessionId), source = `live:${sessionId}`;
-                yield { source, sessionId, revision: String(s.revision), signature: JSON.stringify([s.revision, s.tail]), read: () => {
-                        const events = db.prepare(`SELECT e.seq,e.event_json eventJson,e.created_at createdAt
-            ${ACTIVE_EVENTS_FROM} WHERE a.session_id=? AND e.seq<=? ORDER BY a.active_position`).all(sessionId, s.tail).map(row => {
-                            const event = JSON.parse(String(row.eventJson));
-                            event.seq = Number(row.seq);
-                            event.timestamp ??= new Date(Number(row.createdAt)).toISOString();
-                            return event;
-                        });
-                        return { sessionId, source, events, ...metadata.get(sessionId) };
+                yield { source, sessionId, revision: String(s.revision), signature: JSON.stringify([s.revision, s.tail, s.cold]), read: () => {
+                        db.exec("BEGIN");
+                        try {
+                            const snapshot = transcripts.read(sessionId, { maxSeq: Number(s.tail) });
+                            if (snapshot.kind !== "ready")
+                                throw new Error(`Transcript unavailable: ${snapshot.kind}`);
+                            const events = snapshot.rows.map(row => {
+                                const event = JSON.parse(row.eventJson);
+                                event.seq = row.seq;
+                                event.timestamp ??= new Date(row.createdAt).toISOString();
+                                return event;
+                            });
+                            return { sessionId, source, events, ...metadata.get(sessionId) };
+                        }
+                        finally {
+                            db.exec("COMMIT");
+                        }
                     } };
             }
         }

package/dist/src/manager.d.ts

@@ -56,6 +56,7 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
                     outcomes: {
                         ok?: number | undefined;
                         cancelled?: number | undefined;
+                        partial?: number | undefined;
                         skipped?: number | undefined;
                         failed?: number | undefined;
                         empty?: number | undefined;
@@ -219,8 +220,8 @@ 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: QueryPair, opts: Pick<CorpusSearchOptions, "corpora" | "signal" | "maxSnippetChars">): Promise<CorpusMemorySearchResult[]>;
+    /** Shared discovery: exact trained recipe, scoped before either retrieval lane. */
+    searchCandidates(queries: QueryPair, opts: CorpusSearchOptions): Promise<CorpusMemorySearchResult[]>;
     searchSkills(query: string, minScore: number, limit: number): Promise<SkillSearchCandidate[]>;
     readFile(params: {
         relPath: string;

package/dist/src/manager.js

@@ -831,8 +831,8 @@ export class QmdMemoryManager {
         opts?.signal?.throwIfAborted();
         return this.#renderSearchHits(hits, store, opts);
     }
-    /** Whisperer-only discovery: exact trained recipe, no query-conditioned reranker or merged cap. */
-    async searchWhisperer(queries, opts) {
+    /** Shared discovery: exact trained recipe, scoped before either retrieval lane. */
+    async searchCandidates(queries, opts) {
         return this.#enqueue(async () => {
             opts.signal?.throwIfAborted();
             const collections = this.#collectionNames(opts.corpora);
@@ -840,12 +840,18 @@ export class QmdMemoryManager {
                 return [];
             if (this.#sessions && collections.includes(this.#sessions.collection))
                 await this.#refreshSessionMetadata();
+            const sessions = this.#sessions;
+            let allowedPaths = opts.sessionFilter && sessions && collections.includes(sessions.collection)
+                ? sessionAllowedPaths(this.#sessionMetadata, sessions.collection, opts.sessionFilter) : undefined;
+            if (collections.includes(EXTRACTED_COLLECTION)) {
+                allowedPaths = { ...allowedPaths, [EXTRACTED_COLLECTION]: this.#currentExtracted(undefined, opts.sessionFilter).map(extractedPath) };
+            }
             const store = await this.#getAnalysisStore();
             const hits = new Map();
             // Serialize native QMD work. Cancellation prevents further queries/collections.
             for (const lane of ["lex", "vec"]) {
                 opts.signal?.throwIfAborted();
-                for (const hit of await trainingCandidates(store, queries[lane], collections, lane, opts.signal)) {
+                for (const hit of await trainingCandidates(store, queries[lane], collections, lane, opts.signal, allowedPaths)) {
                     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,

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

@@ -0,0 +1,31 @@
+import type { CorpusMemorySearchResult, CorpusSearchOptions } from "./contracts.js";
+import type { QueryConversation, QueryPair } from "./query-contract.js";
+export type MemoryCandidateManager = {
+    searchCandidates(queries: QueryPair, options: CorpusSearchOptions): Promise<CorpusMemorySearchResult[]>;
+};
+export declare function memoryPassageId(text: string): string;
+export type MemorySearchObservation = {
+    retrievalMs: number;
+    judgeMs: number;
+    candidates: number;
+    eligible: number;
+    requestsSucceeded: number;
+    requestsFailed: number;
+};
+/** Both entry points use the same complete passages and independent usefulness judgments. */
+export declare function searchMemory(manager: MemoryCandidateManager, queries: QueryPair, options: CorpusSearchOptions & {
+    apiKey: string;
+    timeoutMs: number;
+    conversation: QueryConversation;
+    asOf?: string;
+    minUsefulness?: number;
+    excludedPassages?: ReadonlyMap<string, number>;
+    onCandidates?: (observation: MemorySearchObservation) => void;
+    onJudgment?: (event: {
+        candidateIndex: number;
+        elapsedMs: number;
+        error?: unknown;
+    }) => void;
+}): Promise<MemorySearchObservation & {
+    results: CorpusMemorySearchResult[];
+}>;

package/dist/src/memory-search.js

@@ -0,0 +1,61 @@
+import { createHash } from "node:crypto";
+import { MEMORY_PASSAGE_CHARS, duplicateMemoryPassage } from "./memory-passage.js";
+import { judgeMemoryPassage, memoryUsefulnessRequest } from "./typesafe.js";
+export function memoryPassageId(text) {
+    return createHash("sha256").update(text.replace(/\s+/gu, " ").trim()).digest("hex");
+}
+/** Both entry points use the same complete passages and independent usefulness judgments. */
+export async function searchMemory(manager, queries, options) {
+    const { signal } = options;
+    signal?.throwIfAborted();
+    const asOf = options.asOf ?? new Date().toISOString();
+    const started = performance.now();
+    const hits = await manager.searchCandidates(queries, {
+        corpora: options.corpora, sessionFilter: options.sessionFilter, requestContext: options.requestContext,
+        sources: options.sources, signal, maxSnippetChars: MEMORY_PASSAGE_CHARS,
+    });
+    signal?.throwIfAborted();
+    const observation = { retrievalMs: performance.now() - started, judgeMs: 0,
+        candidates: hits.length, eligible: 0, requestsSucceeded: 0, requestsFailed: 0 };
+    const candidates = [];
+    for (const hit of hits) {
+        // Defense in depth before disclosing passages to the external judge.
+        if (options.corpora && !options.corpora.includes("all") && !options.corpora.includes(hit.corpus))
+            continue;
+        const excerpt = hit.snippet.trim();
+        if (!excerpt || excerpt.length > MEMORY_PASSAGE_CHARS || options.excludedPassages?.has(memoryPassageId(excerpt)) ||
+            duplicateMemoryPassage({ ...hit, text: excerpt }, candidates.map(candidate => ({ ...candidate, text: candidate.snippet }))))
+            continue;
+        candidates.push({ ...hit, snippet: excerpt });
+    }
+    observation.eligible = candidates.length;
+    options.onCandidates?.(observation);
+    const judgeStarted = performance.now();
+    const judged = (await Promise.all(candidates.map(async (hit, candidateIndex) => {
+        const requestStarted = performance.now();
+        try {
+            const { probability } = await judgeMemoryPassage(memoryUsefulnessRequest(options.conversation, {
+                excerpt: hit.snippet, corpus: hit.corpus, sourcePath: hit.path,
+                dates: [...new Set(hit.sessionMessages?.flatMap(message => message.timestamp ? [message.timestamp] : [])
+                        ?? (hit.messageTimestamp ? [hit.messageTimestamp] : []))],
+            }, asOf), options);
+            signal?.throwIfAborted();
+            observation.requestsSucceeded++;
+            options.onJudgment?.({ candidateIndex, elapsedMs: performance.now() - requestStarted });
+            // Discovery reciprocal ranks are not vector similarity or usefulness.
+            const { vectorScore: _vectorScore, textScore: _textScore, ...result } = hit;
+            return [{ ...result, score: probability }];
+        }
+        catch (error) {
+            if (signal?.aborted)
+                return [];
+            observation.requestsFailed++;
+            options.onJudgment?.({ candidateIndex, elapsedMs: performance.now() - requestStarted, error });
+            return [];
+        }
+    }))).flat();
+    signal?.throwIfAborted();
+    observation.judgeMs = performance.now() - judgeStarted;
+    return { ...observation, results: judged.filter(hit => hit.score >= (options.minUsefulness ?? 0.7))
+            .sort((a, b) => b.score - a.score).slice(0, options.maxResults ?? 5) };
+}

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

@@ -1,17 +1,13 @@
 import type { OpenClawConfig, OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
 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";
+import { type MemoryCandidateManager } from "./memory-search.js";
 type MemoryWhispererRuntime = {
     getMemorySearchManager(params: {
         cfg: OpenClawConfig;
         agentId: string;
     }): Promise<{
-        manager: {
-            search(query: string, opts?: CorpusSearchOptions): Promise<CorpusMemorySearchResult[]>;
-            searchWhisperer?(queries: QueryPair, opts: Pick<CorpusSearchOptions, "corpora" | "signal" | "maxSnippetChars">): Promise<CorpusMemorySearchResult[]>;
-        } | null;
+        manager: MemoryCandidateManager | null;
     }>;
 };
 export declare function registerMemoryWhisperer(api: OpenClawPluginApi, runtime: MemoryWhispererRuntime, config: UnblockMemoryConfig["memoryWhisperer"], typesafe: UnblockMemoryConfig["typesafe"], diagnostics?: WhispererDiagnostics): Parameters<typeof api.on<"before_prompt_build">>[1] | undefined;