你的 coding agent 會忘事,給它一個不會忘的大腦

一個開放的專案記憶標準——把專案的持久知識寫成純 Markdown,任何 coding agent 都能透過一個小巧的 CLI 讀寫,並隨你跨 agent、跨機器、跨模型一路帶著走。

·Joyqi·1 分鐘閱讀

你花了一個下午,和一個 coding agent 把一件真正要緊的事敲定:為什麼選 Markdown 而不是 SQLite、為什麼砍掉方案 B、這一版的「做完」到底指什麼。推理很扎實,取捨權衡過了,結論也拍板了。

然後,這個 session 結束了。

隔天開一個新的 session——或者換台機器、從 Claude Code 切到 Codex——agent 又把同樣的問題問了一遍:這個專案是做什麼的?為什麼不用 B?這個我們不是早就定了嗎?不是模型不行,只是它從來沒有一個能持久存放結論的地方。程式碼留下了,背後的「為什麼」卻蒸發進了一段再也沒人打開的聊天記錄。

所以我們針對這塊缺口做了一個小標準,並把它開源:brain.md。

它是什麼

brain.md 給專案一個大腦——它的持久決策、需求與約束,寫成純 Markdown,留在儲存庫裡,熬過每一次 session。

開箱即得兩樣東西:

  • 一份契約 —— 專案根目錄下一個 BRAIN.md 檔案,告訴任何 coding agent 這個大腦該怎麼用。agent 只要讀這個檔案,就知道該怎麼用它。
  • 一套工具 —— 一個小巧的 brain CLI,外加幾個裝一次就好的 skill,負責搭建與維護這個大腦。

大腦本身只是儲存庫裡的一堆 Markdown 檔案——動手前不需要先啟動任何服務。它脫胎於 MindMux——我們的專案大腦工作台,MindMux 透過 MCP 等一整套能力來驅動大腦。而 brain.md 是其中開放的那一層:格式與契約,讓任何能讀檔案的 agent 都能擁有一個大腦——搭配 MindMux,或者只用你的編輯器和一個終端機,都行。

一個大腦長什麼樣

它是一個裝著 Markdown 的 brain/ 目錄,裡面有兩種檔案。

Root pages(根頁面) —— 固定六個,一眼看清整個專案:background、architecture、flow、mindmap、stack、roadmap。這些只更新,不新建。

Pages(頁面) —— 每個承載一個持久的知識單元:一個決策、一個概念、一個人、一份參考。邊走邊建,數量不限,沒有繁文縟節。

一個頁面之所以不只是「便籤」,靠的是它的結構。每個頁面有兩層:

  • compiled_truth —— 當前最佳理解,可以整體重寫。
  • timeline —— 只增不改的軌跡,記錄這個理解是怎麼形成的。

一層讓你往前走,一層讓你能回溯。當你推翻過去的判斷時,你不會偷偷改掉歷史——而是往 timeline 追加一條 reversal,讓這次「改主意」留在記錄裡。

設計賭注:檔案 + 一個 CLI

這些單獨拎出來都不是新點子。AGENTS.md 和 CLAUDE.md 早就能給 agent 下常駐指令。brain.md 的賭注更窄,但我覺得更有用:讓記憶有結構,並且 correct by construction(從構造上就保證正確)。

機制是這樣的:讀和寫都走 brain CLI——你永遠不手動編輯大腦檔案。聽起來像個限制,其實這正是關鍵。因為 CLI 是唯一的寫入者:

  • frontmatter 永遠由程式生成,不會變形為無效格式。
  • 重寫 compiled_truth 和往 timeline 追加那一條,發生在同一次原子寫入裡——所以理解絕不可能在不留痕跡的情況下被改動。

第二條才是要害。一個知識庫最常見的腐爛方式,是一次悄無聲息的編輯:有人改了結論,背後的理由卻丟了。把每次寫入都收斂到一條命令上,這種失敗模式就在結構上不可能發生。brain.md 裡沒有 validator,因為已經沒什麼需要 validator 去兜底的了。

到底有什麼不同

如果你用過相近的工具,這裡是誠實的對比。

  • 對比扁平的 CLAUDE.md / rules 檔案 —— 它們很適合放指令,但那是一大團你手工維護、不斷膨脹的文字。大腦是有結構、可定址的知識,自帶稽核軌跡。是不同的活兒。
  • 對比活在某個工具裡的記憶 —— 向量庫、模型自帶的記憶、託管服務:它們是建構在你知識之上的 runtime。而大腦是知識本身那一層——git 裡的純檔案,能在 PR 裡 diff,人、agent 或 grep 都能讀。在它上面加一層 runtime(MindMux 就這麼做,走 MCP;更多工具也可以),知識依然屬於儲存庫,而不是工具。
  • 對比存聊天記錄 —— 聊天記錄是過程,大腦是結論。你要的不是把每句原話找回來,而是那少數幾條你以後還用得上的判斷。

也不綁死在某個模型或工具上。契約是一個檔案,所以同一個大腦在 Claude Code、Codex,以及你下一個要用的東西之間通用。

看它跑起來

工具裝一次:

./setup        # 把 skills 接到你選中的每個 agent(~/.claude、~/.codex、…)

然後在任何專案裡,agent 會搭好並播種一個大腦(brain-setup,再 brain-bootstrap),接下來就自然而然了。真正的回報體現在跨 session的時候:

你     設定就用 Markdown 存,別用 SQLite —— 更好 diff,遷移也省事。

Agent  這就把它記成一條 decision,讓它熬過這次 session。
       $ brain create-page --id config-as-markdown --category decision \
             --title "Store config as Markdown, not SQLite"
       ✓ page created · indexed

—— 三週後,一個全新的 session ——

你     設定為什麼不用資料庫?

Agent  $ brain read-page config-as-markdown
       我們當初選 Markdown 是為了好 diff、零遷移。這是最初的決定,
       以及我們權衡過的取捨……

不用再解釋一遍。下一段對話直接從你已經敲定的地方接著走。

試試看

大腦是專案的記憶,不是某個模型的記憶。下個月換一個 agent,留下來的還是這個大腦。

如果這正是你遇到的問題,大概五分鐘就能體會到:

如果你注意到的第一件事是「這些我居然不用再解釋一遍了」,那它就生效了。這就是我們做它的原因。

Share to