@empirical-gauzza/cli 1.0.29 → 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/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.

package/lib/memoryCommands.js

@@ -50,18 +50,22 @@ const RECALL_PATHS = ['semantic', 'list', 'graph', 'hebbian'];
 const RECALL_HOPS = [1, 2];
 // Hops only mean something on a pathway that walks relationships.
 const RECALL_HOP_PATHS = ['graph', 'hebbian'];
+// Reminder states `memory query --remind-state` may keep. Same enum the server's shared
+// normalizer and Memory.remindState declare.
+const REMIND_STATES = ['pending', 'notified', 'acknowledged', 'cancelled'];
 
 // ─── Scoped `--help` (C-005 item 5) ───────────────────────────────────────────
 // `empirical memory --help` / `empirical memory <sub> --help` print scoped usage instead of
 // the 90-line global help wall bin/empirical.js otherwise short-circuits every --help to.
 
 const MEMORY_SUBCOMMAND_USAGE = {
-  query: 'Usage: empirical memory query --match <query> [--top-k 3] [--category <cat>] [--tags <t1,t2>] [--tags-all <t1,t2>] [--status <s1,s2>] [--path semantic|list|graph|hebbian] [--hops 1|2] [--pretty] [--format table]',
+  query: 'Usage: empirical memory query --match <query> [--top-k 3] [--category <cat>] [--tags <t1,t2>] [--tags-all <t1,t2>] [--status <s1,s2>] [--due-before <ISO date>] [--due-after <ISO date>] [--remind-state pending,notified] [--path semantic|list|graph|hebbian] [--hops 1|2] [--pretty] [--format table]',
   get: 'Usage: empirical memory get --memory-id <id> [--pretty]',
   list: 'Usage: empirical memory list [--category <cat>] [--tags <t1,t2>] [--start-date <ISO>] [--end-date <ISO>] [--limit 20] [--cursor <cursor>] [--oldest] [--pretty] [--format table]',
   record: 'Usage: empirical memory record --category <cat> (--summary <text> | --summary - | --summary-file <path>) [--tags t1,t2] [--node-type observation] [--json-file <path>] [--no-dedupe] [--no-auto-link] [--author-type user|agent]',
   note: 'Usage: empirical memory note --text <note> (--match <query> | --memory-id <id>) [--min-score 0.35]',
   update: 'Usage: empirical memory update (--match <query> | --memory-id <id>) (--patch-json <json> | --json-file <path>) [--min-score 0.35]',
+  acknowledge: 'Usage: empirical memory acknowledge --memory-id <id> [--cancel]   (marks a due reminder done, or dropped with --cancel; frees its slot and clears the alert)',
   delete: 'Usage: empirical memory delete (--match <query> | --memory-id <id>) [--confirm] [--min-score 0.35]\nUsage: empirical memory delete (--tag <t> | --category <c> | --all) --confirm',
   duplicates: 'Usage: empirical memory duplicates --memory-id <id>',
   merge: 'Usage: empirical memory merge --canonical-id <id> --duplicate-id <id> [--no-merge-tags] [--no-merge-relationships]',
@@ -209,6 +213,29 @@ async function runMemoryQuery(args) {
   const pretty = parseFlag(args, '--pretty');
   const format = parseOption(args, '--format', 'json');
 
+  // Reminder filters. Dates are parsed HERE as well as server-side, for the same reason --due
+  // is on record: a typo fails at the terminal, not as a 400 after the round trip. Anything
+  // Date can parse is accepted and sent as the caller typed it.
+  const dueFilters = {};
+  for (const [flag, key] of [['--due-before', 'dueBefore'], ['--due-after', 'dueAfter']]) {
+    const raw = parseOption(args, flag, '');
+    if (!raw) continue;
+    if (Number.isNaN(new Date(raw).getTime())) {
+      warn(`Invalid ${flag} "${raw}". Use an ISO 8601 date, for example 2026-10-14 or 2026-10-14T09:00:00Z.`);
+      process.exit(1);
+    }
+    dueFilters[key] = String(raw).trim();
+  }
+  const remindStateRaw = parseOption(args, '--remind-state', '');
+  const remindState = remindStateRaw
+    ? remindStateRaw.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean)
+    : [];
+  const unknownStates = remindState.filter((s) => !REMIND_STATES.includes(s));
+  if (unknownStates.length) {
+    warn(`--remind-state must be one of: ${REMIND_STATES.join(', ')} (received ${JSON.stringify(unknownStates)})`);
+    process.exit(1);
+  }
+
   // --path / --hops are validated HERE, where the value is decided, so a typo costs no round
   // trip and the message names the four pathways. The server validates the same way (the shared
   // normalizer in packages/server/src/services/recallParams.service.ts); this is a fast local
@@ -252,6 +279,9 @@ async function runMemoryQuery(args) {
   if (tags.length) body.tags = tags;
   if (tagsAll.length) body.tagsAll = tagsAll;
   if (status.length) body.status = status;
+  if (dueFilters.dueBefore) body.dueBefore = dueFilters.dueBefore;
+  if (dueFilters.dueAfter) body.dueAfter = dueFilters.dueAfter;
+  if (remindState.length) body.remindState = remindState;
   if (path) body.path = path;
   if (hops !== null) body.hops = hops;
 
@@ -490,6 +520,23 @@ async function runMemoryRecord(args) {
     payload.authorType = authorType;
   }
 
+  // --due turns the memory into a reminder. Parsed and rejected HERE as well as server-side, so
+  // a typo fails immediately at the terminal instead of coming back as a 400 after the write was
+  // composed. Accepts anything Date can parse, so '2026-10-14' and a full ISO timestamp both work.
+  const dueRaw = parseOption(args, '--due', '');
+  if (dueRaw) {
+    const parsedDue = new Date(dueRaw);
+    if (Number.isNaN(parsedDue.getTime())) {
+      warn(JSON.stringify({
+        error: true,
+        code: 'invalid_due',
+        message: `Invalid --due "${dueRaw}". Use an ISO 8601 date, for example 2026-10-14 or 2026-10-14T09:00:00Z.`
+      }));
+      process.exit(1);
+    }
+    payload.dueAt = parsedDue.toISOString();
+  }
+
   const accessToken = requireAccessToken();
   const baseUrl = resolveApiBaseUrl();
   const recordUrl = new URL('/api/v1/memories', baseUrl).toString();
@@ -549,6 +596,29 @@ async function runMemoryNote(args) {
   log(JSON.stringify(created));
 }
 
+// Closing a reminder from the terminal or from an agent reading a CLI banner. One PUT, the same
+// transition the portal's Mark done / Cancel make; the server retires the alert on every surface.
+async function runMemoryAcknowledge(args) {
+  const memoryId = parseOption(args, '--memory-id', '');
+  const cancel = parseFlag(args, '--cancel');
+  if (!memoryId) {
+    warn(MEMORY_SUBCOMMAND_USAGE.acknowledge);
+    process.exit(1);
+  }
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL(`/api/v1/memories/${encodeURIComponent(memoryId)}`, baseUrl).toString();
+  let response;
+  try {
+    response = await httpJson(url, 'PUT', { remindState: cancel ? 'cancelled' : 'acknowledged' }, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+  const data = response && response.data ? response.data : response;
+  log(JSON.stringify({ id: data.id, remindState: data.remindState, dueAt: data.dueAt || null, message: cancel ? 'Reminder cancelled. Its slot is free.' : 'Reminder marked done. Its slot is free.' }, null, 2));
+}
+
 async function runMemoryUpdate(args) {
   const match = parseOption(args, '--match', '');
   const patchJson = parseOption(args, '--patch-json', '');
@@ -941,9 +1011,21 @@ async function runMemoryBulkImport(args) {
   const bulkUrl = new URL('/api/v1/memories/bulk', baseUrl).toString();
 
   try {
-    const response = await httpJson(bulkUrl, 'POST', { memories, relationships }, buildApiAuthHeaders(accessToken));
-    const data = (response && response.data) ? response.data : response;
-    log(JSON.stringify(data));
+    const enqueueResponse = await httpJson(bulkUrl, 'POST', { memories, relationships }, buildApiAuthHeaders(accessToken));
+    const { jobId } = (enqueueResponse && enqueueResponse.data) ? enqueueResponse.data : enqueueResponse;
+    const statusUrl = new URL(`/api/v1/memories/bulk/${jobId}`, baseUrl).toString();
+
+    const pollIntervalMs = 3000;
+    const maxPolls = 200;
+    for (let i = 0; i < maxPolls; i += 1) {
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+      const statusResponse = await httpJson(statusUrl, 'GET', undefined, buildApiAuthHeaders(accessToken));
+      const job = (statusResponse && statusResponse.data) ? statusResponse.data : statusResponse;
+      if (job.status === 'succeeded') { log(JSON.stringify(job)); return; }
+      if (job.status === 'failed') { warn(JSON.stringify(job)); process.exit(1); }
+    }
+    warn(JSON.stringify({ error: true, code: 'timeout', message: `Job ${jobId} did not complete within ${(maxPolls * pollIntervalMs) / 1000}s` }));
+    process.exit(1);
   } catch (error) {
     printApiError(error);
     process.exit(1);
@@ -1025,6 +1107,7 @@ async function runMemoryCommand(subArgs) {
       if (sub === 'record') return runMemoryRecord(rest);
       if (sub === 'note') return runMemoryNote(rest);
       if (sub === 'update') return runMemoryUpdate(rest);
+      if (sub === 'acknowledge' || sub === 'ack' || sub === 'done') return runMemoryAcknowledge(rest);
       if (sub === 'delete') return runMemoryDelete(rest);
       if (sub === 'duplicates') return runMemoryDuplicates(rest);
       if (sub === 'merge') return runMemoryMerge(rest);
@@ -1053,6 +1136,7 @@ module.exports = {
   runMemoryRecord,
   runMemoryNote,
   runMemoryUpdate,
+  runMemoryAcknowledge,
   runMemoryDelete,
   runMemoryDuplicates,
   runMemoryMerge,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@empirical-gauzza/cli",
-  "version": "1.0.29",
+  "version": "1.0.30",
   "description": "Persistent cross-tool memory for AI agents. Give Claude Code, Codex, Copilot, Cursor, and ChatGPT one shared memory: save project context once, recall it everywhere via CLI or MCP.",
   "keywords": [
     "memory",