@empirical-gauzza/cli 1.0.29 → 1.0.31

package/lib/deviceConfig.js

@@ -41,6 +41,31 @@ function writeIntegrationMode(integrationMode) {
   writeDeviceConfig(config);
 }
 
+// Hosts (codex / copilot / claude) that Empirical has actually been installed for on this
+// machine, recorded by `empirical install` and `empirical plugin install`. `doctor` reads this
+// so a host that merely exists on the machine (a ~/.claude folder left by another tool, or a CLI
+// the user deliberately skipped in the installer) is reported as skipped, not as broken.
+// Returns null when nothing was ever recorded (installs that predate this field), so callers
+// can tell "unknown" apart from "none".
+const KNOWN_HOST_IDS = ['codex', 'copilot', 'claude'];
+
+function readInstalledHosts() {
+  const config = readDeviceConfig();
+  if (!Array.isArray(config.installedHosts)) return null;
+  return config.installedHosts.filter((id) => KNOWN_HOST_IDS.includes(id));
+}
+
+function addInstalledHosts(hostIds) {
+  const config = readDeviceConfig();
+  const existing = Array.isArray(config.installedHosts) ? config.installedHosts : [];
+  const merged = new Set(existing.filter((id) => KNOWN_HOST_IDS.includes(id)));
+  for (const id of hostIds || []) {
+    if (KNOWN_HOST_IDS.includes(id)) merged.add(id);
+  }
+  config.installedHosts = KNOWN_HOST_IDS.filter((id) => merged.has(id));
+  writeDeviceConfig(config);
+}
+
 function readPolicyCache() {
   const config = readDeviceConfig();
   return config.empiricalPolicy || null;
@@ -101,6 +126,8 @@ module.exports = {
   writeDeviceConfig,
   readIntegrationMode,
   writeIntegrationMode,
+  readInstalledHosts,
+  addInstalledHosts,
   readPolicyCache,
   writePolicyCache,
   ensureDeviceId,

package/lib/doctor.js

@@ -13,6 +13,39 @@ const { detectInstallTargets } = require('./installers/detect');
 const { readInstalledVersions } = require('./pluginUpdateCheck');
 const { CORE_PLUGIN_NAME, OPTIONAL_PLUGIN_NAMES } = require('./installers/nativePlugin');
 const { getEmpiricalHooksDir, getCodexHooksScriptsDir, getCodexHomeDir } = require('./installers/hooks');
+const { readIntegrationMode, readInstalledHosts } = require('./deviceConfig');
+
+// ─── Which detected hosts doctor should grade ──────────────────────────────────
+// Doctor output is read by agents, and a FAIL line with a "Run: ..." remedy is, to an agent, an
+// instruction. So a host the user never set Empirical up for must not be graded as broken:
+//   - If the installer recorded which hosts it installed for, grade exactly those.
+//   - Otherwise (installs that predate the record), grade only hosts whose binary is on PATH; a
+//     bare dotfolder (e.g. ~/.claude left behind with no `claude` command) is nothing to check.
+// Skipped hosts still get one informational line so the user can see why they were left out.
+function partitionHostsToCheck(detectedTargets, installedHosts) {
+  const checked = [];
+  const skipped = [];
+  for (const target of detectedTargets) {
+    if (installedHosts !== null) {
+      if (installedHosts.includes(target.id)) {
+        checked.push(target);
+      } else {
+        const evidence = target.onPath
+          ? `${target.id} is on PATH`
+          : `only its ${target.configDir} folder exists; ${target.id} is not on PATH`;
+        skipped.push({ target, reason: `not set up for Empirical (${evidence}). To add it: empirical install.` });
+      }
+    } else if (target.onPath) {
+      checked.push(target);
+    } else {
+      skipped.push({
+        target,
+        reason: `only its ${target.configDir} folder exists; ${target.id} is not on PATH, so there is nothing to check. To set it up later: empirical install.`
+      });
+    }
+  }
+  return { checked, skipped };
+}
 
 // ─── Host MCP config registration ─────────────────────────────────────────────
 // Each host stores "is the Empirical MCP server registered" in a different shape and location.
@@ -377,11 +410,28 @@ async function runDoctor(args) {
     }
 
     // ─── MCP wiring diagnostics (C-007) ─────────────────────────────────────
-    const detectedTargets = detectInstallTargets();
-    if (detectedTargets.length === 0) {
+    const allDetected = detectInstallTargets();
+    let installedHosts = null;
+    let integrationMode = 1;
+    try {
+      installedHosts = readInstalledHosts();
+      integrationMode = readIntegrationMode();
+    } catch (_error) {
+      installedHosts = null;
+      integrationMode = 1;
+    }
+    const { checked: detectedTargets, skipped: skippedTargets } = partitionHostsToCheck(allDetected, installedHosts);
+
+    if (allDetected.length === 0) {
       addCheck('mcp_hosts_detected', 'warn', 'No supported host CLI detected (codex/claude/copilot). Nothing to check for MCP wiring.');
+    } else if (detectedTargets.length === 0) {
+      addCheck('mcp_hosts_detected', 'warn', `Detected: ${allDetected.map((t) => t.label).join(', ')}, but none is set up for Empirical. Run: empirical install.`);
     } else {
-      addCheck('mcp_hosts_detected', 'ok', `Detected: ${detectedTargets.map((t) => t.label).join(', ')}.`);
+      const modeLabel = integrationMode === 2 ? 'CLI-direct' : integrationMode === 3 ? 'MCP + CLI' : 'MCP';
+      addCheck('mcp_hosts_detected', 'ok', `Checking: ${detectedTargets.map((t) => t.label).join(', ')} (${modeLabel} mode).`);
+    }
+    for (const { target, reason } of skippedTargets) {
+      addCheck(`host_${target.id}`, 'skip', `${target.label}: ${reason}`);
     }
 
     for (const target of detectedTargets) {
@@ -393,7 +443,16 @@ async function runDoctor(args) {
       } catch (error) {
         result = { ok: false, message: `Could not inspect ${target.label} MCP config: ${error.message}` };
       }
-      addCheck(`mcp_config_${target.id}`, result.ok ? 'ok' : 'fail', `${target.label}: ${result.message}`);
+      if (integrationMode === 2) {
+        // CLI-direct mode: agents call the `empirical` CLI, so an unregistered MCP server is the
+        // expected state, not a defect. Report whatever is there without failing on absence.
+        const message = result.ok
+          ? `${result.message} (CLI-direct mode; MCP registration is optional.)`
+          : 'CLI-direct mode: MCP server not registered, and none is expected. Agents use the empirical CLI.';
+        addCheck(`mcp_config_${target.id}`, 'ok', `${target.label}: ${message}`);
+      } else {
+        addCheck(`mcp_config_${target.id}`, result.ok ? 'ok' : 'fail', `${target.label}: ${result.message}`);
+      }
     }
 
     const mcpReachability = await checkMcpReachability(token);
@@ -464,6 +523,7 @@ async function runDoctor(args) {
       const statusLabel = (status) => {
         if (status === 'ok') return colorize(ANSI.green, '[OK]  ');
         if (status === 'warn') return colorize(ANSI.yellow, '[WARN]');
+        if (status === 'skip') return colorize(ANSI.dim, '[SKIP]');
         return colorize(ANSI.red, '[FAIL]');
       };
       for (const check of checks) {

package/lib/http.js

@@ -84,7 +84,7 @@ function httpJson(urlString, method, payload, headers = {}, timeoutMs = 0) {
         headers: {
           Accept: 'application/json',
           // Identifies the client so the server can tell a CLI write from a portal write
-          // (services/memoryAuthorship.ts). Writes also send source: 'cli' in the body,
+          // (@empirical/core's memoryAuthorship). Writes also send source: 'cli' in the body,
           // which is authoritative; this covers every other endpoint.
           'User-Agent': 'empirical-cli/1.0',
           ...(body ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) } : {}),
@@ -144,7 +144,7 @@ function httpForm(urlString, method, params, headers = {}) {
         headers: {
           Accept: 'application/json',
           // Identifies the client so the server can tell a CLI write from a portal write
-          // (services/memoryAuthorship.ts). Writes also send source: 'cli' in the body,
+          // (@empirical/core's memoryAuthorship). Writes also send source: 'cli' in the body,
           // which is authoritative; this covers every other endpoint.
           'User-Agent': 'empirical-cli/1.0',
           'Content-Type': 'application/x-www-form-urlencoded',

package/lib/installWizard.js

@@ -23,8 +23,9 @@ const { detectInstallTargets } = require('./installers/detect');
 const { installClaudeHooks, installCodexHooks, installCopilotHooks } = require('./installers/hooks');
 const { runCodex } = require('./installers/codex');
 const { installNativePlugin, OPTIONAL_PLUGIN_NAMES } = require('./installers/nativePlugin');
+const { writeCoreMemoryGuidance } = require('./installers/coreMemoryBlock');
 const { policyFromInstallerOptions, savePolicy: persistPolicy } = require('./policyCommands');
-const { writeIntegrationMode } = require('./deviceConfig');
+const { writeIntegrationMode, addInstalledHosts } = require('./deviceConfig');
 
 function pluginNamesForInstallerOptions(options = {}) {
   const names = ['empirical-memory'];
@@ -234,10 +235,13 @@ async function runInstallFlow() {
     log(uiHeader(`Step 2/2: Installing for ${target.label}...`));
     try {
       if (integrationMode === 2) {
-        // CLI-direct: skip MCP registration; the native plugin owns guidance.
+        // CLI-direct: skip MCP registration only. The skill, the hooks AND the global
+        // instructions block are all still required -- a real Copilot install that skipped the
+        // instructions file here left the agent ignoring Empirical for a whole session.
         const pluginNames = pluginNamesForInstallerOptions(promptOptions);
         installNativePlugin(target.id, pluginNames, integrationMode);
         log(`  - ${target.label} native plugins installed: ${pluginNames.join(', ')}.`);
+        writeCoreMemoryGuidance(target.id, pluginNames);
         if (target.id === 'claude') {
           try {
             installClaudeHooks(pluginNames);
@@ -260,6 +264,7 @@ async function runInstallFlow() {
           }
         }
         log(uiSuccess(`Done: ${target.label} (CLI-direct mode)`));
+        addInstalledHosts([target.id]);
       } else {
         // Mode 1 or 3: run MCP install normally
         const pluginNames = pluginNamesForInstallerOptions(promptOptions);
@@ -269,6 +274,7 @@ async function runInstallFlow() {
           integrationMode
         });
         log(uiSuccess(`Done: ${target.label}`));
+        addInstalledHosts([target.id]);
         if (target.id === 'codex') {
           codexInstalled = true;
           codexNeedsPostLogin = Boolean(installResult?.needsPostLogin);

package/lib/installers/claude.js

@@ -11,7 +11,7 @@ const {
 const { INSTALL_PROMPT_OPTIONS_DEFAULTS } = require('./promptBlocks');
 const { installClaudeHooks } = require('./hooks');
 const { installNativePlugin, CORE_PLUGIN_NAME } = require('./nativePlugin');
-const { buildCoreMemoryBlock, upsertCoreMemoryBlock } = require('./coreMemoryBlock');
+const { writeCoreMemoryGuidance } = require('./coreMemoryBlock');
 
 function runClaude(args, options = {}) {
   return runResolvedCommand('claude', args, options);
@@ -30,14 +30,7 @@ function installClaude(headlessToken, promptOptions = INSTALL_PROMPT_OPTIONS_DEF
   // writes the same kind of identity-framed statement into the one file Claude reads every
   // session unconditionally, inside a clearly delimited block so any of the user's own content
   // in CLAUDE.md is left untouched.
-  try {
-    const claudeMdPath = path.join(os.homedir(), '.claude', 'CLAUDE.md');
-    const block = buildCoreMemoryBlock({ pluginNames: installOptions.pluginNames || [CORE_PLUGIN_NAME] });
-    upsertCoreMemoryBlock(claudeMdPath, block);
-    log(`  - Wrote Empirical core memory guidance to ${claudeMdPath}.`);
-  } catch (error) {
-    warn(`  - Could not write Empirical core memory guidance to CLAUDE.md: ${error.message}`);
-  }
+  writeCoreMemoryGuidance('claude', installOptions.pluginNames || [CORE_PLUGIN_NAME]);
 
   // installNativePlugin throws if the plugin install/update genuinely fails (see
   // assertPluginInstallSucceeded in nativePlugin.js) - hooks are only installed AFTER this

package/lib/installers/codex.js

@@ -11,7 +11,7 @@ const {
 const { INSTALL_PROMPT_OPTIONS_DEFAULTS } = require('./promptBlocks');
 const { installCodexHooks } = require('./hooks');
 const { installNativePlugin, CORE_PLUGIN_NAME } = require('./nativePlugin');
-const { buildCoreMemoryBlock, upsertCoreMemoryBlock } = require('./coreMemoryBlock');
+const { writeCoreMemoryGuidance } = require('./coreMemoryBlock');
 
 function runCodex(args, options = {}) {
   return runResolvedCommand('codex', args, options);
@@ -26,14 +26,7 @@ function installCodex(headlessToken, promptOptions = INSTALL_PROMPT_OPTIONS_DEFA
   // 2026-08-24: see claude.js's identical block for why this now writes AGENTS.md instead of
   // leaving it untouched -- hooks + an installable skill alone were not enough against a
   // competing identity-framed built-in memory feature in a real session.
-  try {
-    const agentsMdPath = path.join(os.homedir(), '.codex', 'AGENTS.md');
-    const block = buildCoreMemoryBlock({ pluginNames: installOptions.pluginNames || [CORE_PLUGIN_NAME] });
-    upsertCoreMemoryBlock(agentsMdPath, block);
-    log(`  - Wrote Empirical core memory guidance to ${agentsMdPath}.`);
-  } catch (error) {
-    warn(`  - Could not write Empirical core memory guidance to AGENTS.md: ${error.message}`);
-  }
+  writeCoreMemoryGuidance('codex', installOptions.pluginNames || [CORE_PLUGIN_NAME]);
 
   // installNativePlugin throws on genuine failure (see assertPluginInstallSucceeded in
   // nativePlugin.js) - hooks install only AFTER this succeeds, never before, so a failed/skipped

package/lib/installers/copilot.js

@@ -12,7 +12,7 @@ const {
 const { INSTALL_PROMPT_OPTIONS_DEFAULTS } = require('./promptBlocks');
 const { installCopilotHooks } = require('./hooks');
 const { installNativePlugin, CORE_PLUGIN_NAME } = require('./nativePlugin');
-const { buildCoreMemoryBlock, upsertCoreMemoryBlock } = require('./coreMemoryBlock');
+const { writeCoreMemoryGuidance } = require('./coreMemoryBlock');
 
 function installCopilot(headlessToken, promptOptions = INSTALL_PROMPT_OPTIONS_DEFAULTS, installOptions = {}) {
   const home = os.homedir();
@@ -65,13 +65,7 @@ function installCopilot(headlessToken, promptOptions = INSTALL_PROMPT_OPTIONS_DE
   // 2026-08-24: see claude.js's identical block for why this now writes copilot-instructions.md
   // instead of leaving it untouched -- hooks + an installable skill alone were not enough
   // against a competing identity-framed built-in memory feature in a real session.
-  try {
-    const block = buildCoreMemoryBlock({ pluginNames: installOptions.pluginNames || [CORE_PLUGIN_NAME] });
-    upsertCoreMemoryBlock(instructionsPath, block);
-    log(`  - Wrote Empirical core memory guidance to ${instructionsPath}.`);
-  } catch (error) {
-    warn(`  - Could not write Empirical core memory guidance to copilot-instructions.md: ${error.message}`);
-  }
+  writeCoreMemoryGuidance('copilot', installOptions.pluginNames || [CORE_PLUGIN_NAME]);
 
   // installNativePlugin throws on genuine failure (see assertPluginInstallSucceeded in
   // nativePlugin.js) - hooks install only AFTER this succeeds, never before, so a failed/skipped

package/lib/installers/coreMemoryBlock.js

@@ -1,6 +1,8 @@
 'use strict';
 
 const { readUtf8IfExists, writeFile, ensureDir } = require('../fsUtils');
+const { log, warn } = require('../ui');
+const os = require('os');
 const path = require('path');
 const { CORE_PLUGIN_NAME, OPTIONAL_PLUGIN_NAMES } = require('./nativePlugin');
 
@@ -88,9 +90,48 @@ function upsertCoreMemoryBlock(filePath, block) {
   writeFile(filePath, next);
 }
 
+// The one instructions file each host reads unconditionally every session. Kept here, next to
+// the block it receives, so every install path (full installer in any mode, `plugin install`)
+// writes to the same place instead of each path re-deriving it.
+const INSTRUCTIONS_FILE_BY_HOST = {
+  claude: ['.claude', 'CLAUDE.md'],
+  codex: ['.codex', 'AGENTS.md'],
+  copilot: ['.copilot', 'copilot-instructions.md']
+};
+
+function instructionsFilePathForHost(hostId) {
+  const segments = INSTRUCTIONS_FILE_BY_HOST[hostId];
+  if (!segments) throw new Error(`No global instructions file is known for host "${hostId}".`);
+  return path.join(os.homedir(), ...segments);
+}
+
+/**
+ * Writes (or refreshes) the core memory block in the host's global instructions file. Every
+ * install path must call this, whatever integration mode the user picked: a real CLI-direct
+ * Copilot install (2026-09-17) installed the skill and hooks but skipped this file, and the
+ * agent ignored Empirical for the whole session exactly as the 2026-08-24 incident predicted.
+ * Never throws; a failure here is logged and must not fail the install that already succeeded.
+ * Returns the path written, or null on failure.
+ */
+function writeCoreMemoryGuidance(hostId, pluginNames = [CORE_PLUGIN_NAME]) {
+  let filePath = null;
+  try {
+    filePath = instructionsFilePathForHost(hostId);
+    const block = buildCoreMemoryBlock({ pluginNames: pluginNames && pluginNames.length ? pluginNames : [CORE_PLUGIN_NAME] });
+    upsertCoreMemoryBlock(filePath, block);
+    log(`  - Wrote Empirical core memory guidance to ${filePath}.`);
+    return filePath;
+  } catch (error) {
+    warn(`  - Could not write Empirical core memory guidance for ${hostId}${filePath ? ` (${filePath})` : ''}: ${error.message}`);
+    return null;
+  }
+}
+
 module.exports = {
   BEGIN_MARKER,
   END_MARKER,
   buildCoreMemoryBlock,
-  upsertCoreMemoryBlock
+  upsertCoreMemoryBlock,
+  instructionsFilePathForHost,
+  writeCoreMemoryGuidance
 };

package/lib/installers/detect.js

@@ -8,33 +8,49 @@ const { installCodex } = require('./codex');
 const { installCopilot } = require('./copilot');
 const { installClaude } = require('./claude');
 
+// A host counts as detected when its binary is on PATH OR its home dotfolder exists. The
+// dotfolder alone is a weak signal (another tool, an uninstalled CLI, or a desktop app can leave
+// one behind), so each target also carries `onPath` and `configDirExists` separately; doctor uses
+// them to say "found only a folder, nothing to check" instead of failing the host.
 function detectInstallTargets() {
   const home = os.homedir();
   const targets = [];
 
-  const codexDetected = commandExists('codex') || fs.existsSync(path.join(home, '.codex'));
-  if (codexDetected) {
+  const codexOnPath = commandExists('codex');
+  const codexDirExists = fs.existsSync(path.join(home, '.codex'));
+  if (codexOnPath || codexDirExists) {
     targets.push({
       id: 'codex',
       label: 'Codex CLI',
+      onPath: codexOnPath,
+      configDirExists: codexDirExists,
+      configDir: path.join(home, '.codex'),
       install: installCodex
     });
   }
 
-  const copilotDetected = commandExists('copilot') || fs.existsSync(path.join(home, '.copilot'));
-  if (copilotDetected) {
+  const copilotOnPath = commandExists('copilot');
+  const copilotDirExists = fs.existsSync(path.join(home, '.copilot'));
+  if (copilotOnPath || copilotDirExists) {
     targets.push({
       id: 'copilot',
       label: 'GitHub Copilot CLI',
+      onPath: copilotOnPath,
+      configDirExists: copilotDirExists,
+      configDir: path.join(home, '.copilot'),
       install: installCopilot
     });
   }
 
-  const claudeDetected = commandExists('claude') || fs.existsSync(path.join(home, '.claude'));
-  if (claudeDetected) {
+  const claudeOnPath = commandExists('claude');
+  const claudeDirExists = fs.existsSync(path.join(home, '.claude'));
+  if (claudeOnPath || claudeDirExists) {
     targets.push({
       id: 'claude',
       label: 'Claude CLI',
+      onPath: claudeOnPath,
+      configDirExists: claudeDirExists,
+      configDir: path.join(home, '.claude'),
       install: installClaude
     });
   }

package/lib/installers/hooks.js

@@ -85,7 +85,9 @@ function runMemoryQuery(args) {
     appendLog('resolved direct entry point: ' + entryPoint);
     return spawnSync(process.execPath, [entryPoint].concat(args), {
       encoding: 'utf8',
-      timeout: 10000,
+      // Must stay under the host manifest cap for this event (25s). Recall is chronically 2-7s
+      // and the old 10s here killed the query silently while the host still had 15s to spare.
+      timeout: 20000,
       shell: false
     });
   }
@@ -97,7 +99,7 @@ function runMemoryQuery(args) {
   appendLog('direct entry point not resolved, falling back to shell invocation (shell=' + (process.platform === 'win32') + ')');
   return spawnSync('empirical', args, {
     encoding: 'utf8',
-    timeout: 10000,
+    timeout: 20000,
     shell: process.platform === 'win32'
   });
 }
@@ -310,7 +312,9 @@ function runMemoryQuery(args) {
     appendLog('resolved direct entry point: ' + entryPoint);
     return spawnSync(process.execPath, [entryPoint].concat(args), {
       encoding: 'utf8',
-      timeout: 10000,
+      // Must stay under the host manifest cap for this event (25s). Recall is chronically 2-7s
+      // and the old 10s here killed the query silently while the host still had 15s to spare.
+      timeout: 20000,
       shell: false
     });
   }
@@ -318,7 +322,7 @@ function runMemoryQuery(args) {
   appendLog('direct entry point not resolved, falling back to shell invocation (shell=' + (process.platform === 'win32') + ')');
   return spawnSync('empirical', args, {
     encoding: 'utf8',
-    timeout: 10000,
+    timeout: 20000,
     shell: process.platform === 'win32'
   });
 }
@@ -552,7 +556,9 @@ function runMemoryQuery(args) {
     appendLog('resolved direct entry point: ' + entryPoint);
     return spawnSync(process.execPath, [entryPoint].concat(args), {
       encoding: 'utf8',
-      timeout: 10000,
+      // Must stay under the host manifest cap for this event (25s). Recall is chronically 2-7s
+      // and the old 10s here killed the query silently while the host still had 15s to spare.
+      timeout: 20000,
       shell: false
     });
   }
@@ -560,7 +566,7 @@ function runMemoryQuery(args) {
   appendLog('direct entry point not resolved, falling back to shell invocation (shell=' + (process.platform === 'win32') + ')');
   return spawnSync('empirical', args, {
     encoding: 'utf8',
-    timeout: 10000,
+    timeout: 20000,
     shell: process.platform === 'win32'
   });
 }

package/lib/installers/skill-variants/SKILL.both.md

@@ -195,6 +195,27 @@ Use these when connected: `get_empirical_policy`, `query_memories`, `list_memori
 graph work, use `get_memory_neighbors` and `update_memory_relationships` when available instead of
 reconstructing relationships through many unrelated calls.
 
+## Reminders — set them, relay them, close them
+
+Any memory can carry a due date. Empirical then brings it back: an email with a calendar entry
+when the reminder is set, a nudge when it is due, and a notice attached to the next Empirical
+response each of the user's agents receives.
+
+- **Set one** when the user says "remind me", names a deadline, or a todo has a real due date.
+  Use the `dueAt` parameter on `record_graph_memory` / `update_memory_by_query` (ISO 8601), or
+  `empirical memory record ... --due 2026-10-14T09:00:00Z` on the CLI. `dueAt` is a real field the
+  server filters and fires on; a date written inside `data` is text and nothing will ever fire.
+- **Relay it.** If any Empirical result starts with `REMINDER DUE`, or a CLI command prints a
+  banner that starts with `REMINDER DUE`, tell the user about it in your own words BEFORE the task
+  you were doing, then ask whether to mark it done. Each agent is shown a reminder once; if you do
+  not relay it, the user does not hear it from you.
+- **Close it** when the user says it is handled: `acknowledge_reminder` with the `memoryId` from
+  the notice (or `state: "cancelled"` to drop it), or `empirical memory acknowledge --memory-id <id>`
+  (`--cancel` to drop). Closing frees the slot; plans cap concurrent open reminders.
+- **What is due?** `query_memories` with `dueBefore` set to now and `remindState: ["pending"]`, or
+  `empirical memory query --match "what is due" --due-before <now> --remind-state pending`.
+  Dueness is a filter; semantic search will not rank a memory higher because it is due.
+
 ## Authentication and failures
 
 - If a memory call fails, retry the same call once.

package/lib/installers/skill-variants/SKILL.cli.md

@@ -179,6 +179,27 @@ token error, run `empirical oauth bootstrap headless --write-env`. When in doubt
 subcommand's flags, run `empirical doc memory`, `empirical doc kit`, or `empirical doc skill`
 rather than guessing.
 
+## Reminders — set them, relay them, close them
+
+Any memory can carry a due date. Empirical then brings it back: an email with a calendar entry
+when the reminder is set, a nudge when it is due, and a notice attached to the next Empirical
+response each of the user's agents receives.
+
+- **Set one** when the user says "remind me", names a deadline, or a todo has a real due date.
+  Use the `dueAt` parameter on `record_graph_memory` / `update_memory_by_query` (ISO 8601), or
+  `empirical memory record ... --due 2026-10-14T09:00:00Z` on the CLI. `dueAt` is a real field the
+  server filters and fires on; a date written inside `data` is text and nothing will ever fire.
+- **Relay it.** If any Empirical result starts with `REMINDER DUE`, or a CLI command prints a
+  banner that starts with `REMINDER DUE`, tell the user about it in your own words BEFORE the task
+  you were doing, then ask whether to mark it done. Each agent is shown a reminder once; if you do
+  not relay it, the user does not hear it from you.
+- **Close it** when the user says it is handled: `acknowledge_reminder` with the `memoryId` from
+  the notice (or `state: "cancelled"` to drop it), or `empirical memory acknowledge --memory-id <id>`
+  (`--cancel` to drop). Closing frees the slot; plans cap concurrent open reminders.
+- **What is due?** `query_memories` with `dueBefore` set to now and `remindState: ["pending"]`, or
+  `empirical memory query --match "what is due" --due-before <now> --remind-state pending`.
+  Dueness is a filter; semantic search will not rank a memory higher because it is due.
+
 ## Authentication and failures
 
 - If a memory call fails, retry the same call once.

package/lib/installers/skill-variants/SKILL.mcp.md

@@ -167,6 +167,27 @@ An `empirical` CLI may also be installed on this machine for diagnostics (`empir
 manual account setup, but it is not the point of this variant — do not lead with CLI commands for
 query or record workflows here.
 
+## Reminders — set them, relay them, close them
+
+Any memory can carry a due date. Empirical then brings it back: an email with a calendar entry
+when the reminder is set, a nudge when it is due, and a notice attached to the next Empirical
+response each of the user's agents receives.
+
+- **Set one** when the user says "remind me", names a deadline, or a todo has a real due date.
+  Use the `dueAt` parameter on `record_graph_memory` / `update_memory_by_query` (ISO 8601), or
+  `empirical memory record ... --due 2026-10-14T09:00:00Z` on the CLI. `dueAt` is a real field the
+  server filters and fires on; a date written inside `data` is text and nothing will ever fire.
+- **Relay it.** If any Empirical result starts with `REMINDER DUE`, or a CLI command prints a
+  banner that starts with `REMINDER DUE`, tell the user about it in your own words BEFORE the task
+  you were doing, then ask whether to mark it done. Each agent is shown a reminder once; if you do
+  not relay it, the user does not hear it from you.
+- **Close it** when the user says it is handled: `acknowledge_reminder` with the `memoryId` from
+  the notice (or `state: "cancelled"` to drop it), or `empirical memory acknowledge --memory-id <id>`
+  (`--cancel` to drop). Closing frees the slot; plans cap concurrent open reminders.
+- **What is due?** `query_memories` with `dueBefore` set to now and `remindState: ["pending"]`, or
+  `empirical memory query --match "what is due" --due-before <now> --remind-state pending`.
+  Dueness is a filter; semantic search will not rank a memory higher because it is due.
+
 ## Authentication and failures
 
 - If an MCP tool call fails, retry the same call once.