From 8a1b220fe9d5da1bd9a438f4dc34d60745d03e0b Mon Sep 17 00:00:00 2001 From: rrader2890 Date: Tue, 7 Jul 2026 20:42:09 -0400 Subject: [PATCH] feat(sdk): memory.admin.prefetchRelated() for the PrefetchRelated RPC MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Spreading-activation prefetch over the KG — pass the memories a session is using (seedMemoryIds), get back the related memories most likely needed next (ranked by shared graph entities). POSTs /admin/memory/prefetch-related, returns MemoryItem[]. check:proto green (45 RPCs, 40 covered). Note: TS shell needs the POST /admin/memory/prefetch-related route wired to the gRPC PrefetchRelated call for REST; the engine RPC is live. Co-Authored-By: Claude Opus 4.8 (1M context) --- proto/coverage.json | 3 ++- proto/memory.proto | 19 +++++++++++++++++++ src/index.ts | 1 + src/resources/memory.ts | 16 ++++++++++++++++ src/types/memory.ts | 7 +++++++ 5 files changed, 45 insertions(+), 1 deletion(-) diff --git a/proto/coverage.json b/proto/coverage.json index 0d26d5b..679082b 100644 --- a/proto/coverage.json +++ b/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", diff --git a/proto/memory.proto b/proto/memory.proto index 3e63b83..dc16b25 100644 --- a/proto/memory.proto +++ b/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. diff --git a/src/index.ts b/src/index.ts index 80bd768..6655bca 100644 --- a/src/index.ts +++ b/src/index.ts @@ -172,6 +172,7 @@ export type { ReflectRequest, ReflectResult, Insight, + PrefetchRelatedRequest, } from './types/memory.js' export { diff --git a/src/resources/memory.ts b/src/resources/memory.ts index 930c2b6..5ea63c1 100644 --- a/src/resources/memory.ts +++ b/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('/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 { + return this.http.post('/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. diff --git a/src/types/memory.ts b/src/types/memory.ts index 9631379..7cf75b1 100644 --- a/src/types/memory.ts +++ b/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 +}