Skip to content

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

7.6 KB
Raw Blame
import type { StateKV } from "./kv.js";
import { KV } from "./schema.js";
import { getGraphGeneration, pinGraphStateGeneration } from "./graph-generation.js";
import { getGraphIndexStatus } from "./graph-retrieval-index.js";
import { getAgentId, isAgentScopeIsolated } from "../config.js";
import type {
  GraphSnapshot,
  Lesson,
  Memory,
  Session,
} from "../types.js";

export interface ViewerCounts {
  sessions: number;
  activeSessions: number;
  observations: number;
  memories: number;
  latestMemories: number;
  lessons: number;
  actions: number;
  crystals: number;
  semantic: number;
  procedural: number;
  graphNodes: number | null;
  graphEdges: number | null;
  updatedAt: string;
}

export type CountedKind = "lessons" | "actions" | "crystals" | "semantic" | "procedural";

const EMIT_DELAY_MS = 500;
const MAX_LOAD_ATTEMPTS = 2;

let counts: ViewerCounts | null = null;
let loading: Promise<ViewerCounts> | null = null;
let changedWhileLoading = false;
let emitter: ((counts: ViewerCounts) => void) | null = null;
let emitTimer: ReturnType<typeof setTimeout> | null = null;

export function setViewerCountsEmitter(fn: ((counts: ViewerCounts) => void) | null): void {
  emitter = fn;
}

export function invalidateViewerCounts(): void {
  counts = null;
  if (loading) changedWhileLoading = true;
}

function inAgentScope(record: { agentId?: string } | null | undefined): boolean {
  if (!record) return false;
  return !isAgentScopeIsolated() || record.agentId === getAgentId();
}

function isLiveLesson(lesson: Lesson | null | undefined): boolean {
  return Boolean(lesson) && lesson!.deleted !== true;
}

async function listOrEmpty<T>(kv: StateKV, scope: string): Promise<T[]> {
  const rows = await kv.list<T>(scope).catch(() => [] as T[]);
  return Array.isArray(rows) ? rows : [];
}

export async function readViewerGraphMetadata(kv: StateKV): Promise<{
  generation: string | null;
  stats: GraphSnapshot["stats"] | null;
  updatedAt: string | null;
  graphIndex: { status: string; incomplete: boolean };
}> {
  for (let attempt = 0; attempt < 2; attempt++) {
    const generation = await getGraphGeneration(kv);
    const control = await getGraphIndexStatus(pinGraphStateGeneration(kv, generation));
    if (generation !== await getGraphGeneration(kv)) continue;
    const ready = control?.status === "ready" && !control.pending && !control.batchPending;
    return {
      generation,
      stats: ready ? { totalNodes: control.nodes, totalEdges: control.edges,
        nodesByType: control.nodesByType, edgesByType: control.edgesByType } : null,
      updatedAt: control?.updatedAt ?? null,
      graphIndex: { status: control?.pending || control?.batchPending ? "dirty" : control?.status ?? "needs-migration",
        incomplete: (control?.incompleteRecords ?? 0) > 0 },
    };
  }
  throw new Error("Graph generation changed while reading index metadata");
}

async function readCounts(kv: StateKV): Promise<ViewerCounts> {
  const [sessions, memories, lessons, actions, crystals, semantic, procedural, graph] =
    await Promise.all([
      listOrEmpty<Session>(kv, KV.sessions),
      listOrEmpty<Memory>(kv, KV.memories),
      listOrEmpty<Lesson>(kv, KV.lessons),
      listOrEmpty<unknown>(kv, KV.actions),
      listOrEmpty<unknown>(kv, KV.crystals),
      listOrEmpty<unknown>(kv, KV.semantic),
      listOrEmpty<unknown>(kv, KV.procedural),
      readViewerGraphMetadata(kv).catch(() => null),
    ]);
  const scopedSessions = sessions.filter(inAgentScope);
  const scopedMemories = memories.filter(inAgentScope);
  return {
    sessions: scopedSessions.length,
    activeSessions: scopedSessions.filter((s) => s.status === "active").length,
    observations: scopedSessions.reduce((sum, s) => sum + (s.observationCount || 0), 0),
    memories: scopedMemories.length,
    latestMemories: scopedMemories.filter((m) => m.isLatest !== false).length,
    lessons: lessons.filter(isLiveLesson).length,
    actions: actions.length,
    crystals: crystals.length,
    semantic: semantic.length,
    procedural: procedural.length,
    graphNodes: graph?.stats?.totalNodes ?? null,
    graphEdges: graph?.stats?.totalEdges ?? null,
    updatedAt: new Date().toISOString(),
  };
}

