#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
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.mjsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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);