Skip to content

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

4.4 KB
Raw Blame
import { spawn } from "node:child_process";
import { resolveClientSecret } from "../secret-store.js";
import { deriveEventId, hasHostIdentity } from "../capture/event-id.js";
import {
  appendSpool,
  drainInProgress,
  drainSpool,
  parseSentMark,
  reconcileSent,
  retainSent,
  spoolHasRecords,
  type SendOutcome,
  type SentMark,
  type SpoolRecord,
} from "../capture/spool.js";

export { stripPrivateData } from "../functions/privacy.js";

export const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111";
const SECRET = resolveClientSecret(REST_URL);
const DRAIN_CHILD_ENV = "AGENTMEMORY_CAPTURE_DRAIN_CHILD";
const DRAIN_MAX_RECORDS = 500;
const DRAIN_DEADLINE_MS = 20_000;
const DRAIN_REQUEST_TIMEOUT_MS = 5000;

export type CaptureOutcome = "delivered" | "duplicate" | "rejected" | "spooled" | "dropped";

export interface ObserveBody {
  hookType: string;
  sessionId: string;
  project: string;
  cwd: string;
  timestamp: string;
  data: unknown;
  eventId?: string;
}

export function authHeaders(): Record<string, string> {
  const h: Record<string, string> = { "Content-Type": "application/json" };
  if (SECRET) h["Authorization"] = `Bearer ${SECRET}`;
  return h;
}

export function withEventId(
  body: ObserveBody,
  host: Record<string, unknown>,
  content?: unknown,
  options: { stable?: boolean } = {},
): ObserveBody {
  const source = options.stable || hasHostIdentity(host) ? host : { ...host, timestamp: body.timestamp };
  return {
    ...body,
    eventId: deriveEventId(body.hookType, body.sessionId, source, content ?? body.data),
  };
}

function classify(status: number): SendOutcome {
  if (status >= 200 && status < 300) return status === 200 ? "duplicate" : "delivered";
  if (status === 408 || status === 429 || status >= 500) return "retry";
  return "rejected";
}

async function post(body: Record<string, unknown>, timeoutMs: number): Promise<{ outcome: SendOutcome; mark: SentMark | null }> {
  const res = await fetch(`${REST_URL}/agentmemory/observe`, {
    method: "POST",
    headers: authHeaders(),
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(timeoutMs),
  });
  const text = await res.text().catch(() => "");
  const outcome = classify(res.status);
  if (outcome !== "delivered" && outcome !== "duplicate") return { outcome, mark: null };
  try {
    return { outcome, mark: parseSentMark(JSON.parse(text)) };
  } catch {
    return { outcome, mark: null };
  }
}

function keepUntilDurable(eventId: string, body: Record<string, unknown>, mark: SentMark): number {
  const { requeued } = reconcileSent(REST_URL, mark.bootId);
  retainSent(REST_URL, eventId, body, mark);
  return requeued;
}

function startDrainChild(): void {
  if (process.env[DRAIN_CHILD_ENV] === "1") return;
  if (!process.argv[1] || drainInProgress(REST_URL)) return;
  try {
    const child = spawn(process.execPath, [process.argv[1]], {
      detached: true,
      stdio: "ignore",
      windowsHide: true,
      env: { ...process.env, [DRAIN_CHILD_ENV]: "1" },
    });
    child.on("error", () => {});
    child.unref();
  } catch {}
}

export async function captureObservation(body: ObserveBody, timeoutMs: number): Promise<CaptureOutcome> {
  const eventId = body.eventId ?? deriveEventId(body.hookType, body.sessionId, null, body.data);
  const payload = { ...body, eventId } as unknown as Record<string, unknown>;
  let reason: string;
  try {
    const { outcome, mark } = await post(payload, timeoutMs);
    if (outcome !== "retry") {
      const requeued = mark ? keepUntilDurable(eventId, payload, mark) : 0;
      if (requeued > 0 || spoolHasRecords(REST_URL)) startDrainChild();
      return outcome;
    }
    reason = "server-error";
  } catch (err) {
    const name = err instanceof Error ? err.name : "";
    reason = name === "TimeoutError" || name === "AbortError" ? "timeout" : "unreachable";
  }
  return appendSpool(REST_URL, eventId, payload, reason).spooled ? "spooled" : "dropped";
}

export function isDrainChild(): boolean {
  return process.env[DRAIN_CHILD_ENV] === "1";
}

export async function runDrainChild(): Promise<void> {
  await drainSpool(
    REST_URL,
    async (record: SpoolRecord) => {
      const { outcome, mark } = await post({ ...record.body, eventId: record.eventId }, DRAIN_REQUEST_TIMEOUT_MS);
      if (mark) retainSent(REST_URL, record.eventId, record.body, mark);
      return outcome;
    },
    { maxRecords: DRAIN_MAX_RECORDS, deadlineMs: DRAIN_DEADLINE_MS },
  ).catch(() => undefined);
}