@anuma/sdk 7.1.1 → 7.3.0

package/dist/expo/index.cjs

@@ -16713,10 +16713,18 @@ function admitVaultProjections(queryEmbedding, vectored, k) {
 }
 async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, queryOpts, opts) {
   let rowsDecrypted = 0;
+  const keysStart = nowMs();
   const keys = await getVaultCandidateKeysOp(
     vaultCtx,
     Object.keys(queryOpts).length > 0 ? queryOpts : void 0
   );
+  const corpusStats = {
+    keysMs: nowMs() - keysStart,
+    embeddingsFetchMs: 0,
+    rowsFetchMs: 0,
+    cacheHits: 0,
+    cacheMisses: 0
+  };
   const hydrateOpts = queryOpts.includeArchived ? { includeArchived: true } : void 0;
   const vaultSize = keys.length;
   if (keys.length === 0) {
@@ -16726,7 +16734,8 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
       queryEmbedding: [],
       vaultSize: 0,
       laneEmbedFailed: false,
-      rowsDecrypted: 0
+      rowsDecrypted: 0,
+      corpusStats
     };
   }
   const queryEmbedStart = nowMs();
@@ -16748,16 +16757,20 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
     for (const k2 of keys) {
       const cached = cachedRowVector(cache, k2.uniqueId, k2.updatedAt);
       if (cached && cached.length === queryEmbedding.length) {
+        corpusStats.cacheHits++;
         vectored.push({ uniqueId: k2.uniqueId, embedding: cached, updatedAt: k2.updatedAt });
         continue;
       }
+      corpusStats.cacheMisses++;
       const modelCompatible = (k2.embeddingModel ?? currentModel) === currentModel;
       if (modelCompatible) missIds.push(k2.uniqueId);
       else noVectorIds.push(k2.uniqueId);
     }
   }
   if (missIds.length > 0) {
+    const embeddingsStart = nowMs();
     const rows = await getVaultEmbeddingsByIdsOp(vaultCtx, missIds, hydrateOpts);
+    corpusStats.embeddingsFetchMs += nowMs() - embeddingsStart;
     const gotVector = /* @__PURE__ */ new Set();
     for (const r of rows) {
       if (!r.embedding) continue;
@@ -16785,7 +16798,9 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
         `memoryVault: projected search un-embedded lane capped at ${laneIds.length}/${noVectorIds.length}`
       );
     }
+    const laneStart = nowMs();
     const laneFetched = await getVaultMemoriesByIdsOp(vaultCtx, laneIds, hydrateOpts);
+    corpusStats.rowsFetchMs += nowMs() - laneStart;
     rowsDecrypted += laneFetched.length;
     for (const row of laneFetched) laneById.set(row.uniqueId, row);
     const laneRows = laneFetched.filter((m) => !isEncrypted(m.content));
@@ -16837,7 +16852,9 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
     }
   }
   const idsToFetch = [...admissionSet].filter((id) => !laneById.has(id));
+  const admittedStart = nowMs();
   const fetched = idsToFetch.length > 0 ? await getVaultMemoriesByIdsOp(vaultCtx, idsToFetch, hydrateOpts) : [];
