Skip to content

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

15.5 KB
Raw Blame
import type { IIIClient } from "iii-sdk";
import { readFileSync } from "node:fs";
import { isManagedImagePath } from "../utils/image-store.js";
import type { RawObservation, CompressedObservation, MemoryProvider, ObservationCompression, Session } from "../types.js";
import { KV } from "../state/schema.js";
import type { StateKV } from "../state/kv.js";
import { COMPRESSION_SYSTEM, buildCompressionPrompt } from "../prompts/compression.js";
import { VISION_DESCRIPTION_PROMPT } from "../prompts/vision.js";
import { parseCompressionXml } from "../prompts/compression-output.js";
import { getSearchIndex, getVectorIndex, scheduleIndexSave, vectorIndexAddGuarded } from "./search.js";
import { CompressOutputSchema } from "../eval/schemas.js";
import { validateOutput } from "../eval/validator.js";
import { scoreCompression } from "../eval/quality.js";
import { compressWithRetry } from "../eval/self-correct.js";
import type { MetricsStore } from "../eval/metrics-store.js";
import { logger } from "../logger.js";
import { emitLiveEvent } from "../viewer/live-events.js";
import { withoutObservationSource } from "./observation-source.js";
import { budgetLiveObservationSource } from "./observation-source-budget.js";
import { buildSyntheticCompression } from "./compress-synthetic.js";
import { withKeyedLock } from "../state/keyed-mutex.js";
import { scrubRecord, stripPrivateData } from "./privacy.js";
import { compressionRaw, needsCompression, observationRevision, pendingCompression, type StoredObservation } from "./compression-state.js";
import { registerCompressionRecovery } from "./compression-recovery.js";

export const COMPRESSION_TIMEOUT_MS = 60_000;

type CompressRequest = { observationId: string; sessionId: string; raw?: RawObservation; expectedRevision?: string; scope?: { project?: string; agentId?: string } };
export type CompressResult = {
  success: boolean;
  error?: string;
  skipped?: boolean;
  retryable?: boolean;
  compressed?: Omit<CompressedObservation, "source">;
  qualityScore?: number;
  sourceTruncated?: boolean;
};
type CompressionAttempt = { revisions: Set<string>; resultRevision?: string };
type ActiveCompression = { promise: Promise<CompressResult>; attempt: CompressionAttempt };
const activeByStore = new WeakMap<StateKV, Map<string, ActiveCompression>>();

export function compressionInFlight(kv: StateKV, sessionId: string, observationId: string): boolean {
  return activeByStore.get(kv)?.has(JSON.stringify([sessionId, observationId])) ?? false;
}

function indexObservation(observation: CompressedObservation): void {
  getSearchIndex().add(observation);
  scheduleIndexSave();
}

