memoryrouter-codex 1.0.0

package/lib/installer.cjs

@@ -0,0 +1,235 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { codexHome, dataHome, loadConfig, saveConfig, configPath } = require('../runtime/config.cjs');
+const { resolveProject } = require('../runtime/project.cjs');
+const { MCP_ENDPOINT, INTEGRATION_VERSION } = require('../runtime/constants.cjs');
+const {
+  installToml, uninstallToml, installAgents, uninstallAgents, readText, replaceBlock,
+  hasUnmanagedMemoryRouterTable, TOML_START, TOML_END, AGENTS_START, AGENTS_END,
+} = require('./managed.cjs');
+const { installHooks, uninstallHooks, isOwnedHook, parseHooks } = require('./hooks.cjs');
+
+function resolveLayout(options = {}) {
+  const env = options.env || process.env;
+  const scope = options.scope || 'user';
+  if (!['user', 'project'].includes(scope)) throw new Error('--scope must be user or project');
+  if (scope === 'user') {
+    const home = codexHome(env);
+    return {
+      scope,
+      root: home,
+      configFile: path.join(home, 'config.toml'),
+      hooksFile: path.join(home, 'hooks.json'),
+      agentsFile: path.join(home, 'AGENTS.md'),
+      runtimeDir: path.join(home, 'memoryrouter', 'runtime'),
+    };
+  }
+  const project = resolveProject(options.projectDir || process.cwd());
+  return {
+    scope,
+    root: project.root,
+    project,
+    configFile: path.join(project.root, '.codex', 'config.toml'),
+    hooksFile: path.join(project.root, '.codex', 'hooks.json'),
+    agentsFile: path.join(project.root, 'AGENTS.md'),
+    runtimeDir: path.join(project.root, '.codex', 'memoryrouter', 'runtime'),
+  };
+}
+
+function copyRuntime(runtimeDir) {
+  const source = path.resolve(__dirname, '..', 'runtime');
+  fs.mkdirSync(runtimeDir, { recursive: true });
+  for (const name of fs.readdirSync(source)) {
+    if (!name.endsWith('.cjs')) continue;
+    fs.copyFileSync(path.join(source, name), path.join(runtimeDir, name));
+  }
+  fs.writeFileSync(path.join(runtimeDir, 'VERSION'), `${INTEGRATION_VERSION}\n`, 'utf8');
+}
+
+function preflight(layout, options = {}) {
+  const configText = readText(layout.configFile);
+  // Validate marker pairs before any file is changed.
+  replaceBlock(configText, TOML_START, TOML_END, '');
+  if (hasUnmanagedMemoryRouterTable(configText) && !options.force) {
+    throw new Error(`An unmanaged [mcp_servers.memoryrouter] table already exists in ${layout.configFile}. Re-run with --force after reviewing the migration backup.`);
+  }
+  if (options.hooks !== false) parseHooks(layout.hooksFile);
+  if (options.agents !== false) replaceBlock(readText(layout.agentsFile), AGENTS_START, AGENTS_END, '');
+}
+
+function init(options = {}) {
+  const layout = resolveLayout(options);
+  const auth = options.auth || 'oauth';
+  if (!['oauth', 'api-key'].includes(auth)) throw new Error('--auth must be oauth or api-key');
+  preflight(layout, options);
+  copyRuntime(layout.runtimeDir);
+  const results = [];
+  results.push(installToml(layout.configFile, { auth, scope: layout.scope, runtimeDir: layout.runtimeDir, force: options.force }));
+  if (options.hooks !== false) results.push(installHooks(layout.hooksFile, layout.runtimeDir, layout.scope));
+  if (options.agents !== false) results.push(installAgents(layout.agentsFile));
+
+  if (options.apiKey) {
+    const current = loadConfig(options.env);
+    saveConfig({ ...current, apiKey: options.apiKey }, options.env);
+  }
+  const manifest = {
+    version: INTEGRATION_VERSION,
+    installedAt: new Date().toISOString(),
+    scope: layout.scope,
+    auth,
+    configFile: layout.configFile,
+    hooksFile: options.hooks === false ? null : layout.hooksFile,
+    agentsFile: options.agents === false ? null : layout.agentsFile,
+    runtimeDir: layout.runtimeDir,
+  };
+  const manifestDir = path.join(dataHome(options.env), 'installations');
+  fs.mkdirSync(manifestDir, { recursive: true, mode: 0o700 });
+  const manifestName = Buffer.from(`${layout.scope}:${layout.root}`).toString('base64url');
+  fs.writeFileSync(path.join(manifestDir, `${manifestName}.json`), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+  return { layout, auth, results, automaticMemory: Boolean(options.apiKey || process.env.MEMORYROUTER_API_KEY || loadConfig(options.env).apiKey) };
+}
+
+function uninstall(options = {}) {
+  const layout = resolveLayout(options);
+  // Refuse partial removal when an owned surface is malformed.
+  replaceBlock(readText(layout.configFile), TOML_START, TOML_END, '');
+  parseHooks(layout.hooksFile);
+  replaceBlock(readText(layout.agentsFile), AGENTS_START, AGENTS_END, '');
+  const results = [
+    uninstallToml(layout.configFile),
+    uninstallHooks(layout.hooksFile),
+    uninstallAgents(layout.agentsFile),
+  ];
+  fs.rmSync(path.dirname(layout.runtimeDir), { recursive: true, force: true });
+  return { layout, results };
+}
+
+function parseVersion(text) {
+  const match = String(text || '').match(/(\d+)\.(\d+)\.(\d+)/);
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function versionAtLeast(actual, minimum) {
+  if (!actual) return false;
+  for (let i = 0; i < 3; i += 1) {
+    if (actual[i] > minimum[i]) return true;
+    if (actual[i] < minimum[i]) return false;
+  }
+  return true;
+}
+
+function codexInfo(cwd, env = process.env) {
+  try {
+    const output = execFileSync('codex', ['--version'], { cwd, env, encoding: 'utf8', timeout: 5000 }).trim();
+    return { installed: true, output, version: parseVersion(output) };
+  } catch { return { installed: false, output: null, version: null }; }
+}
+
+async function fetchJson(url, timeoutMs = 5000, init = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    let data = null;
+    try { data = await response.json(); } catch { /* no json */ }
+    return { ok: response.ok, status: response.status, data };
+  } finally { clearTimeout(timer); }
+}
+
+function probeMcpProtocol() {
+  return fetchJson(MCP_ENDPOINT, 6000, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      jsonrpc: '2.0', id: 1, method: 'initialize',
+      params: { protocolVersion: '2025-11-25', capabilities: {}, clientInfo: { name: 'memoryrouter-codex-doctor', version: INTEGRATION_VERSION } },
+    }),
+  });
+}
+
+function addCheck(checks, name, level, message, details) {
+  checks.push({ name, level, message, ...(details ? { details } : {}) });
+}
+
+async function doctor(options = {}) {
+  const layout = resolveLayout(options);
+  const checks = [];
+  const configText = readText(layout.configFile);
+  const hooksText = readText(layout.hooksFile);
+  const agentsText = readText(layout.agentsFile);
+  const runtimeVersion = readText(path.join(layout.runtimeDir, 'VERSION')).trim();
+  const codex = codexInfo(layout.root, options.env);
+
+  if (!codex.installed) addCheck(checks, 'codex-version', 'warn', 'Codex CLI is not on PATH; app/IDE configuration can still exist, but CLI behavior was not verified.');
+  else if (!versionAtLeast(codex.version, [0, 145, 0])) addCheck(checks, 'codex-version', 'error', `${codex.output} is too old for the lifecycle hooks used here. Upgrade to Codex 0.145.0 or newer.`);
+  else addCheck(checks, 'codex-version', 'pass', `${codex.output} supports current hooks and remote MCP configuration.`);
+
+  addCheck(checks, 'mcp-config', configText.includes(TOML_START) && configText.includes('[mcp_servers.memoryrouter]') ? 'pass' : 'error',
+    configText.includes(TOML_START) ? 'Managed MemoryRouter MCP configuration is present.' : 'Managed MemoryRouter MCP configuration is missing.');
+  addCheck(checks, 'runtime', runtimeVersion === INTEGRATION_VERSION ? 'pass' : 'error',
+    runtimeVersion ? `Installed runtime version is ${runtimeVersion}; package version is ${INTEGRATION_VERSION}.` : 'Managed runtime is missing.');
+
+  let hooks = null;
+  try { hooks = hooksText ? JSON.parse(hooksText) : null; } catch { /* handled */ }
+  const owned = hooks ? Object.values(hooks.hooks || {}).flat().flatMap(group => group.hooks || []).filter(isOwnedHook) : [];
+  addCheck(checks, 'hooks', owned.length >= 7 ? 'pass' : 'error', owned.length ? `${owned.length} managed lifecycle hooks found.` : 'Managed lifecycle hooks are missing or hooks.json is invalid.');
+  addCheck(checks, 'agents', agentsText.includes(AGENTS_START) ? 'pass' : 'warn', agentsText.includes(AGENTS_START) ? 'Managed AGENTS.md guidance is present.' : 'Managed AGENTS.md guidance is missing.');
+
+  const cfg = loadConfig(options.env);
+  const key = process.env.MEMORYROUTER_API_KEY || cfg.apiKey;
+  if (!key) addCheck(checks, 'automatic-auth', 'warn', 'No MemoryRouter API key is available. Remote OAuth tools can work after `codex mcp login memoryrouter`, but automatic hook retrieval/capture is disabled.');
+  else {
+    try {
+      const { stats } = require('../runtime/api.cjs');
+      const response = options.offline ? { ok: true, status: 0 } : await stats(key, { apiBase: cfg.apiBase, timeoutMs: 6000, retries: 0 });
+      addCheck(checks, 'automatic-auth', response.ok ? 'pass' : 'error', options.offline ? 'API key is configured (network check skipped).' : response.ok ? 'API key is valid; automatic retrieval/capture is active.' : `API key validation failed (HTTP ${response.status}).`);
+    } catch (error) { addCheck(checks, 'automatic-auth', 'error', `API key validation failed: ${error.message}`); }
+  }
+
+  if (configText.includes('auth = "oauth"')) {
+    if (options.offline) {
+      addCheck(checks, 'oauth-discovery', 'warn', 'OAuth discovery check skipped in offline mode.');
+      addCheck(checks, 'oauth-session', 'info', 'Browser consent/token issuance is user-specific. Run `codex mcp login memoryrouter`; then `/mcp verbose`. Doctor does not claim login completion without interactive consent.');
+    } else {
+      try {
+        const prm = await fetchJson('https://mcp.memoryrouter.ai/.well-known/oauth-protected-resource');
+        const issuer = prm.data?.authorization_servers?.[0];
+        const metadata = issuer ? await fetchJson(`${issuer}/.well-known/oauth-authorization-server`) : { ok: false };
+        const compatible = prm.ok && prm.data?.resource === MCP_ENDPOINT && metadata.ok && metadata.data?.authorization_endpoint && metadata.data?.token_endpoint && metadata.data?.registration_endpoint && metadata.data?.code_challenge_methods_supported?.includes('S256');
+        addCheck(checks, 'oauth-discovery', compatible ? 'pass' : 'error', compatible
+          ? 'MemoryRouter publishes Codex-compatible RFC 9728 discovery, OAuth metadata, dynamic client registration, and PKCE S256.'
+          : 'OAuth discovery is incomplete or unreachable.', { prmStatus: prm.status, metadataStatus: metadata.status });
+        addCheck(checks, 'oauth-session', 'info', 'Discovery is verified, but browser consent/token issuance is user-specific. Run `codex mcp login memoryrouter`; then `/mcp verbose`. Doctor does not claim login completion without that interactive consent.');
+        const protocol = await probeMcpProtocol();
+        const negotiated = protocol.data?.result?.protocolVersion;
+        addCheck(checks, 'mcp-protocol', negotiated === '2025-11-25' ? 'warn' : protocol.ok ? 'pass' : 'error', negotiated === '2025-11-25'
+          ? 'MemoryRouter currently negotiates legacy MCP 2025-11-25. Codex 0.146 is dual-era and works, but the hosted server is not yet MCP 2026-07-28 compliant.'
+          : protocol.ok ? `MemoryRouter negotiated MCP ${negotiated || 'unknown'}.` : `MCP initialize probe failed (HTTP ${protocol.status}).`);
+      } catch (error) { addCheck(checks, 'oauth-discovery', 'error', `OAuth discovery failed: ${error.message}`); }
+    }
+  } else {
+    addCheck(checks, 'oauth-discovery', 'info', 'Local stdio API-key fallback is configured; Codex OAuth is not used. No secret is stored in project files.');
+  }
+
+  const nativeEnabled = /\[features\][\s\S]*?\bmemories\s*=\s*true\b/.test(configText);
+  const externalDisabled = /\[memories\][\s\S]*?\bdisable_on_external_context\s*=\s*true\b/.test(configText);
+  addCheck(checks, 'native-memories', 'info', nativeEnabled
+    ? `Codex native Memories are enabled${externalDisabled ? ' and external-context generation is disabled.' : '. Consider [memories] disable_on_external_context = true to avoid re-extracting MemoryRouter-assisted chats.'}`
+    : 'Codex native Memories are off or configured in another layer. This integration does not overwrite native-memory settings.');
+
+  const project = resolveProject(layout.root);
+  addCheck(checks, 'project-identity', project.portable ? 'pass' : 'warn', project.portable
+    ? `Project handle ${project.handle} is derived from a canonical git remote and is stable across worktrees/machines.`
+    : `Project handle ${project.handle} falls back to a local ${project.source}; add an origin remote for cross-machine identity.`);
+  addCheck(checks, 'cloud-surface', layout.scope === 'project' ? 'info' : 'warn', layout.scope === 'project'
+    ? 'Project config/hooks can travel with the repository, but cloud environments must trust the project, install Node, and provide MEMORYROUTER_API_KEY. ChatGPT web does not consume local Codex config; use a hosted plugin/connector there.'
+    : 'User-scope config covers local CLI, desktop app, and IDE on this host. Codex cloud and ChatGPT web do not inherit this machine-local config.');
+
+  return { layout, codex, checks, ok: !checks.some(check => check.level === 'error') };
+}
+
+module.exports = { resolveLayout, copyRuntime, preflight, init, uninstall, parseVersion, versionAtLeast, codexInfo, doctor };

