#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
import type { IIIClient } from "iii-sdk";
import type {
Memory,
SemanticMemory,
RetentionScore,
DecayConfig,
} from "../types.js";
import { KV } from "../state/schema.js";
import type { StateKV } from "../state/kv.js";
import type { AccessLog } from "./access-tracker.js";
import {
emptyAccessLog,
deleteAccessLog,
normalizeAccessLog,
} from "./access-tracker.js";
import { recordAudit, runAuditRetentionSweep } from "./audit.js";
import { deleteFacetsForTargets } from "./facets.js";
import { getSearchIndex, vectorIndexRemove, flushIndexSave } from "./search.js";
import { logger } from "../logger.js";
import { getAuditRetentionMonths } from "../config.js";
const DEFAULT_DECAY: DecayConfig = {
lambda: 0.01,
sigma: 0.3,
tierThresholds: {
hot: 0.7,
warm: 0.4,
cold: 0.15,
},
};
function resolveDecayConfig(
input?: Partial<DecayConfig>,
): { config: DecayConfig } | { error: string } {
const tierThresholds = {
...DEFAULT_DECAY.tierThresholds,
...(input?.tierThresholds ?? {}),
};
const config: DecayConfig = {
lambda:
typeof input?.lambda === "number" ? input.lambda : DEFAULT_DECAY.lambda,
sigma: typeof input?.sigma === "number" ? input.sigma : DEFAULT_DECAY.sigma,
tierThresholds,
};
if (!Number.isFinite(config.lambda) || config.lambda <= 0) {
return { error: "config.lambda must be a positive number" };
}
if (!Number.isFinite(config.sigma) || config.sigma < 0) {
return { error: "config.sigma must be a non-negative number" };
}
const { hot, warm, cold } = config.tierThresholds;
if (![hot, warm, cold].every((v) => Number.isFinite(v))) {
return {
error: "config.tierThresholds.hot/warm/cold must be finite numbers",
};
}
if (!(hot >= warm && warm >= cold && cold >= 0)) {
return {
error:
"config.tierThresholds must satisfy hot >= warm >= cold >= 0",
};
}
return { config };
}
function computeReinforcementBoost(
accessTimestamps: number[],
sigma: number,
): number {
const now = Date.now();
let boost = 0;
for (const tAccess of accessTimestamps) {
if (!Number.isFinite(tAccess)) continue;
const daysSinceAccess = (now - tAccess) / (1000 * 60 * 60 * 24);
if (daysSinceAccess > 0) {
boost += 1 / daysSinceAccess;
}
}
return boost * sigma;
}
function computeRetention(
salience: number,
createdAt: string,
accessTimestamps: number[],
config: DecayConfig,
): number {
const deltaT =
(Date.now() - new Date(createdAt).getTime()) / (1000 * 60 * 60 * 24);
const temporalDecay = Math.exp(-config.lambda * deltaT);
const reinforcementBoost = computeReinforcementBoost(
accessTimestamps,
config.sigma,
);
return Math.min(1, salience * temporalDecay + reinforcementBoost);
}
function computeSalience(
memory: Memory | SemanticMemory,
accessCount: number,
): number {
let baseSalience = 0.5;
if ("type" in memory) {
const typeWeights: Record<string, number> = {
architecture: 0.9,
bug: 0.7,
pattern: 0.8,
preference: 0.85,
workflow: 0.6,
fact: 0.5,
};
baseSalience = typeWeights[(memory as Memory).type] || 0.5;
}
if ("confidence" in memory) {
baseSalience = Math.max(baseSalience, (memory as SemanticMemory).confidence);
}
const accessBonus = Math.min(0.2, accessCount * 0.02);
return Math.min(1, baseSalience + accessBonus);
}
export function registerRetentionFunctions(
sdk: IIIClient,
kv: StateKV,
): void {
sdk.registerFunction("mem::retention-score",
async (data: { config?: Partial<DecayConfig> }) => {
const resolved = resolveDecayConfig(data?.config);
if ("error" in resolved) {
return { success: false, error: resolved.error };
}
const { config } = resolved;
const [memories, semanticMems, allLogs] = await Promise.all([
kv.list<Memory>(KV.memories),
kv.list<SemanticMemory>(KV.semantic),
kv.list<unknown>(KV.accessLog).catch(() => [] as unknown[]),
]);
const logsById = new Map<string, AccessLog>();
for (const raw of allLogs) {
const log = normalizeAccessLog(raw);
if (log.memoryId) logsById.set(log.memoryId, log);
}
const scores: RetentionScore[] = [];
const computeDecay = (createdAt: string): number =>
Math.exp(
-config.lambda *
((Date.now() - new Date(createdAt).getTime()) /
(1000 * 60 * 60 * 24)),
);
// Build all entries in memory first, then flush with Promise.all
// so a full rescore is one batched KV write instead of N sequential
// round-trips. Separate counts for the audit record at the end.
const pendingWrites: Array<[string, RetentionScore]> = [];
let episodicScored = 0;
let semanticScored = 0;
for (const mem of memories) {
if (!mem.isLatest) continue;
const log = logsById.get(mem.id) ?? emptyAccessLog(mem.id);
const salience = computeSalience(mem, log.count);
const temporalDecay = computeDecay(mem.createdAt);
const reinforcementBoost = computeReinforcementBoost(
log.recent,
config.sigma,
);
const score = Math.min(
1,
salience * temporalDecay + reinforcementBoost,
);
const entry: RetentionScore = {
memoryId: mem.id,
source: "episodic",
score,
salience,
temporalDecay,
reinforcementBoost,
lastAccessed: log.lastAt || mem.updatedAt,
accessCount: log.count,
};
scores.push(entry);
pendingWrites.push([mem.id, entry]);
episodicScored++;
}
for (const sem of semanticMems) {
const log = logsById.get(sem.id) ?? emptyAccessLog(sem.id);
// Pre-0.8.3 fallback: use sem.lastAccessedAt only when mem:access is empty.
let accessTimestamps: number[];
let effectiveCount: number;
if (log.recent.length > 0 || log.count > 0) {
accessTimestamps = log.recent;
effectiveCount = log.count;
} else if (sem.lastAccessedAt) {
const legacyTs = Date.parse(sem.lastAccessedAt);
accessTimestamps = Number.isFinite(legacyTs) ? [legacyTs] : [];
effectiveCount = sem.accessCount;
} else {
accessTimestamps = [];
effectiveCount = sem.accessCount;
}
const salience = computeSalience(sem, effectiveCount);
const temporalDecay = computeDecay(sem.createdAt);
const reinforcementBoost = computeReinforcementBoost(
accessTimestamps,
config.sigma,
);
const score = Math.min(
1,
salience * temporalDecay + reinforcementBoost,
);
const entry: RetentionScore = {
memoryId: sem.id,
source: "semantic",
score,
salience,
temporalDecay,
reinforcementBoost,
lastAccessed: log.lastAt || sem.lastAccessedAt,
accessCount: effectiveCount,
};
scores.push(entry);
pendingWrites.push([sem.id, entry]);
semanticScored++;
}
// Flush all retention rows in parallel. N sequential writes was
// making full rescores O(n) round-trips on stores with 1000+
// memories; batching drops that to O(1) wall time on the KV
// backends that can pipeline.
await Promise.all(
pendingWrites.map(([id, entry]) =>
kv.set(KV.retentionScores, id, entry),
),
);
scores.sort((a, b) => b.score - a.score);
const tiers = {
hot: scores.filter((s) => s.score >= config.tierThresholds.hot)
.length,
warm: scores.filter(
(s) =>
s.score >= config.tierThresholds.warm &&
s.score < config.tierThresholds.hot,
).length,
cold: scores.filter(
(s) =>
s.score >= config.tierThresholds.cold &&
s.score < config.tierThresholds.warm,
).length,
evictable: scores.filter(
(s) => s.score < config.tierThresholds.cold,
).length,
};
logger.info("Retention scores computed", {
total: scores.length,
...tiers,
});
// Audit the rescore as a single batched event per sweep. We
// intentionally pass an empty targetIds array — a mature store
// can have 1000+ memory ids per rescore and flooding the audit
// log with every memoryId on every cron tick is worse than
// recording just the summary. The details payload has enough
// context for observability (counts per source + per tier).
if (scores.length > 0) {
await recordAudit(kv, "retention_score", "mem::retention-score", [], {
total: scores.length,
episodic: episodicScored,
semantic: semanticScored,
tiers,
config,
});
}
return { success: true, total: scores.length, tiers, scores };
},
);
sdk.registerFunction("mem::retention-evict",
async (data?: {
threshold?: number;
dryRun?: boolean;
maxEvict?: number;
}) => {
const threshold =
typeof data?.threshold === "number" && Number.isFinite(data.threshold)
? data.threshold
: DEFAULT_DECAY.tierThresholds.cold;
const maxEvictRaw =
typeof data?.maxEvict === "number" && Number.isInteger(data.maxEvict)
? data.maxEvict
: 50;
const maxEvict = Math.min(1000, Math.max(0, maxEvictRaw));
const { decrementImageRef } = await import("./image-refs.js");
const allScores = await kv.list<RetentionScore>(KV.retentionScores);
const candidates = allScores
.filter((s) => s.score < threshold)
.sort((a, b) => a.score - b.score)
.slice(0, maxEvict);
if (data?.dryRun) {
return {
success: true,
dryRun: true,
wouldEvict: candidates.length,
candidates: candidates.map((c) => ({
id: c.memoryId,
score: c.score,
})),
};
}
let evicted = 0;
let evictedEpisodic = 0;
let evictedSemantic = 0;
const evictedIds: string[] = [];
const missingIds: string[] = [];
for (const candidate of candidates) {
try {
let scope: string | null = null;
let resolvedSource: "episodic" | "semantic" | null = null;
let mem: Memory | null = null;
if (candidate.source === "semantic") {
mem = await kv.get<Memory>(KV.semantic, candidate.memoryId);
if (mem) {
scope = KV.semantic;
resolvedSource = "semantic";
}
} else if (candidate.source === "episodic") {
mem = await kv.get<Memory>(KV.memories, candidate.memoryId);
if (mem) {
scope = KV.memories;
resolvedSource = "episodic";
}
}
if (!mem && !candidate.source) {
mem = await kv.get<Memory>(KV.memories, candidate.memoryId);
if (mem) {
scope = KV.memories;
resolvedSource = "episodic";
} else {
mem = await kv.get<Memory>(KV.semantic, candidate.memoryId);
if (mem) {
scope = KV.semantic;
resolvedSource = "semantic";
}
}
}
if (!scope || !mem) {
if (candidate.source) {
const other =
candidate.source === "semantic" ? KV.memories : KV.semantic;
if (await kv.get(other, candidate.memoryId)) continue;
}
missingIds.push(candidate.memoryId);
continue;
}
if (mem.imageRef) {
await decrementImageRef(kv, sdk, mem.imageRef);
}
await kv.delete(scope, candidate.memoryId);
evictedIds.push(candidate.memoryId);
evicted++;
if (resolvedSource === "semantic") evictedSemantic++;
else evictedEpisodic++;
await kv.delete(KV.retentionScores, candidate.memoryId);
await deleteAccessLog(kv, candidate.memoryId);
getSearchIndex().remove(candidate.memoryId);
vectorIndexRemove(candidate.memoryId);
} catch {
continue;
}
}
await deleteFacetsForTargets(kv, [...evictedIds, ...missingIds]);
// Retention eviction is a structural delete path that removes
// memories, retention scores, and access logs, so it needs to
// emit an audit record per the repo's audit-coverage policy (see
// mem::governance-delete for the reference pattern). Batched,
// one record per invocation — per-candidate audits would flood
// the audit log during normal eviction sweeps.
if (evicted > 0) {
await flushIndexSave();
await recordAudit(kv, "delete", "mem::retention-evict", evictedIds, {
threshold,
evicted,
evictedEpisodic,
evictedSemantic,
reason: "retention score below threshold",
});
}
logger.info("Retention-based eviction complete", {
evicted,
evictedEpisodic,
evictedSemantic,
threshold,
});
return { success: true, evicted, evictedEpisodic, evictedSemantic };
},
);
sdk.registerFunction("mem::audit-retention-sweep",
async (data?: { retentionMonths?: number }) => {
const retentionMonths =
typeof data?.retentionMonths === "number" &&
Number.isFinite(data.retentionMonths)
? data.retentionMonths
: getAuditRetentionMonths();
const result = await runAuditRetentionSweep(kv, retentionMonths);
if (result.droppedRows > 0) {
logger.info("Audit retention sweep dropped old month scopes", result);
}
return { success: true, ...result };
},
);
}