Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`,
Expand Down
13 changes: 12 additions & 1 deletion src/config.ts
Original file line number Diff line number Diff line change
@@ -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";
Expand Down Expand Up @@ -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 {
Expand Down
13 changes: 11 additions & 2 deletions src/functions/auto-forget.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<{
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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
Expand Down
6 changes: 4 additions & 2 deletions src/functions/retention.ts
Original file line number Diff line number Diff line change
Expand Up @@ -346,10 +346,12 @@ export function registerRetentionFunctions(
}

const mem = await kv.get<Memory>(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);
Expand Down
3 changes: 2 additions & 1 deletion src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -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") {
Expand Down
48 changes: 48 additions & 0 deletions test/auto-forget.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<Memory>("mem:memories", "mem_1"))!.isLatest).toBe(true);
expect((await kv.get<Memory>("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<Memory>("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);
});
});
24 changes: 24 additions & 0 deletions test/config-placeholder-keys.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
});
});
24 changes: 24 additions & 0 deletions test/retention.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
});
});