From e10511ce382a83dfd5900d6f4d97b8278981a686 Mon Sep 17 00:00:00 2001 From: Mikael Hugo Date: Sun, 3 May 2026 00:18:46 +0200 Subject: [PATCH] docs(sf): memory-embeddings.ts header reflects actual pipeline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous header had two stale references: - "buildMemoryLLMCall pattern, prefers a dedicated embedding-capable model" — describes a hook that actually returns null on every call (the Pi SDK has no provider-neutral embedding API yet). - "queryMemoriesRanked falls back to keyword-only scoring" — function doesn't exist; the real consumer is getRelevantMemoriesRanked, and the fallback is static (confidence × hit_count), not keyword. Updated to describe the actual three-stage read pipeline (cosine → relation-boost → optional rerank) and the soft-degrade fallback to static ranking when the gateway is offline. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../extensions/sf/memory-embeddings.ts | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/src/resources/extensions/sf/memory-embeddings.ts b/src/resources/extensions/sf/memory-embeddings.ts index f180a7aeb..99c7da86c 100644 --- a/src/resources/extensions/sf/memory-embeddings.ts +++ b/src/resources/extensions/sf/memory-embeddings.ts @@ -1,11 +1,20 @@ // SF Memory Embeddings — provider-agnostic embedding layer // -// Same model-discovery pattern as buildMemoryLLMCall: prefers a dedicated -// embedding-capable model when available, and returns null when none is -// found (which is the common case — not every provider exposes embeddings). +// Active providers: +// - llm-gateway adapter (memory-embeddings-llm-gateway.ts) — opt-in via +// SF_LLM_GATEWAY_KEY; the only working write path today. +// - buildEmbeddingFn (Pi-SDK provider scan) — discovery hook only; +// returns null because the SDK has no provider-neutral embedding +// API yet. Kept as the future plug-in surface. // -// When embeddings are unavailable, all calls become no-ops and -// queryMemoriesRanked falls back to keyword-only scoring. +// Read pipeline used by `getRelevantMemoriesRanked` (memory-store.ts): +// 1. cosine ranking via rankMemoriesByEmbedding (uses loadEmbeddingMap) +// 2. relation-boost via applyRelationBoost (uses memory_relations edges) +// 3. optional rerank via memory-embeddings-llm-gateway/rerankCandidates +// +// When no gateway is configured (or the worker is offline), all three +// pipeline stages soft-degrade and `getRelevantMemoriesRanked` falls back +// to static (confidence × hit_count) ranking. import type { ExtensionContext } from "@singularity-forge/pi-coding-agent";