gsd-pi 2.75.0 → 2.76.0-dev.b072ebb73

package/src/resources/extensions/gsd/memory-embeddings.ts

@@ -0,0 +1,235 @@
+// GSD 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).
+//
+// When embeddings are unavailable, all calls become no-ops and
+// queryMemoriesRanked falls back to keyword-only scoring.
+
+import type { ExtensionContext } from "@gsd/pi-coding-agent";
+
+import { _getAdapter, isDbAvailable, upsertMemoryEmbedding, deleteMemoryEmbedding } from "./gsd-db.js";
+import { logWarning } from "./workflow-logger.js";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type EmbedFn = (texts: string[]) => Promise<Float32Array[]>;
+
+export interface EmbeddingModelInfo {
+  id: string;
+}
+
+export interface MemoryEmbeddingRow {
+  memoryId: string;
+  model: string;
+  dim: number;
+  vector: Float32Array;
+}
+
+// ─── Model selection ────────────────────────────────────────────────────────
+
+const EMBEDDING_ID_HINTS = [
+  "embed",
+  "embedding",
+  "voyage",
+  "text-embedding",
+  "nomic",
+  "jina-embed",
+  "bge",
+  "mxbai-embed",
+];
+
+/**
+ * Try to build an embedding function from the model registry. Returns null
+ * when no embedding-capable model is obvious from the registry metadata.
+ *
+ * NOTE: the Pi SDK doesn't yet expose a dedicated embeddings API for every
+ * provider. This implementation currently targets Anthropic / OpenAI-shaped
+ * SDKs: when the caller has direct API access via `ctx.modelRegistry`, they
+ * can wire this up by providing an `embedFn` override. We ship the hint-based
+ * detection here so future providers can plug in without touching callers.
+ */
+export function buildEmbeddingFn(ctx: ExtensionContext): EmbedFn | null {
+  try {
+    const available = ctx.modelRegistry?.getAvailable?.();
+    if (!available || available.length === 0) return null;
+    const candidate = available.find((model) => {
+      const id = typeof model?.id === "string" ? model.id.toLowerCase() : "";
+      return EMBEDDING_ID_HINTS.some((hint) => id.includes(hint));
+    });
+    if (!candidate) return null;
+    // We don't currently have a provider-neutral embedding call in Pi; the
+    // detection surface is in place so wiring can happen once Pi offers it.
+    return null;
+  } catch (err) {
+    logWarning("memory-embeddings", `model discovery failed: ${(err as Error).message}`);
+    return null;
+  }
+}
+
+// ─── Vector (de)serialization ───────────────────────────────────────────────
+
+export function packFloat32(vec: Float32Array): Uint8Array {
+  return new Uint8Array(vec.buffer, vec.byteOffset, vec.byteLength);
+}
+
+export function unpackFloat32(blob: unknown): Float32Array | null {
+  if (!blob) return null;
+  try {
+    if (blob instanceof Float32Array) return blob;
+    let view: Uint8Array;
+    if (blob instanceof Uint8Array) {
+      view = blob;
+    } else if (blob instanceof ArrayBuffer) {
+      view = new Uint8Array(blob);
+    } else if ((blob as Buffer).buffer && (blob as Buffer).byteLength != null) {
+      const buf = blob as Buffer;
+      view = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+    } else if (Array.isArray(blob)) {
+      return new Float32Array(blob as number[]);
+    } else {
+      return null;
+    }
+    if (view.byteLength % 4 !== 0) return null;
+    // Copy into an aligned buffer — BLOBs may arrive at odd byte offsets.
+    const aligned = new ArrayBuffer(view.byteLength);
+    new Uint8Array(aligned).set(view);
+    return new Float32Array(aligned);
+  } catch {
+    return null;
+  }
+}
+
+// ─── Math ───────────────────────────────────────────────────────────────────
+
+export function cosineSimilarity(a: Float32Array, b: Float32Array): number {
+  if (a.length === 0 || a.length !== b.length) return 0;
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i];
+    const y = b[i];
+    dot += x * y;
+    normA += x * x;
+    normB += y * y;
+  }
+  if (normA === 0 || normB === 0) return 0;
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+// ─── Read helpers ───────────────────────────────────────────────────────────
+
+export function getEmbeddingForMemory(memoryId: string): MemoryEmbeddingRow | null {
+  if (!isDbAvailable()) return null;
+  const adapter = _getAdapter();
+  if (!adapter) return null;
+  try {
+    const row = adapter
+      .prepare(
+        "SELECT memory_id, model, dim, vector FROM memory_embeddings WHERE memory_id = :id",
+      )
+      .get({ ":id": memoryId });
+    if (!row) return null;
+    const vector = unpackFloat32(row["vector"]);
+    if (!vector) return null;
+    return {
+      memoryId: row["memory_id"] as string,
+      model: row["model"] as string,
+      dim: row["dim"] as number,
+      vector,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function loadAllEmbeddings(): MemoryEmbeddingRow[] {
+  if (!isDbAvailable()) return [];
+  const adapter = _getAdapter();
+  if (!adapter) return [];
+  try {
+    const rows = adapter
+      .prepare(
+        `SELECT e.memory_id, e.model, e.dim, e.vector
+         FROM memory_embeddings e
+         JOIN memories m ON m.id = e.memory_id
+         WHERE m.superseded_by IS NULL`,
+      )
+      .all();
+    const out: MemoryEmbeddingRow[] = [];
+    for (const row of rows) {
+      const vector = unpackFloat32(row["vector"]);
+      if (!vector) continue;
+      out.push({
+        memoryId: row["memory_id"] as string,
+        model: row["model"] as string,
+        dim: row["dim"] as number,
+        vector,
+      });
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+// ─── Write helpers ──────────────────────────────────────────────────────────
+
+export function saveEmbedding(
+  memoryId: string,
+  vector: Float32Array,
+  model: string,
+): boolean {
+  if (!isDbAvailable()) return false;
+  try {
+    upsertMemoryEmbedding({
+      memoryId,
+      model,
+      dim: vector.length,
+      vector: packFloat32(vector),
+      updatedAt: new Date().toISOString(),
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function removeEmbedding(memoryId: string): boolean {
+  if (!isDbAvailable()) return false;
+  try {
+    return deleteMemoryEmbedding(memoryId);
+  } catch {
+    return false;
+  }
+}
+
+// ─── Orchestration ──────────────────────────────────────────────────────────
+
+/**
+ * Embed each memory's content via `embedFn` (if provided) and persist the
+ * resulting vectors. Returns the number of successfully embedded memories.
+ * Safe to call with embedFn=null — it becomes a no-op.
+ */
+export async function embedMemories(
+  memories: Array<{ id: string; content: string }>,
+  embedFn: EmbedFn | null,
+  model: string,
+): Promise<number> {
+  if (!embedFn || memories.length === 0) return 0;
+  try {
+    const vectors = await embedFn(memories.map((m) => m.content));
+    let count = 0;
+    for (let i = 0; i < memories.length && i < vectors.length; i++) {
+      const vector = vectors[i];
+      if (!vector || vector.length === 0) continue;
+      if (saveEmbedding(memories[i].id, vector, model)) count++;
+    }
+    return count;
+  } catch (err) {
+    logWarning("memory-embeddings", `embed failed: ${(err as Error).message}`);
+    return 0;
+  }
+}

package/src/resources/extensions/gsd/memory-extractor.ts

@@ -128,6 +128,14 @@ Actions (return JSON array):
 - UPDATE: {"action": "UPDATE", "id": "<MEM###>", "content": "<revised text>"}
 - REINFORCE: {"action": "REINFORCE", "id": "<MEM###>"}
 - SUPERSEDE: {"action": "SUPERSEDE", "id": "<MEM###>", "superseded_by": "<MEM###>"}
+- LINK: {"action": "LINK", "from": "<MEM###>", "to": "<MEM###>", "rel": "<rel>", "confidence": <0.6-0.95>}
+
+Link relation types:
+- related_to   — two memories cover the same area
+- depends_on   — "to" is a prerequisite for "from"
+- contradicts  — "from" conflicts with "to"
+- elaborates   — "from" expands on "to"
+- supersedes   — "from" replaces "to" (rarely needed; prefer SUPERSEDE)
 
 Rules:
 - Don't create memories for one-off bug fixes or temporary state
@@ -135,6 +143,7 @@ Rules:
 - Keep content to 1-3 sentences
 - Confidence: 0.6 tentative, 0.8 solid, 0.95 well-confirmed
 - Prefer fewer high-quality memories over many low-quality ones
+- Only LINK memories that genuinely relate — don't fabricate edges
 - Return empty array [] if nothing worth remembering
 - NEVER include secrets, API keys, or passwords
 
@@ -262,6 +271,21 @@ export function parseMemoryResponse(raw: string): MemoryAction[] {
             });
           }
           break;
+        case 'LINK':
+          if (
+            typeof item.from === 'string' &&
+            typeof item.to === 'string' &&
+            typeof item.rel === 'string'
+          ) {
+            actions.push({
+              action: 'LINK',
+              from: item.from,
+              to: item.to,
+              rel: item.rel,
+              confidence: typeof item.confidence === 'number' ? item.confidence : undefined,
+            });
+          }
+          break;
       }
     }
 
@@ -273,6 +297,77 @@ export function parseMemoryResponse(raw: string): MemoryAction[] {
 
 // ─── Main Extraction Function ───────────────────────────────────────────────
 
+export interface ExtractFromTranscriptOptions {
+  /** Logical source type (e.g. "execute-task", "note", "file", "url", "artifact"). */
+  sourceType: string;
+  /** Stable identifier for the source (unit id, source id, URL, etc.). */
+  sourceId: string;
+  /** Optional scope for any CREATE actions ("project" / "global" / custom). */
+  scope?: string;
+  /** Optional tags applied to any CREATE actions. */
+  tags?: string[];
+  /** Bypass the mutex + rate-limit when caller has already vetted them. */
+  force?: boolean;
+}
+
+/**
+ * Core extractor — shared by unit post-processing and explicit ingest.
+ * Returns the applied actions for observability. Never throws.
+ */
+export async function extractMemoriesFromTranscript(
+  transcript: string,
+  llmCallFn: LLMCallFn,
+  opts: ExtractFromTranscriptOptions,
+): Promise<import('./memory-store.js').MemoryAction[]> {
+  if (!opts.force) {
+    if (_extracting) return [];
+    const now = Date.now();
+    if (now - _lastExtractionTime < MIN_EXTRACTION_INTERVAL_MS) return [];
+    _lastExtractionTime = now;
+  }
+
+  const acquireMutex = !_extracting;
+  if (acquireMutex) _extracting = true;
+  try {
+    const trimmed = transcript.trim();
+    if (!trimmed) return [];
+
+    const safeTranscript = redactSecrets(trimmed);
+    const activeMemories = getActiveMemories().map((m) => ({
+      id: m.id,
+      category: m.category,
+      content: m.content,
+    }));
+
+    const userPrompt = buildExtractionUserPrompt(
+      opts.sourceType,
+      opts.sourceId,
+      activeMemories,
+      safeTranscript,
+    );
+
+    const response = await llmCallFn(EXTRACTION_SYSTEM, userPrompt);
+    const actions = parseMemoryResponse(response);
+
+    if (actions.length === 0) return [];
+
+    const decorated = actions.map((action): import('./memory-store.js').MemoryAction => {
+      if (action.action !== 'CREATE') return action;
+      return {
+        ...action,
+        scope: action.scope ?? opts.scope,
+        tags: action.tags ?? opts.tags,
+      };
+    });
+    applyMemoryActions(decorated, opts.sourceType, opts.sourceId);
+    return decorated;
+  } catch {
+    return [];
+  } finally {
+    if (acquireMutex) _extracting = false;
+  }
+}
+
 /**
  * Extract memories from a completed unit's activity log.
  * Fire-and-forget — never throws, mutex-guarded, respects rate limiting.
@@ -283,22 +378,16 @@ export async function extractMemoriesFromUnit(
   unitId: string,
   llmCallFn: LLMCallFn,
 ): Promise<void> {
-  // Mutex guard
   if (_extracting) return;
 
-  // Rate limit
   const now = Date.now();
   if (now - _lastExtractionTime < MIN_EXTRACTION_INTERVAL_MS) return;
 
-  // Skip certain unit types
   if (SKIP_TYPES.has(unitType)) return;
 
   const unitKey = `${unitType}/${unitId}`;
-
-  // Already processed
   if (isUnitProcessed(unitKey)) return;
 
-  // Check file size
   try {
     const stat = statSync(activityFile);
     if (stat.size < MIN_ACTIVITY_SIZE) return;
@@ -308,41 +397,18 @@ export async function extractMemoriesFromUnit(
 
   _extracting = true;
   _lastExtractionTime = now;
-
   try {
-    // Read and parse activity file
     const raw = readFileSync(activityFile, 'utf-8');
     const transcript = extractTranscriptFromActivity(raw);
     if (!transcript.trim()) return;
 
-    // Redact secrets
-    const safeTranscript = redactSecrets(transcript);
+    await extractMemoriesFromTranscript(transcript, llmCallFn, {
+      sourceType: unitType,
+      sourceId: unitId,
+      force: true,
+    });
 
-    // Get current memories for context
-    const activeMemories = getActiveMemories().map(m => ({
-      id: m.id,
-      category: m.category,
-      content: m.content,
-    }));
-
-    // Build prompts
-    const userPrompt = buildExtractionUserPrompt(unitType, unitId, activeMemories, safeTranscript);
-
-    // Call LLM
-    const response = await llmCallFn(EXTRACTION_SYSTEM, userPrompt);
-
-    // Parse response
-    const actions = parseMemoryResponse(response);
-
-    // Apply actions
-    if (actions.length > 0) {
-      applyMemoryActions(actions, unitType, unitId);
-    }
-
-    // Decay stale memories periodically
     decayStaleMemories(20);
-
-    // Mark unit as processed
     markUnitProcessed(unitKey, activityFile);
   } catch {
     // Non-fatal — memory extraction failure should never affect auto-mode