package/lib/managed.cjs

@@ -0,0 +1,168 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { INTEGRATION_VERSION, MCP_ENDPOINT } = require('../runtime/constants.cjs');
+
+const TOML_START = '# >>> memoryrouter-codex managed v1 >>>';
+const TOML_END = '# <<< memoryrouter-codex managed v1 <<<';
+const AGENTS_START = '<!-- >>> memoryrouter-codex managed v1 >>> -->';
+const AGENTS_END = '<!-- <<< memoryrouter-codex managed v1 <<< -->';
+
+function readText(file) {
+  try { return fs.readFileSync(file, 'utf8'); } catch (error) {
+    if (error.code === 'ENOENT') return '';
+    throw error;
+  }
+}
+
+function atomicWrite(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, text, 'utf8');
+  fs.renameSync(temp, file);
+}
+
+function replaceBlock(text, start, end, block) {
+  const startIndex = text.indexOf(start);
+  const endIndex = text.indexOf(end);
+  let clean = text;
+  if (startIndex >= 0 || endIndex >= 0) {
+    if (startIndex < 0 || endIndex < startIndex) throw new Error(`Malformed managed block (${start})`);
+    clean = `${text.slice(0, startIndex)}${text.slice(endIndex + end.length)}`;
+  }
+  clean = clean.replace(/\s+$/, '');
+  return block ? `${clean}${clean ? '\n\n' : ''}${start}\n${block.trim()}\n${end}\n` : `${clean}${clean ? '\n' : ''}`;
+}
+
+function hasUnmanagedMemoryRouterTable(text) {
+  const stripped = replaceBlock(text, TOML_START, TOML_END, '');
+  return /^\s*\[mcp_servers\.memoryrouter(?:\.|\])/.test(stripped) || /^\s*\[mcp_servers\.memoryrouter(?:\.|\])/m.test(stripped);
+}
+
+function removeUnmanagedMemoryRouterTables(text) {
+  const withoutManaged = replaceBlock(text, TOML_START, TOML_END, '');
+  const lines = withoutManaged.split('\n');
+  const kept = [];
+  let skip = false;
+  for (const line of lines) {
+    const table = line.match(/^\s*\[([^\]]+)\]\s*(?:#.*)?$/)?.[1]?.trim();
+    if (table) skip = table === 'mcp_servers.memoryrouter' || table.startsWith('mcp_servers.memoryrouter.');
+    if (!skip) kept.push(line);
+  }
+  return kept.join('\n').replace(/\n{3,}/g, '\n\n');
+}
+
+function tomlString(value) { return JSON.stringify(String(value)); }
+
+function mcpBlock({ auth = 'oauth', scope = 'user', runtimeDir }) {
+  const lines = [];
+  if (auth === 'oauth') {
+    lines.push(
+      '[mcp_servers.memoryrouter]',
+      `url = ${tomlString(MCP_ENDPOINT)}`,
+      'auth = "oauth"',
+      'enabled = true',
+      'required = false',
+      'startup_timeout_sec = 20',
+      'tool_timeout_sec = 45',
+      'default_tools_approval_mode = "writes"',
+      'scopes = ["memories:read", "memories:write"]',
+      '',
+      '[mcp_servers.memoryrouter.tools.store_memory]',
+      'approval_mode = "prompt"',
+    );
+  } else if (scope === 'project') {
+    lines.push(
+      '[mcp_servers.memoryrouter]',
+      'command = "npx"',
+      `args = ["-y", "memoryrouter-codex@${INTEGRATION_VERSION}", "mcp-server"]`,
+      'enabled = true',
+      'required = false',
+      'startup_timeout_sec = 20',
+      'tool_timeout_sec = 45',
+      'default_tools_approval_mode = "writes"',
+      '',
+      '[mcp_servers.memoryrouter.tools.memory_forget]',
+      'approval_mode = "prompt"',
+    );
+  } else {
+    lines.push(
+      '[mcp_servers.memoryrouter]',
+      'command = "node"',
+      `args = [${tomlString(path.join(runtimeDir, 'mcp-stdio.cjs'))}]`,
+      'enabled = true',
+      'required = false',
+      'startup_timeout_sec = 20',
+      'tool_timeout_sec = 45',
+      'default_tools_approval_mode = "writes"',
+      '',
+      '[mcp_servers.memoryrouter.tools.memory_forget]',
+      'approval_mode = "prompt"',
+    );
+  }
+  return lines.join('\n');
+}
+
+function installToml(file, options) {
+  const current = readText(file);
+  if (hasUnmanagedMemoryRouterTable(current) && !options.force) {
+    throw new Error(`An unmanaged [mcp_servers.memoryrouter] table already exists in ${file}. Re-run with --force after backing it up, or remove/rename that table.`);
+  }
+  let base = current;
+  let backup = null;
+  if (hasUnmanagedMemoryRouterTable(current) && options.force) {
+    backup = `${file}.memoryrouter-backup-${Date.now()}`;
+    fs.copyFileSync(file, backup);
+    base = removeUnmanagedMemoryRouterTables(current);
+  }
+  const updated = replaceBlock(base, TOML_START, TOML_END, mcpBlock(options));
+  atomicWrite(file, updated);
+  return { changed: updated !== current, file, ...(backup ? { backup } : {}) };
+}
+
+function uninstallToml(file) {
+  const current = readText(file);
+  if (!current.includes(TOML_START)) return { changed: false, file };
+  const updated = replaceBlock(current, TOML_START, TOML_END, '');
+  atomicWrite(file, updated);
+  return { changed: true, file };
+}
+
+function agentsBlock() {
+  return `## MemoryRouter memory\n\n- MemoryRouter is the durable cross-machine, cross-tool, and team/auditable memory layer. Codex native Memories may remain enabled as the local personal recall layer.\n- Automatic hooks search project-scoped memory before each prompt and capture completed turns when a MemoryRouter API key is configured.\n- For explicit recall, search MemoryRouter before answering questions about prior decisions, preferences, incidents, or unfinished work. Depending on auth mode, the tool is named \`search_memories\` or \`memory_search\`.\n- Store only concise, durable decisions, preferences, facts, and incident outcomes. Depending on auth mode, use \`store_memory\` or \`memory_store\`. Do not duplicate a completed turn that hooks already captured.\n- Keep and cite returned \`mrh_...\` handles when a specific memory must be referenced later.\n- Project scope is derived from the canonical git remote when available, so worktrees and machines share identity without uploading local paths.\n- If MemoryRouter is offline, continue the task without memory; never block work on recall or capture.`;
+}
+
+function installAgents(file) {
+  const current = readText(file);
+  const updated = replaceBlock(current, AGENTS_START, AGENTS_END, agentsBlock());
+  atomicWrite(file, updated);
+  return { changed: updated !== current, file };
+}
+
+function uninstallAgents(file) {
+  const current = readText(file);
+  if (!current.includes(AGENTS_START)) return { changed: false, file };
+  const updated = replaceBlock(current, AGENTS_START, AGENTS_END, '');
+  if (!updated.trim()) fs.rmSync(file, { force: true });
+  else atomicWrite(file, updated);
+  return { changed: true, file };
+}
+
+module.exports = {
+  TOML_START,
+  TOML_END,
+  AGENTS_START,
+  AGENTS_END,
+  readText,
+  atomicWrite,
+  replaceBlock,
+  hasUnmanagedMemoryRouterTable,
+  removeUnmanagedMemoryRouterTables,
+  mcpBlock,
+  installToml,
+  uninstallToml,
+  agentsBlock,
+  installAgents,
+  uninstallAgents,
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "memoryrouter-codex",
+  "version": "1.0.0",
+  "description": "Automatic, project-scoped MemoryRouter memory for OpenAI Codex",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "memoryrouter-codex": "bin/cli.cjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "runtime/",
+    "README.md",
+    "RESEARCH.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.cjs",
+    "typecheck": "node --check bin/cli.cjs && for f in lib/*.cjs runtime/*.cjs; do node --check \"$f\"; done",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "keywords": [
+    "codex",
+    "openai",
+    "memory",
+    "mcp",
+    "hooks",
+    "memoryrouter"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MemoryRouter/MemoryRouter.git",
+    "directory": "integrations/codex"
+  }
+}

package/runtime/api.cjs

@@ -0,0 +1,80 @@
+'use strict';
+
+const { INTEGRATION_VERSION } = require('./constants.cjs');
+
+function sleep(ms) { return new Promise(resolve => setTimeout(resolve, ms)); }
+
+async function request(method, endpoint, options = {}) {
+  const {
+    key,
+    body,
+    headers = {},
+    timeoutMs = 7000,
+    retries = method === 'GET' || endpoint.endsWith('/search') ? 2 : 0,
+    apiBase = 'https://api.memoryrouter.ai',
+  } = options;
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetch(`${String(apiBase).replace(/\/$/, '')}${endpoint}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${key}`,
+          'Content-Type': 'application/json',
+          'User-Agent': `memoryrouter-codex/${INTEGRATION_VERSION}`,
+          ...headers,
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: controller.signal,
+      });
+      let data = null;
+      try { data = await response.json(); } catch { /* non-json */ }
+      if (response.ok || response.status < 500 || attempt === retries) {
+        return { ok: response.ok, status: response.status, data };
+      }
+      lastError = new Error(`MemoryRouter returned HTTP ${response.status}`);
+    } catch (error) {
+      lastError = error;
+      if (attempt === retries) throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+    await sleep(100 * (2 ** attempt));
+  }
+  throw lastError || new Error('MemoryRouter request failed');
+}
+
+function search(key, query, limit, options = {}) {
+  return request('POST', '/v1/memory/search', {
+    ...options,
+    key,
+    body: { query, limit },
+    headers: options.sessionId ? { 'X-Session-ID': options.sessionId } : {},
+    retries: options.retries ?? 2,
+  });
+}
+
+function ingest(key, messages, sessionId, options = {}) {
+  return request('POST', '/v1/memory/ingest', {
+    ...options,
+    key,
+    body: { messages, session_id: sessionId, model: 'codex' },
+    retries: 0,
+  });
+}
+
+function stats(key, options = {}) {
+  return request('GET', '/v1/memory/stats', { ...options, key, retries: options.retries ?? 1 });
+}
+
+function warmup(key, options = {}) {
+  return request('POST', '/v1/memory/warmup', { ...options, key, body: {}, retries: 0 });
+}
+
+function clearVault(key, options = {}) {
+  return request('DELETE', '/v1/memory', { ...options, key, retries: 0 });
+}
+
+module.exports = { sleep, request, search, ingest, stats, warmup, clearVault };