memoryrouter-codex 1.1.0 → 1.2.1

package/README.md

@@ -142,6 +142,17 @@ The Codex package captures future work after installation. It does not ship a de
 - 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 suggested, hook-injected context appends a one-line suggestion on every injection until the debt is consolidated.
+
+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.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memoryrouter-codex",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "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/hook.cjs

@@ -36,6 +36,25 @@ function emitContext(eventName, context) {
   return true;
 }
 
+function estimateDebtTokens(reflection) {
+  const raw = reflection?.unconsolidated?.raw?.est_tokens || 0;
+  const tier2 = reflection?.unconsolidated?.tier2?.est_tokens || 0;
+  return raw + tier2;
+}
+
+// Debt nudge rules (reflection-connectors-spec.md, section d):
+// only when a context is being emitted anyway, and counted inside the
+// existing context char cap so it can never push memory content out.
+// Fires on every run with a non-null suggestion.
+function maybeAppendNudge(context, reflection, sessionId, hookContext) {
+  if (!context || !reflection || !reflection.suggestion || !sessionId) return context;
+  const tokens = estimateDebtTokens(reflection);
+  const nudge = `\n\n[MemoryRouter] Consolidation suggested: ${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;
+  return context + nudge;
+}
+
 function turnContent(input, state) {
   const prompt = state.prompts?.[input.turn_id] || state.lastPrompt || '';
   return [
@@ -68,7 +87,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) {
@@ -83,7 +102,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) {
@@ -200,6 +219,8 @@ module.exports = {
   readStdin,
   truncate,
   emitContext,
+  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,
+};