Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(pi-extension): key recall ledger by stable entry ids (#4237)

Zayn Jarvis69dd1d6556e9
diff --git a/examples/pi-coding-agent-extension/README.md b/examples/pi-coding-agent-extension/README.md
index e2317a542..fbc9ef366 100644
--- a/examples/pi-coding-agent-extension/README.md
+++ b/examples/pi-coding-agent-extension/README.md
@@ -128,12 +128,14 @@ storage. Without compensation, every request's history diverges from what the
provider saw last turn, and strict-prefix prompt caches (DeepSeek and other
OpenAI-compatible providers) miss from the first injected message onward
(#4137). The ledger records exactly which block was injected into which user
-message (keyed by position + content hash) in
+message (keyed by stable Pi entry id + content hash) in
`~/.openviking/pi-recall-ledger/<session>.json` and re-applies them on every
request, keeping the prefix byte-identical across turns while the newest
message still gets fresh, current-query recall. Disable with
`"recallLedger": false` or `OPENVIKING_RECALL_LEDGER=0`. Losing the ledger
-file only costs one cache miss; alignment resumes on the next turn.
+file only costs one cache miss; alignment resumes on the next turn. Stable
+entry ids let compacted retained messages and `/tree` branches recover their
+own original blocks even when active-context positions change.
Explicit `recallLimit` values from 1 through 5 produce an effective total
quota of 6 because each coding category keeps one retrieval slot. Direct API
diff --git a/examples/pi-coding-agent-extension/index.ts b/examples/pi-coding-agent-extension/index.ts
index 33b06de6f..13c216341 100644
--- a/examples/pi-coding-agent-extension/index.ts
+++ b/examples/pi-coding-agent-extension/index.ts
@@ -167,17 +167,37 @@ export default async function (pi: ExtensionAPI) {
});
// --- context ---
- pi.on("context", async (event, _ctx) => {
+ pi.on("context", async (event, ctx) => {
if (!connected || bypassed) return;
// Keep recall synchronous with the provider request so the current prompt
// still receives current-query memory, without blocking user-message UI.
await recall.searchPending();
+ // The context hook omits persisted entry ids, but its user messages are a
+ // deep copy of the active SessionManager context. Associate those objects
+ // with stable ids before takeover may filter the array; retained messages
+ // keep object identity through that transform.
+ const userEntryIds = ctx.sessionManager.buildContextEntries()
+ .filter((entry: any) => entry?.type === "message" && entry.message?.role === "user")
+ .map((entry: any) => entry.id as string);
+ const messageIds = new WeakMap<object, string>();
+ let userIndex = 0;
+ for (const message of event.messages as any[]) {
+ if (message?.role !== "user") continue;
+ const entryId = userEntryIds[userIndex++];
+ if (entryId && typeof message === "object") {
+ messageIds.set(message, entryId);
+ }
+ }
+
const afterTakeover = config.takeoverEnabled
? takeover.transformContext(event.messages as any)
: event.messages;
- const messages = recall.injectRecall(afterTakeover);
+ const messages = recall.injectRecall(
+ afterTakeover,
+ (message) => messageIds.get(message) ?? null,
+ );
return { messages };
});
diff --git a/examples/pi-coding-agent-extension/recall.ts b/examples/pi-coding-agent-extension/recall.ts
index ef6397100..70a701e04 100644
--- a/examples/pi-coding-agent-extension/recall.ts
+++ b/examples/pi-coding-agent-extension/recall.ts
@@ -78,7 +78,10 @@ export class RecallManager {
* with them before, and only the newest user message receives this turn's
* fresh block (which is then recorded for future re-injection).
*/
- injectRecall(messages: any[]): any[] {
+ injectRecall(
+ messages: any[],
+ messageIdFor: (message: any) => string | null = () => null,
+ ): any[] {
const ledger = this.ledger?.isOpen ? this.ledger : null;
if (!this.cache.block && !ledger) return messages;
@@ -92,16 +95,19 @@ export class RecallManager {
}
if (lastUserIndex === -1) return messages;
- let ordinal = 0;
for (let i = 0; i <= lastUserIndex; i++) {
const msg = messages[i];
if (msg.role !== "user") continue;
const content = textOf(msg);
const isNewest = i === lastUserIndex;
+ // Pi entry ids survive compaction and branch navigation. Missing ids
+ // fail closed: fresh recall may still reach the newest message, but no
+ // historical block is replayed or recorded under an unstable ordinal.
+ const messageIdentity = messageIdFor(msg);
+ const key = messageIdentity ? ledgerKey(messageIdentity, content) : null;
// Idempotency: never stack a second block onto an already-injected copy.
if (content.includes("<openviking-context")) {
- ordinal++;
continue;
}
@@ -111,13 +117,12 @@ export class RecallManager {
prependBlock(msg, block);
// Key by the ORIGINAL content: that is what the next turn's deep
// copy of this message will contain.
- ledger?.record(ledgerKey(ordinal, content), block);
+ if (key) ledger?.record(key, block);
}
- } else if (ledger) {
- const block = ledger.get(ledgerKey(ordinal, content));
+ } else if (ledger && key) {
+ const block = ledger.get(key);
if (block) prependBlock(msg, block);
}
- ordinal++;
}
ledger?.flush();
diff --git a/examples/pi-coding-agent-extension/shared/recall-ledger.d.mts b/examples/pi-coding-agent-extension/shared/recall-ledger.d.mts
index 68f389ecf..cb1968b31 100644
--- a/examples/pi-coding-agent-extension/shared/recall-ledger.d.mts
+++ b/examples/pi-coding-agent-extension/shared/recall-ledger.d.mts
@@ -1,5 +1,5 @@
export declare function defaultLedgerDir(): string;
-export declare function ledgerKey(ordinal: number, originalContent: string): string;
+export declare function ledgerKey(messageIdentity: string, originalContent: string): string;
export declare class RecallLedger {
constructor(dir?: string);
open(sessionId: string): void;
diff --git a/examples/pi-coding-agent-extension/shared/recall-ledger.mjs b/examples/pi-coding-agent-extension/shared/recall-ledger.mjs
index 42ee6c22c..dee498e75 100644
--- a/examples/pi-coding-agent-extension/shared/recall-ledger.mjs
+++ b/examples/pi-coding-agent-extension/shared/recall-ledger.mjs
@@ -9,8 +9,8 @@
* miss from the first divergent token (#4137).
*
* The ledger fixes that on the extension side: it records exactly which block
- * was injected into which user message, keyed by the message's position and a
- * hash of its ORIGINAL (un-injected) content. On every context event the
+ * was injected into which user message, keyed by the stable Pi session-entry
+ * id and a hash of its ORIGINAL (un-injected) content. On every context event the
* recorded blocks are re-applied to the historical user messages in the fresh
* deep copy, so the bytes sent to the provider this turn are identical to the
* bytes sent last turn, and only the newest user message extends the prefix.
@@ -38,14 +38,13 @@ export function defaultLedgerDir() {
}
/**
- * Key = user-message ordinal + hash of the original content. The ordinal
- * disambiguates repeated identical prompts ("continue"); the hash guards
- * against injecting into the wrong message after history is rewritten
- * (compaction, takeover), where a stale ordinal must simply miss.
+ * Key = stable Pi session-entry id + hash of the original content. Entry ids
+ * survive compaction and /tree navigation, disambiguate repeated identical
+ * prompts, and remain unique across branches in the same session.
*/
-export function ledgerKey(ordinal, originalContent) {
+export function ledgerKey(messageIdentity, originalContent) {
const digest = createHash("sha256").update(originalContent).digest("hex").slice(0, 16);
- return `${ordinal}:${digest}`;
+ return `${messageIdentity}:${digest}`;
}
export class RecallLedger {
diff --git a/examples/pi-coding-agent-extension/tests/recall-ledger.test.mjs b/examples/pi-coding-agent-extension/tests/recall-ledger.test.mjs
index 8e189df74..93b9daef7 100644
--- a/examples/pi-coding-agent-extension/tests/recall-ledger.test.mjs
+++ b/examples/pi-coding-agent-extension/tests/recall-ledger.test.mjs
@@ -24,7 +24,7 @@ function clientReturning(rendered) {
/** One provider request: run recall for the newest prompt, then inject into a
* fresh deep copy of the history — exactly what pi's context hook sees. */
-async function turn(recall, block, history) {
+async function turn(recall, block, history, userEntryIds = null) {
recall.client = clientReturning(block);
const last = history[history.length - 1].content;
const prompt = typeof last === "string"
@@ -33,7 +33,17 @@ async function turn(recall, block, history) {
recall.queueSearch(prompt);
await recall.searchPending();
const view = structuredClone(history);
- return recall.injectRecall(view);
+ const entryIds = userEntryIds ?? view
+ .filter((message) => message.role === "user")
+ .map((_, index) => `entry-${index}`);
+ const messageIds = new WeakMap();
+ let userIndex = 0;
+ for (const message of view) {
+ if (message.role !== "user") continue;
+ const entryId = entryIds[userIndex++];
+ if (entryId) messageIds.set(message, entryId);
+ }
+ return recall.injectRecall(view, (message) => messageIds.get(message) ?? null);
}
test("historical user messages get their original block back, so the request prefix is stable across turns (#4137)", async () => {
@@ -77,7 +87,7 @@ test("historical user messages get their original block back, so the request pre
assert.match(sent3[4].content, /b3 memory/);
});
-test("repeated identical prompts keep distinct blocks via the ordinal in the key", async () => {
+test("repeated identical prompts keep distinct blocks via stable entry ids", async () => {
const dir = mkdtempSync(join(tmpdir(), "ov-ledger-"));
const recall = new RecallManager(clientReturning(""), config(), () => null, new RecallLedger(dir));
recall.openLedger("session-2");
@@ -97,6 +107,26 @@ test("repeated identical prompts keep distinct blocks via the ordinal in the key
assert.doesNotMatch(sent2[2].content, /first continue block/);
});
+test("missing entry ids fail closed without recording ordinal keys", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "ov-ledger-"));
+ const recall = new RecallManager(clientReturning(""), config(), () => null, new RecallLedger(dir));
+ recall.openLedger("session-no-ids");
+
+ const sent1 = await turn(recall, "- fresh b1", [
+ { role: "user", content: "u1 prompt" },
+ ], [null]);
+ assert.match(sent1[0].content, /fresh b1/);
+ recall.invalidate();
+
+ const sent2 = await turn(recall, "- fresh b2", [
+ { role: "user", content: "u1 prompt" },
+ { role: "assistant", content: "a1" },
+ { role: "user", content: "u2 prompt" },
+ ], [null, null]);
+ assert.equal(sent2[0].content, "u1 prompt", "historical message must not replay an ordinal key");
+ assert.match(sent2[2].content, /fresh b2/);
+});
+
test("a short prompt records nothing and history it appears in stays un-injected", async () => {
const dir = mkdtempSync(join(tmpdir(), "ov-ledger-"));
const recall = new RecallManager(clientReturning(""), config(), () => null, new RecallLedger(dir));
@@ -115,7 +145,7 @@ test("a short prompt records nothing and history it appears in stays un-injected
assert.match(sent2[2].content, /b2/);
});
-test("rewritten history (stale ordinals) misses cleanly instead of injecting into the wrong message", async () => {
+test("rewritten history misses cleanly instead of injecting into the wrong message", async () => {
const dir = mkdtempSync(join(tmpdir(), "ov-ledger-"));
const recall = new RecallManager(clientReturning(""), config(), () => null, new RecallLedger(dir));
recall.openLedger("session-4");
@@ -132,6 +162,55 @@ test("rewritten history (stale ordinals) misses cleanly instead of injecting int
assert.equal(sent[0].content, "totally different message");
});
+test("stable entry ids restore the right blocks across compaction and /tree navigation", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "ov-ledger-"));
+ const recall = new RecallManager(clientReturning(""), config(), () => null, new RecallLedger(dir));
+ recall.openLedger("session-compact");
+
+ const beforeCompact = await turn(recall, "- first continue block", [
+ { role: "user", content: "continue" },
+ ], ["entry-0"]);
+ recall.invalidate();
+
+ // Record another identical prompt at a later position before compaction.
+ const longHistory = await turn(recall, "- retained continue block", [
+ { role: "user", content: "continue" },
+ { role: "assistant", content: "a0" },
+ { role: "user", content: "u1" },
+ { role: "assistant", content: "a1" },
+ { role: "user", content: "u2" },
+ { role: "assistant", content: "a2" },
+ { role: "user", content: "u3" },
+ { role: "assistant", content: "a3" },
+ { role: "user", content: "u4" },
+ { role: "assistant", content: "a4" },
+ { role: "user", content: "continue" },
+ ], ["entry-0", "entry-1", "entry-2", "entry-3", "entry-4", "entry-5"]);
+ recall.invalidate();
+
+ // Compaction keeps entry-5 but renumbers it from user position 5 to 0. Its
+ // stable id must restore its own block, not entry-0's same-text block.
+ const afterCompact = await turn(recall, "- post-compact block", [
+ { role: "compactionSummary", summary: "older history", content: "" },
+ { role: "user", content: "continue" },
+ { role: "assistant", content: "a5" },
+ { role: "user", content: "new prompt after compaction" },
+ ], ["entry-5", "entry-6"]);
+ assert.equal(afterCompact[1].content, longHistory[10].content);
+ assert.doesNotMatch(afterCompact[1].content, /first continue block/);
+ recall.invalidate();
+
+ // /tree can return to the pre-compaction branch. The original entry id must
+ // recover the exact bytes that branch sent before compaction.
+ const afterTreeBack = await turn(recall, "- tree branch block", [
+ { role: "user", content: "continue" },
+ { role: "assistant", content: "a0" },
+ { role: "user", content: "new prompt on old branch" },
+ ], ["entry-0", "entry-tree"]);
+ assert.equal(afterTreeBack[0].content, beforeCompact[0].content);
+ assert.doesNotMatch(afterTreeBack[0].content, /retained continue block/);
+});
+
test("array-content user messages round-trip through the ledger", async () => {
const dir = mkdtempSync(join(tmpdir(), "ov-ledger-"));
const recall = new RecallManager(clientReturning(""), config(), () => null, new RecallLedger(dir));
@@ -156,7 +235,7 @@ test("a corrupt ledger file degrades to pre-ledger behaviour", async () => {
const dir = mkdtempSync(join(tmpdir(), "ov-ledger-"));
const ledgerA = new RecallLedger(dir);
ledgerA.open("session-6");
- ledgerA.record(ledgerKey(0, "u1 prompt"), "- b1");
+ ledgerA.record(ledgerKey("entry-corrupt", "u1 prompt"), "- b1");
ledgerA.flush();
const files = readdirSync(dir).filter((f) => f.endsWith(".json"));
@@ -178,7 +257,7 @@ test("ledger file is written atomically with owner-only permissions", async () =
const dir = mkdtempSync(join(tmpdir(), "ov-ledger-"));
const ledger = new RecallLedger(dir);
ledger.open("session-7");
- ledger.record(ledgerKey(0, "u1"), "- b1");
+ ledger.record(ledgerKey("entry-permissions", "u1"), "- b1");
ledger.flush();
const files = readdirSync(dir);