memoryrouter-codex 1.3.0 → 1.4.0

package/README.md

@@ -165,6 +165,8 @@ MemoryRouter's Reflection Hierarchy consolidates raw memories into higher-tier r
 
 Reflection prompts are always server-authored. This package never writes its own consolidation instructions and refuses to reflect if the server response carries none. See https://docs.memoryrouter.ai/reflections for endpoint semantics, lease rules, and billing.
 
+**Automatic consolidation (default on):** when a hook's retrieval response reports debt above the server's threshold, the hooks spawn the same reflect loop as a detached background process (`codex exec` headless, your own inference). Rails: max 3 batches per trigger with a debt re-check between batches, a machine-wide lockfile at `~/.memoryrouter/consolidate.lock` (stale after 20 minutes), a 30 minute cooldown after each completed run, and silent failure with logs at `~/.memoryrouter/consolidate.log`. The threshold always comes from the server response. Opt out with `"autoConsolidate": false` in `~/.memoryrouter/codex/config.json`; the suggestion line, stdio tools, and manual `reflect` keep working.
+
 ## Context budget and failure behavior
 
 - Default injected context cap: 12,000 characters, assembled at memory boundaries.

package/bin/cli.cjs

@@ -23,7 +23,7 @@ function parseArgs(argv) {
 }
 
 function usage() {
-  return `memoryrouter-codex ${INTEGRATION_VERSION}\n\nUsage:\n  memoryrouter-codex init [--scope user|project] [--auth oauth|api-key]\n                          [--project-dir PATH] [--api-key-stdin]\n                          [--no-hooks] [--no-agents]\n  memoryrouter-codex doctor [--scope user|project] [--project-dir PATH] [--offline]\n  memoryrouter-codex uninstall [--scope user|project] [--project-dir PATH]\n  memoryrouter-codex reflect [--tier 1|2] [--batches N|all] [--max-tokens N] [--dry-run]\n  memoryrouter-codex import [--instructions [--run]] [--file PATH] [--dismiss] [--yes]\n  memoryrouter-codex mcp-server\n\nImport:\n  Import historical Codex conversations into your vault. --instructions\n  fetches the server's extraction prompt for the host agent to execute\n  (--run spawns it via codex exec); --file uploads a JSONL extract with a\n  preview, price quote, explicit approval (--yes for non-interactive),\n  idempotent batches, and resume; --dismiss silences the import nudge\n  permanently. Re-running --file is always safe: committed batches replay\n  for free and duplicates are never re-billed.\n\nReflect:\n  Consolidates unconsolidated memories into reflections using Codex itself as\n  the model (codex exec, you pay your own inference). Server-authored\n  instructions; resumable; no local state. --dry-run prints the checkout and\n  lets the lease expire without committing.\n\nAuth modes:\n  oauth    Current remote MCP at ${'https://mcp.memoryrouter.ai/mcp'} (default).\n           Run \`codex mcp login memoryrouter\` after init. Hooks additionally\n           require MEMORYROUTER_API_KEY or a key saved with --api-key-stdin.\n  api-key  Local stdio MCP fallback plus automatic hooks. The key is read only\n           from the environment/private config, never from project files.\n\nSecure key setup:\n  printf '%s' "$MEMORYROUTER_API_KEY" | memoryrouter-codex init --api-key-stdin\n`;
+  return `memoryrouter-codex ${INTEGRATION_VERSION}\n\nUsage:\n  memoryrouter-codex init [--scope user|project] [--auth oauth|api-key]\n                          [--project-dir PATH] [--api-key-stdin]\n                          [--no-hooks] [--no-agents]\n  memoryrouter-codex doctor [--scope user|project] [--project-dir PATH] [--offline]\n  memoryrouter-codex uninstall [--scope user|project] [--project-dir PATH]\n  memoryrouter-codex reflect [--tier 1|2] [--batches N|all] [--max-tokens N] [--dry-run]\n  memoryrouter-codex import [--instructions [--run]] [--file PATH] [--dismiss] [--yes]\n  memoryrouter-codex mcp-server\n\nImport:\n  Import historical Codex conversations into your vault. --instructions\n  fetches the server's extraction prompt for the host agent to execute\n  (--run spawns it via codex exec); --file uploads a JSONL extract with a\n  preview, price quote, explicit approval (--yes for non-interactive),\n  idempotent batches, and resume; --dismiss silences the import nudge\n  permanently. Re-running --file is always safe: committed batches replay\n  for free and duplicates are never re-billed.\n\nReflect:\n  Consolidates unconsolidated memories into reflections using Codex itself as\n  the model (codex exec, you pay your own inference). Server-authored\n  instructions; resumable; no local state. --dry-run prints the checkout and\n  lets the lease expire without committing.\n  Automatic mode: when the server reports consolidation debt above its\n  threshold, the hooks spawn this same loop in the background (max 3 batches\n  per trigger, 30 minute cooldown, machine-wide lockfile at\n  ~/.memoryrouter/consolidate.lock). Opt out with "autoConsolidate": false in\n  ~/.memoryrouter/codex/config.json. Logs: ~/.memoryrouter/consolidate.log\n\nAuth modes:\n  oauth    Current remote MCP at ${'https://mcp.memoryrouter.ai/mcp'} (default).\n           Run \`codex mcp login memoryrouter\` after init. Hooks additionally\n           require MEMORYROUTER_API_KEY or a key saved with --api-key-stdin.\n  api-key  Local stdio MCP fallback plus automatic hooks. The key is read only\n           from the environment/private config, never from project files.\n\nSecure key setup:\n  printf '%s' "$MEMORYROUTER_API_KEY" | memoryrouter-codex init --api-key-stdin\n`;
 }
 
 function optionsFromArgs(args) {
@@ -77,6 +77,15 @@ async function main() {
     process.exitCode = result.ok ? 0 : 1;
     return;
   }
+  if (command === 'reflect-auto') {
+    // Internal entrypoint for the detached automatic consolidation run
+    // spawned by the hooks. Silent to the user's session; logs to
+    // ~/.memoryrouter/consolidate.log. Always exits 0.
+    const { runAutoConsolidate } = require('../runtime/auto.cjs');
+    try { await runAutoConsolidate(); } catch { /* logged */ }
+    process.exitCode = 0;
+    return;
+  }
   if (command === 'import') {
     const { loadConfig, getApiKey } = require('../runtime/config.cjs');
     const { runInstructions, runDismiss, runImportFile } = require('../runtime/import.cjs');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memoryrouter-codex",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Automatic, project-scoped MemoryRouter memory for OpenAI Codex",
   "license": "MIT",
   "type": "commonjs",

package/runtime/auto.cjs

@@ -0,0 +1,235 @@
+'use strict';
+// Automatic threshold-activated consolidation for the codex connector.
+//
+// When a hook's search/prepare response carries a non-null
+// reflection.suggestion (the server's own threshold decision; no threshold is
+// ever hardcoded client-side), the hook spawns the existing reflect loop
+// (runtime/reflect.cjs, codex exec headless) as a detached background
+// process. The user's session is never blocked; failures are silent to the
+// session and logged to ~/.memoryrouter/consolidate.log.
+//
+// Rails: machine-wide lockfile (~/.memoryrouter/consolidate.lock, pid +
+// timestamp, stale after 20 minutes, shared with the other MemoryRouter
+// connectors), max 3 batches per trigger with a debt re-check between
+// batches, 30 minute cooldown after a completed run (plus a 10 minute
+// attempt cooldown so persistent failures cannot spam the host model), and
+// config autoConsolidate: false (default true) to opt out.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const childProcess = require('child_process');
+
+const LOCK_STALE_MS = 20 * 60 * 1000;
+const COOLDOWN_MS = 30 * 60 * 1000;
+const ATTEMPT_COOLDOWN_MS = 10 * 60 * 1000;
+const MAX_BATCHES_PER_TRIGGER = 3;
+
+// The lock/cooldown directory is intentionally the shared ~/.memoryrouter
+// root (not the codex-specific subdirectory) so all MemoryRouter connectors
+// on one machine coordinate through the same lockfile.
+function autoDir(env = process.env) {
+  return env.MEMORYROUTER_AUTO_DIR || path.join(os.homedir(), '.memoryrouter');
+}
+
+function lockPath(env) { return path.join(autoDir(env), 'consolidate.lock'); }
+function statePath(env) { return path.join(autoDir(env), 'consolidate-state.json'); }
+function logPath(env) { return path.join(autoDir(env), 'consolidate.log'); }
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+
+function appendLog(line, env = process.env) {
+  try {
+    ensureDir(autoDir(env));
+    const file = logPath(env);
+    try {
+      if (fs.statSync(file).size > 1024 * 1024) fs.renameSync(file, `${file}.1`);
+    } catch { /* new file */ }
+    fs.appendFileSync(file, `[${new Date().toISOString()}] ${line}\n`, { mode: 0o600 });
+  } catch { /* logging never throws */ }
+}
+
+function readState(env = process.env) {
+  try { return JSON.parse(fs.readFileSync(statePath(env), 'utf8')) || {}; } catch { return {}; }
+}
+
+function writeState(patch, env = process.env) {
+  try {
+    ensureDir(autoDir(env));
+    const next = { ...readState(env), ...patch };
+    fs.writeFileSync(statePath(env), JSON.stringify(next, null, 2) + '\n', { mode: 0o600 });
+  } catch { /* state is best-effort */ }
+}
+
+function lockFresh(env = process.env, now = Date.now()) {
+  try {
+    const info = JSON.parse(fs.readFileSync(lockPath(env), 'utf8'));
+    return now - Number(info.at) <= LOCK_STALE_MS;
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return false;
+    try { return now - fs.statSync(lockPath(env)).mtimeMs <= LOCK_STALE_MS; } catch { return false; }
+  }
+}
+
+function acquireLock(env = process.env, now = Date.now()) {
+  ensureDir(autoDir(env));
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const fd = fs.openSync(lockPath(env), 'wx', 0o600);
+      fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, at: now }) + '\n');
+      fs.closeSync(fd);
+      return true;
+    } catch (err) {
+      if (!err || err.code !== 'EEXIST') return false;
+      if (lockFresh(env, now)) return false;
+      try { fs.unlinkSync(lockPath(env)); } catch { return false; }
+    }
+  }
+  return false;
+}
+
+function releaseLock(env = process.env) {
+  try { fs.unlinkSync(lockPath(env)); } catch { /* already gone */ }
+}
+
+function cooldownActive(env = process.env, now = Date.now()) {
+  const state = readState(env);
+  const completed = Number(state.lastCompletedAt);
+  if (Number.isFinite(completed) && now - completed < COOLDOWN_MS) return true;
+  const attempted = Number(state.lastAttemptAt);
+  if (Number.isFinite(attempted) && now - attempted < ATTEMPT_COOLDOWN_MS) return true;
+  return false;
+}
+
+// Tier choice comes entirely from the server's debt block: per-tier debt and
+// the threshold are both server-reported.
+function pickTier(debt) {
+  const threshold = Number(debt && debt.threshold_importance);
+  const rawEquiv = Number(debt && debt.unconsolidated && debt.unconsolidated.raw
+    && debt.unconsolidated.raw.importance_equiv);
+  const tier2 = Number(debt && debt.unconsolidated && debt.unconsolidated.tier2
+    && debt.unconsolidated.tier2.importance);
+  if (Number.isFinite(threshold) && threshold > 0) {
+    if (Number.isFinite(rawEquiv) && rawEquiv >= threshold) return 1;
+    if (Number.isFinite(tier2) && tier2 >= threshold) return 2;
+  }
+  return /tier 2/i.test(String(debt && debt.suggestion || '')) ? 2 : 1;
+}
+
+function maxBatches(env = process.env) {
+  const raw = parseInt(env.MEMORYROUTER_AUTO_MAX_BATCHES, 10);
+  if (Number.isInteger(raw) && raw >= 1) return Math.min(raw, MAX_BATCHES_PER_TRIGGER);
+  return MAX_BATCHES_PER_TRIGGER;
+}
+
+/**
+ * Trigger check + detached spawn, called from the hook path with the
+ * reflection debt block the hook already received. Never blocks, never
+ * throws into the hook.
+ */
+function maybeSpawnAutoConsolidate(reflection, config = {}, options = {}) {
+  const env = options.env || process.env;
+  try {
+    if (env.MEMORYROUTER_DISABLE === '1') return false;
+    if (config.autoConsolidate === false) return false;
+    if (!reflection || !reflection.suggestion) return false;
+    const now = options.now || Date.now();
+    if (cooldownActive(env, now)) return false;
+    if (lockFresh(env, now)) return false;
+
+    const spawner = options.spawn || childProcess.spawn;
+    const cliPath = options.cliPath || path.resolve(__dirname, '..', 'bin', 'cli.cjs');
+    ensureDir(autoDir(env));
+    const out = fs.openSync(logPath(env), 'a');
+    try {
+      const child = spawner(process.execPath, [cliPath, 'reflect-auto'], {
+        detached: true,
+        stdio: ['ignore', out, out],
+        env: { ...env },
+      });
+      if (child && child.unref) child.unref();
+    } finally {
+      try { fs.closeSync(out); } catch { /* fd handed to child */ }
+    }
+    appendLog(`trigger: spawned reflect-auto (suggestion: ${reflection.suggestion})`, env);
+    return true;
+  } catch (err) {
+    appendLog(`trigger error: ${err && err.message}`, env);
+    return false;
+  }
+}
+
+/**
+ * The detached background run: lock, consolidate up to 3 batches re-checking
+ * debt between each via the API, record completion, release. Reuses the
+ * EXISTING reflect loop (runtime/reflect.cjs); nothing is duplicated.
+ */
+async function runAutoConsolidate(options = {}) {
+  const env = options.env || process.env;
+  const now = options.now || (() => Date.now());
+  const api = options.api || require('./api.cjs');
+  const runReflect = options.runReflect || require('./reflect.cjs').runReflect;
+  const { loadConfig, getApiKey } = require('./config.cjs');
+  const config = options.config || loadConfig(env);
+  const key = options.key || getApiKey(env, config);
+  const log = (line) => appendLog(line, env);
+  if (!key) { log('auto: no API key available; skipping'); return { committed: 0, reason: 'no-key' }; }
+
+  if (cooldownActive(env, now())) { log('auto: cooldown active; skipping'); return { committed: 0, reason: 'cooldown' }; }
+  if (!acquireLock(env, now())) { log('auto: another consolidation run holds the lock; skipping'); return { committed: 0, reason: 'locked' }; }
+
+  writeState({ lastAttemptAt: now() }, env);
+  let committed = 0;
+  try {
+    const bound = maxBatches(env);
+    for (let batch = 0; batch < bound; batch += 1) {
+      const probe = await api.debtProbe(key, { apiBase: config.apiBase });
+      const debt = probe && probe.ok && probe.data && probe.data.reflection;
+      if (!debt || !debt.suggestion) {
+        log(`auto: debt below threshold after ${committed} batch(es); stopping`);
+        break;
+      }
+      const tier = pickTier(debt);
+      log(`auto: batch ${batch + 1}/${bound} starting (tier ${tier}; ${debt.suggestion})`);
+      let result;
+      try {
+        result = await runReflect({ key, tier, batches: '1', env, config, log });
+      } catch (err) {
+        log(`auto: reflect failed: ${err && err.message}`);
+        break;
+      }
+      if (!result || !result.completed) {
+        log('auto: no batch committed; stopping');
+        break;
+      }
+      committed += result.completed;
+    }
+    if (committed > 0) {
+      writeState({ lastCompletedAt: now() }, env);
+      log(`auto: run complete, ${committed} batch(es) committed`);
+    }
+  } finally {
+    releaseLock(env);
+  }
+  return { committed };
+}
+
+module.exports = {
+  maybeSpawnAutoConsolidate,
+  runAutoConsolidate,
+  acquireLock,
+  releaseLock,
+  lockFresh,
+  cooldownActive,
+  pickTier,
+  appendLog,
+  readState,
+  writeState,
+  autoDir,
+  LOCK_STALE_MS,
+  COOLDOWN_MS,
+  ATTEMPT_COOLDOWN_MS,
+  MAX_BATCHES_PER_TRIGGER,
+};

