memoryrouter-codex 1.0.0 → 1.2.0

package/README.md

@@ -2,15 +2,17 @@
 
 Native Codex integration for durable MemoryRouter memory. It uses Codex's current MCP, lifecycle hooks, and `AGENTS.md` surfaces rather than pretending that model-selected MCP calls alone are automatic memory.
 
+> **Release status:** `memoryrouter-codex@1.1.0` is the published npm release. Its automatic capture is message-only: one user request plus the final assistant response, with no tool payloads.
+
 ## What this integration does
 
 | Layer | Behavior |
 | --- | --- |
 | `UserPromptSubmit` hook | Searches MemoryRouter before every prompt and injects bounded, project-scoped context as developer context. |
-| `PostToolUse` + `Stop` hooks | Captures the user request, stable hook-provided tool inputs/results, and final answer after each completed turn. |
+| `Stop` hook | Captures only the user request and final assistant response after each completed turn. Tool names, inputs, and results are excluded. |
 | `SubagentStop` hook | Captures the stable final outcome of completed subagents without parsing their unstable transcript files. |
-| `PreCompact` / compact `SessionStart` | Checkpoints work before compaction and recalls context before Codex continues after compaction. |
-| `SessionEnd` | Best-effort final checkpoint within Codex's three-second SessionEnd budget. |
+| `PreCompact` / compact `SessionStart` | Checkpoints only the current user request and final assistant response when present, then recalls context before Codex continues after compaction. |
+| `SessionEnd` | Best-effort message-only final checkpoint within Codex's three-second SessionEnd budget. |
 | Remote MCP | OAuth-based explicit search/store through `https://mcp.memoryrouter.ai/mcp`. |
 | Local MCP fallback | API-key-authenticated stdio tools with strict project filtering, handles, local suppression, status, and full-vault clear confirmation. |
 | `AGENTS.md` | Tells Codex when to recall/store and how MemoryRouter coexists with native Memories. |
@@ -37,7 +39,7 @@ Obtain a MemoryRouter memory key from your account. Pass it on stdin so it does
 
 ```bash
 printf '%s' "$MEMORYROUTER_API_KEY" | \
-  npx -y memoryrouter-codex@1.0.0 init --scope user --auth oauth --api-key-stdin
+  npx -y memoryrouter-codex@1.1.0 init --scope user --auth oauth --api-key-stdin
 
 codex mcp login memoryrouter
 memoryrouter-codex doctor --scope user
@@ -59,7 +61,7 @@ If you prefer not to persist the key, omit `--api-key-stdin` and ensure `MEMORYR
 ```bash
 cd /path/to/repository
 printf '%s' "$MEMORYROUTER_API_KEY" | \
-  npx -y memoryrouter-codex@1.0.0 init --scope project --auth oauth --api-key-stdin
+  npx -y memoryrouter-codex@1.1.0 init --scope project --auth oauth --api-key-stdin
 codex mcp login memoryrouter
 ```
 
@@ -69,7 +71,7 @@ This writes managed blocks/files under the repository's `AGENTS.md` and `.codex/
 
 ```bash
 printf '%s' "$MEMORYROUTER_API_KEY" | \
-  npx -y memoryrouter-codex@1.0.0 init --scope user --auth api-key --api-key-stdin
+  npx -y memoryrouter-codex@1.1.0 init --scope user --auth api-key --api-key-stdin
 ```
 
 This uses a local stdio MCP server and the MemoryRouter API. It does not put the memory key in Codex config. The fallback tools are:
@@ -126,6 +128,10 @@ Automatic memories use an envelope containing project handle, stable memory hand
 
 Set `retrievalScope` to `"vault"` in the private config only if you intentionally want unscoped automatic recall.
 
+## Historical import boundary
+
+The Codex package captures future work after installation. It does not ship a deterministic importer for ChatGPT exports or prior Codex conversations. A local Codex workflow can inspect an extracted export and curate selected facts, but that is experimental guided curation, not checkpointed/resumable/reconciled archive ingestion. Remote MCP OAuth connection by itself never imports history.
+
 ## Handles, deduplication, retries, and forgetting
 
 - Handles (`mrh_...`) are content-derived from project, kind, and normalized content.
@@ -136,13 +142,24 @@ Set `retrievalScope` to `"vault"` in the private config only if you intentionall
 - Whole-vault deletion is available only when `memory_forget` receives the exact phrase `CLEAR MY ENTIRE MEMORYROUTER VAULT`. It is irreversible and should require Codex approval.
 - Use the MemoryRouter dashboard for server-side audit/management where available.
 
