Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
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.mdindex 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 theprovider saw last turn, and strict-prefix prompt caches (DeepSeek and otherOpenAI-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 everyrequest, keeping the prefix byte-identical across turns while the newestmessage 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 totalquota of 6 because each coding category keeps one retrieval slot. Direct APIdiff --git a/examples/pi-coding-agent-extension/index.ts b/examples/pi-coding-agent-extension/index.tsindex 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.tsindex 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.mtsindex 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.mjsindex 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.mjsindex 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 preassert.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 keyassert.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-injectedassert.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 intassert.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);