diff --git a/CLAUDE.md b/CLAUDE.md index a1859c7246..6827642726 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -213,6 +213,14 @@ reinforces that Lesson on replay. A `memory_save` using the shim's local fallbac replies `localOnly: true` for the returned local ID; the daemon save is unconfirmed, so check the daemon before saving again. The local fallback is not queued. +### Auto-forget scope and image references +`mem::auto-forget` compares contradictions only when project, Global marker and agent ID +match, including missing values. `AUTO_FORGET_INTERVAL_MS` must be a positive integer no +larger than Node's timer limit (2,147,483,647 ms); invalid values warn and fall back to one hour. +Auto-forget and retention release a Memory's image reference after its indexed delete succeeds. +A failed release is logged without blocking deletion bookkeeping; it may leave an unused image. +Concurrent deletion locking is outside this contract. + ### Graph Eviction Every path that hard-deletes Observations or Memories (`mem::evict`, `mem::observe` session-cap eviction, `mem::auto-forget`, `mem::forget`, `mem::retention-evict`, `mem::governance-delete`, diff --git a/src/config.ts b/src/config.ts index a3466b086e..5899b8b79f 100644 --- a/src/config.ts +++ b/src/config.ts @@ -1,6 +1,7 @@ import { join } from "node:path"; import { homedir } from "node:os"; -import { refreshBootVerbose } from "./logger.js"; +import { logger, refreshBootVerbose } from "./logger.js"; +import { parseOptionalPositiveInt } from "./utils/parse-number.js"; import { hydrateEnvFromFile, loadEnvFile } from "./hooks/_env.js"; import pc from "picocolors"; import { isPlaceholderKey } from "./utils/placeholder-key.js"; @@ -537,6 +538,16 @@ export function getSignalDefaultTtlMs(): number { return days > 0 ? days * 24 * 60 * 60 * 1000 : 0; } +export function getAutoForgetIntervalMs(): number { + const raw = getMergedEnv()["AUTO_FORGET_INTERVAL_MS"]; + const parsed = parseOptionalPositiveInt(raw); + if (parsed != null && parsed <= 2_147_483_647) return parsed; + if (raw !== undefined) { + logger.warn("Invalid AUTO_FORGET_INTERVAL_MS; using default", { value: raw }); + } + return 3_600_000; +} + const BACKUP_KEEP_DEFAULT = 7; export function getBackupKeep(): number { diff --git a/src/functions/auto-forget.ts b/src/functions/auto-forget.ts index 90d90cf346..ccf45da817 100644 --- a/src/functions/auto-forget.ts +++ b/src/functions/auto-forget.ts @@ -12,6 +12,12 @@ import { logger } from "../logger.js"; const MS_PER_DAY = 24 * 60 * 60 * 1000; const CONTRADICTION_THRESHOLD = 0.9; +function sameSupersessionScope(a: Memory, b: Memory): boolean { + return a.project === b.project && + (a.global === true) === (b.global === true) && + a.agentId === b.agentId; +} + interface AutoForgetResult { ttlExpired: string[]; contradictions: Array<{ @@ -47,10 +53,12 @@ export function registerAutoForgetFunction(sdk: ISdk, kv: StateKV): void { result.ttlExpired.push(mem.id); deletedIds.add(mem.id); if (!dryRun) { + await deleteIndexed(kv, KV.memories, mem.id); if (mem.imageRef) { - await decrementImageRef(kv, sdk, mem.imageRef); + await decrementImageRef(kv, sdk, mem.imageRef).catch((error) => { + logger.warn("Auto-forget could not release image reference", { memoryId: mem.id, error: String(error) }); + }); } - await deleteIndexed(kv, KV.memories, mem.id); evictedSourceIds.push(mem.id); await recordAudit(kv, "delete", "mem::auto-forget", [mem.id], { resource: "memory", @@ -119,6 +127,7 @@ export function registerAutoForgetFunction(sdk: ISdk, kv: StateKV): void { if (sim > CONTRADICTION_THRESHOLD) { const memA = memById.get(memIds[i])!; const memB = memById.get(memIds[j])!; + if (!sameSupersessionScope(memA, memB)) continue; // Two daily reports of two different days are not a // contradiction. Without this, auto-forget silently re-demotes // exactly the rows a lineage repair just restored - measured diff --git a/src/functions/retention.ts b/src/functions/retention.ts index 81635cb3b0..1f071b3ebd 100644 --- a/src/functions/retention.ts +++ b/src/functions/retention.ts @@ -346,10 +346,12 @@ export function registerRetentionFunctions( } const mem = await kv.get(scope, candidate.memoryId); + await deleteIndexed(kv, scope, candidate.memoryId); if (mem && mem.imageRef) { - await decrementImageRef(kv, sdk, mem.imageRef); + await decrementImageRef(kv, sdk, mem.imageRef).catch((error) => { + logger.warn("Retention could not release image reference", { memoryId: mem.id, error: String(error) }); + }); } - await deleteIndexed(kv, scope, candidate.memoryId); await kv.delete(KV.retentionScores, candidate.memoryId); evicted++; evictedIds.push(candidate.memoryId); diff --git a/src/index.ts b/src/index.ts index 5f727899ce..d0dacb5025 100644 --- a/src/index.ts +++ b/src/index.ts @@ -14,6 +14,7 @@ import { isContextInjectionEnabled, getSqlitePath, getBackupKeep, + getAutoForgetIntervalMs, } from "./config.js"; import { createInprocSdk } from "./engine/inproc/sdk.js"; import { SqliteVectorStore } from "./engine/inproc/vectors.js"; @@ -563,7 +564,7 @@ async function main() { config.streamsPort, ); - const autoForgetIntervalMs = parseInt(process.env.AUTO_FORGET_INTERVAL_MS || "3600000", 10); + const autoForgetIntervalMs = getAutoForgetIntervalMs(); const consolidationIntervalMs = parseInt(process.env.CONSOLIDATION_INTERVAL_MS || "7200000", 10); if (process.env.AUTO_FORGET_ENABLED !== "false") { diff --git a/test/auto-forget.test.ts b/test/auto-forget.test.ts index 875fb43bbb..f21391d99c 100644 --- a/test/auto-forget.test.ts +++ b/test/auto-forget.test.ts @@ -317,4 +317,52 @@ describe("Auto-Forget Function", () => { expect(result.contradictions.length).toBe(0); }); + + describe("contradiction pass stays within one scope (#437)", () => { + const content = "Use React hooks for state management in all components"; + + it.each([ + ["different projects", { project: "alpha" }, { project: "beta" }], + ["missing and present project", {}, { project: "alpha" }], + ["different agents", { project: "alpha", agentId: "a" }, { project: "alpha", agentId: "b" }], + ["missing and present agent", { project: "alpha" }, { project: "alpha", agentId: "a" }], + ["a Global and a scoped Memory", { project: "alpha", global: true }, { project: "alpha" }], + ])("keeps both latest across %s", async (_label, a, b) => { + await kv.set("mem:memories", "mem_1", makeMemory({ id: "mem_1", content, createdAt: "2026-01-01T00:00:00Z", ...a })); + await kv.set("mem:memories", "mem_2", makeMemory({ id: "mem_2", content, createdAt: "2026-02-01T00:00:00Z", ...b })); + + const result = (await sdk.trigger("mem::auto-forget", {})) as { contradictions: unknown[] }; + + expect(result.contradictions).toHaveLength(0); + expect((await kv.get("mem:memories", "mem_1"))!.isLatest).toBe(true); + expect((await kv.get("mem:memories", "mem_2"))!.isLatest).toBe(true); + }); + + it("still supersedes the older of two in one project", async () => { + await kv.set("mem:memories", "mem_1", makeMemory({ id: "mem_1", content, project: "alpha", createdAt: "2026-01-01T00:00:00Z" })); + await kv.set("mem:memories", "mem_2", makeMemory({ id: "mem_2", content, project: "alpha", createdAt: "2026-02-01T00:00:00Z" })); + + await sdk.trigger("mem::auto-forget", {}); + + expect((await kv.get("mem:memories", "mem_1"))!.isLatest).toBe(false); + }); + }); + + it("keeps the image ref when the TTL delete fails (#437)", async () => { + await kv.set("mem:memories", "mem_img", makeMemory({ + id: "mem_img", + forgetAfter: "2020-01-01T00:00:00Z", + imageRef: "/images/a.png", + })); + await kv.set("mem:image-refs", "/images/a.png", 2); + const realDelete = kv.delete; + kv.delete = async (scope, key) => { + if (scope === "mem:memories") throw new Error("disk full"); + return realDelete(scope, key); + }; + + await expect(sdk.trigger("mem::auto-forget", {})).rejects.toThrow("disk full"); + + expect(await kv.get("mem:image-refs", "/images/a.png")).toBe(2); + }); }); diff --git a/test/config-placeholder-keys.test.ts b/test/config-placeholder-keys.test.ts index 2dff67cb5e..01f6cc55d9 100644 --- a/test/config-placeholder-keys.test.ts +++ b/test/config-placeholder-keys.test.ts @@ -57,3 +57,27 @@ describe("LLM provider detection ignores placeholder keys", () => { expect(await detect()).toEqual({ provider: "anthropic", kind: "llm" }); }); }); + +describe("auto-forget interval", () => { + const original = process.env.AUTO_FORGET_INTERVAL_MS; + + afterEach(() => { + if (original === undefined) delete process.env.AUTO_FORGET_INTERVAL_MS; + else process.env.AUTO_FORGET_INTERVAL_MS = original; + vi.restoreAllMocks(); + }); + + it.each(["abc", "1h", "0", "-5", "1.5", "", "Infinity", "2147483648"])("warns and defaults for %s", async (raw) => { + process.env.AUTO_FORGET_INTERVAL_MS = raw; + const warn = vi.spyOn(process.stderr, "write").mockImplementation(() => true); + const { getAutoForgetIntervalMs } = await import("../src/config.js"); + expect(getAutoForgetIntervalMs()).toBe(3_600_000); + expect(warn).toHaveBeenCalledWith(expect.stringContaining("Invalid AUTO_FORGET_INTERVAL_MS")); + }); + + it("accepts a positive integer", async () => { + process.env.AUTO_FORGET_INTERVAL_MS = "600000"; + const { getAutoForgetIntervalMs } = await import("../src/config.js"); + expect(getAutoForgetIntervalMs()).toBe(600_000); + }); +}); diff --git a/test/retention.test.ts b/test/retention.test.ts index a6c05c6993..9e5ebaa783 100644 --- a/test/retention.test.ts +++ b/test/retention.test.ts @@ -533,4 +533,28 @@ describe("RetentionScoring", () => { expect(getSearchIndex().has("mem_evict")).toBe(false); }); }); + + it("mem::retention-evict keeps the image ref when the delete fails (#437)", async () => { + const { registerRetentionFunctions } = await import( + "../src/functions/retention.js" + ); + const sdk = mockSdk(); + const kv = mockKV([{ ...makeMemory("mem_img", "fact", 500), imageRef: "/images/a.png" }]); + await kv.set("mem:image-refs", "/images/a.png", 2); + registerRetentionFunctions(sdk as never, kv as never); + await sdk.trigger({ function_id: "mem::retention-score", payload: {} }); + const realDelete = kv.delete; + kv.delete = async (scope, key) => { + if (scope === "mem:memories") throw new Error("disk full"); + return realDelete(scope, key); + }; + + const result = (await sdk.trigger({ + function_id: "mem::retention-evict", + payload: { threshold: 0.9 }, + })) as { evicted: number }; + + expect(result.evicted).toBe(0); + expect(await kv.get("mem:image-refs", "/images/a.png")).toBe(2); + }); });