export async function getViewerCounts(kv: StateKV): Promise<ViewerCounts> {
  if (counts) {
    noteGraphStats((await readViewerGraphMetadata(kv).catch(() => null))?.stats);
    if (counts) return { ...counts };
  }
  if (!loading) {
    loading = (async () => {
      let result = await readCounts(kv);
      for (let attempt = 1; attempt < MAX_LOAD_ATTEMPTS && changedWhileLoading; attempt++) {
        changedWhileLoading = false;
        result = await readCounts(kv);
      }
      // A second concurrent change can exhaust the bounded refresh attempts.
      // Return this read, but let the next request refresh instead of caching it.
      counts = changedWhileLoading ? null : result;
      changedWhileLoading = false;
      return result;
    })().finally(() => {
      loading = null;
    });
  }
  return { ...(await loading) };
}

function scheduleEmit(): void {
  if (!emitter || emitTimer) return;
  emitTimer = setTimeout(() => {
    emitTimer = null;
    if (counts && emitter) emitter({ ...counts });
  }, EMIT_DELAY_MS);
  if (typeof emitTimer === "object" && emitTimer && "unref" in emitTimer) emitTimer.unref();
}

function applyDelta(apply: (current: ViewerCounts) => boolean): void {
  if (!counts) {
    if (loading) changedWhileLoading = true;
    return;
  }
  if (!apply(counts)) return;
  counts.updatedAt = new Date().toISOString();
  scheduleEmit();
}

function presence(before: unknown, after: unknown): number {
  return (after ? 1 : 0) - (before ? 1 : 0);
}

export function noteSessionChange(before: Session | null | undefined, after: Session | null | undefined): void {
  const prev = inAgentScope(before) ? before : null;
  const next = inAgentScope(after) ? after : null;
  applyDelta((c) => {
    const sessions = presence(prev, next);
    const active = presence(prev?.status === "active", next?.status === "active");
    const observations = (next?.observationCount || 0) - (prev?.observationCount || 0);
    if (sessions === 0 && active === 0 && observations === 0) return false;
    c.sessions += sessions;
    c.activeSessions += active;
    c.observations += observations;
    return true;
  });
}

export function noteMemoryChange(before: Memory | null | undefined, after: Memory | null | undefined): void {
  const prev = inAgentScope(before) ? before : null;
  const next = inAgentScope(after) ? after : null;
  applyDelta((c) => {
    const total = presence(prev, next);
    const latest = presence(prev && prev.isLatest !== false, next && next.isLatest !== false);
    if (total === 0 && latest === 0) return false;
    c.memories += total;
    c.latestMemories += latest;
    return true;
  });
}

export function noteRowChange(kind: CountedKind, before: unknown, after: unknown): void {
  const alive = (row: unknown) =>
    kind === "lessons" ? isLiveLesson(row as Lesson | null | undefined) : Boolean(row);
  applyDelta((c) => {
    const delta = presence(alive(before), alive(after));
    if (delta === 0) return false;
    c[kind] += delta;
    return true;
  });
}

export function noteGraphStats(stats: GraphSnapshot["stats"] | null | undefined): void {
  applyDelta((c) => {
    const nodes = stats?.totalNodes ?? null, edges = stats?.totalEdges ?? null;
    if (c.graphNodes === nodes && c.graphEdges === edges) return false;
    c.graphNodes = nodes;
    c.graphEdges = edges;
    return true;
  });
}

export function resetViewerCounts(): void {
  counts = null;
  loading = null;
  changedWhileLoading = false;
  emitter = null;
  if (emitTimer) clearTimeout(emitTimer);
  emitTimer = null;
}