memgineering 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -11,6 +11,85 @@ language the reader wants. The bilingual rule the monorepo applies to
 
 ## [Unreleased]
 
+## [0.2.0] — 2026-08-09
+
+The record can say why, and you can see what a memory is actually worth.
+
+### Added
+
+- **`evidence <ref>`** — how much a memory has been used, and why it last
+  changed: how often recall surfaced it, how often anyone opened it, when it
+  was last read, how many times it has been revised, and the reason attached to
+  the most recent change. Every number comes from records that already existed;
+  nothing new is collected, and running it records nothing of its own — so
+  measuring a memory cannot change where `resurface` ranks it.
+- **A standing for each memory** — `well-used`, `surfaced, never opened`, or
+  `never recalled` — computed from usage rather than declared. It is withheld
+  entirely when this machine has no recall history yet, since that log is local
+  state and a brain copied to a new machine starts empty.
+- **`--reason` on every write verb.** `remember`, `exclude`, `unexclude` and
+  `undo` accept one for the first time; `revise`, `retire` and `unretire`
+  already did. The reason on an `undo` is usually the most valuable of the set.
+- **`log` shows the reason** without needing `--verbose`.
+
+### Fixed
+
+- **`revise --reason` and `retire --reason` were silently discarded.** Both
+  flags shipped in 0.1.0, and `retire --help` described the reason as "kept in
+  the record". It was not kept anywhere: only creating a brand-new note ever
+  read the field, so on the ordinary path — changing a note that already exists
+  — the text went nowhere. Reasons given to those commands are now recorded in
+  the operation ledger, where `log` and `evidence` can show them.
+
+- **`recall` now names the language barrier** when a query cannot reach the
+  brain. Search matches text, so an English query never reaches Korean notes
+  however it is worded — and the old zero-result footer suggested broader
+  wording, the one remedy that cannot work. Four testers hit this and came
+  within one command of telling their user the brain held nothing on a subject
+  it had notes about. The warning also appears above results, because the
+  failure is rarely a clean zero: a couple of English scaffolding notes match
+  and look like an answer.
+- **`use` with no argument now says which brain you are on**, and how it
+  resolved — by pointer, by containment, or by being the only one linked. Its
+  own help had always promised this; it reported only whether a pointer file
+  existed, and three testers went and read the config file by hand instead.
+- **`open` no longer tells you to hand-edit frontmatter** when a note states no
+  conclusion. It points at `memgineering revise --claim`, which is the
+  sanctioned path — the previous hint contradicted the bolded rule against
+  editing brain files directly, and a hand edit is invisible to `undo`.
+- **`evidence` no longer implies a well-used memory is a correct one.** A note
+  the repository flatly contradicted was described as backed by the record.
+  Usage is attendance, and where a memory contradicts another the output now
+  says plainly that usage cannot settle which is right.
+- **`evidence` sees a contradiction declared by either note.** The `contradicts`
+  edge lives on whichever note a revise happened to touch, so the warning above
+  fired on only one of the two — and stayed silent on the other, which is the
+  side a reader is more likely to be trusting by mistake.
+- **`evidence` divides the open rate by the number printed beside it.** It used
+  to divide by recalls while `surfaced` also counted resurfacings, so the two
+  figures and the percentage reconciled with none of each other.
+- **`remember --reason` help disambiguated** — it records why you are writing
+  something down, not why the fact is true. One tester nearly filed the
+  substance of a note there, where recall would never show it.
+
+### Changed
+
+- A reason that looks like it contains credential material is refused, with the
+  pattern named and the value never echoed. The ledger travels with the brain,
+  so an unscreened reason would become a permanent synced copy of a secret —
+  and the deny layer that screens notes does not look at the ledger. The write
+  itself is unaffected: rephrase, or drop the flag.
+- Operation records carry a `rationale` field and `rule_version` is now 2.
+  Ledgers written by 0.1.x still read correctly; an older line simply reports
+  no reason given, which is what happened.
+
+### Agent guidance
+
+The bundled hub and the `memgineering-memory` skill now cover `evidence` and
+ask for `--reason` on every write, including the rule that a newer memory does
+not automatically win. **Restart your agent session after upgrading** so the
+new guidance is loaded.
+
 ## [0.1.0] — 2026-08-09
 
 First release. A brain is a folder of your own notes; every agent you use

package/assets/MEMGINEERING.md

@@ -2,7 +2,7 @@
 name: memgineering
 description: Use whenever the user refers to something they told you before, asks what was decided, or tells you something worth keeping. The memory lives in their own folder and outlives this session; check it before answering from guesswork, and write to it when you learn something durable.
 type: skill
-version: 0.1.0
+version: 0.2.0
 ---
 
 # memgineering
@@ -47,17 +47,33 @@ memgineering open <handle> --detail full   # the whole note
 `open` also takes a note's exact title or its path, so you do not need to
 recall first when you already know what you want.
 
+**Check the evidence before trusting an old memory,** or when two of them
+disagree:
+
+```
+memgineering evidence <handle>
+```
+
+How often it has been surfaced, how often anyone read it, when it last changed
+and why. **Newer does not win**: a rule that has stood for eleven months has
+eleven months of nobody contradicting it behind it. Use whether it was actually
+reached for, not its date.
+
 **Remember when you learn something durable** — a decision, a constraint, a
 correction the user made, how something actually works:
 
 ```
-memgineering remember "deploys are manual — launchctl by hand, no CD"
+memgineering remember "deploys are manual — launchctl by hand, no CD" --reason "watched it twice"
 ```
 
 No approval step, by design. It is recorded and reversible (`memgineering
 undo`), so the cost of a wrong entry is one command, not a permanent mistake.
 Do not ask permission for ordinary observations — write them.
 
