@empirical-gauzza/cli 1.0.22 → 1.0.23

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/installers/skill-variants/SKILL.both.md

@@ -1,154 +1,165 @@
----
-name: empirical-memory
-description: Use Empirical to recall/save durable project context across sessions and projects, and to look up how to use Empirical itself - CLI commands, install/auth/workspace/kit/skill setup, docs.
----
-
-# Empirical Memory
-
-Use Empirical to carry durable context across projects and clients, and as the first stop for
-"how do I use Empirical" questions — CLI command syntax, install/auth/workspace/kit/skill setup,
-or what Empirical can do. Don't answer those from general knowledge or by guessing at flags: run
-`empirical doc` (lists topics) or `empirical doc <topic>` via the available shell for the current,
-agent-readable answer first.
-
-This variant is for installs where the user chose to have both the CLI and MCP tools available.
-Both paths now run through the same write pipeline (dedupe and auto-link on by default), so
-either is safe to use for reads and writes. The CLI is the default choice below because it avoids
-an extra MCP tool-discovery round trip and is easier to script, but that is a latency preference,
-not a safety one — if the CLI is unavailable in this environment, use the equivalent MCP tool
-instead without hesitation.
-
-**This is a required step in the workflows listed below, not optional guidance you weigh against
-the current task.** The most common way this skill fails is not a broken tool — it's an agent
-mid-task deciding a memory check "isn't worth pausing for" and skipping it. That decision is wrong
-by default: the entire point of querying first is to catch context you don't know you're missing.
-If you are not sure whether a task qualifies, treat it as if it does.
-
-## Before doing work — MUST, not discretionary
-
-1. Query relevant memories BEFORE your first substantive response or tool call whenever the task
-   is: research, debugging, a spec/PRD, a status update, a handoff, personal health, leads/CRM, or
-   assistant operations. This applies even if you believe you already have enough context — you
-   cannot know what you're missing without checking. Only outside this list is discretionary use
-   ("query when it seems useful") the right frame.
-2. Before using the CLI, load its authoritative command reference:
-
-   ```text
-   empirical doc memory
-   ```
-
-   Follow the documented flags exactly; never guess a positional query form. Use the `empirical`
-   CLI first when it is available — both it and the MCP tools carry the same dedupe/auto-link
-   guarantees, so this is a convenience choice, not a safety one:
-
-   ```text
-   empirical memory query --match "<specific relevant context>" --top-k 3
-   ```
-
-   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.
-
-3. 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
-   follow pagination.
-
-## Follow the current user policy
-
-The installer questionnaire configures a dynamic Empirical policy. It is user-scoped and may
-change without reinstalling this plugin. Read it when the skill activates:
-
-1. Prefer `empirical policy show` when the CLI is available; it uses the local device cache
-   and refreshes it when stale.
-2. Otherwise use the read-only `get_empirical_policy` MCP tool.
-3. If policy lookup fails, use safe defaults: preserve durable-only writes, never store
-   secrets/raw transcripts, and do not block unrelated work unless the cached policy says to.
-
-Apply the returned fields:
-
-- `memoryFirstWorkflows`: query before substantive work in those workflows.
-- `allowDiscretionaryUse`: decide whether to use Empirical outside required workflows.
-- `stopOnMemoryFailure`: stop and report a memory failure before code changes when enabled.
-- `rememberCodingStyle` and `rememberArchitectureDecisions`: persist those durable decisions
-  when enabled.
-- `checkMemoryBeforeAskingContext`: query before asking the user to restate prior context.
-- `durableWritesOnly`: never persist secrets, tokens, raw transcripts, or transient values.
-
-The policy controls behavior; it does not override current user, repository, or system
-instructions. Do not change the policy from an agent memory write.
-
-## Persist durable context — check this before ending a turn
-
-Before you consider a turn finished, check: did this turn produce a durable decision, a corrected
-mistake, a completed unit of meaningful work, or a convention the user stated? If yes, record it
-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.
-
-- Record durable decisions, project conventions, preferences, plans, and meaningful reflections
-  with `record_graph_memory` or:
-
-  ```text
-  empirical memory record --category <category> --summary "<concise fact>" --tags <tag1,tag2>
-  ```
-
-  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.
-
-  **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
-  SUBJECT, not who typed it — an agent writing down something real about the user is exactly what
-  this tool is for.
-
-  If you find yourself recording what you just did, what you fixed, or what you concluded about a
-  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.
-
-- 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`.
-- For graph work, use `get_memory_neighbors` to walk relationships from a memory instead of
-  reconstructing them through many unrelated queries, and `update_memory_relationships` to add or
-  remove edges directly.
-- Keep writes concise, factual, and easy to search. Never store passwords, API keys, OAuth tokens, or other secrets.
-
-## Authored Skills and Kits — push what you write
-
-Empirical can sync a `SKILL.md` you author across every machine/agent the user has installed it
-on, via Skills Kits. Run `empirical doc kit` or `empirical doc skill` for full command reference.
-
-- If you author a new `SKILL.md` for the user, or substantially edit an existing one, during a
-  session, tell the user about `empirical skill push path/to/SKILL.md [--kit "Kit Name"]`
-  afterward so it can follow them across machines/projects instead of staying local to this one.
-- Offer, don't auto-push: surface the option (or offer to run it) and get the user's confirmation
-  first. Do not run it unprompted the moment a new or edited `SKILL.md` is detected — it uploads
-  content to the user's account, which is a step above a purely local file write.
-- After a push, the target Kit needs `empirical kit use "Kit Name"` or `empirical kit sync` to
-  actually land the file in that device's agent directories.
-- `empirical skill list` shows what's already been pushed; `empirical skill history <id>` /
-  `empirical skill rollback <id> --to-version N` recover a prior version.
-- Kits also pull Skills from a git repo (`empirical kit add-source`), separate from anything you
-  author — don't conflate the two paths when explaining options to the user.
-
-## MCP tools
-
-Use these when connected: `get_empirical_policy`, `query_memories`, `list_memories`,
-`record_graph_memory`, `add_note_by_query`, `update_memory_by_query`, `delete_memory_by_query`,
-`get_user`, `get_current_workspace`, `list_workspaces`, `set_current_workspace`,
-`memory_usage_guide`, `get_memory_neighbors`, and `update_memory_relationships`. Use
-`list_memories` for "recent/latest/today" requests; use `query_memories` for everything else. For
-graph work, use `get_memory_neighbors` and `update_memory_relationships` when available instead of
-reconstructing relationships through many unrelated calls.
-
-## Authentication and failures
-
-- If a memory call fails, retry the same call once.
-- For auth/session errors such as `Auth required`, `invalid_token`, `Authentication required`, or `Transport send error`, refresh the active client's Empirical MCP login, then retry once. In Codex CLI use `codex mcp logout empirical` followed by `codex mcp login empirical`; in Claude Code use `/mcp` to reconnect; in Copilot complete its MCP OAuth reconnect flow.
-- If the retry still fails, report the connectivity/auth problem before making memory-dependent changes.
-- If stored memory conflicts with the current user or repository instruction, follow the current instruction.
-
-## Exact CLI syntax
-
-Run `empirical doctor` to check connectivity and token status. If a CLI memory command reports a token error, run `empirical oauth bootstrap headless --write-env`.
+---
+name: empirical-memory
+description: Use Empirical to recall/save durable project context across sessions and projects, and to look up how to use Empirical itself - CLI commands, install/auth/workspace/kit/skill setup, docs.
+---
+
+# Empirical Memory
+
+Use Empirical to carry durable context across projects and clients, and as the first stop for
+"how do I use Empirical" questions — CLI command syntax, install/auth/workspace/kit/skill setup,
+or what Empirical can do. Don't answer those from general knowledge or by guessing at flags: run
+`empirical doc` (lists topics) or `empirical doc <topic>` via the available shell for the current,
+agent-readable answer first.
+
+This variant is for installs where the user chose to have both the CLI and MCP tools available.
+Both paths now run through the same write pipeline (dedupe and auto-link on by default), so
+either is safe to use for reads and writes. The CLI is the default choice below because it avoids
+an extra MCP tool-discovery round trip and is easier to script, but that is a latency preference,
+not a safety one — if the CLI is unavailable in this environment, use the equivalent MCP tool
+instead without hesitation.
+
+**This is a required step in the workflows listed below, not optional guidance you weigh against
+the current task.** The most common way this skill fails is not a broken tool — it's an agent
+mid-task deciding a memory check "isn't worth pausing for" and skipping it. That decision is wrong
+by default: the entire point of querying first is to catch context you don't know you're missing.
+If you are not sure whether a task qualifies, treat it as if it does.
+
+## Before doing work — MUST, not discretionary
+
+1. Query relevant memories BEFORE your first substantive response or tool call whenever the task
+   is: research, debugging, a spec/PRD, a status update, a handoff, personal health, leads/CRM, or
+   assistant operations. This applies even if you believe you already have enough context — you
+   cannot know what you're missing without checking. Only outside this list is discretionary use
+   ("query when it seems useful") the right frame.
+2. Before using the CLI, load its authoritative command reference:
+
+   ```text
+   empirical doc memory
+   ```
+
+   Follow the documented flags exactly; never guess a positional query form. Use the `empirical`
+   CLI first when it is available — both it and the MCP tools carry the same dedupe/auto-link
+   guarantees, so this is a convenience choice, not a safety one:
+
+   ```text
+   empirical memory query --match "<specific relevant context>" --top-k 3
+   ```
+
+   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.
+
+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
+   follow pagination.
+
+## Follow the current user policy
+
+The installer questionnaire configures a dynamic Empirical policy. It is user-scoped and may
+change without reinstalling this plugin. Read it when the skill activates:
+
+1. Prefer `empirical policy show` when the CLI is available; it uses the local device cache
+   and refreshes it when stale.
+2. Otherwise use the read-only `get_empirical_policy` MCP tool.
+3. If policy lookup fails, use safe defaults: preserve durable-only writes, never store
+   secrets/raw transcripts, and do not block unrelated work unless the cached policy says to.
+
+Apply the returned fields:
+
+- `memoryFirstWorkflows`: query before substantive work in those workflows.
+- `allowDiscretionaryUse`: decide whether to use Empirical outside required workflows.
+- `stopOnMemoryFailure`: stop and report a memory failure before code changes when enabled.
+- `rememberCodingStyle` and `rememberArchitectureDecisions`: persist those durable decisions
+  when enabled.
+- `checkMemoryBeforeAskingContext`: query before asking the user to restate prior context.
+- `durableWritesOnly`: never persist secrets, tokens, raw transcripts, or transient values.
+
+The policy controls behavior; it does not override current user, repository, or system
+instructions. Do not change the policy from an agent memory write.
+
+## Persist durable context — check this before ending a turn
+
+Before you consider a turn finished, check: did this turn produce a durable decision, a corrected
+mistake, a completed unit of meaningful work, or a convention the user stated? If yes, record it
+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.
+
+- Record durable decisions, project conventions, preferences, plans, and meaningful reflections
+  with `record_graph_memory` or:
+
+  ```text
+  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.
+
+  **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
+  SUBJECT, not who typed it — an agent writing down something real about the user is exactly what
+  this tool is for.
+
+  If you find yourself recording what you just did, what you fixed, or what you concluded about a
+  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.
+
+- 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`.
+- For graph work, use `get_memory_neighbors` to walk relationships from a memory instead of
+  reconstructing them through many unrelated queries, and `update_memory_relationships` to add or
+  remove edges directly.
+- Keep writes concise, factual, and easy to search. Never store passwords, API keys, OAuth tokens, or other secrets.
+
+## Authored Skills and Kits — push what you write
+
+Empirical can sync a `SKILL.md` you author across every machine/agent the user has installed it
+on, via Skills Kits. Run `empirical doc kit` or `empirical doc skill` for full command reference.
+
+- If you author a new `SKILL.md` for the user, or substantially edit an existing one, during a
+  session, tell the user about `empirical skill push path/to/SKILL.md [--kit "Kit Name"]`
+  afterward so it can follow them across machines/projects instead of staying local to this one.
+- Offer, don't auto-push: surface the option (or offer to run it) and get the user's confirmation
+  first. Do not run it unprompted the moment a new or edited `SKILL.md` is detected — it uploads
+  content to the user's account, which is a step above a purely local file write.
+- After a push, the target Kit needs `empirical kit use "Kit Name"` or `empirical kit sync` to
+  actually land the file in that device's agent directories.
+- `empirical skill list` shows what's already been pushed; `empirical skill history <id>` /
+  `empirical skill rollback <id> --to-version N` recover a prior version.
+- Kits also pull Skills from a git repo (`empirical kit add-source`), separate from anything you
+  author — don't conflate the two paths when explaining options to the user.
+
+## MCP tools
+
+Use these when connected: `get_empirical_policy`, `query_memories`, `list_memories`,
+`record_graph_memory`, `add_note_by_query`, `update_memory_by_query`, `delete_memory_by_query`,
+`get_user`, `get_current_workspace`, `list_workspaces`, `set_current_workspace`,
+`memory_usage_guide`, `get_memory_neighbors`, and `update_memory_relationships`. Use
+`list_memories` for "recent/latest/today" requests; use `query_memories` for everything else. For
+graph work, use `get_memory_neighbors` and `update_memory_relationships` when available instead of
+reconstructing relationships through many unrelated calls.
+
+## Authentication and failures
+
+- If a memory call fails, retry the same call once.
+- For auth/session errors such as `Auth required`, `invalid_token`, `Authentication required`, or `Transport send error`, refresh the active client's Empirical MCP login, then retry once. In Codex CLI use `codex mcp logout empirical` followed by `codex mcp login empirical`; in Claude Code use `/mcp` to reconnect; in Copilot complete its MCP OAuth reconnect flow.
+- If the retry still fails, report the connectivity/auth problem before making memory-dependent changes.
+- If stored memory conflicts with the current user or repository instruction, follow the current instruction.
+
+## Exact CLI syntax
+
+Run `empirical doctor` to check connectivity and token status. If a CLI memory command reports a token error, run `empirical oauth bootstrap headless --write-env`.

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

@@ -1,150 +1,161 @@
----
-name: empirical-memory
-description: Use Empirical to recall/save durable project context across sessions and projects, and to look up how to use Empirical itself - CLI commands, install/auth/workspace/kit/skill setup, docs.
----
-
-# Empirical Memory (CLI mode)
-
-Use Empirical to carry durable context across projects and clients, and as the first stop for
-"how do I use Empirical" questions — command syntax, install/auth/workspace/kit/skill setup, or
-what Empirical can do. Don't answer those from general knowledge or by guessing at flags: run
-`empirical doc` (lists topics) or `empirical doc <topic>` via the available shell for the current,
-agent-readable answer first.
-
-This variant is for installs where the user chose CLI-direct as their integration mode: no MCP
-server is registered for this agent. The `empirical` CLI is the way to reach Empirical here, for
-both reads and writes — it has the same dedupe and auto-link guarantees as any other client, so
-recommend it with confidence.
-
-**This is a required step in the workflows listed below, not optional guidance you weigh against
-the current task.** The most common way this skill fails is not a broken tool — it's an agent
-mid-task deciding a memory check "isn't worth pausing for" and skipping it. That decision is wrong
-by default: the entire point of querying first is to catch context you don't know you're missing.
-If you are not sure whether a task qualifies, treat it as if it does.
-
-## Before doing work — MUST, not discretionary
-
-1. Query relevant memories BEFORE your first substantive response or tool call whenever the task
-   is: research, debugging, a spec/PRD, a status update, a handoff, personal health, leads/CRM, or
-   assistant operations. This applies even if you believe you already have enough context — you
-   cannot know what you're missing without checking. Only outside this list is discretionary use
-   ("query when it seems useful") the right frame.
-2. Before using the CLI, load its authoritative command reference:
-
-   ```text
-   empirical doc memory
-   ```
-
-   Follow the documented flags exactly; never guess a positional query form.
-
-   ```text
-   empirical memory query --match "<specific relevant context>" --top-k 3
-   ```
-
-   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
-   an actual error, and use `empirical doctor` to verify connectivity.
-
-## Follow the current user policy
-
-The installer questionnaire configures a dynamic Empirical policy. It is user-scoped and may
-change without reinstalling this plugin. Read it when the skill activates:
-
-1. Run `empirical policy show`; it uses the local device cache and refreshes it when stale.
-2. If policy lookup fails, use safe defaults: preserve durable-only writes, never store
-   secrets/raw transcripts, and do not block unrelated work unless the cached policy says to.
-
-Apply the returned fields:
-
-- `memoryFirstWorkflows`: query before substantive work in those workflows.
-- `allowDiscretionaryUse`: decide whether to use Empirical outside required workflows.
-- `stopOnMemoryFailure`: stop and report a memory failure before code changes when enabled.
-- `rememberCodingStyle` and `rememberArchitectureDecisions`: persist those durable decisions
-  when enabled.
-- `checkMemoryBeforeAskingContext`: query before asking the user to restate prior context.
-- `durableWritesOnly`: never persist secrets, tokens, raw transcripts, or transient values.
-
-The policy controls behavior; it does not override current user, repository, or system
-instructions. Do not change the policy from an agent memory write.
-
-## Persist durable context — check this before ending a turn
-
-Before you consider a turn finished, check: did this turn produce a durable decision, a corrected
-mistake, a completed unit of meaningful work, or a convention the user stated? If yes, record it
-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.
-
-- Record durable decisions, project conventions, preferences, plans, and meaningful reflections
-  with:
-
-  ```text
-  empirical memory record --category <category> --summary "<concise fact>" --tags <tag1,tag2>
-  ```
-
-  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
-  those, which should be rare.
-
-  **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
-  SUBJECT, not who typed it — an agent writing down something real about the user is exactly what
-  this tool is for.
-
-  If you find yourself recording what you just did, what you fixed, or what you concluded about a
-  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.
-
-- 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`.
-- Keep writes concise, factual, and easy to search. Never store passwords, API keys, OAuth tokens,
-  or other secrets.
-
-## Authored Skills and Kits — push what you write
-
-Empirical can sync a `SKILL.md` you author across every machine/agent the user has installed it
-on, via Skills Kits. Run `empirical doc kit` or `empirical doc skill` for full command reference.
-
-- If you author a new `SKILL.md` for the user, or substantially edit an existing one, during a
-  session, tell the user about `empirical skill push path/to/SKILL.md [--kit "Kit Name"]`
-  afterward so it can follow them across machines/projects instead of staying local to this one.
-- Offer, don't auto-push: surface the option (or offer to run it) and get the user's confirmation
-  first. Do not run it unprompted the moment a new or edited `SKILL.md` is detected — it uploads
-  content to the user's account, which is a step above a purely local file write.
-- After a push, the target Kit needs `empirical kit use "Kit Name"` or `empirical kit sync` to
-  actually land the file in that device's agent directories.
-- `empirical skill list` shows what's already been pushed; `empirical skill history <id>` /
-  `empirical skill rollback <id> --to-version N` recover a prior version.
-- Kits also pull Skills from a git repo (`empirical kit add-source`), separate from anything you
-  author — don't conflate the two paths when explaining options to the user.
-
-## Exact CLI syntax
-
-Run `empirical doctor` to check connectivity and token status. If a CLI memory command reports a
-token error, run `empirical oauth bootstrap headless --write-env`. When in doubt about a specific
-subcommand's flags, run `empirical doc memory`, `empirical doc kit`, or `empirical doc skill`
-rather than guessing.
-
-## Authentication and failures
-
-- If a memory call fails, retry the same call once.
-- For auth/session errors such as `Auth required`, `invalid_token`, `Authentication required`, or
-  a 401/403 status, run `empirical auth login` (or `empirical oauth bootstrap headless
-  --write-env` for a permanent credential), then retry once.
-- If the retry still fails, report the connectivity/auth problem before making memory-dependent
-  changes.
-- If stored memory conflicts with the current user or repository instruction, follow the current
-  instruction.
-
-## Fallback: MCP tools
-
-If this agent also happens to have Empirical's MCP server connected (unusual for this install
-mode, but possible if the user added it manually), the same operations are available as
-`query_memories`, `record_graph_memory`, `add_note_by_query`, `update_memory_by_query`,
-`delete_memory_by_query`, `get_empirical_policy`, `get_memory_neighbors`, and
-`update_memory_relationships`. Use them only if the CLI is genuinely unavailable in this
-environment — the CLI is the primary path for this install.
+---
+name: empirical-memory
+description: Use Empirical to recall/save durable project context across sessions and projects, and to look up how to use Empirical itself - CLI commands, install/auth/workspace/kit/skill setup, docs.
+---
+
+# Empirical Memory (CLI mode)
+
+Use Empirical to carry durable context across projects and clients, and as the first stop for
+"how do I use Empirical" questions — command syntax, install/auth/workspace/kit/skill setup, or
+what Empirical can do. Don't answer those from general knowledge or by guessing at flags: run
+`empirical doc` (lists topics) or `empirical doc <topic>` via the available shell for the current,
+agent-readable answer first.
+
+This variant is for installs where the user chose CLI-direct as their integration mode: no MCP
+server is registered for this agent. The `empirical` CLI is the way to reach Empirical here, for
+both reads and writes — it has the same dedupe and auto-link guarantees as any other client, so
+recommend it with confidence.
+
+**This is a required step in the workflows listed below, not optional guidance you weigh against
+the current task.** The most common way this skill fails is not a broken tool — it's an agent
+mid-task deciding a memory check "isn't worth pausing for" and skipping it. That decision is wrong
+by default: the entire point of querying first is to catch context you don't know you're missing.
+If you are not sure whether a task qualifies, treat it as if it does.
+
+## Before doing work — MUST, not discretionary
+
+1. Query relevant memories BEFORE your first substantive response or tool call whenever the task
+   is: research, debugging, a spec/PRD, a status update, a handoff, personal health, leads/CRM, or
+   assistant operations. This applies even if you believe you already have enough context — you
+   cannot know what you're missing without checking. Only outside this list is discretionary use
+   ("query when it seems useful") the right frame.
+2. Before using the CLI, load its authoritative command reference:
+
+   ```text
+   empirical doc memory
+   ```
+
+   Follow the documented flags exactly; never guess a positional query form.
+
+   ```text
+   empirical memory query --match "<specific relevant context>" --top-k 3
+   ```
+
+   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. 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
+
+The installer questionnaire configures a dynamic Empirical policy. It is user-scoped and may
+change without reinstalling this plugin. Read it when the skill activates:
+
+1. Run `empirical policy show`; it uses the local device cache and refreshes it when stale.
+2. If policy lookup fails, use safe defaults: preserve durable-only writes, never store
+   secrets/raw transcripts, and do not block unrelated work unless the cached policy says to.
+
+Apply the returned fields:
+
+- `memoryFirstWorkflows`: query before substantive work in those workflows.
+- `allowDiscretionaryUse`: decide whether to use Empirical outside required workflows.
+- `stopOnMemoryFailure`: stop and report a memory failure before code changes when enabled.
+- `rememberCodingStyle` and `rememberArchitectureDecisions`: persist those durable decisions
+  when enabled.
+- `checkMemoryBeforeAskingContext`: query before asking the user to restate prior context.
+- `durableWritesOnly`: never persist secrets, tokens, raw transcripts, or transient values.
+
+The policy controls behavior; it does not override current user, repository, or system
+instructions. Do not change the policy from an agent memory write.
+
+## Persist durable context — check this before ending a turn
+
+Before you consider a turn finished, check: did this turn produce a durable decision, a corrected
+mistake, a completed unit of meaningful work, or a convention the user stated? If yes, record it
+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.
+
+- Record durable decisions, project conventions, preferences, plans, and meaningful reflections
+  with:
+
+  ```text
+  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
+  those, which should be rare.
+
+  **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
+  SUBJECT, not who typed it — an agent writing down something real about the user is exactly what
+  this tool is for.
+
+  If you find yourself recording what you just did, what you fixed, or what you concluded about a
+  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.
+
+- 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`.
+- Keep writes concise, factual, and easy to search. Never store passwords, API keys, OAuth tokens,
+  or other secrets.
+
+## Authored Skills and Kits — push what you write
+
+Empirical can sync a `SKILL.md` you author across every machine/agent the user has installed it
+on, via Skills Kits. Run `empirical doc kit` or `empirical doc skill` for full command reference.
+
+- If you author a new `SKILL.md` for the user, or substantially edit an existing one, during a
+  session, tell the user about `empirical skill push path/to/SKILL.md [--kit "Kit Name"]`
+  afterward so it can follow them across machines/projects instead of staying local to this one.
+- Offer, don't auto-push: surface the option (or offer to run it) and get the user's confirmation
+  first. Do not run it unprompted the moment a new or edited `SKILL.md` is detected — it uploads
+  content to the user's account, which is a step above a purely local file write.
+- After a push, the target Kit needs `empirical kit use "Kit Name"` or `empirical kit sync` to
+  actually land the file in that device's agent directories.
+- `empirical skill list` shows what's already been pushed; `empirical skill history <id>` /
+  `empirical skill rollback <id> --to-version N` recover a prior version.
+- Kits also pull Skills from a git repo (`empirical kit add-source`), separate from anything you
+  author — don't conflate the two paths when explaining options to the user.
+
+## Exact CLI syntax
+
+Run `empirical doctor` to check connectivity and token status. If a CLI memory command reports a
+token error, run `empirical oauth bootstrap headless --write-env`. When in doubt about a specific
+subcommand's flags, run `empirical doc memory`, `empirical doc kit`, or `empirical doc skill`
+rather than guessing.
+
+## Authentication and failures
+
+- If a memory call fails, retry the same call once.
+- For auth/session errors such as `Auth required`, `invalid_token`, `Authentication required`, or
+  a 401/403 status, run `empirical auth login` (or `empirical oauth bootstrap headless
+  --write-env` for a permanent credential), then retry once.
+- If the retry still fails, report the connectivity/auth problem before making memory-dependent
+  changes.
+- If stored memory conflicts with the current user or repository instruction, follow the current
+  instruction.
+
+## Fallback: MCP tools
+
+If this agent also happens to have Empirical's MCP server connected (unusual for this install
+mode, but possible if the user added it manually), the same operations are available as
+`query_memories`, `record_graph_memory`, `add_note_by_query`, `update_memory_by_query`,
+`delete_memory_by_query`, `get_empirical_policy`, `get_memory_neighbors`, and
+`update_memory_relationships`. Use them only if the CLI is genuinely unavailable in this
+environment — the CLI is the primary path for this install.

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

