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";