@bothat-io/molenkopf 0.1.2

package/packages/core/src/manifest/audit-store.ts

@@ -0,0 +1,189 @@
+import { readFile, readdir, rename, rm, stat } from "node:fs/promises";
+import { renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { defaultDataDir } from "../storage/local-paths.ts";
+import { chmodPrivateSync, ensurePrivateDirSync, PRIVATE_FILE_MODE } from "../storage/private-state.ts";
+import { purgeChildDir } from "../storage/purge-dir.ts";
+import { isAuditManifest, normalizedManifest } from "./audit-safety.ts";
+
+export type AuditManifest = {
+  requestId: string;
+  timestamp: string;
+  method: string;
+  path: string;
+  targetHost: string;
+  providerId?: string;
+  client?: { id: string; label: string; source: "user" | "agent" | "api_key" | "unattributed"; userId?: string; agentId?: string; teamIds?: string[]; keyId?: string; project?: string };
+  compressedItems: number;
+  estimatedOriginalTokens: number;
+  estimatedCompressedTokens: number;
+  estimatedSavedTokens: number;
+  redactedSecrets: number;
+  retrievalIds: string[];
+  compressorsUsed: string[];
+  warnings: string[];
+  statusCode?: number;
+  durationMs?: number;
+  upstreamInputTokens?: number;
+  upstreamOutputTokens?: number;
+};
+export type AuditRetention = { maxFiles?: number; maxBytes?: number; maxAgeMs?: number };
+export type AuditStoreOptions = { retention?: AuditRetention; now?: () => Date };
+export type AuditPage = { items: AuditManifest[]; nextCursor?: string; skippedCorrupt: number };
+
+export class AuditCursorError extends Error {
+  constructor() { super("invalid audit cursor"); this.name = "AuditCursorError"; }
+}
+
+export class AuditStore {
+  private root: string;
+  private retention: AuditRetention;
+  private now: () => Date;
+
+  constructor(root = defaultDataDir(), options: AuditStoreOptions = {}) {
+    this.root = root; this.retention = options.retention ?? {}; this.now = options.now ?? (() => new Date());
+  }
+
+  async write(manifest: AuditManifest): Promise<void> {
+    const safe = normalizedManifest(manifest);
+    const dir = join(this.root, "audit");
+    ensurePrivateDirSync(dir);
+    const name = `${safe.timestamp.replace(/[:.]/g, "-")}-${safeName(safe.requestId)}.json`;
+    const tmp = join(dir, `tmp-${process.pid}-${Date.now()}-${safeName(safe.requestId)}.json.tmp`);
+    const final = join(dir, name);
+    writeFileSync(tmp, JSON.stringify(safe, null, 2), privateWriteOptions());
+    chmodPrivateSync(tmp, PRIVATE_FILE_MODE);
+    renameSync(tmp, final);
+    chmodPrivateSync(final, PRIVATE_FILE_MODE);
+    await this.enforceRetention(dir);
+  }
+
+  async latest(): Promise<AuditManifest | undefined> {
+    return this.latestFast();
+  }
+
+  async latestFast(): Promise<AuditManifest | undefined> {
+    return (await this.listPage({ limit: 1, newestFirst: true })).items[0];
+  }
+
+  async listPage(options: { limit?: number; cursor?: string; newestFirst?: boolean; filter?: (item: AuditManifest) => boolean } = {}): Promise<AuditPage> {
+    const dir = join(this.root, "audit");
+    const limit = Math.max(1, Math.min(1000, Math.floor(options.limit ?? 100)));
+    let files = await auditFiles(dir);
+    if (options.newestFirst) files = files.reverse();
+    const start = options.cursor ? cursorIndex(files, options.cursor) + 1 : 0;
+    const items: AuditManifest[] = [];
+    let skippedCorrupt = 0, index = Math.max(0, start), lastFile: string | undefined;
+    for (; index < files.length && items.length < limit; index++) {
+      const file = files[index];
+      const item = await readManifest(dir, file);
+      if (item && (!options.filter || options.filter(item))) { items.push(item); lastFile = file; } else if (!item) { skippedCorrupt++; await quarantine(dir, file); }
+    }
+    return { items, skippedCorrupt, nextCursor: index < files.length && lastFile ? encodeCursor(lastFile) : undefined };
+  }
+
+  async list(): Promise<AuditManifest[]> {
+    const dir = join(this.root, "audit");
+    const files = await auditFiles(dir);
+    const out: AuditManifest[] = [];
+    for (const file of files) {
+      const item = await readManifest(dir, file);
+      if (item) out.push(item); else await quarantine(dir, file);
+    }
+    return out;
+  }
+
+  async purgeAll(): Promise<void> {
+    await purgeChildDir(this.root, "audit");
+  }
+
+  private async enforceRetention(dir: string): Promise<void> {
+    if (!this.retention.maxAgeMs && !this.retention.maxFiles && !this.retention.maxBytes) return;
+    const files = await auditFiles(dir).catch(() => []);
+    const now = this.now().getTime();
+    const entries = await Promise.all(files.map(async (file) => ({ file, size: await fileSize(join(dir, file)), ageMs: now - fileTime(file) })));
+    let kept = entries.filter((entry) => !this.retention.maxAgeMs || entry.ageMs <= this.retention.maxAgeMs);
+    for (const entry of entries) if (!kept.includes(entry)) await rm(join(dir, entry.file), { force: true });
+    if (this.retention.maxFiles && kept.length > this.retention.maxFiles) {
+      for (const entry of kept.slice(0, kept.length - this.retention.maxFiles)) await rm(join(dir, entry.file), { force: true });
+      kept = kept.slice(-this.retention.maxFiles);
+    }
+    while (this.retention.maxBytes && kept.reduce((sum, entry) => sum + entry.size, 0) > this.retention.maxBytes && kept.length) {
+      const [entry, ...rest] = kept;
+      await rm(join(dir, entry.file), { force: true });
+      kept = rest;
+    }
+  }
+}
+
+async function auditFiles(dir: string): Promise<string[]> {
+  try {
+    return (await readdir(dir)).filter((file) => file.endsWith(".json") && !file.endsWith(".corrupt.json")).sort();
+  } catch (err) {
+    if (isFsCode(err, "ENOENT")) return [];
+    throw err;
+  }
+}
+
+async function readManifest(dir: string, file: string): Promise<AuditManifest | undefined> {
+  let raw: string;
+  try {
+    raw = await readFile(join(dir, file), "utf8");
+  } catch (err) {
+    if (isFsCode(err, "ENOENT")) return undefined;
+    throw err;
+  }
+  try {
+    const value = JSON.parse(raw) as unknown;
+    if (!isAuditManifest(value)) return undefined;
+    try {
+      return normalizedManifest(value);
+    } catch {
+      return undefined;
+    }
+  } catch (err) {
+    if (err instanceof SyntaxError) return undefined;
+    throw err;
+  }
+}
+
+function isFsCode(err: unknown, code: string): boolean {
+  return Boolean(err && typeof err === "object" && "code" in err && (err as { code?: unknown }).code === code);
+}
+
+async function quarantine(dir: string, file: string): Promise<void> {
+  await rename(join(dir, file), join(dir, `${file}.corrupt`)).catch(() => {});
+}
+
+function safeName(value: string): string {
+  return value.replace(/[^a-z0-9._:-]/gi, "_").slice(0, 96) || "request";
+}
+
+function encodeCursor(file: string): string {
+  return Buffer.from(JSON.stringify({ file }), "utf8").toString("base64url");
+}
+
+function cursorIndex(files: string[], cursor: string): number {
+  try {
+    const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")) as { file?: unknown };
+    if (typeof parsed.file !== "string") throw new Error("bad");
+    const index = files.indexOf(parsed.file);
+    if (index < 0) throw new Error("bad");
+    return index;
+  } catch {
+    throw new AuditCursorError();
+  }
+}
+
+function fileTime(file: string): number {
+  const stamp = file.slice(0, 24).replace(/T(\d\d)-(\d\d)-(\d\d)-(\d\d\d)Z/, "T$1:$2:$3.$4Z");
+  return Date.parse(stamp) || 0;
+}
+
+async function fileSize(path: string): Promise<number> {
+  try { return (await stat(path)).size; } catch { return 0; }
+}
+
+function privateWriteOptions(): { mode: number } | undefined {
+  return process.platform === "win32" ? undefined : { mode: PRIVATE_FILE_MODE };
+}

package/packages/core/src/manifest/audit-summary.ts

@@ -0,0 +1,184 @@
+import type { AuditManifest } from "./audit-store.ts";
+import { confirmedSavedTokens } from "./audit-metrics.ts";
+
+export type AuditSummaryTotals = {
+  requests: number;
+  ok: number;
+  errors: number;
+  unknown: number;
+  originalTokens: number;
+  forwardedTokens: number;
+  savedTokens: number;
+  savedPercent: number;
+  upstreamInputTokens: number;
+  upstreamOutputTokens: number;
+  compressedItems: number;
+  redactedSecrets: number;
+  warnings: number;
+};
+
+export type AuditSummaryCount = { id: string; label: string; count: number };
+
+export type AuditSummaryStatusTotals = {
+  ok: number;
+  errors: number;
+  unknown: number;
+  byClass: AuditSummaryCount[];
+  byCode: AuditSummaryCount[];
+};
+
+export type AuditSummaryWarningTotals = { requests: number; warnings: number };
+
+export type AuditSummaryBucket = AuditSummaryTotals & {
+  id: string;
+  label: string;
+  source: string;
+  project?: string;
+  latestAt?: string;
+};
+
+export type AuditSummaryBreakdown = AuditSummaryTotals & { id: string; label: string; latestAt?: string };
+
+export type AuditSummary = AuditSummaryTotals & {
+  buckets: AuditSummaryBucket[];
+  statusTotals: AuditSummaryStatusTotals;
+  warningTotals: AuditSummaryWarningTotals;
+  providers: AuditSummaryBreakdown[];
+  endpoints: AuditSummaryBreakdown[];
+};
+
+type MutableTotals = Omit<AuditSummaryTotals, "savedPercent">;
+type MutableBucket = Omit<AuditSummaryBucket, "savedPercent">;
+type MutableBreakdown = Omit<AuditSummaryBreakdown, "savedPercent">;
+
+type StatusAccumulator = { unknown: number; byClass: Map<string, AuditSummaryCount>; byCode: Map<string, AuditSummaryCount> };
+
+export function summarizeAudit(manifests: AuditManifest[]): AuditSummary {
+  const totals = empty();
+  const buckets = new Map<string, MutableBucket>();
+  const providers = new Map<string, MutableBreakdown>();
+  const endpoints = new Map<string, MutableBreakdown>();
+  const status = emptyStatus();
+  let warningRequests = 0;
+  for (const manifest of manifests) {
+    add(totals, manifest);
+    addStatus(status, manifest.statusCode);
+    if (manifest.warnings.length > 0) warningRequests++;
+    const client = manifest.client ?? { id: "unattributed", label: "unattributed client", source: "unattributed" as const };
+    addGroup(bucketFor(buckets, client), manifest);
+    addGroup(breakdownFor(providers, providerId(manifest), providerLabel(manifest)), manifest);
+    addGroup(breakdownFor(endpoints, endpointId(manifest), endpointLabel(manifest)), manifest);
+  }
+  return {
+    ...finish(totals),
+    buckets: sortGroups([...buckets.values()].map(finish)),
+    statusTotals: {
+      ok: totals.ok,
+      errors: totals.errors,
+      unknown: status.unknown,
+      byClass: sortCounts(status.byClass),
+      byCode: sortCounts(status.byCode)
+    },
+    warningTotals: { requests: warningRequests, warnings: totals.warnings },
+    providers: sortGroups([...providers.values()].map(finish)),
+    endpoints: sortGroups([...endpoints.values()].map(finish))
+  };
+}
+
+function empty(): MutableTotals {
+  return { requests: 0, ok: 0, errors: 0, unknown: 0, originalTokens: 0, forwardedTokens: 0, savedTokens: 0, upstreamInputTokens: 0, upstreamOutputTokens: 0, compressedItems: 0, redactedSecrets: 0, warnings: 0 };
+}
+
+function emptyStatus(): StatusAccumulator { return { unknown: 0, byClass: new Map(), byCode: new Map() }; }
+
+function add(target: MutableTotals, manifest: AuditManifest) {
+  target.requests++;
+  const status = statusKind(manifest.statusCode);
+  if (status === "ok") target.ok++;
+  else if (status === "error") target.errors++;
+  else target.unknown++;
+  target.originalTokens += manifest.estimatedOriginalTokens;
+  target.forwardedTokens += manifest.estimatedCompressedTokens;
+  target.savedTokens += confirmedSavedTokens(manifest);
+  target.upstreamInputTokens += manifest.upstreamInputTokens ?? 0;
+  target.upstreamOutputTokens += manifest.upstreamOutputTokens ?? 0;
+  target.compressedItems += manifest.compressedItems;
+  target.redactedSecrets += manifest.redactedSecrets;
+  target.warnings += manifest.warnings.length;
+}
+
+function addGroup<T extends MutableTotals & { latestAt?: string }>(target: T, manifest: AuditManifest): T {
+  add(target, manifest);
+  if (!target.latestAt || manifest.timestamp > target.latestAt) target.latestAt = manifest.timestamp;
+  return target;
+}
+
+function addStatus(status: StatusAccumulator, statusCode: number | undefined) {
+  const kind = statusKind(statusCode);
+  if (statusCode === undefined) {
+    status.unknown++;
+    bump(status.byCode, "unknown", "unknown");
+    bump(status.byClass, "unknown", "unknown");
+    return;
+  }
+  const code = String(statusCode);
+  const statusClass = kind === "unknown" && (statusCode < 100 || statusCode > 599) ? "unknown" : `${Math.floor(statusCode / 100)}xx`;
+  if (kind === "unknown") status.unknown++;
+  bump(status.byCode, code, code);
+  bump(status.byClass, statusClass, statusClass);
+}
+
+function bucketFor(map: Map<string, MutableBucket>, client: NonNullable<AuditManifest["client"]>): MutableBucket {
+  const id = client.keyId ? `key:${client.keyId}:project:${client.project ?? "none"}` : client.id;
+  const bucket = map.get(id) ?? { id, label: client.label, source: client.source, project: client.project, ...empty() };
+  bucket.project ??= client.project;
+  map.set(id, bucket);
+  return bucket;
+}
+
+function statusKind(statusCode: number | undefined): "ok" | "error" | "unknown" {
+  return !Number.isInteger(statusCode) ? "unknown" : statusCode >= 200 && statusCode <= 399 ? "ok" : statusCode >= 400 && statusCode <= 599 ? "error" : "unknown";
+}
+
+function breakdownFor(map: Map<string, MutableBreakdown>, id: string, label: string): MutableBreakdown {
+  const item = map.get(id) ?? { id, label, ...empty() };
+  map.set(id, item);
+  return item;
+}
+
+function finish<T extends MutableTotals>(totals: T): T & { savedPercent: number } {
+  return { ...totals, savedPercent: percent(totals.savedTokens, totals.originalTokens) };
+}
+
+function percent(part: number, total: number): number {
+  if (total <= 0 || part <= 0) return 0;
+  return Math.round((part / total) * 10000) / 100;
+}
+
+function sortGroups<T extends AuditSummaryTotals & { id: string }>(items: T[]): T[] {
+  return items.sort((a, b) => b.savedTokens - a.savedTokens || b.requests - a.requests || a.id.localeCompare(b.id));
+}
+
+function sortCounts(map: Map<string, AuditSummaryCount>): AuditSummaryCount[] {
+  return [...map.values()].sort((a, b) => b.count - a.count || a.id.localeCompare(b.id));
+}
+
+function bump(map: Map<string, AuditSummaryCount>, id: string, label: string) {
+  const item = map.get(id) ?? { id, label, count: 0 };
+  item.count++;
+  map.set(id, item);
+}
+
+function providerId(manifest: AuditManifest): string {
+  return manifest.providerId ? `provider:${manifest.providerId}` : `provider-host:${providerLabel(manifest)}`;
+}
+
+function providerLabel(manifest: AuditManifest): string { return manifest.providerId || manifest.targetHost || "unknown"; }
+
+function endpointId(manifest: AuditManifest): string { return `endpoint:${manifest.method}:${endpointPath(manifest.path)}`; }
+
+function endpointLabel(manifest: AuditManifest): string { return `${manifest.method} ${endpointPath(manifest.path)}`; }
+
+function endpointPath(path: string): string {
+  try { return new URL(path, "http://molenkopf.local").pathname || "/"; } catch { return "unknown"; }
+}

package/packages/core/src/manifest/usage-meter.ts

@@ -0,0 +1,105 @@
+export type UsageTotals = { inputTokens?: number; outputTokens?: number };
+
+const MAX_TOKEN_VALUE = 1_000_000_000;
+const MAX_BUFFER_CHARS = 2_000_000;
+
+export function createUsageMeter() {
+  let input: number | undefined;
+  let output: number | undefined;
+  let buffer = "";
+  let sseBuffer = "";
+  return {
+    feed(chunk: Buffer | string): void {
+      const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      buffer = trimBuffer(buffer + text);
+      sseBuffer += text;
+      sseBuffer = consumeSseEvents(sseBuffer, (event) => applyUsage(eventUsage(event)));
+    },
+    result(): UsageTotals {
+      applyUsage(jsonUsage(buffer));
+      return { inputTokens: input, outputTokens: output };
+    }
+  };
+
+  function applyUsage(usage: UsageTotals | undefined) {
+    input = maxToken(input, usage?.inputTokens);
+    output = maxToken(output, usage?.outputTokens);
+  }
+}
+
+function consumeSseEvents(text: string, onEvent: (event: SseEvent) => void): string {
+  let start = 0;
+  for (;;) {
+    const lf = text.indexOf("\n\n", start);
+    const crlf = text.indexOf("\r\n\r\n", start);
+    const end = lf === -1 ? crlf : crlf === -1 ? lf : Math.min(lf, crlf);
+    if (end === -1) break;
+    const raw = text.slice(start, end);
+    const event = parseSseEvent(raw);
+    if (event) onEvent(event);
+    start = end + (text.startsWith("\r\n\r\n", end) ? 4 : 2);
+  }
+  return trimBuffer(text.slice(start));
+}
+
+type SseEvent = { type?: string; data: unknown };
+
+function parseSseEvent(raw: string): SseEvent | undefined {
+  let type: string | undefined;
+  const data: string[] = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (line.startsWith("event:")) type = line.slice(6).trim();
+    if (line.startsWith("data:")) data.push(line.slice(5).trimStart());
+  }
+  const body = data.join("\n").trim();
+  if (!body || body === "[DONE]") return undefined;
+  try {
+    return { type, data: JSON.parse(body) };
+  } catch {
+    return undefined;
+  }
+}
+
+function eventUsage(event: SseEvent): UsageTotals | undefined {
+  if (!isRecord(event.data)) return undefined;
+  if (event.type === "message_start" && isRecord(event.data.message)) return usageObject(event.data.message.usage);
+  if (event.type === "message_delta") return usageObject(event.data.usage);
+  if (isRecord(event.data.response)) return usageObject(event.data.response.usage);
+  return usageObject(event.data.usage);
+}
+
+function jsonUsage(text: string): UsageTotals | undefined {
+  const trimmed = text.trim();
+  if (!trimmed || (trimmed[0] !== "{" && trimmed[0] !== "[")) return undefined;
+  try {
+    const parsed = JSON.parse(trimmed);
+    return isRecord(parsed) ? usageObject(parsed.usage) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function usageObject(value: unknown): UsageTotals | undefined {
+  if (!isRecord(value)) return undefined;
+  return {
+    inputTokens: token(value.input_tokens) ?? token(value.prompt_tokens),
+    outputTokens: token(value.output_tokens) ?? token(value.completion_tokens)
+  };
+}
+
+function token(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= MAX_TOKEN_VALUE ? value : undefined;
+}
+
+function maxToken(current: number | undefined, next: number | undefined): number | undefined {
+  if (next === undefined) return current;
+  return current === undefined || next > current ? next : current;
+}
+
+function trimBuffer(text: string): string {
+  return text.length > MAX_BUFFER_CHARS ? text.slice(-MAX_BUFFER_CHARS) : text;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/packages/core/src/memory/memory-extractor.ts

@@ -0,0 +1,57 @@
+import { shortHash } from "../utils/hash.ts";
+
+// Derives a small, safe set of memory concepts from the real transferred text:
+// file paths, code symbols, and error types. Only short derived tokens are kept
+// (never raw prompts). Callers must pass already-redacted text.
+
+export type ConceptKind = "file" | "symbol" | "error";
+export type Concept = { id: string; label: string; kind: ConceptKind };
+
+const FILE_RE = /\b[\w./-]{2,60}\.(?:ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb|json|sql|md|yml|yaml|toml|sh)\b/g;
+const SYMBOL_RE = /\b(?:function|class|interface|type|def|func|struct)\s+([A-Za-z_][A-Za-z0-9_]{2,40})/g;
+const ERROR_RE = /\b([A-Z][A-Za-z0-9_]*(?:Error|Exception))\b/g;
+
+const PER_KIND = 6;
+const MAX_CONCEPTS = 8;
+
+export function extractConcepts(text: string): Concept[] {
+  if (typeof text !== "string" || text.length < 3) return [];
+  const files = collect(text, FILE_RE, 0, "file");
+  const symbols = collect(text, SYMBOL_RE, 1, "symbol");
+  const errors = collect(text, ERROR_RE, 1, "error");
+  const merged: Concept[] = [];
+  const seen = new Set<string>();
+  for (const concept of [...errors, ...files, ...symbols]) {
+    if (seen.has(concept.id)) continue;
+    seen.add(concept.id);
+    merged.push(concept);
+    if (merged.length >= MAX_CONCEPTS) break;
+  }
+  return merged;
+}
+
+function collect(text: string, re: RegExp, group: number, kind: ConceptKind): Concept[] {
+  re.lastIndex = 0;
+  const out: Concept[] = [];
+  const seen = new Set<string>();
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(text)) !== null && out.length < PER_KIND) {
+    const raw = (match[group] ?? match[0]).trim();
+    const path = kind === "file" ? safePath(raw) : undefined;
+    const label = kind === "file" ? path?.split("/").pop() ?? "" : raw;
+    if (!label || label.length > 48 || /^[A-Za-z0-9_-]{24,}$/.test(label)) continue;
+    const id = kind === "file" ? `file:${path}` : `${kind}:${label}`;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push({ id, label, kind });
+  }
+  return out;
+}
+
+function safePath(value: string): string | undefined {
+  const normalized = value.replace(/\\/g, "/").split("/").filter((part) => part && part !== "." && part !== "..").join("/");
+  if (!normalized) return undefined;
+  if (normalized.length <= 96 && /^[\w./-]+$/.test(normalized)) return normalized;
+  const base = normalized.split("/").pop() ?? "file";
+  return `${base.slice(0, 40)}-${shortHash(normalized)}`;
+}

package/packages/core/src/memory/memory-graph.ts

@@ -0,0 +1,55 @@
+import type { Concept } from "./memory-extractor.ts";
+
+// A text-derived memory graph: concept nodes (files, symbols, errors) linked by
+// co-occurrence within the same agent request. Bounded so it stays a safe,
+// renderable summary, not an unbounded log of traffic.
+
+export type MemoryNode = { id: string; label: string; kind: string; count: number; lastSeen?: string };
+export type MemoryEdge = { from: string; to: string; count: number };
+export type MemoryGraph = { nodes: MemoryNode[]; edges: MemoryEdge[]; updatedAt?: string };
+
+const MAX_NODES = 120;
+const MAX_EDGES = 240;
+const MAX_COUNT = 99999;
+
+export function createMemoryGraph(): MemoryGraph {
+  return { nodes: [], edges: [] };
+}
+
+export function recordConcepts(graph: MemoryGraph, concepts: Concept[], timestamp?: string): MemoryGraph {
+  const upserted = concepts.filter((concept) => upsert(graph, concept, timestamp));
+  const nodeIds = new Set(graph.nodes.map((node) => node.id));
+  const present = upserted.filter((concept) => nodeIds.has(concept.id));
+  for (let i = 0; i < present.length; i++) {
+    for (let j = i + 1; j < present.length; j++) link(graph, present[i].id, present[j].id);
+  }
+  if (concepts.length) graph.updatedAt = timestamp ?? graph.updatedAt;
+  return graph;
+}
+
+function upsert(graph: MemoryGraph, concept: Concept, timestamp = graph.updatedAt): boolean {
+  const found = graph.nodes.find((node) => node.id === concept.id);
+  if (found) {
+    found.count = Math.min(MAX_COUNT, found.count + 1);
+    found.lastSeen = timestamp ?? found.lastSeen;
+    return true;
+  }
+  if (graph.nodes.length >= MAX_NODES) evictOne(graph);
+  if (graph.nodes.length >= MAX_NODES) return false;
+  graph.nodes.push({ id: concept.id, label: concept.label, kind: concept.kind, count: 1, lastSeen: timestamp });
+  return true;
+}
+
+function evictOne(graph: MemoryGraph) {
+  const candidate = [...graph.nodes].sort((a, b) => a.count - b.count || (a.lastSeen ?? "").localeCompare(b.lastSeen ?? "") || a.id.localeCompare(b.id))[0];
+  if (!candidate) return;
+  graph.nodes = graph.nodes.filter((node) => node.id !== candidate.id);
+  graph.edges = graph.edges.filter((edge) => edge.from !== candidate.id && edge.to !== candidate.id);
+}
+
+function link(graph: MemoryGraph, a: string, b: string) {
+  const [from, to] = a < b ? [a, b] : [b, a];
+  const found = graph.edges.find((edge) => edge.from === from && edge.to === to);
+  if (found) found.count = Math.min(MAX_COUNT, found.count + 1);
+  else if (graph.edges.length < MAX_EDGES) graph.edges.push({ from, to, count: 1 });
+}