brain.md

brain.md 概覽

這是什麼

brain.md 是一個持久化、基於檔案的記憶層，專為編碼代理設計。它提供一個開放、與代理無關的標準，以純 Markdown 捕捉專案的持久知識，並透過零依賴的 CLI 讀寫。這個「大腦」存在於儲存庫中，可跨代理、機器和模型移動。工具包會建立 BRAIN.md 協定檔案和 brain/ 目錄，並將代理設定檔預設接入儲存庫。任何能讀取檔案的編碼代理，只要讀取專案的 BRAIN.md（純 Markdown）即可使用這個大腦。

主要功能

• 儲存庫原生 — Markdown 存在於專案中，隨 git 移動，無論是否有上層執行環境。
• 與代理無關 — 合約是一個檔案（BRAIN.md）。任何能讀取它的代理都能使用大腦。
• 建構即正確 — 每次寫入都透過 brain CLI，因此大腦的不變性不會因格式錯誤的編輯而破壞。不需要驗證器。
• 編譯真相與僅附加時間線 — 每個頁面包含可重寫的 compiled_truth（當前最佳理解）以及僅附加的 timeline（證據鏈）。update-truth 在一次原子寫入中重寫真相並附加時間線條目。
• Claude Code 與 Codex 的生命週期鉤子 — brain install-hooks 安裝工作階段啟動鉤子，自動載入大腦上下文。
• 零依賴 Node CLI — brain 指令以 node 執行，無外部依賴。

使用情境

• 跨編碼工作階段持久化持久決策、需求和約束，使其在工作階段結束後仍然存在。
• 讓新的編碼代理無需從零開始即可存取專案的歷史與理由。
• 記錄難以僅從程式碼重構的知識（例如為何未選擇某條路徑、權衡的取捨）。

快速開始

全域安裝工具（無需複製儲存庫）： bash npm install -g @mindmux/brain-md brain setup -y 或使用 npx（不會將 brain 留在 PATH 上）： bash npx @mindmux/brain-md setup -y 初始化專案（在專案根目錄）： bash brain init 初始化後，會建立 BRAIN.md 和 brain/ 目錄，並將代理設定檔（CLAUDE.md、AGENTS.md）預設接入。

授權與價格

採用 Apache-2.0 授權。開源。

內容整理自該專案公開的 README 與儲存庫資訊。