memoryrouter-codex 1.3.0 → 1.5.0

package/README.md

@@ -77,6 +77,7 @@ printf '%s' "$MEMORYROUTER_API_KEY" | \
 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:
 
 - `memory_search`
+- `memory_date_search`
 - `memory_store`
 - `memory_status`
 - `memory_forget`
@@ -161,10 +162,12 @@ MemoryRouter's Reflection Hierarchy consolidates raw memories into higher-tier r
 - **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.
+`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_date_search` retrieves memories from a specific time window (`from` required ISO 8601, optional `to`, `query`, `tiers`, `importance`, `max_tokens`): use it for questions like 'what happened last week' or 'most important things this month or lately', setting importance to 7 or higher with tiers `[2, 3]` for importance questions, omitting `query` for a chronological review. `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.
 
+**Automatic consolidation (default on):** when a hook's retrieval response reports debt above the server's threshold, the hooks spawn the same reflect loop as a detached background process (`codex exec` headless, your own inference). Rails: max 3 batches per trigger with a debt re-check between batches, a machine-wide lockfile at `~/.memoryrouter/consolidate.lock` (stale after 20 minutes), a 30 minute cooldown after each completed run, and silent failure with logs at `~/.memoryrouter/consolidate.log`. The threshold always comes from the server response. Opt out with `"autoConsolidate": false` in `~/.memoryrouter/codex/config.json`; the suggestion line, stdio tools, and manual `reflect` keep working.
+
 ## Context budget and failure behavior
 
 - Default injected context cap: 12,000 characters, assembled at memory boundaries.

package/bin/cli.cjs

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

package/package.json

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

package/runtime/api.cjs

@@ -129,10 +129,17 @@ function deleteIds(key, ids, options = {}) {
 }
 
 function dateSearch(key, params = {}, options = {}) {
+  const body = {};
+  if (params.from !== undefined) body.from = params.from;
+  if (params.to !== undefined) body.to = params.to;
+  if (params.query !== undefined) body.query = params.query;
+  if (params.max_tokens !== undefined) body.max_tokens = params.max_tokens;
+  if (Array.isArray(params.tiers) && params.tiers.length) body.tiers = params.tiers;
+  if (params.importance !== undefined) body.importance = params.importance;
   return request('POST', '/v1/memory/date-search', {
     ...options,
     key,
-    body: params,
+    body,
     timeoutMs: options.timeoutMs || 15000,
     retries: options.retries ?? 1,
   });

package/runtime/auto.cjs

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

package/runtime/constants.cjs

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

package/runtime/hook.cjs

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

package/runtime/mcp-stdio.cjs

@@ -5,7 +5,7 @@ const readline = require('readline');
 const fs = require('fs');
 const { loadConfig, getApiKey, configPath, auditPath, recordAudit, healthPath } = require('./config.cjs');
 const { resolveProject } = require('./project.cjs');
-const { searchScoped, storeScoped, forgetLocally } = require('./memory.cjs');
+const { searchScoped, storeScoped, forgetLocally, parseEnvelope } = require('./memory.cjs');
 const api = require('./api.cjs');
 const { contractFrom, validateEntries } = require('./reflect.cjs');
 const { INTEGRATION_VERSION } = require('./constants.cjs');
@@ -15,19 +15,36 @@ const SERVER_INSTRUCTIONS = 'MemoryRouter provides durable cross-machine, cross-
 const TOOLS = [
   {
     name: 'memory_search',
-    description: 'Search durable MemoryRouter memories. Defaults to the current git project and filters other projects out.',
+    description: "Search durable MemoryRouter memories. Defaults to the current git project and filters other projects out. For questions like 'what are the most important things' set importance to 7 or higher with tiers [2, 3], since only reflections carry importance ratings. For time-window questions like 'what happened last week' or 'lately' use memory_date_search instead.",
     inputSchema: {
       type: 'object',
       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.' },
+        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. Only tiers 2 and 3 carry importance ratings. Omit to search all tiers blended.' },
+        importance: { type: 'integer', minimum: 1, maximum: 10, description: "Minimum importance threshold, 1 to 10. Only reflections (tiers 2 and 3) carry ratings, so raw memories are excluded whenever this is set. For 'most important' questions use 7 or higher with tiers [2, 3]." },
       },
       required: ['query'],
     },
     annotations: { title: 'Search MemoryRouter', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
   },
+  {
+    name: 'memory_date_search',
+    description: "Retrieve memories from a specific time window. Use for questions like 'what happened last week' or 'most important things this month or lately'. For importance questions set importance to 7 or higher with tiers [2, 3], since only reflections carry importance ratings. Omit query for a chronological review; include query to rank by relevance within the window. Resolve relative phrases like 'lately' to concrete ISO dates before calling.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        from: { type: 'string', description: 'Window start, ISO 8601 date or datetime (e.g. 2026-08-10 or 2026-08-10T00:00:00Z). Required. Must be a concrete date, not a relative phrase.' },
+        to: { type: 'string', description: 'Window end, ISO 8601 date or datetime. Optional, defaults to now.' },
+        query: { type: 'string', description: 'Optional relevance query. Omit for a pure chronological browse; include to rank results within the window.' },
+        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. Only tiers 2 and 3 carry importance ratings. Omit to include all tiers.' },
+        importance: { type: 'integer', minimum: 1, maximum: 10, description: "Minimum importance threshold, 1 to 10. Only reflections (tiers 2 and 3) carry ratings, so raw memories are excluded whenever this is set. For 'most important' questions use 7 or higher with tiers [2, 3]." },
+        max_tokens: { type: 'integer', minimum: 1000, maximum: 200000, description: 'Token budget for returned results. Server default 50000; use a smaller value like 5000 for a quick look.' },
+      },
+      required: ['from'],
+    },
+    annotations: { title: 'Date search MemoryRouter', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+  },
   {
     name: 'memory_store',
     description: 'Store a concise durable project memory. Returns a stable content-derived handle and deduplicates exact repeats.',
@@ -139,6 +156,48 @@ async function callTool(name, args = {}, options = {}) {
     }
     return textResult(text);
   }
+  if (name === 'memory_date_search') {
+    if (!args.from || typeof args.from !== 'string') return textResult('from is required (ISO 8601 date or datetime)', true);
+    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);
+    }
+    if (args.max_tokens !== undefined && (!Number.isInteger(args.max_tokens) || args.max_tokens < 1000 || args.max_tokens > 200000)) {
+      return textResult('max_tokens must be an integer between 1000 and 200000', true);
+    }
+    const params = { from: args.from };
+    if (typeof args.to === 'string' && args.to) params.to = args.to;
+    if (typeof args.query === 'string' && args.query.trim()) params.query = args.query.trim();
+    if (args.tiers !== undefined) params.tiers = args.tiers;
+    if (args.importance !== undefined) params.importance = args.importance;
+    if (args.max_tokens !== undefined) params.max_tokens = args.max_tokens;
+    const response = await api.dateSearch(key, params, { apiBase: config.apiBase, timeoutMs: 15000 });
+    if (!response.ok) {
+      const detail = response.data && response.data.error ? ` ${response.data.error}` : '';
+      return textResult(`Date search failed (HTTP ${response.status}).${detail}`, true);
+    }
+    const data = response.data || {};
+    const rows = Array.isArray(data.results) ? data.results : [];
+    if (!rows.length) return textResult('No memories in that window matched the filters.');
+    const lines = rows.map(row => {
+      const parsed = parseEnvelope(row.content);
+      const body = parsed ? parsed.body : String(row.content || '');
+      const tierTag = row.tier != null ? ` | tier ${row.tier}` : '';
+      const importanceTag = row.importance != null ? ` | importance ${row.importance}` : '';
+      return `[${row.date || 'unknown date'}${tierTag}${importanceTag}]\n${body}`;
+    });
+    const header = data.window
+      ? `Window ${data.window.from || params.from} to ${data.window.to || 'now'} (${rows.length} memories${data.truncated ? ', truncated' : ''}).`
+      : `${rows.length} memories${data.truncated ? ' (truncated)' : ''}.`;
+    const footer = data.truncated
+      ? `\n\nTruncated. Continue with ${data.next_to ? `to = ${data.next_to}` : data.next_from ? `from = ${data.next_from}` : 'a narrower window'}.`
+      : '';
+    return textResult(`${header}\n\n${lines.join('\n\n')}${footer}`);
+  }
   if (name === 'memory_store') {
     if (!args.content) return textResult('content is required', true);
     const result = await storeScoped(args.content, {