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): persist recall injections for prompt caching (#4143)
Zayn Jarvis167951eaa6d1
diff --git a/examples/pi-coding-agent-extension/README.md b/examples/pi-coding-agent-extension/README.mdindex 4397668ce..e2317a542 100644--- a/examples/pi-coding-agent-extension/README.md+++ b/examples/pi-coding-agent-extension/README.md@@ -118,6 +118,22 @@ All fields below live in `config.json`. Defaults are shown.| `recallLimit` | `10` | Legacy quota-scaling input converted to six coding quotas, not a final cap || `scoreThreshold` | `0.35` | Min relevance score (0–1) || `minQueryLength` | `3` | Skip recall for queries shorter than N characters |+| `recallLedger` | `true` | Persist injected blocks and re-apply them to historical user messages so provider prompt-prefix caches keep hitting |++### Recall injection ledger++Pi's `context` hook hands extensions a deep copy of the session messages, so+an injected `<openviking-context>` block is never written back to session+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+`~/.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.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/config.ts b/examples/pi-coding-agent-extension/config.tsindex e95ec05ea..3c85eebd5 100644--- a/examples/pi-coding-agent-extension/config.ts+++ b/examples/pi-coding-agent-extension/config.ts@@ -25,6 +25,7 @@ export interface OVConfig {recallPreferAbstract: boolean;recallLimit: number;recallLimitConfigured: boolean;+ recallLedger: boolean;scoreThreshold: number;minQueryLength: number;profileTokenBudget: number;@@ -66,6 +67,9 @@ const DEFAULT_CONFIG: OVConfig = {recallPreferAbstract: true,recallLimit: 10,recallLimitConfigured: false,+ // Persist injected recall blocks and re-apply them to historical user+ // messages so provider prompt-prefix caches keep hitting (#4137).+ recallLedger: true,scoreThreshold: 0.35,minQueryLength: 3,profileTokenBudget: 10000,@@ -144,6 +148,9 @@ export function loadConfig(extensionDir: string): OVConfig {config.recallQueryExpansion = process.env.OPENVIKING_RECALL_QUERY_EXPANSION === "off" ? "off" : "auto";config.recallQueryExpansionConfigured = true;}+ if (process.env.OPENVIKING_RECALL_LEDGER !== undefined) {+ config.recallLedger = envBool(process.env.OPENVIKING_RECALL_LEDGER, config.recallLedger);+ }config.recallLimit = clampInt(config.recallLimit, 1, 50, DEFAULT_CONFIG.recallLimit);config.recallMaxContentChars = clampInt(config.recallMaxContentChars, 100, 5000, DEFAULT_CONFIG.recallMaxContentChars);@@ -165,6 +172,7 @@ export function loadConfig(extensionDir: string): OVConfig {config.captureMode = config.captureMode === "keyword" ? "keyword" : "semantic";config.recallPeerScope = config.recallPeerScope === "actor" ? "actor" : "all";config.recallQueryExpansion = config.recallQueryExpansion === "off" ? "off" : "auto";+ config.recallLedger = config.recallLedger !== false;if (!Array.isArray(config.bypassPatterns)) config.bypassPatterns = [];config.peerId = resolveEffectivePeerId({ cfg: config as any, cwd: process.cwd() }).peerId;return config;diff --git a/examples/pi-coding-agent-extension/index.ts b/examples/pi-coding-agent-extension/index.tsindex 20ceaeaeb..33b06de6f 100644--- a/examples/pi-coding-agent-extension/index.ts+++ b/examples/pi-coding-agent-extension/index.ts@@ -15,6 +15,7 @@ import { dirname } from "node:path";import { loadConfigFromModuleUrl, type OVConfig } from "./config.js";import { OVClient } from "./client.js";import { RecallManager } from "./recall.js";+import { RecallLedger } from "./shared/recall-ledger.mjs";import { SyncManager } from "./sync.js";import { buildProfileBlock } from "./shared/profile-inject.mjs";import { guardVikingUriToolCall } from "./lib/uri-guard-adapter.mjs";@@ -31,7 +32,14 @@ export default async function (pi: ExtensionAPI) {// --- Initialize modules ---const client = new OVClient(config);const sync = new SyncManager(client, config);- const recall = new RecallManager(client, config, () => sync.sessionId);+ const recall = new RecallManager(+ client,+ config,+ () => sync.sessionId,+ // The ledger keeps request prefixes byte-stable for provider prompt+ // caches (#4137); it is per pi session and opened once the id is known.+ config.recallLedger ? new RecallLedger() : null,+ );const debugLog = (message: string) => {const file = process.env.OV_DEBUG_LOG;if (!file) return;@@ -84,6 +92,7 @@ export default async function (pi: ExtensionAPI) {// Ensure OV sessionconst piSessionId = ctx.sessionManager.getSessionId();+ recall.openLedger(piSessionId);const ok = await sync.ensureSession(piSessionId);if (!ok) {if (config.logLevel !== "silent") {diff --git a/examples/pi-coding-agent-extension/recall.ts b/examples/pi-coding-agent-extension/recall.tsindex 400033d00..ef6397100 100644--- a/examples/pi-coding-agent-extension/recall.ts+++ b/examples/pi-coding-agent-extension/recall.ts@@ -1,6 +1,7 @@import type { OVClient } from "./client.js";import type { OVConfig } from "./config.js";import { buildRecallBlock } from "./shared/recall-core.mjs";+import { RecallLedger, ledgerKey } from "./shared/recall-ledger.mjs";export interface RecallCache {block: string | null;@@ -15,11 +16,23 @@ export class RecallManager {// Read lazily: the session manager that owns this id is constructed after the// recall manager, and the id only exists once a session has been opened.private sessionId: () => string | null;+ private ledger: RecallLedger | null;- constructor(client: OVClient, config: OVConfig, sessionId: () => string | null = () => null) {+ constructor(+ client: OVClient,+ config: OVConfig,+ sessionId: () => string | null = () => null,+ ledger: RecallLedger | null = null,+ ) {this.client = client;this.config = config;this.sessionId = sessionId;+ this.ledger = ledger;+ }++ /** Bind the injection ledger to the pi session (idempotent). */+ openLedger(piSessionId: string): void {+ this.ledger?.open(piSessionId);}queueSearch(userQuery: string): void {@@ -57,35 +70,57 @@ export class RecallManager {// --- Injection ---+ /**+ * Inject recall into the deep-copied provider view of the session.+ *+ * Two passes keep the request prefix byte-identical across turns (#4137):+ * historical user messages get the exact block the ledger says was sent+ * 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[] {- if (!this.cache.block) return messages;+ const ledger = this.ledger?.isOpen ? this.ledger : null;+ if (!this.cache.block && !ledger) return messages;- // Find the user message (scan backwards)+ // Locate the newest user message; everything before it is history.+ let lastUserIndex = -1;for (let i = messages.length - 1; i >= 0; i--) {+ if (messages[i].role === "user") {+ lastUserIndex = i;+ break;+ }+ }+ if (lastUserIndex === -1) return messages;++ let ordinal = 0;+ for (let i = 0; i <= lastUserIndex; i++) {const msg = messages[i];- if (msg.role === "user") {- // Idempotency check- const content = typeof msg.content === "string"- ? msg.content- : Array.isArray(msg.content)- ? msg.content.filter((b: any) => b.type === "text").map((b: any) => b.text).join("")- : "";+ if (msg.role !== "user") continue;+ const content = textOf(msg);+ const isNewest = i === lastUserIndex;- if (content.includes("<openviking-context")) break;+ // Idempotency: never stack a second block onto an already-injected copy.+ if (content.includes("<openviking-context")) {+ ordinal++;+ continue;+ }- // Prepend block to user message+ if (isNewest) {const block = this.cache.block;- if (typeof msg.content === "string") {- msg.content = block + "\n" + msg.content;- } else if (Array.isArray(msg.content)) {- const textBlocks = msg.content.filter((b: any) => b.type === "text");- if (textBlocks.length > 0) {- (textBlocks[0] as any).text = block + "\n" + (textBlocks[0] as any).text;- }+ if (block) {+ 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);}- break;+ } else if (ledger) {+ const block = ledger.get(ledgerKey(ordinal, content));+ if (block) prependBlock(msg, block);}+ ordinal++;}++ ledger?.flush();return messages;}@@ -94,3 +129,22 @@ export class RecallManager {this.pendingPrompt = "";}}++function textOf(msg: any): string {+ return typeof msg.content === "string"+ ? msg.content+ : Array.isArray(msg.content)+ ? msg.content.filter((b: any) => b.type === "text").map((b: any) => b.text).join("")+ : "";+}++function prependBlock(msg: any, block: string): void {+ if (typeof msg.content === "string") {+ msg.content = block + "\n" + msg.content;+ } else if (Array.isArray(msg.content)) {+ const textBlocks = msg.content.filter((b: any) => b.type === "text");+ if (textBlocks.length > 0) {+ (textBlocks[0] as any).text = block + "\n" + (textBlocks[0] as any).text;+ }+ }+}diff --git a/examples/pi-coding-agent-extension/shared/recall-ledger.d.mts b/examples/pi-coding-agent-extension/shared/recall-ledger.d.mtsnew file mode 100644index 000000000..68f389ecf--- /dev/null+++ b/examples/pi-coding-agent-extension/shared/recall-ledger.d.mts@@ -0,0 +1,10 @@+export declare function defaultLedgerDir(): string;+export declare function ledgerKey(ordinal: number, originalContent: string): string;+export declare class RecallLedger {+ constructor(dir?: string);+ open(sessionId: string): void;+ get isOpen(): boolean;+ get(key: string): string | null;+ record(key: string, block: string): void;+ flush(): void;+}diff --git a/examples/pi-coding-agent-extension/shared/recall-ledger.mjs b/examples/pi-coding-agent-extension/shared/recall-ledger.mjsnew file mode 100644index 000000000..42ee6c22c--- /dev/null+++ b/examples/pi-coding-agent-extension/shared/recall-ledger.mjs@@ -0,0 +1,126 @@+/**+ * Persistent per-session ledger of recall blocks injected into user messages.+ *+ * Pi's context hook hands extensions a deep copy of the session messages, so+ * a block prepended to a user message is never written back to session+ * storage. On the next request the history is rebuilt without it, and the+ * request prefix no longer matches what the provider cached last turn —+ * strict-prefix caches (DeepSeek and other OpenAI-compatible providers) then+ * 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+ * 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.+ *+ * Storage follows the pending-queue convention: one JSON file per pi session+ * under `~/.openviking/pi-recall-ledger/` (0o700), overridable with+ * OPENVIKING_RECALL_LEDGER_DIR. Losing the file (fresh machine, cleanup) only+ * costs one cache miss per historical message; alignment resumes on the next+ * turn because re-injection re-records as it goes.+ */+import { mkdirSync, readFileSync, writeFileSync, renameSync, chmodSync } from "node:fs";+import { join } from "node:path";+import { homedir } from "node:os";+import { createHash } from "node:crypto";++const LEDGER_DIR_MODE = 0o700;+const LEDGER_FILE_MODE = 0o600;+/** Bounded so a very long session cannot grow the file without limit. */+const MAX_ENTRIES = 500;+const LEDGER_VERSION = 1;++export function defaultLedgerDir() {+ return process.env.OPENVIKING_RECALL_LEDGER_DIR+ || join(homedir(), ".openviking", "pi-recall-ledger");+}++/**+ * 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.+ */+export function ledgerKey(ordinal, originalContent) {+ const digest = createHash("sha256").update(originalContent).digest("hex").slice(0, 16);+ return `${ordinal}:${digest}`;+}++export class RecallLedger {+ constructor(dir = defaultLedgerDir()) {+ this.dir = dir;+ this.sessionId = null;+ this.entries = new Map();+ this.loaded = false;+ this.dirty = false;+ }++ /** Bind to a pi session and load its file. Safe to call repeatedly. */+ open(sessionId) {+ if (!sessionId || sessionId === this.sessionId) return;+ this.sessionId = sessionId;+ this.entries.clear();+ this.loaded = false;+ try {+ const raw = readFileSync(this.filePath(), "utf-8");+ const data = JSON.parse(raw);+ if (data && data.version === LEDGER_VERSION && Array.isArray(data.entries)) {+ for (const e of data.entries) {+ if (typeof e?.key === "string" && typeof e?.block === "string") {+ this.entries.set(e.key, e.block);+ }+ }+ }+ } catch {+ // Missing or corrupt file: start empty. Costs one miss, never breaks pi.+ }+ this.loaded = true;+ }++ get isOpen() {+ return this.loaded && this.sessionId !== null;+ }++ get(key) {+ return this.entries.get(key) ?? null;+ }++ /** Record an injected block. Call flush() once per context event afterwards. */+ record(key, block) {+ if (this.entries.get(key) === block) return;+ this.entries.set(key, block);+ while (this.entries.size > MAX_ENTRIES) {+ const oldest = this.entries.keys().next().value;+ if (oldest === undefined) break;+ this.entries.delete(oldest);+ }+ this.dirty = true;+ }++ /** Atomic write (tmp + rename), same durability pattern as pending-queue. */+ flush() {+ if (!this.dirty || !this.sessionId) return;+ try {+ mkdirSync(this.dir, { recursive: true, mode: LEDGER_DIR_MODE });+ try { chmodSync(this.dir, LEDGER_DIR_MODE); } catch { /* pre-existing dir */ }+ const payload = JSON.stringify({+ version: LEDGER_VERSION,+ entries: [...this.entries].map(([key, block]) => ({ key, block })),+ });+ const tmp = this.filePath() + ".tmp";+ writeFileSync(tmp, payload, { mode: LEDGER_FILE_MODE });+ renameSync(tmp, this.filePath());+ this.dirty = false;+ } catch {+ // Best effort; persistence failure degrades to the pre-ledger behaviour.+ }+ }++ filePath() {+ // Session ids are uuids today; sanitize anyway so a hostile id cannot escape the dir.+ const safe = String(this.sessionId).replace(/[^A-Za-z0-9._-]/g, "_");+ return join(this.dir, `${safe}.json`);+ }+}diff --git a/examples/pi-coding-agent-extension/tests/recall-ledger.test.mjs b/examples/pi-coding-agent-extension/tests/recall-ledger.test.mjsnew file mode 100644index 000000000..8e189df74--- /dev/null+++ b/examples/pi-coding-agent-extension/tests/recall-ledger.test.mjs@@ -0,0 +1,189 @@+import test from "node:test";+import assert from "node:assert/strict";+import { mkdtempSync, readFileSync, writeFileSync, readdirSync } from "node:fs";+import { join } from "node:path";+import { tmpdir } from "node:os";+import { RecallManager } from "../recall.ts";+import { RecallLedger, ledgerKey } from "../shared/recall-ledger.mjs";++function config(overrides = {}) {+ return {+ minQueryLength: 3,+ recallLimit: 6,+ recallMaxContentChars: 500,+ recallTokenBudget: 2000,+ scoreThreshold: 0.35,+ peerId: "",+ ...overrides,+ };+}++function clientReturning(rendered) {+ return { fetchJSON: async () => ({ ok: true, result: { 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) {+ recall.client = clientReturning(block);+ const last = history[history.length - 1].content;+ const prompt = typeof last === "string"+ ? last+ : last.filter((b) => b.type === "text").map((b) => b.text).join("");+ recall.queueSearch(prompt);+ await recall.searchPending();+ const view = structuredClone(history);+ return recall.injectRecall(view);+}++test("historical user messages get their original block back, so the request prefix is stable across turns (#4137)", async () => {+ const dir = mkdtempSync(join(tmpdir(), "ov-ledger-"));+ const recall = new RecallManager(clientReturning(""), config(), () => null, new RecallLedger(dir));+ recall.openLedger("session-1");++ // Turn 1: [u1] with recall block b1+ const sent1 = await turn(recall, "- b1 memory", [+ { role: "user", content: "u1 prompt" },+ ]);+ assert.match(sent1[0].content, /b1 memory/);++ recall.invalidate(); // agent_end++ // Turn 2: history rebuilt from storage WITHOUT b1; new block b2 for u2.+ const sent2 = await turn(recall, "- b2 memory", [+ { role: "user", content: "u1 prompt" },+ { role: "assistant", content: "a1" },+ { role: "user", content: "u2 prompt" },+ ]);++ // The bytes for u1 this turn must equal the bytes sent last turn.+ assert.equal(sent2[0].content, sent1[0].content, "u1 prefix must be byte-identical to turn 1");+ assert.match(sent2[2].content, /b2 memory/);++ recall.invalidate();++ // Turn 3 after a process restart: a brand-new manager + ledger from disk.+ const restarted = new RecallManager(clientReturning(""), config(), () => null, new RecallLedger(dir));+ restarted.openLedger("session-1");+ const sent3 = await turn(restarted, "- b3 memory", [+ { role: "user", content: "u1 prompt" },+ { role: "assistant", content: "a1" },+ { role: "user", content: "u2 prompt" },+ { role: "assistant", content: "a2" },+ { role: "user", content: "u3 prompt" },+ ]);+ assert.equal(sent3[0].content, sent1[0].content, "u1 survives restart");+ assert.equal(sent3[2].content, sent2[2].content, "u2 survives restart");+ assert.match(sent3[4].content, /b3 memory/);+});++test("repeated identical prompts keep distinct blocks via the ordinal in the key", async () => {+ const dir = mkdtempSync(join(tmpdir(), "ov-ledger-"));+ const recall = new RecallManager(clientReturning(""), config(), () => null, new RecallLedger(dir));+ recall.openLedger("session-2");++ const sent1 = await turn(recall, "- first continue block", [+ { role: "user", content: "continue" },+ ]);+ recall.invalidate();+ const sent2 = await turn(recall, "- second continue block", [+ { role: "user", content: "continue" },+ { role: "assistant", content: "a1" },+ { role: "user", content: "continue" },+ ]);++ assert.equal(sent2[0].content, sent1[0].content);+ assert.match(sent2[2].content, /second continue block/);+ assert.doesNotMatch(sent2[2].content, /first continue block/);+});++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));+ recall.openLedger("session-3");++ const sent1 = await turn(recall, "- unused", [{ role: "user", content: "x" }]);+ assert.equal(sent1[0].content, "x");+ recall.invalidate();++ const sent2 = await turn(recall, "- b2", [+ { role: "user", content: "x" },+ { role: "assistant", content: "a1" },+ { role: "user", content: "real second prompt" },+ ]);+ assert.equal(sent2[0].content, "x", "no phantom block for a message that never had one");+ assert.match(sent2[2].content, /b2/);+});++test("rewritten history (stale ordinals) 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");++ await turn(recall, "- b1", [{ role: "user", content: "u1 prompt" }]);+ recall.invalidate();++ // Compaction dropped u1; a different message now sits at ordinal 0.+ const sent = await turn(recall, "- b2", [+ { role: "user", content: "totally different message" },+ { role: "assistant", content: "a" },+ { role: "user", content: "u2 prompt" },+ ]);+ assert.equal(sent[0].content, "totally different message");+});++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));+ recall.openLedger("session-5");++ const sent1 = await turn(recall, "- b1", [+ { role: "user", content: [{ type: "text", text: "u1 prompt" }] },+ ]);+ assert.match(sent1[0].content[0].text, /b1/);+ recall.invalidate();++ const sent2 = await turn(recall, "- b2", [+ { role: "user", content: [{ type: "text", text: "u1 prompt" }] },+ { role: "assistant", content: "a1" },+ { role: "user", content: [{ type: "text", text: "u2 prompt" }] },+ ]);+ assert.equal(sent2[0].content[0].text, sent1[0].content[0].text);+ assert.match(sent2[2].content[0].text, /b2/);+});++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.flush();++ const files = readdirSync(dir).filter((f) => f.endsWith(".json"));+ assert.equal(files.length, 1);+ writeFileSync(join(dir, files[0]), "{not json");++ const recall = new RecallManager(clientReturning(""), config(), () => null, new RecallLedger(dir));+ recall.openLedger("session-6");+ const sent = await turn(recall, "- b2", [+ { role: "user", content: "u1 prompt" },+ { role: "assistant", content: "a1" },+ { role: "user", content: "u2 prompt" },+ ]);+ assert.equal(sent[0].content, "u1 prompt");+ assert.match(sent[2].content, /b2/);+});++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.flush();++ const files = readdirSync(dir);+ assert.deepEqual(files, ["session-7.json"]);+ const data = JSON.parse(readFileSync(join(dir, "session-7.json"), "utf-8"));+ assert.equal(data.version, 1);+ assert.equal(data.entries.length, 1);+});