@unblocklabs/unblock-memory 0.8.1 → 0.8.3

package/dist/src/contracts.d.ts

@@ -2,6 +2,7 @@ import type { MemoryPluginCapability } from "openclaw/plugin-sdk/memory-host-cor
 import type { OpenClawPluginToolContext } from "openclaw/plugin-sdk/plugin-entry";
 import type { SessionMetadata, SessionSnippetMessage } from "./session-projector.js";
 import type { ChatType } from "./config.js";
+import type { RetrievalTimings } from "./retrieval-timing.js";
 export type MemoryPluginRuntimeContract = NonNullable<MemoryPluginCapability["runtime"]>;
 type ManagerLookup = Awaited<ReturnType<MemoryPluginRuntimeContract["getMemorySearchManager"]>>;
 export type MemorySearchManagerContract = NonNullable<ManagerLookup["manager"]>;
@@ -35,6 +36,8 @@ export type CorpusSearchOptions = Omit<NonNullable<Parameters<MemorySearchManage
     maxSnippetChars?: number;
     sessionFilter?: SessionSearchFilter;
     requestContext?: MemoryRequestContext;
+    /** Internal, per-call numeric timing sink; never part of tool input/output. */
+    timings?: RetrievalTimings;
 };
 export type MemoryEmbeddingProbeResult = Awaited<ReturnType<MemorySearchManagerContract["probeEmbeddingAvailability"]>>;
 export type MemorySyncParams = Parameters<NonNullable<MemorySearchManagerContract["sync"]>>[0];

package/dist/src/diagnostics.d.ts

@@ -59,6 +59,37 @@ export declare class WhispererDiagnostics {
                         empty?: number | undefined;
                         timed_out?: number | undefined;
                     };
