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
import { createHash } from "node:crypto";
import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
import { homedir } from "node:os";
import { dirname, join } from "node:path";
import { createLogger } from "./debug-log.mjs";
import { sendSessionMessages } from "./batch-send.mjs";
import { createOvHttp } from "./ov-http.mjs";
import { enqueue, replayPending } from "./pending-queue.mjs";
import { buildProfileBlock } from "./profile-inject.mjs";
import { buildRecallBlock, isRecallEnabled } from "./recall-core.mjs";
import { buildPluginConfig } from "./plugin-config.mjs";
import { isRetryableFailure } from "./retryable.mjs";
import { deriveHarnessSessionId, isBypassed } from "./session-model.mjs";
import { resolveEffectivePeerId } from "./workspace-peer.mjs";
const STATE_VERSION = 1;
const STATE_DIR_MODE = 0o700;
const STATE_FILE_MODE = 0o600;
function safePart(value) {
return String(value || "unknown").replace(/[^A-Za-z0-9._-]/g, "-");
}
export function stableHash(...values) {
return createHash("sha256")
.update(values.map((value) => String(value ?? "")).join("\n"))
.digest("hex");
}
/**
* The config for one of the thin hook harnesses.
*
* These four used to read the environment and nothing else, so `ov config
* switch` moved their credentials and left their behaviour behind, and an
* `ovcli.conf` `plugin` entry named after them was inert. They resolve through
* the same layers as every other harness now; only the client's own name for
* itself stays local.
*
* `cwd` selects the workspace layer. It defaults to this process's directory,
* which is all a hook knows before the payload on stdin names the session's
* own — the caller re-resolves once it has it. That is safe because a workspace
* file may not carry connection or credential keys, so the base URL and API key
* cannot move under a logger or fetch helper already built from the first load.
*/
export function loadAgentHookConfig(clientId, cwd = process.cwd(), { env = process.env } = {}) {
return {
...buildPluginConfig(clientId, {
cwd,
env,
version: env.OPENVIKING_INTEGRATION_VERSION,
logFile: `${clientId}-hooks.log`,
}),
clientId,
};
}
export function createAgentLogger(clientId, hookName, cfg) {
return createLogger(`${clientId}:${hookName}`, cfg);
}
export async function readRawHookInput() {
const chunks = [];
for await (const chunk of process.stdin) chunks.push(chunk);
return Buffer.concat(chunks).toString();
}
export async function readHookInput() {
const raw = await readRawHookInput();
if (!raw.trim()) return {};
try { return JSON.parse(raw); } catch { return {}; }
}
export function resolveAgentCwd(input = {}) {
const workspaceRoots = Array.isArray(input.workspace_roots)
? input.workspace_roots
: Array.isArray(input.workspaceRoots) ? input.workspaceRoots : [];
return String(
input.cwd
|| workspaceRoots.find((value) => typeof value === "string" && value.trim())
|| process.env.CURSOR_PROJECT_DIR
|| process.cwd(),
);
}
export function resolveNativeSessionId(input = {}) {
const direct = input.conversation_id || input.session_id || input.sessionId || input.generation_id;
if (direct) return safePart(direct);
const transcript = input.transcript_path || input.transcriptPath;
if (transcript) {
const match = String(transcript).match(/([0-9a-f]{8}-[0-9a-f-]{20,})/i);
return safePart(match?.[1] || stableHash(transcript).slice(0, 24));
}
const cwd = resolveAgentCwd(input);
return `cwd-${stableHash(cwd).slice(0, 20)}`;
}
export function deriveAgentSessionId(prefix, input = {}) {
return deriveHarnessSessionId(prefix, resolveNativeSessionId(input));
}
function statePath(clientId, nativeSessionId) {
const root = process.env.OPENVIKING_HOOK_STATE_DIR
|| join(homedir(), ".openviking", "hook-state");
return join(root, safePart(clientId), `${safePart(nativeSessionId)}.json`);
}
function sleep(ms) {
return new Promise((resolve) => setTimeout(resolve, ms));
}
export async function withAgentHookLock(clientId, nativeSessionId, callback) {
const file = statePath(clientId, nativeSessionId);
const lock = `${file}.lock`;
await mkdir(dirname(file), { recursive: true, mode: STATE_DIR_MODE });
const deadline = Date.now() + 5000;
while (true) {
try {
await mkdir(lock, { mode: STATE_DIR_MODE });
break;
} catch (error) {
if (error?.code !== "EEXIST") throw error;
try {
if (Date.now() - (await stat(lock)).mtimeMs > 60_000) {
await rm(lock, { recursive: true, force: true });
continue;
}
} catch {}
if (Date.now() >= deadline) return null;
await sleep(50);
}
}
try {
return await callback(file);
} finally {
await rm(lock, { recursive: true, force: true }).catch(() => {});
}
}
export async function readHookState(clientId, nativeSessionId) {
try {
const parsed = JSON.parse(await readFile(statePath(clientId, nativeSessionId), "utf8"));
return parsed && typeof parsed === "object" ? parsed : {};
} catch {
return {};
}
}
export async function writeHookState(clientId, nativeSessionId, value) {
const file = statePath(clientId, nativeSessionId);
await mkdir(dirname(file), { recursive: true, mode: STATE_DIR_MODE });
const tmp = `${file}.${process.pid}.tmp`;
await writeFile(tmp, `${JSON.stringify({ version: STATE_VERSION, ...value }, null, 2)}\n`, {
encoding: "utf8",
mode: STATE_FILE_MODE,
});
await rename(tmp, file);
}
/**
* The `fetchJSON` a hook talks through.
*
* `getActorPeerId` is a getter rather than a value because Codex only knows its
* peer after loading session state under the session lock, and because a stack
* whose every call names its own peer answers with the empty string. The
* workspace peer behind the default is resolved on demand so those callers do
* not pay for a lookup they never read.
*/
export function makeAgentFetchJSON(cfg, cwd = process.cwd(), {
defaultTimeoutMs,
getActorPeerId,
requireJsonBody = false,
} = {}) {
let resolved = null;
const workspacePeer = () => (resolved ??= resolveEffectivePeerId({ cfg, cwd }));
const fetchJSON = createOvHttp(cfg, {
defaultTimeoutMs: defaultTimeoutMs ?? cfg.timeoutMs,
resolveActorPeerId: getActorPeerId || (() => workspacePeer().peerId),
requireJsonBody,
});
return { fetchJSON, get effectivePeer() { return workspacePeer(); } };
}
/** Park a write for the next hook to replay. Never throws: the caller is a hook. */
export async function enqueueAgentPending(type, sessionId, payload = {}) {
try {
return await enqueue(type, sessionId, payload);
} catch {
return { ok: false };
}
}
/**
* What became of a write that failed: parked for replay, or reported once on
* stderr when no retry can help. `pendingQueued` / `pendingEnqueueFailed` are
* what the capture hooks log and what decides whether a turn is lost.
*/
async function notePendingWrite(type, sessionId, payload, result) {
if (result.ok) return result;
if (!isRetryableFailure(result)) {
const detail = result.error?.message || result.error?.code || "";
process.stderr.write(
`[ov] ${type} failed with non-retryable status ${result.status || "unknown"};`
+ ` not enqueuing pending retry${detail ? ` (${detail})` : ""}\n`,
);
return result;
}
const pending = await enqueueAgentPending(type, sessionId, payload);
if (pending.ok) result.pendingQueued = true;
else result.pendingEnqueueFailed = true;
return result;
}
export async function addAgentMessage(fetchJSON, sessionId, payload) {
const result = await fetchJSON(`/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`, {
method: "POST",
body: JSON.stringify(payload),
});
return notePendingWrite("addMessage", sessionId, payload, result);
}
/**
* Session routes attribute a message by its body `peer_id` alone: the
* actor-peer header scopes reads, not session writes. A payload that already
* names its peer keeps it; an empty `peerId` (peer mode off) stamps nothing.
*/
export async function addAgentMessages(fetchJSON, sessionId, payloads, peerId = "") {
const stamped = peerId
? payloads.map((payload) => (payload.peer_id ? payload : { ...payload, peer_id: peerId }))
: payloads;
return sendSessionMessages(fetchJSON, sessionId, stamped, { enqueueOnRetryable: true });
}
export async function commitAgentSession(fetchJSON, sessionId, log = () => {}, payload = {}) {
const body = payload || {};
const result = await fetchJSON(`/api/v1/sessions/${encodeURIComponent(sessionId)}/commit`, {
method: "POST",
body: JSON.stringify(body),
});
await notePendingWrite("commitSession", sessionId, body, result);
log("commit", {
sessionId,
ok: result.ok,
status: result.result?.status || result.status,
trace_id: result.traceId || result.result?.trace_id,
queued: Boolean(result.pendingQueued),
error: result.ok ? undefined : result.error?.message || result.error?.code,
});
return result;
}
/** Session meta, or null when the session does not exist and `autoCreate` is off. */
export async function getAgentSession(fetchJSON, sessionId, { autoCreate = false } = {}) {
const query = autoCreate ? "?auto_create=true" : "";
const result = await fetchJSON(`/api/v1/sessions/${encodeURIComponent(sessionId)}${query}`);
return result.ok ? result.result : null;
}
/** Assembled session context (includes latest_archive_overview), or null. */
export async function getAgentSessionContext(fetchJSON, sessionId, tokenBudget = 128000) {
const result = await fetchJSON(
`/api/v1/sessions/${encodeURIComponent(sessionId)}/context?token_budget=${tokenBudget}`,
);
return result.ok ? result.result : null;
}
export async function replayAgentPending(fetchJSON, log = () => {}) {
return replayPending(fetchJSON, log);
}
export async function recallForPrompt(fetchJSON, cfg, prompt, cwd, log = () => {}, options = {}) {
if (!isRecallEnabled(cfg) || !String(prompt || "").trim()) return null;
const peer = resolveEffectivePeerId({ cfg, cwd });
return buildRecallBlock(fetchJSON, cfg, prompt, {
actorPeerId: peer.peerId,
legacyPeerId: peer.legacyPeerId,
// Passing the OV session id is what turns on server-side query expansion
// and the cross-turn dedup ledger for these thin harnesses.
sessionId: options.sessionId || "",
excludeUris: cfg.recallExcludeUris,
log,
});
}
export async function buildAgentProfile(fetchJSON, cfg, cwd) {
const peer = resolveEffectivePeerId({ cfg, cwd });
const profile = await buildProfileBlock(fetchJSON, cfg.profileTokenBudget, peer.peerId, cfg);
return profile?.block || null;
}
export function shouldBypassAgent(cfg, input = {}) {
return isBypassed(cfg, { sessionId: resolveNativeSessionId(input), cwd: resolveAgentCwd(input) });
}
/**
* The opening every hook entry shares: read the payload, re-resolve the config
* against the session's directory, answer the two gates, then run the hook's
* own work and emit one envelope.
*
* `run` receives the resolved stage and returns the envelope's payload — a
* systemMessage, a context block, or nothing. A closed gate calls
* `onSkip(reason, stage)` with `"bad_stdin"`, `"disabled"` or `"bypass"`, emits
* an empty envelope and never runs the callback. `run` may emit early through
* `stage.emit` (a detaching hook has to answer before its worker starts); the
* envelope is written once.
*
* Both gates are predicates over `(cfg, stage)`: `enabled` says whether this
* hook runs at all, `bypass` whether this session is one the plugin stays out
* of. `sessionId` reads the session out of the payload — the default is the key
* Claude Code and Codex send, and a host that spells it differently, or derives
* it, hands over its own resolver rather than turning the gate off.
*
* The write-path preamble — the enabled gate against this process's directory,
* then `maybeDetach` — stays in the entry. A worker has to be spawned before
* stdin is consumed, and its response is the host's own.
*/
export async function runHookStage({
clientId,
loadConfig = (cwd) => loadAgentHookConfig(clientId, cwd),
input: { read = readRawHookInput, tolerant = false } = {},
sessionId: resolveSessionId = (payload) => payload.session_id ?? payload.sessionId,
gates: { enabled = null, bypass = (cfg, stage) => stage.bypassed } = {},
envelope = () => {},
onSkip = () => {},
} = {}, run = () => undefined) {
let emitted = false;
const emit = (value) => {
if (emitted) return;
emitted = true;
envelope(value);
};
let badStdin = false;
const raw = await read();
let payload;
try {
payload = JSON.parse(tolerant ? raw || "{}" : raw);
} catch {
badStdin = !tolerant;
payload = {};
}
if (!payload || typeof payload !== "object") payload = {};
const cwd = resolveAgentCwd(payload);
const cfg = loadConfig(cwd);
const sessionId = resolveSessionId(payload);
const stage = {
cfg,
input: payload,
raw,
cwd,
sessionId,
bypassed: isBypassed(cfg, { sessionId, cwd }),
emit,
};
if (badStdin) {
onSkip("bad_stdin", stage);
emit();
return undefined;
}
if (cfg.enabled === false || (enabled && !enabled(cfg, stage))) {
onSkip("disabled", stage);
emit();
return undefined;
}
if (bypass && bypass(cfg, stage)) {
onSkip("bypass", stage);
emit();
return undefined;
}
const result = await run(stage);
emit(result);
return result;
}