+## Reflections and consolidation
+
+MemoryRouter's Reflection Hierarchy consolidates raw memories into higher-tier reflections. This package exposes it in two lanes:
+
+- **CLI:** `memoryrouter-codex reflect [--tier 1|2] [--batches N|all] [--max-tokens N] [--dry-run]`. The loop checks out a batch of unconsolidated memories under a 15 minute server lease, runs Codex itself headlessly (`codex exec`, you pay your own inference) with server-authored instructions, and commits the resulting reflection entries. It keeps no local state: if anything dies mid-loop, the lease expires server-side and the memories return to the pool, so re-running always resumes from the oldest unconsolidated memory. `--dry-run` prints the checkout and prompt and deliberately lets the lease expire (this bills one checkout).
+- **Local stdio MCP:** `memory_consolidate` (checkout, returns memory texts plus the server's reflection instructions) and `memory_commit_reflections` (submit entries for the batch, idempotent on replay). The model never sees memory row IDs; it works with bare texts and one opaque `cb_` batch id.
+
+`memory_search` accepts optional `tiers` (subset of `[1, 2, 3]`: raw, reflections, high-level reflections) and `importance` (integer 1 to 10 minimum threshold; only reflections carry ratings). `memory_status` reports the current reflection debt. When the server reports that consolidation is available, hook-injected context appends a one-line hint at most once per session per 24 hours.
+
+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.
+
 ## Context budget and failure behavior
 
 - Default injected context cap: 12,000 characters, assembled at memory boundaries.
 - Hook `additionalContextLimit`: approximately 3,500 tokens, so Codex can spill unexpectedly large context safely instead of consuming the whole model window.
 - Candidate search default: 12 before strict project filtering.
 - All hook entrypoints exit zero on missing credentials, malformed input, API errors, and timeouts. Memory never blocks Codex work.
-- Hook status is recorded without secrets in `~/.memoryrouter/codex/health.json`. Search/store/forget outcomes (metadata only, never memory content or keys) append to a rotating 5 MiB local `~/.memoryrouter/codex/audit.jsonl`. `memory_status` exposes both locations. This is a host-local integration audit, not a server-wide team access log. Session/trace state older than 30 days is pruned at session start.
+- Hook status is recorded without secrets in `~/.memoryrouter/codex/health.json`. Search/store/forget outcomes (metadata only, never memory content or keys) append to a rotating 5 MiB local `~/.memoryrouter/codex/audit.jsonl`. `memory_status` exposes both locations. This is a host-local integration audit, not a server-wide team access log. Session state and any legacy pre-1.1 trace files older than 30 days are pruned at session start. Version 1.1 creates no tool trace files.
 - Set `MEMORYROUTER_DEBUG=1` for hook errors on stderr. Debug is off by default.
 
 ## Codex native Memories coexistence
@@ -172,7 +189,7 @@ Live verification with official `@openai/codex` **0.146.0** established:
 5. Codex generates an authorization URL with PKCE S256, `memories:read memories:write`, the exact RFC 8707 resource, and a loopback callback.
 6. The browser consent/token step was deliberately not completed by the package test because it is account-specific. Therefore `doctor` verifies discovery compatibility but never reports an OAuth session as logged in without user consent. Use `codex mcp login memoryrouter` and `/mcp verbose` to complete/verify it.
 
-The remote server currently negotiates legacy MCP `2025-11-25`. Codex 0.146 remains dual-era and initializes it successfully today. MemoryRouter's MCP server still needs its separate `2026-07-28` protocol modernization; this client integration does not hide that server limitation.
+The production server supports modern stateless MCP `2026-07-28` and still accepts `2025-11-25`, `2025-06-18`, and `2025-03-26` for handshake-era clients. Codex 0.146 initializes the compatibility path successfully. Do not infer Codex support from protocol negotiation alone; verify OAuth login, `/mcp verbose`, and the actual tool inventory.
 
 ## Doctor
 
@@ -189,15 +206,15 @@ Doctor checks Codex version, managed config, runtime version, hook count, `AGENT
 Upgrade idempotently by re-running the pinned/new package:
 
 ```bash
-npx -y memoryrouter-codex@1.0.0 init --scope user
+npx -y memoryrouter-codex@1.1.0 init --scope user
 ```
 
 Uninstall:
 
 ```bash
-npx -y memoryrouter-codex@1.0.0 uninstall --scope user
+npx -y memoryrouter-codex@1.1.0 uninstall --scope user
 # or
-npx -y memoryrouter-codex@1.0.0 uninstall --scope project --project-dir /repo
+npx -y memoryrouter-codex@1.1.0 uninstall --scope project --project-dir /repo
 ```
 
 Uninstall deliberately retains `~/.memoryrouter/codex/` because another project installation may use the credentials and local suppression state. Delete that private directory manually only when no integration uses it.
@@ -205,8 +222,8 @@ Uninstall deliberately retains `~/.memoryrouter/codex/` because another project
 ## Honest limitations
 
 - Hooks are the deterministic automatic path. Remote MCP alone remains model-invoked, not guaranteed every turn.
-- The transcript file path supplied to hooks is documented as unstable, so this integration does **not** parse Codex transcript JSONL. It captures only stable hook fields: prompt, tool input/result, and final assistant message.
-- Hosted tools such as web search do not currently emit `PostToolUse`; their detailed output is not automatically captured unless reflected in the final response.
+- The transcript file path supplied to hooks is documented as unstable, so this integration does **not** parse Codex transcript JSONL. Version 1.1 captures only the stable user prompt and `last_assistant_message`.
+- Tool-call records are intentionally excluded. MemoryRouter does not store tool names, tool IDs, tool inputs, tool results, commands, patches, or other `PostToolUse` payloads from automatic Codex capture. Important outcomes must appear in the final assistant response to be retained.
 - Some specialized tool paths can opt out of hooks. Codex documents hooks as a useful extension surface, not a complete enforcement boundary.
 - SessionEnd can happen after a 30-minute idle period and has a three-second maximum. It is a best-effort checkpoint; normal `Stop` capture is the primary write path.
 - Project scoping is strict for this package's automatic retrieval/local MCP. The existing hosted remote MCP server has no first-class project argument, so use local tools/hooks when cross-project isolation is required.

package/RESEARCH.md

@@ -17,7 +17,7 @@ Verified 2026-07-31. This is engineering evidence, not public marketing copy.
 ## Platform findings used in the architecture
 
 - Current Codex supports command hooks for `SessionStart`, `SessionEnd`, `PreToolUse`, `PostToolUse`, `PreCompact`, `PostCompact`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, and `Stop`.
-- Hook transcript paths are explicitly documented as unstable. The integration therefore uses stable event fields and an append-only local tool trace rather than parsing transcript JSONL.
+- Hook transcript paths are explicitly documented as unstable. Version 1.0 used stable event fields plus an append-only local `PostToolUse` trace. Version 1.1 removes that trace and its hook entirely: completed-turn storage is composed only from the `UserPromptSubmit` prompt and Stop's stable `last_assistant_message`.
 - Hooks are enabled by default and project hooks require trust. `features.codex_hooks` is only a deprecated alias; the current canonical key is `features.hooks`.
 - Remote MCP OAuth no longer needs `experimental_use_rmcp_client` in current Codex. That key is absent from the current configuration reference.
 - The local CLI, desktop Codex host, and IDE extension share Codex config. ChatGPT web uses hosted plugin tools and does not inherit local config.
@@ -54,4 +54,8 @@ npm run typecheck
 npm pack --dry-run
 ```
 
-The integration suite covers config migration/backup, foreign-config preservation, corrupt config fail-closed behavior, idempotent upgrades, uninstall, project/worktree identity, project-vs-vault filtering, native-memory config coexistence, OAuth/local fallback configuration, read retries, write deduplication, hook fail-open behavior, full stable-field turn capture, context budgets, local suppression, and MCP tool annotations.
+The integration suite covers config migration/backup, foreign-config preservation, corrupt config fail-closed behavior, idempotent upgrades, uninstall, project/worktree identity, project-vs-vault filtering, native-memory config coexistence, OAuth/local fallback configuration, read retries, write deduplication, hook fail-open behavior, prompt/final-only turn and checkpoint capture, explicit exclusion of tool payloads, context budgets, local suppression, and MCP tool annotations.
+
+## Version 1.1 capture decision
+
+`PostToolUse` is not registered by the installer in 1.1. The runtime no longer defines or reads trace files, and health records no longer count tool calls. Normal Stop capture requires `last_assistant_message`; PreCompact and SessionEnd may preserve the cached user prompt when no final response is available. `SubagentStop` remains separate and stores only its stable final outcome plus non-payload agent identifiers.

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 mcp-server\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 mcp-server\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`;
 }
 
 function optionsFromArgs(args) {
@@ -66,6 +66,17 @@ async function main() {
     await require('../runtime/mcp-stdio.cjs').main();
     return;
   }
+  if (command === 'reflect') {
+    const { runReflect } = require('../runtime/reflect.cjs');
+    const result = await runReflect({
+      tier: args.tier,
+      batches: args.batches,
+      maxTokens: args.maxTokens,
+      dryRun: Boolean(args.dryRun),
+    });
+    process.exitCode = result.ok ? 0 : 1;
+    return;
+  }
   const options = optionsFromArgs(args);
   if (command === 'init') {
     const result = init(options);

package/lib/hooks.cjs

@@ -52,7 +52,6 @@ function managedGroups(runtimeDir, scope) {
   return {
     SessionStart: [{ matcher: 'startup|resume|clear|compact', hooks: [handler('session-start', 8, 'Recalling MemoryRouter context', 3500)] }],
     UserPromptSubmit: [{ hooks: [handler('inject', 8, 'Searching project memory', 3500)] }],
-    PostToolUse: [{ hooks: [handler('trace', 3)] }],
     Stop: [{ hooks: [handler('capture', 18, 'Saving durable project memory')] }],
     SubagentStop: [{ hooks: [handler('capture-subagent', 15, 'Saving durable subagent outcome')] }],
     PreCompact: [{ matcher: 'manual|auto', hooks: [handler('flush', 18, 'Saving memory before compaction')] }],

package/lib/installer.cjs

@@ -11,7 +11,7 @@ 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');
+const { installHooks, uninstallHooks, isOwnedHook, managedGroups, parseHooks } = require('./hooks.cjs');
 
 function resolveLayout(options = {}) {
   const env = options.env || process.env;
@@ -176,7 +176,8 @@ async function doctor(options = {}) {
   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.');
+  const expectedOwned = Object.values(managedGroups(layout.runtimeDir, layout.scope)).flat().flatMap(group => group.hooks || []).length;
+  addCheck(checks, 'hooks', owned.length === expectedOwned ? 'pass' : 'error', owned.length ? `${owned.length} of ${expectedOwned} 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);

