@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/memory/proposal.ts

@@ -0,0 +1,180 @@
+import { createHash } from "node:crypto";
+import type { EvidenceFinding, EvidenceOverview, EvidenceTag } from "../evidence/index.js";
+import { inspectEvidence } from "../evidence/index.js";
+import { canonicalMemoryRepositoryIdentity } from "./operations.js";
+import { loadMemoryRecords, upsertMemoryRecord } from "./store.js";
+import type { MemoryProposalResult, MemoryRecord, MemoryRepositoryIdentity, MemoryScope } from "./types.js";
+
+const LESSON_MAX_CHARS = 240;
+const APPLY_MAX_CHARS = 160;
+
+const TAG_PRIORITY = [
+	"test-failure",
+	"build-failure",
+	"blocked-tool",
+	"protected-artifact",
+	"timeout",
+	"context-overflow",
+	"missing-dependency",
+	"wrong-runtime",
+	"auth-failure",
+	"cwd-missing",
+	"destructive-cleanup",
+	"unknown",
+] as const satisfies ReadonlyArray<EvidenceTag>;
+
+export async function proposeMemoryFromEvidence(dataDir: string, evidenceId: string): Promise<MemoryProposalResult> {
+	const evidence = await inspectEvidence(dataDir, evidenceId);
+	const existing = (await loadMemoryRecords(dataDir)).find((record) => record.id === memoryIdFromEvidence(evidenceId));
+	if (existing !== undefined) return { record: existing, created: false };
+
+	const record = memoryRecordFromEvidence(evidence.overview, evidence.findings);
+	await upsertMemoryRecord(dataDir, record);
+	return { record, created: true };
+}
+
+export function memoryIdFromEvidence(evidenceId: string): string {
+	const digest = createHash("sha256").update(evidenceId, "utf8").digest("hex").slice(0, 16);
+	return `mem-${digest}`;
+}
+
+export function memoryRecordFromEvidence(
+	overview: EvidenceOverview,
+	findings: ReadonlyArray<EvidenceFinding>,
+): MemoryRecord {
+	const tags = overview.tags;
+	const primaryTag = primaryEvidenceTag(tags);
+	const repository = inferRepository(overview);
+	const scope = inferScope(overview, repository);
+	const record: MemoryRecord = {
+		id: memoryIdFromEvidence(overview.evidenceId),
+		scope,
+		key: `evidence:${overview.evidenceId}`,
+		lesson: truncateText(buildLesson(overview, findings, primaryTag), LESSON_MAX_CHARS),
+		evidenceRefs: [overview.evidenceId],
+		appliesWhen: appliesWhen(overview),
+		avoidWhen: avoidWhen(overview),
+		confidence: confidenceForEvidence(overview, findings),
+		createdAt: overview.generatedAt,
+		approved: false,
+	};
+	if (scope === "repo" && repository !== null) record.repository = repository;
+	return record;
+}
+
+/**
+ * Repo scope requires exactly one evidence cwd that canonicalizes to a usable
+ * repository identity; anything else is ambiguous and falls through to the
+ * next scope.
+ */
+function inferRepository(overview: EvidenceOverview): MemoryRepositoryIdentity | null {
+	const cwds = [...new Set(overview.cwds)];
+	if (cwds.length !== 1 || cwds[0] === undefined) return null;
+	return canonicalMemoryRepositoryIdentity(cwds[0]);
+}
+
+function inferScope(overview: EvidenceOverview, repository: MemoryRepositoryIdentity | null): MemoryScope {
+	if (overview.source.kind === "eval") return "task-family";
+	if (repository !== null) return "repo";
+	if (overview.runtimeIds.length > 0) return "runtime";
+	if (overview.agentIds.length > 0) return "agent";
+	return "global";
+}
+
+function primaryEvidenceTag(tags: ReadonlyArray<EvidenceTag>): EvidenceTag | null {
+	for (const tag of TAG_PRIORITY) {
+		if (tags.includes(tag)) return tag;
+	}
+	return tags[0] ?? null;
+}
+
+function buildLesson(
+	overview: EvidenceOverview,
+	findings: ReadonlyArray<EvidenceFinding>,
+	primaryTag: EvidenceTag | null,
+): string {
+	const task = overview.tasks[0] ?? "the cited workflow";
+	const finding = findings.find((item) => item.severity === "warn") ?? findings[0] ?? null;
+	const findingText = finding === null ? "" : ` Finding: ${finding.message}`;
+	if (primaryTag === "test-failure") {
+		return `Evidence ${overview.evidenceId} shows validation failure around "${task}". Recheck the failing validation path before claiming completion.${findingText}`;
+	}
+	if (primaryTag === "build-failure") {
+		return `Evidence ${overview.evidenceId} shows build failure around "${task}". Rebuild before treating related changes as complete.${findingText}`;
+	}
+	if (primaryTag === "blocked-tool") {
+		return `Evidence ${overview.evidenceId} shows blocked tool activity around "${task}". Adjust the workflow to respect tool and safety policy.${findingText}`;
+	}
+	if (primaryTag === "protected-artifact") {
+		return `Evidence ${overview.evidenceId} includes protected artifacts for "${task}". Preserve validated artifacts unless newer validation supersedes them.${findingText}`;
+	}
+	if (primaryTag === "timeout") {
+		return `Evidence ${overview.evidenceId} shows timeout risk around "${task}". Prefer bounded validation steps and explicit limits.${findingText}`;
+	}
+	if (primaryTag === "context-overflow") {
+		return `Evidence ${overview.evidenceId} shows context pressure around "${task}". Prefer scoped retrieval or compaction over prompt growth.${findingText}`;
+	}
+	if (primaryTag === "missing-dependency") {
+		return `Evidence ${overview.evidenceId} shows a missing dependency around "${task}". Verify local prerequisites before rerunning the workflow.${findingText}`;
+	}
+	if (primaryTag === "wrong-runtime") {
+		return `Evidence ${overview.evidenceId} shows runtime mismatch around "${task}". Confirm the configured runtime and model before dispatch.${findingText}`;
+	}
+	if (primaryTag === "auth-failure") {
+		return `Evidence ${overview.evidenceId} shows auth failure around "${task}". Check target credentials before repeating the workflow.${findingText}`;
+	}
+	if (primaryTag === "cwd-missing") {
+		return `Evidence ${overview.evidenceId} shows missing working-directory state around "${task}". Confirm repo-local cwd paths before running commands.${findingText}`;
+	}
+	if (primaryTag === "destructive-cleanup") {
+		return `Evidence ${overview.evidenceId} shows destructive cleanup risk around "${task}". Keep validated artifacts protected until replacement validation exists.${findingText}`;
+	}
+	const tagText = overview.tags.length === 0 ? "no failure tags" : `tags ${overview.tags.join(", ")}`;
+	return `Evidence ${overview.evidenceId} records ${tagText} for "${task}". Keep this as memory only after human approval.${findingText}`;
+}
+
+function appliesWhen(overview: EvidenceOverview): string[] {
+	return uniqueStrings([
+		`source:${formatSource(overview)}`,
+		...overview.tasks.map((task) => `task:${truncateText(task, APPLY_MAX_CHARS)}`),
+		...overview.cwds.map((cwd) => `cwd:${truncateText(cwd, APPLY_MAX_CHARS)}`),
+		...overview.tags.map((tag) => `tag:${tag}`),
+		...overview.runtimeIds.map((runtimeId) => `runtime:${runtimeId}`),
+		...overview.modelIds.map((modelId) => `model:${modelId}`),
+	]);
+}
+
+function avoidWhen(overview: EvidenceOverview): string[] {
+	if (overview.cwds.length === 0 && overview.runtimeIds.length === 0 && overview.tags.length === 0) return [];
+	return ["current task, repo, runtime, or failure mode differs from cited evidence"];
+}
+
+function confidenceForEvidence(overview: EvidenceOverview, findings: ReadonlyArray<EvidenceFinding>): number {
+	let value = 0.45;
+	if (overview.totals.runs > 0) value += 0.05;
+	if (overview.totals.receipts > 0 || overview.source.kind === "eval") value += 0.05;
+	if (overview.tags.length > 0) value += 0.05;
+	if (findings.some((finding) => finding.severity === "warn")) value += 0.05;
+	if (overview.totals.linkedToolEvents > 0 || overview.totals.toolEvents > 0) value += 0.05;
+	return Math.min(0.75, Number(value.toFixed(2)));
+}
+
+function formatSource(overview: EvidenceOverview): string {
+	if (overview.source.kind === "run") return `run:${overview.source.runId}`;
+	if (overview.source.kind === "session") return `session:${overview.source.sessionId}`;
+	return `eval:${overview.source.evalId}`;
+}
+
+function truncateText(value: string, maxChars: number): string {
+	if (value.length <= maxChars) return value;
+	if (maxChars <= 3) return value.slice(0, maxChars);
+	return `${value.slice(0, maxChars - 3)}...`;
+}
+
+function uniqueStrings(values: ReadonlyArray<string>): string[] {
+	return [...new Set(values.filter((value) => value.length > 0))].sort(compareStrings);
+}
+
+function compareStrings(a: string, b: string): number {
+	return a.localeCompare(b);
+}

