BHGBrain：為你的 AI 代理打造共享、持久的記憶體

你使用的每個 AI 程式開發代理，Claude Code、Codex、Copilot、Gemini，每次對話都從失憶開始。昨天的除錯突破、上週的架構決策、三個 sprint 前團隊達成的編碼標準，全沒了。你要嘛重新解釋一切，要嘛期望代理從湊巧開啟的檔案推論出來。

這是當前代理工作流程最大的摩擦點。不是模型品質。不是工具整合。是記憶。

BHGBrain 是我們的答案：一個開源 MCP 伺服器，為你的 AI 代理提供持久、可搜尋、共享的第二大腦。

問題：每個代理都是金魚

若你曾用 AI 程式開發代理做過實際專案，就知道這個模式：

1. 上午對話：你解釋架構、限制與慣例。代理表現優異。
2. 下午對話：新上下文視窗。代理建議了你四小時前要它避免的那個模式。
3. 隔天：另一個代理（也許是 Codex 跑背景任務）對 Claude Code 昨天學到的內容毫無所知。

權宜之計很脆弱：

• MEMORY.md 檔案用到 500 行就開始在每則訊息吃掉 15% 的上下文視窗。
• 系統提示是靜態的，無法捕捉演進中的知識。
• 對話記錄是代理專屬且不可搜尋的。
• 手動重新解釋正是我們當初用代理想避免的事。

根本問題在於：每個代理有自己的瞬時上下文，且彼此互不相通。

BHGBrain 做了什麼

BHGBrain 是 MCP 伺服器，意味任何相容 MCP 的 AI 客戶端都能將其作為工具連接。它暴露一組簡單操作：

在底層，每筆記憶都會獲得：

• 向量嵌入存於 Qdrant 供語意搜尋
• 元資料與全文索引存於 SQLite 供快速過濾與關鍵字搜尋
• 自動去重，若你重複告訴它同一件事，會合併而非複製
• 類型分類，記憶分為情節（事件）、語意（事實）或程序（工作流程）

寫入管線

當代理呼叫 remember 時，BHGBrain 不會只是把文字倒進資料庫。它執行多階段管線：

1. 提取，LLM 將原始輸入拆解為原子記憶候選項，並推論類型、標籤與重要性分數。
2. 決策，每個候選項與同命名空間的既有記憶比較。系統決定：ADD（新知識）、UPDATE（精煉既有）、DELETE（使舊資訊失效）或 NOOP（已知）。
3. 儲存，被接受的記憶進行嵌入、索引並持久化。

若提取模型不可用，BHGBrain 會回退到使用內容雜湊與餘弦相似度閾值的確定性去重。它絕不會默默丟棄記憶。

讀取路徑

當代理需要上下文時，呼叫 recall 或 search：

• 語意搜尋依意義找記憶（「本專案的驗證如何運作？」）
• 全文搜尋找精確詞彙（「OIDC federated credentials」）
• 混合搜尋透過 Reciprocal Rank Fusion 結合兩者（預設 70% 語意、30% 全文）

此外還有 memory://inject，一個特殊的 MCP 資源，會在對話開始時交付一塊預算控制的上下文區塊，讓代理無需手動提示即以相關知識啟動。

為何共享大腦改變一切

真正的力量不在於單一代理能記住事情。而在於你所有的代理共享同一份記憶。

情境：多代理開發

你在專案上運行三個代理：

• Claude Code 用於 IDE 內互動開發
• Codex 用於背景任務（測試產生、重構）
• OpenClaw 用於營運與部署自動化

沒有共享記憶，每個代理各自為政。Claude Code 學會你的命名慣例；Codex 產生違反慣例的測試。OpenClaw 部署的設定與 Claude Code 昨天記錄的架構決策相抵觸。

有了 BHGBrain，當 Claude Code 儲存「所有 API 路由使用 kebab-case 並回傳 RFC 7807 problem details」時，Codex 会在下次 recall 取得並產生合規測試。OpenClaw 的部署腳本也對齊相同慣例。一筆記憶，三個代理，零漂移。

情境：入職與知識轉移

新團隊成員報到。與其讀 40 頁 wiki 文件（一半過時），他們將 AI 代理連到團隊的 BHGBrain 實例。代理立即能存取：

• 架構決策及其理由
• 編碼標準與具體範例
• 已知陷阱與解決方法
• 專案特定術語

BHGBrain 隨附的 bootstrap 提示會帶領走過一段結構化的 10 段訪談，涵蓋身份、職責、目標、工具、實體地圖與運作規則，約 30 分鐘內建立完整的工作畫像。

情境：跨儲存庫延續

跨多個儲存庫工作（微服務、monorepo 拆分或多組織諮詢常見）？BHGBrain 的命名空間與集合系統讓知識井然有序：

• 命名空間 project-alpha 持有該專案特定記憶
• 命名空間 global 持有跨切面標準
• 命名空間內的集合將相關記憶分組（如 api-design、infrastructure、security）

