sdk: memory.admin.prefetchRelated()

proto/coverage.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "Tracks how each engine RPC (proto/memory.proto) is surfaced in the SDK. check-proto-drift.mjs fails CI if the proto gains an RPC that is in neither list, so the SDK can't silently fall behind the engine. Vendored from thinkfleet-memory-engine main @ 7f1c2be69ae1.",
+  "_comment": "Tracks how each engine RPC (proto/memory.proto) is surfaced in the SDK. check-proto-drift.mjs fails CI if the proto gains an RPC that is in neither list, so the SDK can't silently fall behind the engine. Vendored from thinkfleet-memory-engine main @ bc5c9ec.",
   "covered": {
     "Save": "memory.admin.create / memory.observe",
     "Observe": "memory.observe",
@@ -10,6 +10,7 @@
     "Estimate": "lattice.estimate",
     "Consolidate": "memory.admin.dedup",
     "Reflect": "memory.admin.reflect",
+    "PrefetchRelated": "memory.admin.prefetchRelated",
     "Backfill": "memory.admin.backfillEmbeddings",
     "GetCalibration": "lattice.getCalibration",
     "GetProfile": "lattice.getProfile",

proto/memory.proto

@@ -106,6 +106,14 @@ service Memory {
     // run on a schedule by the SaaS (like Consolidate).
     rpc Reflect(ReflectRequest) returns (ReflectResult);
 
+    // Predictive (anticipatory) retrieval — spreading activation over the
+    // knowledge graph. Given the memories a session is currently working with
+    // (`seed_memory_ids`), return other memories linked to the SAME graph
+    // entities, ranked by how many distinct shared entities connect them (the
+    // more graph paths, the stronger the association). Surfaces the context
+    // most likely needed next before it's asked for. Deterministic; read-only.
+    rpc PrefetchRelated(PrefetchRelatedRequest) returns (SearchResponse);
+
     // Generate embeddings for items that don't have one yet (the backfill
     // work-list). generate-on-save only covers new writes; this catches up the
     // existing corpus. No-op if the engine's embedding provider is disabled.
@@ -823,6 +831,17 @@ message ReflectResult {
     bool dry_run = 3;
 }
 
+message PrefetchRelatedRequest {
+    // Tenancy; normally injected from gRPC metadata.
+    optional string platform_id = 10;
+    optional string project_id = 11;
+    // The memories the session is currently working with — the activation
+    // seed. Their graph entities drive the prefetch.
+    repeated string seed_memory_ids = 1;
+    // Max related memories to return. Default 10, clamped [1, 100].
+    optional uint32 limit = 2;
+}
+
 message BackfillRequest {
     // Max items to embed this call. Default 500, clamped [1, 10000]. Call
     // repeatedly until embedded == 0 to drain a large corpus.

src/index.ts

@@ -172,6 +172,7 @@ export type {
   ReflectRequest,
   ReflectResult,
   Insight,
+  PrefetchRelatedRequest,
 } from './types/memory.js'
 
 export {

src/resources/memory.ts

@@ -20,6 +20,7 @@ import {
   type DedupResult,
   type ReflectRequest,
   type ReflectResult,
+  type PrefetchRelatedRequest,
   type ObserveAttachmentRequest,
   type ObserveDocumentRequest,
   type ObserveRequest,
@@ -548,6 +549,21 @@ export class AdminMemoryResource {
     return this.http.post<ReflectResult>('/admin/memory/reflect', body, options)
   }
 
+  /**
+   * Predictive (anticipatory) retrieval — spreading activation over the
+   * knowledge graph. Given the memories a session is currently working with
+   * (`seedMemoryIds`), returns other memories linked to the SAME graph
+   * entities, ranked by how many distinct shared entities connect them — the
+   * context most likely needed next, surfaced before it's asked for.
+   * Deterministic and read-only.
+   */
+  async prefetchRelated(
+    body: PrefetchRelatedRequest,
+    options?: RequestOptions,
+  ): Promise<MemoryItem[]> {
+    return this.http.post<MemoryItem[]>('/admin/memory/prefetch-related', body, options)
+  }
+
   /**
    * List the feedback records attached to a memory item — useful when
    * inspecting auto-flagged items to decide whether to confirm or reject.

src/types/memory.ts

@@ -283,3 +283,10 @@ export interface ReflectResult {
   sourcesConsidered: number
   dryRun: boolean
 }
+
+export interface PrefetchRelatedRequest {
+  /** The memories the session is currently working with — the activation seed. */
+  seedMemoryIds: string[]
+  /** Max related memories to return. Default 10, clamped [1, 100]. */
+  limit?: number
+}