feat(memory): keep a decision's reason and show it in briefings

AGENTS.md

@@ -115,7 +115,7 @@ host is recallable from all of them. Not installed yet? Follow
 | Tool | Purpose |
 |---|---|
 | `work_package` | Prepare one bounded untrusted digest (calendar-selected) or transcript package from the newest Claude Code session under the client's single matching MCP workspace root; submit one strictly validated result for pending human review or defer without durable change. Submission retains bounded redacted source turns for comparison; agents cannot apply or reject, and hashes identify freshness and workspace scope rather than authentication. |
-| `remember` | Store knowledge as an entity with observations, tags, and relations; or pass only `note` (free text) and the title, observations and name are derived; `replace: true` rewrites a named memory, keeping the old version as history |
+| `remember` | Store knowledge as an entity with observations, tags, and relations; or pass only `note` (free text) and the title, observations and name are derived; `replace: true` rewrites a named memory, keeping the old version as history; a new decision, or a `replace` of one, needs `why` (its reason and what would make it stop holding) |
 | `recall` | Search stored knowledge: one or two words match any of them; three or more must all match, falling back to any-word matching only when nothing matches all; ranked by relevance. Empty query lists recent |
 | `forget` | Archive an entity (soft-delete), or remove one observation via the `observation` parameter |
 | `export` | Export memories as portable JSON for sharing or backup |
@@ -147,7 +147,14 @@ host is recallable from all of them. Not installed yet? Follow
   scope that this project's sessions never see.
 - **A mistake with a known cause and fix is a `learn` call** (it creates a
   `lesson_learned`, which later sessions show as a lesson). A choice between