代理自動查詢正確範圍。無交叉污染，無上下文遺失。

架構：簡單且自架

BHGBrain 在你的機器或你的基礎架構上運行。除了嵌入 API 外無雲端依賴（且即便這也是可選的，可用本地模型）。

MCP Clients (Claude / Codex / OpenClaw / etc.)
  → MCP transport (HTTP or stdio)
  → BHGBrain server
      → Write pipeline (extraction + dedup + decision)
      → Qdrant (vector search)
      → SQLite (metadata, fulltext, categories, audit log)

需求：

• Node.js 20+
• Qdrant（Docker 一行指令：docker run -d --name qdrant -p 6333:6333 qdrant/qdrant）
• OpenAI API 金鑰（供嵌入），或使用 Ollama 搭配 nomic-embed-text 達成完全本地運行

安裝並執行：

git clone https://github.com/Big-Hat-Group-Inc/BHGBrain.git
cd BHGBrain
npm install && npm run build
export OPENAI_API_KEY=sk-...
export BHGBRAIN_TOKEN=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
node dist/index.js

就這樣。你的代理現在可透過 stdio（本地）或 HTTP（網路）連接。

預設企業就緒

BHGBrain 不是玩具。它從第一天起就以生產環境考量打造：

• 驗證：非回送 HTTP 連線需 Bearer Token。失敗即關閉，若 token 環境變數未設定且繫結至非回送位址，伺服器拒絕啟動。
• 速率限制：預設每客戶端每分鐘 100 請求。
• 稽核日誌：每次寫入與刪除都記錄時間戳、命名空間、客戶端 ID 與操作類型。
• 機密掃描：記憶儲存前檢查憑證模式。疑似機密會被拒絕。
• 備份與還原：完整 SQLite + Qdrant 快照，含完整性驗證。
• 優雅降級：若 Qdrant 故障，讀取回退至 SQLite 全文。若嵌入 API 不可用，伺服器進入降級模式而非崩潰。
• 結構化日誌：JSON 日誌，含自動 token 與內容遮蔽。

5 分鐘上手

1. 啟動 Qdrant

docker run -d --name qdrant -p 6333:6333 qdrant/qdrant

2. 安裝 BHGBrain

git clone https://github.com/Big-Hat-Group-Inc/BHGBrain.git
cd BHGBrain && npm install && npm run build

3. 設定你的代理

對於 Claude Desktop，加入 claude_desktop_config.json：

{
  "mcpServers": {
    "bhgbrain": {
      "command": "node",
      "args": ["/path/to/BHGBrain/dist/index.js"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

對於 HTTP 客戶端（OpenClaw、mcporter、遠端代理）：

{
  "mcpServers": {
    "bhgbrain": {
      "transport": "http",
      "url": "http://127.0.0.1:3721",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

4. 開始記憶

請你的代理記住某件事：

「記住：我們的 API 使用 kebab-case 路由，回傳 RFC 7807 problem details，且所有端點都要求 Bearer Token 驗證。」

BHGBrain 儲存它，分類為 semantic，加上適當標籤，並透過 recall 供每個連線的代理使用。

5. 啟動你的大腦

執行隨附的 bootstrap 訪談以建立完整工作畫像：

# Paste the contents of BootstrapPrompt.txt into a fresh AI conversation
# The agent will interview you across 10 sections and produce a structured profile

進階使用者的 CLI

BHGBrain 含完整 CLI 供直接管理：

bhgbrain search "authentication patterns" --mode hybrid
bhgbrain list --limit 20
bhgbrain category set "Coding Standards" --file ./standards.md
bhgbrain stats
bhgbrain gc --consolidate    # Merge similar memories, flag stale ones
bhgbrain backup create

何時用 BHGBrain 與 MEMORY.md

MEMORY.md 適用於單一代理、單一專案、少量筆記。BHGBrain 適用於團隊、多代理工作流程，以及 AI 記憶需求已超出文字檔的任何人。

下一步

BHGBrain v1 著重於把核心做對：可靠儲存、智慧去重、混合搜尋與多客戶端存取。路線圖包含：

• 多使用者 RBAC — 團隊層級存取控制
• 靜態加密 — 供受監管環境
• 雲端同步 — 跨機器的選用同步
• 工作記憶 TTL — 自動到期的短期草稿記憶

試試看

BHGBrain 為開源，採 MIT 授權。

GitHub： github.com/Big-Hat-Group-Inc/BHGBrain

若你的 AI 代理老是不記得你昨天說的話，給它們一顆持久的大腦吧。

Kevin Kaminski 是 Big Hat Group 的創辦人，我們在此打造圍繞企業 AI、Windows 365 與雲端基礎架構的工具與諮詢實務。BHGBrain 源自我們對日常多代理工作流程中代理失憶的挫折。