package/src/domains/memory/store.ts

@@ -0,0 +1,163 @@
+import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { safeResourceWrite } from "../../core/safe-resource-write.js";
+import { MEMORY_VERSION, type MemoryRecord, type MemoryStatus, type MemoryStoreFile } from "./types.js";
+import { validateMemoryStore } from "./validate.js";
+
+export const MEMORY_STORE_MAX_RECORDS = 500;
+export const MEMORY_STALE_APPROVED_DAYS = 180;
+export const MEMORY_STALE_UNAPPROVED_DAYS = 30;
+
+export function memoryRoot(dataDir: string): string {
+	return join(dataDir, "memory");
+}
+
+export function memoryStorePath(dataDir: string): string {
+	return join(memoryRoot(dataDir), "records.json");
+}
+
+export async function loadMemoryRecords(dataDir: string): Promise<MemoryRecord[]> {
+	let raw: string;
+	try {
+		raw = await readFile(memoryStorePath(dataDir), "utf8");
+	} catch (error) {
+		if (isErrorWithCode(error) && error.code === "ENOENT") return [];
+		throw error;
+	}
+	return parseAndValidate(raw, memoryStorePath(dataDir));
+}
+
+/**
+ * Synchronous variant for hot prompt-build paths. Reads the local memory
+ * store file each call. The store is bounded at MEMORY_STORE_MAX_RECORDS and
+ * lives on local disk, so the sync read is cheap and avoids forcing every
+ * prompt compile site to thread an async boundary through the chat loop.
+ */
+export function loadMemoryRecordsSync(dataDir: string): MemoryRecord[] {
+	let raw: string;
+	try {
+		raw = readFileSync(memoryStorePath(dataDir), "utf8");
+	} catch (error) {
+		if (isErrorWithCode(error) && error.code === "ENOENT") return [];
+		throw error;
+	}
+	return parseAndValidate(raw, memoryStorePath(dataDir));
+}
+
+function parseAndValidate(raw: string, source: string): MemoryRecord[] {
+	const parsed = parseJson(raw, source);
+	const result = validateMemoryStore(parsed, "$");
+	if (!result.valid) {
+		throw new Error(
+			`memory store invalid: ${result.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`,
+		);
+	}
+	return sortMemoryRecords(result.store.records);
+}
+
+export async function writeMemoryRecords(dataDir: string, records: ReadonlyArray<MemoryRecord>): Promise<string> {
+	const sorted = sortMemoryRecords(records);
+	if (sorted.length > MEMORY_STORE_MAX_RECORDS) {
+		throw new Error(`memory store limit reached (${MEMORY_STORE_MAX_RECORDS}); run clio-coder memory prune --stale`);
+	}
+	const store: MemoryStoreFile = { version: MEMORY_VERSION, records: sorted };
+	const path = memoryStorePath(dataDir);
+	safeResourceWrite(path, `${JSON.stringify(store, null, 2)}\n`, { encoding: "utf8" });
+	return path;
+}
+
+export async function upsertMemoryRecord(dataDir: string, record: MemoryRecord): Promise<MemoryRecord> {
+	const records = await loadMemoryRecords(dataDir);
+	const existingIndex = records.findIndex((item) => item.id === record.id);
+	const next = existingIndex === -1 ? [...records, record] : replaceAt(records, existingIndex, record);
+	await writeMemoryRecords(dataDir, next);
+	return record;
+}
+
+export async function updateMemoryRecord(
+	dataDir: string,
+	memoryId: string,
+	update: (record: MemoryRecord) => MemoryRecord,
+): Promise<MemoryRecord> {
+	const records = await loadMemoryRecords(dataDir);
+	const index = records.findIndex((record) => record.id === memoryId);
+	if (index === -1) throw new Error(`memory record not found: ${memoryId}`);
+	const current = records[index];
+	if (current === undefined) throw new Error(`memory record not found: ${memoryId}`);
+	const updated = update(current);
+	await writeMemoryRecords(dataDir, replaceAt(records, index, updated));
+	return updated;
+}
+
+export async function pruneStaleMemoryRecords(dataDir: string, now: Date = new Date()): Promise<MemoryRecord[]> {
+	const records = await loadMemoryRecords(dataDir);
+	const kept = records.filter((record) => !isStaleMemoryRecord(record, now));
+	const pruned = records.filter((record) => isStaleMemoryRecord(record, now));
+	await writeMemoryRecords(dataDir, kept);
+	return pruned;
+}
+
+function isStaleMemoryRecord(record: MemoryRecord, now: Date): boolean {
+	const reference = record.lastVerifiedAt ?? record.createdAt;
+	const referenceMs = Date.parse(reference);
+	if (!Number.isFinite(referenceMs)) return true;
+	const staleAfterDays = record.approved ? MEMORY_STALE_APPROVED_DAYS : MEMORY_STALE_UNAPPROVED_DAYS;
+	return now.getTime() - referenceMs > staleAfterDays * 24 * 60 * 60 * 1000;
+}
+
+export function memoryStatus(record: MemoryRecord): MemoryStatus {
+	if (record.approved) return "approved";
+	if (record.rejectedAt !== undefined) return "rejected";
+	return "proposed";
+}
+
+export function sortMemoryRecords(records: ReadonlyArray<MemoryRecord>): MemoryRecord[] {
+	return [...records].sort(compareMemoryRecords);
+}
+
+function compareMemoryRecords(left: MemoryRecord, right: MemoryRecord): number {
+	const byScope = scopeRank(left.scope) - scopeRank(right.scope);
+	if (byScope !== 0) return byScope;
+	const byKey = left.key.localeCompare(right.key);
+	if (byKey !== 0) return byKey;
+	const byCreated = left.createdAt.localeCompare(right.createdAt);
+	if (byCreated !== 0) return byCreated;
+	return left.id.localeCompare(right.id);
+}
+
+function replaceAt(records: ReadonlyArray<MemoryRecord>, index: number, record: MemoryRecord): MemoryRecord[] {
+	return records.map((item, itemIndex) => (itemIndex === index ? record : item));
+}
+
+function scopeRank(scope: MemoryRecord["scope"]): number {
+	switch (scope) {
+		case "global":
+			return 0;
+		case "repo":
+			return 1;
+		case "language":
+			return 2;
+		case "runtime":
+			return 3;
+		case "agent":
+			return 4;
+		case "task-family":
+			return 5;
+		case "hpc-domain":
+			return 6;
+	}
+}
+
+function parseJson(raw: string, source: string): unknown {
+	try {
+		return JSON.parse(raw) as unknown;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`${source}: invalid JSON: ${message}`);
+	}
+}
+
+function isErrorWithCode(error: unknown): error is NodeJS.ErrnoException {
+	return typeof error === "object" && error !== null && "code" in error;
+}

