#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
import { TriggerAction, type IIIClient } from "iii-sdk";
import type { Memory, MemoryRelation } from "../types.js";
import { memoryToObservation } from "../state/memory-utils.js";
import { memoryTitleFromContent } from "./remember.js";
import {
getSearchIndex,
scheduleIndexSave,
vectorIndexAddGuarded,
vectorIndexRemove,
} from "./search.js";
import { KV, generateId } from "../state/schema.js";
import { StateKV } from "../state/kv.js";
import { withKeyedLock } from "../state/keyed-mutex.js";
import { safeAudit } from "./audit.js";
import { recordAccessBatch } from "./access-tracker.js";
import { logger } from "../logger.js";
const MEMORY_TYPES = new Set([
"pattern",
"preference",
"architecture",
"bug",
"workflow",
"fact",
]);
function computeConfidence(
source: Memory,
target: Memory,
relationType: MemoryRelation["type"],
): number {
let score = 0.5;
const sharedSessions = source.sessionIds.filter((sid) =>
target.sessionIds.includes(sid),
);
score += Math.min(sharedSessions.length * 0.1, 0.3);
const now = Date.now();
const sourceAge = now - new Date(source.updatedAt).getTime();
const targetAge = now - new Date(target.updatedAt).getTime();
const sevenDays = 7 * 24 * 60 * 60 * 1000;
const ninetyDays = 90 * 24 * 60 * 60 * 1000;
if (sourceAge < sevenDays && targetAge < sevenDays) {
score += 0.1;
} else if (sourceAge > ninetyDays && targetAge > ninetyDays) {
score -= 0.1;
}
if (relationType === "supersedes") score += 0.1;
if (relationType === "contradicts") score -= 0.05;
return Math.max(0, Math.min(1, score));
}
export function registerRelationsFunction(sdk: IIIClient, kv: StateKV): void {
sdk.registerFunction("mem::relate",
async (data: {
sourceId: string;
targetId: string;
type: MemoryRelation["type"];
confidence?: number;
}) => {
const [firstId, secondId] = [data.sourceId, data.targetId].sort();
const lockKey =
firstId === secondId ? `mem:${firstId}` : `mem:${firstId}:${secondId}`;
return withKeyedLock(lockKey, async () => {
const source = await kv.get<Memory>(KV.memories, data.sourceId);
const target = await kv.get<Memory>(KV.memories, data.targetId);
if (!source || !target) {
return {
success: false,
error: "source or target memory not found",
};
}
const confidence =
data.confidence !== undefined
? Math.max(0, Math.min(1, data.confidence))
: computeConfidence(source, target, data.type);
const relation: MemoryRelation = {
type: data.type,
sourceId: data.sourceId,
targetId: data.targetId,
createdAt: new Date().toISOString(),
confidence,
};
const relationId = generateId("rel");
await kv.set(KV.relations, relationId, relation);
if (!source.relatedIds) source.relatedIds = [];
let sourceUpdated = false;
if (!source.relatedIds.includes(data.targetId)) {
source.relatedIds.push(data.targetId);
await kv.set(KV.memories, data.sourceId, source);
sourceUpdated = true;
}
if (!target.relatedIds) target.relatedIds = [];
let targetUpdated = false;
if (!target.relatedIds.includes(data.sourceId)) {
target.relatedIds.push(data.sourceId);
await kv.set(KV.memories, data.targetId, target);
targetUpdated = true;
}
await safeAudit(kv, "relation_create", "mem::relate", [relationId], {
type: data.type,
sourceId: data.sourceId,
targetId: data.targetId,
confidence,
});
if (sourceUpdated) {
await safeAudit(
kv,
"relation_update",
"mem::relate",
[data.sourceId],
{ relationId, updatedRelatedId: data.targetId },
);
}
if (targetUpdated) {
await safeAudit(
kv,
"relation_update",
"mem::relate",
[data.targetId],
{ relationId, updatedRelatedId: data.sourceId },
);
}
logger.info("Memory relation created", {
relationId,
type: data.type,
source: data.sourceId,
target: data.targetId,
});
return { success: true, relationId, relation };
});
},
);
sdk.registerFunction("mem::evolve",
async (data: {
memoryId: string;
newContent: string;
newTitle?: string;
newType?: string;
}) => {
if (
!data?.memoryId ||
typeof data.newContent !== "string" ||
!data.newContent.trim()
) {
return { success: false, error: "memoryId and newContent are required" };
}
if (data.newType !== undefined && !MEMORY_TYPES.has(data.newType)) {
return { success: false, error: `invalid type: ${data.newType}` };
}
return withKeyedLock("mem:remember", async () => {
const existing = await kv.get<Memory>(KV.memories, data.memoryId);
if (!existing) {
return { success: false, error: "memory not found", code: "not_found" };
}
if (existing.isLatest === false) {
return {
success: false,
error: "memory is not the latest version; edit the latest version instead",
code: "not_latest",
};
}
const newType = (data.newType ?? existing.type) as Memory["type"];
if (
data.newContent === existing.content &&
newType === existing.type &&
(!data.newTitle || data.newTitle === existing.title)
) {
return { success: false, error: "nothing changed", code: "unchanged" };
}
const titleWasDerived =
existing.title === memoryTitleFromContent(existing.content);
const now = new Date().toISOString();
const evolved: Memory = {
...existing,
id: generateId("mem"),
createdAt: now,
updatedAt: now,
type: newType,
title:
data.newTitle ||
(titleWasDerived ? memoryTitleFromContent(data.newContent) : existing.title),
content: data.newContent,
version: (existing.version || 1) + 1,
parentId: existing.id,
supersedes: [existing.id, ...(existing.supersedes || [])],
isLatest: true,
};
existing.isLatest = false;
await kv.set(KV.memories, existing.id, existing);
try {
getSearchIndex().remove(existing.id);
} catch {}
vectorIndexRemove(existing.id);
await safeAudit(kv, "evolve", "mem::evolve", [existing.id], {
operation: "evolve",
action: "mark_non_latest",
newId: evolved.id,
});
await kv.set(KV.memories, evolved.id, evolved);
try {
getSearchIndex().add(memoryToObservation(evolved), "memory");
scheduleIndexSave();
} catch (err) {
logger.warn("Failed to index evolved memory into BM25", {
memId: evolved.id,
error: err instanceof Error ? err.message : String(err),
});
}
await vectorIndexAddGuarded(
evolved.id,
evolved.sessionIds?.[0] ?? "memory",
evolved.title + " " + evolved.content,
{ kind: "memory", logId: evolved.id },
);
await safeAudit(kv, "evolve", "mem::evolve", [evolved.id], {
operation: "evolve",
oldId: existing.id,
newId: evolved.id,
version: evolved.version,
});
const relation: MemoryRelation = {
type: "supersedes",
sourceId: evolved.id,
targetId: existing.id,
createdAt: now,
confidence: 1.0,
};
const relationId = generateId("rel");
await kv.set(KV.relations, relationId, relation);
await safeAudit(kv, "evolve", "mem::evolve", [relationId], {
operation: "supersedes",
oldId: existing.id,
newId: evolved.id,
});
logger.info("Memory evolved", {
oldId: existing.id,
newId: evolved.id,
version: evolved.version,
});
await sdk
.trigger({
function_id: "mem::cascade-update",
payload: { supersededMemoryId: existing.id },
action: TriggerAction.Void(),
})
.catch(() => {});
return { success: true, memory: evolved, previousId: existing.id };
});
},
);
sdk.registerFunction("mem::get-related",
async (data: {
memoryId: string;
maxHops?: number;
minConfidence?: number;
}) => {
const maxHops = Math.min(data.maxHops ?? 2, 5);
const MAX_VISITED = 500;
const rawMinConf = Number(data.minConfidence);
const minConfidence = Number.isFinite(rawMinConf)
? Math.max(0, Math.min(1, rawMinConf))
: 0;
const allRelations = await kv
.list<MemoryRelation>(KV.relations)
.catch(() => []);
const visited = new Set<string>();
const result: Array<{
memory: Memory;
hop: number;
confidence: number;
}> = [];
const queue: Array<{ id: string; hop: number }> = [
{ id: data.memoryId, hop: 0 },
];
while (queue.length > 0 && visited.size < MAX_VISITED) {
const current = queue.shift()!;
if (visited.has(current.id) || current.hop > maxHops) continue;
visited.add(current.id);
const memory = await kv.get<Memory>(KV.memories, current.id);
if (!memory) continue;
if (current.hop > 0) {
const matchingRelations = allRelations.filter(
(r) =>
(r.sourceId === current.id && visited.has(r.targetId)) ||
(r.targetId === current.id && visited.has(r.sourceId)),
);
const confidence =
matchingRelations.length > 0
? Math.max(...matchingRelations.map((r) => r.confidence ?? 0.5))
: 0.5;
if (confidence >= minConfidence) {
result.push({ memory, hop: current.hop, confidence });
}
}
const relatedIds = memory.relatedIds || [];
const supersedes = memory.supersedes || [];
const parentId = memory.parentId ? [memory.parentId] : [];
const kvLinked = allRelations
.filter((r) => r.sourceId === current.id || r.targetId === current.id)
.map((r) => (r.sourceId === current.id ? r.targetId : r.sourceId));
const allLinks = [
...new Set([...relatedIds, ...supersedes, ...parentId, ...kvLinked]),
];
for (const nextId of allLinks) {
if (!visited.has(nextId)) {
queue.push({ id: nextId, hop: current.hop + 1 });
}
}
}
result.sort((a, b) => b.confidence - a.confidence);
void recordAccessBatch(
kv,
result.map((r) => r.memory.id),
);
logger.info("Related memories retrieved", {
memoryId: data.memoryId,
found: result.length,
});
return { results: result };
},
);
}