+                    slowestRecent: {
+                        outcome: "ok" | "cancelled" | "partial" | "skipped" | "failed" | "empty" | "timed_out";
+                        setupMs?: number | undefined;
+                        queueWaitMs?: number | undefined;
+                        metadataMs?: number | undefined;
+                        storeSetupMs?: number | undefined;
+                        bm25Ms?: number | undefined;
+                        vectorMs?: number | undefined;
+                        vectorIndexCheckMs?: number | undefined;
+                        vectorScopeMs?: number | undefined;
+                        embeddingMs?: number | undefined;
+                        vectorScanMs?: number | undefined;
+                        hydrationMs?: number | undefined;
+                        vectorMappingMs?: number | undefined;
+                        vectorOtherMs?: number | undefined;
+                        passageMs?: number | undefined;
+                        candidatePrepMs?: number | undefined;
+                        retrievalOtherMs?: number | undefined;
+                        otherMs?: number | undefined;
+                        retrievalMs?: number | undefined;
+                        judgeMs?: number | undefined;
+                        metadataReloads?: number | undefined;
+                        vectorScanAttempts?: number | undefined;
+                        elapsedMs?: number | undefined;
+                        gateMs?: number | undefined;
+                        generationMs?: number | undefined;
+                        candidates?: number | undefined;
+                        eligible?: number | undefined;
+                        results?: number | undefined;
+                        contextChars?: number | undefined;
+                    }[];
                     measurements: {
                         [k: string]: {
                             total: number;

package/dist/src/manager.d.ts

@@ -62,6 +62,37 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
                         empty?: number | undefined;
                         timed_out?: number | undefined;
                     };
+                    slowestRecent: {
+                        outcome: "ok" | "cancelled" | "partial" | "skipped" | "failed" | "empty" | "timed_out";
+                        setupMs?: number | undefined;
+                        queueWaitMs?: number | undefined;
+                        metadataMs?: number | undefined;
+                        storeSetupMs?: number | undefined;
+                        bm25Ms?: number | undefined;
+                        vectorMs?: number | undefined;
+                        vectorIndexCheckMs?: number | undefined;
+                        vectorScopeMs?: number | undefined;
+                        embeddingMs?: number | undefined;
+                        vectorScanMs?: number | undefined;
+                        hydrationMs?: number | undefined;
+                        vectorMappingMs?: number | undefined;
+                        vectorOtherMs?: number | undefined;
+                        passageMs?: number | undefined;
+                        candidatePrepMs?: number | undefined;
+                        retrievalOtherMs?: number | undefined;
+                        otherMs?: number | undefined;
+                        retrievalMs?: number | undefined;
+                        judgeMs?: number | undefined;
+                        metadataReloads?: number | undefined;
+                        vectorScanAttempts?: number | undefined;
+                        elapsedMs?: number | undefined;
+                        gateMs?: number | undefined;
+                        generationMs?: number | undefined;
+                        candidates?: number | undefined;
+                        eligible?: number | undefined;
+                        results?: number | undefined;
+                        contextChars?: number | undefined;
+                    }[];
                     measurements: {
                         [k: string]: {
                             total: number;

package/dist/src/manager.js

@@ -18,11 +18,11 @@ import { abortable } from "./abortable.js";
 import { RetrievalTelemetry } from "./retrieval-telemetry.js";
 import { trainingCandidates } from "./training-candidates.js";
 import { expandSessionSearchHit, renderMemoryPassage } from "./memory-passage.js";
+import { startTiming, timeStage, vectorTrace, vectorParts, unaccounted } from "./retrieval-timing.js";
 export { expandSessionSearchHit } from "./memory-passage.js";
 const DEFAULT_READ_LINES = 120;
 const MAX_READ_CHARS = 12_000;
 const WATCH_DEBOUNCE_MS = 250;
-const qmdModule = import("@unblocklabs/qmd");
 function readSkillDocuments(source) {
     const documents = [];
     const visitedDirectories = new Set();
@@ -304,10 +304,12 @@ export class QmdMemoryManager {
     async #refreshSessionMetadata() {
         const sessions = this.#sessions;
         if (!sessions)
-            return;
+            return false;
         const mtimeNs = await this.#manifestMtimeNs(sessions.manifestPath);
-        if (mtimeNs !== this.#sessionManifestMtimeNs)
-            await this.#reloadSessionMetadata();
+        if (mtimeNs === this.#sessionManifestMtimeNs)
+            return false;
+        await this.#reloadSessionMetadata();
+        return true;
     }
     #startWatcher() {
         const paths = [...new Set([...this.#sources.values()]
@@ -362,7 +364,7 @@ export class QmdMemoryManager {
             }
             return this.#store;
         }
-        const { createStore } = await qmdModule;
+        const { createStore } = await import("@unblocklabs/qmd");
         const store = await createStore({
             dbPath: this.#dbPath,
             keepModelsWarm: this.#keepModelsWarm,
@@ -833,34 +835,57 @@ export class QmdMemoryManager {
     }
     /** 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);
-            if (!collections.length)
-                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"]) {
+        const { timings, signal } = opts;
+        const endQueueWait = startTiming("queueWaitMs", timings, signal);
+        try {
+            return await this.#enqueue(async () => {
+                endQueueWait();
                 opts.signal?.throwIfAborted();
-                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,
-                            chunkPos: hit.bestChunkPos, chunkLen: hit.bestChunk.length, displayPath: hit.file, score: hit.score });
+                const collections = this.#collectionNames(opts.corpora);
+                if (!collections.length)
+                    return [];
+                const allowedPaths = await timeStage("metadataMs", timings, signal, async () => {
+                    if (this.#sessions && collections.includes(this.#sessions.collection)) {
+                        const reloaded = await this.#refreshSessionMetadata();
+                        if (timings && !signal?.aborted)
+                            timings.metadataReloads = Number(reloaded);
+                    }
+                    const sessions = this.#sessions;
+                    let allowed = opts.sessionFilter && sessions && collections.includes(sessions.collection)
+                        ? sessionAllowedPaths(this.#sessionMetadata, sessions.collection, opts.sessionFilter) : undefined;
+                    if (collections.includes(EXTRACTED_COLLECTION)) {
+                        allowed = { ...allowed, [EXTRACTED_COLLECTION]: this.#currentExtracted(undefined, opts.sessionFilter).map(extractedPath) };
+                    }
+                    return allowed;
+                });
+                const store = await timeStage("storeSetupMs", timings, signal, () => this.#getAnalysisStore());
+                const hits = new Map();
+                // Serialize native QMD work. Cancellation prevents further queries/collections.
+                for (const lane of ["lex", "vec"]) {
+                    opts.signal?.throwIfAborted();
+                    let candidates;
+                    try {
+                        candidates = await timeStage(lane === "lex" ? "bm25Ms" : "vectorMs", timings, signal, () => trainingCandidates(store, queries[lane], collections, lane, opts.signal, allowedPaths, lane === "vec" ? vectorTrace(timings, signal) : undefined));
+                    }
+                    finally {
+                        if (lane === "vec" && timings?.vectorMs !== undefined) {
+                            timings.vectorOtherMs = unaccounted(timings.vectorMs, timings, vectorParts);
+                        }
+                    }
+                    for (const hit of candidates) {
+                        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, true);
-        });
+                opts.signal?.throwIfAborted();
+                return timeStage("passageMs", timings, signal, () => this.#renderSearchHits([...hits.values()], store, opts, true));
+            });
+        }
+        finally {
+            endQueueWait();
+        }
     }
     async #renderSearchHits(hits, store, opts, whisperer = false) {
         const tokenizer = store.internal?.llm;
@@ -932,7 +957,7 @@ export class QmdMemoryManager {
         if (!store.internal?.llm)
             throw new Error("Skill Whisperer requires the QMD embedding model");
         const llm = store.internal.llm;
-        const { formatDocForEmbedding, formatQueryForEmbedding } = await qmdModule;
+        const { formatDocForEmbedding, formatQueryForEmbedding } = await import("@unblocklabs/qmd");
         let skillIndex = this.#skillIndex;
         if (!skillIndex) {
             const pending = (async () => {

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

@@ -1,10 +1,11 @@
 import type { CorpusMemorySearchResult, CorpusSearchOptions } from "./contracts.js";
 import type { QueryConversation, QueryPair } from "./query-contract.js";
+import { type RetrievalTimings } from "./retrieval-timing.js";
 export type MemoryCandidateManager = {
     searchCandidates(queries: QueryPair, options: CorpusSearchOptions): Promise<CorpusMemorySearchResult[]>;
 };
 export declare function memoryPassageId(text: string): string;
-export type MemorySearchObservation = {
+export type MemorySearchObservation = RetrievalTimings & {
     retrievalMs: number;
     judgeMs: number;
     candidates: number;

package/dist/src/memory-search.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { MEMORY_PASSAGE_CHARS, duplicateMemoryPassage } from "./memory-passage.js";
 import { judgeMemoryPassage, memoryUsefulnessRequest } from "./typesafe.js";
+import { startTiming, retrievalParts, unaccounted } from "./retrieval-timing.js";
 export function memoryPassageId(text) {
     return createHash("sha256").update(text.replace(/\s+/gu, " ").trim()).digest("hex");
 }
@@ -9,53 +10,74 @@ 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,
-    });
+    const timings = options.timings ?? {};
+    const endRetrieval = startTiming("retrievalMs", timings, signal);
+    let hits;
+    try {
+        hits = await manager.searchCandidates(queries, {
+            corpora: options.corpora, sessionFilter: options.sessionFilter, requestContext: options.requestContext,
+            sources: options.sources, signal, maxSnippetChars: MEMORY_PASSAGE_CHARS, timings,
+        });
+    }
+    finally {
+        endRetrieval();
+        if (timings.retrievalMs !== undefined)
+            timings.retrievalOtherMs = unaccounted(timings.retrievalMs, timings, retrievalParts);
+    }
     signal?.throwIfAborted();
-    const observation = { retrievalMs: performance.now() - started, judgeMs: 0,
+    const observation = { retrievalMs: timings.retrievalMs ?? 0, 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 });
+    const endCandidatePrep = startTiming("candidatePrepMs", timings, signal);
+    try {
+        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 });
+        }
+    }
+    finally {
+        endCandidatePrep();
     }
     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)
+    const endJudge = startTiming("judgeMs", timings, signal);
+    let judged;
+    try {
+        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 [];
-            observation.requestsFailed++;
-            options.onJudgment?.({ candidateIndex, elapsedMs: performance.now() - requestStarted, error });
-            return [];
-        }
-    }))).flat();
+            }
+        }))).flat();
+    }
+    finally {
+        endJudge();
+    }
     signal?.throwIfAborted();
-    observation.judgeMs = performance.now() - judgeStarted;
-    return { ...observation, results: judged.filter(hit => hit.score >= (options.minUsefulness ?? 0.7))
+    observation.judgeMs = timings.judgeMs ?? 0;
+    return { ...timings, ...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.js

@@ -4,6 +4,7 @@ import { ApiQueryGenerator, QueryApiError, queryConversation } from "./query-gen
 import { judgeTrainingInput, TRAINING_GATE_THRESHOLD } from "./training-gate.js";
 import { QueryInputBudgetError } from "./query-contract.js";
 import { searchMemory, memoryPassageId } from "./memory-search.js";
+import { timeStage } from "./retrieval-timing.js";
 export function registerMemoryWhisperer(api, runtime, config, typesafe, diagnostics) {
     if (!config.enabled || !typesafe.enabled)
         return;
@@ -53,7 +54,7 @@ export function registerMemoryWhisperer(api, runtime, config, typesafe, diagnost
         const run = async () => {
             const conversation = queryConversation(event.prompt, event.messages);
             stage = "credentials";
-            const apiKey = await resolveTypeSafeApiKey(typesafe);
+            const apiKey = await timeStage("setupMs", measurement, signal, () => resolveTypeSafeApiKey(typesafe));
             if (signal.aborted)
                 return;
             if (!apiKey) {
@@ -112,7 +113,7 @@ export function registerMemoryWhisperer(api, runtime, config, typesafe, diagnost
                     measurement.generationMs = performance.now() - generationStarted;
                 }
                 stage = "retrieval";
-                const { manager } = await runtime.getMemorySearchManager({ cfg: api.config, agentId });
+                const { manager } = await timeStage("setupMs", measurement, signal, () => runtime.getMemorySearchManager({ cfg: api.config, agentId }));
                 if (signal.aborted)
                     return;
                 if (!manager) {
@@ -121,7 +122,7 @@ export function registerMemoryWhisperer(api, runtime, config, typesafe, diagnost
                     return;
                 }
                 const search = await searchMemory(manager, queries, {
-                    corpora, signal, apiKey, timeoutMs: typesafe.timeoutMs, conversation, asOf,
+                    corpora, signal, apiKey, timeoutMs: typesafe.timeoutMs, conversation, asOf, timings: measurement,
                     minUsefulness: config.minUsefulness, maxResults: 4, excludedPassages: state.recent,
                     onCandidates: observation => {
                         measurement.retrievalMs = observation.retrievalMs;

package/dist/src/plugin.js

@@ -78,6 +78,7 @@ function createSearchTool(runtime, ctx, typesafe, diagnostics) {
                     return jsonResult({ results: [], error: "TypeSafe API key not configured or TypeSafe disabled" });
                 }
                 const { manager, error } = await runtime.getMemorySearchManager(active);
+                measurement.setupMs = performance.now() - started;
                 if (!manager)
                     return jsonResult({ results: [], error: error ?? "memory unavailable" });
                 const search = await searchMemory(manager, queries, {
@@ -86,7 +87,7 @@ function createSearchTool(runtime, ctx, typesafe, diagnostics) {
                     maxResults,
                     minUsefulness,
                     apiKey, timeoutMs: typesafe.timeoutMs, conversation,
-                    signal,
+                    signal, timings: measurement,
                     requestContext: active.requestContext,
                     onCandidates: ({ retrievalMs, candidates, eligible }) => {
                         Object.assign(measurement, { retrievalMs, candidates, eligible });
@@ -121,6 +122,10 @@ function createSearchTool(runtime, ctx, typesafe, diagnostics) {
             }
             finally {
                 measurement.elapsedMs = performance.now() - started;
+                measurement.setupMs ??= measurement.elapsedMs;
+                // Manual search is sequential. Whisperer stages overlap and cannot use this subtraction.
+                measurement.otherMs = Math.max(0, measurement.elapsedMs - measurement.setupMs -
+                    (measurement.retrievalMs ?? 0) - (measurement.candidatePrepMs ?? 0) - (measurement.judgeMs ?? 0));
                 if (signal?.aborted)
                     measurement.outcome = signal.reason instanceof Error && signal.reason.name === "TimeoutError"
                         ? "timed_out" : "cancelled";

package/dist/src/retrieval-telemetry.d.ts

@@ -1,11 +1,12 @@
+import { type RetrievalTimings } from "./retrieval-timing.js";
 type RetrievalOperation = "vector" | "memoryWhisperer" | "memorySearch";
 type RetrievalOutcome = "ok" | "partial" | "empty" | "failed" | "cancelled" | "timed_out" | "skipped";
-declare const fields: readonly ["elapsedMs", "retrievalMs", "judgeMs", "gateMs", "generationMs", "candidates", "eligible", "results", "contextChars"];
+declare const fields: readonly ["elapsedMs", "retrievalMs", "judgeMs", "gateMs", "generationMs", "setupMs", "queueWaitMs", "metadataMs", "storeSetupMs", "bm25Ms", "vectorMs", "vectorIndexCheckMs", "vectorScopeMs", "embeddingMs", "vectorScanMs", "hydrationMs", "vectorMappingMs", "vectorOtherMs", "passageMs", "candidatePrepMs", "retrievalOtherMs", "otherMs", "metadataReloads", "vectorScanAttempts", "candidates", "eligible", "results", "contextChars"];
 type Field = typeof fields[number];
 export type RetrievalObservation = {
     outcome: RetrievalOutcome;
     elapsedMs: number;
-} & Partial<Record<Field, number>>;
+} & RetrievalTimings & Partial<Record<Field, number>>;
 /** Only fixed operation/outcome names and nonnegative numbers enter this store. */
 export declare class RetrievalTelemetry {
     #private;
@@ -24,6 +25,37 @@ export declare class RetrievalTelemetry {
                     empty?: number | undefined;
                     timed_out?: number | undefined;
                 };
+                slowestRecent: {
+                    outcome: RetrievalOutcome;
+                    setupMs?: number | undefined;
+                    queueWaitMs?: number | undefined;
+                    metadataMs?: number | undefined;
+                    storeSetupMs?: number | undefined;
+                    bm25Ms?: number | undefined;
+                    vectorMs?: number | undefined;
+                    vectorIndexCheckMs?: number | undefined;
+                    vectorScopeMs?: number | undefined;
+                    embeddingMs?: number | undefined;
+                    vectorScanMs?: number | undefined;
+                    hydrationMs?: number | undefined;
+                    vectorMappingMs?: number | undefined;
+                    vectorOtherMs?: number | undefined;
+                    passageMs?: number | undefined;
+                    candidatePrepMs?: number | undefined;
+                    retrievalOtherMs?: number | undefined;
+                    otherMs?: number | undefined;
+                    retrievalMs?: number | undefined;
+                    judgeMs?: number | undefined;
+                    metadataReloads?: number | undefined;
+                    vectorScanAttempts?: number | undefined;
+                    elapsedMs?: number | undefined;
+                    gateMs?: number | undefined;
+                    generationMs?: number | undefined;
+                    candidates?: number | undefined;
+                    eligible?: number | undefined;
+                    results?: number | undefined;
+                    contextChars?: number | undefined;
+                }[];
                 measurements: {
                     [k: string]: {
                         total: number;

package/dist/src/retrieval-telemetry.js

@@ -1,15 +1,20 @@
-const fields = ["elapsedMs", "retrievalMs", "judgeMs", "gateMs", "generationMs", "candidates", "eligible", "results", "contextChars"];
+import { timingFields } from "./retrieval-timing.js";
+const fields = ["elapsedMs", "retrievalMs", "judgeMs", "gateMs", "generationMs", ...timingFields,
+    "metadataReloads", "vectorScanAttempts", "candidates", "eligible", "results", "contextChars"];
 const recentLimit = 256;
+const outcomes = ["ok", "partial", "empty", "failed", "cancelled", "timed_out", "skipped"];
 const boundedAdd = (left, right) => Math.min(Number.MAX_SAFE_INTEGER, left + right);
 /** Only fixed operation/outcome names and nonnegative numbers enter this store. */
 export class RetrievalTelemetry {
     #entries = new Map();
     record(operation, observation) {
+        if (!["vector", "memoryWhisperer", "memorySearch"].includes(operation) || !outcomes.includes(observation.outcome))
+            return;
         const entry = this.#entries.get(operation) ?? { calls: 0, outcomes: {}, totals: {}, recent: [] };
         this.#entries.set(operation, entry);
         entry.calls = boundedAdd(entry.calls, 1);
         entry.outcomes[observation.outcome] = boundedAdd(entry.outcomes[observation.outcome] ?? 0, 1);
-        const sample = {};
+        const sample = { outcome: observation.outcome };
         for (const field of fields) {
             const value = observation[field];
             if (value === undefined || !Number.isFinite(value) || value < 0)
@@ -28,6 +33,8 @@ export class RetrievalTelemetry {
             operations: Object.fromEntries([...this.#entries].map(([operation, entry]) => [operation, {
                     calls: entry.calls,
                     outcomes: { ...entry.outcomes },
+                    slowestRecent: entry.recent.filter(sample => sample.elapsedMs !== undefined)
+                        .toSorted((a, b) => b.elapsedMs - a.elapsedMs).slice(0, 5).map(sample => ({ ...sample })),
                     measurements: Object.fromEntries(fields.map(field => {
                         const values = entry.recent.flatMap(sample => sample[field] === undefined ? [] : [sample[field]]).sort((a, b) => a - b);
                         const percentile = (fraction) => values.length ? values[Math.ceil(values.length * fraction) - 1] : null;

package/dist/src/retrieval-timing.d.ts

@@ -0,0 +1,12 @@
+import type { VectorSearchTrace } from "@unblocklabs/qmd";
+export declare const timingFields: readonly ["setupMs", "queueWaitMs", "metadataMs", "storeSetupMs", "bm25Ms", "vectorMs", "vectorIndexCheckMs", "vectorScopeMs", "embeddingMs", "vectorScanMs", "hydrationMs", "vectorMappingMs", "vectorOtherMs", "passageMs", "candidatePrepMs", "retrievalOtherMs", "otherMs"];
+type TimingField = typeof timingFields[number] | "retrievalMs" | "judgeMs";
+export type RetrievalTimings = Partial<Record<TimingField | "metadataReloads" | "vectorScanAttempts", number>>;
+/** Freeze in-flight duration at abort, without changing the work's cancellation behavior. */
+export declare function startTiming(field: TimingField, timings?: RetrievalTimings, signal?: AbortSignal): () => void;
+export declare function timeStage<T>(field: TimingField, timings: RetrievalTimings | undefined, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T>;
+export declare function vectorTrace(timings?: RetrievalTimings, signal?: AbortSignal): VectorSearchTrace | undefined;
+export declare function unaccounted(total: number, timings: RetrievalTimings, fields: readonly TimingField[]): number;
+export declare const vectorParts: ("vectorIndexCheckMs" | "vectorScopeMs" | "embeddingMs" | "vectorScanMs" | "hydrationMs" | "vectorMappingMs")[];
+export declare const retrievalParts: readonly ["queueWaitMs", "metadataMs", "storeSetupMs", "bm25Ms", "vectorMs", "passageMs"];
+export {};

package/dist/src/retrieval-timing.js

@@ -0,0 +1,52 @@
+export const timingFields = ["setupMs", "queueWaitMs", "metadataMs", "storeSetupMs", "bm25Ms", "vectorMs",
+    "vectorIndexCheckMs", "vectorScopeMs", "embeddingMs", "vectorScanMs", "hydrationMs", "vectorMappingMs",
+    "vectorOtherMs", "passageMs", "candidatePrepMs", "retrievalOtherMs", "otherMs"];
+/** Freeze in-flight duration at abort, without changing the work's cancellation behavior. */
+export function startTiming(field, timings, signal) {
+    if (!timings || signal?.aborted)
+        return () => { };
+    const started = performance.now();
+    const previous = timings[field] ?? 0;
+    let ended = false;
+    const end = () => {
+        if (ended)
+            return;
+        ended = true;
+        timings[field] = previous + performance.now() - started;
+        signal?.removeEventListener("abort", end);
+    };
+    signal?.addEventListener("abort", end, { once: true });
+    return end;
+}
+export async function timeStage(field, timings, signal, run) {
+    const end = startTiming(field, timings, signal);
+    try {
+        return await run();
+    }
+    finally {
+        end();
+    }
+}
+const vectorFields = {
+    index_check: "vectorIndexCheckMs", scope_resolution: "vectorScopeMs", embedding: "embeddingMs",
+    vector_scan_knn: "vectorScanMs", hydration: "hydrationMs", result_mapping: "vectorMappingMs",
+};
+export function vectorTrace(timings, signal) {
+    if (!timings)
+        return;
+    return timing => {
+        if (signal?.aborted || !Number.isFinite(timing.durationMs) || timing.durationMs < 0)
+            return;
+        const field = vectorFields[timing.stage];
+        if (!field)
+            return;
+        timings[field] = (timings[field] ?? 0) + timing.durationMs;
+        if (timing.stage === "vector_scan_knn")
+            timings.vectorScanAttempts = (timings.vectorScanAttempts ?? 0) + 1;
+    };
+}
+export function unaccounted(total, timings, fields) {
+    return Math.max(0, total - fields.reduce((sum, field) => sum + (timings[field] ?? 0), 0));
+}
+export const vectorParts = Object.values(vectorFields);
+export const retrievalParts = ["queueWaitMs", "metadataMs", "storeSetupMs", "bm25Ms", "vectorMs", "passageMs"];

package/dist/src/training-candidates.d.ts

@@ -1,7 +1,7 @@
-import type { AllowedDocumentPaths, QMDStore } from "@unblocklabs/qmd";
+import type { AllowedDocumentPaths, QMDStore, VectorSearchTrace } from "@unblocklabs/qmd";
 import type { QueryLane } from "./query-contract.js";
 /** Runtime and training share the exact ten-candidate recipe, not hybrid ranking. */
-export declare function trainingCandidates(qmd: QMDStore, query: string, collection: string | string[], lane: QueryLane, signal?: AbortSignal, allowedPaths?: AllowedDocumentPaths): Promise<{
+export declare function trainingCandidates(qmd: QMDStore, query: string, collection: string | string[], lane: QueryLane, signal?: AbortSignal, allowedPaths?: AllowedDocumentPaths, trace?: VectorSearchTrace): Promise<{
     vector?: {
         score: number;
         rank: number;

package/dist/src/training-candidates.js

@@ -1,8 +1,8 @@
 /** Runtime and training share the exact ten-candidate recipe, not hybrid ranking. */
-export async function trainingCandidates(qmd, query, collection, lane, signal, allowedPaths) {
+export async function trainingCandidates(qmd, query, collection, lane, signal, allowedPaths, trace) {
     const hits = await qmd.discoverCandidates({ query, lane, collection, limit: 10, signal,
         // Preserve keyword chunk tie-breaking against this lane's own query.
-        intent: query, allowedPaths });
+        intent: query, allowedPaths, trace });
     return hits.map(({ method, rank, score, file, body, bestChunk, bestChunkPos }) => {
         const retrieval = {
             [method]: { score, rank: rank + 1 },

package/docs/retrieval.md

@@ -80,6 +80,31 @@ judging time, candidate/result counts and outcomes (including partial failures).
 These counters are separate from automatic `memoryWhisperer` and internal `vector`
 retrieval; no query or evidence text is recorded.
 
+Both `memorySearch` and `memoryWhisperer` also report per-call stage measurements:
+
+- `setupMs`: credentials and manager initialization (manual search also includes input validation).
+- `queueWaitMs`: waiting for admission behind other index operations.
+- `metadataMs` / `metadataReloads`: session metadata refresh and evidence filtering; reload count is
+  present only when the session corpus is selected and refresh completes.
+- `storeSetupMs`: opening or obtaining the QMD store.
+- `bm25Ms` and `vectorMs`: complete sequential candidate-discovery lanes.
+- Inside `vectorMs`, QMD reports `vectorIndexCheckMs`, `vectorScopeMs`, `embeddingMs`,
+  `vectorScanMs`, `hydrationMs`, and `vectorMappingMs`. Repeated scan/hydration stages are summed;
+  `vectorScanAttempts` counts native scans. Embedding time includes any lazy model/context setup.
+- `passageMs`: rendering merged candidates; `candidatePrepMs`: eligibility checks and deduplication
+  before disclosure to TypeSafe. `judgeMs` covers the concurrent candidate judgments, not their sum.
+- `vectorOtherMs` and `retrievalOtherMs` expose time outside measured child stages. `otherMs` accounts
+  for the remaining manual tool execution. Whisperer stages overlap, so no additive whole-run
+  residual is reported for it. Parent durations must not be added to their child durations.
+
+Each measurement includes lifetime totals/sample counts and p50/p95 over up to 256 recent calls.
+`slowestRecent` contains the five slowest calls **within that same window**, each with its outcome
+and numeric breakdown, so stages can be correlated without combining unrelated percentiles.
+With 12 samples, nearest-rank p95 is the largest sample. Whole-tool time excludes Gateway transport.
+Failed/cancelled calls retain completed stages and in-flight durations through cancellation;
+unexecuted stages and unfinished native trace stages are absent, not zero. No query, passage,
+path, credential or session identifier is retained; samples are process-local and reset on recreation.
+
 Corpora and session filters select evidence; they are not audience ACLs. Normal
 tools can access this agent's configured non-skill corpora, not just its current
 chat. Only index material suitable for the agent's tool callers. Per-feature

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "unblock-memory",
   "name": "Unblock Memory",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Indexes, retrieves, and analyzes configured workspace memory with existing QMD vectors.",
   "kind": "memory",
   "activation": { "onStartup": true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unblocklabs/unblock-memory",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Workspace-native memory for OpenClaw, powered by QMD",
   "type": "module",
   "license": "MIT",