+  corpusStats.rowsFetchMs += nowMs() - admittedStart;
   rowsDecrypted += fetched.length;
   const admittedRows = [
     ...fetched,
@@ -16866,7 +16883,10 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
   }
   if (staleIds.length > 0) {
     const contentById = new Map(memories.map((m) => [m.uniqueId, m]));
-    for (const r of await getVaultEmbeddingsByIdsOp(vaultCtx, staleIds, hydrateOpts)) {
+    const staleStart = nowMs();
+    const staleRows = await getVaultEmbeddingsByIdsOp(vaultCtx, staleIds, hydrateOpts);
+    corpusStats.embeddingsFetchMs += nowMs() - staleStart;
+    for (const r of staleRows) {
       if (!r.embedding) continue;
       try {
         const parsed = JSON.parse(r.embedding);
@@ -16898,7 +16918,15 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
     eventTimeKind: normalizeEventTimeKind(m.eventTimeKind),
     factType: m.factType
   }));
-  return { memories, embeddedItems, queryEmbedding, vaultSize, laneEmbedFailed, rowsDecrypted };
+  return {
+    memories,
+    embeddedItems,
+    queryEmbedding,
+    vaultSize,
+    laneEmbedFailed,
+    rowsDecrypted,
+    corpusStats
+  };
 }
 async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache, searchOptions) {
   if (!query || typeof query !== "string") {
@@ -16939,6 +16967,7 @@ async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache,
     embeddingFailure = true;
   };
   const embedStats = { queryMs: 0, rowsEmbedded: 0 };
+  let corpusStats;
   if (searchOptions?.decryptLast) {
     const forceIncludeIds = [
       ...searchOptions.entityRanking ?? [],
@@ -16959,6 +16988,7 @@ async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache,
       onEmbeddingDegraded,
       embedStats
     });
+    corpusStats = corpus.corpusStats;
     if (corpus.vaultSize === 0) {
       return {
         memories: [],
@@ -16970,7 +17000,8 @@ async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache,
         decryptLast: true,
         rowsDecrypted: corpus.rowsDecrypted,
         queryEmbedMs: embedStats.queryMs,
-        rowsEmbedded: embedStats.rowsEmbedded
+        rowsEmbedded: embedStats.rowsEmbedded,
+        corpusStats
       };
     }
     ({ memories, embeddedItems, queryEmbedding, vaultSize } = corpus);
@@ -16987,7 +17018,8 @@ async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache,
         decryptLast: true,
         rowsDecrypted: corpus.rowsDecrypted,
         queryEmbedMs: embedStats.queryMs,
-        rowsEmbedded: embedStats.rowsEmbedded
+        rowsEmbedded: embedStats.rowsEmbedded,
+        corpusStats
       };
     }
   } else {
@@ -17120,7 +17152,8 @@ async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache,
     embeddingsUnavailable,
     embeddingFailure,
     decryptLast: !!searchOptions?.decryptLast,
-    rowsDecrypted
+    rowsDecrypted,
+    ...corpusStats && { corpusStats }
   };
 }
 async function rankPreparedVaultCandidates(query, prepared, embeddingOptions, searchOptions) {
@@ -17337,7 +17370,8 @@ async function searchVaultMemoriesWithSize(query, vaultCtx, embeddingOptions, ca
       decryptLast: prepared.decryptLast,
       rowsDecrypted: prepared.rowsDecrypted,
       queryEmbedMs: prepared.queryEmbedMs,
-      rowsEmbedded: prepared.rowsEmbedded
+      rowsEmbedded: prepared.rowsEmbedded,
+      ...prepared.corpusStats && { corpusStats: prepared.corpusStats }
     };
   }
   if (prepared.memories.length === 0) {
@@ -17352,7 +17386,8 @@ async function searchVaultMemoriesWithSize(query, vaultCtx, embeddingOptions, ca
       decryptLast: prepared.decryptLast,
       rowsDecrypted: prepared.rowsDecrypted,
       queryEmbedMs: prepared.queryEmbedMs,
-      rowsEmbedded: prepared.rowsEmbedded
+      rowsEmbedded: prepared.rowsEmbedded,
+      ...prepared.corpusStats && { corpusStats: prepared.corpusStats }
     };
   }
   const ranked = await rankPreparedVaultCandidates(
@@ -17367,7 +17402,8 @@ async function searchVaultMemoriesWithSize(query, vaultCtx, embeddingOptions, ca
     decryptLast: prepared.decryptLast,
     rowsDecrypted: prepared.rowsDecrypted,
     queryEmbedMs: prepared.queryEmbedMs,
-    rowsEmbedded: prepared.rowsEmbedded
+    rowsEmbedded: prepared.rowsEmbedded,
+    ...prepared.corpusStats && { corpusStats: prepared.corpusStats }
   };
 }
 async function searchVaultMemories(query, vaultCtx, embeddingOptions, cache, searchOptions) {
@@ -19356,6 +19392,7 @@ async function recall(query, ctx, options = {}) {
   let factLaneRankedOnCosine = false;
   let decryptLastRan;
   let vaultRowsDecrypted;
+  let corpusStats;
   let graphLaneCount = 0;
   let temporalLaneCount = 0;
   let graphLaneFailed = false;
@@ -19396,6 +19433,10 @@ async function recall(query, ctx, options = {}) {
       ...decryptLastRan !== void 0 && { decryptLast: decryptLastRan },
       ...vaultRowsDecrypted !== void 0 && { vaultRowsDecrypted },
       ...vaultRowsEmbedded !== void 0 && { vaultRowsEmbedded },
+      ...corpusStats && {
+        vaultCacheHits: corpusStats.cacheHits,
+        vaultCacheMisses: corpusStats.cacheMisses
+      },
       ...chunkStats && {
         chunkRowsScanned: chunkStats.rowsScanned,
         chunkRowsFetched: chunkStats.rowsFetched,
@@ -19418,7 +19459,12 @@ async function recall(query, ctx, options = {}) {
         rerank: rerankMs,
         queryEmbed: queryEmbedMs,
         chunkLane: chunkLaneMs,
-        fuse: fuseMs
+        fuse: fuseMs,
+        ...corpusStats && {
+          corpusKeys: corpusStats.keysMs,
+          corpusEmbeddingsFetch: corpusStats.embeddingsFetchMs,
+          corpusRowsFetch: corpusStats.rowsFetchMs
+        }
       },
       degraded
     };
@@ -19492,7 +19538,8 @@ async function recall(query, ctx, options = {}) {
       embeddingsUnavailable: factEmbeddingsUnavailable,
       rankedOnCosine: factRankedOnCosine,
       decryptLast: factDecryptLast,
-      rowsDecrypted: factRowsDecrypted
+      rowsDecrypted: factRowsDecrypted,
+      corpusStats: factCorpusStats
     } = await (ctx.factSource?.search.bind(ctx.factSource) ?? ((searchQuery, searchOptions) => searchVaultMemoriesWithSize(
       searchQuery,
       ctx.vaultCtx,
@@ -19558,6 +19605,7 @@ async function recall(query, ctx, options = {}) {
     factLaneRankedOnCosine = factRankedOnCosine;
     decryptLastRan = factDecryptLast;
     vaultRowsDecrypted = factRowsDecrypted;
+    corpusStats = factCorpusStats;
     factLaneMs = nowMs() - factStart;
   }
   if (chunkEmbedFailed && !factLaneRankedOnCosine) embeddingsUnavailable = true;
@@ -20914,6 +20962,7 @@ var queryFields = [
   "updated_after",
   "topics_due",
   "topics_extracted",
+  "event_time_overlaps",
   "order",
   "cursor",
   "limit",
@@ -22163,6 +22212,7 @@ var MAX_QUERY_IDS = 1e3;
 var MAX_QUERY_TOPICS = 100;
 var MAX_QUERY_FILTER = 20;
 var GRAPH_LANE_ROWS = 256;
+var TEMPORAL_LANE_ROWS = 256;
 var RemoteMemoryPartialCreateError = class extends Error {
   constructor(created, cause) {
     super(`createMany stored ${created.length} memories before a batch failed`);
@@ -22261,7 +22311,7 @@ function createRemoteMemoryStore(options) {
   const pipeline = createRemoteMemoryPipeline({
     ...options,
     graphRanking: options.graphRanking ?? ((query, _traverse, recallOptions) => topicGraphRanking(query, recallOptions)),
-    temporalRanking: options.temporalRanking ?? (() => Promise.resolve([]))
+    temporalRanking: options.temporalRanking ?? ((query, now) => eventTimeRanking(query, now))
   });
   const subscribers = /* @__PURE__ */ new Set();
   const seen = /* @__PURE__ */ new Map();
@@ -22324,6 +22374,24 @@ function createRemoteMemoryStore(options) {
       matched: [...canonicalTopics(memory)].filter((name) => wanted.has(name)).length
     })).filter((row) => row.matched > 0).sort((a, b) => b.matched - a.matched).slice(0, NODE_BUDGET).map((row) => row.memoryId);
   };
+  const eventTimeRanking = async (query, now) => {
+    const window2 = parseQueryTimeWindow(query, now);
+    if (!window2) return [];
+    const rows = await pages(
+      metadata2,
+      { event_time_overlaps: { start: window2.start, end: window2.end } },
+      TEMPORAL_LANE_ROWS
+    );
+    return rows.map(({ memory }) => ({
+      memoryId: memory.memory_id,
+      score: scoreEventTimeOverlap(
+        memory.event_time_start ?? null,
+        memory.event_time_end ?? null,
+        memory.event_time_kind ?? null,
+        window2
+      )
+    })).filter((row) => row.score > 0).sort((a, b) => b.score - a.score).map((row) => row.memoryId);
+  };
   const enumerateIds = async (read, ids, filters) => (await Promise.all(
     chunks2([...new Set(ids)], MAX_QUERY_IDS).map(
       (memory_ids) => pages(read, { ...filters, memory_ids })

package/dist/expo/index.d.mts

@@ -4011,6 +4011,13 @@ declare function eagerEmbedContent(content: string, embeddingOptions: EmbeddingO
  * trusting it (see `vectorVersion.ts`).
  */
 updatedAt?: Date): Promise<void>;
+interface CorpusStats {
+    keysMs: number;
+    embeddingsFetchMs: number;
+    rowsFetchMs: number;
+    cacheHits: number;
+    cacheMisses: number;
+}
 /**
  * A single vault search result with its similarity score.
  */
@@ -4089,6 +4096,7 @@ declare function searchVaultMemoriesWithSize(query: string, vaultCtx: VaultMemor
      */
     queryEmbedMs: number;
     rowsEmbedded: number;
+    corpusStats?: CorpusStats;
 }>;
 /**
  * Search vault memories by semantic similarity. Returns structured results
@@ -4653,6 +4661,8 @@ interface RecallDiagnostics {
      * LEGACY read path this batch is uncapped, so it can be the whole vault.
      */
     vaultRowsEmbedded?: number;
+    vaultCacheHits?: number;
+    vaultCacheMisses?: number;
     /** Embedded messages the chunk lane considered; absent when the lane did not run. */
     chunkRowsScanned?: number;
     /** Messages whose vectors the chunk lane read from storage on a cache miss. */
@@ -4755,6 +4765,9 @@ interface RecallDiagnostics {
         chunkLane: number;
         /** Cross-lane RRF fusion + provenance dedup after both lanes. */
         fuse: number;
+        corpusKeys?: number;
+        corpusEmbeddingsFetch?: number;
+        corpusRowsFetch?: number;
     };
     /** Soft-degradation signals that fired this call (empty when clean). */
     degraded: RecallDegradation[];
@@ -9641,6 +9654,10 @@ interface RemoteMemoryQueryOptions extends RemoteMemoryReadFilters {
     updated_after?: number;
     topics_due?: number;
     topics_extracted?: boolean;
+    event_time_overlaps?: {
+        start: number;
+        end: number;
+    };
     order?: "created" | "updated" | "archived" | "changed";
     cursor?: string;
     limit?: number;
@@ -9819,7 +9836,6 @@ interface RemoteMemoryStoreOptions {
     embeddingOptions: EmbeddingOptions;
     /** Defaults to ranking memories by how many query entities their topics name. */
     graphRanking?: RecallFactSource["graphRanking"];
-    /** Defaults to no temporal lane: nearby has no event-time filter yet. */
     temporalRanking?: RecallFactSource["temporalRanking"];
     pollIntervalMs?: number;
 }

package/dist/expo/index.d.ts

@@ -4011,6 +4011,13 @@ declare function eagerEmbedContent(content: string, embeddingOptions: EmbeddingO
  * trusting it (see `vectorVersion.ts`).
  */
 updatedAt?: Date): Promise<void>;
+interface CorpusStats {
+    keysMs: number;
+    embeddingsFetchMs: number;
+    rowsFetchMs: number;
+    cacheHits: number;
+    cacheMisses: number;
+}
 /**
  * A single vault search result with its similarity score.
  */
@@ -4089,6 +4096,7 @@ declare function searchVaultMemoriesWithSize(query: string, vaultCtx: VaultMemor
      */
     queryEmbedMs: number;
     rowsEmbedded: number;
+    corpusStats?: CorpusStats;
 }>;
 /**
  * Search vault memories by semantic similarity. Returns structured results
@@ -4653,6 +4661,8 @@ interface RecallDiagnostics {
      * LEGACY read path this batch is uncapped, so it can be the whole vault.
      */
     vaultRowsEmbedded?: number;
+    vaultCacheHits?: number;
+    vaultCacheMisses?: number;
     /** Embedded messages the chunk lane considered; absent when the lane did not run. */
     chunkRowsScanned?: number;
     /** Messages whose vectors the chunk lane read from storage on a cache miss. */
@@ -4755,6 +4765,9 @@ interface RecallDiagnostics {
         chunkLane: number;
         /** Cross-lane RRF fusion + provenance dedup after both lanes. */
         fuse: number;
+        corpusKeys?: number;
+        corpusEmbeddingsFetch?: number;
+        corpusRowsFetch?: number;
     };
     /** Soft-degradation signals that fired this call (empty when clean). */
     degraded: RecallDegradation[];
@@ -9641,6 +9654,10 @@ interface RemoteMemoryQueryOptions extends RemoteMemoryReadFilters {
     updated_after?: number;
     topics_due?: number;
     topics_extracted?: boolean;
+    event_time_overlaps?: {
+        start: number;
+        end: number;
+    };
     order?: "created" | "updated" | "archived" | "changed";
     cursor?: string;
     limit?: number;
@@ -9819,7 +9836,6 @@ interface RemoteMemoryStoreOptions {
     embeddingOptions: EmbeddingOptions;
     /** Defaults to ranking memories by how many query entities their topics name. */
     graphRanking?: RecallFactSource["graphRanking"];
-    /** Defaults to no temporal lane: nearby has no event-time filter yet. */
     temporalRanking?: RecallFactSource["temporalRanking"];
     pollIntervalMs?: number;
 }

package/dist/expo/index.mjs

@@ -15098,10 +15098,18 @@ function admitVaultProjections(queryEmbedding, vectored, k) {
 }
 async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, queryOpts, opts) {
   let rowsDecrypted = 0;
+  const keysStart = nowMs();
   const keys = await getVaultCandidateKeysOp(
     vaultCtx,
     Object.keys(queryOpts).length > 0 ? queryOpts : void 0
   );
+  const corpusStats = {
+    keysMs: nowMs() - keysStart,
+    embeddingsFetchMs: 0,
+    rowsFetchMs: 0,
+    cacheHits: 0,
+    cacheMisses: 0
+  };
   const hydrateOpts = queryOpts.includeArchived ? { includeArchived: true } : void 0;
   const vaultSize = keys.length;
   if (keys.length === 0) {
@@ -15111,7 +15119,8 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
       queryEmbedding: [],
       vaultSize: 0,
       laneEmbedFailed: false,
-      rowsDecrypted: 0
+      rowsDecrypted: 0,
+      corpusStats
     };
   }
   const queryEmbedStart = nowMs();
@@ -15133,16 +15142,20 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
     for (const k2 of keys) {
       const cached = cachedRowVector(cache, k2.uniqueId, k2.updatedAt);
       if (cached && cached.length === queryEmbedding.length) {
+        corpusStats.cacheHits++;
         vectored.push({ uniqueId: k2.uniqueId, embedding: cached, updatedAt: k2.updatedAt });
         continue;
       }
+      corpusStats.cacheMisses++;
       const modelCompatible = (k2.embeddingModel ?? currentModel) === currentModel;
       if (modelCompatible) missIds.push(k2.uniqueId);
       else noVectorIds.push(k2.uniqueId);
     }
   }
   if (missIds.length > 0) {
+    const embeddingsStart = nowMs();
     const rows = await getVaultEmbeddingsByIdsOp(vaultCtx, missIds, hydrateOpts);
+    corpusStats.embeddingsFetchMs += nowMs() - embeddingsStart;
     const gotVector = /* @__PURE__ */ new Set();
     for (const r of rows) {
       if (!r.embedding) continue;
@@ -15170,7 +15183,9 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
         `memoryVault: projected search un-embedded lane capped at ${laneIds.length}/${noVectorIds.length}`
       );
     }
+    const laneStart = nowMs();
     const laneFetched = await getVaultMemoriesByIdsOp(vaultCtx, laneIds, hydrateOpts);
+    corpusStats.rowsFetchMs += nowMs() - laneStart;
     rowsDecrypted += laneFetched.length;
     for (const row of laneFetched) laneById.set(row.uniqueId, row);
     const laneRows = laneFetched.filter((m) => !isEncrypted(m.content));
@@ -15222,7 +15237,9 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
     }
   }
   const idsToFetch = [...admissionSet].filter((id) => !laneById.has(id));
+  const admittedStart = nowMs();
   const fetched = idsToFetch.length > 0 ? await getVaultMemoriesByIdsOp(vaultCtx, idsToFetch, hydrateOpts) : [];
+  corpusStats.rowsFetchMs += nowMs() - admittedStart;
   rowsDecrypted += fetched.length;
   const admittedRows = [
     ...fetched,
@@ -15251,7 +15268,10 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
   }
   if (staleIds.length > 0) {
     const contentById = new Map(memories.map((m) => [m.uniqueId, m]));
-    for (const r of await getVaultEmbeddingsByIdsOp(vaultCtx, staleIds, hydrateOpts)) {
+    const staleStart = nowMs();
+    const staleRows = await getVaultEmbeddingsByIdsOp(vaultCtx, staleIds, hydrateOpts);
+    corpusStats.embeddingsFetchMs += nowMs() - staleStart;
+    for (const r of staleRows) {
       if (!r.embedding) continue;
       try {
         const parsed = JSON.parse(r.embedding);
@@ -15283,7 +15303,15 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
     eventTimeKind: normalizeEventTimeKind(m.eventTimeKind),
     factType: m.factType
   }));
-  return { memories, embeddedItems, queryEmbedding, vaultSize, laneEmbedFailed, rowsDecrypted };
+  return {
+    memories,
+    embeddedItems,
+    queryEmbedding,
+    vaultSize,
+    laneEmbedFailed,
+    rowsDecrypted,
+    corpusStats
+  };
 }
 async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache, searchOptions) {
   if (!query || typeof query !== "string") {
@@ -15324,6 +15352,7 @@ async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache,
     embeddingFailure = true;
   };
   const embedStats = { queryMs: 0, rowsEmbedded: 0 };
+  let corpusStats;
   if (searchOptions?.decryptLast) {
     const forceIncludeIds = [
       ...searchOptions.entityRanking ?? [],
@@ -15344,6 +15373,7 @@ async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache,
       onEmbeddingDegraded,
       embedStats
     });
+    corpusStats = corpus.corpusStats;
     if (corpus.vaultSize === 0) {
       return {
         memories: [],
@@ -15355,7 +15385,8 @@ async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache,
         decryptLast: true,
         rowsDecrypted: corpus.rowsDecrypted,
         queryEmbedMs: embedStats.queryMs,
-        rowsEmbedded: embedStats.rowsEmbedded
+        rowsEmbedded: embedStats.rowsEmbedded,
+        corpusStats
       };
     }
     ({ memories, embeddedItems, queryEmbedding, vaultSize } = corpus);
@@ -15372,7 +15403,8 @@ async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache,
         decryptLast: true,
         rowsDecrypted: corpus.rowsDecrypted,
         queryEmbedMs: embedStats.queryMs,
-        rowsEmbedded: embedStats.rowsEmbedded
+        rowsEmbedded: embedStats.rowsEmbedded,
+        corpusStats
       };
     }
   } else {
@@ -15505,7 +15537,8 @@ async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache,
     embeddingsUnavailable,
     embeddingFailure,
     decryptLast: !!searchOptions?.decryptLast,
-    rowsDecrypted
+    rowsDecrypted,
+    ...corpusStats && { corpusStats }
   };
 }
 async function rankPreparedVaultCandidates(query, prepared, embeddingOptions, searchOptions) {
@@ -15722,7 +15755,8 @@ async function searchVaultMemoriesWithSize(query, vaultCtx, embeddingOptions, ca
       decryptLast: prepared.decryptLast,
       rowsDecrypted: prepared.rowsDecrypted,
       queryEmbedMs: prepared.queryEmbedMs,
-      rowsEmbedded: prepared.rowsEmbedded
+      rowsEmbedded: prepared.rowsEmbedded,
+      ...prepared.corpusStats && { corpusStats: prepared.corpusStats }
     };
   }
   if (prepared.memories.length === 0) {
@@ -15737,7 +15771,8 @@ async function searchVaultMemoriesWithSize(query, vaultCtx, embeddingOptions, ca
       decryptLast: prepared.decryptLast,
       rowsDecrypted: prepared.rowsDecrypted,
       queryEmbedMs: prepared.queryEmbedMs,
-      rowsEmbedded: prepared.rowsEmbedded
+      rowsEmbedded: prepared.rowsEmbedded,
+      ...prepared.corpusStats && { corpusStats: prepared.corpusStats }
     };
   }
   const ranked = await rankPreparedVaultCandidates(
@@ -15752,7 +15787,8 @@ async function searchVaultMemoriesWithSize(query, vaultCtx, embeddingOptions, ca
     decryptLast: prepared.decryptLast,
     rowsDecrypted: prepared.rowsDecrypted,
     queryEmbedMs: prepared.queryEmbedMs,
-    rowsEmbedded: prepared.rowsEmbedded
+    rowsEmbedded: prepared.rowsEmbedded,
+    ...prepared.corpusStats && { corpusStats: prepared.corpusStats }
   };
 }
 async function searchVaultMemories(query, vaultCtx, embeddingOptions, cache, searchOptions) {
@@ -17727,6 +17763,7 @@ async function recall(query, ctx, options = {}) {
   let factLaneRankedOnCosine = false;
   let decryptLastRan;
   let vaultRowsDecrypted;
+  let corpusStats;
   let graphLaneCount = 0;
   let temporalLaneCount = 0;
   let graphLaneFailed = false;
@@ -17767,6 +17804,10 @@ async function recall(query, ctx, options = {}) {
       ...decryptLastRan !== void 0 && { decryptLast: decryptLastRan },
       ...vaultRowsDecrypted !== void 0 && { vaultRowsDecrypted },
       ...vaultRowsEmbedded !== void 0 && { vaultRowsEmbedded },
+      ...corpusStats && {
+        vaultCacheHits: corpusStats.cacheHits,
+        vaultCacheMisses: corpusStats.cacheMisses
+      },
       ...chunkStats && {
         chunkRowsScanned: chunkStats.rowsScanned,
         chunkRowsFetched: chunkStats.rowsFetched,
@@ -17789,7 +17830,12 @@ async function recall(query, ctx, options = {}) {
         rerank: rerankMs,
         queryEmbed: queryEmbedMs,
         chunkLane: chunkLaneMs,
-        fuse: fuseMs
+        fuse: fuseMs,
+        ...corpusStats && {
+          corpusKeys: corpusStats.keysMs,
+          corpusEmbeddingsFetch: corpusStats.embeddingsFetchMs,
+          corpusRowsFetch: corpusStats.rowsFetchMs
+        }
       },
       degraded
     };
@@ -17863,7 +17909,8 @@ async function recall(query, ctx, options = {}) {
       embeddingsUnavailable: factEmbeddingsUnavailable,
       rankedOnCosine: factRankedOnCosine,
       decryptLast: factDecryptLast,
-      rowsDecrypted: factRowsDecrypted
+      rowsDecrypted: factRowsDecrypted,
+      corpusStats: factCorpusStats
     } = await (ctx.factSource?.search.bind(ctx.factSource) ?? ((searchQuery, searchOptions) => searchVaultMemoriesWithSize(
       searchQuery,
       ctx.vaultCtx,
@@ -17929,6 +17976,7 @@ async function recall(query, ctx, options = {}) {
     factLaneRankedOnCosine = factRankedOnCosine;
     decryptLastRan = factDecryptLast;
     vaultRowsDecrypted = factRowsDecrypted;
+    corpusStats = factCorpusStats;
     factLaneMs = nowMs() - factStart;
   }
   if (chunkEmbedFailed && !factLaneRankedOnCosine) embeddingsUnavailable = true;
@@ -19273,6 +19321,7 @@ var queryFields = [
   "updated_after",
   "topics_due",
   "topics_extracted",
+  "event_time_overlaps",
   "order",
   "cursor",
   "limit",
@@ -20520,6 +20569,7 @@ var MAX_QUERY_IDS = 1e3;
 var MAX_QUERY_TOPICS = 100;
 var MAX_QUERY_FILTER = 20;
 var GRAPH_LANE_ROWS = 256;
+var TEMPORAL_LANE_ROWS = 256;
 var RemoteMemoryPartialCreateError = class extends Error {
   constructor(created, cause) {
     super(`createMany stored ${created.length} memories before a batch failed`);
@@ -20618,7 +20668,7 @@ function createRemoteMemoryStore(options) {
   const pipeline = createRemoteMemoryPipeline({
     ...options,
     graphRanking: options.graphRanking ?? ((query, _traverse, recallOptions) => topicGraphRanking(query, recallOptions)),
-    temporalRanking: options.temporalRanking ?? (() => Promise.resolve([]))
+    temporalRanking: options.temporalRanking ?? ((query, now) => eventTimeRanking(query, now))
   });
   const subscribers = /* @__PURE__ */ new Set();
   const seen = /* @__PURE__ */ new Map();
@@ -20681,6 +20731,24 @@ function createRemoteMemoryStore(options) {
       matched: [...canonicalTopics(memory)].filter((name) => wanted.has(name)).length
     })).filter((row) => row.matched > 0).sort((a, b) => b.matched - a.matched).slice(0, NODE_BUDGET).map((row) => row.memoryId);
   };
+  const eventTimeRanking = async (query, now) => {
+    const window2 = parseQueryTimeWindow(query, now);
+    if (!window2) return [];
+    const rows = await pages(
+      metadata2,
+      { event_time_overlaps: { start: window2.start, end: window2.end } },
+      TEMPORAL_LANE_ROWS
+    );
+    return rows.map(({ memory }) => ({
+      memoryId: memory.memory_id,
+      score: scoreEventTimeOverlap(
+        memory.event_time_start ?? null,
+        memory.event_time_end ?? null,
+        memory.event_time_kind ?? null,
+        window2
+      )
+    })).filter((row) => row.score > 0).sort((a, b) => b.score - a.score).map((row) => row.memoryId);
+  };
   const enumerateIds = async (read, ids, filters) => (await Promise.all(
     chunks2([...new Set(ids)], MAX_QUERY_IDS).map(
       (memory_ids) => pages(read, { ...filters, memory_ids })

package/dist/memory/context.d.mts

@@ -557,6 +557,8 @@ interface RecallDiagnostics {
      * LEGACY read path this batch is uncapped, so it can be the whole vault.
      */
     vaultRowsEmbedded?: number;
+    vaultCacheHits?: number;
+    vaultCacheMisses?: number;
     /** Embedded messages the chunk lane considered; absent when the lane did not run. */
     chunkRowsScanned?: number;
     /** Messages whose vectors the chunk lane read from storage on a cache miss. */
@@ -659,6 +661,9 @@ interface RecallDiagnostics {
         chunkLane: number;
         /** Cross-lane RRF fusion + provenance dedup after both lanes. */
         fuse: number;
+        corpusKeys?: number;
+        corpusEmbeddingsFetch?: number;
+        corpusRowsFetch?: number;
     };
     /** Soft-degradation signals that fired this call (empty when clean). */
     degraded: RecallDegradation[];