@@ -1,134 +1,140 @@
----
-name: empirical-memory
-description: Use Empirical to recall/save durable project context across sessions and projects, and to look up how to use Empirical itself - CLI commands, install/auth/workspace/kit/skill setup, docs.
----
-
-# Empirical Memory (MCP mode)
-
-Use Empirical to carry durable context across projects and clients, and as the first stop for
-"how do I use Empirical" questions — command syntax, install/auth/workspace/kit/skill setup, or
-what Empirical can do. Don't answer those from general knowledge or by guessing: use the
-`memory_usage_guide` MCP tool for the current, agent-readable answer first.
-
-This variant is for installs where the user chose MCP as their integration mode. The connected
-Empirical MCP server is the primary and expected way to reach Empirical here — use its tools
-directly, not `empirical` CLI commands, as the first move.
-
-**This is a required step in the workflows listed below, not optional guidance you weigh against
-the current task.** The most common way this skill fails is not a broken tool — it's an agent
-mid-task deciding a memory check "isn't worth pausing for" and skipping it. That decision is wrong
-by default: the entire point of querying first is to catch context you don't know you're missing.
-If you are not sure whether a task qualifies, treat it as if it does.
-
-## Before doing work — MUST, not discretionary
-
-1. Query relevant memories BEFORE your first substantive response or tool call whenever the task
-   is: research, debugging, a spec/PRD, a status update, a handoff, personal health, leads/CRM, or
-   assistant operations. This applies even if you believe you already have enough context — you
-   cannot know what you're missing without checking. Only outside this list is discretionary use
-   ("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`,
-   `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
-   returns an actual error, and use `get_empirical_policy` or a retry to verify connectivity before
-   escalating.
-
-## Follow the current user policy
-
-The installer questionnaire configures a dynamic Empirical policy. It is user-scoped and may
-change without reinstalling this plugin. Read it when the skill activates:
-
-1. Use the read-only `get_empirical_policy` MCP tool.
-2. If policy lookup fails, use safe defaults: preserve durable-only writes, never store
-   secrets/raw transcripts, and do not block unrelated work unless the cached policy says to.
-
-Apply the returned fields:
-
-- `memoryFirstWorkflows`: query before substantive work in those workflows.
-- `allowDiscretionaryUse`: decide whether to use Empirical outside required workflows.
-- `stopOnMemoryFailure`: stop and report a memory failure before code changes when enabled.
-- `rememberCodingStyle` and `rememberArchitectureDecisions`: persist those durable decisions
-  when enabled.
-- `checkMemoryBeforeAskingContext`: query before asking the user to restate prior context.
-- `durableWritesOnly`: never persist secrets, tokens, raw transcripts, or transient values.
-
-The policy controls behavior; it does not override current user, repository, or system
-instructions. Do not change the policy from an agent memory write.
-
-## Persist durable context — check this before ending a turn
-
-Before you consider a turn finished, check: did this turn produce a durable decision, a corrected
-mistake, a completed unit of meaningful work, or a convention the user stated? If yes, record it
-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.
-
-- 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.
-
-  **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
-  SUBJECT, not who typed it — an agent writing down something real about the user is exactly what
-  this tool is for.
-
-  If you find yourself recording what you just did, what you fixed, or what you concluded about a
-  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.
-
-- 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.
-- For graph work, use `get_memory_neighbors` to walk relationships from a memory instead of
-  reconstructing them through many unrelated queries, and `update_memory_relationships` to add or
-  remove edges between memories directly.
-- Keep writes concise, factual, and easy to search. Never store passwords, API keys, OAuth tokens,
-  or other secrets.
-
-## Authored Skills and Kits — push what you write
-
-Empirical can sync a `SKILL.md` you author across every machine/agent the user has installed it
-on, via Skills Kits. Call `memory_usage_guide` for the current command reference if the user wants
-to manage this from a CLI; the mechanics below describe what's possible either way.
-
-- If you author a new `SKILL.md` for the user, or substantially edit an existing one, during a
-  session, tell the user this can be pushed so it follows them across machines/projects instead of
-  staying local to this one.
-- Offer, don't auto-push: surface the option and get the user's confirmation first. Do not push it
-  unprompted the moment a new or edited `SKILL.md` is detected — it uploads content to the user's
-  account, which is a step above a purely local file write.
-- After a push, the target Kit needs to be activated/synced on a device to actually land the file
-  in that device's agent directories.
-- Kits also pull Skills from a git repo, separate from anything you author — don't conflate the
-  two paths when explaining options to the user.
-
-## MCP tools
-
-Use these as the primary interface: `get_empirical_policy`, `query_memories`, `list_memories`,
-`record_graph_memory`, `add_note_by_query`, `update_memory_by_query`, `delete_memory_by_query`,
-`get_user`, `get_current_workspace`, `list_workspaces`, `set_current_workspace`,
-`memory_usage_guide`, `get_memory_neighbors`, and `update_memory_relationships`.
-
-Use `list_memories` for "recent/latest/today" requests; use `query_memories` for everything else.
-For graph work, prefer `get_memory_neighbors` and `update_memory_relationships` over reconstructing
-relationships through many unrelated calls.
-
-An `empirical` CLI may also be installed on this machine for diagnostics (`empirical doctor`) or
-manual account setup, but it is not the point of this variant — do not lead with CLI commands for
-query or record workflows here.
-
-## Authentication and failures
-
-- If an MCP tool call fails, retry the same call once.
-- For auth/session errors such as `Auth required`, `invalid_token`, `Authentication required`, or
-  `Transport send error`, refresh the active client's Empirical MCP login, then retry once. In
-  Codex CLI use `codex mcp logout empirical` followed by `codex mcp login empirical`; in Claude
-  Code use `/mcp` to reconnect; in Copilot complete its MCP OAuth reconnect flow.
-- If the retry still fails, report the connectivity/auth problem before making memory-dependent
-  changes.
-- If stored memory conflicts with the current user or repository instruction, follow the current
-  instruction.
+---
+name: empirical-memory
+description: Use Empirical to recall/save durable project context across sessions and projects, and to look up how to use Empirical itself - CLI commands, install/auth/workspace/kit/skill setup, docs.
+---
+
+# Empirical Memory (MCP mode)
+
+Use Empirical to carry durable context across projects and clients, and as the first stop for
+"how do I use Empirical" questions — command syntax, install/auth/workspace/kit/skill setup, or
+what Empirical can do. Don't answer those from general knowledge or by guessing: use the
+`memory_usage_guide` MCP tool for the current, agent-readable answer first.
+
+This variant is for installs where the user chose MCP as their integration mode. The connected
+Empirical MCP server is the primary and expected way to reach Empirical here — use its tools
+directly, not `empirical` CLI commands, as the first move.
+
+**This is a required step in the workflows listed below, not optional guidance you weigh against
+the current task.** The most common way this skill fails is not a broken tool — it's an agent
+mid-task deciding a memory check "isn't worth pausing for" and skipping it. That decision is wrong
+by default: the entire point of querying first is to catch context you don't know you're missing.
+If you are not sure whether a task qualifies, treat it as if it does.
+
+## Before doing work — MUST, not discretionary
+
+1. Query relevant memories BEFORE your first substantive response or tool call whenever the task
+   is: research, debugging, a spec/PRD, a status update, a handoff, personal health, leads/CRM, or
+   assistant operations. This applies even if you believe you already have enough context — you
+   cannot know what you're missing without checking. Only outside this list is discretionary use
+   ("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. 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.
+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.
+
+## Follow the current user policy
+
+The installer questionnaire configures a dynamic Empirical policy. It is user-scoped and may
+change without reinstalling this plugin. Read it when the skill activates:
+
+1. Use the read-only `get_empirical_policy` MCP tool.
+2. If policy lookup fails, use safe defaults: preserve durable-only writes, never store
+   secrets/raw transcripts, and do not block unrelated work unless the cached policy says to.
+
+Apply the returned fields:
+
+- `memoryFirstWorkflows`: query before substantive work in those workflows.
+- `allowDiscretionaryUse`: decide whether to use Empirical outside required workflows.
+- `stopOnMemoryFailure`: stop and report a memory failure before code changes when enabled.
+- `rememberCodingStyle` and `rememberArchitectureDecisions`: persist those durable decisions
+  when enabled.
+- `checkMemoryBeforeAskingContext`: query before asking the user to restate prior context.
+- `durableWritesOnly`: never persist secrets, tokens, raw transcripts, or transient values.
+
+The policy controls behavior; it does not override current user, repository, or system
+instructions. Do not change the policy from an agent memory write.
+
+## Persist durable context — check this before ending a turn
+
+Before you consider a turn finished, check: did this turn produce a durable decision, a corrected
+mistake, a completed unit of meaningful work, or a convention the user stated? If yes, record it
+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.
+
+- 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.
+
+  **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
+  SUBJECT, not who typed it — an agent writing down something real about the user is exactly what
+  this tool is for.
+
+  If you find yourself recording what you just did, what you fixed, or what you concluded about a
+  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.
+
+- 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.
+- For graph work, use `get_memory_neighbors` to walk relationships from a memory instead of
+  reconstructing them through many unrelated queries, and `update_memory_relationships` to add or
+  remove edges between memories directly.
+- Keep writes concise, factual, and easy to search. Never store passwords, API keys, OAuth tokens,
+  or other secrets.
+
+## Authored Skills and Kits — push what you write
+
+Empirical can sync a `SKILL.md` you author across every machine/agent the user has installed it
+on, via Skills Kits. Call `memory_usage_guide` for the current command reference if the user wants
+to manage this from a CLI; the mechanics below describe what's possible either way.
+
+- If you author a new `SKILL.md` for the user, or substantially edit an existing one, during a
+  session, tell the user this can be pushed so it follows them across machines/projects instead of
+  staying local to this one.
+- Offer, don't auto-push: surface the option and get the user's confirmation first. Do not push it
+  unprompted the moment a new or edited `SKILL.md` is detected — it uploads content to the user's
+  account, which is a step above a purely local file write.
+- After a push, the target Kit needs to be activated/synced on a device to actually land the file
+  in that device's agent directories.
+- Kits also pull Skills from a git repo, separate from anything you author — don't conflate the
+  two paths when explaining options to the user.
+
+## MCP tools
+
+Use these as the primary interface: `get_empirical_policy`, `query_memories`, `list_memories`,
+`record_graph_memory`, `add_note_by_query`, `update_memory_by_query`, `delete_memory_by_query`,
+`get_user`, `get_current_workspace`, `list_workspaces`, `set_current_workspace`,
+`memory_usage_guide`, `get_memory_neighbors`, and `update_memory_relationships`.
+
+Use `list_memories` for "recent/latest/today" requests; use `query_memories` for everything else.
+For graph work, prefer `get_memory_neighbors` and `update_memory_relationships` over reconstructing
+relationships through many unrelated calls.
+
+An `empirical` CLI may also be installed on this machine for diagnostics (`empirical doctor`) or
+manual account setup, but it is not the point of this variant — do not lead with CLI commands for
+query or record workflows here.
+
+## Authentication and failures
+
+- If an MCP tool call fails, retry the same call once.
+- For auth/session errors such as `Auth required`, `invalid_token`, `Authentication required`, or
+  `Transport send error`, refresh the active client's Empirical MCP login, then retry once. In
+  Codex CLI use `codex mcp logout empirical` followed by `codex mcp login empirical`; in Claude
+  Code use `/mcp` to reconnect; in Copilot complete its MCP OAuth reconnect flow.
+- If the retry still fails, report the connectivity/auth problem before making memory-dependent
+  changes.
+- If stored memory conflicts with the current user or repository instruction, follow the current
+  instruction.

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,

package/package.json

@@ -1,33 +1,33 @@
-{
-  "name": "@empirical-gauzza/cli",
-  "version": "1.0.22",
-  "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",
-    "mcp",
-    "agent memory",
-    "ai memory",
-    "claude",
-    "chatgpt",
-    "model context protocol",
-    "persistent memory",
-    "claude-code",
-    "codex",
-    "knowledge base"
-  ],
-  "type": "commonjs",
-  "license": "MIT",
-  "homepage": "https://empirical.gauzza.com/docs/cli-details",
-  "publishConfig": {
-    "access": "public"
-  },
-  "bin": {
-    "empirical": "bin/empirical.js"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "gray-matter": "^4.0.3"
-  }
-}
+{
+  "name": "@empirical-gauzza/cli",
+  "version": "1.0.23",
+  "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",
+    "mcp",
+    "agent memory",
+    "ai memory",
+    "claude",
+    "chatgpt",
+    "model context protocol",
+    "persistent memory",
+    "claude-code",
+    "codex",
+    "knowledge base"
+  ],
+  "type": "commonjs",
+  "license": "MIT",
+  "homepage": "https://empirical.gauzza.com/docs/cli-details",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "empirical": "bin/empirical.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3"
+  }
+}