Skip to content

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

15.0 KB
Raw Blame
import type { IIIClient } from "iii-sdk";
import { markCaptureEventDeleted } from "../capture/event-record.js";
import type {
  Session,
  CompressedObservation,
  RawObservation,
  SessionSummary,
  Memory,
} from "../types.js";
import { KV } from "../state/schema.js";
import { StateKV } from "../state/kv.js";
import { withKeyedLock } from "../state/keyed-mutex.js";
import { removeSessionFromProjectIndex } from "../state/session-index.js";
import { unindexObservationSession } from "../state/obs-index.js";
import { isConsolidationEnabled } from "../config.js";
import { recordAudit } from "./audit.js";
import { deleteAccessLog } from "./access-tracker.js";
import { deleteFacetsForTargets } from "./facets.js";
import { getSearchIndex, vectorIndexRemove, flushIndexSave } from "./search.js";
import { logger } from "../logger.js";

interface EvictionConfig {
  staleSessionDays: number;
  lowImportanceMaxDays: number;
  lowImportanceThreshold: number;
  maxObservationsPerProject: number;
}

const MS_PER_DAY = 24 * 60 * 60 * 1000;

const DEFAULTS: EvictionConfig = {
  staleSessionDays: 30,
  lowImportanceMaxDays: 90,
  lowImportanceThreshold: 3,
  maxObservationsPerProject: 10_000,
};

interface EvictionStats {
  staleSessions: number;
  lowImportanceObs: number;
  capEvictions: number;
  expiredMemories: number;
  nonLatestMemories: number;
  dryRun: boolean;
}

function isValidRecoveryResult(result: unknown): boolean {
  if (!result || typeof result !== "object") return false;
  if (!("success" in result)) return true;
  return (result as { success?: unknown }).success !== false;
}

function isCompressedObservation(
  observation: CompressedObservation | RawObservation,
): observation is CompressedObservation {
  return (
    "title" in observation &&
    typeof observation.title === "string" &&
    observation.title.length > 0
  );
}

async function recoverStaleSession(
  sdk: IIIClient,
  sessionId: string,
): Promise<boolean> {
  try {
    const result = await sdk.trigger({
      function_id: "event::session::stopped",
      // Suppress the per-session consolidation fan-out: eviction runs a
      // single corpus-wide consolidation pass after all recoveries instead.
      payload: { sessionId, skipConsolidation: true },
    });
    if (!isValidRecoveryResult(result)) {
      logger.warn("Stale session recovery failed", {
        sessionId,
        result,
      });
      return false;
    }
    return true;
  } catch (err) {
    logger.warn("Stale session recovery failed", {
      sessionId,
      error: err instanceof Error ? err.message : String(err),
    });
    return false;
  }
}

async function runRecoveredSessionConsolidation(sdk: IIIClient): Promise<void> {
  // Same gate as the session-stop path: keyless installs must not fire
  // no-op LLM consolidation from an eviction sweep either.
  if (!isConsolidationEnabled()) return;
  try {
    await sdk.trigger({
      function_id: "mem::consolidate-pipeline",
      payload: { tier: "all", force: true },
    });
    // One crystallization pass for the batch (the per-session fan-out was
    // suppressed with skipConsolidation), keeping recovered sessions
    // consistent with normally-stopped ones without the N-fold amplification.
    await sdk.trigger({
      function_id: "mem::auto-crystallize",
      payload: { olderThanDays: 0 },
    });
  } catch (err) {
    logger.warn("Recovered session consolidation failed", {
      error: err instanceof Error ? err.message : String(err),
    });
  }
}

