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

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

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

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,17 +34,29 @@ 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] [--author-type user|agent]',
@@ -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));
@@ -353,6 +415,7 @@ 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] [--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;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@empirical-gauzza/cli",
-  "version": "1.0.27",
+  "version": "1.0.28",
   "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",