--- name: mem-save description: Save a decision from this conversation into the development memory. Use when a decision was just made, when the user says to remember something, when the user wraps up and wants this session's decisions collected (收工、整理這次的決定), or when asked to record why an approach was chosen or rejected. --- # Save a development memory Records are what you, or your team, read six months from now. A record without the reason is close to useless. ## 1. Draft the record Write it in the language the conversation used, and keep three things in the body: - **原因 / Why**: what forced the decision — the constraint, the bug, the number that was too slow. - **決定 / Decision**: what will happen now, concretely. Name the files, tables, fields or flags. - **放棄 / Rejected**: the option that was not taken and why. This is the part people forget and the part that saves the most time later. Keep the title short and searchable: the subject, then what changed. Pick a `type`: | type | when | |---|---| | `decision` | a choice between options, with a reason | | `feature` | how something was built across one or more repos | | `runbook` | steps to operate or recover something | | `note` | context worth keeping that fits nothing above | ## 2. Show it to the user first Print the draft and ask for corrections. Never save a record the user has not seen. ## 3. Save it Pipe the JSON into the CLI from the repository you are working in, so the repo and branch are picked up: ```bash cat <<'JSON' | bun "${CLAUDE_PLUGIN_ROOT}/src/cli.ts" record { "type": "decision", "title": "匯出報表改成單筆失敗不中斷", "body": "原因:整批 rollback 會讓已完成的匯出重跑\n決定:失敗的列寫進 failedRows,整批繼續,最後回報\n放棄:維持整批 rollback", "product": "billing", "entities": [{"kind": "table", "name": "export_job"}], "files": [{"repo": "example-org/example-repo", "path": "src/export/Runner.java"}] } JSON ``` `type`, `title` and `body` are required; everything else is optional. `author`, `repos`, `branch` and the timestamp are filled in automatically. Saving the same title and body twice is a no-op, so it is safe to retry. `repos` also decides whether the card can ever reach the team repo: only cards saved in a code repo that the team repo's `repos.yaml` lists are submitted. When saving from somewhere else a card that belongs to that team, set `repos` explicitly. ## 4. Confirm Show the returned id, and tell the user where the record lives in the words the CLI's last line uses: local until it is submitted to the memory repo, or, in personal mode, only on this machine. ## Collecting a whole session When the user wraps up (收工、整理這次的決定、把今天的決定存起來), go through this conversation once instead of one decision at a time: 1. List every decision made in it, numbered, one line each: what was decided and why, in a few words. Leave out ideas that were dropped along the way. Search the memory first and mark the ones already saved as cards. 2. Let the user pick which ones to keep. 3. Draft a card for each pick, in the three parts above, and show them all together. 4. Save the ones the user approves, one `record` call each, and list the ids. Never invent a reason the conversation does not contain: write 待補 and let the user fill it in. ## Filing an answer back The same flow works for a question you just answered from the memory. If the answer took real digging — you pieced it together from several records or from raw conversation — and no document already says it, offer to save it as a `note`: - **title**: the question, in the words someone would ask it again - **body**: the answer, then where it came from (record ids, files, commits) Do not file answers that only restate an existing document, and do not file anything the user did not agree to. A note is raw material, not a document: the next document written on that subject draws on it. Never offer to turn one answer into a document of its own. ## Notes - Search before saving (`memory_search`, or `bun "${CLAUDE_PLUGIN_ROOT}/src/cli.ts" search `): if a record already covers this, update the story in a new record and mention which one it supersedes with `"supersedes": ""`. - Secrets, credentials and personal data never belong in a record. - Nothing here pushes to git. Submitting records to the team repo is a separate, explicit step the user runs.