package/src/domains/memory/task-bank.ts

@@ -0,0 +1,229 @@
+import { ceilChars } from "../session/context-accounting.js";
+
+export const TASK_MEMORY_VERSION = 1;
+export const TASK_MEMORY_DEFAULT_KNOWLEDGE_CAP = 20;
+export const TASK_MEMORY_DEFAULT_PROCEDURAL_CAP = 30;
+export const TASK_MEMORY_CONTENT_MAX_CHARS = 1_200;
+
+export type TaskMemoryClass = "status" | "knowledge" | "procedural";
+export type TaskMemoryRenderableClass = Exclude<TaskMemoryClass, "status">;
+
+export interface TaskMemoryEntry {
+	id: string;
+	kind: TaskMemoryClass;
+	content: string;
+	createdAt: string;
+	lastTouchedAt: string;
+	injectionCount: number;
+}
+
+/** JSON-safe export shape. The bank itself remains session-scoped and in memory. */
+export interface TaskMemorySnapshot {
+	version: 1;
+	status: TaskMemoryEntry | null;
+	knowledge: TaskMemoryEntry[];
+	procedural: TaskMemoryEntry[];
+}
+
+export interface TaskMemoryBankOptions {
+	knowledgeCap?: number;
+	proceduralCap?: number;
+	now?: () => Date;
+}
+
+export interface SaveTaskMemoryOptions {
+	/** Update an existing entry while preserving its identity. */
+	id?: string;
+}
+
+/**
+ * Per-session execution memory. This deliberately has no durable store or
+ * approval flow: it is authoritative working state for one active task.
+ */
+export class TaskMemoryBank {
+	readonly #knowledgeCap: number;
+	readonly #proceduralCap: number;
+	readonly #now: () => Date;
+	readonly #knowledge = new Map<string, TaskMemoryEntry>();
+	readonly #procedural = new Map<string, TaskMemoryEntry>();
+	#status: TaskMemoryEntry | null = null;
+	#nextId = 1;
+
+	constructor(options: TaskMemoryBankOptions = {}) {
+		this.#knowledgeCap = positiveInteger(options.knowledgeCap, TASK_MEMORY_DEFAULT_KNOWLEDGE_CAP);
+		this.#proceduralCap = positiveInteger(options.proceduralCap, TASK_MEMORY_DEFAULT_PROCEDURAL_CAP);
+		this.#now = options.now ?? (() => new Date());
+	}
+
+	updateStatus(content: string): TaskMemoryEntry {
+		const timestamp = this.#timestamp();
+		const normalized = normalizeContent(content);
+		this.#status =
+			this.#status === null
+				? this.#newEntry("status", normalized, timestamp)
+				: { ...this.#status, content: normalized, lastTouchedAt: timestamp };
+		return cloneEntry(this.#status);
+	}
+
+	saveKnowledge(content: string, options: SaveTaskMemoryOptions = {}): TaskMemoryEntry {
+		return this.#save("knowledge", content, options.id);
+	}
+
+	saveProcedural(content: string, options: SaveTaskMemoryOptions = {}): TaskMemoryEntry {
+		return this.#save("procedural", content, options.id);
+	}
+
+	deleteEntry(id: string): boolean {
+		if (this.#status?.id === id) {
+			this.#status = null;
+			return true;
+		}
+		return this.#knowledge.delete(id) || this.#procedural.delete(id);
+	}
+
+	/** Reset execution state when the composition root switches sessions. */
+	clear(): void {
+		this.#status = null;
+		this.#knowledge.clear();
+		this.#procedural.clear();
+		this.#nextId = 1;
+	}
+
+	/** Record attribution after an entry has contributed to a visible reminder. */
+	recordInjection(ids: ReadonlyArray<string>): void {
+		for (const id of new Set(ids)) {
+			const entries = this.#knowledge.has(id) ? this.#knowledge : this.#procedural;
+			const entry = entries.get(id);
+			if (entry === undefined) continue;
+			const updated = { ...entry, injectionCount: entry.injectionCount + 1, lastTouchedAt: this.#timestamp() };
+			entries.set(id, updated);
+		}
+	}
+
+	/**
+	 * Render only action-agent-visible classes under a conservative character
+	 * token estimate. Status remains private even if a caller requests it.
+	 */
+	render(budgetTokens: number, kinds: ReadonlyArray<TaskMemoryRenderableClass> = ["knowledge", "procedural"]): string {
+		if (!Number.isFinite(budgetTokens) || budgetTokens <= 0) return "";
+		const allowed = new Set(kinds);
+		const entries = [...this.#knowledge.values(), ...this.#procedural.values()]
+			.filter((entry) => allowed.has(entry.kind as TaskMemoryRenderableClass))
+			.sort(compareForRender);
+		let rendered = "";
+		for (const entry of entries) {
+			const line = `- [${entry.id}] ${entry.kind}: ${entry.content}`;
+			const candidate = rendered.length === 0 ? line : `${rendered}\n${line}`;
+			if (ceilChars(candidate.length) > budgetTokens) continue;
+			rendered = candidate;
+		}
+		return rendered;
+	}
+
+	/**
+	 * Render the block handed back to the action agent after compaction, which is
+	 * the one place status is visible.
+	 *
+	 * `render` refuses status because a mid-turn reminder must never expose the
+	 * policy's private progress model as if the action agent had said it. That
+	 * boundary is different: compaction destroyed the agent's own working state
+	 * and this hands it back. Restoring knowledge alone restored nothing in the
+	 * common case, because across ten live LLM steps the model wrote status in all
+	 * ten and knowledge in two. Status leads for the same reason, and knowledge
+	 * takes the remaining budget. Procedural stays out, unchanged.
+	 */
+	renderRestoredState(budgetTokens: number): string {
+		if (!Number.isFinite(budgetTokens) || budgetTokens <= 0) return "";
+		const status = this.#status;
+		const statusLine = status === null ? "" : `- [${status.id}] status: ${status.content}`;
+		if (statusLine.length > 0 && ceilChars(statusLine.length) > budgetTokens)
+			return this.render(budgetTokens, ["knowledge"]);
+		const remaining = statusLine.length === 0 ? budgetTokens : budgetTokens - ceilChars(statusLine.length);
+		const knowledge = this.render(remaining, ["knowledge"]);
+		if (statusLine.length === 0) return knowledge;
+		return knowledge.length === 0 ? statusLine : `${statusLine}\n${knowledge}`;
+	}
+
+	snapshot(): TaskMemorySnapshot {
+		return {
+			version: TASK_MEMORY_VERSION,
+			status: this.#status === null ? null : cloneEntry(this.#status),
+			knowledge: [...this.#knowledge.values()].sort(compareForSnapshot).map(cloneEntry),
+			procedural: [...this.#procedural.values()].sort(compareForSnapshot).map(cloneEntry),
+		};
+	}
+
+	#save(kind: TaskMemoryRenderableClass, content: string, id: string | undefined): TaskMemoryEntry {
+		const entries = this.#mapFor(kind);
+		const normalized = normalizeContent(content);
+		const timestamp = this.#timestamp();
+		let saved: TaskMemoryEntry;
+		if (id === undefined) {
+			saved = this.#newEntry(kind, normalized, timestamp);
+		} else {
+			const existing = entries.get(id);
+			if (existing === undefined) throw new Error(`task memory entry not found: ${id}`);
+			saved = { ...existing, content: normalized, lastTouchedAt: timestamp };
+		}
+		entries.set(saved.id, saved);
+		this.#evictOldest(entries, kind === "knowledge" ? this.#knowledgeCap : this.#proceduralCap);
+		return cloneEntry(saved);
+	}
+
+	#newEntry(kind: TaskMemoryClass, content: string, timestamp: string): TaskMemoryEntry {
+		const prefix = kind === "status" ? "s" : kind === "knowledge" ? "k" : "p";
+		const id = `tm-${prefix}-${this.#nextId.toString(36)}`;
+		this.#nextId += 1;
+		return { id, kind, content, createdAt: timestamp, lastTouchedAt: timestamp, injectionCount: 0 };
+	}
+
+	#mapFor(kind: TaskMemoryRenderableClass): Map<string, TaskMemoryEntry> {
+		return kind === "knowledge" ? this.#knowledge : this.#procedural;
+	}
+
+	#evictOldest(entries: Map<string, TaskMemoryEntry>, cap: number): void {
+		while (entries.size > cap) {
+			const oldest = [...entries.values()].sort(compareForEviction)[0];
+			if (oldest === undefined) return;
+			entries.delete(oldest.id);
+		}
+	}
+
+	#timestamp(): string {
+		return this.#now().toISOString();
+	}
+}
+
+function normalizeContent(content: string): string {
+	const normalized = content.replace(/\s+/gu, " ").trim();
+	if (normalized.length === 0) throw new Error("task memory content must not be empty");
+	return normalized.slice(0, TASK_MEMORY_CONTENT_MAX_CHARS).trimEnd();
+}
+
+function positiveInteger(value: number | undefined, fallback: number): number {
+	return value !== undefined && Number.isInteger(value) && value > 0 ? value : fallback;
+}
+
+function cloneEntry(entry: TaskMemoryEntry): TaskMemoryEntry {
+	return { ...entry };
+}
+
+function compareForEviction(left: TaskMemoryEntry, right: TaskMemoryEntry): number {
+	const byTouched = left.lastTouchedAt.localeCompare(right.lastTouchedAt);
+	if (byTouched !== 0) return byTouched;
+	const byCreated = left.createdAt.localeCompare(right.createdAt);
+	if (byCreated !== 0) return byCreated;
+	return left.id.localeCompare(right.id);
+}
+
+function compareForRender(left: TaskMemoryEntry, right: TaskMemoryEntry): number {
+	const byTouched = right.lastTouchedAt.localeCompare(left.lastTouchedAt);
+	if (byTouched !== 0) return byTouched;
+	if (left.kind !== right.kind) return left.kind === "knowledge" ? -1 : 1;
+	return left.id.localeCompare(right.id);
+}
+
+function compareForSnapshot(left: TaskMemoryEntry, right: TaskMemoryEntry): number {
+	const byCreated = left.createdAt.localeCompare(right.createdAt);
+	return byCreated !== 0 ? byCreated : left.id.localeCompare(right.id);
+}