Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

fix(audit): add audit coverage for mem::forget + document policy (#125)

Rohit Ghumare9a6680433815
diff --git a/src/functions/audit.ts b/src/functions/audit.ts
index 5cb0e1a9..f3d5f088 100644
--- a/src/functions/audit.ts
+++ b/src/functions/audit.ts
@@ -3,6 +3,32 @@ import { KV, generateId } from "../state/schema.js";
import type { StateKV } from "../state/kv.js";
import { logger } from "../logger.js";
+// Audit coverage policy (issue #125).
+//
+// Every structural deletion of a memory, observation, session, or
+// semantic row MUST call recordAudit. Two shapes are allowed, keyed to
+// whether the caller is scoped or bulk:
+//
+// Scoped deletions — a user-visible, per-call action removing a
+// bounded set of items. Emit ONE audit row per call with targetIds
+// populated. Examples: mem::governance-delete, mem::forget.
+//
+// Bulk deletions — automatic sweeps (retention, TTL eviction,
+// auto-forget) that can remove hundreds of rows per invocation.
+// Emit ONE batched audit row per invocation with targetIds listing
+// every removed id and details.evicted holding the count. Per-item
+// audit rows would flood the audit log during routine sweeps.
+//
+// Either shape is required; silent deletes are not acceptable.
+//
+// operation field:
+// - "delete" — permanent removal (governance, retention sweep, evict).
+// - "forget" — user-initiated forget (mem::forget, mem::auto-forget).
+// - everything else — see AuditEntry["operation"] union in src/types.ts.
+//
+// When adding a new deletion path, add an explicit recordAudit call
+// BEFORE kv.delete(...) and match one of the two shapes above.
+
export async function recordAudit(
kv: StateKV,
operation: AuditEntry["operation"],
diff --git a/src/functions/remember.ts b/src/functions/remember.ts
index 1300e779..69579fe0 100644
--- a/src/functions/remember.ts
+++ b/src/functions/remember.ts
@@ -4,6 +4,7 @@ import { KV, generateId, jaccardSimilarity } from "../state/schema.js";
import { StateKV } from "../state/kv.js";
import { withKeyedLock } from "../state/keyed-mutex.js";
import { deleteAccessLog } from "./access-tracker.js";
+import { recordAudit } from "./audit.js";
import { logger } from "../logger.js";
export function registerRememberFunction(sdk: ISdk, kv: StateKV): void {
@@ -115,17 +116,21 @@ export function registerRememberFunction(sdk: ISdk, kv: StateKV): void {
},
);
- sdk.registerFunction("mem::forget",
+ sdk.registerFunction("mem::forget",
async (data: {
sessionId?: string;
observationIds?: string[];
memoryId?: string;
}) => {
let deleted = 0;
+ const deletedMemoryIds: string[] = [];
+ const deletedObservationIds: string[] = [];
+ let deletedSession = false;
if (data.memoryId) {
await kv.delete(KV.memories, data.memoryId);
await deleteAccessLog(kv, data.memoryId);
+ deletedMemoryIds.push(data.memoryId);
deleted++;
}
@@ -136,6 +141,7 @@ export function registerRememberFunction(sdk: ISdk, kv: StateKV): void {
) {
for (const obsId of data.observationIds) {
await kv.delete(KV.observations(data.sessionId), obsId);
+ deletedObservationIds.push(obsId);
deleted++;
}
}
@@ -150,13 +156,32 @@ export function registerRememberFunction(sdk: ISdk, kv: StateKV): void {
);
for (const obs of observations) {
await kv.delete(KV.observations(data.sessionId), obs.id);
+ deletedObservationIds.push(obs.id);
deleted++;
}
await kv.delete(KV.sessions, data.sessionId);
await kv.delete(KV.summaries, data.sessionId);
+ deletedSession = true;
deleted += 2;
}
+ if (deleted > 0) {
+ await recordAudit(
+ kv,
+ "forget",
+ "mem::forget",
+ [...deletedMemoryIds, ...deletedObservationIds],
+ {
+ sessionId: data.sessionId,
+ deleted,
+ memoriesDeleted: deletedMemoryIds.length,
+ observationsDeleted: deletedObservationIds.length,
+ sessionDeleted: deletedSession,
+ reason: "user-initiated forget",
+ },
+ );
+ }
+
logger.info("Memory forgotten", { deleted });
return { success: true, deleted };
},
diff --git a/test/remember-forget-audit.test.ts b/test/remember-forget-audit.test.ts
new file mode 100644
index 00000000..7be571fa
--- /dev/null
+++ b/test/remember-forget-audit.test.ts
@@ -0,0 +1,119 @@
+import { describe, it, expect, vi } from "vitest";
+
+vi.mock("../src/logger.js", () => ({
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+vi.mock("../src/state/keyed-mutex.js", () => ({
+ withKeyedLock: <T>(_key: string, fn: () => Promise<T>) => fn(),
+}));
+
+import { registerRememberFunction } from "../src/functions/remember.js";
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ get: async <T>(scope: string, key: string): Promise<T | null> =>
+ (store.get(scope)?.get(key) as T) ?? null,
+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, data);
+ return data;
+ },
+ delete: async (scope: string, key: string): Promise<void> => {
+ store.get(scope)?.delete(key);
+ },
+ list: async <T>(scope: string): Promise<T[]> => {
+ const entries = store.get(scope);
+ return entries ? (Array.from(entries.values()) as T[]) : [];
+ },
+ };
+}
+
+function mockSdk() {
+ const functions = new Map<string, Function>();
+ return {
+ registerFunction: (id: string, handler: Function) => {
+ functions.set(id, handler);
+ },
+ registerTrigger: () => {},
+ trigger: async (input: { function_id: string; payload: unknown }) => {
+ const fn = functions.get(input.function_id);
+ if (!fn) throw new Error(`unknown fn ${input.function_id}`);
+ return fn(input.payload);
+ },
+ };
+}
+
+describe("mem::forget audit coverage (issue #125)", () => {
+ it("emits a single audit row when a memory is forgotten", async () => {
+ const sdk = mockSdk();
+ const kv = mockKV();
+ registerRememberFunction(sdk as never, kv as never);
+
+ await kv.set("mem:memories", "mem_a", { id: "mem_a", content: "x" });
+
+ const result = await sdk.trigger({
+ function_id: "mem::forget",
+ payload: { memoryId: "mem_a" },
+ });
+ expect((result as { deleted: number }).deleted).toBe(1);
+
+ const auditRows = await kv.list<{
+ operation: string;
+ functionId: string;
+ targetIds: string[];
+ details: Record<string, unknown>;
+ }>("mem:audit");
+ expect(auditRows).toHaveLength(1);
+ const [row] = auditRows;
+ expect(row.operation).toBe("forget");
+ expect(row.functionId).toBe("mem::forget");
+ expect(row.targetIds).toEqual(["mem_a"]);
+ expect(row.details.memoriesDeleted).toBe(1);
+ expect(row.details.observationsDeleted).toBe(0);
+ expect(row.details.sessionDeleted).toBe(false);
+ });
+
+ it("emits one batched audit row when an entire session is forgotten", async () => {
+ const sdk = mockSdk();
+ const kv = mockKV();
+ registerRememberFunction(sdk as never, kv as never);
+
+ await kv.set("mem:sessions", "sess_1", { id: "sess_1" });
+ await kv.set("mem:summaries", "sess_1", { id: "sess_1" });
+ await kv.set("mem:obs:sess_1", "obs_a", { id: "obs_a" });
+ await kv.set("mem:obs:sess_1", "obs_b", { id: "obs_b" });
+
+ await sdk.trigger({
+ function_id: "mem::forget",
+ payload: { sessionId: "sess_1" },
+ });
+
+ const auditRows = await kv.list<{
+ targetIds: string[];
+ details: Record<string, unknown>;
+ }>("mem:audit");
+ expect(auditRows).toHaveLength(1);
+ const [row] = auditRows;
+ expect([...row.targetIds].sort()).toEqual(["obs_a", "obs_b"]);
+ expect(row.details.memoriesDeleted).toBe(0);
+ expect(row.details.observationsDeleted).toBe(2);
+ expect(row.details.sessionDeleted).toBe(true);
+ expect(row.details.deleted).toBe(4);
+ });
+
+ it("does not emit an audit row when nothing is deleted", async () => {
+ const sdk = mockSdk();
+ const kv = mockKV();
+ registerRememberFunction(sdk as never, kv as never);
+
+ await sdk.trigger({
+ function_id: "mem::forget",
+ payload: { sessionId: undefined, memoryId: undefined },
+ });
+
+ const auditRows = await kv.list("mem:audit");
+ expect(auditRows).toHaveLength(0);
+ });
+});