@empirical-gauzza/cli 1.0.26 → 1.0.28

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

@@ -48,6 +48,8 @@ If you are not sure whether a task qualifies, treat it as if it does.
    Add `--category` or `--tags` when known. Omit `--pretty` for routine recall because graph-rich
    results can be large. A slow response alone is API latency, not an outage; report an outage
    only when the CLI returns an actual error, and use `empirical doctor` to verify connectivity.
+   When the user asks for every record of a topic, add `--path list`; when they ask what a
+   memory connects to, add `--path graph`.
 
 3. Scope recall to the project you are in. Derive a project tag from the repository name
    (`git rev-parse --show-toplevel`, then the folder name) or, outside a repo, the working
@@ -61,6 +63,21 @@ If you are not sure whether a task qualifies, treat it as if it does.
    doc memory`) over a match query. For exhaustive topic retrieval, use the topic as a tag and
    follow pagination.
 
+5. A filtered query (category, tags, nodeType) that returns nothing is not proof the memory
+   doesn't exist — it only proves nothing matched that exact filter combination. A memory's
+   real category or tag convention often does not match how you or the user would naturally
+   describe it in conversation (e.g. described as "an idea" but stored under a different
+   category; tagged with a project's short name where you tried its full one). Before
+   concluding a memory doesn't exist, retry at least once with the filter relaxed or removed —
+   category dropped, tags loosened to an OR match, or a plain unfiltered query — rather than
+   only varying the search phrase.
+
+6. If a specific recall miss turns out to have a narrow, demonstrable cause (a filter mismatch,
+   a stale tag, a wrong category), stop there. Report that cause and move on — do not generalize
+   one miss into a theory about the memory system being broken and then go build measurement or
+   debugging work around the theory. Confirm the narrow cause is insufficient before entertaining
+   a systemic explanation, not after.
+
 ## Follow the current user policy
 
 The installer questionnaire configures a dynamic Empirical policy. It is user-scoped and may
@@ -113,6 +130,13 @@ Two rules that are not optional:
   Both dedupe against near-duplicate existing memories and auto-link related ones by default; pass
   `--no-dedupe` / `--no-auto-link` on the CLI only when you deliberately want to skip one of those.
 
+  **One idea per memory, not a bundle.** When a turn produces several distinct facts or ideas
+  worth keeping, record each as its own call rather than folding them into one large memory.
+  `record_graph_memory` (and `empirical memory record`) can and should be called multiple times
+  in the same turn — that is expected usage, not overhead to be minimized. A compound memory is
+  harder to find later (a query matching one idea in it won't surface the others as well) and
+  harder to link precisely into the graph than several atomic ones.
+
   **Record facts about the USER, not about your own work.** You are a scribe here. "Matt prefers
   short status updates" is a memory; "refactored the cluster selector, tests pass" is your diary
   and belongs in the work-history skill, tagged and with `mass: 1`. The distinction is the
@@ -123,6 +147,18 @@ Two rules that are not optional:
   codebase, stop: that is work-history or scar-tissue, and filing it here makes it indistinguishable
   from something the user actually said or lived. Downstream features read these as the user's life.
 
+  **Say which one it is: pass `authorType`.** Same distinction, made explicit in the data instead
+  of left to be guessed from which transport you happened to use. `authorType: "user"` when the
+  memory is about the user — something they said, decided, prefer, or are working toward.
+  `authorType: "agent"` when it is your own work. Do not set `"agent"` merely because you are the
+  one calling: an agent writing down a real fact about the user is recording a user-authored fact,
+  and that is the whole point of this tool. On the CLI it is `--author-type user|agent`. Omit it
+  when you genuinely cannot tell, and it stays unresolved rather than being invented.
+
+  This is read back at retrieval time to keep an agent's session notes out of answers about the
+  user's own life and work, so a wrong value does not show up as a warning, it shows up as the
+  wrong memories coming back.
+
 - Append a correction or follow-up to an existing memory with `add_note_by_query` / `empirical memory note`.
 - Patch an existing memory with `update_memory_by_query` / `empirical memory update`.
 - Delete only when the user explicitly asks; use the delete tool with confirmation, or `empirical memory delete --match "<memory>" --confirm`.

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

@@ -44,6 +44,8 @@ If you are not sure whether a task qualifies, treat it as if it does.
    Add `--category` or `--tags` when known. Omit `--pretty` for routine recall because graph-rich
    results can be large. Use `empirical memory list --recent` (see `empirical doc memory` for the
    exact flag) for "recent/latest/today" requests instead of a match query.
+   When the user asks for every record of a topic, add `--path list`; when they ask what a
+   memory connects to, add `--path graph`.
 3. Scope recall to the project you are in. Derive a project tag from the repository name
    (`git rev-parse --show-toplevel`, then the folder name) or, outside a repo, the working
    directory name, lowercased with spaces as hyphens. Add `--tags <project>` to every
@@ -52,6 +54,18 @@ If you are not sure whether a task qualifies, treat it as if it does.
    facts about this one.
 4. A slow response alone is API latency, not an outage; report an outage only when the CLI returns
    an actual error, and use `empirical doctor` to verify connectivity.
+5. A filtered query (`--category`, `--tags`, `--tags-all`, `--status`) that returns nothing is not
+   proof the memory doesn't exist — it only proves nothing matched that exact filter combination.
+   A memory's real category or tag convention often does not match how you or the user would
+   naturally describe it in conversation (e.g. described as "an idea" but stored under a different
+   category; tagged with a project's short name where you tried its full one). Before concluding a
+   memory doesn't exist, retry at least once with the filter relaxed or removed — category dropped,
+   tags loosened, or a plain unfiltered `--match` — rather than only varying the search phrase.
+6. If a specific recall miss turns out to have a narrow, demonstrable cause (a filter mismatch, a
+   stale tag, a wrong category), stop there. Report that cause and move on — do not generalize one
+   miss into a theory about the memory system being broken and then go build measurement or
+   debugging work around the theory. Confirm the narrow cause is insufficient before entertaining a
+   systemic explanation, not after.
 
 ## Follow the current user policy
 
@@ -105,6 +119,13 @@ Two rules that are not optional:
   first. Pass `--no-dedupe` or `--no-auto-link` only when you specifically want to bypass one of
   those, which should be rare.
 
+  **One idea per memory, not a bundle.** When a turn produces several distinct facts or ideas
+  worth keeping, record each with its own `empirical memory record` call rather than folding them
+  into one large memory. Calling it multiple times in the same turn is expected usage, not
+  overhead to be minimized. A compound memory is harder to find later (a query matching one idea
+  in it won't surface the others as well) and harder to link precisely into the graph than several
+  atomic ones.
+
   **Record facts about the USER, not about your own work.** You are a scribe here. "Matt prefers
   short status updates" is a memory; "refactored the cluster selector, tests pass" is your diary
   and belongs in the work-history skill, tagged and with `mass: 1`. The distinction is the
@@ -115,6 +136,18 @@ Two rules that are not optional:
   codebase, stop: that is work-history or scar-tissue, and filing it here makes it indistinguishable
   from something the user actually said or lived. Downstream features read these as the user's life.
 
+  **Say which one it is: pass `authorType`.** Same distinction, made explicit in the data instead
+  of left to be guessed from which transport you happened to use. `authorType: "user"` when the
+  memory is about the user — something they said, decided, prefer, or are working toward.
+  `authorType: "agent"` when it is your own work. Do not set `"agent"` merely because you are the
+  one calling: an agent writing down a real fact about the user is recording a user-authored fact,
+  and that is the whole point of this tool. On the CLI it is `--author-type user|agent`. Omit it
+  when you genuinely cannot tell, and it stays unresolved rather than being invented.
+
+  This is read back at retrieval time to keep an agent's session notes out of answers about the
+  user's own life and work, so a wrong value does not show up as a warning, it shows up as the
+  wrong memories coming back.
+
 - Append a correction or follow-up to an existing memory with `empirical memory note`.
 - Patch an existing memory with `empirical memory update`.
 - Delete only when the user explicitly asks: `empirical memory delete --match "<memory>" --confirm`.

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

@@ -39,9 +39,24 @@ If you are not sure whether a task qualifies, treat it as if it does.
    `nodeType`, and `monthKey` when they improve recall. For "recent/latest/today" requests, prefer
    `list_memories` instead — it is the tool built for that shape of request. For exhaustive topic
    retrieval, use the topic as a tag and follow pagination.
+   When the user asks for every record of a topic use `list_memories` with that topic as a tag,
+   and when they ask what a memory connects to use `get_memory_neighbors`.
 5. A slow response alone is API latency, not an outage; report an outage only when a tool call
    returns an actual error, and use `get_empirical_policy` or a retry to verify connectivity before
    escalating.
+6. A filtered `query_memories` call (`category`, `tags`, `nodeType`) that returns nothing is not
+   proof the memory doesn't exist — it only proves nothing matched that exact filter combination.
+   A memory's real category or tag convention often does not match how you or the user would
+   naturally describe it in conversation (e.g. described as "an idea" but stored under a
+   different category; tagged with a project's short name where you tried its full one). Before
+   concluding a memory doesn't exist, retry at least once with the filter relaxed or removed —
+   category dropped, tags loosened to an OR match, or a plain unfiltered query — rather than only
+   varying the search phrase.
+7. If a specific recall miss turns out to have a narrow, demonstrable cause (a filter mismatch, a
+   stale tag, a wrong category), stop there. Report that cause and move on — do not generalize one
+   miss into a theory about the memory system being broken and then go build measurement or
+   debugging work around the theory. Confirm the narrow cause is insufficient before entertaining a
+   systemic explanation, not after.
 
 ## Follow the current user policy
 
@@ -82,6 +97,13 @@ Two rules that are not optional:
   with the `record_graph_memory` MCP tool. It runs write-intent classification, dedupe, and
   auto-linking automatically — you do not need to check for duplicates yourself first.
 
+  **One idea per memory, not a bundle.** When a turn produces several distinct facts or ideas
+  worth keeping, record each with its own `record_graph_memory` call rather than folding them
+  into one large memory. Calling it multiple times in the same turn is expected usage, not
+  overhead to be minimized. A compound memory is harder to find later (a query matching one idea
+  in it won't surface the others as well) and harder to link precisely into the graph than several
+  atomic ones.
+
   **Record facts about the USER, not about your own work.** You are a scribe here. "Matt prefers
   short status updates" is a memory; "refactored the cluster selector, tests pass" is your diary
   and belongs in the work-history skill, tagged and with `mass: 1`. The distinction is the
@@ -92,6 +114,18 @@ Two rules that are not optional:
   codebase, stop: that is work-history or scar-tissue, and filing it here makes it indistinguishable
   from something the user actually said or lived. Downstream features read these as the user's life.
 
+  **Say which one it is: pass `authorType`.** Same distinction, made explicit in the data instead
+  of left to be guessed from which transport you happened to use. `authorType: "user"` when the
+  memory is about the user — something they said, decided, prefer, or are working toward.
+  `authorType: "agent"` when it is your own work. Do not set `"agent"` merely because you are the
+  one calling: an agent writing down a real fact about the user is recording a user-authored fact,
+  and that is the whole point of this tool. On the CLI it is `--author-type user|agent`. Omit it
+  when you genuinely cannot tell, and it stays unresolved rather than being invented.
+
+  This is read back at retrieval time to keep an agent's session notes out of answers about the
+  user's own life and work, so a wrong value does not show up as a warning, it shows up as the
+  wrong memories coming back.
+
 - Append a correction or follow-up to an existing memory with `add_note_by_query`.
 - Patch an existing memory with `update_memory_by_query`.
 - Delete only when the user explicitly asks; use `delete_memory_by_query` with confirmation.

package/lib/memoryCommands.js

@@ -6,7 +6,7 @@ const { log, warn } = require('./ui');
 const { httpJson, printApiError } = require('./http');
 const { parseOption, parseFlag } = require('./env');
 const { requireAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
-const { MEMORY_CATEGORIES, DOC_TOPICS } = require('./constants');
+const { MEMORY_CATEGORIES, NODE_TYPES, DOC_TOPICS } = require('./constants');
 const { withSelectedWorkspaceContext } = require('./workspaceContext');
 
 // ─── Table rendering (--format table) ─────────────────────────────────────────
@@ -34,20 +34,32 @@ function renderMemoryResultsTable(items) {
     id: m.id || m._id || '',
     category: m.category || '',
     summary: truncateForTable(m.summary, 60),
-    score: m.rankScore != null ? m.rankScore : (m.similarityScore != null ? m.similarityScore : '')
+    // The recall front door emits `score` (toQueryRow plus score in mcp/tools/memory.ts); the
+    // older /query route emitted rankScore/similarityScore. Read all three so the column is not
+    // blank against a real /recall row. On the list pathways score is deliberately absent, and
+    // an empty cell is the honest rendering of "this pathway does not rank".
+    score: m.score != null ? m.score : (m.rankScore != null ? m.rankScore : (m.similarityScore != null ? m.similarityScore : ''))
   }));
   return renderTable(rows, ['id', 'category', 'summary', 'score']);
 }
 
+// The retrieval pathways `memory query --path` may pin. Same four names the server's shared
+// normalizer accepts (packages/server/src/services/recallParams.service.ts). Omitting --path
+// leaves the classifier deciding, exactly as before.
+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'];
+
 // ─── 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>] [--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>] [--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]',
+  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]',
   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',
@@ -179,7 +191,7 @@ function printMemoryResolveError(result) {
 async function runMemoryQuery(args) {
   const match = parseOption(args, '--match', '');
   if (!match) {
-    warn('Usage: empirical memory query --match <query> [--top-k 3] [--category <cat>] [--tags <t1,t2>] [--tags-all <t1,t2>] [--status <s1,s2>] [--pretty]');
+    warn(MEMORY_SUBCOMMAND_USAGE.query);
     process.exit(1);
   }
 
@@ -197,29 +209,79 @@ async function runMemoryQuery(args) {
   const pretty = parseFlag(args, '--pretty');
   const format = parseOption(args, '--format', 'json');
 
+  // --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
+  // echo of that contract, never a second, looser one.
+  const pathRaw = parseOption(args, '--path', '');
+  let path = '';
+  if (pathRaw) {
+    path = String(pathRaw).trim().toLowerCase();
+    if (!RECALL_PATHS.includes(path)) {
+      warn(`--path must be one of: ${RECALL_PATHS.join(', ')} (received ${JSON.stringify(pathRaw)})`);
+      process.exit(1);
+    }
+  }
+
+  const hopsRaw = parseOption(args, '--hops', '');
+  let hops = null;
+  if (hopsRaw) {
+    const parsedHops = Number(hopsRaw);
+    if (!RECALL_HOPS.includes(parsedHops)) {
+      warn(`--hops must be 1 or 2 (received ${JSON.stringify(hopsRaw)})`);
+      process.exit(1);
+    }
+    // Silently ignoring --hops on a ranked or list pathway would look like it took effect.
+    if (!RECALL_HOP_PATHS.includes(path)) {
+      warn(`--hops only applies with --path graph or --path hebbian${path ? ` (received --path ${path})` : ' (no --path given)'}`);
+      process.exit(1);
+    }
+    hops = parsedHops;
+  }
+
   const accessToken = requireAccessToken();
   const baseUrl = resolveApiBaseUrl();
-  const queryUrl = new URL('/api/v1/memories/query', baseUrl).toString();
+  // The recall front door: the same answer the MCP query_memories tool gives, which /query never
+  // gave (classifier routing, the list block, the exact-tag retry, agent-note exclusion,
+  // retrievalPath). It takes its parameters FLAT, matching the shared normalizer, not nested
+  // under `filters` the way the older /query route did. Send one shape only.
+  const queryUrl = new URL('/api/v1/memories/recall', baseUrl).toString();
 
   const body = { query: match, topK };
-  const filters = {};
-  if (category) filters.category = category;
-  if (tags.length) filters.tags = tags;
-  if (tagsAll.length) filters.tagsAll = tagsAll;
-  if (status.length) filters.status = status;
-  if (Object.keys(filters).length) body.filters = filters;
+  if (category) body.category = category;
+  if (tags.length) body.tags = tags;
+  if (tagsAll.length) body.tagsAll = tagsAll;
+  if (status.length) body.status = status;
+  if (path) body.path = path;
+  if (hops !== null) body.hops = hops;
 
   let response;
   try {
     response = await httpJson(queryUrl, 'POST', body, buildApiAuthHeaders(accessToken));
   } catch (error) {
+    // A 404 here means the server predates the recall front door. Say that plainly instead of
+    // rerouting to /query: that fallback would quietly answer through a different routing path
+    // with different defaults (topK 10 against 3) and keep the old route alive forever.
+    if (error && error.statusCode === 404) {
+      warn(JSON.stringify({
+        error: true,
+        code: 'recall_route_missing',
+        message: 'This server does not serve /api/v1/memories/recall yet. Upgrade the Empirical server, or use an older CLI against it.'
+      }));
+      process.exit(1);
+    }
     printApiError(error);
     process.exit(1);
   }
 
-  const results = (response && response.data && Array.isArray(response.data.results))
-    ? response.data.results
-    : (Array.isArray(response) ? response : []);
+  // The front door answers with data.memories; the older /query route answered with data.results.
+  // Both are accepted so a CLI pointed at a server that predates /recall still prints rows.
+  const data = response && response.data ? response.data : null;
+  const results = (data && Array.isArray(data.memories))
+    ? data.memories
+    : ((data && Array.isArray(data.results))
+      ? data.results
+      : (Array.isArray(response) ? response : []));
 
   if (format === 'table') {
     log(renderMemoryResultsTable(results));
@@ -351,8 +413,9 @@ async function runMemoryRecord(args) {
     }
 
     if (!category || !summary) {
-      warn('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]');
+      warn('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]');
       warn('Valid categories: ' + MEMORY_CATEGORIES.join(', '));
+      warn('Valid node types: ' + NODE_TYPES.join(', '));
       process.exit(1);
     }
 
@@ -369,6 +432,15 @@ async function runMemoryRecord(args) {
     const tags = tagsRaw ? tagsRaw.split(',').map((t) => t.trim()).filter(Boolean) : [];
     const nodeType = parseOption(args, '--node-type', 'observation');
 
+    if (!NODE_TYPES.includes(nodeType)) {
+      warn(JSON.stringify({
+        error: true,
+        code: 'invalid_node_type',
+        message: `Invalid nodeType "${nodeType}". Valid: ${NODE_TYPES.join(', ')}`
+      }));
+      process.exit(1);
+    }
+
     payload = { category, summary, nodeType, data: { text: String(summary) } };
     if (tags.length) payload.tags = tags;
   }
@@ -395,6 +467,29 @@ async function runMemoryRecord(args) {
     payload.autoLink = false;
   }
 
+  // Authorship (2026-09-09). `source` is observable truth: this is the CLI, so say so.
+  // Until now the CLI sent nothing, the server fell back to the transport it saw ('api'),
+  // and api maps to authorType 'user' because that mapping was written for the web portal.
+  // Every agent write through this command was therefore stored as authored by the user.
+  // 'cli' resolves to authorType 'unknown', which is the honest answer when nobody says.
+  if (payload.source === undefined) payload.source = 'cli';
+
+  // --author-type lets the caller state what the transport cannot know. An agent recording
+  // its own session notes should pass 'agent'; an agent recording something the user said
+  // or decided should pass 'user'. Omitted, it stays 'unknown' rather than being guessed.
+  const authorType = parseOption(args, '--author-type', '');
+  if (authorType) {
+    if (!['user', 'agent', 'system'].includes(authorType)) {
+      warn(JSON.stringify({
+        error: true,
+        code: 'invalid_author_type',
+        message: `Invalid --author-type "${authorType}". Valid: user, agent, system`
+      }));
+      process.exit(1);
+    }
+    payload.authorType = authorType;
+  }
+
   const accessToken = requireAccessToken();
   const baseUrl = resolveApiBaseUrl();
   const recordUrl = new URL('/api/v1/memories', baseUrl).toString();