+**Always pass `--reason`.** Every write verb takes it and it goes in the ledger.
+It is the only part of a record that still means anything to whoever reads it
+six months from now, and it is refused if it looks like it carries a credential.
+
 **Revise when a conclusion changes:**
 
 ```

package/assets/memgineering-memory/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memgineering-memory
-description: Use when the user asks about something they told you before, refers to a past decision, wants their own notes searched, or says something worth keeping. Triggers include "what did I decide about X", "check my notes", "how do we deploy again", "remember this", "예전에 뭐라고 정했더라", "내 노트에서 찾아줘", "이거 기억해둬", "what do you know about my setup". Covers recall, open, remember, revise, undo, and resurface against the user's own brain folder.
+description: Use when the user asks about something they told you before, refers to a past decision, wants their own notes searched, or says something worth keeping. Triggers include "what did I decide about X", "check my notes", "how do we deploy again", "remember this", "is this still true", "which one do I go with", "예전에 뭐라고 정했더라", "내 노트에서 찾아줘", "이거 기억해둬", "what do you know about my setup". Covers recall, open, evidence, remember, revise, undo, and resurface against the user's own brain folder.
 type: skill
 allowed-tools: Bash(memgineering:*)
 ---
@@ -74,20 +74,70 @@ Say so. Only titles, aliases and summaries are searched, so suggest broader
 words — but do not go read their folder yourself to compensate. A brain that
 answers "nothing" is giving you real information.
 
+## Deciding which one to trust
+
+When two memories disagree, or one looks old enough to doubt, do not settle it
+by date.
+
+```
+memgineering evidence deploy-manual
+```
+
+```
+  surfaced       34×  (12× in this folder, 22× elsewhere)
+  opened         12×  (35% of the recalls that surfaced it)
+  last used      3 days ago
+  in the ledger  since 2026-05-02  ·  changed 2×
+
+**well-used** — it has been reached for and read. The record backs it.
+
+why it last changed:
+> CD was removed from the repo
+```
+
+**Newer does not win.** A rule that has stood for eleven months has eleven
+months of nobody contradicting it behind it; a note written last week has a
+week. What separates them is whether either was ever actually used, and what
+the last person to change their mind said. Both are in the output above.
+
+Three standings, and each is a fact rather than a grade:
+
+- **well-used** — recall returned it and somebody read it
+- **surfaced, never opened** — it keeps coming back and nobody reads it. Either
+  it does not answer those questions, or its summary does not say what it knows
+- **never recalled** — nothing has ever surfaced it. It may be perfectly true
+  and simply never needed, but nothing supports it either
+
+If it says this machine has no recall history, the numbers mean nothing yet —
+that log is local, so a brain synced to a new laptop starts empty. Say that
+rather than reporting the memory as unused.
+
 ## Writing things down
 
 ```
-memgineering remember "deploys are manual — launchctl by hand, no CD"
+memgineering remember "deploys are manual — launchctl by hand, no CD" \
+  --reason "watched the deploy happen by hand twice"
 ```
 
 Lands immediately as its own note and is recallable at once. There is no
 approval queue: the design trades permission-before for correction-after, and
 every write records how to reverse it.
 
+**Pass `--reason` on every write.** It goes in the ledger, and it is the only
+part of the record that survives being read six months later by somebody — the
+user, or you in a new session — who no longer remembers the conversation. Every
+write verb takes it: `remember`, `revise`, `retire`, `exclude`, `undo`. The one
+on `undo` is usually the most valuable of all, because it is the moment an
+earlier conclusion turned out to be wrong.
+
+It is refused if it looks like it contains a credential. The ledger travels
+with the brain, so that would be a permanent synced copy — say what changed
+without the value, or drop the flag; the write itself is unaffected.
+
 ```
-memgineering undo              # the last change
+memgineering undo --reason "that belonged to the other project"   # the last change
 memgineering undo <op_id>      # a specific one
-memgineering log               # what has changed, and what can still be undone
+memgineering log               # what changed, why, and what can still be undone
 ```
 
 Write down: decisions and their reasons, constraints, corrections the user
@@ -122,7 +172,7 @@ the user's; neither this command nor you should rewrite it uninvited.
 
 ```
 memgineering retire <ref> --reason "the date moved"   # no longer current, still visible