-  options is a `remember` with type `decision`.
+  options is a `remember` with type `decision` and a `why`: the reason for it
+  AND what would make it stop holding ("too heavy to deploy for one user;
+  revisit if we add a hosted tier"). A new decision, or a `replace` of one,
+  without one is refused.
+  Briefings, session start and the durable-memory index show each decision with
+  its reason (or "no reason recorded"), and one nobody has read or added to for
+  30 days as "unconfirmed N days: re-check before relying" — recall it to check
+  it still holds before you follow it.
 - **Reuse a stable `name` to append.** Calling `remember` with an existing
   name appends observations and dedupes tags. A fresh name for every update
   creates duplicates that recall must wade through. A name another project
@@ -156,16 +163,17 @@ host is recallable from all of them. Not installed yet? Follow
   `replace: true` and the `observations` it should now hold (a replace with
   neither `observations` nor `note` is refused, because it would empty the
   memory; to fix only a title, send the current observations with it).
-  `type` is not needed — the memory keeps the one it has.
+  `type` is not needed — the memory keeps the one it has. Replacing a
+  decision needs its `why` again.
   Pass a `type` only to reclassify: one that differs from what is stored
   rewrites it. (`type` is still required on a call with no `note` that is
   not a `replace`, and on a `replace` whose `name` does not exist yet.) Observations are rewritten (tags too
   when you pass them, the title when you pass `title` or `note`); what was
   there moves to `metadata.replaced_history` with the time it was replaced,
   so the wrong line stops showing up in recall but is not lost (recall shows
   only `replaced_history_count`; `export` has the versions).
-- **Replacing a decision**: `remember` the new one with a relation of type
-  `supersedes` pointing at the old — the old entity is archived (recoverable),
+- **Replacing a decision**: `remember` the new one, with its own `why`, and a
+  relation of type `supersedes` pointing at the old — the old entity is archived (recoverable),
   not left active to contradict the new one.
 - **Two memories that cannot both be true**: relation type `contradicts` —
   both then surface as a conflict every time either is recalled.

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to MeMesh are documented here.
 
 ## [Unreleased]
 
+### Changed
+
+- A decision now keeps the reason it was made. `remember` takes `why` (CLI `--why`): the reason for the decision and what would make it stop holding. It is stored as the observation `Why: …`; a reason typed with its own `Why: ` label is stored with one label. Creating a memory of type `decision`, `architecture_decision` or `design_decision` without it — or rewriting one with `replace` — is refused, with a message that names both halves; adding to an existing decision does not need it, and a note file or an `import` is still stored (untrusted, so it appears in the briefing only once trusted), as is an accepted dream proposal. Before, a decision could be stored as a bare conclusion, and the briefing showed only its title, so a later session could not tell whether the reason behind it still applied. The CLI's `fix it with:` command after a quick-form decision now carries `--why`, so copying it is not refused.
+- The briefing, the session-start block and the durable-memory index (`briefing --index`, `GET /v1/briefing-index`) show each decision with its latest `Why:` after the title, or `(no reason recorded)` when it has none, and a decision that nobody has recalled or added to for 30 days with `(unconfirmed N days: re-check before relying)`. Recalling it clears that note. The age counts the newest observation of every decision type, not only `decision`, so `architecture_decision` and `design_decision` are marked too. When a decision line is cut to its budget, the title is clipped first (down to 40 characters), then the reason, and the notes and the `[mem:id]` handle are never cut; a decision whose first observation is a reason shows only its latest reason, once. A read or observation dated in the future is ignored, and a decision with no observation is aged from its creation in the ranked block as in the index.
+- The Hermes and OpenClaw extensions pass `why` through. Hermes returns the server's own sentence when a write is refused, as OpenClaw's `memory_store` does, instead of a bare status line; both say `why` is required for `decision`, `architecture_decision` and `design_decision`. The decision-nudge and "remember this" hooks tell the agent a decision needs `why`, and the documentation's `remember` examples for a decision carry one.
+
 ### Fixed
 
 - A host that stalled past its router lease (a laptop that slept, for example) now registers again when the router answers one of its requests (a heartbeat, for example) with `stale_generation`, waiting longer each time the router keeps doing so. Before, it stayed connected and silent: the router no longer listed it or delivered to it, and nothing was reported.

README.md

@@ -145,7 +145,7 @@ Full command and tool reference: [docs/api/API_REFERENCE.md](docs/api/API_REFERE
 | Tool | What it does |
 |------|-------------|
 | `work_package` | Prepare one bounded untrusted calendar digest or Claude Code transcript package under one matching MCP workspace root; submit one strict result for pending human review, or defer without durable change. Transcript submission retains bounded redacted source turns; no file path, hidden reasoning, provider, embedding, or vector data is exposed. |
-| `remember` | Store knowledge as observations, relations and tags — or pass free text as `note` and the title, observations and name are derived; `replace` corrects a memory in place |
+| `remember` | Store knowledge as observations, relations and tags — or pass free text as `note` and the title, observations and name are derived; `replace` corrects a memory in place; a new decision needs `why` (its reason, and what would make it stop holding) |
 | `recall` | Local FTS5 search with multi-factor scoring (relevance, recency, frequency, confidence, recall impact) |
 | `forget` | Soft-archive (never deletes) or remove specific observations |
 | `export` | Back up, migrate, or move memories as JSON between compatible agents |

README.zh-TW.md

@@ -147,7 +147,7 @@ memesh serve           # 啟動本機 server 並印出儀表板網址
 | 工具 | 做什麼 |
 |------|--------|
 | `work_package` | 準備一份有界限且不受信任的日曆摘要，或從唯一符合的 MCP workspace root 準備 Claude Code transcript 套件；提交一份嚴格結果等待人工審核，或延後而不產生耐久變更。Transcript 提交會保留有界且已遮蔽的來源輪次；不會暴露檔案路徑、隱藏推理、provider、embedding 或 vector 資料。 |
-| `remember` | 用觀察、關係和標籤儲存知識；也可以只給一段自由文字（`note`），標題、觀察和名稱會自動推導出來；`replace` 則是直接改掉既有的那一筆 |
+| `remember` | 用觀察、關係和標籤儲存知識；也可以只給一段自由文字（`note`），標題、觀察和名稱會自動推導出來；`replace` 則是直接改掉既有的那一筆；新的決策（`decision`）一定要附 `why`（為什麼這樣決定，以及什麼情況下就不成立了） |
 | `recall` | 本機 FTS5 搜尋，包含多因素評分（相關性、近期性、頻率、信心、回憶影響） |
 | `forget` | 軟歸檔（永不刪除）或移除特定觀察 |
 | `export` | 以 JSON 備份、搬遷記憶，或在相容代理之間轉移 |