Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

6.5 KB
Raw Blame
import { matchesSearchLayer, type SearchLayer, type SearchLayerResolver } from "./search-layer.js";

export function float32ToBase64(arr: Float32Array): string {
  return Buffer.from(arr.buffer, arr.byteOffset, arr.byteLength).toString(
    "base64",
  );
}

export function base64ToFloat32(b64: string): Float32Array {
  const buf = Buffer.from(b64, "base64");
  return new Float32Array(
    buf.buffer,
    buf.byteOffset,
    buf.byteLength / Float32Array.BYTES_PER_ELEMENT,
  );
}

function cosineSimilarity(a: Float32Array, b: Float32Array): number {
  if (a.length !== b.length) return 0;
  let dot = 0;
  let normA = 0;
  let normB = 0;
  for (let i = 0; i < a.length; i++) {
    dot += a[i] * b[i];
    normA += a[i] * a[i];
    normB += b[i] * b[i];
  }
  const denom = Math.sqrt(normA) * Math.sqrt(normB);
  return denom === 0 ? 0 : dot / denom;
}

export type VectorEntry = { embedding: Float32Array; sessionId: string };

export type VectorChangeListener = (obsId: string | null, entry: VectorEntry | null) => void;

export class VectorIndex {
  private vectors: Map<string, VectorEntry> = new Map();
  private changes: Map<string, boolean> = new Map();
  private listener: VectorChangeListener | null = null;

  setChangeListener(listener: VectorChangeListener | null): void {
    this.listener = listener;
  }

  add(obsId: string, sessionId: string, embedding: Float32Array): void {
    const entry = { embedding, sessionId };
    this.vectors.set(obsId, entry);
    this.changes.set(obsId, true);
    this.listener?.(obsId, entry);
  }

  remove(obsId: string): void {
    if (this.vectors.delete(obsId)) {
      this.changes.set(obsId, false);
      this.listener?.(obsId, null);
    }
  }

  has(obsId: string): boolean {
    return this.vectors.has(obsId);
  }

  get(obsId: string): VectorEntry | undefined {
    return this.vectors.get(obsId);
  }

  entries(): IterableIterator<[string, VectorEntry]> {
    return this.vectors.entries();
  }

  loadPersisted(obsId: string, sessionId: string, embedding: Float32Array): void {
    this.vectors.set(obsId, { embedding, sessionId });
  }

  get pendingChanges(): number {
    return this.changes.size;
  }

  takeChanges(): Map<string, boolean> {
    const taken = this.changes;
    this.changes = new Map();
    return taken;
  }

  returnChanges(changes: Map<string, boolean>): void {
    for (const [obsId, present] of changes) {
      if (!this.changes.has(obsId)) this.changes.set(obsId, present);
    }
  }

  markRemoved(obsId: string): void {
    if (!this.vectors.has(obsId)) this.changes.set(obsId, false);
  }

  markAllChanged(): void {
    for (const obsId of this.vectors.keys()) this.changes.set(obsId, true);
  }

  search(
    query: Float32Array,
    limit = 20,
    targetLayer: SearchLayer = "all",
    resolveLayer?: SearchLayerResolver,
  ): Array<{ obsId: string; sessionId: string; score: number }> {
    const results: Array<{
      obsId: string;
      sessionId: string;
      score: number;
    }> = [];
    let minScore = -Infinity;

    for (const [obsId, entry] of this.vectors) {
      if (!matchesSearchLayer(obsId, entry.sessionId, targetLayer, resolveLayer?.(obsId, entry.sessionId))) continue;
      const score = cosineSimilarity(query, entry.embedding);
      if (results.length < limit) {
        results.push({ obsId, sessionId: entry.sessionId, score });
        if (results.length === limit) {
          results.sort((a, b) => a.score - b.score);
          minScore = results[0].score;
        }
      } else if (score > minScore) {
        results[0] = { obsId, sessionId: entry.sessionId, score };
        results.sort((a, b) => a.score - b.score);
        minScore = results[0].score;
      }
    }

    results.sort((a, b) => b.score - a.score);
    return results;
  }

  get size(): number {
    return this.vectors.size;
  }

  // Walks every stored vector and returns the obsIds whose dimension
  // doesn't match `expected`, plus the set of distinct dimensions seen.
  // Used by the persistence-restore guard in src/index.ts to refuse
  // loading any index containing wrong-dimension vectors — including
  // legacy on-disk indexes written before the live-API dimension guard
  // existed (where a mid-session provider swap could mix dimensions
  // inside a single index). Empty `mismatches` plus a single-entry
  // `seenDimensions` matching `expected` is the only clean state.
  validateDimensions(
    expected: number,
  ): { mismatches: Array<{ obsId: string; dim: number }>; seenDimensions: Set<number> } {
    const mismatches: Array<{ obsId: string; dim: number }> = [];
    const seenDimensions = new Set<number>();
    for (const [obsId, entry] of this.vectors) {
      const dim = entry.embedding.length;
      seenDimensions.add(dim);
      if (dim !== expected) {
        mismatches.push({ obsId, dim });
      }
    }
    return { mismatches, seenDimensions };
  }

  clear(): void {
    const hadVectors = this.vectors.size > 0;
    for (const obsId of this.vectors.keys()) this.changes.set(obsId, false);
    this.vectors.clear();
    if (hadVectors) this.listener?.(null, null);
  }

  restoreFrom(other: VectorIndex): void {
    const src = (other as any).vectors as Map<
      string,
      { embedding: Float32Array; sessionId: string }
    >;
    this.vectors = new Map();
    for (const [obsId, entry] of src) {
      this.vectors.set(obsId, {
        embedding: new Float32Array(entry.embedding),
        sessionId: entry.sessionId,
      });
    }
    this.changes = new Map(other.changes);
  }

  serialize(): string {
    const data: Array<[string, { embedding: string; sessionId: string }]> = [];
    for (const [obsId, entry] of this.vectors) {
      data.push([
        obsId,
        {
          embedding: float32ToBase64(entry.embedding),
          sessionId: entry.sessionId,
        },
      ]);
    }
    return JSON.stringify(data);
  }

  static deserialize(json: string): VectorIndex {
    const idx = new VectorIndex();
    let data: unknown;
    try {
      data = JSON.parse(json);
    } catch {
      return idx;
    }
    if (!Array.isArray(data)) return idx;
    for (const row of data) {
      try {
        if (!Array.isArray(row) || row.length < 2) continue;
        const [obsId, entry] = row;
        if (
          typeof obsId !== "string" ||
          typeof entry?.embedding !== "string" ||
          typeof entry?.sessionId !== "string"
        )
          continue;
        idx.vectors.set(obsId, {
          embedding: base64ToFloat32(entry.embedding),
          sessionId: entry.sessionId,
        });
      } catch {
        continue;
      }
    }
    return idx;
  }
}