@empirical-gauzza/cli 1.0.20 → 1.0.21

package/bin/empirical.js

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

package/lib/installers/coreMemoryBlock.js

@@ -1,91 +1,91 @@
-'use strict';
-
-const { readUtf8IfExists, writeFile, ensureDir } = require('../fsUtils');
-const path = require('path');
-const { CORE_PLUGIN_NAME, OPTIONAL_PLUGIN_NAMES } = require('./nativePlugin');
-
-// 2026-08-24: added after a real incident where an agent (Claude Code) ignored Empirical's
-// memory skill for an entire session despite its reminder hooks firing on every turn, and
-// defaulted instead to a competing BUILT-IN memory feature baked into its own system prompt in
-// first-person, identity-framed language ("You have a persistent, file-based memory system...").
-// That framing -- "this is what you are", not "here is a tool you could call" -- is what won by
-// default. The fix is not a stronger hook; it's writing the SAME kind of identity-framed
-// statement into the one place every agent reads unconditionally every session: its global
-// instructions file (CLAUDE.md / AGENTS.md / copilot-instructions.md). Prior versions of the
-// installers deliberately left these files untouched ("native plugin guidance is authoritative")
-// -- that trust was real-world false; hooks and an installable skill were not enough on their own.
-const BEGIN_MARKER = '<!-- BEGIN EMPIRICAL CORE MEMORY -->';
-const END_MARKER = '<!-- END EMPIRICAL CORE MEMORY -->';
-
-const PLUGIN_DESCRIPTIONS = {
-  [CORE_PLUGIN_NAME]: 'query and save durable project/user context - the core memory skill',
-  'empirical-work-history': 'record concise summaries of completed work for future agents',
-  'empirical-scar-tissue': 'record recurring failure patterns and prevention guidance',
-  'empirical-todo': 'track actionable follow-ups by project'
-};
-
-function describePlugin(name) {
-  return PLUGIN_DESCRIPTIONS[name] || 'an installed Empirical skill';
-}
-
-/**
- * Builds the identity-framed core memory block. Dynamic: lists exactly the plugins this install
- * run actually installed, not a static "here's everything that could exist" list, so it stays
- * accurate as skills are added or removed on a later `empirical install`/`empirical plugin` run.
- */
-function buildCoreMemoryBlock({ pluginNames = [CORE_PLUGIN_NAME] } = {}) {
-  const names = Array.isArray(pluginNames) && pluginNames.length ? pluginNames : [CORE_PLUGIN_NAME];
-  const skillLines = names.map((name) => `- \`${name}\` - ${describePlugin(name)}`).join('\n');
-
-  return `${BEGIN_MARKER}
-## Persistent memory: Empirical
-
-You have access to Empirical, a persistent, queryable, cross-session memory graph. This is your
-durable memory system for this project and user - not a feature you might use, the actual place
-durable context lives. It takes priority over inventing your own local notes: writing project
-findings to ad-hoc local markdown files instead of Empirical produces something no other session,
-tool, or agent can search or reuse, and defeats the reason this is installed at all.
-
-Before substantive work (research, debugging, a spec or PRD, a status update, a handoff, or
-picking up previously completed work), query Empirical first - do not assume you already have
-enough context. After completing meaningful work, or discovering a mistake worth not repeating,
-record it in Empirical, not in a local file.
-
-Installed Empirical skills in this environment:
-${skillLines}
-
-Run \`empirical doc\` for the full command reference, or \`empirical doc memory\` for exact query/record syntax.
-${END_MARKER}`;
-}
-
-/**
- * Replaces the block between BEGIN/END markers if present, otherwise appends a fresh block
- * (with a leading blank line if the file already has content). Never touches anything outside
- * the markers, so a user's own instructions in this file are preserved untouched. Creates the
- * file (and its parent directory) if it does not exist yet.
- */
-function upsertCoreMemoryBlock(filePath, block) {
-  ensureDir(path.dirname(filePath));
-  const existing = readUtf8IfExists(filePath) || '';
-
-  const beginIndex = existing.indexOf(BEGIN_MARKER);
-  const endIndex = existing.indexOf(END_MARKER);
-
-  if (beginIndex !== -1 && endIndex !== -1 && endIndex > beginIndex) {
-    const before = existing.slice(0, beginIndex);
-    const after = existing.slice(endIndex + END_MARKER.length);
-    writeFile(filePath, `${before}${block}${after}`);
-    return;
-  }
-
-  const trimmed = existing.replace(/\s+$/, '');
-  const next = trimmed ? `${trimmed}\n\n${block}\n` : `${block}\n`;
-  writeFile(filePath, next);
-}
-
-module.exports = {
-  BEGIN_MARKER,
-  END_MARKER,
-  buildCoreMemoryBlock,
-  upsertCoreMemoryBlock
-};
+'use strict';
+
+const { readUtf8IfExists, writeFile, ensureDir } = require('../fsUtils');
+const path = require('path');
+const { CORE_PLUGIN_NAME, OPTIONAL_PLUGIN_NAMES } = require('./nativePlugin');
+
+// 2026-08-24: added after a real incident where an agent (Claude Code) ignored Empirical's
+// memory skill for an entire session despite its reminder hooks firing on every turn, and
+// defaulted instead to a competing BUILT-IN memory feature baked into its own system prompt in
+// first-person, identity-framed language ("You have a persistent, file-based memory system...").
+// That framing -- "this is what you are", not "here is a tool you could call" -- is what won by
+// default. The fix is not a stronger hook; it's writing the SAME kind of identity-framed
+// statement into the one place every agent reads unconditionally every session: its global
+// instructions file (CLAUDE.md / AGENTS.md / copilot-instructions.md). Prior versions of the
+// installers deliberately left these files untouched ("native plugin guidance is authoritative")
+// -- that trust was real-world false; hooks and an installable skill were not enough on their own.
+const BEGIN_MARKER = '<!-- BEGIN EMPIRICAL CORE MEMORY -->';
+const END_MARKER = '<!-- END EMPIRICAL CORE MEMORY -->';
+
+const PLUGIN_DESCRIPTIONS = {
+  [CORE_PLUGIN_NAME]: 'query and save durable project/user context - the core memory skill',
+  'empirical-work-history': 'record concise summaries of completed work for future agents',
+  'empirical-scar-tissue': 'record recurring failure patterns and prevention guidance',
+  'empirical-todo': 'track actionable follow-ups by project'
+};
+
+function describePlugin(name) {
+  return PLUGIN_DESCRIPTIONS[name] || 'an installed Empirical skill';
+}
+
+/**
+ * Builds the identity-framed core memory block. Dynamic: lists exactly the plugins this install
+ * run actually installed, not a static "here's everything that could exist" list, so it stays
+ * accurate as skills are added or removed on a later `empirical install`/`empirical plugin` run.
+ */
+function buildCoreMemoryBlock({ pluginNames = [CORE_PLUGIN_NAME] } = {}) {
+  const names = Array.isArray(pluginNames) && pluginNames.length ? pluginNames : [CORE_PLUGIN_NAME];
+  const skillLines = names.map((name) => `- \`${name}\` - ${describePlugin(name)}`).join('\n');
+
+  return `${BEGIN_MARKER}
+## Persistent memory: Empirical
+
+You have access to Empirical, a persistent, queryable, cross-session memory graph. This is your
+durable memory system for this project and user - not a feature you might use, the actual place
+durable context lives. It takes priority over inventing your own local notes: writing project
+findings to ad-hoc local markdown files instead of Empirical produces something no other session,
+tool, or agent can search or reuse, and defeats the reason this is installed at all.
+
+Before substantive work (research, debugging, a spec or PRD, a status update, a handoff, or
+picking up previously completed work), query Empirical first - do not assume you already have
+enough context. After completing meaningful work, or discovering a mistake worth not repeating,
+record it in Empirical, not in a local file.
+
+Installed Empirical skills in this environment:
+${skillLines}
+
+Run \`empirical doc\` for the full command reference, or \`empirical doc memory\` for exact query/record syntax.
+${END_MARKER}`;
+}
+
+/**
+ * Replaces the block between BEGIN/END markers if present, otherwise appends a fresh block
+ * (with a leading blank line if the file already has content). Never touches anything outside
+ * the markers, so a user's own instructions in this file are preserved untouched. Creates the
+ * file (and its parent directory) if it does not exist yet.
+ */
+function upsertCoreMemoryBlock(filePath, block) {
+  ensureDir(path.dirname(filePath));
+  const existing = readUtf8IfExists(filePath) || '';
+
+  const beginIndex = existing.indexOf(BEGIN_MARKER);
+  const endIndex = existing.indexOf(END_MARKER);
+
+  if (beginIndex !== -1 && endIndex !== -1 && endIndex > beginIndex) {
+    const before = existing.slice(0, beginIndex);
+    const after = existing.slice(endIndex + END_MARKER.length);
+    writeFile(filePath, `${before}${block}${after}`);
+    return;
+  }
+
+  const trimmed = existing.replace(/\s+$/, '');
+  const next = trimmed ? `${trimmed}\n\n${block}\n` : `${block}\n`;
+  writeFile(filePath, next);
+}
+
+module.exports = {
+  BEGIN_MARKER,
+  END_MARKER,
+  buildCoreMemoryBlock,
+  upsertCoreMemoryBlock
+};

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

@@ -1,154 +1,154 @@
----
-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. 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`.