#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
import { TriggerAction, type IIIClient } from "iii-sdk";
import type { CompressedObservation, Memory, Session } from "../types.js";
import { KV } from "../state/schema.js";
import { StateKV } from "../state/kv.js";
import { emitLiveEvent } from "../viewer/live-events.js";
import { isReflectEnabled } from "../functions/slots.js";
import {
detectLlmProviderKind,
getAgentId,
getConsolidationCooldownMs,
isAgentScopeIsolated,
isConsolidationEnabled,
} from "../config.js";
import { logger } from "../logger.js";
import { noteMemoryChange, noteSessionChange } from "../state/viewer-counts.js";
// Global marker recording when corpus consolidation last ran, used to debounce
// the per-turn session-stop fan-out.
const CONSOLIDATION_MARKER_KEY = "consolidation:lastRun";
async function consolidationDueUnserialized(kv: StateKV): Promise<boolean> {
const cooldownMs = getConsolidationCooldownMs();
if (cooldownMs <= 0) return true; // debounce disabled
const now = Date.now();
const marker = await kv
.get<{ at?: number }>(KV.config, CONSOLIDATION_MARKER_KEY)
.catch(() => null);
const lastAt = typeof marker?.at === "number" ? marker.at : 0;
if (now - lastAt < cooldownMs) return false;
await kv.set(KV.config, CONSOLIDATION_MARKER_KEY, { at: now }).catch(() => {});
return true;
}
// Concurrent session-stop events would otherwise interleave the marker
// read-check-write above and both pass the cooldown. Serialize the whole
// check through an in-process chain so exactly one concurrent caller wins.
let consolidationCheckChain: Promise<unknown> = Promise.resolve();
function consolidationDue(kv: StateKV): Promise<boolean> {
const result = consolidationCheckChain.then(() =>
consolidationDueUnserialized(kv),
);
consolidationCheckChain = result.catch(() => false);
return result;
}
export function registerEventTriggers(sdk: IIIClient, kv: StateKV): void {
sdk.registerFunction("event::session::stopped", async (data: { sessionId: string; skipConsolidation?: boolean }) => {
const summary = await sdk.trigger<typeof data, { unchanged?: boolean } | undefined>({
function_id: "mem::summarize",
payload: data,
});
if (summary?.unchanged === true) return summary;
const fireVoid = (function_id: string, payload: unknown) =>
sdk
.trigger({ function_id, payload, action: TriggerAction.Void() })
.catch((err) =>
logger.warn(function_id + " trigger failed", {
sessionId: data.sessionId,
error: err instanceof Error ? err.message : String(err),
}),
);
if (isReflectEnabled()) {
fireVoid("mem::slot-reflect", { sessionId: data.sessionId });
}
// Unconditional: mem::graph-extract gates its LLM pass internally.
try {
const observations = await kv.list<CompressedObservation>(
KV.observations(data.sessionId),
);
const compressed = observations.filter((o) => o.title);
if (compressed.length > 0) {
fireVoid("mem::graph-extract", { observations: compressed });
}
} catch (err) {
logger.warn("graph-extract trigger failed", {
sessionId: data.sessionId,
error: err instanceof Error ? err.message : String(err),
});
}
// Crystals + lessons consolidation. The stop lifecycle is the single
// source of truth: event::session::stopped fires for ALL agents (the
// client-side session-end hook no longer drives consolidation directly).
// Gated so keyless/zero-LLM users don't fire no-op LLM calls.
//
// skipConsolidation suppresses the fan-out when this handler is driven
// by eviction's stale-session recovery: evict calls session::stopped
// once per recovered session, then runs ONE final consolidation pass.
// Without this guard, N recovered sessions launch N concurrent forced
// full-corpus consolidations plus N crystallizations.
//
// Debounce: /session/end is posted by the per-turn Stop hook, so this
// handler fires on every agent turn. consolidate-pipeline + auto-crystallize
// are full-corpus LLM work with no internal "nothing changed" guard, so
// firing them every turn is a cost/latency storm for connected agents.
// Bound the global corpus consolidation to once per cooldown window.
if (isConsolidationEnabled() && !data.skipConsolidation) {
if (await consolidationDue(kv)) {
fireVoid("mem::consolidate-pipeline", { tier: "all", force: true });
fireVoid("mem::auto-crystallize", { olderThanDays: 0 });
if (detectLlmProviderKind() === "llm") {
fireVoid("mem::skill-extract", { sessionId: data.sessionId });
}
}
}
return summary;
});
// React to observation count changes and emit a lightweight live event for dashboards/viewer.
sdk.registerFunction(
"event::session::observation-count-changed",
async (payload: {
key: string;
event_type: string;
old_value?: Session;
new_value?: Session;
}) => {
noteSessionChange(payload.old_value, isStateDelete(payload) ? null : payload.new_value);
if (isOutOfAgentScope(payload.new_value ?? payload.old_value)) {
return { emitted: false };
}
if (isStateDelete(payload)) {
await sendViewerEvent(sdk, `session-deleted-${payload.key}-${Date.now()}`, "session.deleted", {
sessionId: payload.key,
});
return { emitted: true };
}
if (payload.new_value) {
await sendViewerEvent(sdk, `session-updated-${payload.key}-${Date.now()}`, "session.updated", {
session: payload.new_value,
});
}
const oldCount = payload.old_value?.observationCount ?? 0;
const newCount = payload.new_value?.observationCount ?? 0;
if (newCount <= oldCount) return { emitted: Boolean(payload.new_value) };
await sendViewerEvent(sdk, `session-activity-${payload.key}-${Date.now()}`, "session.activity", {
sessionId: payload.key,
observationCount: newCount,
delta: newCount - oldCount,
updatedAt: payload.new_value?.updatedAt ?? new Date().toISOString(),
});
return { emitted: true };
},
);
sdk.registerTrigger({
type: "state",
function_id: "event::session::observation-count-changed",
config: { scope: KV.sessions },
});
sdk.registerFunction(
"event::memory::changed",
async (payload: {
key: string;
event_type: string;
old_value?: Memory;
new_value?: Memory;
}) => {
const deleted = isStateDelete(payload);
noteMemoryChange(payload.old_value, deleted ? null : payload.new_value);
if (isOutOfAgentScope(payload.new_value ?? payload.old_value)) {
return { emitted: false };
}
const memory = payload.new_value;
const created = !deleted && !payload.old_value;
let type = "memory.updated";
if (deleted) type = "memory.deleted";
else if (created) type = "memory.created";
await sendViewerEvent(
sdk,
`${type.replace(".", "-")}-${payload.key}-${Date.now()}`,
type,
deleted
? { memoryId: payload.key, isLatest: payload.old_value?.isLatest }
: {
memoryId: payload.key,
type: memory?.type,
title: memory?.title,
isLatest: memory?.isLatest,
updatedAt: memory?.updatedAt,
memory,
},
);
return { emitted: true };
},
);
sdk.registerTrigger({
type: "state",
function_id: "event::memory::changed",
config: { scope: KV.memories },
});
}
export function isStateDelete(payload: { event_type: string; new_value?: unknown }): boolean {
return payload.event_type === "state:deleted" || !payload.new_value;
}
export function isOutOfAgentScope(record: { agentId?: string } | undefined): boolean {
return isAgentScopeIsolated() && record?.agentId !== getAgentId();
}
export async function sendViewerEvent(
_sdk: IIIClient,
id: string,
type: string,
data: Record<string, unknown>,
): Promise<void> {
emitLiveEvent({ id, type, data });
}