package/package.json

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

package/runtime/api.cjs

@@ -47,10 +47,13 @@ async function request(method, endpoint, options = {}) {
 }
 
 function search(key, query, limit, options = {}) {
+  const body = { query, limit };
+  if (options.tiers !== undefined) body.tiers = options.tiers;
+  if (options.importance !== undefined) body.importance = options.importance;
   return request('POST', '/v1/memory/search', {
     ...options,
     key,
-    body: { query, limit },
+    body,
     headers: options.sessionId ? { 'X-Session-ID': options.sessionId } : {},
     retries: options.retries ?? 2,
   });
@@ -77,4 +80,84 @@ function clearVault(key, options = {}) {
   return request('DELETE', '/v1/memory', { ...options, key, retries: 0 });
 }
 
-module.exports = { sleep, request, search, ingest, stats, warmup, clearVault };
+// Reflection Hierarchy wrappers. Checkout and commit run with retries: 0 because
+// both create or consume leases; blind transport retries are handled by the
+// reflect loop, not this layer.
+function reflectCheckout(key, tier = 1, maxTokens, options = {}) {
+  const body = { tier };
+  // Default budget is 50000 tokens. No connector-side cap: the server's own
+  // checkout limits are the only bound.
+  body.max_tokens = maxTokens === undefined ? 50000 : maxTokens;
+  return request('POST', '/v1/memory/consolidate/checkout', {
+    ...options,
+    key,
+    body,
+    timeoutMs: options.timeoutMs || 20000,
+    retries: 0,
+  });
+}
+
+function reflectCommit(key, batchId, entries, options = {}) {
+  return request('POST', '/v1/memory/consolidate/commit', {
+    ...options,
+    key,
+    body: { batch_id: batchId, entries },
+    timeoutMs: options.timeoutMs || 30000,
+    retries: 0,
+  });
+}
+
+function inspect(key, memoryId, options = {}) {
+  return request('POST', '/v1/memory/inspect', {
+    ...options,
+    key,
+    body: { memory_id: memoryId },
+    timeoutMs: options.timeoutMs || 15000,
+    retries: options.retries ?? 1,
+  });
+}
+
+function deleteIds(key, ids, options = {}) {
+  return request('POST', '/v1/memory/delete-ids', {
+    ...options,
+    key,
+    body: { ids },
+    timeoutMs: options.timeoutMs || 20000,
+    retries: 0,
+  });
+}
+
+function dateSearch(key, params = {}, options = {}) {
+  return request('POST', '/v1/memory/date-search', {
+    ...options,
+    key,
+    body: params,
+    timeoutMs: options.timeoutMs || 15000,
+    retries: options.retries ?? 1,
+  });
+}
+
+// Sanctioned debt read: an empty-window date-search returns the reflection
+// debt block with zero results and bills zero retrieval tokens.
+function debtProbe(key, options = {}) {
+  return dateSearch(key, {
+    from: new Date(Date.now() - 1000).toISOString(),
+    max_tokens: 1000,
+  }, options);
+}
+
+module.exports = {
+  sleep,
+  request,
+  search,
+  ingest,
+  stats,
+  warmup,
+  clearVault,
+  reflectCheckout,
+  reflectCommit,
+  inspect,
+  deleteIds,
+  dateSearch,
+  debtProbe,
+};

package/runtime/config.cjs

@@ -74,10 +74,6 @@ function sessionStatePath(sessionId, env = process.env) {
   return path.join(stateDir(env), `${safeId(sessionId)}.json`);
 }
 
-function tracePath(sessionId, turnId, env = process.env) {
-  return path.join(stateDir(env), `${safeId(sessionId)}-${safeId(turnId)}.trace.jsonl`);
-}
-
 function loadSessionState(sessionId, env = process.env) {
   try {
     const value = JSON.parse(fs.readFileSync(sessionStatePath(sessionId, env), 'utf8'));
@@ -154,7 +150,6 @@ module.exports = {
   safeId,
   stateDir,
   sessionStatePath,
-  tracePath,
   loadSessionState,
   saveSessionState,
   pruneState,

package/runtime/constants.cjs

@@ -1,13 +1,11 @@
 'use strict';
 
-const INTEGRATION_VERSION = '1.0.0';
+const INTEGRATION_VERSION = '1.1.0';
 const RUNTIME_SCHEMA_VERSION = 1;
 const API_BASE = 'https://api.memoryrouter.ai';
 const MCP_ENDPOINT = 'https://mcp.memoryrouter.ai/mcp';
 const DEFAULT_CONTEXT_CHARS = 12000;
 const DEFAULT_SEARCH_RESULTS = 12;
-const MAX_TRACE_RECORD_CHARS = 8000;
-const MAX_TRACE_TOTAL_CHARS = 60000;
 const ENVELOPE_HEADER = '[MemoryRouter Codex Memory v1]';
 
 module.exports = {
@@ -17,7 +15,5 @@ module.exports = {
   MCP_ENDPOINT,
   DEFAULT_CONTEXT_CHARS,
   DEFAULT_SEARCH_RESULTS,
-  MAX_TRACE_RECORD_CHARS,
-  MAX_TRACE_TOTAL_CHARS,
   ENVELOPE_HEADER,
 };

package/runtime/hook.cjs

@@ -1,11 +1,9 @@
 #!/usr/bin/env node
 'use strict';
 
-const fs = require('fs');
-const { loadConfig, getApiKey, loadSessionState, saveSessionState, tracePath, pruneState, recordHealth } = require('./config.cjs');
+const { loadConfig, getApiKey, loadSessionState, saveSessionState, pruneState, recordHealth } = require('./config.cjs');
 const { resolveProject } = require('./project.cjs');
 const { searchScoped, storeScoped, memoryHandle } = require('./memory.cjs');
-const { MAX_TRACE_RECORD_CHARS, MAX_TRACE_TOTAL_CHARS } = require('./constants.cjs');
 
 function debug(...values) {
   if (process.env.MEMORYROUTER_DEBUG) console.error('[memoryrouter-codex]', ...values);
@@ -22,7 +20,7 @@ function readStdin(timeoutMs = 1500) {
   });
 }
 
-function truncate(value, limit = MAX_TRACE_RECORD_CHARS) {
+function truncate(value, limit = 8000) {
   let text;
   try { text = typeof value === 'string' ? value : JSON.stringify(value); } catch { text = String(value); }
   if (text.length <= limit) return text;
@@ -38,61 +36,41 @@ function emitContext(eventName, context) {
   return true;
 }
 
-function appendTrace(input, env = process.env) {
-  if (!input.session_id || !input.turn_id) return;
-  const record = {
-    at: new Date().toISOString(),
-    turn_id: input.turn_id,
-    tool_name: input.tool_name,
-    tool_use_id: input.tool_use_id,
-    input: truncate(input.tool_input),
-    response: truncate(input.tool_response),
-  };
-  const file = tracePath(input.session_id, input.turn_id, env);
-  fs.appendFileSync(file, `${JSON.stringify(record)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'a' });
-}
+const NUDGE_SUPPRESS_MS = 24 * 60 * 60 * 1000;
 
-function readTrace(sessionId, turnId, env = process.env) {
-  const file = tracePath(sessionId, turnId, env);
-  let text;
-  try { text = fs.readFileSync(file, 'utf8'); } catch { return []; }
-  const records = [];
-  let total = 0;
-  for (const line of text.split('\n')) {
-    if (!line.trim()) continue;
-    try {
-      const record = JSON.parse(line);
-      const size = JSON.stringify(record).length;
-      if (total + size > MAX_TRACE_TOTAL_CHARS) break;
-      records.push(record);
-      total += size;
-    } catch { /* tolerate partial concurrent append */ }
-  }
-  return records;
+function estimateDebtTokens(reflection) {
+  const raw = reflection?.unconsolidated?.raw?.est_tokens || 0;
+  const tier2 = reflection?.unconsolidated?.tier2?.est_tokens || 0;
+  return raw + tier2;
 }
 
-function removeTrace(sessionId, turnId, env = process.env) {
-  try { fs.unlinkSync(tracePath(sessionId, turnId, env)); } catch { /* absent */ }
+// Debt nudge rules (reflection-connectors-spec.md, section d):
+// only when a context is being emitted anyway, at most once per session state
+// per 24h window, and counted inside the existing context char cap so it can
+// never push memory content out.
+function maybeAppendNudge(context, reflection, sessionId, hookContext) {
+  if (!context || !reflection || !reflection.suggestion || !sessionId) return context;
+  const state = loadSessionState(sessionId, hookContext.env);
+  if (state.lastNudgeAt && Date.now() - Date.parse(state.lastNudgeAt) < NUDGE_SUPPRESS_MS) return context;
+  const tokens = estimateDebtTokens(reflection);
+  const nudge = `\n\n[MemoryRouter] Consolidation available: ${Math.round(tokens / 1000)}k unconsolidated tokens. Run: memoryrouter-codex reflect`;
+  const maxChars = Number(hookContext.config?.contextChars || 12000);
+  if (context.length + nudge.length > maxChars) return context;
+  state.lastNudgeAt = new Date().toISOString();
+  saveSessionState(sessionId, state, hookContext.env);
+  return context + nudge;
 }
 
-function turnContent(input, state, records, partial = false) {
+function turnContent(input, state) {
   const prompt = state.prompts?.[input.turn_id] || state.lastPrompt || '';
-  const parts = [
-    partial ? 'Codex work checkpoint before compaction/session end.' : 'Completed Codex turn.',
-    prompt ? `User request:\n${truncate(prompt, 40000)}` : null,
-  ];
-  if (records.length) {
-    parts.push(`Tool activity (${records.length} calls):`);
-    for (const record of records) {
-      parts.push([
-        `- ${record.tool_name || 'tool'} (${record.tool_use_id || 'unknown'})`,
-        `  input: ${record.input}`,
-        `  result: ${record.response}`,
-      ].join('\n'));
-    }
-  }
-  if (input.last_assistant_message) parts.push(`Final assistant response:\n${truncate(input.last_assistant_message, 60000)}`);
-  return parts.filter(Boolean).join('\n\n');
+  return [
+    prompt ? `User request:
+${truncate(prompt, 40000)}` : null,
+    input.last_assistant_message
+      ? `Final assistant response:
+${truncate(input.last_assistant_message, 60000)}`
+      : null,
+  ].filter(Boolean).join('\n\n');
 }
 
 async function handleInject(input, context) {
@@ -115,7 +93,7 @@ async function handleInject(input, context) {
     memories: result.memories?.length || 0,
     status: result.status,
   }, context.env);
-  emitContext('UserPromptSubmit', result.context);
+  emitContext('UserPromptSubmit', maybeAppendNudge(result.context, result.reflection, input.session_id, context));
 }
 
 async function handleSessionStart(input, context) {
@@ -130,7 +108,7 @@ async function handleSessionStart(input, context) {
     project: context.project.handle,
     memories: result.memories?.length || 0,
   }, context.env);
-  emitContext('SessionStart', result.context);
+  emitContext('SessionStart', maybeAppendNudge(result.context, result.reflection, input.session_id, context));
 }
 
 async function captureTurn(input, context, partial = false) {
@@ -142,9 +120,10 @@ async function captureTurn(input, context, partial = false) {
   if (!partial && state.capturedTurns?.[turnId]) {
     return { ok: true, skipped: 'deduplicated', handle: state.capturedTurns[turnId] };
   }
-  const records = readTrace(sessionId, turnId, context.env);
-  if (!input.last_assistant_message && records.length === 0) return { ok: true, skipped: 'empty' };
-  const content = turnContent({ ...input, turn_id: turnId }, state, records, partial);
+  const prompt = state.prompts?.[turnId] || state.lastPrompt || '';
+  if (!partial && !input.last_assistant_message) return { ok: true, skipped: 'empty' };
+  if (partial && !prompt && !input.last_assistant_message) return { ok: true, skipped: 'empty' };
+  const content = turnContent({ ...input, turn_id: turnId }, state);
   const kind = partial ? 'checkpoint' : 'turn';
   const handle = memoryHandle(context.project.handle, kind, content);
   if ((state.capturedHandles || []).includes(handle)) return { ok: true, skipped: 'deduplicated', handle };
@@ -166,14 +145,14 @@ async function captureTurn(input, context, partial = false) {
     if (!partial && state.prompts) delete state.prompts[turnId];
     state.lastCaptureAt = new Date().toISOString();
     saveSessionState(sessionId, state, context.env);
-    if (!partial) removeTrace(sessionId, turnId, context.env);
   }
   recordHealth(partial ? 'flush' : 'capture', {
     ok: result.ok,
     status: result.status,
     project: context.project.handle,
     handle,
-    toolCalls: records.length,
+    hasPrompt: Boolean(prompt),
+    hasFinalResponse: Boolean(input.last_assistant_message),
   }, context.env);
   return result;
 }
@@ -222,7 +201,6 @@ async function run(kind, input, options = {}) {
   switch (kind) {
     case 'inject': return handleInject(input, context);
     case 'session-start': return handleSessionStart(input, context);
-    case 'trace': appendTrace(input, env); return;
     case 'capture': return captureTurn(input, context, false);
     case 'capture-subagent': return captureSubagent(input, context);
     case 'flush': return captureTurn(input, context, true);
@@ -232,7 +210,7 @@ async function run(kind, input, options = {}) {
 
 async function main() {
   const kind = process.argv[2];
-  const wallClock = setTimeout(() => process.exit(0), kind === 'trace' ? 2500 : kind === 'inject' ? 7500 : 18000);
+  const wallClock = setTimeout(() => process.exit(0), kind === 'inject' ? 7500 : 18000);
   wallClock.unref();
   let input = {};
   try { input = JSON.parse((await readStdin()) || '{}'); } catch { debug('invalid hook JSON'); }
@@ -247,9 +225,8 @@ module.exports = {
   readStdin,
   truncate,
   emitContext,
-  appendTrace,
-  readTrace,
-  removeTrace,
+  maybeAppendNudge,
+  estimateDebtTokens,
   turnContent,
   handleInject,
   handleSessionStart,

package/runtime/mcp-stdio.cjs

@@ -7,6 +7,7 @@ const { loadConfig, getApiKey, configPath, auditPath, recordAudit, healthPath }
 const { resolveProject } = require('./project.cjs');
 const { searchScoped, storeScoped, forgetLocally } = require('./memory.cjs');
 const api = require('./api.cjs');
+const { contractFrom, validateEntries } = require('./reflect.cjs');
 const { INTEGRATION_VERSION } = require('./constants.cjs');
 
 const SERVER_INSTRUCTIONS = 'MemoryRouter provides durable cross-machine, cross-tool, team-shareable memory. Search project memory before answering questions about prior decisions, preferences, incidents, or unfinished work. Store concise durable decisions and preferences after they are established. Automatic Codex hooks may already capture completed turns, so do not duplicate them. Use returned memory handles when referring to a record. Codex native Memories remain the local personal recall layer; MemoryRouter is the shared and auditable layer.';
@@ -20,6 +21,8 @@ const TOOLS = [
       properties: {
         query: { type: 'string', description: 'Semantic search query.' },
         limit: { type: 'integer', minimum: 1, maximum: 50, description: 'Candidate results before project filtering.' },
+        tiers: { type: 'array', items: { type: 'integer', enum: [1, 2, 3] }, minItems: 1, uniqueItems: true, description: 'Restrict results to these memory tiers. 1 raw memories, 2 reflections, 3 high-level reflections. Omit to search all tiers blended.' },
+        importance: { type: 'integer', minimum: 1, maximum: 10, description: 'Only return memories rated at least this important (1 to 10). Only reflections carry ratings, so this filters to tier 2 and 3 content.' },
       },
       required: ['query'],
     },
@@ -57,6 +60,46 @@ const TOOLS = [
     },
     annotations: { title: 'Forget MemoryRouter memory', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
   },
+  {
+    name: 'memory_consolidate',
+    description: 'Use this when the user asks to consolidate, reflect on, or organize their memories, or when memory_status or a search result reports that consolidation is available. Checks out a batch of unconsolidated memories from the connected vault under a 15 minute lease and returns their texts plus server instructions for writing reflection entries. Follow the returned instructions to write the entries, then call memory_commit_reflections with the batch_id. Nothing is modified until commit.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tier: { type: 'integer', enum: [1, 2], default: 1, description: '1 consolidates raw memories into reflections; 2 consolidates reflections into high-level reflections.' },
+        max_tokens: { type: 'integer', minimum: 1000, default: 50000, description: 'Token budget for the checked-out batch. Defaults to 50000. No connector-side cap.' },
+      },
+      additionalProperties: false,
+    },
+    annotations: { title: 'Consolidate memories (checkout)', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+  },
+  {
+    name: 'memory_commit_reflections',
+    description: 'Use this to complete a consolidation started with memory_consolidate. Submits the reflection entries you wrote for the checked-out batch. Each entry is standalone prose with an importance rating from 1 to 10. The server stores the reflections, links them to their source memories, and marks the sources consolidated. Safe to retry: committing the same batch twice returns the original result.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        batch_id: { type: 'string', minLength: 1 },
+        entries: {
+          type: 'array',
+          minItems: 1,
+          maxItems: 100,
+          items: {
+            type: 'object',
+            properties: {
+              text: { type: 'string', minLength: 1, maxLength: 8000 },
+              importance: { type: 'integer', minimum: 1, maximum: 10 },
+            },
+            required: ['text', 'importance'],
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ['batch_id', 'entries'],
+      additionalProperties: false,
+    },
+    annotations: { title: 'Commit reflections', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+  },
 ];
 
 function textResult(text, isError = false) {
@@ -73,10 +116,28 @@ async function callTool(name, args = {}, options = {}) {
 
   if (name === 'memory_search') {
     if (!args.query) return textResult('query is required', true);
-    const result = await searchScoped(args.query, { env, config, key, cwd, project, limit: args.limit });
+    if (args.tiers !== undefined) {
+      if (!Array.isArray(args.tiers) || args.tiers.length < 1 || args.tiers.some(tier => ![1, 2, 3].includes(tier))) {
+        return textResult('tiers must be a non-empty array drawn from [1, 2, 3]', true);
+      }
+    }
+    if (args.importance !== undefined && (!Number.isInteger(args.importance) || args.importance < 1 || args.importance > 10)) {
+      return textResult('importance must be an integer 1 to 10', true);
+    }
+    const result = await searchScoped(args.query, {
+      env, config, key, cwd, project, limit: args.limit,
+      ...(args.tiers !== undefined ? { tiers: args.tiers } : {}),
+      ...(args.importance !== undefined ? { importance: args.importance } : {}),
+    });
     if (!result.ok) return textResult(`Memory search failed${result.status ? ` (HTTP ${result.status})` : ''}.`, true);
     if (!result.context) return textResult(`No memories matched current project ${project.handle}.`);
-    return textResult(result.context);
+    let text = result.context;
+    const debt = result.reflection;
+    if (debt && debt.suggestion) {
+      const tokens = (debt.unconsolidated?.raw?.est_tokens || 0) + (debt.unconsolidated?.tier2?.est_tokens || 0);
+      text += `\n\nNote: ${Math.round(tokens / 1000)}k unconsolidated memory tokens are ready for consolidation. Suggest consolidating when convenient.`;
+    }
+    return textResult(text);
   }
   if (name === 'memory_store') {
     if (!args.content) return textResult('content is required', true);
@@ -89,10 +150,14 @@ async function callTool(name, args = {}, options = {}) {
       : `Stored for project ${project.handle}. Memory handle: ${result.handle}`);
   }
   if (name === 'memory_status') {
-    const response = await api.stats(key, { apiBase: config.apiBase, timeoutMs: 8000, retries: 1 });
+    const [response, probe] = await Promise.all([
+      api.stats(key, { apiBase: config.apiBase, timeoutMs: 8000, retries: 1 }),
+      api.debtProbe(key, { apiBase: config.apiBase, timeoutMs: 8000 }).catch(() => null),
+    ]);
     let health = null;
     try { health = JSON.parse(fs.readFileSync(healthPath(env), 'utf8')); } catch { /* optional */ }
-    return textResult(JSON.stringify({
+    const debt = probe && probe.ok ? probe.data?.reflection || null : null;
+    const status = {
       connected: response.ok,
       status: response.status,
       project: { handle: project.handle, identitySource: project.source, crossMachineStable: project.portable },
@@ -101,8 +166,65 @@ async function callTool(name, args = {}, options = {}) {
       localAuditFile: auditPath(env),
       retrievalScope: config.retrievalScope,
       vault: response.ok ? response.data : null,
+      reflection: debt,
       recentHooks: health,
-    }, null, 2));
+    };
+    let text = JSON.stringify(status, null, 2);
+    if (debt && debt.suggestion) {
+      const tokens = (debt.unconsolidated?.raw?.est_tokens || 0) + (debt.unconsolidated?.tier2?.est_tokens || 0);
+      text += `\n\nConsolidation is available: ${Math.round(tokens / 1000)}k unconsolidated memory tokens. The user can ask to consolidate memories.`;
+    }
+    return textResult(text);
+  }
+  if (name === 'memory_consolidate') {
+    const tier = args.tier === undefined ? 1 : args.tier;
+    if (tier !== 1 && tier !== 2) return textResult('tier must be 1 or 2', true);
+    if (args.max_tokens !== undefined && (!Number.isInteger(args.max_tokens) || args.max_tokens < 1000)) {
+      return textResult('max_tokens must be an integer of at least 1000', true);
+    }
+    const response = await api.reflectCheckout(key, tier, args.max_tokens, { apiBase: config.apiBase });
+    if (response.status === 403) return textResult('This memory key is read-only; consolidation requires a writable key.', true);
+    if (!response.ok) return textResult(`Consolidation checkout failed (HTTP ${response.status}).`, true);
+    const data = response.data || {};
+    if (!data.batch_id || !data.count) return textResult('Nothing to consolidate. The unconsolidated pool is empty.');
+    const contract = contractFrom(data);
+    if (!contract) return textResult('Checkout response carried no reflection contract. Refusing to consolidate: this connector never authors reflection prompts.', true);
+    // Invariant: the model never sees memory row IDs. source_ids is dropped
+    // here and never rendered; commit needs only the opaque batch_id.
+    const dated = (Array.isArray(data.memories) ? data.memories : [])
+      .map(memory => `[${memory.date || 'unknown date'}]\n${memory.text}`)
+      .join('\n\n');
+    recordAudit('consolidate-checkout', { ok: true, tier, count: data.count, project: project.handle }, env);
+    return textResult([
+      contract.instructions,
+      '',
+      `Batch of ${data.count} memories (${data.est_tokens} estimated tokens), covering ${data.covers?.from || 'unknown'} to ${data.covers?.to || 'unknown'}.`,
+      '',
+      dated,
+      '',
+      `When your entries are ready, call memory_commit_reflections with batch_id ${data.batch_id} before ${data.lease_expires_at}.`,
+    ].join('\n'));
+  }
+  if (name === 'memory_commit_reflections') {
+    if (!args.batch_id || typeof args.batch_id !== 'string') return textResult('batch_id is required', true);
+    const validated = validateEntries({ entries: args.entries });
+    if (!validated.ok) return textResult(`Invalid entries: ${validated.reason}`, true);
+    const response = await api.reflectCommit(key, args.batch_id, validated.entries, { apiBase: config.apiBase });
+    if (response.status === 409) {
+      return textResult('The consolidation lease expired before commit. Ask the user whether to start over with memory_consolidate; the memories were returned to the pool and nothing was lost.', true);
+    }
+    if (response.status === 403) return textResult('This memory key is read-only; commit requires a writable key.', true);
+    if (!response.ok) return textResult(`Commit failed (HTTP ${response.status}).`, true);
+    const data = response.data || {};
+    // Invariant: created reflection UUIDs are dropped; the model never sees row IDs.
+    const created = Array.isArray(data.created) ? data.created.length : 0;
+    recordAudit('consolidate-commit', { ok: true, alreadyCommitted: Boolean(data.already_committed), created, sourcesConsolidated: data.sources_consolidated || 0, project: project.handle }, env);
+    const summary = data.already_committed
+      ? 'This batch was already committed; the original result stands.'
+      : `${created} reflections written; ${data.sources_consolidated || 0} memories consolidated.`;
+    const debt = data.reflection;
+    const remaining = debt && debt.suggestion ? ` Remaining: ${debt.suggestion}.` : '';
+    return textResult(`${summary}${remaining}`);
   }
   if (name === 'memory_forget') {
     if (args.clear_vault_confirmation === 'CLEAR MY ENTIRE MEMORYROUTER VAULT') {

package/runtime/memory.cjs

@@ -62,13 +62,18 @@ function parseEnvelope(content) {
   return { project, handle, kind, body };
 }
 
-function filterMemories(memories, projectHandle, config) {
+function filterMemories(memories, projectHandle, config, options = {}) {
   const scope = config.retrievalScope || 'project';
   const forgotten = new Set(config.forgottenHandles || []);
+  // Reflections (tier 2 and 3) are vault-level distilled prose without project
+  // envelopes. When the caller explicitly asked for reflection tiers, let those
+  // rows through the project filter instead of silently dropping every result.
+  const requestedReflectionTiers = Array.isArray(options.tiers) && options.tiers.some(tier => tier >= 2);
   return (Array.isArray(memories) ? memories : []).filter(memory => {
     const parsed = parseEnvelope(memory.content);
     if (parsed && forgotten.has(parsed.handle)) return false;
     if (scope === 'vault') return true;
+    if (requestedReflectionTiers && memory.tier != null && memory.tier >= 2) return true;
     return parsed?.project === projectHandle;
   });
 }
@@ -85,7 +90,9 @@ function formatContext(memories, projectHandle, maxChars) {
     const body = parsed ? parsed.body : String(memory.content || '');
     const handle = parsed?.handle || memory.id || 'unhandled';
     const timestamp = memory.timestampHuman || (memory.timestamp ? new Date(memory.timestamp).toISOString() : 'unknown time');
-    const chunk = `\n\n[${handle} | ${timestamp}]\n${body.slice(0, 5000)}`;
+    const tierTag = memory.tier != null && memory.tier !== 1 ? ` | tier ${memory.tier}` : '';
+    const importanceTag = memory.importance != null ? ` | importance ${memory.importance}` : '';
+    const chunk = `\n\n[${handle} | ${timestamp}${tierTag}${importanceTag}]\n${body.slice(0, 5000)}`;
     if (output.length + chunk.length > maxChars) break;
     output += chunk;
   }
@@ -110,18 +117,21 @@ async function searchScoped(query, options = {}) {
       sessionId: options.sessionId,
       timeoutMs: options.timeoutMs || 5500,
       retries: options.retries,
+      ...(options.tiers !== undefined ? { tiers: options.tiers } : {}),
+      ...(options.importance !== undefined ? { importance: options.importance } : {}),
     },
   );
   if (!response.ok) {
     recordAudit('search', { ok: false, status: response.status, project: project.handle }, options.env);
     return { ok: false, status: response.status, memories: [], context: '' };
   }
-  const memories = filterMemories(response.data?.memories, project.handle, config);
+  const memories = filterMemories(response.data?.memories, project.handle, config, { tiers: options.tiers });
   recordAudit('search', { ok: true, project: project.handle, candidates: response.data?.memories?.length || 0, returned: memories.length }, options.env);
   return {
     ok: true,
     project,
     memories,
+    reflection: response.data?.reflection || null,
     context: formatContext(memories, project.handle, Number(config.contextChars || 12000)),
   };
 }
@@ -188,7 +198,7 @@ function forgetLocally(handle, options = {}) {
     ok: true,
     handle,
     deleted: false,
-    message: 'Suppressed from MemoryRouter Codex retrieval on this machine. The server record was not deleted because the current MemoryRouter API has no per-memory delete endpoint.',
+    message: 'Suppressed from MemoryRouter Codex retrieval on this machine. The server record was not deleted; this Codex surface performs local suppression only. Per-memory server deletion is available from other MemoryRouter surfaces.',
   };
 }
 

package/runtime/reflect.cjs

@@ -0,0 +1,250 @@
+'use strict';
+
+// Reflection Hierarchy consolidation loop for the codex CLI lane.
+//
+// Locked invariants (reflection-connectors-spec.md, section d):
+// 1. The server is the single source of reflection prompts. This module never
+//    authors reflection guidance; the model prompt is built exclusively from
+//    reflection_contract.instructions plus the dated memory texts. The strict
+//    JSON envelope instruction is connector mechanics, which is permitted.
+// 2. No memory IDs ever reach the model. source_ids from checkout are never
+//    included in the prompt; batch_id stays with the connector.
+// 3. No local state. Lease expiry on the server is the recovery mechanism;
+//    re-running continues from the oldest unconsolidated memory.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+const api = require('./api.cjs');
+const { loadConfig, getApiKey, recordAudit } = require('./config.cjs');
+
+const MAX_ENTRY_CHARS = 8000;
+const MAX_ENTRIES = 100;
+const JSON_ENVELOPE_INSTRUCTION = [
+  'Output STRICT JSON only, no prose before or after, exactly this shape:',
+  '{"entries": [{"text": "...", "importance": N}]}',
+  'Each entry object has exactly two fields: text (string) and importance (integer 1 to 10).',
+].join('\n');
+const RETRY_SUFFIX = '\n\nYour previous output was not valid JSON in the required shape. Respond again with ONLY the JSON object, nothing else.';
+
+function contractFrom(data) {
+  if (data && data.reflection_contract && typeof data.reflection_contract.instructions === 'string') {
+    return { instructions: data.reflection_contract.instructions, version: data.reflection_contract.version ?? null };
+  }
+  if (data && data.tier_definitions && typeof data.tier_definitions.instruction === 'string') {
+    return { instructions: data.tier_definitions.instruction, version: null };
+  }
+  return null;
+}
+
+function buildPrompt(instructions, memories) {
+  const texts = (Array.isArray(memories) ? memories : [])
+    .map(memory => `[${memory.date || 'unknown date'}]\n${memory.text}`)
+    .join('\n\n');
+  return `${instructions}\n\nMemories:\n\n${texts}\n\n${JSON_ENVELOPE_INSTRUCTION}`;
+}
+
+function extractJson(text) {
+  const raw = String(text || '');
+  try { return JSON.parse(raw); } catch { /* try fenced or embedded */ }
+  const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
+  if (fenced) {
+    try { return JSON.parse(fenced[1]); } catch { /* fall through */ }
+  }
+  const start = raw.indexOf('{');
+  const end = raw.lastIndexOf('}');
+  if (start >= 0 && end > start) {
+    try { return JSON.parse(raw.slice(start, end + 1)); } catch { /* invalid */ }
+  }
+  return null;
+}
+
+function validateEntries(parsed) {
+  if (!parsed || !Array.isArray(parsed.entries)) return { ok: false, reason: 'entries array missing' };
+  if (parsed.entries.length < 1) return { ok: false, reason: 'entries array is empty' };
+  if (parsed.entries.length > MAX_ENTRIES) return { ok: false, reason: `more than ${MAX_ENTRIES} entries` };
+  const entries = [];
+  for (const entry of parsed.entries) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return { ok: false, reason: 'entry is not an object' };
+    const keys = Object.keys(entry);
+    const extras = keys.filter(k => k !== 'text' && k !== 'importance');
+    if (extras.length) return { ok: false, reason: `entry has forbidden fields: ${extras.join(', ')}` };
+    if (typeof entry.text !== 'string' || entry.text.length < 1 || entry.text.length > MAX_ENTRY_CHARS) {
+      return { ok: false, reason: `entry text must be a string of 1 to ${MAX_ENTRY_CHARS} chars` };
+    }
+    if (!Number.isInteger(entry.importance) || entry.importance < 1 || entry.importance > 10) {
+      return { ok: false, reason: 'entry importance must be an integer 1 to 10' };
+    }
+    entries.push({ text: entry.text, importance: entry.importance });
+  }
+  return { ok: true, entries };
+}
+
+function invokeCodex(prompt, options = {}) {
+  const outFile = path.join(os.tmpdir(), `mrcodex-reflect-${process.pid}-${crypto.randomBytes(4).toString('hex')}.txt`);
+  try {
+    const result = spawnSync('codex', ['exec', '--skip-git-repo-check', '--output-last-message', outFile, prompt], {
+      encoding: 'utf8',
+      timeout: options.timeoutMs || 10 * 60 * 1000,
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    if (result.error) return { ok: false, reason: result.error.message };
+    let output = '';
+    try { output = fs.readFileSync(outFile, 'utf8'); } catch { output = String(result.stdout || ''); }
+    if (!output.trim()) return { ok: false, reason: `codex exec produced no output (exit ${result.status})` };
+    return { ok: true, output };
+  } finally {
+    try { fs.rmSync(outFile, { force: true }); } catch { /* best effort */ }
+  }
+}
+
+async function runReflect(options = {}) {
+  const env = options.env || process.env;
+  const config = options.config || loadConfig(env);
+  const key = options.key || getApiKey(env, config);
+  const log = options.log || (line => process.stdout.write(`${line}\n`));
+  const invokeModel = options.invokeModel || invokeCodex;
+  if (!key) {
+    log('MemoryRouter API key is not configured. Run `memoryrouter-codex init` or set MEMORYROUTER_API_KEY.');
+    return { ok: false, reason: 'no-api-key' };
+  }
+  const tier = Number(options.tier || 1);
+  if (tier !== 1 && tier !== 2) {
+    log('tier must be 1 or 2');
+    return { ok: false, reason: 'bad-tier' };
+  }
+  const batchesAll = options.batches === 'all';
+  const maxBatches = batchesAll ? Infinity : Math.max(1, Number(options.batches || 1));
+  const maxTokens = options.maxTokens === undefined ? undefined : Number(options.maxTokens);
+  const apiOptions = { apiBase: config.apiBase };
+
+  let completed = 0;
+  let totalCreated = 0;
+  let totalConsolidated = 0;
+  let leaseWarned = false;
+  let leaseRetries = 0;
+  const maxLeaseRetries = 3;
+
+  while (completed < maxBatches) {
+    const checkout = await api.reflectCheckout(key, tier, maxTokens, apiOptions);
+    if (!checkout.ok) {
+      log(`Checkout failed (HTTP ${checkout.status}).`);
+      recordAudit('reflect-checkout', { ok: false, status: checkout.status, tier }, env);
+      return { ok: false, reason: 'checkout-failed', status: checkout.status, completed };
+    }
+    const data = checkout.data || {};
+    if (!data.batch_id || !data.count) {
+      log(completed ? 'Pool is empty. Nothing more to consolidate.' : 'Nothing to consolidate.');
+      return { ok: true, completed, created: totalCreated, consolidated: totalConsolidated, empty: true };
+    }
+    recordAudit('reflect-checkout', { ok: true, tier, count: data.count, estTokens: data.est_tokens }, env);
+
+    const contract = contractFrom(data);
+    if (!contract) {
+      log('Checkout response carried no reflection contract. Refusing to reflect: this connector never authors its own reflection prompt. Update memoryrouter-codex or contact support.');
+      return { ok: false, reason: 'no-contract', completed };
+    }
+
+    const prompt = buildPrompt(contract.instructions, data.memories);
+
+    if (options.dryRun) {
+      log(`Dry run. Batch of ${data.count} memories (${data.est_tokens} est tokens), lease expires ${data.lease_expires_at}.`);
+      log('The lease will be allowed to expire; nothing will be committed.');
+      log('\n----- reflection contract instructions -----\n');
+      log(contract.instructions);
+      log('\n----- full model prompt -----\n');
+      log(prompt);
+      return { ok: true, dryRun: true, completed };
+    }
+
+    log(`Batch ${completed + 1}: ${data.count} memories, ${data.est_tokens} est tokens, lease expires ${data.lease_expires_at}.`);
+
+    let entries = null;
+    let attemptPrompt = prompt;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      const invocation = invokeModel(attemptPrompt, options);
+      if (!invocation.ok) {
+        log(`Model invocation failed: ${invocation.reason}`);
+        break;
+      }
+      const validated = validateEntries(extractJson(invocation.output));
+      if (validated.ok) { entries = validated.entries; break; }
+      log(`Model output invalid (${validated.reason}).${attempt === 0 ? ' Retrying once.' : ''}`);
+      attemptPrompt = prompt + RETRY_SUFFIX;
+    }
+    if (!entries) {
+      log('Giving up on this batch. The lease will expire on its own and the memories return to the pool. No entries were invented.');
+      recordAudit('reflect-abandon', { tier, batchAbandoned: true }, env);
+      return { ok: false, reason: 'model-output-invalid', completed };
+    }
+
+    if (data.lease_expires_at && Date.now() >= Date.parse(data.lease_expires_at)) {
+      log('The model step outlasted the lease; skipping commit and re-checking out a fresh batch.');
+      if (!leaseWarned) {
+        log('Hint: pass a smaller --max-tokens so each batch fits inside the 15 minute lease.');
+        leaseWarned = true;
+      }
+      leaseRetries += 1;
+      if (leaseRetries >= maxLeaseRetries) {
+        log('Repeated lease expiries; stopping. Re-run with a smaller --max-tokens.');
+        return { ok: false, reason: 'lease-expired-repeatedly', completed };
+      }
+      continue;
+    }
+
+    const commit = await api.reflectCommit(key, data.batch_id, entries, apiOptions);
+    if (commit.status === 409) {
+      log('Lease expired before commit. The memories returned to the pool; re-checking out.');
+      if (!leaseWarned) {
+        log('Hint: pass a smaller --max-tokens so each batch fits inside the 15 minute lease.');
+        leaseWarned = true;
+      }
+      leaseRetries += 1;
+      if (leaseRetries >= maxLeaseRetries) {
+        log('Repeated lease expiries; stopping. Re-run with a smaller --max-tokens.');
+        return { ok: false, reason: 'lease-expired-repeatedly', completed };
+      }
+      continue;
+    }
+    leaseRetries = 0;
+    if (!commit.ok) {
+      log(`Commit failed (HTTP ${commit.status}).`);
+      recordAudit('reflect-commit', { ok: false, status: commit.status, tier }, env);
+      return { ok: false, reason: 'commit-failed', status: commit.status, completed };
+    }
+    const committed = commit.data || {};
+    const createdCount = Array.isArray(committed.created) ? committed.created.length : 0;
+    totalCreated += createdCount;
+    totalConsolidated += committed.sources_consolidated || 0;
+    completed += 1;
+    recordAudit('reflect-commit', {
+      ok: true, tier, alreadyCommitted: Boolean(committed.already_committed), created: createdCount, sourcesConsolidated: committed.sources_consolidated || 0,
+    }, env);
+    if (committed.already_committed) {
+      log('Batch was already committed; treated as success.');
+    } else {
+      log(`Committed ${createdCount} reflections covering ${committed.sources_consolidated || 0} memories.`);
+    }
+    const debt = committed.reflection;
+    if (debt && debt.suggestion) log(`Remaining: ${debt.suggestion}.`);
+    else if (debt && !debt.suggestion && batchesAll) {
+      log('Debt is below threshold; stopping.');
+      break;
+    }
+  }
+
+  log(`Done. ${completed} batch${completed === 1 ? '' : 'es'} committed, ${totalCreated} reflections created, ${totalConsolidated} memories consolidated.`);
+  return { ok: true, completed, created: totalCreated, consolidated: totalConsolidated };
+}
+
+module.exports = {
+  JSON_ENVELOPE_INSTRUCTION,
+  contractFrom,
+  buildPrompt,
+  extractJson,
+  validateEntries,
+  invokeCodex,
+  runReflect,
+};