Skip to content

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

fix(capture): store a Cursor prompt once when the transcript back-fill replays it (#1470)

Rohit Ghumare695b7e4ff89b
diff --git a/plugin/scripts/session-end.mjs b/plugin/scripts/session-end.mjs
index ff60e20a..c98f569c 100755
--- a/plugin/scripts/session-end.mjs
+++ b/plugin/scripts/session-end.mjs
@@ -92,7 +92,10 @@ async function main() {
project,
cwd,
timestamp,
- data: { prompt }
+ data: {
+ prompt,
+ backfill: true
+ }
}, {}, {
source: "transcript",
transcript: data.transcript_path,
diff --git a/src/capture/prompt-ledger.ts b/src/capture/prompt-ledger.ts
new file mode 100644
index 00000000..444ac821
--- /dev/null
+++ b/src/capture/prompt-ledger.ts
@@ -0,0 +1,107 @@
+import { createHash } from "node:crypto";
+import { KV } from "../state/schema.js";
+import type { StateKV } from "../state/kv.js";
+
+export const PROMPT_LEDGER_MAX_KEYS = 1000;
+
+export const PROMPT_LEDGER_MAX_REFS = 200;
+
+interface PromptRefs {
+ live: string[];
+ claimed: string[];
+}
+
+export interface PromptLedger {
+ sessionId: string;
+ updatedAt: string;
+ prompts: Record<string, PromptRefs>;
+}
+
+export function isBackfillPrompt(data: unknown): boolean {
+ return typeof data === "object" && data !== null && (data as Record<string, unknown>)["backfill"] === true;
+}
+
+export function promptContentKey(prompt: string): string | null {
+ const normalized = prompt.replace(/\s+/g, " ").trim();
+ if (!normalized) return null;
+ return createHash("sha256").update(normalized).digest("hex").slice(0, 32);
+}
+
+function ledgerKey(sessionId: string): string {
+ return `pl_${createHash("sha256").update(sessionId).digest("hex").slice(0, 40)}`;
+}
+
+function refs(value: unknown): PromptRefs | null {
+ if (!value || typeof value !== "object") return null;
+ const v = value as Record<string, unknown>;
+ if (!Array.isArray(v["live"]) || !Array.isArray(v["claimed"])) return null;
+ return {
+ live: v["live"].filter((x): x is string => typeof x === "string"),
+ claimed: v["claimed"].filter((x): x is string => typeof x === "string"),
+ };
+}
+
+async function load(kv: StateKV, sessionId: string): Promise<PromptLedger> {
+ const stored = await kv.get<PromptLedger>(KV.capturePrompts, ledgerKey(sessionId));
+ const prompts: Record<string, PromptRefs> = {};
+ if (stored && typeof stored.prompts === "object" && stored.prompts !== null) {
+ for (const [key, value] of Object.entries(stored.prompts)) {
+ const entry = refs(value);
+ if (entry) prompts[key] = entry;
+ }
+ }
+ return { sessionId, updatedAt: stored?.updatedAt ?? new Date().toISOString(), prompts };
+}
+
+async function save(kv: StateKV, ledger: PromptLedger): Promise<void> {
+ const keys = Object.keys(ledger.prompts);
+ for (const key of keys.slice(0, Math.max(0, keys.length - PROMPT_LEDGER_MAX_KEYS))) {
+ delete ledger.prompts[key];
+ }
+ ledger.updatedAt = new Date().toISOString();
+ await kv.set(KV.capturePrompts, ledgerKey(ledger.sessionId), ledger);
+}
+
+function bounded(list: string[]): string[] {
+ return list.length > PROMPT_LEDGER_MAX_REFS ? list.slice(list.length - PROMPT_LEDGER_MAX_REFS) : list;
+}
+
+export async function recordLivePrompt(kv: StateKV, sessionId: string, prompt: string, ref: string): Promise<void> {
+ const key = promptContentKey(prompt);
+ if (!key) return;
+ const ledger = await load(kv, sessionId);
+ const current = ledger.prompts[key] ?? { live: [], claimed: [] };
+ if (current.live.includes(ref)) return;
+ delete ledger.prompts[key];
+ ledger.prompts[key] = { live: bounded([...current.live, ref]), claimed: current.claimed };
+ await save(kv, ledger);
+}
+
+export async function claimBackfillPrompt(kv: StateKV, sessionId: string, prompt: string, ref: string): Promise<boolean> {
+ const key = promptContentKey(prompt);
+ if (!key) return false;
+ const ledger = await load(kv, sessionId);
+ const current = ledger.prompts[key];
+ if (!current) return false;
+ if (current.claimed.includes(ref)) return true;
+ if (current.claimed.length >= current.live.length) return false;
+ current.claimed = bounded([...current.claimed, ref]);
+ await save(kv, ledger);
+ return true;
+}
+
+export async function prunePromptLedgers(kv: StateKV, cutoffMs: number, maxLedgers: number): Promise<number> {
+ const ledgers = await kv.list<PromptLedger>(KV.capturePrompts).catch(() => [] as PromptLedger[]);
+ const sorted = ledgers
+ .filter((l): l is PromptLedger => !!l && typeof l.sessionId === "string")
+ .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+ let removed = 0;
+ for (let i = 0; i < sorted.length; i++) {
+ const ledger = sorted[i]!;
+ if (i >= maxLedgers || Date.parse(ledger.updatedAt) < cutoffMs) {
+ await kv.delete(KV.capturePrompts, ledgerKey(ledger.sessionId)).catch(() => {});
+ removed++;
+ }
+ }
+ return removed;
+}
diff --git a/src/functions/capture.ts b/src/functions/capture.ts
index f2f25da9..e945eff1 100644
--- a/src/functions/capture.ts
+++ b/src/functions/capture.ts
@@ -17,6 +17,7 @@ import {
type CompletedEvent,
} from "../capture/event-record.js";
import { restoreIndexEntries } from "./observe.js";
+import { prunePromptLedgers } from "../capture/prompt-ledger.js";
import { scrubRecord } from "./privacy.js";
import { runtimeConfigPath } from "../cli/engine-launch.js";
import { captureDurableAfterMs, engineStateConfigPaths } from "../cli/engine-config.js";
@@ -430,6 +431,7 @@ export function registerCaptureFunctions(
removed++;
}
}
+ removed += await prunePromptLedgers(kv, cutoff, policy.eventsMax);
inboxSize = null;
counters.pruned += removed;
lastPruneAt = new Date().toISOString();
diff --git a/src/functions/observe.ts b/src/functions/observe.ts
index ffdbe0bb..237fd2c7 100644
--- a/src/functions/observe.ts
+++ b/src/functions/observe.ts
@@ -13,6 +13,7 @@ import { withKeyedLock } from "../state/keyed-mutex.js";
import { isAutoCompressEnabled } from "../config.js";
import { buildSyntheticCompression } from "./compress-synthetic.js";
import { isCaptureKey } from "../capture/event-record.js";
+import { claimBackfillPrompt, isBackfillPrompt, recordLivePrompt } from "../capture/prompt-ledger.js";
import { getSearchIndex, getVectorIndex, scheduleIndexSave, vectorIndexAddGuarded } from "./search.js";
import { getAgentId } from "../config.js";
import { logger } from "../logger.js";
@@ -175,14 +176,24 @@ export function registerObserveFunction(
}
const pendingImageData = extractedImage;
+ const submittedPrompt =
+ payload.hookType === "prompt_submit" && typeof raw.userPrompt === "string" ? raw.userPrompt : undefined;
+ const backfillPrompt = submittedPrompt && isBackfillPrompt(payload.data) ? submittedPrompt : undefined;
+ const livePrompt = submittedPrompt && !backfillPrompt ? submittedPrompt : undefined;
+ const promptRef = durable || typeof payload.eventId !== "string" ? obsId : payload.eventId;
return withKeyedLock(`obs:${payload.sessionId}`, async () => {
const existing = await kv.list<CompressedObservation>(KV.observations(payload.sessionId));
const stored = durable ? existing.find((o) => o?.id === obsId) : undefined;
if (stored) {
+ if (livePrompt) await recordLivePrompt(kv, payload.sessionId, livePrompt, promptRef);
await restoreIndexEntries(stored);
return { observationId: obsId, deduplicated: true, existing: true };
}
+ if (backfillPrompt && (await claimBackfillPrompt(kv, payload.sessionId, backfillPrompt, promptRef))) {
+ recordDedupSkip();
+ return { deduplicated: true, sessionId: payload.sessionId };
+ }
if (maxObservationsPerSession && maxObservationsPerSession > 0) {
if (existing.length >= maxObservationsPerSession) {
return {
@@ -269,6 +280,7 @@ export function registerObserveFunction(
if (dedupMap && dedupHash) {
dedupMap.record(dedupHash);
}
+ if (livePrompt) await recordLivePrompt(kv, payload.sessionId, livePrompt, promptRef);
await sdk.trigger({
function_id: "stream::send",
diff --git a/src/hooks/session-end.ts b/src/hooks/session-end.ts
index bd652922..61895918 100644
--- a/src/hooks/session-end.ts
+++ b/src/hooks/session-end.ts
@@ -70,7 +70,7 @@ async function main() {
transcriptPrompts.map((prompt, index) =>
captureObservation(
withEventId(
- { hookType: "prompt_submit", sessionId, project, cwd, timestamp, data: { prompt } },
+ { hookType: "prompt_submit", sessionId, project, cwd, timestamp, data: { prompt, backfill: true } },
{},
{ source: "transcript", transcript: data.transcript_path, index, prompt },
{ stable: true },
diff --git a/src/state/schema.ts b/src/state/schema.ts
index 1f2365f9..eaecb6de 100644
--- a/src/state/schema.ts
+++ b/src/state/schema.ts
@@ -60,6 +60,7 @@ export const KV = {
obsSessionIndex: (shard: number) => `mem:idx:obs:${shard}`,
captureInbox: "mem:capture:inbox",
captureEvents: (shard: string) => `mem:capture:events:${shard}`,
+ capturePrompts: "mem:capture:prompts",
} as const;
export const STREAM = {
diff --git a/test/capture-backfill-prompts.test.ts b/test/capture-backfill-prompts.test.ts
new file mode 100644
index 00000000..656d3fd4
--- /dev/null
+++ b/test/capture-backfill-prompts.test.ts
@@ -0,0 +1,235 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mockKV, mockSdk } from "./helpers/mocks.js";
+import { KV } from "../src/state/schema.js";
+import { withEventId, type ObserveBody } from "../src/hooks/_capture.js";
+
+vi.mock("../src/logger.js", () => ({
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+type Kv = ReturnType<typeof mockKV>;
+
+const SESSION = "ses_cursor_backfill";
+const TRANSCRIPT = "/home/u/.cursor/projects/p/agent-transcripts/t.jsonl";
+
+async function boot(kv: Kv) {
+ const { registerObserveFunction } = await import("../src/functions/observe.js");
+ const { registerCaptureFunctions } = await import("../src/functions/capture.js");
+ const { DedupMap } = await import("../src/functions/dedup.js");
+ const sdk = mockSdk({ looseTrigger: true });
+ registerObserveFunction(sdk as never, kv as never, new DedupMap());
+ const controller = registerCaptureFunctions(sdk as never, kv as never, {});
+ const send = (body: ObserveBody) => {
+ const { eventId, ...payload } = body;
+ return sdk.trigger("mem::capture", { payload, eventId }) as Promise<Record<string, unknown>>;
+ };
+ return { send, controller };
+}
+
+function base(timestamp: string, data: Record<string, unknown>, sessionId = SESSION): ObserveBody {
+ return { hookType: "prompt_submit", sessionId, project: "proj", cwd: "/work/proj", timestamp, data };
+}
+
+function cursorLive(prompt: string, timestamp: string): ObserveBody {
+ const host = { conversation_id: SESSION, generation_id: "gen-1", hook_event_name: "beforeSubmitPrompt", prompt };
+ return withEventId(base(timestamp, { prompt }), host);
+}
+
+function backfill(prompt: string, index: number, timestamp = "2026-10-03T12:00:00.000Z"): ObserveBody {
+ return withEventId(
+ base(timestamp, { prompt, backfill: true }),
+ {},
+ { source: "transcript", transcript: TRANSCRIPT, index, prompt },
+ { stable: true },
+ );
+}
+
+function prompts(kv: Kv, sessionId = SESSION) {
+ return [...(kv.store.get(KV.observations(sessionId))?.values() ?? [])] as Array<{ id: string }>;
+}
+
+describe("transcript back-fill of prompts without a host prompt id", () => {
+ beforeEach(() => {
+ vi.resetModules();
+ });
+ afterEach(() => {
+ vi.unstubAllEnvs();
+ });
+
+ it("stores a prompt once when the back-fill replays a live capture", async () => {
+ const kv = mockKV();
+ const { send } = await boot(kv);
+ const live = cursorLive("fix the login bug", "2026-10-03T10:00:00.000Z");
+ const replay = backfill("fix the login bug", 0);
+ expect(live.eventId).not.toBe(replay.eventId);
+ expect(await send(live)).toMatchObject({ status: "accepted" });
+ expect(await send(replay)).toMatchObject({ status: "duplicate" });
+ expect(prompts(kv)).toHaveLength(1);
+ });
+
+ it("matches the back-fill when only whitespace differs", async () => {
+ const kv = mockKV();
+ const { send } = await boot(kv);
+ await send(cursorLive(" fix the\nlogin bug ", "2026-10-03T10:00:00.000Z"));
+ expect(await send(backfill("fix the login bug", 0))).toMatchObject({ status: "duplicate" });
+ expect(prompts(kv)).toHaveLength(1);
+ });
+
+ it("keeps two identical live prompts and absorbs a two-entry back-fill", async () => {
+ const kv = mockKV();
+ const { send } = await boot(kv);
+ await send(cursorLive("continue", "2026-10-03T10:00:00.000Z"));
+ await send(cursorLive("continue", "2026-10-03T10:00:05.000Z"));
+ expect(prompts(kv)).toHaveLength(2);
+ expect(await send(backfill("continue", 0))).toMatchObject({ status: "duplicate" });
+ expect(await send(backfill("continue", 1))).toMatchObject({ status: "duplicate" });
+ expect(prompts(kv)).toHaveLength(2);
+ });
+
+ it("stores the extra occurrence when the back-fill has more copies than were captured live", async () => {
+ const kv = mockKV();
+ const { send } = await boot(kv);
+ await send(cursorLive("continue", "2026-10-03T10:00:00.000Z"));
+ await send(backfill("continue", 0));
+ expect(await send(backfill("continue", 1))).toMatchObject({ status: "accepted" });
+ expect(prompts(kv)).toHaveLength(2);
+ });
+
+ it("stores a back-filled prompt that was never captured live", async () => {
+ const kv = mockKV();
+ const { send } = await boot(kv);
+ await send(cursorLive("first prompt", "2026-10-03T10:00:00.000Z"));
+ expect(await send(backfill("first prompt", 0))).toMatchObject({ status: "duplicate" });
+ expect(await send(backfill("prompt lost while the service was down", 1))).toMatchObject({ status: "accepted" });
+ expect(prompts(kv)).toHaveLength(2);
+ });
+
+ it("does not store the back-fill again when the session end hook runs twice", async () => {
+ const kv = mockKV();
+ const { send } = await boot(kv);
+ await send(cursorLive("continue", "2026-10-03T10:00:00.000Z"));
+ await send(backfill("continue", 0));
+ await send(backfill("never live", 1));
+ await send(backfill("continue", 0, "2026-10-03T13:00:00.000Z"));
+ await send(backfill("never live", 1, "2026-10-03T13:00:00.000Z"));
+ expect(prompts(kv)).toHaveLength(2);
+ });
+
+ it("keeps sessions apart", async () => {
+ const kv = mockKV();
+ const { send } = await boot(kv);
+ await send(cursorLive("continue", "2026-10-03T10:00:00.000Z"));
+ const other = withEventId(
+ base("2026-10-03T12:00:00.000Z", { prompt: "continue", backfill: true }, "ses_other_session"),
+ {},
+ { source: "transcript", transcript: TRANSCRIPT, index: 0, prompt: "continue" },
+ { stable: true },
+ );
+ expect(await send(other)).toMatchObject({ status: "accepted" });
+ expect(prompts(kv, "ses_other_session")).toHaveLength(1);
+ });
+
+ it("still matches after a restart between the live capture and the back-fill", async () => {
+ const kv = mockKV();
+ const first = await boot(kv);
+ await first.send(cursorLive("fix the login bug", "2026-10-03T10:00:00.000Z"));
+ vi.resetModules();
+ const second = await boot(kv);
+ expect(await second.send(backfill("fix the login bug", 0))).toMatchObject({ status: "duplicate" });
+ expect(prompts(kv)).toHaveLength(1);
+ });
+
+ it("drops idle ledgers on prune", async () => {
+ vi.stubEnv("AGENTMEMORY_CAPTURE_DEDUP_HOURS", "1");
+ const kv = mockKV();
+ const { send, controller } = await boot(kv);
+ await send(cursorLive("continue", "2026-10-03T10:00:00.000Z"));
+ const ledgers = kv.store.get(KV.capturePrompts)!;
+ expect(ledgers.size).toBe(1);
+ for (const ledger of ledgers.values()) (ledger as { updatedAt: string }).updatedAt = "2020-01-01T00:00:00.000Z";
+ await controller.prune();
+ expect(ledgers.size).toBe(0);
+ });
+});
+
+describe("prompts with a host prompt id", () => {
+ beforeEach(() => {
+ vi.resetModules();
+ });
+
+ it("keeps the host derived id and stores the prompt once", async () => {
+ const kv = mockKV();
+ const { send } = await boot(kv);
+ const host = { session_id: SESSION, prompt_id: "prompt_0123456789", prompt: "continue" };
+ const live = withEventId(base("2026-10-03T10:00:00.000Z", { prompt: "continue" }), host);
+ const replay = withEventId(base("2026-10-03T12:00:00.000Z", { prompt: "continue" }), host, undefined, { stable: true });
+ expect(live.eventId).toMatch(/^evh_/);
+ expect(replay.eventId).toBe(live.eventId);
+ await send(live);
+ expect(await send(replay)).toMatchObject({ status: "duplicate" });
+ expect(prompts(kv)).toHaveLength(1);
+ });
+});
+
+describe("prompt ledger durability", () => {
+ beforeEach(() => {
+ vi.resetModules();
+ });
+
+ it("fails instead of treating an unreadable ledger as empty", async () => {
+ const { recordLivePrompt } = await import("../src/capture/prompt-ledger.js");
+ const kv = mockKV();
+ await recordLivePrompt(kv as never, SESSION, "continue", "obs_ref_one_aaaa");
+ const before = JSON.stringify([...kv.store.get(KV.capturePrompts)!.values()]);
+ const failing = { ...kv, get: async () => { throw new Error("state read timed out"); } };
+ await expect(recordLivePrompt(failing as never, SESSION, "continue", "obs_ref_two_bbbb")).rejects.toThrow("state read timed out");
+ expect(JSON.stringify([...kv.store.get(KV.capturePrompts)!.values()])).toBe(before);
+ });
+
+ it("answers a retried back-fill claim with the same identity without using another live slot", async () => {
+ const { recordLivePrompt, claimBackfillPrompt } = await import("../src/capture/prompt-ledger.js");
+ const kv = mockKV();
+ await recordLivePrompt(kv as never, SESSION, "continue", "obs_live_one_aaaa");
+ expect(await claimBackfillPrompt(kv as never, SESSION, "continue", "obs_fill_one_aaaa")).toBe(true);
+ expect(await claimBackfillPrompt(kv as never, SESSION, "continue", "obs_fill_one_aaaa")).toBe(true);
+ expect(await claimBackfillPrompt(kv as never, SESSION, "continue", "obs_fill_two_bbbb")).toBe(false);
+ await recordLivePrompt(kv as never, SESSION, "continue", "obs_live_one_aaaa");
+ expect(await claimBackfillPrompt(kv as never, SESSION, "continue", "obs_fill_two_bbbb")).toBe(false);
+ });
+
+ it("records the live prompt on a retry that finds the observation already stored", async () => {
+ const kv = mockKV();
+ const { registerObserveFunction } = await import("../src/functions/observe.js");
+ const sdk = mockSdk({ looseTrigger: true });
+ registerObserveFunction(sdk as never, kv as never);
+ const realSet = kv.set;
+ let failLedger = true;
+ kv.set = (async (scope: string, key: string, data: unknown) => {
+ if (scope === KV.capturePrompts && failLedger) {
+ failLedger = false;
+ throw new Error("ledger write failed");
+ }
+ return realSet(scope, key, data);
+ }) as typeof kv.set;
+ const live = {
+ hookType: "prompt_submit",
+ sessionId: SESSION,
+ project: "proj",
+ cwd: "/work/proj",
+ timestamp: "2026-10-03T10:00:00.000Z",
+ data: { prompt: "ship it" },
+ eventId: "evc_live_ship_it",
+ observationId: "obs_live_ship_it_0001",
+ };
+ await expect(sdk.trigger("mem::observe", live)).rejects.toThrow("ledger write failed");
+ expect(await sdk.trigger("mem::observe", live)).toMatchObject({ existing: true });
+ const fill = {
+ ...live,
+ data: { prompt: "ship it", backfill: true },
+ eventId: "evc_fill_ship_it",
+ observationId: "obs_fill_ship_it_0001",
+ };
+ expect(await sdk.trigger("mem::observe", fill)).toMatchObject({ deduplicated: true });
+ expect(prompts(kv)).toHaveLength(1);
+ });
+});
diff --git a/test/session-end-transcript.test.ts b/test/session-end-transcript.test.ts
index f48cf42d..9433b515 100644
--- a/test/session-end-transcript.test.ts
+++ b/test/session-end-transcript.test.ts
@@ -95,6 +95,7 @@ describe("session-end transcript prompt backfill", () => {
for (const p of observes) {
expect(p.body.hookType).toBe("prompt_submit");
expect(p.body.sessionId).toBe("ses_t1");
+ expect((p.body.data as { backfill?: unknown }).backfill).toBe(true);
}
const endIndex = posts.findIndex((p) => p.path.includes("/session/end"));
expect(endIndex).toBeGreaterThanOrEqual(0);