export function registerEvictFunction(sdk: IIIClient, kv: StateKV): void {
  sdk.registerFunction("mem::evict", 
    async (data: { dryRun?: boolean }): Promise<EvictionStats> => {
      const dryRun = data?.dryRun ?? false;
      const { decrementImageRef } = await import("./image-refs.js");
      let indexCleaned = false;
      const removeObservation = (
        sessionId: string,
        selected: CompressedObservation,
        eligible: (current: CompressedObservation) => boolean,
      ) => withKeyedLock(`obs:${sessionId}`, async () => {
        const current = await kv.get<CompressedObservation>(KV.observations(sessionId), selected.id);
        if (!current || !eligible(current)) return null;
        await markCaptureEventDeleted(kv, current);
        await kv.delete(KV.observations(sessionId), selected.id);
        getSearchIndex().remove(selected.id);
        vectorIndexRemove(selected.id);
        indexCleaned = true;
        return current;
      });

      const configOverride = await kv
        .get<Partial<EvictionConfig>>(KV.config, "eviction")
        .catch(() => null);
      const cfg = { ...DEFAULTS, ...configOverride };

      const now = Date.now();
      const stats: EvictionStats = {
        staleSessions: 0,
        lowImportanceObs: 0,
        capEvictions: 0,
        expiredMemories: 0,
        nonLatestMemories: 0,
        dryRun,
      };

      let recoveredStaleSessions = 0;
      const sessions = await kv.list<Session>(KV.sessions).catch(() => []);
      const summaries = await kv
        .list<SessionSummary>(KV.summaries)
        .catch(() => []);
      const summaryIds = new Set(summaries.map((s) => s.sessionId));

      for (const session of sessions) {
        if (!session.startedAt) continue;
        const age = now - new Date(session.startedAt).getTime();
        const staleDays = cfg.staleSessionDays * MS_PER_DAY;
        if (age > staleDays && !summaryIds.has(session.id)) {
          if (dryRun) {
            stats.staleSessions++;
          } else {
            const observations = await kv
              .list<CompressedObservation | RawObservation>(
                KV.observations(session.id),
              )
              .catch((err) => {
                logger.warn("Stale session observation scan failed", {
                  sessionId: session.id,
                  error: err instanceof Error ? err.message : String(err),
                });
                return null;
              });
            if (!observations) continue;

            const sessionRevision = JSON.stringify(session);
            const observationsRevision = JSON.stringify(observations);
            let recovered = false;
            const hasCompressedObservations = observations.some(
              isCompressedObservation,
            );
            if (hasCompressedObservations) {
              recovered = await recoverStaleSession(sdk, session.id);
              if (!recovered) continue;
              recoveredStaleSessions++;
            } else if (observations.length > 0) {
              logger.warn("Stale session has no compressed observations", {
                sessionId: session.id,
              });
              continue;
            }

            try {
              const removed = await withKeyedLock(`obs:${session.id}`, async () => {
                const current = await kv.get<Session>(KV.sessions, session.id);
                if (!current || JSON.stringify(current) !== sessionRevision) return false;
                const currentObservations = await kv.list(KV.observations(session.id));
                if (JSON.stringify(currentObservations) !== observationsRevision) return false;
                await kv.delete(KV.sessions, session.id);
                await kv.delete(KV.summaryRepairs, session.id);
                return true;
              });
              if (!removed) continue;
              stats.staleSessions++;
            } catch (err) {
              logger.warn("Eviction delete failed", {
                resource: "session",
                id: session.id,
                error: err instanceof Error ? err.message : String(err),
              });
              continue;
            }
            for (const o of observations) {
              await unindexObservationSession(kv, o.id).catch(() => {});
            }
            await removeSessionFromProjectIndex(
              kv,
              session.project,
              session.id,
            ).catch(() => {});
            await recordAudit(kv, "delete", "mem::evict", [session.id], {
              resource: "session",
              reason: recovered
                ? "stale_session_recovered_then_evicted"
                : "stale_session_without_summary",
              dryRun,
            });
          }
        }
      }

      if (!dryRun && recoveredStaleSessions > 0) {
        await runRecoveredSessionConsolidation(sdk);
      }

      const projectObs = new Map<string, CompressedObservation[]>();
      for (const session of sessions) {
        const obs = await kv
          .list<CompressedObservation>(KV.observations(session.id))
          .catch(() => []);
        const compressed = obs.filter((o) => o.title);

        for (const o of compressed) {
          if (!o.timestamp) continue;
          const age = now - new Date(o.timestamp).getTime();
          const maxAge = cfg.lowImportanceMaxDays * MS_PER_DAY;
          if (
            age > maxAge &&
            (o.importance ?? 5) < cfg.lowImportanceThreshold
          ) {
            if (dryRun) {
              stats.lowImportanceObs++;
            } else {
              let removed: CompressedObservation | null;
              try {
                removed = await removeObservation(session.id, o, (current) =>
                  Boolean(current.title) && now - new Date(current.timestamp).getTime() > maxAge &&
                  (current.importance ?? 5) < cfg.lowImportanceThreshold,
                );
                if (!removed) continue;
                stats.lowImportanceObs++;
              } catch (err) {
                logger.warn("Eviction delete failed", {
                  resource: "observation",
                  id: o.id,
                  sessionId: session.id,
                  error: err instanceof Error ? err.message : String(err),
                });
                continue;
              }
              await unindexObservationSession(kv, o.id).catch(() => {});
              if (removed.imageData) await decrementImageRef(kv, sdk, removed.imageData);
              if (removed.imageRef && removed.imageRef !== removed.imageData) await decrementImageRef(kv, sdk, removed.imageRef);
              await recordAudit(kv, "delete", "mem::evict", [o.id], {
                resource: "observation",
                reason: "low_importance_old_observation",
                sessionId: session.id,
                dryRun,
              });
            }
          }
        }

        const project = session.project || "unknown";
        const existing = projectObs.get(project) || [];
        existing.push(...compressed);
        projectObs.set(project, existing);
      }

      for (const [, obs] of projectObs) {
        if (obs.length > cfg.maxObservationsPerProject) {
          const sorted = obs.sort(
            (a, b) => (a.importance ?? 5) - (b.importance ?? 5),
          );
          const toEvict = sorted.slice(
            0,
            obs.length - cfg.maxObservationsPerProject,
          );
          if (dryRun) {
            stats.capEvictions += toEvict.length;
          } else {
            for (const o of toEvict) {
              let removed: CompressedObservation | null;
              try {
                removed = await removeObservation(o.sessionId, o, (current) =>
                  JSON.stringify(current) === JSON.stringify(o),
                );
                if (!removed) continue;
                stats.capEvictions++;
              } catch (err) {
                logger.warn("Eviction delete failed", {
                  resource: "observation",
                  id: o.id,
                  sessionId: o.sessionId,
                  error: err instanceof Error ? err.message : String(err),
                });
                continue;
              }
              await unindexObservationSession(kv, o.id).catch(() => {});
              if (removed.imageData) await decrementImageRef(kv, sdk, removed.imageData);
              if (removed.imageRef && removed.imageRef !== removed.imageData) await decrementImageRef(kv, sdk, removed.imageRef);
              await recordAudit(kv, "delete", "mem::evict", [o.id], {
                resource: "observation",
                reason: "project_observation_cap",
                sessionId: o.sessionId,
                dryRun,
              });
            }
          }
        }
      }

      const memories = await kv.list<Memory>(KV.memories).catch(() => []);
      const evictedMemIds = new Set<string>();
      const deletedMemIds = new Set<string>();
      try {
        for (const mem of memories) {
          if (mem.forgetAfter) {
            const expiry = new Date(mem.forgetAfter).getTime();
            if (now > expiry) {
              if (dryRun) {
                stats.expiredMemories++;
                evictedMemIds.add(mem.id);
              } else {
                try {
                  await kv.delete(KV.memories, mem.id);
                  deletedMemIds.add(mem.id);
                  stats.expiredMemories++;
                  evictedMemIds.add(mem.id);
                } catch (err) {
                  logger.warn("Eviction delete failed", {
                    resource: "memory",
                    id: mem.id,
                    reason: "expired_memory",
                    error: err instanceof Error ? err.message : String(err),
                  });
                  continue;
                }
                if (mem.imageRef) {
                  await decrementImageRef(kv, sdk, mem.imageRef);
                }
                await recordAudit(kv, "delete", "mem::evict", [mem.id], {
                  resource: "memory",
                  reason: "expired_memory",
                  dryRun,
                });
                await deleteAccessLog(kv, mem.id);
              }
            }
          }

          if (
            !evictedMemIds.has(mem.id) &&
            mem.isLatest === false &&
            mem.createdAt
          ) {
            const age = now - new Date(mem.createdAt).getTime();
            if (age > cfg.lowImportanceMaxDays * MS_PER_DAY) {
              if (dryRun) {
                stats.nonLatestMemories++;
              } else {
                try {
                  await kv.delete(KV.memories, mem.id);
                  deletedMemIds.add(mem.id);
                  stats.nonLatestMemories++;
                } catch (err) {
                  logger.warn("Eviction delete failed", {
                    resource: "memory",
                    id: mem.id,
                    reason: "old_non_latest_memory",
                    error: err instanceof Error ? err.message : String(err),
                  });
                  continue;
                }
                if (mem.imageRef) {
                  await decrementImageRef(kv, sdk, mem.imageRef);
                }
                await recordAudit(kv, "delete", "mem::evict", [mem.id], {
                  resource: "memory",
                  reason: "old_non_latest_memory",
                  dryRun,
                });
                await deleteAccessLog(kv, mem.id);
              }
            }
          }
        }
      } finally {
        await deleteFacetsForTargets(kv, deletedMemIds);
      }

      if (indexCleaned) await flushIndexSave();
      logger.info("Eviction complete", { stats });
      return stats;
    },
  );
}