export function registerCompressFunction(
  sdk: IIIClient,
  kv: StateKV,
  provider: MemoryProvider,
  metricsStore?: MetricsStore,
): void {
  const active = activeByStore.get(kv) ?? new Map<string, ActiveCompression>();
  activeByStore.set(kv, active);

  async function matchesScope(data: CompressRequest, row: StoredObservation): Promise<boolean> {
    if (!data.scope) return true;
    const session = await kv.get<Session>(KV.sessions, data.sessionId);
    return Boolean(session && (!data.scope.project || session.project === data.scope.project) &&
      (!data.scope.agentId || (row.agentId ?? session.agentId) === data.scope.agentId));
  }

  async function compress(data: CompressRequest, attempt: CompressionAttempt, deadline: number): Promise<CompressResult> {
    const { sessionId, observationId } = data;
    const startMs = Date.now();
    async function bounded<T>(work: () => Promise<T>): Promise<T> {
      const remaining = deadline - Date.now();
      if (remaining <= 0) throw new Error("compression_timeout");
      let timer: ReturnType<typeof setTimeout> | undefined;
      try {
        return await Promise.race([work(), new Promise<never>((_, reject) => {
          timer = setTimeout(() => reject(new Error("compression_timeout")), remaining);
        })]);
      } finally { clearTimeout(timer); }
    }
    const prepared = await withKeyedLock(`obs:${sessionId}`, async () => {
      const stored = await kv.get<StoredObservation>(KV.observations(sessionId), observationId);
      if (!stored || typeof stored !== "object" || stored.id !== observationId || stored.sessionId !== sessionId) return null;
      if (!await matchesScope(data, stored)) return { skipped: true as const };
      if (data.expectedRevision && observationRevision(stored) !== data.expectedRevision) return { skipped: true as const };
      if (!needsCompression(stored) && !data.raw) return { skipped: true as const };
      const rows = await kv.list<CompressedObservation>(KV.observations(sessionId));
      const fallback = "title" in stored ? stored : budgetLiveObservationSource(buildSyntheticCompression(scrubRecord(stored)), rows);
      const raw = compressionRaw(fallback);
      if (!raw && !("title" in stored)) return { unavailable: true as const };
      const compression: ObservationCompression = {
        ...pendingCompression((stored.compression?.attempts ?? 0) + (raw ? 1 : 0)),
        ...(raw ? { lastAttemptAt: new Date().toISOString() } : { status: "failed" as const, error: "source_unavailable" as const }),
      };
      const claimed = { ...stored, compression };
      await kv.set(KV.observations(sessionId), observationId, claimed);
      attempt.revisions.add(observationRevision(stored));
      attempt.revisions.add(observationRevision(claimed));
      if ("title" in claimed) indexObservation(claimed);
      return { raw, claimed, fallback, revision: observationRevision(claimed) };
    });
    if (!prepared) return { success: false, error: "observation_not_found", skipped: true, retryable: false };
    if ("skipped" in prepared) return { success: true, skipped: true };
    if ("unavailable" in prepared || !prepared.raw) return { success: false, error: "source_unavailable", retryable: false };
    const { raw, claimed, fallback, revision } = prepared;

    async function fail(error: NonNullable<ObservationCompression["error"]>): Promise<CompressResult> {
      const changed = await withKeyedLock(`obs:${sessionId}`, async () => {
        const current = await kv.get<StoredObservation>(KV.observations(sessionId), observationId);
        if (!current || observationRevision(current) !== revision) return true;
        const failed = { ...claimed, compression: { ...claimed.compression!, status: "failed" as const, error } };
        await kv.set(KV.observations(sessionId), observationId, failed);
        attempt.resultRevision = observationRevision(failed);
        attempt.revisions.add(attempt.resultRevision);
        return false;
      });
      await metricsStore?.record("mem::compress", Date.now() - startMs, false).catch(() => {});
      return changed
        ? { success: false, error: "observation_changed", skipped: true, retryable: false }
        : { success: false, error, retryable: true, ...(fallback.source?.truncated ? { sourceTruncated: true } : {}) };
    }

    try {
      let imageDescription: string | undefined;
      const hasImage = raw.modality === "image" || raw.modality === "mixed";

      if (hasImage && raw.imageData && provider.describeImage) {
        try {
          let base64Data = raw.imageData;
          let mimeType = "image/png";

          if (!raw.imageData.startsWith("/9j/") && !raw.imageData.startsWith("iVBOR")) {
            if (!isManagedImagePath(raw.imageData)) {
              throw new Error(`Refusing to read image outside managed store: ${raw.imageData}`);
            }
            const fileBuffer = readFileSync(raw.imageData);
            base64Data = fileBuffer.toString("base64");
            if (raw.imageData.endsWith(".jpg") || raw.imageData.endsWith(".jpeg")) mimeType = "image/jpeg";
            else if (raw.imageData.endsWith(".webp")) mimeType = "image/webp";
            else if (raw.imageData.endsWith(".gif")) mimeType = "image/gif";
          }

          imageDescription = await bounded(() => provider.describeImage!(base64Data, mimeType, VISION_DESCRIPTION_PROMPT));
          logger.info("Image described by vision model", { obsId: observationId });
        } catch {
          logger.warn("Vision model call failed, falling back to text-only compression", { obsId: observationId });
        }
      }

      const retainedOutput = raw.toolOutput ?? (raw.raw && Object.keys(Object(raw.raw)).length > 0 ? raw.raw : undefined);
      const prompt = buildCompressionPrompt({
        hookType: raw.hookType,
        toolName: raw.toolName,
        toolInput: raw.toolInput,
        toolOutput: imageDescription ? `[Image Description]: ${imageDescription}\n\n${retainedOutput ?? ""}` : retainedOutput,
        userPrompt: raw.userPrompt,
        assistantResponse: raw.assistantResponse,
        timestamp: raw.timestamp,
      });
      const validator = (response: string) => {
        const parsed = parseCompressionXml(response);
        if (!parsed) return { valid: false as const, errors: ["xml_parse_failed"] };
        const result = validateOutput(CompressOutputSchema, scrubRecord(parsed), "mem::compress");
        return result.valid ? result : { valid: false as const, errors: result.result.errors };
      };
      const result = await compressWithRetry({
        ...provider,
        compress: (system, user) => bounded(() => provider.compress(system, user)),
      }, COMPRESSION_SYSTEM, prompt, validator, 1);
      if (!result.valid) {
        return fail(result.errors?.includes("xml_parse_failed") ? "parse_failed" : "validation_failed");
      }
      const qualityScore = scoreCompression(result.data);
      const candidate: CompressedObservation = {
        ...fallback,
        ...result.data,
        compressedAt: new Date().toISOString(),
        confidence: qualityScore / 100,
        compression: { ...claimed.compression, status: "complete" },
        ...(raw.imageData ? { imageRef: raw.imageData } : {}),
        ...(imageDescription ? { imageDescription: stripPrivateData(imageDescription) } : {}),
      };
      const compressed = await withKeyedLock(`obs:${sessionId}`, async () => {
        const current = await kv.get<StoredObservation>(KV.observations(sessionId), observationId);
        if (!current || observationRevision(current) !== revision || !await matchesScope(data, current)) return null;
        const rows = await kv.list<CompressedObservation>(KV.observations(sessionId));
        const bounded = budgetLiveObservationSource(candidate, rows);
        await kv.set(KV.observations(sessionId), observationId, bounded);
        attempt.resultRevision = observationRevision(bounded);
        attempt.revisions.add(attempt.resultRevision);
        indexObservation(bounded);
        return bounded;
      });
      if (!compressed) return { success: false, error: "observation_changed", skipped: true, retryable: false };
      const committedRevision = observationRevision(compressed);
      await bounded(() => vectorIndexAddGuarded(
        observationId, sessionId, compressed.title + " " + compressed.narrative,
        { kind: "observation", logId: observationId },
        (embedding, isCurrent) => withKeyedLock(`obs:${sessionId}`, async () => {
          const current = await kv.get<StoredObservation>(KV.observations(sessionId), observationId);
          if (!isCurrent() || !current || observationRevision(current) !== committedRevision) return false;
          getVectorIndex()?.add(observationId, sessionId, embedding);
          return true;
        }),
      )).catch(() => {});
      const published = await withKeyedLock(`obs:${sessionId}`, async () => {
        const current = await kv.get<StoredObservation>(KV.observations(sessionId), observationId);
        if (!current || observationRevision(current) !== committedRevision || !await matchesScope(data, current)) return false;
        emitLiveEvent({
          id: `compressed-${observationId}`,
          type: "compressed_observation",
          data: { type: "compressed", observation: withoutObservationSource(compressed), sessionId },
        });
        return true;
      });
      if (!published) return { success: false, error: "observation_changed", skipped: true, retryable: false };
      await metricsStore?.record("mem::compress", Date.now() - startMs, true, qualityScore).catch(() => {});
      return { success: true, compressed: withoutObservationSource(compressed), qualityScore, ...(compressed.source?.truncated ? { sourceTruncated: true } : {}) };
    } catch {
      logger.warn("Observation retained for compression retry", { observationId, sessionId });
      return fail("compression_failed");
    }
  }

  async function dispatch(data: CompressRequest, deadline: number): Promise<CompressResult> {
    const key = JSON.stringify([data.sessionId, data.observationId]);
    const existing = active.get(key);
    if (existing) {
      const changed: CompressResult = { success: false, error: "observation_changed", skipped: true, retryable: false };
      const requestedRevision = await withKeyedLock(`obs:${data.sessionId}`, async () => {
        const current = await kv.get<StoredObservation>(KV.observations(data.sessionId), data.observationId);
        if (!current || current.id !== data.observationId || current.sessionId !== data.sessionId || !await matchesScope(data, current)) return null;
        const revision = observationRevision(current);
        if (data.expectedRevision && data.expectedRevision !== revision && !existing.attempt.revisions.has(data.expectedRevision)) return null;
        return data.expectedRevision ?? revision;
      });
      if (!requestedRevision) return changed;
      let timer: ReturnType<typeof setTimeout> | undefined;
      const result = await Promise.race([existing.promise, new Promise<CompressResult>((resolve) => {
        timer = setTimeout(() => resolve({ success: false, error: "compression_timeout", retryable: true }), Math.max(0, deadline - Date.now()));
      })]).finally(() => clearTimeout(timer));
      if (result.error === "compression_timeout") return result;
      const shared = await withKeyedLock(`obs:${data.sessionId}`, async () => {
        const current = await kv.get<StoredObservation>(KV.observations(data.sessionId), data.observationId);
        if (!current || current.id !== data.observationId || current.sessionId !== data.sessionId || !await matchesScope(data, current)) return changed;
        const revision = observationRevision(current);
        if (revision === existing.attempt.resultRevision && existing.attempt.revisions.has(requestedRevision)) return result;
        return revision === requestedRevision && (needsCompression(current) || data.raw) ? null : changed;
      });
      return shared ?? dispatch({ ...data, expectedRevision: requestedRevision }, deadline);
    }
    if (Date.now() >= deadline) return { success: false, error: "compression_timeout", retryable: true };
    const attempt: CompressionAttempt = { revisions: new Set() };
    const task: ActiveCompression = { attempt, promise: compress(data, attempt, deadline).finally(() => {
      if (active.get(key) === task) active.delete(key);
    }) };
    active.set(key, task);
    return task.promise;
  }

  sdk.registerFunction("mem::compress", (data: CompressRequest): Promise<CompressResult> => {
    if (!data || typeof data.sessionId !== "string" || !data.sessionId.trim() ||
        typeof data.observationId !== "string" || !data.observationId.trim()) {
      return Promise.resolve({ success: false, error: "invalid_observation_identity", retryable: false });
    }
    if (data.raw !== undefined && (!data.raw || typeof data.raw.hookType !== "string" || !data.raw.hookType)) {
      return Promise.resolve({ success: false, error: "invalid_raw_observation" });
    }
    return dispatch(data, Date.now() + COMPRESSION_TIMEOUT_MS);
  });
  registerCompressionRecovery(sdk, kv);
}