Skip to content

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

perf(plugins): batch add-message writes and shared async detach across memory plugins (#3261)

t0saki6f10e263618b
diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
index 34812fd7a..7e9259d58 100644
--- a/.github/workflows/pr.yml
+++ b/.github/workflows/pr.yml
@@ -43,6 +43,7 @@ jobs:
examples/claude-code-memory-plugin/scripts/lib/pending-queue.test.mjs \
examples/cursor-memory-plugin/scripts/cursor-plugin.test.mjs \
examples/trae-memory-hooks/scripts/trae-hooks.test.mjs \
+ examples/memory-plugin-shared/batch-send.test.mjs \
examples/memory-plugin-shared/install-agent-hooks.test.mjs \
examples/memory-plugin-shared/install-opencode-jsonc.test.mjs \
examples/memory-plugin-shared/install-tui.test.mjs \
diff --git a/examples/claude-code-memory-plugin/.claude-plugin/plugin.json b/examples/claude-code-memory-plugin/.claude-plugin/plugin.json
index b56d6d1cc..edb729849 100644
--- a/examples/claude-code-memory-plugin/.claude-plugin/plugin.json
+++ b/examples/claude-code-memory-plugin/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "openviking-memory",
- "version": "0.4.2",
+ "version": "0.4.3",
"description": "Long-term semantic memory for Claude Code, powered by OpenViking. Auto-recall relevant memories at session start and capture important information during conversations.",
"author": {
"name": "OpenViking",
diff --git a/examples/claude-code-memory-plugin/package-lock.json b/examples/claude-code-memory-plugin/package-lock.json
index cf80125b6..5a1c0e9a8 100644
--- a/examples/claude-code-memory-plugin/package-lock.json
+++ b/examples/claude-code-memory-plugin/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "claude-code-openviking-memory",
- "version": "0.4.2",
+ "version": "0.4.3",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "claude-code-openviking-memory",
- "version": "0.4.2",
+ "version": "0.4.3",
"dependencies": {
"@modelcontextprotocol/sdk": "^1.12.1",
"zod": "^4.3.6"
diff --git a/examples/claude-code-memory-plugin/package.json b/examples/claude-code-memory-plugin/package.json
index 199e7a0a8..b8218b070 100644
--- a/examples/claude-code-memory-plugin/package.json
+++ b/examples/claude-code-memory-plugin/package.json
@@ -1,6 +1,6 @@
{
"name": "claude-code-openviking-memory",
- "version": "0.4.2",
+ "version": "0.4.3",
"description": "OpenViking memory plugin for Claude Code — semantic long-term memory",
"type": "module",
"scripts": {
diff --git a/examples/claude-code-memory-plugin/scripts/auto-capture.mjs b/examples/claude-code-memory-plugin/scripts/auto-capture.mjs
index bb2293fd8..f89601171 100644
--- a/examples/claude-code-memory-plugin/scripts/auto-capture.mjs
+++ b/examples/claude-code-memory-plugin/scripts/auto-capture.mjs
@@ -25,7 +25,6 @@ import { tmpdir } from "node:os";
import { isPluginEnabled, loadConfig } from "./config.mjs";
import { createLogger } from "./debug-log.mjs";
import {
- addMessage,
commitSession,
deriveOvSessionId,
enqueuePendingDirectly,
@@ -37,6 +36,7 @@ import {
import { maybeDetach, readHookStdin } from "./lib/async-writer.mjs";
import { readJsonState, writeJsonState } from "./lib/state.mjs";
import { getEffectivePeerId } from "./lib/workspace-peer.mjs";
+import { sendSessionMessages } from "./shared/batch-send.mjs";
if (!isPluginEnabled()) {
process.stdout.write(JSON.stringify({ decision: "approve" }) + "\n");
@@ -393,10 +393,7 @@ function sanitizePartsForSend(parts) {
}
async function pushTurnsToOv(ovSessionId, turns, peerId = "") {
- let ok = 0;
- let queued = 0;
- let failed = 0;
- let enqueueFailed = 0;
+ const payloads = [];
for (const turn of turns) {
// Send structured parts: tool calls/results are dedicated `tool` parts, not
// inlined into content, so the server can process them separately.
@@ -405,13 +402,12 @@ async function pushTurnsToOv(ovSessionId, turns, peerId = "") {
const payload = { role: turn.role, parts };
if (peerId) payload.peer_id = peerId;
- const res = await addMessage(fetchJSON, ovSessionId, payload);
- if (res.ok) ok++;
- else if (res.pendingQueued) queued++;
- else if (res.pendingEnqueueFailed) enqueueFailed++;
- else failed++;
+ payloads.push(payload);
}
- return { ok, queued, failed, enqueueFailed };
+ const res = await sendSessionMessages(fetchJSON, ovSessionId, payloads, {
+ enqueueOnRetryable: true,
+ });
+ return { ok: res.sent, queued: res.queued, failed: res.failed, enqueueFailed: res.enqueueFailed };
}
async function enqueueTurnsToPending(ovSessionId, turns, peerId = "") {
diff --git a/examples/claude-code-memory-plugin/scripts/lib/async-writer.mjs b/examples/claude-code-memory-plugin/scripts/lib/async-writer.mjs
index 93c0cebbb..a885f2e21 100644
--- a/examples/claude-code-memory-plugin/scripts/lib/async-writer.mjs
+++ b/examples/claude-code-memory-plugin/scripts/lib/async-writer.mjs
@@ -1,79 +1 @@
-/**
- * Async write-path helper.
- *
- * When `cfg.writePathAsync` is true and we're not already the worker, we:
- * 1. Drain the parent's stdin (the hook payload from CC)
- * 2. Emit `{decision:"approve"}` on stdout so CC unblocks immediately
- * 3. Spawn a detached clone of ourselves with env OV_HOOK_WORKER=1
- * 4. Feed the drained payload to the worker's stdin, unref, and exit
- *
- * The worker re-enters the same script, maybeDetach returns false (because
- * OV_HOOK_WORKER=1), and the hook's normal synchronous code path reads its
- * own stdin and runs the OV HTTP work with nobody waiting.
- *
- * Call this BEFORE the hook reads stdin itself. When it returns true, the
- * caller must `return` out of main() immediately.
- */
-
-import { spawn } from "node:child_process";
-
-const WORKER_ENV = "OV_HOOK_WORKER";
-
-export async function maybeDetach(cfg, { approve }) {
- if (!cfg.writePathAsync) return false;
- if (process.env[WORKER_ENV] === "1") return false;
-
- // Drain parent stdin so we can forward to the worker.
- let raw;
- try {
- const chunks = [];
- for await (const chunk of process.stdin) chunks.push(chunk);
- raw = Buffer.concat(chunks);
- } catch {
- // stdin read failed — let the synchronous path handle it (safer than
- // silently losing the event).
- return false;
- }
-
- let child;
- try {
- child = spawn(process.execPath, [process.argv[1]], {
- detached: true,
- stdio: ["pipe", "ignore", "ignore"],
- env: { ...process.env, [WORKER_ENV]: "1" },
- });
- } catch {
- // spawn failed — fall through to sync mode, but we've already drained
- // stdin so hand the payload back via env var path below.
- process.env.OPENVIKING_HOOK_STDIN_CACHE = raw.toString();
- return false;
- }
-
- // Approve CC first, then write to the detached child. Ordering matters:
- // CC reads our stdout before waiting for exit, so approving here is what
- // unblocks the user turn.
- approve();
-
- try {
- child.stdin.write(raw);
- child.stdin.end();
- } catch { /* worker may have already exited; nothing useful to recover */ }
- child.unref();
- return true;
-}
-
-/**
- * Fallback stdin reader used when the async path drained stdin but spawn
- * failed; hooks should call this instead of reading stdin directly when
- * possible so the sync fallback still works after a failed detach.
- */
-export async function readHookStdin() {
- if (process.env.OPENVIKING_HOOK_STDIN_CACHE) {
- const cached = process.env.OPENVIKING_HOOK_STDIN_CACHE;
- delete process.env.OPENVIKING_HOOK_STDIN_CACHE;
- return cached;
- }
- const chunks = [];
- for await (const chunk of process.stdin) chunks.push(chunk);
- return Buffer.concat(chunks).toString();
-}
+export * from "../shared/async-writer.mjs";
diff --git a/examples/claude-code-memory-plugin/scripts/shared/async-writer.mjs b/examples/claude-code-memory-plugin/scripts/shared/async-writer.mjs
new file mode 100644
index 000000000..8ffc71468
--- /dev/null
+++ b/examples/claude-code-memory-plugin/scripts/shared/async-writer.mjs
@@ -0,0 +1,78 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+/**
+ * Async write-path helper for hook-based memory plugins.
+ *
+ * When `cfg.writePathAsync` is true and we're not already the worker, we:
+ * 1. Drain the parent's stdin (the hook payload)
+ * 2. Emit the harness-specific approve/no-op response on stdout immediately
+ * 3. Spawn a detached clone of ourselves with env OV_HOOK_WORKER=1
+ * 4. Feed the drained payload to the worker's stdin, unref, and exit
+ *
+ * The worker re-enters the same script, maybeDetach returns false (because
+ * OV_HOOK_WORKER=1), and the hook's normal synchronous code path reads its
+ * own stdin and runs the OV HTTP work with nobody waiting.
+ *
+ * Call this BEFORE the hook reads stdin itself. When it returns true, the
+ * caller must `return` out of main() immediately.
+ */
+
+import { spawn } from "node:child_process";
+
+const WORKER_ENV = "OV_HOOK_WORKER";
+
+export async function maybeDetach(cfg, { approve }) {
+ if (!cfg.writePathAsync) return false;
+ if (process.env[WORKER_ENV] === "1") return false;
+
+ // Drain parent stdin so we can forward to the worker.
+ let raw;
+ try {
+ const chunks = [];
+ for await (const chunk of process.stdin) chunks.push(chunk);
+ raw = Buffer.concat(chunks);
+ } catch {
+ // stdin read failed - let the synchronous path handle it.
+ return false;
+ }
+
+ let child;
+ try {
+ child = spawn(process.execPath, [process.argv[1]], {
+ detached: true,
+ stdio: ["pipe", "ignore", "ignore"],
+ env: { ...process.env, [WORKER_ENV]: "1" },
+ });
+ } catch {
+ // spawn failed - fall through to sync mode, but we've already drained
+ // stdin so hand the payload back via env var path below.
+ process.env.OPENVIKING_HOOK_STDIN_CACHE = raw.toString();
+ return false;
+ }
+
+ // Approve first, then write to the detached child. Ordering matters for
+ // harnesses that read stdout before waiting for the hook process to exit.
+ approve();
+
+ try {
+ child.stdin.write(raw);
+ child.stdin.end();
+ } catch { /* worker may have already exited; nothing useful to recover */ }
+ child.unref();
+ return true;
+}
+
+/**
+ * Fallback stdin reader used when the async path drained stdin but spawn
+ * failed; hooks should call this instead of reading stdin directly when
+ * possible so the sync fallback still works after a failed detach.
+ */
+export async function readHookStdin() {
+ if (process.env.OPENVIKING_HOOK_STDIN_CACHE) {
+ const cached = process.env.OPENVIKING_HOOK_STDIN_CACHE;
+ delete process.env.OPENVIKING_HOOK_STDIN_CACHE;
+ return cached;
+ }
+ const chunks = [];
+ for await (const chunk of process.stdin) chunks.push(chunk);
+ return Buffer.concat(chunks).toString();
+}
diff --git a/examples/claude-code-memory-plugin/scripts/shared/batch-send.mjs b/examples/claude-code-memory-plugin/scripts/shared/batch-send.mjs
new file mode 100644
index 000000000..6d929d6bf
--- /dev/null
+++ b/examples/claude-code-memory-plugin/scripts/shared/batch-send.mjs
@@ -0,0 +1,122 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+import { enqueue } from "./pending-queue.mjs";
+
+export const BATCH_LIMIT = 100;
+
+export function isRetryableSendFailure(res) {
+ if (!res || res.ok) return false;
+ const status = Number(res.status || 0);
+ return !status || status === 408 || status === 429 || status >= 500;
+}
+
+function makeResult() {
+ return {
+ sent: 0,
+ queued: 0,
+ enqueueFailed: 0,
+ failed: 0,
+ retryable: false,
+ usedBatch: true,
+ lastError: null,
+ };
+}
+
+async function enqueueRemainder(sessionId, payloads, startIndex, result, retryable, lastError) {
+ result.retryable = retryable;
+ result.lastError = lastError ?? null;
+
+ if (!retryable) {
+ result.failed += Math.max(0, payloads.length - startIndex);
+ return result;
+ }
+
+ const baseCreatedAt = Date.now();
+ for (let i = startIndex; i < payloads.length; i++) {
+ const queued = await enqueue("addMessage", sessionId, payloads[i], {
+ createdAt: baseCreatedAt + (i - startIndex),
+ });
+ if (!queued.ok) {
+ // Stop at the first enqueue failure so queued entries stay a contiguous
+ // prefix: consumers mark the first sent+queued payloads as captured, so
+ // skipping a payload here and queueing a later one would silently drop it.
+ result.enqueueFailed += payloads.length - i;
+ return result;
+ }
+ result.queued++;
+ }
+ return result;
+}
+
+async function sendSerial(fetchJSON, sessionId, payloads, startIndex, opts, result) {
+ result.usedBatch = false;
+ const encodedSid = encodeURIComponent(sessionId);
+ for (let i = startIndex; i < payloads.length; i++) {
+ const res = await fetchJSON(`/api/v1/sessions/${encodedSid}/messages`, {
+ method: "POST",
+ body: JSON.stringify(payloads[i]),
+ });
+ if (res?.ok) {
+ result.sent++;
+ await opts.onSent?.(1);
+ continue;
+ }
+
+ const retryable = isRetryableSendFailure(res);
+ if (opts.enqueueOnRetryable) {
+ return enqueueRemainder(sessionId, payloads, i, result, retryable, res?.error ?? res);
+ }
+ result.retryable = retryable;
+ result.lastError = res?.error ?? res ?? null;
+ result.failed += payloads.length - i;
+ return result;
+ }
+ return result;
+}
+
+/**
+ * Send add-message payloads in server-sized batches with serial fallback.
+ *
+ * @param {Function} fetchJSON - (path, init) => { ok, status, result?, error? }
+ * @param {string} sessionId - OpenViking session id
+ * @param {Array<object>} payloads - sanitized add-message request bodies
+ * @param {object} opts
+ * @param {boolean} opts.enqueueOnRetryable - enqueue unsent payloads after a retryable failure
+ * @param {Function} opts.onSent - called with the number of messages durably sent after each success
+ * @returns {Promise<{sent:number,queued:number,enqueueFailed:number,failed:number,retryable:boolean,usedBatch:boolean,lastError:any}>}
+ */
+export async function sendSessionMessages(fetchJSON, sessionId, payloads, opts = {}) {
+ const result = makeResult();
+ const messages = Array.isArray(payloads) ? payloads : [];
+ if (messages.length === 0) return result;
+
+ const encodedSid = encodeURIComponent(sessionId);
+ for (let start = 0; start < messages.length; start += BATCH_LIMIT) {
+ const chunk = messages.slice(start, start + BATCH_LIMIT);
+ const res = await fetchJSON(`/api/v1/sessions/${encodedSid}/messages/batch`, {
+ method: "POST",
+ body: JSON.stringify({ messages: chunk }),
+ });
+
+ if (res?.ok) {
+ result.sent += chunk.length;
+ await opts.onSent?.(chunk.length);
+ continue;
+ }
+
+ const status = Number(res?.status || 0);
+ if (status === 404 || status === 405) {
+ return sendSerial(fetchJSON, sessionId, messages, start, opts, result);
+ }
+
+ const retryable = isRetryableSendFailure(res);
+ if (opts.enqueueOnRetryable) {
+ return enqueueRemainder(sessionId, messages, start, result, retryable, res?.error ?? res);
+ }
+ result.retryable = retryable;
+ result.lastError = res?.error ?? res ?? null;
+ result.failed += messages.length - start;
+ return result;
+ }
+
+ return result;
+}
diff --git a/examples/claude-code-memory-plugin/scripts/shared/pending-queue.mjs b/examples/claude-code-memory-plugin/scripts/shared/pending-queue.mjs
index cbf6d445f..16e4da0dc 100644
--- a/examples/claude-code-memory-plugin/scripts/shared/pending-queue.mjs
+++ b/examples/claude-code-memory-plugin/scripts/shared/pending-queue.mjs
@@ -182,10 +182,12 @@ async function recoverStaleProcessing(dir) {
* @param {string} type - "addMessage" or "commitSession"
* @param {string} sessionId - OV session ID
* @param {object} payload - the data that failed to send
+ * @param {object} options
+ * @param {number} options.createdAt - optional queue timestamp override
*/
-export async function enqueue(type, sessionId, payload) {
+export async function enqueue(type, sessionId, payload, options = {}) {
const dir = getPendingDir();
- const now = Date.now();
+ const now = Number.isFinite(options.createdAt) ? options.createdAt : Date.now();
const dedupKey = makeDedupKey(type, sessionId, payload);
const filename = pendingFilename(dedupKey, 0);
const entry = {
diff --git a/examples/claude-code-memory-plugin/scripts/subagent-stop.mjs b/examples/claude-code-memory-plugin/scripts/subagent-stop.mjs
index 9b45ad6d4..946aa4677 100644
--- a/examples/claude-code-memory-plugin/scripts/subagent-stop.mjs
+++ b/examples/claude-code-memory-plugin/scripts/subagent-stop.mjs
@@ -22,7 +22,6 @@ import { tmpdir } from "node:os";
import { isPluginEnabled, loadConfig } from "./config.mjs";
import { createLogger } from "./debug-log.mjs";
import {
- addMessage,
commitSession,
deriveOvSessionId,
enqueuePendingDirectly,
@@ -32,6 +31,7 @@ import {
} from "./lib/ov-session.mjs";
import { maybeDetach, readHookStdin } from "./lib/async-writer.mjs";
import { getEffectivePeerId } from "./lib/workspace-peer.mjs";
+import { sendSessionMessages } from "./shared/batch-send.mjs";
if (!isPluginEnabled()) {
process.stdout.write(JSON.stringify({ decision: "approve" }) + "\n");
@@ -239,6 +239,7 @@ async function pushTurns(ovSessionId, turns, { peerId = null, enqueueOnly = fals
let queued = 0;
let failed = 0;
let enqueueFailed = 0;
+ const payloads = [];
for (const turn of turns) {
// Send structured parts: tool calls/results are dedicated `tool` parts, not
// inlined into content, so the server can process them separately.
@@ -248,14 +249,22 @@ async function pushTurns(ovSessionId, turns, { peerId = null, enqueueOnly = fals
if (parts.length === 0) continue;
const payload = { role: turn.role, parts };
if (peerId) payload.peer_id = peerId;
- const res = enqueueOnly
- ? await enqueuePendingDirectly("addMessage", ovSessionId, payload)
- : await addMessage(fetchJSON, ovSessionId, payload);
- if (enqueueOnly && res.ok) queued++;
- else if (res.ok) ok++;
- else if (res.pendingQueued) queued++;
- else if (res.pendingEnqueueFailed || enqueueOnly) enqueueFailed++;
- else failed++;
+ if (enqueueOnly) {
+ const res = await enqueuePendingDirectly("addMessage", ovSessionId, payload);
+ if (res.ok) queued++;
+ else enqueueFailed++;
+ } else {
+ payloads.push(payload);
+ }
+ }
+ if (!enqueueOnly) {
+ const res = await sendSessionMessages(fetchJSON, ovSessionId, payloads, {
+ enqueueOnRetryable: true,
+ });
+ ok = res.sent;
+ queued = res.queued;
+ failed = res.failed;
+ enqueueFailed = res.enqueueFailed;
}
// Commit once at the end; subagents are short-lived, so threshold tracking
// adds little value.
diff --git a/examples/codex-memory-plugin/.codex-plugin/plugin.json b/examples/codex-memory-plugin/.codex-plugin/plugin.json
index 1328fd4b8..bca752031 100644
--- a/examples/codex-memory-plugin/.codex-plugin/plugin.json
+++ b/examples/codex-memory-plugin/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "openviking-memory",
- "version": "0.7.2",
+ "version": "0.7.3",
"description": "Long-term semantic memory for Codex, powered by OpenViking. Recall on UserPromptSubmit, incremental add_message on Stop (per turn), commit on PreCompact, and active-window heuristic + idle-TTL sweep on SessionStart (source=startup|clear). Includes a local stdio MCP proxy that reads OpenViking credentials from env/ovcli.conf.",
"author": {
"name": "OpenViking",
diff --git a/examples/codex-memory-plugin/scripts/auto-capture.mjs b/examples/codex-memory-plugin/scripts/auto-capture.mjs
index c97e5f529..4eac34972 100644
--- a/examples/codex-memory-plugin/scripts/auto-capture.mjs
+++ b/examples/codex-memory-plugin/scripts/auto-capture.mjs
@@ -32,6 +32,8 @@ import {
import { loadConfig } from "./config.mjs";
import { createLogger } from "./debug-log.mjs";
import { loadState, resolveOvSessionId, saveState } from "./session-state.mjs";
+import { maybeDetach, readHookStdin } from "./shared/async-writer.mjs";
+import { sendSessionMessages } from "./shared/batch-send.mjs";
import { resolveEffectivePeerId } from "./shared/workspace-peer.mjs";
const cfg = loadConfig();
@@ -46,30 +48,41 @@ function noop(message) {
output(message ? { systemMessage: message } : {});
}
-async function fetchJSON(path, init = {}) {
+function makeHeaders() {
+ const headers = { "Content-Type": "application/json" };
+ if (cfg.apiKey) {
+ headers["Authorization"] = `Bearer ${cfg.apiKey}`;
+ headers["X-API-Key"] = cfg.apiKey;
+ }
+ if (cfg.sendIdentityHeaders && cfg.account) headers["X-OpenViking-Account"] = cfg.account;
+ if (cfg.sendIdentityHeaders && cfg.user) headers["X-OpenViking-User"] = cfg.user;
+ if (activePeerId) headers["X-OpenViking-Actor-Peer"] = activePeerId;
+ return headers;
+}
+
+async function fetchJSONRes(path, init = {}) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), cfg.captureTimeoutMs);
try {
- const headers = { "Content-Type": "application/json" };
- if (cfg.apiKey) {
- headers["Authorization"] = `Bearer ${cfg.apiKey}`;
- headers["X-API-Key"] = cfg.apiKey;
- }
- if (cfg.sendIdentityHeaders && cfg.account) headers["X-OpenViking-Account"] = cfg.account;
- if (cfg.sendIdentityHeaders && cfg.user) headers["X-OpenViking-User"] = cfg.user;
- if (activePeerId) headers["X-OpenViking-Actor-Peer"] = activePeerId;
- const res = await fetch(`${cfg.baseUrl}${path}`, { ...init, headers, signal: controller.signal });
+ const res = await fetch(`${cfg.baseUrl}${path}`, { ...init, headers: makeHeaders(), signal: controller.signal });
const body = await res.json().catch(() => null);
- if (!body) return null;
- if (!res.ok || body.status === "error") return null;
- return body.result ?? body;
- } catch {
- return null;
+ if (!body) return { ok: false, status: res.status, error: { message: "empty or invalid JSON response" } };
+ if (!res.ok || body.status === "error") {
+ return { ok: false, status: res.status, error: body.error || body };
+ }
+ return { ok: true, status: res.status, result: body.result ?? body };
+ } catch (err) {
+ return { ok: false, status: 0, error: { message: err?.message || String(err) } };
} finally {
clearTimeout(timer);
}
}
+async function fetchJSON(path, init = {}) {
+ const r = await fetchJSONRes(path, init);
+ return r.ok ? (r.result ?? null) : null;
+}
+
// ---------------------------------------------------------------------------
// Transcript parsing (JSONL rollout)
// ---------------------------------------------------------------------------
@@ -113,22 +126,20 @@ function selectStopTurns(state, turns) {
}
async function appendTurns(ovSessionId, turns, state) {
- let appended = 0;
- for (const turn of turns) {
+ const payloads = turns.map((turn) => {
const body = turn.parts?.length
? { role: turn.role, parts: turn.parts }
: { role: turn.role, content: turn.text };
if (activePeerId) body.peer_id = activePeerId;
- const result = await fetchJSON(`/api/v1/sessions/${encodeURIComponent(ovSessionId)}/messages`, {
- method: "POST",
- body: JSON.stringify(body),
- });
- if (!result) break;
- appended += 1;
- state.capturedTurnCount += 1;
- await saveState(state);
- }
- return appended;
+ return body;
+ });
+ const r = await sendSessionMessages(fetchJSONRes, ovSessionId, payloads, {
+ onSent: async (n) => {
+ state.capturedTurnCount += n;
+ await saveState(state);
+ },
+ });
+ return r.sent;
}
async function maybeCommitByThreshold(ovSessionId, added) {
@@ -171,11 +182,13 @@ async function main() {
return;
}
+ // Async write mode returns a no-op response immediately; worker stdout is
+ // intentionally discarded, so appended-count systemMessage is sync-only.
+ if (await maybeDetach(cfg, { approve: () => output({}) })) return;
+
let input;
try {
- const chunks = [];
- for await (const chunk of process.stdin) chunks.push(chunk);
- input = JSON.parse(Buffer.concat(chunks).toString());
+ input = JSON.parse(await readHookStdin());
} catch {
log("skip", { stage: "stdin_parse", reason: "invalid input" });
noop();
diff --git a/examples/codex-memory-plugin/scripts/auto-capture.test.mjs b/examples/codex-memory-plugin/scripts/auto-capture.test.mjs
index d50305c2d..ec464fecc 100644
--- a/examples/codex-memory-plugin/scripts/auto-capture.test.mjs
+++ b/examples/codex-memory-plugin/scripts/auto-capture.test.mjs
@@ -123,7 +123,7 @@ test("auto-capture commits when pending tokens cross threshold", async () => {
writeJson(res, { status: "ok", result: { ok: true } });
return;
}
- if (req.method === "POST" && url.pathname.endsWith("/messages")) {
+ if (req.method === "POST" && url.pathname.endsWith("/messages/batch")) {
calls[calls.length - 1].body = await readRequestBody(req);
writeJson(res, { status: "ok", result: { ok: true } });
return;
@@ -157,6 +157,7 @@ test("auto-capture commits when pending tokens cross threshold", async () => {
OPENVIKING_COMMIT_TOKEN_THRESHOLD: "1000",
OPENVIKING_COMMIT_KEEP_RECENT_COUNT: "7",
OPENVIKING_MIN_QUERY_LENGTH: "1",
+ OPENVIKING_WRITE_PATH_ASYNC: "0",
OPENVIKING_TIMEOUT_MS: "5000",
OPENVIKING_URL: baseUrl,
},
@@ -171,9 +172,11 @@ test("auto-capture commits when pending tokens cross threshold", async () => {
assert.ok(commitCall, `expected threshold commit call; calls=${JSON.stringify(calls)} debug=${debugLog}`);
assert.deepEqual(commitCall.body, { keep_recent_count: 7 });
+ const batchCall = calls.find((call) => call.path.endsWith("/messages/batch"));
+ assert.ok(batchCall, `expected batch add-message call; calls=${JSON.stringify(calls)}`);
const messageBodies = calls
- .filter((call) => call.path.endsWith("/messages"))
- .map((call) => call.body);
+ .filter((call) => call.path.endsWith("/messages") || call.path.endsWith("/messages/batch"))
+ .flatMap((call) => call.body?.messages ?? [call.body]);
const toolCallBody = messageBodies.find((body) =>
body.parts?.some((part) => part.type === "tool" && part.tool_status === "running")
);
diff --git a/examples/codex-memory-plugin/scripts/config.mjs b/examples/codex-memory-plugin/scripts/config.mjs
index efbabef5f..e211ff7d3 100644
--- a/examples/codex-memory-plugin/scripts/config.mjs
+++ b/examples/codex-memory-plugin/scripts/config.mjs
@@ -199,6 +199,7 @@ export function loadConfig() {
process.env.OPENVIKING_CAPTURE_TOOL_MAX_CHARS,
num(cx.captureToolMaxChars, 2000),
))),
+ writePathAsync: envBool("OPENVIKING_WRITE_PATH_ASYNC") ?? (cx.writePathAsync !== false),
// Default true: a "memory plugin" without assistant-side capture only sees half the
// conversation, which makes extraction noticeably worse. Mirrors the claude-code plugin
// (examples/claude-code-memory-plugin/scripts/config.mjs). Operators who want the old
diff --git a/examples/codex-memory-plugin/scripts/pre-compact-capture.mjs b/examples/codex-memory-plugin/scripts/pre-compact-capture.mjs
index 669b072ec..0d5c51b53 100644
--- a/examples/codex-memory-plugin/scripts/pre-compact-capture.mjs
+++ b/examples/codex-memory-plugin/scripts/pre-compact-capture.mjs
@@ -27,6 +27,7 @@ import {
import { loadConfig } from "./config.mjs";
import { createLogger } from "./debug-log.mjs";
import { loadState, resolveOvSessionId, saveState } from "./session-state.mjs";
+import { sendSessionMessages } from "./shared/batch-send.mjs";
import { resolveEffectivePeerId } from "./shared/workspace-peer.mjs";
const cfg = loadConfig();
@@ -41,30 +42,41 @@ function noop(message) {
output(message ? { systemMessage: message } : {});
}
-async function fetchJSON(path, init = {}) {
+function makeHeaders() {
+ const headers = { "Content-Type": "application/json" };
+ if (cfg.apiKey) {
+ headers["Authorization"] = `Bearer ${cfg.apiKey}`;
+ headers["X-API-Key"] = cfg.apiKey;
+ }
+ if (cfg.sendIdentityHeaders && cfg.account) headers["X-OpenViking-Account"] = cfg.account;
+ if (cfg.sendIdentityHeaders && cfg.user) headers["X-OpenViking-User"] = cfg.user;
+ if (activePeerId) headers["X-OpenViking-Actor-Peer"] = activePeerId;
+ return headers;
+}
+
+async function fetchJSONRes(path, init = {}) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), cfg.captureTimeoutMs);
try {
- const headers = { "Content-Type": "application/json" };
- if (cfg.apiKey) {
- headers["Authorization"] = `Bearer ${cfg.apiKey}`;
- headers["X-API-Key"] = cfg.apiKey;
- }
- if (cfg.sendIdentityHeaders && cfg.account) headers["X-OpenViking-Account"] = cfg.account;
- if (cfg.sendIdentityHeaders && cfg.user) headers["X-OpenViking-User"] = cfg.user;
- if (activePeerId) headers["X-OpenViking-Actor-Peer"] = activePeerId;
- const res = await fetch(`${cfg.baseUrl}${path}`, { ...init, headers, signal: controller.signal });
+ const res = await fetch(`${cfg.baseUrl}${path}`, { ...init, headers: makeHeaders(), signal: controller.signal });
const body = await res.json().catch(() => null);
- if (!body) return null;
- if (!res.ok || body.status === "error") return null;
- return body.result ?? body;
- } catch {
- return null;
+ if (!body) return { ok: false, status: res.status, error: { message: "empty or invalid JSON response" } };
+ if (!res.ok || body.status === "error") {
+ return { ok: false, status: res.status, error: body.error || body };
+ }
+ return { ok: true, status: res.status, result: body.result ?? body };
+ } catch (err) {
+ return { ok: false, status: 0, error: { message: err?.message || String(err) } };
} finally {
clearTimeout(timer);
}
}
+async function fetchJSON(path, init = {}) {
+ const r = await fetchJSONRes(path, init);
+ return r.ok ? (r.result ?? null) : null;
+}
+
function parseTranscript(content) {
try {
const data = JSON.parse(content);
@@ -95,20 +107,15 @@ async function readTranscriptTurns(transcriptPath) {
}
async function appendTurns(ovSessionId, turns) {
- let appended = 0;
- for (const turn of turns) {
+ const payloads = turns.map((turn) => {
const body = turn.parts?.length
? { role: turn.role, parts: turn.parts }
: { role: turn.role, content: turn.text };
if (activePeerId) body.peer_id = activePeerId;
- const result = await fetchJSON(`/api/v1/sessions/${encodeURIComponent(ovSessionId)}/messages`, {
- method: "POST",
- body: JSON.stringify(body),
- });
- if (!result) break;
- appended += 1;
- }
- return appended;
+ return body;
+ });
+ const r = await sendSessionMessages(fetchJSONRes, ovSessionId, payloads);
+ return r.sent;
}
async function main() {
diff --git a/examples/codex-memory-plugin/scripts/shared/async-writer.mjs b/examples/codex-memory-plugin/scripts/shared/async-writer.mjs
new file mode 100644
index 000000000..8ffc71468
--- /dev/null
+++ b/examples/codex-memory-plugin/scripts/shared/async-writer.mjs
@@ -0,0 +1,78 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+/**
+ * Async write-path helper for hook-based memory plugins.
+ *
+ * When `cfg.writePathAsync` is true and we're not already the worker, we:
+ * 1. Drain the parent's stdin (the hook payload)
+ * 2. Emit the harness-specific approve/no-op response on stdout immediately
+ * 3. Spawn a detached clone of ourselves with env OV_HOOK_WORKER=1
+ * 4. Feed the drained payload to the worker's stdin, unref, and exit
+ *
+ * The worker re-enters the same script, maybeDetach returns false (because
+ * OV_HOOK_WORKER=1), and the hook's normal synchronous code path reads its
+ * own stdin and runs the OV HTTP work with nobody waiting.
+ *
+ * Call this BEFORE the hook reads stdin itself. When it returns true, the
+ * caller must `return` out of main() immediately.
+ */
+
+import { spawn } from "node:child_process";
+
+const WORKER_ENV = "OV_HOOK_WORKER";
+
+export async function maybeDetach(cfg, { approve }) {
+ if (!cfg.writePathAsync) return false;
+ if (process.env[WORKER_ENV] === "1") return false;
+
+ // Drain parent stdin so we can forward to the worker.
+ let raw;
+ try {
+ const chunks = [];
+ for await (const chunk of process.stdin) chunks.push(chunk);
+ raw = Buffer.concat(chunks);
+ } catch {
+ // stdin read failed - let the synchronous path handle it.
+ return false;
+ }
+
+ let child;
+ try {
+ child = spawn(process.execPath, [process.argv[1]], {
+ detached: true,
+ stdio: ["pipe", "ignore", "ignore"],
+ env: { ...process.env, [WORKER_ENV]: "1" },
+ });
+ } catch {
+ // spawn failed - fall through to sync mode, but we've already drained
+ // stdin so hand the payload back via env var path below.
+ process.env.OPENVIKING_HOOK_STDIN_CACHE = raw.toString();
+ return false;
+ }
+
+ // Approve first, then write to the detached child. Ordering matters for
+ // harnesses that read stdout before waiting for the hook process to exit.
+ approve();
+
+ try {
+ child.stdin.write(raw);
+ child.stdin.end();
+ } catch { /* worker may have already exited; nothing useful to recover */ }
+ child.unref();
+ return true;
+}
+
+/**
+ * Fallback stdin reader used when the async path drained stdin but spawn
+ * failed; hooks should call this instead of reading stdin directly when
+ * possible so the sync fallback still works after a failed detach.
+ */
+export async function readHookStdin() {
+ if (process.env.OPENVIKING_HOOK_STDIN_CACHE) {
+ const cached = process.env.OPENVIKING_HOOK_STDIN_CACHE;
+ delete process.env.OPENVIKING_HOOK_STDIN_CACHE;
+ return cached;
+ }
+ const chunks = [];
+ for await (const chunk of process.stdin) chunks.push(chunk);
+ return Buffer.concat(chunks).toString();
+}
diff --git a/examples/codex-memory-plugin/scripts/shared/batch-send.mjs b/examples/codex-memory-plugin/scripts/shared/batch-send.mjs
new file mode 100644
index 000000000..6d929d6bf
--- /dev/null
+++ b/examples/codex-memory-plugin/scripts/shared/batch-send.mjs
@@ -0,0 +1,122 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+import { enqueue } from "./pending-queue.mjs";
+
+export const BATCH_LIMIT = 100;
+
+export function isRetryableSendFailure(res) {
+ if (!res || res.ok) return false;
+ const status = Number(res.status || 0);
+ return !status || status === 408 || status === 429 || status >= 500;
+}
+
+function makeResult() {
+ return {
+ sent: 0,
+ queued: 0,
+ enqueueFailed: 0,
+ failed: 0,
+ retryable: false,
+ usedBatch: true,
+ lastError: null,
+ };
+}
+
+async function enqueueRemainder(sessionId, payloads, startIndex, result, retryable, lastError) {
+ result.retryable = retryable;
+ result.lastError = lastError ?? null;
+
+ if (!retryable) {
+ result.failed += Math.max(0, payloads.length - startIndex);
+ return result;
+ }
+
+ const baseCreatedAt = Date.now();
+ for (let i = startIndex; i < payloads.length; i++) {
+ const queued = await enqueue("addMessage", sessionId, payloads[i], {
+ createdAt: baseCreatedAt + (i - startIndex),
+ });
+ if (!queued.ok) {
+ // Stop at the first enqueue failure so queued entries stay a contiguous
+ // prefix: consumers mark the first sent+queued payloads as captured, so
+ // skipping a payload here and queueing a later one would silently drop it.
+ result.enqueueFailed += payloads.length - i;
+ return result;
+ }
+ result.queued++;
+ }
+ return result;
+}
+
+async function sendSerial(fetchJSON, sessionId, payloads, startIndex, opts, result) {
+ result.usedBatch = false;
+ const encodedSid = encodeURIComponent(sessionId);
+ for (let i = startIndex; i < payloads.length; i++) {
+ const res = await fetchJSON(`/api/v1/sessions/${encodedSid}/messages`, {
+ method: "POST",
+ body: JSON.stringify(payloads[i]),
+ });
+ if (res?.ok) {
+ result.sent++;
+ await opts.onSent?.(1);
+ continue;
+ }
+
+ const retryable = isRetryableSendFailure(res);
+ if (opts.enqueueOnRetryable) {
+ return enqueueRemainder(sessionId, payloads, i, result, retryable, res?.error ?? res);
+ }
+ result.retryable = retryable;
+ result.lastError = res?.error ?? res ?? null;
+ result.failed += payloads.length - i;
+ return result;
+ }
+ return result;
+}
+
+/**
+ * Send add-message payloads in server-sized batches with serial fallback.
+ *
+ * @param {Function} fetchJSON - (path, init) => { ok, status, result?, error? }
+ * @param {string} sessionId - OpenViking session id
+ * @param {Array<object>} payloads - sanitized add-message request bodies
+ * @param {object} opts
+ * @param {boolean} opts.enqueueOnRetryable - enqueue unsent payloads after a retryable failure
+ * @param {Function} opts.onSent - called with the number of messages durably sent after each success
+ * @returns {Promise<{sent:number,queued:number,enqueueFailed:number,failed:number,retryable:boolean,usedBatch:boolean,lastError:any}>}
+ */
+export async function sendSessionMessages(fetchJSON, sessionId, payloads, opts = {}) {
+ const result = makeResult();
+ const messages = Array.isArray(payloads) ? payloads : [];
+ if (messages.length === 0) return result;
+
+ const encodedSid = encodeURIComponent(sessionId);
+ for (let start = 0; start < messages.length; start += BATCH_LIMIT) {
+ const chunk = messages.slice(start, start + BATCH_LIMIT);
+ const res = await fetchJSON(`/api/v1/sessions/${encodedSid}/messages/batch`, {
+ method: "POST",
+ body: JSON.stringify({ messages: chunk }),
+ });
+
+ if (res?.ok) {
+ result.sent += chunk.length;
+ await opts.onSent?.(chunk.length);
+ continue;
+ }
+
+ const status = Number(res?.status || 0);
+ if (status === 404 || status === 405) {
+ return sendSerial(fetchJSON, sessionId, messages, start, opts, result);
+ }
+
+ const retryable = isRetryableSendFailure(res);
+ if (opts.enqueueOnRetryable) {
+ return enqueueRemainder(sessionId, messages, start, result, retryable, res?.error ?? res);
+ }
+ result.retryable = retryable;
+ result.lastError = res?.error ?? res ?? null;
+ result.failed += messages.length - start;
+ return result;
+ }
+
+ return result;
+}
diff --git a/examples/codex-memory-plugin/scripts/shared/pending-queue.mjs b/examples/codex-memory-plugin/scripts/shared/pending-queue.mjs
index cbf6d445f..16e4da0dc 100644
--- a/examples/codex-memory-plugin/scripts/shared/pending-queue.mjs
+++ b/examples/codex-memory-plugin/scripts/shared/pending-queue.mjs
@@ -182,10 +182,12 @@ async function recoverStaleProcessing(dir) {
* @param {string} type - "addMessage" or "commitSession"
* @param {string} sessionId - OV session ID
* @param {object} payload - the data that failed to send
+ * @param {object} options
+ * @param {number} options.createdAt - optional queue timestamp override
*/
-export async function enqueue(type, sessionId, payload) {
+export async function enqueue(type, sessionId, payload, options = {}) {
const dir = getPendingDir();
- const now = Date.now();
+ const now = Number.isFinite(options.createdAt) ? options.createdAt : Date.now();
const dedupKey = makeDedupKey(type, sessionId, payload);
const filename = pendingFilename(dedupKey, 0);
const entry = {
diff --git a/examples/cursor-memory-plugin/.cursor-plugin/plugin.json b/examples/cursor-memory-plugin/.cursor-plugin/plugin.json
index 59cb54866..9f8ad045c 100644
--- a/examples/cursor-memory-plugin/.cursor-plugin/plugin.json
+++ b/examples/cursor-memory-plugin/.cursor-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "openviking-memory",
"displayName": "OpenViking Memory",
- "version": "0.1.1",
+ "version": "0.1.2",
"description": "Automatic long-term memory recall and conversation capture for Cursor",
"author": {
"name": "OpenViking"
diff --git a/examples/cursor-memory-plugin/openviking.integration.json b/examples/cursor-memory-plugin/openviking.integration.json
index 1630f4fb8..00b38d312 100644
--- a/examples/cursor-memory-plugin/openviking.integration.json
+++ b/examples/cursor-memory-plugin/openviking.integration.json
@@ -1,7 +1,7 @@
{
"schemaVersion": 1,
"id": "openviking-memory",
- "version": "0.1.1",
+ "version": "0.1.2",
"clients": ["cursor"],
"capabilities": ["hooks", "mcp", "rules", "skills"]
}
diff --git a/examples/cursor-memory-plugin/scripts/cursor-hook.mjs b/examples/cursor-memory-plugin/scripts/cursor-hook.mjs
index da1a05be0..1a0e22f22 100644
--- a/examples/cursor-memory-plugin/scripts/cursor-hook.mjs
+++ b/examples/cursor-memory-plugin/scripts/cursor-hook.mjs
@@ -4,7 +4,7 @@ import { readFile } from "node:fs/promises";
import { parseCursorTranscript } from "./cursor-transcript.mjs";
import {
- addAgentMessage,
+ addAgentMessages,
buildAgentProfile,
commitAgentSession,
createAgentLogger,
@@ -40,19 +40,18 @@ async function captureTranscript(input, state, sessionId) {
let turns = [];
try { turns = parseCursorTranscript(await readFile(transcriptPath, "utf8")); } catch { return { state, captured: 0 }; }
const capturedHashes = new Set(Array.isArray(state.capturedHashes) ? state.capturedHashes : []);
- let captured = 0;
+ const toSend = [];
for (const [index, turn] of turns.entries()) {
// Cursor transcripts do not expose a stable message id. Include the
// transcript position so two legitimate identical turns are retained,
// while duplicate Hook executions over the same transcript still dedupe.
const hash = stableHash(index, turn.role, turn.content);
if (capturedHashes.has(hash)) continue;
- const result = await addAgentMessage(fetchJSON, sessionId, turn);
- if (result.ok || [0, 408, 429].includes(result.status) || result.status >= 500) {
- capturedHashes.add(hash);
- captured += 1;
- }
+ toSend.push({ hash, turn });
}
+ const result = await addAgentMessages(fetchJSON, sessionId, toSend.map((item) => item.turn));
+ const captured = result.sent + result.queued;
+ for (const item of toSend.slice(0, captured)) capturedHashes.add(item.hash);
return {
captured,
state: {
diff --git a/examples/cursor-memory-plugin/scripts/cursor-plugin.test.mjs b/examples/cursor-memory-plugin/scripts/cursor-plugin.test.mjs
index adb74f3b6..760bf3f86 100644
--- a/examples/cursor-memory-plugin/scripts/cursor-plugin.test.mjs
+++ b/examples/cursor-memory-plugin/scripts/cursor-plugin.test.mjs
@@ -113,7 +113,8 @@ test("Cursor injects recall before the request and Stop captures transcript delt
actorPeers.push(request.headers["x-openviking-actor-peer"]);
response.end(JSON.stringify({ result: { rendered: "remembered context" } }));
} else if (request.url?.includes("/messages")) {
- messages.push(JSON.parse(body));
+ const parsed = JSON.parse(body);
+ messages.push(...(parsed.messages ?? [parsed]));
response.end(JSON.stringify({ result: { ok: true } }));
} else if (request.url?.endsWith("/commit")) {
response.end(JSON.stringify({ result: { ok: true } }));
@@ -172,7 +173,8 @@ test("Cursor replays offline capture on the next SessionStart", async () => {
response.end(JSON.stringify({ status: "error", error: "offline" }));
return;
}
- messages.push(JSON.parse(body));
+ const parsed = JSON.parse(body);
+ messages.push(...(parsed.messages ?? [parsed]));
}
response.end(JSON.stringify({ result: { ok: true } }));
});
diff --git a/examples/memory-plugin-shared/batch-send.test.mjs b/examples/memory-plugin-shared/batch-send.test.mjs
new file mode 100644
index 000000000..d5782fa31
--- /dev/null
+++ b/examples/memory-plugin-shared/batch-send.test.mjs
@@ -0,0 +1,212 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import { sendSessionMessages } from "./lib/batch-send.mjs";
+import { listPending } from "./lib/pending-queue.mjs";
+
+function payloads(count, offset = 0) {
+ return Array.from({ length: count }, (_, i) => ({
+ role: "user",
+ content: `message-${offset + i}`,
+ }));
+}
+
+function parseBody(init) {
+ return JSON.parse(init?.body || "{}");
+}
+
+async function withPendingDir(fn) {
+ const old = process.env.OPENVIKING_PENDING_DIR;
+ const dir = await mkdtemp(join(tmpdir(), "ov-batch-send-"));
+ process.env.OPENVIKING_PENDING_DIR = dir;
+ try {
+ return await fn(dir);
+ } finally {
+ if (old == null) delete process.env.OPENVIKING_PENDING_DIR;
+ else process.env.OPENVIKING_PENDING_DIR = old;
+ await rm(dir, { recursive: true, force: true });
+ }
+}
+
+test("sendSessionMessages chunks batches at the server limit", async () => {
+ const chunkSizes = [];
+ const onSent = [];
+ const res = await sendSessionMessages(
+ async (path, init) => {
+ assert.equal(path, "/api/v1/sessions/session-1/messages/batch");
+ const body = parseBody(init);
+ chunkSizes.push(body.messages.length);
+ return { ok: true, status: 200, result: { added: -1 } };
+ },
+ "session-1",
+ payloads(250),
+ { onSent: async (n) => onSent.push(n) },
+ );
+
+ assert.deepEqual(chunkSizes, [100, 100, 50]);
+ assert.deepEqual(onSent, [100, 100, 50]);
+ assert.deepEqual(res, {
+ sent: 250,
+ queued: 0,
+ enqueueFailed: 0,
+ failed: 0,
+ retryable: false,
+ usedBatch: true,
+ lastError: null,
+ });
+});
+
+for (const status of [404, 405]) {
+ test(`sendSessionMessages falls back to serial sends on batch ${status}`, async () => {
+ const calls = [];
+ const sentBodies = [];
+ const res = await sendSessionMessages(
+ async (path, init) => {
+ calls.push(path);
+ if (path.endsWith("/messages/batch")) return { ok: false, status, error: { message: "missing" } };
+ sentBodies.push(parseBody(init));
+ return { ok: true, status: 200, result: { ok: true } };
+ },
+ "legacy-server",
+ payloads(3),
+ );
+
+ assert.deepEqual(calls, [
+ "/api/v1/sessions/legacy-server/messages/batch",
+ "/api/v1/sessions/legacy-server/messages",
+ "/api/v1/sessions/legacy-server/messages",
+ "/api/v1/sessions/legacy-server/messages",
+ ]);
+ assert.deepEqual(sentBodies.map((body) => body.content), ["message-0", "message-1", "message-2"]);
+ assert.equal(res.sent, 3);
+ assert.equal(res.usedBatch, false);
+ assert.equal(res.failed, 0);
+ });
+}
+
+test("sendSessionMessages queues the unsent suffix after a retryable batch failure", async () => {
+ await withPendingDir(async (dir) => {
+ let batch = 0;
+ const res = await sendSessionMessages(
+ async () => {
+ batch += 1;
+ if (batch === 1) return { ok: true, status: 200, result: { ok: true } };
+ return { ok: false, status: 503, error: { message: "unavailable" } };
+ },
+ "retry-session",
+ payloads(250),
+ { enqueueOnRetryable: true },
+ );
+
+ assert.equal(res.sent, 100);
+ assert.equal(res.queued, 150);
+ assert.equal(res.failed, 0);
+ assert.equal(res.retryable, true);
+ assert.equal((await readdir(dir)).filter((name) => name.endsWith(".json")).length, 150);
+ const pending = await listPending();
+ assert.deepEqual(
+ pending.slice(0, 3).map(({ entry }) => entry.payload.content),
+ ["message-100", "message-101", "message-102"],
+ );
+ assert.ok(pending[1].entry.createdAt > pending[0].entry.createdAt);
+ });
+});
+
+test("sendSessionMessages treats non-retryable failures as failed without enqueueing", async () => {
+ await withPendingDir(async (dir) => {
+ const res = await sendSessionMessages(
+ async () => ({ ok: false, status: 400, error: { message: "bad request" } }),
+ "bad-session",
+ payloads(4),
+ { enqueueOnRetryable: true },
+ );
+
+ assert.equal(res.sent, 0);
+ assert.equal(res.queued, 0);
+ assert.equal(res.failed, 4);
+ assert.equal(res.retryable, false);
+ assert.equal((await readdir(dir).catch(() => [])).filter((name) => name.endsWith(".json")).length, 0);
+ });
+});
+
+test("sendSessionMessages treats missing status failures as retryable", async () => {
+ await withPendingDir(async () => {
+ const res = await sendSessionMessages(
+ async () => ({ ok: false, error: { message: "network-ish" } }),
+ "unknown-status",
+ payloads(2),
+ { enqueueOnRetryable: true },
+ );
+
+ assert.equal(res.sent, 0);
+ assert.equal(res.queued, 2);
+ assert.equal(res.failed, 0);
+ assert.equal(res.retryable, true);
+ });
+});
+
+test("sendSessionMessages stops queueing at the first enqueue failure to keep the queued prefix contiguous", async () => {
+ await withPendingDir(async (dir) => {
+ // Poison the second payload's pending filename: the pre-created garbage
+ // file triggers EEXIST on write and defeats the dedup-recovery read, so
+ // enqueue reports ok:false for exactly that payload. Filename layout
+ // mirrors pending-queue.mjs makeDedupKey/pendingFilename.
+ const dedupKey = createHash("sha256")
+ .update("addMessage")
+ .update("\n")
+ .update("prefix-session")
+ .update("\n")
+ .update('{"content":"message-1","role":"user"}')
+ .digest("hex");
+ await writeFile(join(dir, `${dedupKey}_0.json`), "not json", "utf-8");
+
+ const res = await sendSessionMessages(
+ async () => ({ ok: false, status: 503, error: { message: "unavailable" } }),
+ "prefix-session",
+ payloads(3),
+ { enqueueOnRetryable: true },
+ );
+
+ // message-0 queued, message-1 failed to enqueue, message-2 must NOT be
+ // queued: consumers mark the first sent+queued payloads as captured, so a
+ // queued entry after a gap would let the gapped message be dropped.
+ assert.equal(res.sent, 0);
+ assert.equal(res.queued, 1);
+ assert.equal(res.enqueueFailed, 2);
+ assert.equal(res.failed, 0);
+ assert.equal(res.retryable, true);
+ const pending = await listPending();
+ assert.deepEqual(
+ pending.map(({ entry }) => entry.payload.content),
+ ["message-0"],
+ );
+ });
+});
+
+test("sendSessionMessages queues the remaining suffix after serial fallback failure", async () => {
+ await withPendingDir(async () => {
+ let serialCount = 0;
+ const onSent = [];
+ const res = await sendSessionMessages(
+ async (path) => {
+ if (path.endsWith("/messages/batch")) return { ok: false, status: 404, error: { message: "missing" } };
+ serialCount += 1;
+ if (serialCount <= 2) return { ok: true, status: 200, result: { ok: true } };
+ return { ok: false, status: 503, error: { message: "unavailable" } };
+ },
+ "serial-retry",
+ payloads(5),
+ { enqueueOnRetryable: true, onSent: async (n) => onSent.push(n) },
+ );
+
+ assert.equal(res.usedBatch, false);
+ assert.equal(res.sent, 2);
+ assert.equal(res.queued, 3);
+ assert.equal(res.failed, 0);
+ assert.deepEqual(onSent, [1, 1]);
+ });
+});
diff --git a/examples/memory-plugin-shared/install-agent-hooks.test.mjs b/examples/memory-plugin-shared/install-agent-hooks.test.mjs
index 10f8d72cd..4795051dd 100644
--- a/examples/memory-plugin-shared/install-agent-hooks.test.mjs
+++ b/examples/memory-plugin-shared/install-agent-hooks.test.mjs
@@ -113,6 +113,7 @@ test("combined Cursor and TRAE install preserves unrelated hooks and is idempote
const shared = join(home, ".openviking", "agent-integrations", "memory-plugin-shared", "lib");
assert.ok(existsSync(join(shared, "agent-hook-runtime.mjs")));
assert.ok(existsSync(join(shared, "agent-uri-guard.mjs")));
+ assert.ok(existsSync(join(shared, "batch-send.mjs")));
assert.ok(existsSync(join(shared, "mcp-proxy-core.mjs")));
assert.ok(existsSync(join(shared, "uri-guard.mjs")));
for (const client of ["cursor", "trae", "trae-cn"]) {
diff --git a/examples/memory-plugin-shared/install.sh b/examples/memory-plugin-shared/install.sh
index 41c62b122..b5054d936 100644
--- a/examples/memory-plugin-shared/install.sh
+++ b/examples/memory-plugin-shared/install.sh
@@ -1742,7 +1742,7 @@ assemble_agent_integration() { # assemble_agent_integration <source-subdir> <des
mkdir -p "$shared_dest.tmp"
for file in \
agent-hook-runtime.mjs agent-uri-guard.mjs credentials.mjs debug-log.mjs \
- mcp-proxy-core.mjs pending-queue.mjs profile-inject.mjs recall-core.mjs \
+ batch-send.mjs mcp-proxy-core.mjs pending-queue.mjs profile-inject.mjs recall-core.mjs \
session-model.mjs uri-guard.mjs workspace-peer.mjs; do
cp "$shared/lib/$file" "$shared_dest.tmp/$file"
done
diff --git a/examples/memory-plugin-shared/lib/agent-hook-runtime.mjs b/examples/memory-plugin-shared/lib/agent-hook-runtime.mjs
index 012b85a56..f03435baf 100644
--- a/examples/memory-plugin-shared/lib/agent-hook-runtime.mjs
+++ b/examples/memory-plugin-shared/lib/agent-hook-runtime.mjs
@@ -5,6 +5,7 @@ import { dirname, join } from "node:path";
import { resolveOpenVikingCredentials } from "./credentials.mjs";
import { createLogger } from "./debug-log.mjs";
+import { sendSessionMessages } from "./batch-send.mjs";
import { enqueue, replayPending } from "./pending-queue.mjs";
import { buildProfileBlock } from "./profile-inject.mjs";
import { buildRecallBlock } from "./recall-core.mjs";
@@ -203,6 +204,10 @@ export async function addAgentMessage(fetchJSON, sessionId, payload) {
return result;
}
+export async function addAgentMessages(fetchJSON, sessionId, payloads) {
+ return sendSessionMessages(fetchJSON, sessionId, payloads, { enqueueOnRetryable: true });
+}
+
export async function commitAgentSession(fetchJSON, sessionId) {
const result = await fetchJSON(`/api/v1/sessions/${encodeURIComponent(sessionId)}/commit`, {
method: "POST",
diff --git a/examples/memory-plugin-shared/lib/async-writer.mjs b/examples/memory-plugin-shared/lib/async-writer.mjs
new file mode 100644
index 000000000..1cc338fd0
--- /dev/null
+++ b/examples/memory-plugin-shared/lib/async-writer.mjs
@@ -0,0 +1,77 @@
+/**
+ * Async write-path helper for hook-based memory plugins.
+ *
+ * When `cfg.writePathAsync` is true and we're not already the worker, we:
+ * 1. Drain the parent's stdin (the hook payload)
+ * 2. Emit the harness-specific approve/no-op response on stdout immediately
+ * 3. Spawn a detached clone of ourselves with env OV_HOOK_WORKER=1
+ * 4. Feed the drained payload to the worker's stdin, unref, and exit
+ *
+ * The worker re-enters the same script, maybeDetach returns false (because
+ * OV_HOOK_WORKER=1), and the hook's normal synchronous code path reads its
+ * own stdin and runs the OV HTTP work with nobody waiting.
+ *
+ * Call this BEFORE the hook reads stdin itself. When it returns true, the
+ * caller must `return` out of main() immediately.
+ */
+
+import { spawn } from "node:child_process";
+
+const WORKER_ENV = "OV_HOOK_WORKER";
+
+export async function maybeDetach(cfg, { approve }) {
+ if (!cfg.writePathAsync) return false;
+ if (process.env[WORKER_ENV] === "1") return false;
+
+ // Drain parent stdin so we can forward to the worker.
+ let raw;
+ try {
+ const chunks = [];
+ for await (const chunk of process.stdin) chunks.push(chunk);
+ raw = Buffer.concat(chunks);
+ } catch {
+ // stdin read failed - let the synchronous path handle it.
+ return false;
+ }
+
+ let child;
+ try {
+ child = spawn(process.execPath, [process.argv[1]], {
+ detached: true,
+ stdio: ["pipe", "ignore", "ignore"],
+ env: { ...process.env, [WORKER_ENV]: "1" },
+ });
+ } catch {
+ // spawn failed - fall through to sync mode, but we've already drained
+ // stdin so hand the payload back via env var path below.
+ process.env.OPENVIKING_HOOK_STDIN_CACHE = raw.toString();
+ return false;
+ }
+
+ // Approve first, then write to the detached child. Ordering matters for
+ // harnesses that read stdout before waiting for the hook process to exit.
+ approve();
+
+ try {
+ child.stdin.write(raw);
+ child.stdin.end();
+ } catch { /* worker may have already exited; nothing useful to recover */ }
+ child.unref();
+ return true;
+}
+
+/**
+ * Fallback stdin reader used when the async path drained stdin but spawn
+ * failed; hooks should call this instead of reading stdin directly when
+ * possible so the sync fallback still works after a failed detach.
+ */
+export async function readHookStdin() {
+ if (process.env.OPENVIKING_HOOK_STDIN_CACHE) {
+ const cached = process.env.OPENVIKING_HOOK_STDIN_CACHE;
+ delete process.env.OPENVIKING_HOOK_STDIN_CACHE;
+ return cached;
+ }
+ const chunks = [];
+ for await (const chunk of process.stdin) chunks.push(chunk);
+ return Buffer.concat(chunks).toString();
+}
diff --git a/examples/memory-plugin-shared/lib/batch-send.mjs b/examples/memory-plugin-shared/lib/batch-send.mjs
new file mode 100644
index 000000000..ce32c3af9
--- /dev/null
+++ b/examples/memory-plugin-shared/lib/batch-send.mjs
@@ -0,0 +1,121 @@
+import { enqueue } from "./pending-queue.mjs";
+
+export const BATCH_LIMIT = 100;
+
+export function isRetryableSendFailure(res) {
+ if (!res || res.ok) return false;
+ const status = Number(res.status || 0);
+ return !status || status === 408 || status === 429 || status >= 500;
+}
+
+function makeResult() {
+ return {
+ sent: 0,
+ queued: 0,
+ enqueueFailed: 0,
+ failed: 0,
+ retryable: false,
+ usedBatch: true,
+ lastError: null,
+ };
+}
+
+async function enqueueRemainder(sessionId, payloads, startIndex, result, retryable, lastError) {
+ result.retryable = retryable;
+ result.lastError = lastError ?? null;
+
+ if (!retryable) {
+ result.failed += Math.max(0, payloads.length - startIndex);
+ return result;
+ }
+
+ const baseCreatedAt = Date.now();
+ for (let i = startIndex; i < payloads.length; i++) {
+ const queued = await enqueue("addMessage", sessionId, payloads[i], {
+ createdAt: baseCreatedAt + (i - startIndex),
+ });
+ if (!queued.ok) {
+ // Stop at the first enqueue failure so queued entries stay a contiguous
+ // prefix: consumers mark the first sent+queued payloads as captured, so
+ // skipping a payload here and queueing a later one would silently drop it.
+ result.enqueueFailed += payloads.length - i;
+ return result;
+ }
+ result.queued++;
+ }
+ return result;
+}
+
+async function sendSerial(fetchJSON, sessionId, payloads, startIndex, opts, result) {
+ result.usedBatch = false;
+ const encodedSid = encodeURIComponent(sessionId);
+ for (let i = startIndex; i < payloads.length; i++) {
+ const res = await fetchJSON(`/api/v1/sessions/${encodedSid}/messages`, {
+ method: "POST",
+ body: JSON.stringify(payloads[i]),
+ });
+ if (res?.ok) {
+ result.sent++;
+ await opts.onSent?.(1);
+ continue;
+ }
+
+ const retryable = isRetryableSendFailure(res);
+ if (opts.enqueueOnRetryable) {
+ return enqueueRemainder(sessionId, payloads, i, result, retryable, res?.error ?? res);
+ }
+ result.retryable = retryable;
+ result.lastError = res?.error ?? res ?? null;
+ result.failed += payloads.length - i;
+ return result;
+ }
+ return result;
+}
+
+/**
+ * Send add-message payloads in server-sized batches with serial fallback.
+ *
+ * @param {Function} fetchJSON - (path, init) => { ok, status, result?, error? }
+ * @param {string} sessionId - OpenViking session id
+ * @param {Array<object>} payloads - sanitized add-message request bodies
+ * @param {object} opts
+ * @param {boolean} opts.enqueueOnRetryable - enqueue unsent payloads after a retryable failure
+ * @param {Function} opts.onSent - called with the number of messages durably sent after each success
+ * @returns {Promise<{sent:number,queued:number,enqueueFailed:number,failed:number,retryable:boolean,usedBatch:boolean,lastError:any}>}
+ */
+export async function sendSessionMessages(fetchJSON, sessionId, payloads, opts = {}) {
+ const result = makeResult();
+ const messages = Array.isArray(payloads) ? payloads : [];
+ if (messages.length === 0) return result;
+
+ const encodedSid = encodeURIComponent(sessionId);
+ for (let start = 0; start < messages.length; start += BATCH_LIMIT) {
+ const chunk = messages.slice(start, start + BATCH_LIMIT);
+ const res = await fetchJSON(`/api/v1/sessions/${encodedSid}/messages/batch`, {
+ method: "POST",
+ body: JSON.stringify({ messages: chunk }),
+ });
+
+ if (res?.ok) {
+ result.sent += chunk.length;
+ await opts.onSent?.(chunk.length);
+ continue;
+ }
+
+ const status = Number(res?.status || 0);
+ if (status === 404 || status === 405) {
+ return sendSerial(fetchJSON, sessionId, messages, start, opts, result);
+ }
+
+ const retryable = isRetryableSendFailure(res);
+ if (opts.enqueueOnRetryable) {
+ return enqueueRemainder(sessionId, messages, start, result, retryable, res?.error ?? res);
+ }
+ result.retryable = retryable;
+ result.lastError = res?.error ?? res ?? null;
+ result.failed += messages.length - start;
+ return result;
+ }
+
+ return result;
+}
diff --git a/examples/memory-plugin-shared/lib/pending-queue.mjs b/examples/memory-plugin-shared/lib/pending-queue.mjs
index e049de794..749bf5977 100644
--- a/examples/memory-plugin-shared/lib/pending-queue.mjs
+++ b/examples/memory-plugin-shared/lib/pending-queue.mjs
@@ -181,10 +181,12 @@ async function recoverStaleProcessing(dir) {
* @param {string} type - "addMessage" or "commitSession"
* @param {string} sessionId - OV session ID
* @param {object} payload - the data that failed to send
+ * @param {object} options
+ * @param {number} options.createdAt - optional queue timestamp override
*/
-export async function enqueue(type, sessionId, payload) {
+export async function enqueue(type, sessionId, payload, options = {}) {
const dir = getPendingDir();
- const now = Date.now();
+ const now = Number.isFinite(options.createdAt) ? options.createdAt : Date.now();
const dedupKey = makeDedupKey(type, sessionId, payload);
const filename = pendingFilename(dedupKey, 0);
const entry = {
diff --git a/examples/memory-plugin-shared/sync.mjs b/examples/memory-plugin-shared/sync.mjs
index 25b2804d8..19344baa2 100644
--- a/examples/memory-plugin-shared/sync.mjs
+++ b/examples/memory-plugin-shared/sync.mjs
@@ -18,7 +18,7 @@ const HARNESS_SHARED_FILES = [
"profile-inject.mjs",
"uri-guard.mjs",
];
-const OPENCODE_SHARED_FILES = [...HARNESS_SHARED_FILES, "mcp-proxy-core.mjs"];
+const OPENCODE_SHARED_FILES = [...HARNESS_SHARED_FILES, "mcp-proxy-core.mjs", "async-writer.mjs", "batch-send.mjs"];
const TARGETS = [
{ dir: join(ROOT, "examples", "claude-code-memory-plugin", "scripts", "shared"), files: OPENCODE_SHARED_FILES },
{ dir: join(ROOT, "examples", "codex-memory-plugin", "scripts", "shared"), files: OPENCODE_SHARED_FILES },
diff --git a/examples/memory-plugin-shared/sync.test.mjs b/examples/memory-plugin-shared/sync.test.mjs
index 721ad891e..e3abc7c77 100644
--- a/examples/memory-plugin-shared/sync.test.mjs
+++ b/examples/memory-plugin-shared/sync.test.mjs
@@ -18,7 +18,7 @@ const HARNESS_SHARED_FILES = [
"profile-inject.mjs",
"uri-guard.mjs",
];
-const OPENCODE_SHARED_FILES = [...HARNESS_SHARED_FILES, "mcp-proxy-core.mjs"];
+const OPENCODE_SHARED_FILES = [...HARNESS_SHARED_FILES, "mcp-proxy-core.mjs", "async-writer.mjs", "batch-send.mjs"];
const TARGETS = [
{ dir: join(ROOT, "examples", "claude-code-memory-plugin", "scripts", "shared"), files: OPENCODE_SHARED_FILES },
{ dir: join(ROOT, "examples", "codex-memory-plugin", "scripts", "shared"), files: OPENCODE_SHARED_FILES },
diff --git a/examples/opencode-plugin/lib/memory-session.mjs b/examples/opencode-plugin/lib/memory-session.mjs
index 3aa5a5394..22ec44b20 100644
--- a/examples/opencode-plugin/lib/memory-session.mjs
+++ b/examples/opencode-plugin/lib/memory-session.mjs
@@ -12,6 +12,9 @@ import {
enqueue,
replayPending,
} from "./shared/pending-queue.mjs"
+import {
+ sendSessionMessages,
+} from "./shared/batch-send.mjs"
import {
log,
effectivePeerId,
@@ -358,7 +361,7 @@ export function createMemorySessionManager({ config, pluginRoot }) {
}
async function flushPendingMessages(opencodeSessionId, state) {
- let added = 0
+ const toSend = []
for (const [messageId, message] of state.messages.entries()) {
if (message.captured) continue
const body = buildCapturePayload(message)
@@ -366,40 +369,45 @@ export function createMemorySessionManager({ config, pluginRoot }) {
message.captured = true
continue
}
- const ok = await addMessageToSession(state.ovSessionId, body)
- if (!ok) break
- message.captured = true
- added += 1
- }
- if (added > 0) {
- state.lastActivityAt = Date.now()
- debouncedSaveState()
+ toSend.push({ messageId, message, body })
}
- return added
- }
+ if (toSend.length === 0) return 0
- async function addMessageToSession(ovSessionId, body) {
+ let added = 0
const health = await fetchJSON(config, "/health", {}, { timeoutMs: 5000 })
if (!health.ok) {
- await enqueue("addMessage", ovSessionId, body)
- return true
+ for (const item of toSend) {
+ const queued = await enqueue("addMessage", state.ovSessionId, item.body)
+ if (!queued.ok) break
+ item.message.captured = true
+ added += 1
+ }
+ } else {
+ const res = await sendSessionMessages(
+ (endpoint, init = {}, options = {}) => fetchJSON(config, endpoint, init, { timeoutMs: 10000, ...options }),
+ state.ovSessionId,
+ toSend.map((item) => item.body),
+ { enqueueOnRetryable: true },
+ )
+ added = res.sent + res.queued
+ for (const item of toSend.slice(0, added)) {
+ item.message.captured = true
+ }
+ if (res.failed > 0 || res.enqueueFailed > 0) {
+ log("ERROR", "message", "Failed to add message to OpenViking session", {
+ openviking_session: state.ovSessionId,
+ status: res.lastError?.status,
+ error: res.lastError,
+ failed: res.failed,
+ enqueueFailed: res.enqueueFailed,
+ })
+ }
}
- const res = await fetchJSON(config, `/api/v1/sessions/${encodeURIComponent(ovSessionId)}/messages`, {
- method: "POST",
- body: JSON.stringify(body),
- }, { timeoutMs: 10000 })
- if (res.ok) return true
- if (isRetryableFailure(res)) {
- const queued = await enqueue("addMessage", ovSessionId, body)
- return Boolean(queued.ok)
+ if (added > 0) {
+ state.lastActivityAt = Date.now()
+ debouncedSaveState()
}
- log("ERROR", "message", "Failed to add message to OpenViking session", {
- openviking_session: ovSessionId,
- role: body.role,
- status: res.status,
- error: res.error,
- })
- return false
+ return added
}
async function maybeCommitByThreshold(state) {
diff --git a/examples/opencode-plugin/lib/shared/async-writer.mjs b/examples/opencode-plugin/lib/shared/async-writer.mjs
new file mode 100644
index 000000000..8ffc71468
--- /dev/null
+++ b/examples/opencode-plugin/lib/shared/async-writer.mjs
@@ -0,0 +1,78 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+/**
+ * Async write-path helper for hook-based memory plugins.
+ *
+ * When `cfg.writePathAsync` is true and we're not already the worker, we:
+ * 1. Drain the parent's stdin (the hook payload)
+ * 2. Emit the harness-specific approve/no-op response on stdout immediately
+ * 3. Spawn a detached clone of ourselves with env OV_HOOK_WORKER=1
+ * 4. Feed the drained payload to the worker's stdin, unref, and exit
+ *
+ * The worker re-enters the same script, maybeDetach returns false (because
+ * OV_HOOK_WORKER=1), and the hook's normal synchronous code path reads its
+ * own stdin and runs the OV HTTP work with nobody waiting.
+ *
+ * Call this BEFORE the hook reads stdin itself. When it returns true, the
+ * caller must `return` out of main() immediately.
+ */
+
+import { spawn } from "node:child_process";
+
+const WORKER_ENV = "OV_HOOK_WORKER";
+
+export async function maybeDetach(cfg, { approve }) {
+ if (!cfg.writePathAsync) return false;
+ if (process.env[WORKER_ENV] === "1") return false;
+
+ // Drain parent stdin so we can forward to the worker.
+ let raw;
+ try {
+ const chunks = [];
+ for await (const chunk of process.stdin) chunks.push(chunk);
+ raw = Buffer.concat(chunks);
+ } catch {
+ // stdin read failed - let the synchronous path handle it.
+ return false;
+ }
+
+ let child;
+ try {
+ child = spawn(process.execPath, [process.argv[1]], {
+ detached: true,
+ stdio: ["pipe", "ignore", "ignore"],
+ env: { ...process.env, [WORKER_ENV]: "1" },
+ });
+ } catch {
+ // spawn failed - fall through to sync mode, but we've already drained
+ // stdin so hand the payload back via env var path below.
+ process.env.OPENVIKING_HOOK_STDIN_CACHE = raw.toString();
+ return false;
+ }
+
+ // Approve first, then write to the detached child. Ordering matters for
+ // harnesses that read stdout before waiting for the hook process to exit.
+ approve();
+
+ try {
+ child.stdin.write(raw);
+ child.stdin.end();
+ } catch { /* worker may have already exited; nothing useful to recover */ }
+ child.unref();
+ return true;
+}
+
+/**
+ * Fallback stdin reader used when the async path drained stdin but spawn
+ * failed; hooks should call this instead of reading stdin directly when
+ * possible so the sync fallback still works after a failed detach.
+ */
+export async function readHookStdin() {
+ if (process.env.OPENVIKING_HOOK_STDIN_CACHE) {
+ const cached = process.env.OPENVIKING_HOOK_STDIN_CACHE;
+ delete process.env.OPENVIKING_HOOK_STDIN_CACHE;
+ return cached;
+ }
+ const chunks = [];
+ for await (const chunk of process.stdin) chunks.push(chunk);
+ return Buffer.concat(chunks).toString();
+}
diff --git a/examples/opencode-plugin/lib/shared/batch-send.mjs b/examples/opencode-plugin/lib/shared/batch-send.mjs
new file mode 100644
index 000000000..6d929d6bf
--- /dev/null
+++ b/examples/opencode-plugin/lib/shared/batch-send.mjs
@@ -0,0 +1,122 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+import { enqueue } from "./pending-queue.mjs";
+
+export const BATCH_LIMIT = 100;
+
+export function isRetryableSendFailure(res) {
+ if (!res || res.ok) return false;
+ const status = Number(res.status || 0);
+ return !status || status === 408 || status === 429 || status >= 500;
+}
+
+function makeResult() {
+ return {
+ sent: 0,
+ queued: 0,
+ enqueueFailed: 0,
+ failed: 0,
+ retryable: false,
+ usedBatch: true,
+ lastError: null,
+ };
+}
+
+async function enqueueRemainder(sessionId, payloads, startIndex, result, retryable, lastError) {
+ result.retryable = retryable;
+ result.lastError = lastError ?? null;
+
+ if (!retryable) {
+ result.failed += Math.max(0, payloads.length - startIndex);
+ return result;
+ }
+
+ const baseCreatedAt = Date.now();
+ for (let i = startIndex; i < payloads.length; i++) {
+ const queued = await enqueue("addMessage", sessionId, payloads[i], {
+ createdAt: baseCreatedAt + (i - startIndex),
+ });
+ if (!queued.ok) {
+ // Stop at the first enqueue failure so queued entries stay a contiguous
+ // prefix: consumers mark the first sent+queued payloads as captured, so
+ // skipping a payload here and queueing a later one would silently drop it.
+ result.enqueueFailed += payloads.length - i;
+ return result;
+ }
+ result.queued++;
+ }
+ return result;
+}
+
+async function sendSerial(fetchJSON, sessionId, payloads, startIndex, opts, result) {
+ result.usedBatch = false;
+ const encodedSid = encodeURIComponent(sessionId);
+ for (let i = startIndex; i < payloads.length; i++) {
+ const res = await fetchJSON(`/api/v1/sessions/${encodedSid}/messages`, {
+ method: "POST",
+ body: JSON.stringify(payloads[i]),
+ });
+ if (res?.ok) {
+ result.sent++;
+ await opts.onSent?.(1);
+ continue;
+ }
+
+ const retryable = isRetryableSendFailure(res);
+ if (opts.enqueueOnRetryable) {
+ return enqueueRemainder(sessionId, payloads, i, result, retryable, res?.error ?? res);
+ }
+ result.retryable = retryable;
+ result.lastError = res?.error ?? res ?? null;
+ result.failed += payloads.length - i;
+ return result;
+ }
+ return result;
+}
+
+/**
+ * Send add-message payloads in server-sized batches with serial fallback.
+ *
+ * @param {Function} fetchJSON - (path, init) => { ok, status, result?, error? }
+ * @param {string} sessionId - OpenViking session id
+ * @param {Array<object>} payloads - sanitized add-message request bodies
+ * @param {object} opts
+ * @param {boolean} opts.enqueueOnRetryable - enqueue unsent payloads after a retryable failure
+ * @param {Function} opts.onSent - called with the number of messages durably sent after each success
+ * @returns {Promise<{sent:number,queued:number,enqueueFailed:number,failed:number,retryable:boolean,usedBatch:boolean,lastError:any}>}
+ */
+export async function sendSessionMessages(fetchJSON, sessionId, payloads, opts = {}) {
+ const result = makeResult();
+ const messages = Array.isArray(payloads) ? payloads : [];
+ if (messages.length === 0) return result;
+
+ const encodedSid = encodeURIComponent(sessionId);
+ for (let start = 0; start < messages.length; start += BATCH_LIMIT) {
+ const chunk = messages.slice(start, start + BATCH_LIMIT);
+ const res = await fetchJSON(`/api/v1/sessions/${encodedSid}/messages/batch`, {
+ method: "POST",
+ body: JSON.stringify({ messages: chunk }),
+ });
+
+ if (res?.ok) {
+ result.sent += chunk.length;
+ await opts.onSent?.(chunk.length);
+ continue;
+ }
+
+ const status = Number(res?.status || 0);
+ if (status === 404 || status === 405) {
+ return sendSerial(fetchJSON, sessionId, messages, start, opts, result);
+ }
+
+ const retryable = isRetryableSendFailure(res);
+ if (opts.enqueueOnRetryable) {
+ return enqueueRemainder(sessionId, messages, start, result, retryable, res?.error ?? res);
+ }
+ result.retryable = retryable;
+ result.lastError = res?.error ?? res ?? null;
+ result.failed += messages.length - start;
+ return result;
+ }
+
+ return result;
+}
diff --git a/examples/opencode-plugin/lib/shared/pending-queue.mjs b/examples/opencode-plugin/lib/shared/pending-queue.mjs
index cbf6d445f..16e4da0dc 100644
--- a/examples/opencode-plugin/lib/shared/pending-queue.mjs
+++ b/examples/opencode-plugin/lib/shared/pending-queue.mjs
@@ -182,10 +182,12 @@ async function recoverStaleProcessing(dir) {
* @param {string} type - "addMessage" or "commitSession"
* @param {string} sessionId - OV session ID
* @param {object} payload - the data that failed to send
+ * @param {object} options
+ * @param {number} options.createdAt - optional queue timestamp override
*/
-export async function enqueue(type, sessionId, payload) {
+export async function enqueue(type, sessionId, payload, options = {}) {
const dir = getPendingDir();
- const now = Date.now();
+ const now = Number.isFinite(options.createdAt) ? options.createdAt : Date.now();
const dedupKey = makeDedupKey(type, sessionId, payload);
const filename = pendingFilename(dedupKey, 0);
const entry = {
diff --git a/examples/opencode-plugin/package.json b/examples/opencode-plugin/package.json
index 7329b8a45..3f9d897db 100644
--- a/examples/opencode-plugin/package.json
+++ b/examples/opencode-plugin/package.json
@@ -1,6 +1,6 @@
{
"name": "@openviking/opencode-plugin",
- "version": "0.2.2",
+ "version": "0.2.3",
"author": "@openviking",
"description": "Unified OpenCode plugin for OpenViking repository retrieval and long-term memory",
"type": "module",
diff --git a/examples/opencode-plugin/tests/memory-session.test.mjs b/examples/opencode-plugin/tests/memory-session.test.mjs
index e271a51f0..d223fdf17 100644
--- a/examples/opencode-plugin/tests/memory-session.test.mjs
+++ b/examples/opencode-plugin/tests/memory-session.test.mjs
@@ -26,7 +26,7 @@ async function withCaptureServer(fn) {
res.setHeader("Content-Type", "application/json")
if (req.url === "/health") {
res.end(JSON.stringify({ status: "ok" }))
- } else if (req.url?.startsWith("/api/v1/sessions/") && req.url.endsWith("/messages")) {
+ } else if (req.url?.startsWith("/api/v1/sessions/") && req.url.endsWith("/messages/batch")) {
res.end(JSON.stringify({ status: "ok", result: { accepted: true } }))
} else if (req.url?.startsWith("/api/v1/sessions/")) {
res.end(JSON.stringify({ status: "ok", result: { pending_tokens: 0 } }))
@@ -94,11 +94,11 @@ test("session.idle event flushes pending OpenCode capture", async () => {
await manager.handleEvent({ type: "session.idle", sessionID: "oc-session-1" })
- const addMessage = requests.find((request) => request.url === "/api/v1/sessions/oc-oc-session-1/messages")
+ const addMessage = requests.find((request) => request.url === "/api/v1/sessions/oc-oc-session-1/messages/batch")
assert.ok(addMessage, "session.idle should POST pending messages")
const body = JSON.parse(addMessage.body)
- assert.equal(body.role, "user")
- assert.match(body.content, /idle events must flush captures/)
+ assert.equal(body.messages[0].role, "user")
+ assert.match(body.messages[0].content, /idle events must flush captures/)
await manager.flushAll({ commit: false })
})
})
@@ -136,11 +136,11 @@ test("assistant messages are captured even when finish is not stop", async () =>
await manager.handleEvent({ type: "session.idle", properties: { sessionID: "oc-session-2" } })
- const addMessage = requests.find((request) => request.url === "/api/v1/sessions/oc-oc-session-2/messages")
+ const addMessage = requests.find((request) => request.url === "/api/v1/sessions/oc-oc-session-2/messages/batch")
assert.ok(addMessage, "session.idle should capture non-stop assistant messages")
const body = JSON.parse(addMessage.body)
- assert.equal(body.role, "assistant")
- assert.match(body.content, /Partial assistant output/)
+ assert.equal(body.messages[0].role, "assistant")
+ assert.match(body.messages[0].content, /Partial assistant output/)
await manager.flushAll({ commit: false })
})
})
diff --git a/examples/pi-coding-agent-extension/shared/pending-queue.mjs b/examples/pi-coding-agent-extension/shared/pending-queue.mjs
index cbf6d445f..16e4da0dc 100644
--- a/examples/pi-coding-agent-extension/shared/pending-queue.mjs
+++ b/examples/pi-coding-agent-extension/shared/pending-queue.mjs
@@ -182,10 +182,12 @@ async function recoverStaleProcessing(dir) {
* @param {string} type - "addMessage" or "commitSession"
* @param {string} sessionId - OV session ID
* @param {object} payload - the data that failed to send
+ * @param {object} options
+ * @param {number} options.createdAt - optional queue timestamp override
*/
-export async function enqueue(type, sessionId, payload) {
+export async function enqueue(type, sessionId, payload, options = {}) {
const dir = getPendingDir();
- const now = Date.now();
+ const now = Number.isFinite(options.createdAt) ? options.createdAt : Date.now();
const dedupKey = makeDedupKey(type, sessionId, payload);
const filename = pendingFilename(dedupKey, 0);
const entry = {
diff --git a/examples/trae-memory-hooks/openviking.integration.json b/examples/trae-memory-hooks/openviking.integration.json
index 51eaa6b64..fe7da2ce0 100644
--- a/examples/trae-memory-hooks/openviking.integration.json
+++ b/examples/trae-memory-hooks/openviking.integration.json
@@ -1,7 +1,7 @@
{
"schemaVersion": 1,
"id": "openviking-memory",
- "version": "0.1.1",
+ "version": "0.1.2",
"clients": ["trae", "trae-cn"],
"capabilities": ["hooks", "mcp"]
}
diff --git a/examples/trae-memory-hooks/scripts/trae-hook.mjs b/examples/trae-memory-hooks/scripts/trae-hook.mjs
index cb6929551..fe7406d6c 100644
--- a/examples/trae-memory-hooks/scripts/trae-hook.mjs
+++ b/examples/trae-memory-hooks/scripts/trae-hook.mjs
@@ -1,7 +1,7 @@
#!/usr/bin/env node
import {
- addAgentMessage,
+ addAgentMessages,
buildAgentProfile,
commitAgentSession,
createAgentLogger,
@@ -108,16 +108,15 @@ async function main() {
state = await readHookState(requestedClient, nativeSessionId);
const hashes = new Set(Array.isArray(state.capturedHashes) ? state.capturedHashes : []);
const turnKey = state.pendingPrompt?.at || state.lastTurnKey || state.promptHash || "unknown-turn";
- let captured = 0;
+ const toSend = [];
for (const turn of buildTraeTurns(input, state)) {
const hash = stableHash(turnKey, turn.role, turn.content);
if (hashes.has(hash)) continue;
- const result = await addAgentMessage(fetchJSON, sessionId, turn);
- if (result.ok || [0, 408, 429].includes(result.status) || result.status >= 500) {
- hashes.add(hash);
- captured += 1;
- }
+ toSend.push({ hash, turn });
}
+ const result = await addAgentMessages(fetchJSON, sessionId, toSend.map((item) => item.turn));
+ const captured = result.sent + result.queued;
+ for (const item of toSend.slice(0, captured)) hashes.add(item.hash);
let nextCount = Number(state.capturedSinceCommit || 0) + captured;
if (captured > 0) {
const committed = await commitAgentSession(fetchJSON, sessionId);
diff --git a/examples/trae-memory-hooks/scripts/trae-hooks.test.mjs b/examples/trae-memory-hooks/scripts/trae-hooks.test.mjs
index b015ad274..132a6af8a 100644
--- a/examples/trae-memory-hooks/scripts/trae-hooks.test.mjs
+++ b/examples/trae-memory-hooks/scripts/trae-hooks.test.mjs
@@ -99,7 +99,8 @@ test("TRAE prompt hook injects recall and Stop captures dedicated event fields",
if (request.url === "/api/v1/search/recall") {
response.end(JSON.stringify({ result: { rendered: "trae memory" } }));
} else if (request.url?.includes("/messages")) {
- messages.push({ url: request.url, body: JSON.parse(body) });
+ const parsed = JSON.parse(body);
+ messages.push(...(parsed.messages ?? [parsed]).map((message) => ({ url: request.url, body: message })));
response.end(JSON.stringify({ result: { ok: true } }));
} else if (request.url?.endsWith("/commit")) {
commits.push(request.url);