@empirical-gauzza/cli 1.0.22 → 1.0.24

package/README.md

@@ -1,63 +1,63 @@
-# @empirical-gauzza/cli
-
-Command-line installer and local MCP wiring helper for [Empirical](https://empirical.gauzza.com) — portable memory infrastructure for AI agents, assistants, and coding tools.
-
-Full documentation: **[empirical.gauzza.com/docs/cli-details](https://empirical.gauzza.com/docs/cli-details)**
-
-## Install
-
-```bash
-npm install -g @empirical-gauzza/cli
-```
-
-## Quick start
-
-```bash
-empirical install       # interactive setup for Claude Code, Codex, or Copilot CLI
-empirical auth login    # browser-based OAuth login
-empirical doctor        # verify token, API connectivity, and workspace status
-```
-
-Full walkthrough: [empirical.gauzza.com/docs/install](https://empirical.gauzza.com/docs/install)
-
-## What it does
-
-- Installs and configures the Empirical MCP plugin for supported coding agents (Claude Code, Codex CLI, Copilot CLI)
-- Manages OAuth login, including headless/CI bootstrap and Docker token flows
-- Reads, writes, and maintains memories from the command line
-- Manages Skills Kits — create, sync, and push authored Skills across machines
-- Manages workspaces, invites, and registered devices
-- Exposes agent-readable docs and a connectivity `doctor` check
-
-## Commands
-
-| Command | Docs |
-| --- | --- |
-| `empirical install` | [/docs/install](https://empirical.gauzza.com/docs/install#connect) |
-| `empirical plugin install / check` | [/docs/cli-plugins](https://empirical.gauzza.com/docs/cli-plugins) |
-| `empirical auth login / logout` | [/docs/cli-auth](https://empirical.gauzza.com/docs/cli-auth) |
-| `empirical oauth bootstrap / refresh` | [/docs/cli-oauth](https://empirical.gauzza.com/docs/cli-oauth) |
-| `empirical policy show / set` | [/docs/cli-policy](https://empirical.gauzza.com/docs/cli-policy) |
-| `empirical memory query / record / update / delete / export ...` | [/docs/cli-memory](https://empirical.gauzza.com/docs/cli-memory) |
-| `empirical workspace list / create / invite ...` | [/docs/cli-workspaces](https://empirical.gauzza.com/docs/cli-workspaces) |
-| `empirical kit create / sync / use ...` | [/docs/cli-kit](https://empirical.gauzza.com/docs/cli-kit) |
-| `empirical skill push / history / rollback` | [/docs/cli-skill](https://empirical.gauzza.com/docs/cli-skill) |
-| `empirical device list / show` | [/docs/cli-devices](https://empirical.gauzza.com/docs/cli-devices) |
-| `empirical doc [topic]` | [/docs/cli-doc-command](https://empirical.gauzza.com/docs/cli-doc-command) |
-| `empirical doctor` | [/docs/cli-doctor](https://empirical.gauzza.com/docs/cli-doctor) |
-
-Run `empirical --help` at any time for the full, current command list, or `empirical doc` for agent-readable topic docs.
-
-## Security model
-
-API keys and OAuth tokens are stored locally and are never printed in full after initial issuance. See [empirical.gauzza.com/docs/security-model](https://empirical.gauzza.com/docs/security-model) for details on credential handling and headless/CI usage.
-
-## Links
-
-- [Documentation](https://empirical.gauzza.com/docs/install)
-- [Homepage](https://empirical.gauzza.com)
-- [Support](https://empirical.gauzza.com/support/)
-
-## License
-
-MIT
+# @empirical-gauzza/cli
+
+Command-line installer and local MCP wiring helper for [Empirical](https://empirical.gauzza.com) — portable memory infrastructure for AI agents, assistants, and coding tools.
+
+Full documentation: **[empirical.gauzza.com/docs/cli-details](https://empirical.gauzza.com/docs/cli-details)**
+
+## Install
+
+```bash
+npm install -g @empirical-gauzza/cli
+```
+
+## Quick start
+
+```bash
+empirical install       # interactive setup for Claude Code, Codex, or Copilot CLI
+empirical auth login    # browser-based OAuth login
+empirical doctor        # verify token, API connectivity, and workspace status
+```
+
+Full walkthrough: [empirical.gauzza.com/docs/install](https://empirical.gauzza.com/docs/install)
+
+## What it does
+
+- Installs and configures the Empirical MCP plugin for supported coding agents (Claude Code, Codex CLI, Copilot CLI)
+- Manages OAuth login, including headless/CI bootstrap and Docker token flows
+- Reads, writes, and maintains memories from the command line
+- Manages Skills Kits — create, sync, and push authored Skills across machines
+- Manages workspaces, invites, and registered devices
+- Exposes agent-readable docs and a connectivity `doctor` check
+
+## Commands
+
+| Command | Docs |
+| --- | --- |
+| `empirical install` | [/docs/install](https://empirical.gauzza.com/docs/install#connect) |
+| `empirical plugin install / check` | [/docs/cli-plugins](https://empirical.gauzza.com/docs/cli-plugins) |
+| `empirical auth login / logout` | [/docs/cli-auth](https://empirical.gauzza.com/docs/cli-auth) |
+| `empirical oauth bootstrap / refresh` | [/docs/cli-oauth](https://empirical.gauzza.com/docs/cli-oauth) |
+| `empirical policy show / set` | [/docs/cli-policy](https://empirical.gauzza.com/docs/cli-policy) |
+| `empirical memory query / record / update / delete / export ...` | [/docs/cli-memory](https://empirical.gauzza.com/docs/cli-memory) |
+| `empirical workspace list / create / invite ...` | [/docs/cli-workspaces](https://empirical.gauzza.com/docs/cli-workspaces) |
+| `empirical kit create / sync / use ...` | [/docs/cli-kit](https://empirical.gauzza.com/docs/cli-kit) |
+| `empirical skill push / history / rollback` | [/docs/cli-skill](https://empirical.gauzza.com/docs/cli-skill) |
+| `empirical device list / show` | [/docs/cli-devices](https://empirical.gauzza.com/docs/cli-devices) |
+| `empirical doc [topic]` | [/docs/cli-doc-command](https://empirical.gauzza.com/docs/cli-doc-command) |
+| `empirical doctor` | [/docs/cli-doctor](https://empirical.gauzza.com/docs/cli-doctor) |
+
+Run `empirical --help` at any time for the full, current command list, or `empirical doc` for agent-readable topic docs.
+
+## Security model
+
+API keys and OAuth tokens are stored locally and are never printed in full after initial issuance. See [empirical.gauzza.com/docs/security-model](https://empirical.gauzza.com/docs/security-model) for details on credential handling and headless/CI usage.
+
+## Links
+
+- [Documentation](https://empirical.gauzza.com/docs/install)
+- [Homepage](https://empirical.gauzza.com)
+- [Support](https://empirical.gauzza.com/support/)
+
+## License
+
+MIT

package/bin/empirical.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 'use strict';
 

package/lib/constants.js

@@ -60,9 +60,22 @@ Save a new memory.
 
     empirical memory record --category build --summary "Use ESM modules for all new packages" [--tags ts,node] [--node-type observation]
 
+Passing text that contains code (backticks, \${...}, $(...)): do NOT put it in a double-quoted
+\`--summary "..."\` -- the shell substitutes those away before the CLI runs and the write still
+succeeds with the code silently missing. Use one of:
+
+    empirical memory record --category build --summary-file ./note.md --tags ts
+    empirical memory record --category build --summary - --tags ts <<'EOF'
+    Use \`createChat()\`; raw calls leak \${stage} and 400.
+    EOF
+
+(a single-quoted heredoc delimiter, 'EOF', disables substitution). From an MCP-connected agent,
+prefer the record_graph_memory tool, which takes JSON and never touches a shell.
+
 Flags:
 - \`--category\` (required unless --json-file): memory category
-- \`--summary\` (required unless --json-file): memory summary text
+- \`--summary\` (required unless --summary-file/--json-file): memory summary text; \`-\` reads stdin
+- \`--summary-file\`: path to a file whose contents become the summary (safe for code)
 - \`--tags\`: comma-separated tags
 - \`--node-type\`: node type, default \`observation\`
 - \`--json-file\`: path to JSON file with full memory payload

package/lib/doc.js

@@ -11,7 +11,7 @@ function runDoc(args) {
     user: 'Get current user identity (MCP: get_user; CLI: doctor --output json)',
     workspace: 'List, view, and switch workspaces',
     doctor: 'Check token, connectivity, and workspace health',
-    agents: 'Supported agents, integration modes, and native plugin setup',
+    agents: 'Supported agents, integration modes, and native plugin setup',
     auth: 'Token types, bootstrap, refresh, resolution order',
     install: 'Install Empirical for Codex / Copilot / Claude Code',
     kit: 'Create, source, activate, and sync Skills Kits',

package/lib/env.js

@@ -1,49 +1,49 @@
-'use strict';
-
-const { ask } = require('./ui');
-
-function getEnv(name, fallback = '') {
-  return String(process.env[name] ?? fallback).trim();
-}
-
-function requireEnv(name) {
-  const value = getEnv(name);
-  if (!value) {
-    throw new Error(`Missing required env var: ${name}`);
-  }
-  return value;
-}
-
-async function resolveRequiredValueFromEnvOrPrompt(envName, promptLabel) {
-  const value = getEnv(envName);
-  if (value) return value;
-
-  if (!process.stdin.isTTY) {
-    throw new Error(`Missing required env var: ${envName}`);
-  }
-
-  const answer = (await ask(`${promptLabel}: `)).trim();
-  if (!answer) {
-    throw new Error(`${promptLabel} is required`);
-  }
-
-  return answer;
-}
-
-function parseFlag(args, flagName) {
-  return args.includes(flagName);
-}
-
-function parseOption(args, optionName, fallback = '') {
-  const index = args.indexOf(optionName);
-  if (index === -1) return fallback;
-  return String(args[index + 1] || '').trim() || fallback;
-}
-
-module.exports = {
-  getEnv,
-  requireEnv,
-  resolveRequiredValueFromEnvOrPrompt,
-  parseFlag,
-  parseOption
-};
+'use strict';
+
+const { ask } = require('./ui');
+
+function getEnv(name, fallback = '') {
+  return String(process.env[name] ?? fallback).trim();
+}
+
+function requireEnv(name) {
+  const value = getEnv(name);
+  if (!value) {
+    throw new Error(`Missing required env var: ${name}`);
+  }
+  return value;
+}
+
+async function resolveRequiredValueFromEnvOrPrompt(envName, promptLabel) {
+  const value = getEnv(envName);
+  if (value) return value;
+
+  if (!process.stdin.isTTY) {
+    throw new Error(`Missing required env var: ${envName}`);
+  }
+
+  const answer = (await ask(`${promptLabel}: `)).trim();
+  if (!answer) {
+    throw new Error(`${promptLabel} is required`);
+  }
+
+  return answer;
+}
+
+function parseFlag(args, flagName) {
+  return args.includes(flagName);
+}
+
+function parseOption(args, optionName, fallback = '') {
+  const index = args.indexOf(optionName);
+  if (index === -1) return fallback;
+  return String(args[index + 1] || '').trim() || fallback;
+}
+
+module.exports = {
+  getEnv,
+  requireEnv,
+  resolveRequiredValueFromEnvOrPrompt,
+  parseFlag,
+  parseOption
+};

package/lib/installers/detect.js

@@ -1,47 +1,47 @@
-'use strict';
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { commandExists } = require('../fsUtils');
-const { installCodex } = require('./codex');
-const { installCopilot } = require('./copilot');
-const { installClaude } = require('./claude');
-
-function detectInstallTargets() {
-  const home = os.homedir();
-  const targets = [];
-
-  const codexDetected = commandExists('codex') || fs.existsSync(path.join(home, '.codex'));
-  if (codexDetected) {
-    targets.push({
-      id: 'codex',
-      label: 'Codex CLI',
-      install: installCodex
-    });
-  }
-
-  const copilotDetected = commandExists('copilot') || fs.existsSync(path.join(home, '.copilot'));
-  if (copilotDetected) {
-    targets.push({
-      id: 'copilot',
-      label: 'GitHub Copilot CLI',
-      install: installCopilot
-    });
-  }
-
-  const claudeDetected = commandExists('claude') || fs.existsSync(path.join(home, '.claude'));
-  if (claudeDetected) {
-    targets.push({
-      id: 'claude',
-      label: 'Claude CLI',
-      install: installClaude
-    });
-  }
-
-  return targets;
-}
-
-module.exports = {
-  detectInstallTargets
-};
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { commandExists } = require('../fsUtils');
+const { installCodex } = require('./codex');
+const { installCopilot } = require('./copilot');
+const { installClaude } = require('./claude');
+
+function detectInstallTargets() {
+  const home = os.homedir();
+  const targets = [];
+
+  const codexDetected = commandExists('codex') || fs.existsSync(path.join(home, '.codex'));
+  if (codexDetected) {
+    targets.push({
+      id: 'codex',
+      label: 'Codex CLI',
+      install: installCodex
+    });
+  }
+
+  const copilotDetected = commandExists('copilot') || fs.existsSync(path.join(home, '.copilot'));
+  if (copilotDetected) {
+    targets.push({
+      id: 'copilot',
+      label: 'GitHub Copilot CLI',
+      install: installCopilot
+    });
+  }
+
+  const claudeDetected = commandExists('claude') || fs.existsSync(path.join(home, '.claude'));
+  if (claudeDetected) {
+    targets.push({
+      id: 'claude',
+      label: 'Claude CLI',
+      install: installClaude
+    });
+  }
+
+  return targets;
+}
+
+module.exports = {
+  detectInstallTargets
+};

package/lib/installers/hooks.js

@@ -477,7 +477,7 @@ function main() {
   appendLog('stop hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
 
   console.log(JSON.stringify({
-    systemMessage: '[Empirical reminder] Before finishing: if this turn included a completed decision, a corrected mistake, or meaningful work worth remembering, record it now via the empirical-memory skill or \`empirical memory record\` - do not wait to be asked.'
+    systemMessage: '[Empirical reminder] Before finishing: if this turn included a completed decision, a corrected mistake, or meaningful work worth remembering, record it now, one memory per finding (a fix, a root cause, a decision, a lesson), via the empirical-memory, empirical-work-history, or empirical-scar-tissue skill or \`empirical memory record\`. Local notes are not recorded. Do not wait to be asked.'
   }));
   process.exit(0);
 }
@@ -545,7 +545,7 @@ function main() {
 
   console.log(JSON.stringify({
     decision: 'block',
-    reason: '[Empirical reminder] Before finishing: if this turn included a completed decision, a corrected mistake, or meaningful work worth remembering, record it now via the empirical-memory skill or \`empirical memory record\` - do not wait to be asked.'
+    reason: '[Empirical reminder] Before finishing: if this turn included a completed decision, a corrected mistake, or meaningful work worth remembering, record it now, one memory per finding (a fix, a root cause, a decision, a lesson), via the empirical-memory, empirical-work-history, or empirical-scar-tissue skill or \`empirical memory record\`. Local notes are not recorded. Do not wait to be asked.'
   }));
   process.exit(0);
 }
@@ -618,7 +618,7 @@ function main() {
   process.stdout.write(JSON.stringify({
     hookSpecificOutput: {
       hookEventName: 'Stop',
-      additionalContext: '[Empirical] Record memory-worthy work now via empirical-memory skill.'
+      additionalContext: '[Empirical] Record memory-worthy work now: one memory per finding (a fix, a root cause, a decision, a lesson) via the empirical-memory, empirical-work-history, or empirical-scar-tissue skill. Local notes are not recorded.'
     }
   }) + '\\n');
   process.exit(0);

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

@@ -49,7 +49,13 @@ If you are not sure whether a task qualifies, treat it as if it does.
    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.
 
-3. If the CLI is unavailable, use the connected MCP `query_memories` tool. Use filters such as
+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. Pass it as `tags: ["<project>"]` on every
+   `query_memories` call and add it to `tags` on every `record_graph_memory` call. If a scoped
+   query comes back with a `retrievalNote`, nothing from this project matched: the results are
+   from other projects, so use them as background only and say so if you rely on one.
+4. If the CLI is unavailable, use the connected MCP `query_memories` tool. Use filters such as
    `category`, `tags`, `nodeType`, and `monthKey` when they improve recall. For "recent/latest/
    today" requests, prefer `list_memories` (CLI: `empirical memory list --recent`, see `empirical
    doc memory`) over a match query. For exhaustive topic retrieval, use the topic as a tag and
@@ -86,6 +92,11 @@ mistake, a completed unit of meaningful work, or a convention the user stated? I
 now — do not wait to be asked, and do not defer it because the current task feels done. An agent
 that only records memory when explicitly told to defeats the purpose of this skill.
 
+Two rules that are not optional:
+
+- Record one memory per finding. A session that fixed three things records three memories, each with the fix phrase and the date in its summary. One combined summary is not recorded: it cannot be found by any question about one of its parts.
+- Empirical first. A note in a local file, a scratchpad, or a host memory directory is not recorded; it is invisible to every other session, tool, and agent. Record in Empirical, then keep a local pointer if you want one.
+
 - Record durable decisions, project conventions, preferences, plans, and meaningful reflections
   with `record_graph_memory` or:
 
@@ -93,6 +104,11 @@ that only records memory when explicitly told to defeats the purpose of this ski
   empirical memory record --category <category> --summary "<concise fact>" --tags <tag1,tag2>
   ```
 
+  **Code in the summary?** Never pass backticks or `${...}` inside a double-quoted `--summary`; the
+  shell substitutes them away before the CLI runs and the write still succeeds with the code gone.
+  Use `--summary-file <path>`, or `--summary -` with a single-quoted heredoc (`<<'EOF'`), or the MCP
+  `record_graph_memory` tool, which takes JSON and never touches a shell.
+
   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.
 

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

@@ -44,7 +44,13 @@ 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.
-3. A slow response alone is API latency, not an outage; report an outage only when the CLI returns
+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
+   `empirical memory query` and `empirical memory record`. If a scoped query returns nothing,
+   retry without `--tags` and treat what comes back as background from other projects, not as
+   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.
 
 ## Follow the current user policy
@@ -76,6 +82,11 @@ mistake, a completed unit of meaningful work, or a convention the user stated? I
 now — do not wait to be asked, and do not defer it because the current task feels done. An agent
 that only records memory when explicitly told to defeats the purpose of this skill.
 
+Two rules that are not optional:
+
+- Record one memory per finding. A session that fixed three things records three memories, each with the fix phrase and the date in its summary. One combined summary is not recorded: it cannot be found by any question about one of its parts.
+- Empirical first. A note in a local file, a scratchpad, or a host memory directory is not recorded; it is invisible to every other session, tool, and agent. Record in Empirical, then keep a local pointer if you want one.
+
 - Record durable decisions, project conventions, preferences, plans, and meaningful reflections
   with:
 
@@ -83,6 +94,11 @@ that only records memory when explicitly told to defeats the purpose of this ski
   empirical memory record --category <category> --summary "<concise fact>" --tags <tag1,tag2>
   ```
 
+  **Code in the summary?** Never pass backticks or `${...}` inside a double-quoted `--summary`; the
+  shell substitutes them away before the CLI runs and the write still succeeds with the code gone.
+  Use `--summary-file <path>`, or `--summary -` with a single-quoted heredoc (`<<'EOF'`), or the MCP
+  `record_graph_memory` tool, which takes JSON and never touches a shell.
+
   This command dedupes against near-duplicate existing memories and auto-links related ones by
   default, the same as any other Empirical client — you do not need a separate duplicate check
   first. Pass `--no-dedupe` or `--no-auto-link` only when you specifically want to bypass one of

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

@@ -29,11 +29,17 @@ If you are not sure whether a task qualifies, treat it as if it does.
    ("query when it seems useful") the right frame.
 2. If you have not used Empirical's MCP tools yet this session, call `memory_usage_guide` once to
    confirm current tool names, filters, and pagination behavior before relying on memory.
-3. Use the `query_memories` MCP tool for recall. Use filters such as `category`, `tags`,
+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. Pass it as `tags: ["<project>"]` on every
+   `query_memories` call and add it to `tags` on every `record_graph_memory` call. If a scoped
+   query comes back with a `retrievalNote`, nothing from this project matched: the results are
+   from other projects, so use them as background only and say so if you rely on one.
+4. Use the `query_memories` MCP tool for recall. Use filters such as `category`, `tags`,
    `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.
-4. A slow response alone is API latency, not an outage; report an outage only when a tool call
+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.
 
@@ -66,6 +72,11 @@ mistake, a completed unit of meaningful work, or a convention the user stated? I
 now — do not wait to be asked, and do not defer it because the current task feels done. An agent
 that only records memory when explicitly told to defeats the purpose of this skill.
 
+Two rules that are not optional:
+
+- Record one memory per finding. A session that fixed three things records three memories, each with the fix phrase and the date in its summary. One combined summary is not recorded: it cannot be found by any question about one of its parts.
+- Empirical first. A note in a local file, a scratchpad, or a host memory directory is not recorded; it is invisible to every other session, tool, and agent. Record in Empirical, then keep a local pointer if you want one.
+
 - Record durable decisions, project conventions, preferences, plans, and meaningful reflections
   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.

package/lib/memoryCommands.js

@@ -47,7 +47,7 @@ const MEMORY_SUBCOMMAND_USAGE = {
   query: 'Usage: empirical memory query --match <query> [--top-k 3] [--category <cat>] [--tags <t1,t2>] [--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> [--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]',
   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',
@@ -290,6 +290,33 @@ async function runMemoryList(args) {
   log(pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data));
 }
 
+// Shell substitution silently eats code out of a double-quoted --summary: backticks become
+// command substitution and ${...} becomes variable expansion BEFORE the CLI ever sees the
+// text, and the write still succeeds, so the memory looks fine with the code gone. Two
+// defenses: (1) inputs that never pass through shell quoting -- `--summary-file <path>` and
+// `--summary -` (stdin, pair it with a single-quoted heredoc); (2) a warning when an inline
+// summary carries the residue of an eaten substitution.
+function resolveSummaryInput(args, { readFile = (p) => fs.readFileSync(path.resolve(p), 'utf8'), readStdin = () => fs.readFileSync(0, 'utf8') } = {}) {
+  const summaryFile = parseOption(args, '--summary-file', '');
+  if (summaryFile) {
+    return { summary: String(readFile(summaryFile)).replace(/\r?\n$/, ''), source: 'file' };
+  }
+  const inline = parseOption(args, '--summary', '');
+  if (inline === '-') {
+    return { summary: String(readStdin()).replace(/\r?\n$/, ''), source: 'stdin' };
+  }
+  return { summary: inline, source: inline ? 'inline' : 'none' };
+}
+
+function detectShellMangling(summary) {
+  const text = String(summary || '');
+  const reasons = [];
+  if (/``/.test(text)) reasons.push('an empty backtick pair (a `command` was probably substituted away)');
+  if (/\$(\s|$|[^A-Za-z0-9_{(])/.test(text) && !/\$\d/.test(text)) reasons.push('a lone "$" (a ${VAR} or $(cmd) was probably expanded to nothing)');
+  if (/\$\{\s*\}/.test(text)) reasons.push('an empty ${} placeholder');
+  return reasons;
+}
+
 async function runMemoryRecord(args) {
   const jsonFile = parseOption(args, '--json-file', '');
   let payload;
@@ -303,10 +330,20 @@ async function runMemoryRecord(args) {
     }
   } else {
     const category = parseOption(args, '--category', '');
-    const summary = parseOption(args, '--summary', '');
+    const { summary, source: summarySource } = resolveSummaryInput(args);
+
+    if (summarySource === 'inline') {
+      const mangled = detectShellMangling(summary);
+      if (mangled.length) {
+        warn(JSON.stringify({
+          warning: 'possible_shell_substitution',
+          message: 'The summary looks like the shell altered it before the CLI saw it: ' + mangled.join('; ') + '. Recording anyway. For text containing backticks or ${...}, use --summary-file <path>, or --summary - with a single-quoted heredoc, or the MCP record_graph_memory tool.'
+        }));
+      }
+    }
 
     if (!category || !summary) {
-      warn('Usage: empirical memory record --category <cat> --summary <text> [--tags t1,t2] [--node-type observation] [--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]');
       warn('Valid categories: ' + MEMORY_CATEGORIES.join(', '));
       process.exit(1);
     }
@@ -902,6 +939,8 @@ async function runMemoryCommand(subArgs) {
 }
 
 module.exports = {
+  resolveSummaryInput,
+  detectShellMangling,
   withCliAnalyticsContext,
   resolveMemoryByQuery,
   printMemoryResolveError,