package/runtime/constants.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-const INTEGRATION_VERSION = '1.1.0';
+const INTEGRATION_VERSION = '1.4.0';
 const RUNTIME_SCHEMA_VERSION = 1;
 const API_BASE = 'https://api.memoryrouter.ai';
 const MCP_ENDPOINT = 'https://mcp.memoryrouter.ai/mcp';

package/runtime/hook.cjs

@@ -4,6 +4,7 @@
 const { loadConfig, getApiKey, loadSessionState, saveSessionState, pruneState, recordHealth } = require('./config.cjs');
 const { resolveProject } = require('./project.cjs');
 const { searchScoped, storeScoped, memoryHandle } = require('./memory.cjs');
+const { maybeSpawnAutoConsolidate } = require('./auto.cjs');
 
 function debug(...values) {
   if (process.env.MEMORYROUTER_DEBUG) console.error('[memoryrouter-codex]', ...values);
@@ -95,6 +96,10 @@ async function handleInject(input, context) {
     memories: result.memories?.length || 0,
     status: result.status,
   }, context.env);
+  // Automatic consolidation (default on; config autoConsolidate: false opts
+  // out): detached fire-and-forget background run when the server says
+  // should-consolidate. Never blocks the hook.
+  maybeSpawnAutoConsolidate(result.reflection, context.config, { env: context.env });
   emitContext('UserPromptSubmit', maybeAppendNudge(result.context, result.reflection, input.session_id, context, result.importState));
 }
 
@@ -110,6 +115,7 @@ async function handleSessionStart(input, context) {
     project: context.project.handle,
     memories: result.memories?.length || 0,
   }, context.env);
+  maybeSpawnAutoConsolidate(result.reflection, context.config, { env: context.env });
   emitContext('SessionStart', maybeAppendNudge(result.context, result.reflection, input.session_id, context, result.importState));
 }