@empirical-gauzza/cli 1.0.28 → 1.0.30

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/installers/hooks.js

@@ -110,37 +110,125 @@ function main() {
     process.exit(0);
   }
 
-  var result = runMemoryQuery([
-    'memory', 'query',
-    '--match', 'project context, conventions, recent decisions, user preferences',
-    '--top-k', '8'
-  ]);
-
-  if (!result || result.status !== 0 || !result.stdout) {
-    appendLog('memory query failed or returned no stdout (status=' + (result && result.status) + ', stderr=' + (result && result.stderr ? String(result.stderr).slice(0, 300) : '') + ')');
-    process.exit(0);
+  // Declared inside main() on purpose: function declarations hoist, and other hook templates in
+  // this file have their own main() without the memory-query plumbing.
+
+  // WHAT PROJECT IS THIS, in priority order. Guessing from the directory name is the last resort,
+  // not the contract: a repo folder is not always what the corpus tags memories with.
+  //   1. EMPIRICAL_PROJECT_TAG / EMPIRICAL_TOPICS environment variables
+  //   2. .empirical.json in the working directory or any ancestor, up to 6 levels:
+  //        { "project": "empirical_v2", "topics": ["search ranking", "deploy"] }
+  //   3. the working directory name, lowercased
+  function readProjectConfig() {
+    var config = { project: '', topics: [] };
+    try {
+      var dir = process.cwd();
+      for (var depth = 0; depth < 6; depth += 1) {
+        var candidate = path.join(dir, '.empirical.json');
+        if (fs.existsSync(candidate)) {
+          var parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+          config.project = String(parsed && parsed.project ? parsed.project : '').trim().toLowerCase();
+          if (parsed && Array.isArray(parsed.topics)) {
+            config.topics = parsed.topics.map(function (t) { return String(t || '').trim(); }).filter(Boolean);
+          }
+          appendLog('loaded project config from ' + candidate);
+          return config;
+        }
+        var parent = path.dirname(dir);
+        if (!parent || parent === dir) { break; }
+        dir = parent;
+      }
+    } catch (e) {
+      appendLog('project config unreadable, continuing without it: ' + e.message);
+    }
+    return config;
   }
 
-  var results;
-  try {
-    results = JSON.parse(result.stdout);
-  } catch (e) {
-    appendLog('failed to parse memory query stdout as JSON: ' + e.message);
-    process.exit(0);
+  // requireAll selects --tags-all (AND) over --tags (OR). This matters: --tags is an OR match, so
+  // asking for 'empirical_v2,todo' returns every project's todos, which put a wellnessonbalance
+  // item into an empirical_v2 session during testing on 2026-09-16.
+  function fetchMemories(matchText, tags, topK, requireAll) {
+    var args = ['memory', 'query', '--match', matchText, '--top-k', String(topK)];
+    if (tags) { args.push(requireAll ? '--tags-all' : '--tags', tags); }
+    var queryResult = runMemoryQuery(args);
+    if (!queryResult || queryResult.status !== 0 || !queryResult.stdout) {
+      appendLog('memory query failed (tags=' + (tags || 'none') + ', status=' + (queryResult && queryResult.status) + ', stderr=' + (queryResult && queryResult.stderr ? String(queryResult.stderr).slice(0, 200) : '') + ')');
+      return [];
+    }
+    try {
+      var parsed = JSON.parse(queryResult.stdout);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch (e) {
+      appendLog('failed to parse memory query stdout as JSON: ' + e.message);
+      return [];
+    }
+  }
+
+  var fileConfig = readProjectConfig();
+  var envTag = String(process.env.EMPIRICAL_PROJECT_TAG || '').trim().toLowerCase();
+  var envTopics = String(process.env.EMPIRICAL_TOPICS || '').split(',').map(function (t) { return t.trim(); }).filter(Boolean);
+
+  var tag = envTag || fileConfig.project;
+  var tagSource = envTag ? 'env' : (fileConfig.project ? 'config' : 'cwd');
+  if (!tag) {
+    try {
+      tag = String(path.basename(process.cwd() || '') || '').trim().toLowerCase();
+    } catch (e) {
+      tag = '';
+    }
+  }
+
+  var topics = envTopics.length ? envTopics : fileConfig.topics;
+  var contextMatch = topics.length
+    ? topics.join(', ')
+    : 'project context, conventions, recent decisions, user preferences';
+
+  appendLog('project tag=' + (tag || '(none)') + ' (source=' + tagSource + '), topics=' + (topics.length ? topics.join('|') : '(default)'));
+
+  // Scope every query to the project. Measured 2026-09-16: with no tag filter all 8 slots went to
+  // one unrelated project during a full session in a different repo, so the only automatic context
+  // rail in the product was spending every slot on the wrong thing. A tag filter also disables the
+  // server's agent-process-note exclusion, which is what makes a project's own scar tissue and
+  // work history reachable here at all.
+  //
+  // Open items get their OWN query instead of competing for rank. Tested 2026-09-16: a due-dated
+  // memory did not surface in the generic top-8 with or without a project filter, because dueness
+  // is not a semantic property. Anything that must be seen needs a reserved slot.
+  // AND, not OR: this must be THIS project's todos. No --status filter on purpose, because todos
+  // written without a data.status would silently vanish from the one place they get surfaced;
+  // the label tells the reader to confirm instead.
+  var todos = tag ? fetchMemories('open todo, next action, follow-up, due', tag + ',todo', 3, true) : [];
+  var context = tag ? fetchMemories(contextMatch, tag, 6) : [];
+
+  // A corpus whose tags do not match the resolved project must never end up worse off than before
+  // this change, so fall back to the original unscoped query.
+  if (context.length === 0) {
+    appendLog('project-scoped query returned nothing, falling back to unscoped');
+    context = fetchMemories(contextMatch, '', 8);
   }
 
-  if (!Array.isArray(results) || results.length === 0) {
+  if (todos.length === 0 && context.length === 0) {
     appendLog('memory query returned zero results');
     process.exit(0);
   }
 
+  var openCount = todos.length;
+  var results = todos.concat(context);
+
   appendLog('memory query returned ' + results.length + ' result(s), injecting into session context');
 
-  var lines = results.slice(0, 8).map(function (r) {
+  // Summaries in a mature corpus run to thousands of characters. Injecting eight in full is a wall
+  // of text that gets skimmed past, which fails the same way as never injecting them at all:
+  // presence in context is not attention. Truncate hard; the agent can query for the rest.
+  var lines = results.slice(0, 9).map(function (r, i) {
     var category = r && r.category ? r.category : 'memory';
-    var summary = r && r.summary ? r.summary : '';
-    return '- [' + category + '] ' + summary;
+    var summary = String(r && r.summary ? r.summary : '');
+    summary = summary.split('\\n').join(' ').split('\\r').join(' ').split('\\t').join(' ').trim();
+    if (summary.length > 240) { summary = summary.slice(0, 237) + '...'; }
+    var prefix = i < openCount ? '- [OPEN ITEM, confirm status] ' : '- [' + category + '] ';
+    return prefix + summary;
   });
+  lines.push('- Before risky or repeated work, ask first: empirical memory query --match "<what you are about to do>" --tags scar-tissue');
 
   console.log('Empirical memory context for this session:\\n' + lines.join('\\n'));
   process.exit(0);
@@ -259,40 +347,126 @@ function main() {
     process.exit(0);
   }
 
-  var result = runMemoryQuery([
-    'memory', 'query',
-    '--match', 'project context, conventions, recent decisions, user preferences',
-    '--top-k', '8'
-  ]);
+  // Declared inside main() on purpose: function declarations hoist, and other hook templates in
+  // this file have their own main() without the memory-query plumbing.
+
+  // WHAT PROJECT IS THIS, in priority order. Guessing from the directory name is the last resort,
+  // not the contract: a repo folder is not always what the corpus tags memories with.
+  //   1. EMPIRICAL_PROJECT_TAG / EMPIRICAL_TOPICS environment variables
+  //   2. .empirical.json in the working directory or any ancestor, up to 6 levels:
+  //        { "project": "empirical_v2", "topics": ["search ranking", "deploy"] }
+  //   3. the working directory name, lowercased
+  function readProjectConfig() {
+    var config = { project: '', topics: [] };
+    try {
+      var dir = process.cwd();
+      for (var depth = 0; depth < 6; depth += 1) {
+        var candidate = path.join(dir, '.empirical.json');
+        if (fs.existsSync(candidate)) {
+          var parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+          config.project = String(parsed && parsed.project ? parsed.project : '').trim().toLowerCase();
+          if (parsed && Array.isArray(parsed.topics)) {
+            config.topics = parsed.topics.map(function (t) { return String(t || '').trim(); }).filter(Boolean);
+          }
+          appendLog('loaded project config from ' + candidate);
+          return config;
+        }
+        var parent = path.dirname(dir);
+        if (!parent || parent === dir) { break; }
+        dir = parent;
+      }
+    } catch (e) {
+      appendLog('project config unreadable, continuing without it: ' + e.message);
+    }
+    return config;
+  }
 
-  if (!result || result.status !== 0 || !result.stdout) {
-    appendLog('memory query failed or returned no stdout (status=' + (result && result.status) + ', stderr=' + (result && result.stderr ? String(result.stderr).slice(0, 300) : '') + ')');
-    emitContext('');
-    process.exit(0);
+  // requireAll selects --tags-all (AND) over --tags (OR). This matters: --tags is an OR match, so
+  // asking for 'empirical_v2,todo' returns every project's todos, which put a wellnessonbalance
+  // item into an empirical_v2 session during testing on 2026-09-16.
+  function fetchMemories(matchText, tags, topK, requireAll) {
+    var args = ['memory', 'query', '--match', matchText, '--top-k', String(topK)];
+    if (tags) { args.push(requireAll ? '--tags-all' : '--tags', tags); }
+    var queryResult = runMemoryQuery(args);
+    if (!queryResult || queryResult.status !== 0 || !queryResult.stdout) {
+      appendLog('memory query failed (tags=' + (tags || 'none') + ', status=' + (queryResult && queryResult.status) + ', stderr=' + (queryResult && queryResult.stderr ? String(queryResult.stderr).slice(0, 200) : '') + ')');
+      return [];
+    }
+    try {
+      var parsed = JSON.parse(queryResult.stdout);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch (e) {
+      appendLog('failed to parse memory query stdout as JSON: ' + e.message);
+      return [];
+    }
   }
 
-  var results;
-  try {
-    results = JSON.parse(result.stdout);
-  } catch (e) {
-    appendLog('failed to parse memory query stdout as JSON: ' + e.message);
-    emitContext('');
-    process.exit(0);
+  var fileConfig = readProjectConfig();
+  var envTag = String(process.env.EMPIRICAL_PROJECT_TAG || '').trim().toLowerCase();
+  var envTopics = String(process.env.EMPIRICAL_TOPICS || '').split(',').map(function (t) { return t.trim(); }).filter(Boolean);
+
+  var tag = envTag || fileConfig.project;
+  var tagSource = envTag ? 'env' : (fileConfig.project ? 'config' : 'cwd');
+  if (!tag) {
+    try {
+      tag = String(path.basename(process.cwd() || '') || '').trim().toLowerCase();
+    } catch (e) {
+      tag = '';
+    }
+  }
+
+  var topics = envTopics.length ? envTopics : fileConfig.topics;
+  var contextMatch = topics.length
+    ? topics.join(', ')
+    : 'project context, conventions, recent decisions, user preferences';
+
+  appendLog('project tag=' + (tag || '(none)') + ' (source=' + tagSource + '), topics=' + (topics.length ? topics.join('|') : '(default)'));
+
+  // Scope every query to the project. Measured 2026-09-16: with no tag filter all 8 slots went to
+  // one unrelated project during a full session in a different repo, so the only automatic context
+  // rail in the product was spending every slot on the wrong thing. A tag filter also disables the
+  // server's agent-process-note exclusion, which is what makes a project's own scar tissue and
+  // work history reachable here at all.
+  //
+  // Open items get their OWN query instead of competing for rank. Tested 2026-09-16: a due-dated
+  // memory did not surface in the generic top-8 with or without a project filter, because dueness
+  // is not a semantic property. Anything that must be seen needs a reserved slot.
+  // AND, not OR: this must be THIS project's todos. No --status filter on purpose, because todos
+  // written without a data.status would silently vanish from the one place they get surfaced;
+  // the label tells the reader to confirm instead.
+  var todos = tag ? fetchMemories('open todo, next action, follow-up, due', tag + ',todo', 3, true) : [];
+  var context = tag ? fetchMemories(contextMatch, tag, 6) : [];
+
+  // A corpus whose tags do not match the resolved project must never end up worse off than before
+  // this change, so fall back to the original unscoped query.
+  if (context.length === 0) {
+    appendLog('project-scoped query returned nothing, falling back to unscoped');
+    context = fetchMemories(contextMatch, '', 8);
   }
 
-  if (!Array.isArray(results) || results.length === 0) {
+  if (todos.length === 0 && context.length === 0) {
     appendLog('memory query returned zero results');
     emitContext('');
     process.exit(0);
   }
 
+  var openCount = todos.length;
+  var results = todos.concat(context);
+
   appendLog('memory query returned ' + results.length + ' result(s), injecting into session context');
 
-  var lines = results.slice(0, 8).map(function (r) {
+  // Summaries in a mature corpus run to thousands of characters. Injecting eight in full is a wall
+  // of text that gets skimmed past, which fails the same way as never injecting them at all:
+  // presence in context is not attention. Truncate hard; the agent can query for the rest.
+  var lines = results.slice(0, 9).map(function (r, i) {
     var category = r && r.category ? r.category : 'memory';
-    var summary = r && r.summary ? r.summary : '';
-    return '- [' + category + '] ' + summary;
+    var summary = String(r && r.summary ? r.summary : '');
+    summary = summary.split('\\n').join(' ').split('\\r').join(' ').split('\\t').join(' ').trim();
+    if (summary.length > 240) { summary = summary.slice(0, 237) + '...'; }
+    var prefix = i < openCount ? '- [OPEN ITEM, confirm status] ' : '- [' + category + '] ';
+    return prefix + summary;
   });
+  lines.push('- Before risky or repeated work, ask first: empirical memory query --match "<what you are about to do>" --tags scar-tissue');
 
   console.log(JSON.stringify({
     hookSpecificOutput: {
@@ -400,38 +574,124 @@ function main() {
     process.exit(0);
   }
 
-  var result = runMemoryQuery([
-    'memory', 'query',
-    '--match', 'project context, conventions, recent decisions, user preferences',
-    '--top-k', '8'
-  ]);
+  // Declared inside main() on purpose: function declarations hoist, and other hook templates in
+  // this file have their own main() without the memory-query plumbing.
+
+  // WHAT PROJECT IS THIS, in priority order. Guessing from the directory name is the last resort,
+  // not the contract: a repo folder is not always what the corpus tags memories with.
+  //   1. EMPIRICAL_PROJECT_TAG / EMPIRICAL_TOPICS environment variables
+  //   2. .empirical.json in the working directory or any ancestor, up to 6 levels:
+  //        { "project": "empirical_v2", "topics": ["search ranking", "deploy"] }
+  //   3. the working directory name, lowercased
+  function readProjectConfig() {
+    var config = { project: '', topics: [] };
+    try {
+      var dir = process.cwd();
+      for (var depth = 0; depth < 6; depth += 1) {
+        var candidate = path.join(dir, '.empirical.json');
+        if (fs.existsSync(candidate)) {
+          var parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+          config.project = String(parsed && parsed.project ? parsed.project : '').trim().toLowerCase();
+          if (parsed && Array.isArray(parsed.topics)) {
+            config.topics = parsed.topics.map(function (t) { return String(t || '').trim(); }).filter(Boolean);
+          }
+          appendLog('loaded project config from ' + candidate);
+          return config;
+        }
+        var parent = path.dirname(dir);
+        if (!parent || parent === dir) { break; }
+        dir = parent;
+      }
+    } catch (e) {
+      appendLog('project config unreadable, continuing without it: ' + e.message);
+    }
+    return config;
+  }
 
-  if (!result || result.status !== 0 || !result.stdout) {
-    appendLog('memory query failed or returned no stdout (status=' + (result && result.status) + ', stderr=' + (result && result.stderr ? String(result.stderr).slice(0, 300) : '') + ')');
-    console.log('{}');
-    process.exit(0);
+  // requireAll selects --tags-all (AND) over --tags (OR). This matters: --tags is an OR match, so
+  // asking for 'empirical_v2,todo' returns every project's todos, which put a wellnessonbalance
+  // item into an empirical_v2 session during testing on 2026-09-16.
+  function fetchMemories(matchText, tags, topK, requireAll) {
+    var args = ['memory', 'query', '--match', matchText, '--top-k', String(topK)];
+    if (tags) { args.push(requireAll ? '--tags-all' : '--tags', tags); }
+    var queryResult = runMemoryQuery(args);
+    if (!queryResult || queryResult.status !== 0 || !queryResult.stdout) {
+      appendLog('memory query failed (tags=' + (tags || 'none') + ', status=' + (queryResult && queryResult.status) + ', stderr=' + (queryResult && queryResult.stderr ? String(queryResult.stderr).slice(0, 200) : '') + ')');
+      return [];
+    }
+    try {
+      var parsed = JSON.parse(queryResult.stdout);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch (e) {
+      appendLog('failed to parse memory query stdout as JSON: ' + e.message);
+      return [];
+    }
   }
 
-  var results;
-  try {
-    results = JSON.parse(result.stdout);
-  } catch (e) {
-    appendLog('failed to parse memory query stdout as JSON: ' + e.message);
-    console.log('{}');
-    process.exit(0);
+  var fileConfig = readProjectConfig();
+  var envTag = String(process.env.EMPIRICAL_PROJECT_TAG || '').trim().toLowerCase();
+  var envTopics = String(process.env.EMPIRICAL_TOPICS || '').split(',').map(function (t) { return t.trim(); }).filter(Boolean);
+
+  var tag = envTag || fileConfig.project;
+  var tagSource = envTag ? 'env' : (fileConfig.project ? 'config' : 'cwd');
+  if (!tag) {
+    try {
+      tag = String(path.basename(process.cwd() || '') || '').trim().toLowerCase();
+    } catch (e) {
+      tag = '';
+    }
   }
 
-  if (!Array.isArray(results) || results.length === 0) {
+  var topics = envTopics.length ? envTopics : fileConfig.topics;
+  var contextMatch = topics.length
+    ? topics.join(', ')
+    : 'project context, conventions, recent decisions, user preferences';
+
+  appendLog('project tag=' + (tag || '(none)') + ' (source=' + tagSource + '), topics=' + (topics.length ? topics.join('|') : '(default)'));
+
+  // Scope every query to the project. Measured 2026-09-16: with no tag filter all 8 slots went to
+  // one unrelated project during a full session in a different repo, so the only automatic context
+  // rail in the product was spending every slot on the wrong thing. A tag filter also disables the
+  // server's agent-process-note exclusion, which is what makes a project's own scar tissue and
+  // work history reachable here at all.
+  //
+  // Open items get their OWN query instead of competing for rank. Tested 2026-09-16: a due-dated
+  // memory did not surface in the generic top-8 with or without a project filter, because dueness
+  // is not a semantic property. Anything that must be seen needs a reserved slot.
+  // AND, not OR: this must be THIS project's todos. No --status filter on purpose, because todos
+  // written without a data.status would silently vanish from the one place they get surfaced;
+  // the label tells the reader to confirm instead.
+  var todos = tag ? fetchMemories('open todo, next action, follow-up, due', tag + ',todo', 3, true) : [];
+  var context = tag ? fetchMemories(contextMatch, tag, 6) : [];
+
+  // A corpus whose tags do not match the resolved project must never end up worse off than before
+  // this change, so fall back to the original unscoped query.
+  if (context.length === 0) {
+    appendLog('project-scoped query returned nothing, falling back to unscoped');
+    context = fetchMemories(contextMatch, '', 8);
+  }
+
+  if (todos.length === 0 && context.length === 0) {
     appendLog('memory query returned zero results');
     console.log('{}');
     process.exit(0);
   }
 
-  var lines = results.slice(0, 8).map(function (r) {
+  var openCount = todos.length;
+  var results = todos.concat(context);
+
+  // Summaries in a mature corpus run to thousands of characters. Injecting eight in full is a wall
+  // of text that gets skimmed past, which fails the same way as never injecting them at all:
+  // presence in context is not attention. Truncate hard; the agent can query for the rest.
+  var lines = results.slice(0, 9).map(function (r, i) {
     var category = r && r.category ? r.category : 'memory';
-    var summary = r && r.summary ? r.summary : '';
-    return '- [' + category + '] ' + summary;
+    var summary = String(r && r.summary ? r.summary : '');
+    summary = summary.split('\\n').join(' ').split('\\r').join(' ').split('\\t').join(' ').trim();
+    if (summary.length > 240) { summary = summary.slice(0, 237) + '...'; }
+    var prefix = i < openCount ? '- [OPEN ITEM, confirm status] ' : '- [' + category + '] ';
+    return prefix + summary;
   });
+  lines.push('- Before risky or repeated work, ask first: empirical memory query --match "<what you are about to do>" --tags scar-tissue');
 
   // Logged only - Copilot's sessionStart event has no field that surfaces this to the model.
   appendLog('memory query returned ' + results.length + ' result(s) (session-start has no output channel to inject them, logged only): ' + lines.join(' | '));
@@ -840,7 +1100,7 @@ function installClaudeHooks(pluginNames) {
   for (const matcher of ['startup', 'resume', 'compact']) {
     settings.hooks.SessionStart.push({
       matcher,
-      hooks: [{ type: 'command', command: buildHookCommand(sessionStartScriptPath), timeout: 15 }]
+      hooks: [{ type: 'command', command: buildHookCommand(sessionStartScriptPath), timeout: 25 }]
     });
   }
 
@@ -969,7 +1229,7 @@ function installCodexHooks(pluginNames) {
   for (const matcher of ['startup', 'resume']) {
     hooksFile.hooks.SessionStart.push({
       matcher,
-      hooks: [{ type: 'command', command: sessionStartCommand, commandWindows: sessionStartCommandWindows, timeout: 15 }]
+      hooks: [{ type: 'command', command: sessionStartCommand, commandWindows: sessionStartCommandWindows, timeout: 25 }]
     });
   }
 

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.