-memgineering exclude path/to/note.md                  # stop reading it entirely
+memgineering exclude path/to/note.md --reason "names an internal host"   # stop reading it
 ```
 
 Retiring keeps the note in recall, ranked last and labelled. Excluding takes it

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/program.ts
-import { Command as Command16 } from "commander";
+import { Command as Command17 } from "commander";
 
 // src/help.ts
 import { Help } from "commander";
@@ -145,7 +145,7 @@ var COMMAND_GROUPS = [
   {
     title: "MEMORY",
     blurb: "day to day \u2014 what your agent reaches for while working",
-    commands: ["recall", "open", "remember", "revise", "undo", "resurface"]
+    commands: ["recall", "open", "evidence", "remember", "revise", "undo", "resurface"]
   },
   {
     title: "BRAIN",
@@ -2547,12 +2547,36 @@ var OpRecordSchema = z7.object({
   hash_after: z7.string().nullable(),
   /** The frontmatter block region, for reversing a `revise`. */
   patch: z7.object({ before: z7.string(), after: z7.string() }).nullable().default(null),
+  /**
+   * Why this was done, in the words of whoever did it. Never derived.
+   *
+   * Defaulted rather than required so a ledger written by 0.1.x — which had no
+   * such field — still parses. An old line reads as "no reason was given",
+   * which is exactly what happened.
+   */
+  rationale: z7.string().nullable().default(null),
   /** Which generation of the write rules produced this. */
   rule_version: z7.number().int().positive(),
   /** The op this reverses or replaces, when it does. */
   supersedes: z7.string().nullable().default(null)
 });
-var RULE_VERSION = 1;
+var RULE_VERSION = 2;
+var RATIONALE_MAX = 500;
+function sanitizeRationale(raw) {
+  if (raw == null) return null;
+  const clean = stripControl(raw).trim();
+  if (clean === "") return null;
+  const hits = secretContentHits(clean);
+  if (hits.length > 0) {
+    throw memgError(
+      "invalid_input",
+      `the reason looks like it contains credential material (${hits.map((h) => h.code).join(", ")})`,
+      "The ledger travels with the brain, so this would be a permanent synced copy. Say what changed and why without the value itself, or drop --reason \u2014 the write itself is unaffected."
+    );
+  }
+  const capped = clean.length > RATIONALE_MAX ? `${clean.slice(0, RATIONALE_MAX - 1)}\u2026` : clean;
+  return capped;
+}
 function ledgerDir(vaultRoot) {
   return join6(vaultRoot, BRAND.vaultLedgerDir, "ledger");
 }
@@ -2581,6 +2605,7 @@ async function appendOp(vaultRoot, op) {
     hash_before: op.hashBefore,
     hash_after: op.hashAfter,
     patch: op.patch ?? null,
+    rationale: op.rationale ?? null,
     rule_version: RULE_VERSION,
     supersedes: op.supersedes ?? null
   });
@@ -3499,7 +3524,10 @@ function openCommand() {
           );
           printHuman(
             c.gray(
-              "To state one, add frontmatter at the top of the note:\n    ---\n    memgineering:\n      id: kitchen-remodel\n      claim: The kitchen work runs until April 15.\n      contradicts: [kitchen-remodel-march]\n    ---\n`contradicts` is what makes two notes surface as a conflict."
+              `To state one:
+    memgineering revise ${handle} --claim "<the conclusion>" --summary "<one line>"
+Add --contradicts <id> when it disagrees with another memory; that edge is what
+makes the two surface together as a conflict.`
             )
           );
         }
@@ -3928,7 +3956,8 @@ Brain: ${root}`));
 function lifecycleCommand(action) {
   return new Command5(action).description(
     action === "retire" ? "mark a memory as no longer current \u2014 the note itself is not changed" : "mark a retired memory as current again"
-  ).argument("<ref>", "handle, id, path, or exact title").option("--reason <text>", "why \u2014 kept in the record").option("--vault <path>", "which brain the memory is in").action(async (ref, opts) => {
+  ).argument("<ref>", "handle, id, path, or exact title").option("--reason <text>", "why \u2014 kept in the ledger").option("--vault <path>", "which brain the memory is in").action(async (ref, opts) => {
+    const rationale = sanitizeRationale(opts.reason);
     const { brain } = await resolveBrain(opts.vault);
     const adapter = await LocalFileCasAdapter.openVault(brain.root, {
       createPrefix: brain.observationsDir
@@ -4003,6 +4032,7 @@ function lifecycleCommand(action) {
         hashBefore: hashContent(before.content),
         hashAfter: hashContent(outcome.content),
         patch: { before: preview.before, after: preview.after },
+        rationale,
         snapshotBefore: before.content
       });
     });
@@ -4030,7 +4060,8 @@ Undo: \`memgineering undo ${record.op_id}\``));
 function ignoreCommand(mode) {
   return new Command5(mode).description(
     mode === "exclude" ? "stop reading a note entirely \u2014 the note itself is not changed" : "read a note again after excluding it"
-  ).argument("<path>", "path inside the brain, e.g. decisions/launch-date.md").option("--vault <path>", "which brain the note is in").action(async (path, opts) => {
+  ).argument("<path>", "path inside the brain, e.g. decisions/launch-date.md").option("--reason <text>", "why \u2014 kept in the ledger").option("--vault <path>", "which brain the note is in").action(async (path, opts) => {
+    const rationale = sanitizeRationale(opts.reason);
     const { brain } = await resolveBrain(opts.vault);
     const adapter = await LocalFileCasAdapter.openVault(brain.root, {
       createPrefix: brain.observationsDir
@@ -4054,6 +4085,7 @@ function ignoreCommand(mode) {
         hashBefore: hashContent(base.content),
         hashAfter: hashContent(result.content),
         patch: { before: base.content, after: result.content },
+        rationale,
         snapshotBefore: base.content
       });
     });
@@ -4101,12 +4133,170 @@ var unretireCommand = () => lifecycleCommand("unretire");
 var excludeCommand = () => ignoreCommand("exclude");
 var unexcludeCommand = () => ignoreCommand("unexclude");
 
+// src/commands/evidence.ts
+import { Command as Command6 } from "commander";
+function evidenceCommand() {
+  return new Command6("evidence").description("how much a memory has been used, and why it last changed").argument("<ref>", "handle, id, path, or exact title").option("--vault <path>", "which brain to read").action(async (ref, opts) => {
+    const { brain } = await resolveBrain(opts.vault);
+    const adapter = await openBrainOrExplain(brain.root);
+    const built = await openIndex(adapter, brain.root);
+    const entry = resolveRef(built.entries, ref);
+    const [events, ledger] = await Promise.all([readEvents(brain.root), readOps(brain.root)]);
+    const now = /* @__PURE__ */ new Date();
+    const report = assembleEvidence(entry, events, ledger.ops, {
+      contextDir: process.cwd(),
+      now,
+      brain: built.entries
+    });
+    printDual({
+      json: report,
+      human: () => {
+        printHuman(`## evidence: ${entry.memory.title}
+`);
+        printHuman(`\`id: ${report.id}\`  \xB7  \`${report.path}\`
+`);
+        if (report.critical) {
+          printHuman(c.yellow("\u26A0 critical \u2014 this note defines how the agent behaves.") + "\n");
+        }
+        if (!report.brain_has_history) {
+          printHuman(
+            c.yellow("This machine has no recall history for this brain yet.") + c.gray(
+              "\nThe usage numbers below are zero because nothing has been recorded here,\nnot because the memory is unused. The log is local state and does not sync.\n"
+            )
+          );
+        }
+        const rows = [
+          [
+            "surfaced",
+            report.surfaced === 0 ? "never" : `${report.surfaced}\xD7  (${report.surfaced_here}\xD7 in this folder, ${report.surfaced - report.surfaced_here}\xD7 elsewhere)`
+          ],
+          [
+            "opened",
+            report.opened === 0 ? "never" : `${report.opened}\xD7${report.open_rate === null ? "" : `  (${report.opened} of the ${report.surfaced} times it surfaced)`}`
+          ],
+          ["last used", report.last_touched ? ago(report.last_touched, now) : "\u2014"],
+          [
+            "in the ledger",
+            report.first_recorded ? `since ${report.first_recorded.slice(0, 10)}  \xB7  changed ${report.changed}\xD7${report.undone > 0 ? `  \xB7  undone ${report.undone}\xD7` : ""}` : "nothing recorded \u2014 this note predates the ledger, or was only edited by hand"
+          ]
+        ];
+        if (report.declared_from) {
+          rows.push(["declared", `valid from ${report.declared_from.slice(0, 10)}`]);
+        }
+        if (report.supersedes > 0 || report.contradicts > 0) {
+          rows.push([
+            "relations",
+            [
+              report.supersedes > 0 ? `supersedes ${report.supersedes}` : null,
+              report.contradicts > 0 ? `contradicts ${report.contradicts}` : null
+            ].filter(Boolean).join(" \xB7 ")
+          ]);
+        }
+        const pad = rows.reduce((w, [label]) => Math.max(w, label.length), 0) + 2;
+        for (const [label, value] of rows) printHuman(`  ${label.padEnd(pad)}${value}`);
+        if (report.standing) {
+          printHuman(`
+**${report.standing}** \u2014 ${STANDING_MEANS[report.standing]}`);
+        }
+        if (report.contradicts > 0) {
+          printHuman(
+            c.yellow(
+              `
+\u26A0 this memory contradicts ${report.contradicts} other${report.contradicts === 1 ? "" : "s"}.`
+            ) + c.gray(
+              "\n  Both sides can be well-used. Usage cannot settle which one is right \u2014 compare the\n  reasons above, or check something outside the brain."
+            )
+          );
+        }
+        if (report.last_reason) {
+          printHuman(
+            report.last_reason.verb === "remember" ? "\nwhy it was recorded:" : "\nwhy it last changed:"
+          );
+          printHuman(quoteBlock(report.last_reason.text));
+          printHuman(
+            c.gray(`  ${report.last_reason.verb}, ${report.last_reason.ts.slice(0, 10)}`)
+          );
+        } else if (report.changed > 0) {
+          printHuman(
+            c.gray(
+              "\nIt has changed, and no reason was recorded. Pass `--reason` when you write and the next one will say why."
+            )
+          );
+        }
+      }
+    });
+  });
+}
+var STANDING_MEANS = {
+  "well-used": "it gets reached for and read. That is attendance, not correctness.",
+  "surfaced, never opened": "recall keeps returning it and nobody reads it. Either it does not answer those questions, or its summary does not say what it knows.",
+  "never recalled": "nothing has ever surfaced it. It may be true and simply never needed \u2014 but nothing here supports it either."
+};
+function assembleEvidence(entry, events, ops, opts) {
+  const id = entry.memory.id;
+  const surfacing = events.filter(
+    (e) => (e.verb === "recall" || e.verb === "resurface") && e.returned_ids.includes(id)
+  );
+  const opens = events.filter((e) => e.verb === "open" && e.opened_id === id);
+  const touched = [...surfacing, ...opens].map((e) => e.ts).sort().at(-1);
+  const mine = ops.filter((o) => o.target === entry.path || o.memory_id === id);
+  const changed = mine.filter((o) => o.verb !== "undo" && o.verb !== "remember").length;
+  const undone = mine.filter((o) => o.verb === "undo").length;
+  const withReason = mine.filter((o) => o.rationale !== null).at(-1);
+  const relationsOfType = (type) => entry.relations.filter((r) => r.type === type && r.from === id).length;
+  const disputedWith = /* @__PURE__ */ new Set();
+  for (const relation of entry.relations) {
+    if (relation.type === "contradicts" && relation.from === id) disputedWith.add(relation.to);
+  }
+  for (const other of opts.brain ?? []) {
+    if (other.memory.id === id) continue;
+    for (const relation of other.relations) {
+      if (relation.type === "contradicts" && relation.to === id) disputedWith.add(relation.from);
+    }
+  }
+  return {
+    id,
+    path: entry.path,
+    title: entry.memory.title,
+    critical: entry.path.startsWith("01_BASE/"),
+    brain_has_history: events.length > 0,
+    surfaced: surfacing.length,
+    surfaced_here: surfacing.filter((e) => isInside(e.context_dir, opts.contextDir)).length,
+    opened: opens.length,
+    // Divided by the number printed directly above it. It used to be divided by
+    // recalls only, while `surfaced` also counted resurfacings — so a reader saw
+    // two numbers and a percentage that reconciled with neither.
+    open_rate: surfacing.length === 0 ? null : opens.length / surfacing.length,
+    last_touched: touched ?? null,
+    first_recorded: mine[0]?.ts ?? null,
+    declared_from: entry.claims.find((claim) => claim.valid_from)?.valid_from ?? null,
+    changed,
+    undone,
+    supersedes: relationsOfType("supersedes"),
+    contradicts: disputedWith.size,
+    last_reason: withReason ? { verb: withReason.verb, ts: withReason.ts, text: withReason.rationale } : null,
+    // Withheld rather than guessed when the log is empty. "Never recalled" on a
+    // brain that arrived this morning would be a confident wrong answer, which
+    // is the one thing a memory tool must not produce.
+    standing: events.length === 0 ? null : opens.length > 0 ? "well-used" : surfacing.length > 0 ? "surfaced, never opened" : "never recalled"
+  };
+}
+function ago(iso, now) {
+  const days = Math.floor((now.getTime() - Date.parse(iso)) / 864e5);
+  if (!Number.isFinite(days)) return iso;
+  if (days <= 0) return "today";
+  if (days === 1) return "yesterday";
+  if (days < 30) return `${days} days ago`;
+  if (days < 365) return `${Math.floor(days / 30)} months ago`;
+  return `${Math.floor(days / 365)} years ago`;
+}
+
 // src/commands/init.ts
 import { mkdir as mkdir8, readdir as readdir5, writeFile as writeFile6 } from "fs/promises";
 import { join as join13, resolve as resolve6 } from "path";
-import { Command as Command6 } from "commander";
+import { Command as Command7 } from "commander";
 function initCommand() {
-  return new Command6("init").description("create a new brain, laid out and ready to write into").argument("<path>", "where the brain should live").option("--name <name>", "what to call it in the hub", "My brain").action(async (path, opts) => {
+  return new Command7("init").description("create a new brain, laid out and ready to write into").argument("<path>", "where the brain should live").option("--name <name>", "what to call it in the hub", "My brain").action(async (path, opts) => {
     const root = resolve6(path);
     const existing = await readdir5(root).catch(() => null);
     if (existing && existing.filter((e) => !e.startsWith(".")).length > 0) {
@@ -4274,9 +4464,9 @@ function files(name) {
 }
 
 // src/commands/log.ts
-import { Command as Command7 } from "commander";
+import { Command as Command8 } from "commander";
 function logCommand() {
-  return new Command7("log").description("what changed in this brain, and what can still be undone").option("--limit <n>", "how many operations", (v) => parseInt(v, 10), 20).option("--verbose", "include hashes and reverse patches").option("--vault <path>", "which brain to read").action(async (opts) => {
+  return new Command8("log").description("what changed in this brain, and what can still be undone").option("--limit <n>", "how many operations", (v) => parseInt(v, 10), 20).option("--verbose", "include hashes and reverse patches").option("--vault <path>", "which brain to read").action(async (opts) => {
     const { brain } = await resolveBrain(opts.vault);
     const adapter = await openBrainOrExplain(brain.root);
     const { ops, skipped } = await readOps(brain.root);
@@ -4322,6 +4512,7 @@ function logCommand() {
             `- \`${op.op_id}\` ${op.verb} \`${op.target}\`${marks.length ? c.yellow(`  (${marks.join(", ")})`) : ""}`
           );
           printHuman(c.gray(`  ${op.ts} \xB7 ${op.actor}`));
+          if (op.rationale) printHuman(c.gray(quoteBlock(op.rationale, "  > ")));
           if (opts.verbose) {
             printHuman(c.gray(`  ${op.hash_before ?? "\u2205"} \u2192 ${op.hash_after ?? "\u2205"}`));
           }
@@ -4357,6 +4548,7 @@ function summarize(op) {
     verb: op.verb,
     target: op.target,
     memory_id: op.memory_id,
+    rationale: op.rationale,
     supersedes: op.supersedes
   };
 }
@@ -4369,9 +4561,9 @@ async function readOrNull(adapter, path) {
 }
 
 // src/commands/recall.ts
-import { Command as Command8 } from "commander";
+import { Command as Command9 } from "commander";
 function recallCommand() {
-  return new Command8("recall").description("recall memory cards for a question").argument("<query>", "what you want to remember").option("--vault <path>", "which brain to search").option("--scope <scope>", "restrict to one scope").option("--limit <n>", "max cards", (v) => parseInt(v, 10), 8).option("--detail <level>", "title | card | summary | chunks | full (default: card)").action(
+  return new Command9("recall").description("recall memory cards for a question").argument("<query>", "what you want to remember").option("--vault <path>", "which brain to search").option("--scope <scope>", "restrict to one scope").option("--limit <n>", "max cards", (v) => parseInt(v, 10), 8).option("--detail <level>", "title | card | summary | chunks | full (default: card)").action(
     async (query, opts) => {
       const detail = parseDetail(opts.detail, "card");
       const { brain } = await resolveBrain(opts.vault);
@@ -4411,10 +4603,27 @@ function recallCommand() {
           conflicts: result.conflicts
         },
         human: () => {
+          const otherScript = unreachableScript(query, built.entries);
+          const sayWhy = () => {
+            printHuman(
+              c.yellow(
+                `\u26A0 This brain's notes are mostly written in ${otherScript}, and this query is not.`
+              ) + c.gray(
+                `
+  Search matches text, not meaning, so no rewording in another language will reach them.
+  Ask again in ${otherScript}, or run \`memgineering resurface\` to see what is here.
+`
+              )
+            );
+          };
           if (rows.length === 0) {
             printHuman(`## recall: ${query}
 `);
             printHuman("_Nothing matched._\n");
+            if (otherScript) {
+              sayWhy();
+              return;
+            }
             printHuman(
               c.gray(
                 "Only titles, aliases and summaries are searched \u2014 try fewer or broader words, or drop --scope."
@@ -4424,6 +4633,7 @@ function recallCommand() {
           }
           printHuman(`## recall: ${query}  (${rows.length} cards)
 `);
+          if (otherScript) sayWhy();
           for (const [i, { card, handle, stage }] of rows.entries()) {
             printHuman(renderCard(i + 1, card, handle, detail, stage));
           }
@@ -4471,11 +4681,62 @@ function renderCard(n, card, handle, detail, stage) {
   out.push("");
   return out.join("\n");
 }
+function unreachableScript(query, entries) {
+  const queryScripts = scriptsIn(query);
+  if (queryScripts.size === 0) return null;
+  const written = entries.filter((e) => !e.path.startsWith("01_BASE/"));
+  const counts = /* @__PURE__ */ new Map();
+  for (const entry of written) {
+    const script = dominantScriptOf(`${entry.memory.title} ${entry.memory.summary ?? ""}`);
+    if (script) counts.set(script, (counts.get(script) ?? 0) + 1);
+  }
+  if (counts.size === 0) return null;
+  const [dominant, seen] = [...counts].sort((a, b) => b[1] - a[1])[0];
+  if (queryScripts.has(dominant)) return null;
+  return seen >= Math.max(2, written.length / 2) ? dominant : null;
+}
+var SCRIPT_RANGES = [
+  ["Korean", /[가-힣ᄀ-ᇿ]/g],
+  ["Kana", /[぀-ヿ]/g],
+  ["Han", /[一-鿿]/g],
+  ["Cyrillic", /[Ѐ-ӿ]/g],
+  ["Arabic", /[؀-ۿ]/g],
+  ["English", /[A-Za-z]/g]
+];
+function scriptCounts(text) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const [name, pattern] of SCRIPT_RANGES) {
+    const n = (text.match(pattern) ?? []).length;
+    if (n > 0) counts.set(name, n);
+  }
+  const han = counts.get("Han") ?? 0;
+  if (counts.has("Kana")) {
+    counts.set("Japanese", (counts.get("Kana") ?? 0) + han);
+    counts.delete("Kana");
+    counts.delete("Han");
+  } else if (han > 0) {
+    counts.set("Chinese", han);
+    counts.delete("Han");
+  }
+  return counts;
+}
+function dominantScriptOf(text) {
+  const ranked = [...scriptCounts(text)].sort((a, b) => b[1] - a[1]);
+  if (ranked.length === 0) return null;
+  if (ranked.length > 1 && ranked[0][1] === ranked[1][1]) return null;
+  return ranked[0][0];
+}
+function scriptsIn(text) {
+  return new Set(scriptCounts(text).keys());
+}
 
 // src/commands/remember.ts
-import { Command as Command9 } from "commander";
+import { Command as Command10 } from "commander";
 function rememberCommand() {
-  return new Command9("remember").description("write something down now, with no approval step").argument("<text>", "what to remember").option("--vault <path>", "which brain to write to").option("--scope <scope>", "what this is about \u2014 a project, an area").action(async (text, opts) => {
+  return new Command10("remember").description("write something down now, with no approval step").argument("<text>", "what to remember").option("--vault <path>", "which brain to write to").option("--scope <scope>", "what this is about \u2014 a project, an area").option(
+    "--reason <text>",
+    "why you are recording this \u2014 goes in the ledger, not in the note (the fact itself belongs in <text>)"
+  ).action(async (text, opts) => {
     const body = stripControl(text).trim();
     if (body === "") {
       throw memgError(
@@ -4484,6 +4745,7 @@ function rememberCommand() {
         'Pass the text: `memgineering remember "deploys are manual \u2014 launchctl by hand"`'
       );
     }
+    const rationale = sanitizeRationale(opts.reason);
     const { brain } = await resolveBrain(opts.vault);
     await openBrainOrExplain(brain.root);
     const now = /* @__PURE__ */ new Date();
@@ -4519,6 +4781,7 @@ function rememberCommand() {
         memoryId: id,
         hashBefore: null,
         hashAfter: hashContent(content),
+        rationale,
         now
       });
     });
@@ -4562,9 +4825,9 @@ function yamlString(value) {
 }
 
 // src/commands/resurface.ts
-import { Command as Command10 } from "commander";
+import { Command as Command11 } from "commander";
 function resurfaceCommand() {
-  return new Command10("resurface").description("what is worth having in view right now, without being asked").option("--context-dir <path>", "where the work is happening (default: cwd)").option("--limit <n>", "how many cards", (v) => parseInt(v, 10), 5).option("--vault <path>", "which brain").action(async (opts) => {
+  return new Command11("resurface").description("what is worth having in view right now, without being asked").option("--context-dir <path>", "where the work is happening (default: cwd)").option("--limit <n>", "how many cards", (v) => parseInt(v, 10), 5).option("--vault <path>", "which brain").action(async (opts) => {
     const contextDir = opts.contextDir ?? process.cwd();
     const { brain } = await resolveBrain(opts.vault, contextDir);
     const adapter = await openBrainOrExplain(brain.root);
@@ -4690,9 +4953,9 @@ function rank(entries, events, opts) {
 
 // src/commands/revise.ts
 import { readFile as readFile14 } from "fs/promises";
-import { Command as Command11 } from "commander";
+import { Command as Command12 } from "commander";
 function reviseCommand() {
-  return new Command11("revise").description("change a memory's conclusion, and record how to undo it").argument("<ref>", "handle, id, path, or exact title").option("--claim <text>", "what is now true").option("--summary <text>", "the one line recall will show (defaults to the claim)").option("--action <kind>", "reinforce | supersede | conflict", "supersede").option("--contradicts <ids...>", "memories this disagrees with").option("--reason <text>", "why this change is right").option("--because <text>", "the passage from the note that justifies it").option("--input <json>", "the whole change as JSON (file path, `-`, or inline)").option("--dry-run", "show the diff and write nothing").option("--vault <path>", "which brain to write to").action(async (ref, opts) => {
+  return new Command12("revise").description("change a memory's conclusion, and record how to undo it").argument("<ref>", "handle, id, path, or exact title").option("--claim <text>", "what is now true").option("--summary <text>", "the one line recall will show (defaults to the claim)").option("--action <kind>", "reinforce | supersede | conflict", "supersede").option("--contradicts <ids...>", "memories this disagrees with").option("--reason <text>", "why this change is right").option("--because <text>", "the passage from the note that justifies it").option("--input <json>", "the whole change as JSON (file path, `-`, or inline)").option("--dry-run", "show the diff and write nothing").option("--vault <path>", "which brain to write to").action(async (ref, opts) => {
     const { brain } = await resolveBrain(opts.vault);
     await openBrainOrExplain(brain.root);
     const adapter = await LocalFileCasAdapter.openVault(brain.root, {
@@ -4701,6 +4964,9 @@ function reviseCommand() {
     const built = await openIndex(adapter, brain.root);
     const entry = resolveRef(built.entries, ref);
     const input = await buildCommitInput(entry, opts);
+    const rationale = sanitizeRationale(
+      input.reason === NO_REASON_GIVEN ? null : input.reason ?? null
+    );
     const result = commit(asSingleMatch(entry), input);
     if (result.action === "ignore") {
       throw memgError("invalid_input", "nothing to revise", "Pass --claim, or --input with one.");
@@ -4756,6 +5022,7 @@ function reviseCommand() {
         // would build a permanent second copy of something the author may
         // later delete on purpose.
         patch: { before: preview.before, after: preview.after },
+        rationale,
         snapshotBefore: before.content
       });
       return { record, content: outcome.content };
@@ -4788,6 +5055,7 @@ Undo: \`memgineering undo ${applied.record.op_id}\``));
     });
   });
 }
+var NO_REASON_GIVEN = "revised directly";
 async function buildCommitInput(entry, opts) {
   if (opts.input) {
     const raw = await readInput(opts.input);
@@ -4823,7 +5091,7 @@ async function buildCommitInput(entry, opts) {
       relates_to: [],
       contradicts: opts.contradicts ?? []
     },
-    reason: opts.reason ?? "revised directly",
+    reason: opts.reason ?? NO_REASON_GIVEN,
     // The engine refuses to submit without an excerpt, because approving a
     // diff on an assertion alone is not consent. Nothing here is approved by a
     // person, but the requirement still earns its keep: it forces the record
@@ -4890,10 +5158,10 @@ import { access, mkdir as mkdir9, readFile as readFile15 } from "fs/promises";
 import { homedir as homedir3 } from "os";
 import { dirname as dirname3, join as join14 } from "path";
 import { fileURLToPath } from "url";
-import { Command as Command12 } from "commander";
+import { Command as Command13 } from "commander";
 import prompts2 from "prompts";
 function setupCommand() {
-  return new Command12("setup").description("install into your agents, and point at a brain").option("--agent", "non-interactive: take every answer from flags").option("--human", "interactive: choose from a list").option("--tools <list>", "comma-separated: claude, codex, gemini (default: all detected)").option("--auto-update <choice>", "on | off  (default: on, recommended)").option("--hook <choice>", "on | off \u2014 SessionStart resurface, Claude Code only").option("--dry-run", "report what would change, write nothing").option("--silent", "only speak if something changed").action(async (opts) => {
+  return new Command13("setup").description("install into your agents, and point at a brain").option("--agent", "non-interactive: take every answer from flags").option("--human", "interactive: choose from a list").option("--tools <list>", "comma-separated: claude, codex, gemini (default: all detected)").option("--auto-update <choice>", "on | off  (default: on, recommended)").option("--hook <choice>", "on | off \u2014 SessionStart resurface, Claude Code only").option("--dry-run", "report what would change, write nothing").option("--silent", "only speak if something changed").action(async (opts) => {
     const mode = await resolveMode(opts);
     const detected = await detectTools();
     if (detected.length === 0) {
@@ -5258,7 +5526,7 @@ async function exists(path) {
 }
 
 // src/commands/update.ts
-import { Command as Command13 } from "commander";
+import { Command as Command14 } from "commander";
 
 // src/version.ts
 import { readFileSync } from "fs";
@@ -5500,7 +5768,7 @@ function shortMessage(err) {
 
 // src/commands/update.ts
 function updateCommand() {
-  return new Command13("update").description("update memgineering itself").option("--check", "report what is available and change nothing").action(async (opts) => {
+  return new Command14("update").description("update memgineering itself").option("--check", "report what is available and change nothing").action(async (opts) => {
     const status = await checkForUpdate(VERSION);
     const provenance = await detectProvenance();
     const previous = await readUpdateState();
@@ -5608,9 +5876,10 @@ function reportBelowMinimum(below) {
 // src/commands/undo.ts
 import { readFile as readFile17, rm as rm8 } from "fs/promises";
 import { join as join18 } from "path";
-import { Command as Command14 } from "commander";
+import { Command as Command15 } from "commander";
 function undoCommand() {
-  return new Command14("undo").description("take back the last change, or a named one").argument("[op]", "operation id (default: the most recent)").option("--vault <path>", "which brain to act on").action(async (opId, opts) => {
+  return new Command15("undo").description("take back the last change, or a named one").argument("[op]", "operation id (default: the most recent)").option("--reason <text>", "why it is being taken back \u2014 kept in the ledger").option("--vault <path>", "which brain to act on").action(async (opId, opts) => {
+    const rationale = sanitizeRationale(opts.reason);
     const { brain } = await resolveBrain(opts.vault);
     await openBrainOrExplain(brain.root);
     const { ops } = await readOps(brain.root);
@@ -5658,6 +5927,7 @@ function undoCommand() {
         memoryId: target.memory_id,
         hashBefore: actualHash,
         hashAfter: reverted === null ? null : hashContent(reverted),
+        rationale,
         supersedes: target.op_id
       });
     });
@@ -5747,25 +6017,32 @@ The text from before that change is still on this machine: ${join18(snapshotDir(
 
 // src/commands/use.ts
 import { isAbsolute as isAbsolute2, relative as relative2, resolve as resolve8 } from "path";
-import { Command as Command15 } from "commander";
+import { Command as Command16 } from "commander";
+var VIA_MEANS = {
+  flag: "because --vault named it",
+  pointer: `because a \`${BRAND.pointerFileName}\` file here points at it`,
+  cwd: "because this folder is inside it",
+  only: "because it is the only brain linked"
+};
 function useCommand() {
-  return new Command15("use").description("bind this folder (and everything under it) to one brain").argument("[brain]", "path to the brain \u2014 omit to show what this folder resolves to").option("--here <dir>", "write the pointer in this directory instead of the cwd").action(async (brainPath, opts) => {
+  return new Command16("use").description("bind this folder (and everything under it) to one brain").argument("[brain]", "path to the brain \u2014 omit to show what this folder resolves to").option("--here <dir>", "write the pointer in this directory instead of the cwd").action(async (brainPath, opts) => {
     const where = await canonicalize(resolve8(opts.here ?? process.cwd()));
     if (!brainPath) {
       const pointer = await readPointer(where);
+      const resolved = await resolveBrain(void 0, where);
       printDual({
-        json: pointer ? { pointer: pointer.from, brain: pointer.root } : { pointer: null },
+        json: {
+          brain: resolved.brain.root,
+          via: resolved.via,
+          pointer: pointer ? pointer.from : null
+        },
         human: () => {
-          if (!pointer) {
-            printHuman("_No pointer here._\n");
-            printHuman(
-              c.gray(
-                "This folder resolves by containment, or by being the only linked brain.\nBind one explicitly with `memgineering use <brain>`."
-              )
-            );
-            return;
+          printHuman(`Using \`${resolved.brain.root}\`
+`);
+          printHuman(c.gray(`  ${VIA_MEANS[resolved.via]}`));
+          if (resolved.via !== "pointer") {
+            printHuman(c.gray("  Bind this folder explicitly with `memgineering use <brain>`."));
           }
-          printHuman(`\`${pointer.from}\` \u2192 \`${pointer.root}\``);
         }
       });
       return;
@@ -5804,13 +6081,14 @@ A pointer to an unlinked folder would fail on every command instead of at this o
 
 // src/program.ts
 function buildProgram() {
-  const program = new Command16("memgineering").version(VERSION).description("memgineering \u2014 one memory for the AI you connect").option("--json", "emit JSON to stdout instead of markdown", false).hook("preAction", (thisCommand) => {
+  const program = new Command17("memgineering").version(VERSION).description("memgineering \u2014 one memory for the AI you connect").option("--json", "emit JSON to stdout instead of markdown", false).hook("preAction", (thisCommand) => {
     const opts = thisCommand.optsWithGlobals();
     if (opts.json || process.env[BRAND.jsonEnvVar] === "1") setJsonMode(true);
   });
   configureGroupedHelp(program);
   program.addCommand(recallCommand());
   program.addCommand(openCommand());
+  program.addCommand(evidenceCommand());
   program.addCommand(rememberCommand());
   program.addCommand(reviseCommand());
   program.addCommand(undoCommand());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memgineering",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "description": "One memory for the AI you connect. Recall, remember, and revise a brain your agents share — stored in your own folder.",
   "license": "Apache-2.0",