tai-ch0802/agent-brain

Agent Brain

持久化檔案優先記憶系統。每次 Antigravity session 都會貢獻到一個日益增長的知識庫，以 Markdown 檔案儲存在本地 ~/.agent-brain/，並同步到 pCloud /agent-brain/。

目標

建構一個數位孿生 — 一個隨時間累積所有 session 知識、使用者偏好、專案上下文和決策的代理人。

記憶本體論

所有流經代理人記憶的資訊都被分類成四個本體層次。使用此分類來決定每筆資訊該儲存在哪裡。

四層分類

| 層次 | 代碼 | 本質 | 可變性 | 生命週期 | 對應檔案 | |------|------|------|--------|---------|---------| | 身分 | IDENTITY | 我跟誰共事 | 極少變動（需多次觀察才更新） | 永久 | USER.md | | 知識 | KNOWLEDGE | 我知道什麼 | 累積式、可壓縮 | 長期 (30+ 天) | MEMORY.md | | 經驗 | EXPERIENCE | 我做過什麼 | 不可變（僅增不減） | 歷史記錄 | sessions/*.md | | 狀態 | STATE | 我正在做什麼 | 可自由覆寫 | 當次工作區間 | STATE.md |

分類決策流程

當新資訊出現時，依此決策樹判定路由：

新資訊 →
├─ 是關於使用者本人的偏好或習慣？       → 身分 IDENTITY (USER.md)
├─ 30 天後仍然有用的持久技術事實？       → 知識 KNOWLEDGE (MEMORY.md)
├─ 目前正在處理的任務上下文？            → 狀態 STATE (STATE.md)
└─ 以上皆非，但值得記錄？               → 經驗 EXPERIENCE (sessions/*.md)

各層次寫入規則

| 層次 | 寫入方式 | 同步策略 | 衝突解決 | |------|---------|----------|---------| | 身分 | 覆寫（需多次觀察佐證） | 區段合併 | 取較長版本 | | 知識 | 僅追加持久事實 | 區段合併 | 取較長版本 | | 經驗 | 嚴格僅增不減 | 追加合併 + 去重 | 標頭指紋去重 | | 狀態 | 自由覆寫 | 永不同步（臨時性） | 不適用 |

記憶檔案結構

~/.agent-brain/
├── .env                    # pCloud 認證資訊（永不同步）
├── .sync-manifest.json     # 增量同步用的 SHA256 清單
├── MEMORY.md               # 長期持久事實（知識）
├── USER.md                 # 使用者偏好與行為模式（身分）
├── STATE.md                # 當前工作 session 上下文（狀態）
├── sessions/
│   └── YYYY-MM-DD.md       # 每日 session 日誌（經驗，僅增不減）
├── projects/
│   └── {project-name}.md   # 各專案累積上下文
├── tmp/                    # 衝突解決用暫存目錄（自動清理）
└── brain.db                # SQLite FTS5 索引

檔案角色

| 檔案 | 啟動時載入 | 用途 | |------|:---:|---------| | MEMORY.md | ✅ 完整 | 跨 session 事實、決策、學習心得 | | USER.md | ✅ 完整 | 使用者的編碼風格、工具偏好 | | STATE.md | ✅ 完整 | 上次 session 可恢復的工作上下文 | | sessions/今天.md | ✅ 完整 | 今天的 session 摘要 | | sessions/昨天.md | ✅ 完整 | 昨天的上下文以維持連續性 | | sessions/更早 | ❌ 按需 | 透過 grep 或 brain.db 搜尋 | | projects/*.md | ❌ 按需 | 處理該專案時載入 | | brain.db | ❌ 由腳本 | SQLite FTS5 索引用於記憶搜尋 | | .sync-manifest.json | ❌ 內部 | 追蹤檔案 SHA256 雜湊值用於增量同步 |

Session 啟動程序

在每次 session 執行：

1. 檢查引導：如果 ~/.agent-brain/ 不存在，執行：

   bash ~/.gemini/antigravity/skills/agent-brain/scripts/bootstrap.sh
   

2. 歸檔過期 STATE：如果 ~/.agent-brain/STATE.md 存在：

   • 讀取其 Updated: 時間戳記
   • 如果時間戳記是前一天的（非今天）：將其內容摘要追加到對應的 sessions/YYYY-MM-DD.md 作為歸檔狀態區塊，然後清空 STATE.md
   • 如果時間戳記是今天的：保持原樣（可能是同一工作區間的延續）

3. 載入核心記憶 — 將以下檔案讀入上下文：

   • ~/.agent-brain/MEMORY.md（完整）
   • ~/.agent-brain/USER.md（完整）
   • ~/.agent-brain/STATE.md（完整，如果存在且非空）
   • ~/.agent-brain/sessions/YYYY-MM-DD.md（今天，如果存在）
   • ~/.agent-brain/sessions/YYYY-MM-DD.md（昨天，如果存在）

4. 載入專案上下文（可選）：如果當前工作區明確對應某個專案，檢查 ~/.agent-brain/projects/{project-name}.md 是否存在並載入。

5. 帶著累積的知識上下文，繼續處理使用者的請求。

Session 結束程序

觸發偵測

當使用者表示或暗示 session 結束時，啟動記憶沖刷：

• 顯式：save brain、sync memory、記憶同步、更新記憶
• 隱式：commit、release note、告一段落、今天先到這、收工、結束、下班、先這樣

記憶沖刷步驟（僅限本地）

1. 產生 session 摘要並附加到 ~/.agent-brain/sessions/YYYY-MM-DD.md：

   ## Session HH:MM:SS — {上下文}
   **專案**：[[projects/{name}]]
   **工作區**：{repo 或目錄路徑}
   
   ### 摘要
   {1-3 句話說明完成了什麼}
   
   ### 關鍵決策
   - {決策 1}
   - {決策 2}
   
   ### 學習心得
   - {獲得的新知識}
   
   ### 後續步驟
   - [ ] {未完成的任務}
   

2. 更新 MEMORY.md（如果有新的持久事實出現）：

   • 影響未來 session 的技術決策
   • 發現的跨專案模式
   • 新的架構知識
   • 重要的 URL、憑證位置、環境細節
   • 不要複製 session 級別的細節 — 只提升持久事實

3. 更新 USER.md（如果觀察到新的使用者偏好）

4. 更新 STATE.md — 以當前工作上下文覆寫：

   • 正在進行或剛完成的任務
   • 關鍵變數：活躍分支、目標檔案、正在除錯的錯誤碼
   • 供下次 session 延續的便條筆記

5. 更新 projects/{name}.md，加上今天 session 的交叉連結：

   - YYYY-MM-DD: {簡述} [[sessions/YYYY-MM-DD#session-hhmmss]]
   

   如果檔案不存在則建立，使用 memory-format.md 中的格式。

6. 檢查 MEMORY.md 容量：

   • 如果 MEMORY.md 超過 400 行：警告 ⚠ MEMORY.md 接近上限 (XXX/500 行)。建議壓縮。
   • 如果 MEMORY.md 超過 500 行：觸發壓縮（移除 90 天未引用條目、合併相關條目、將專案細節移至 projects/）

7. 執行索引器：

   python3 ~/.gemini/antigravity/skills/agent-brain/scripts/index-memory.py index
   

注意：Session 結束時不會自動同步至 pCloud。請使用 /upload-brain 推送變更或 /sync-brain 進行完整雙向同步。

記憶回想程序

當使用者詢問過去的工作、決策或歷史時：

1. 特定專案 → 讀取 ~/.agent-brain/projects/{name}.md
2. 特定日期 → 讀取 ~/.agent-brain/sessions/YYYY-MM-DD.md
3. 關鍵字搜尋 → 在 ~/.agent-brain/ 上使用 grep_search
4. 廣泛語意搜尋 → 執行：

   python3 ~/.gemini/antigravity/skills/agent-brain/scripts/index-memory.py search "查詢"
   

pCloud 同步

• API 主機：api.pcloud.com（美國資料中心）
• 遠端路徑：/agent-brain/
• 認證資訊：~/.agent-brain/.env
• 如需 API 詳情，請參考 pcloud 技能

增量同步

同步系統使用 SHA256 清單（.sync-manifest.json）來追蹤已同步的檔案。只有自上次同步以來內容有變更的檔案才會被傳輸。

同步指令

# 檢查同步狀態（預覽模式 — 顯示會有哪些變更，不執行寫入）
bash ~/.gemini/antigravity/skills/agent-brain/scripts/sync.sh status

# 上傳本地變更至 pCloud（增量 — 僅傳輸異動檔案）
bash ~/.gemini/antigravity/skills/agent-brain/scripts/sync.sh push

# 從 pCloud 下載（增量 — 僅傳輸異動檔案）
bash ~/.gemini/antigravity/skills/agent-brain/scripts/sync.sh pull

# 雙向同步（含衝突解決）
bash ~/.gemini/antigravity/skills/agent-brain/scripts/sync.sh sync

衝突解決

當本地和遠端版本的檔案自上次同步後都有變更時：

1. 建立 ~/.agent-brain/tmp/ 暫存目錄
2. 將遠端檔案下載至 tmp/
3. 根據檔案類型進行合併：
   • Session 日誌（sessions/*.md）：追加合併 — 以標頭指紋去重 session 區塊
   • 一般 Markdown（MEMORY.md、USER.md、projects/*.md）：以 ## 標題為 key 的區段級合併 — 雙方獨有的區段都保留，共有區段取較長的版本
   • 其他檔案：以遠端版本為準
4. 合併完成後清理 tmp/
5. brain.db 從頭重建 — 使用 index-memory.py rebuild 重建，brain.db 視為衍生產物，永不直接合併
6. 最終合併結果（含重建的 brain.db）推送至 pCloud

記憶維護規則

1. MEMORY.md 應保持在 500 行以內。如果過大，進行壓縮：移除過時事實、合併相關條目、將舊區段歸檔到 projects/。
2. Session 記錄僅增不減。永不編輯過去的 session 條目。
3. 每個活躍專案一個檔案。透過新增 [ARCHIVED] 前綴歸檔不活躍的專案。
4. 交叉連結一切。Session 參考 [[projects/name]]，專案參考 [[sessions/date]]。
5. 記憶檔案中不放密鑰。認證資訊只放在 .env 中。
6. STATE.md 是臨時性的。不要在 STATE 中儲存持久事實 — 應將其提升至 MEMORY.md。過期的 STATE（來自前一天的）會在下次 session 開始時自動歸檔。
7. STATE.md 永不同步。它僅存在於本地機器，作為短期工作便條簿。

Workflows

Agent Brain 附帶五個全域 workflow，可在 bootstrap 過程中安裝至 ~/.agent/workflows/（也可稍後手動透過 install-workflows.sh 安裝）：

| Workflow | Slash 指令 | 用途 | |----------|-----------|------| | save-brain | /save-brain | 沖刷 session 記憶 → 更新 MEMORY/USER/STATE/projects → 建立索引（僅限本地） | | upload-brain | /upload-brain | 推送本地變更至 pCloud（單向上傳，增量） | | download-brain | /download-brain | 從 pCloud 拉取變更至本地（單向下載，增量） | | sync-brain | /sync-brain | 基於 SHA 增量傳輸的 pCloud 雙向同步（含衝突解決） | | load-brain | /load-brain | 載入 MEMORY.md、USER.md、STATE.md、今日/昨日 session → 載入專案上下文（僅限本地） |

安裝 Workflows

Workflows 會在 bootstrap 過程中自動安裝。如需手動安裝或重新安裝：

bash ~/.gemini/antigravity/skills/agent-brain/scripts/install-workflows.sh

詳細參考

• 記憶檔案格式範本：參閱 memory-format.md
• Session 生命週期詳情：參閱 session-lifecycle.md