深入解析 Clawdbot 的記憶系統架構：從 Context 與 Memory 的差異、兩層記憶結構、向量搜尋機制，到 Compaction 壓縮與 Memory Flush 防丟失機制，完整了解 AI 助理如何實現 24/7 持久記憶。

什麼是 AI 記憶系統？

AI 記憶系統是讓 AI 助理能夠跨對話、跨時間保留重要資訊的機制，使得每次對話不再是從零開始，而是能延續之前的脈絡與決策。

與 ChatGPT 或 Claude 的雲端記憶不同，Clawdbot 採用完全本地化的記憶架構：

  • 所有記憶以 Markdown 檔案 儲存在本機
  • 使用者擁有完整的資料控制權
  • 可手動編輯、版本控制
  • 支援語意搜尋快速檢索

Context vs Memory：關鍵差異

理解 Clawdbot 記憶系統的第一步，是區分 Context（上下文） 與 Memory（記憶）。

Context（上下文）

Context 是模型在單次請求中看到的所有內容：

1
Context = System Prompt + 對話歷史 + 工具結果 + 附件
特性說明
短暫性僅存在於當次請求
有限制受模型 Context Window 限制（如 200K tokens）
有成本每個 token 都計入 API 費用

Memory（記憶）

Memory 是儲存在磁碟上的持久資料：

1
Memory = MEMORY.md + memory/*.md + Session 記錄
特性說明
持久性重啟後仍然存在，可保留數月、數年
無限制可無限成長
低成本儲存不產生 API 費用
可搜尋透過向量索引進行語意檢索

兩層記憶架構

Clawdbot 採用兩層記憶系統，分別處理短期與長期記憶：

1
2
3
4
5
6
~/clawd/
├── MEMORY.md              # Layer 2: 長期記憶
└── memory/
    ├── 2026-01-27.md      # Layer 1: 今日筆記
    ├── 2026-01-26.md      # 昨日筆記
    └── ...

Layer 1：每日筆記 (memory/YYYY-MM-DD.md)

這是 AI 在一天中持續記錄的筆記，採用 Append-only 模式：

1
2
3
4
5
6
7
8
9
10
11
# 2026-01-27

## 10:30 AM - API 討論
討論 REST vs GraphQL 架構。決定：使用 REST 簡化實作。
主要端點：/users, /auth, /projects

## 2:15 PM - 部署
部署 v2.3.0 到 production，無異常。

## 4:00 PM - 使用者偏好
使用者提到偏好 TypeScript 勝過 JavaScript。

寫入時機：

  • 使用者說「記住這個」
  • AI 判斷為重要資訊
  • 系統自動觸發（Compaction 前）

Layer 2：長期記憶 (MEMORY.md)

這是經過整理的持久知識庫：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Long-term Memory

## 使用者偏好
- 偏好 TypeScript 勝過 JavaScript
- 喜歡簡潔的解釋
- 目前專案：Acme Dashboard

## 重要決策
- 2026-01-15: 選擇 PostgreSQL 作為資料庫
- 2026-01-20: 採用 REST 而非 GraphQL
- 2026-01-27: 使用 Tailwind CSS

## 重要聯絡人
- Alice ([email protected]) - 設計主管
- Bob ([email protected]) - 後端工程師

寫入時機：

  • 重大決策
  • 長期有效的偏好設定
  • 重要的學習經驗

記憶工具

Clawdbot 透過兩個專用工具存取記憶：

memory_search：語意搜尋

搜尋所有記憶檔案，找出相關內容：

1
2
3
4
5
6
7
8
{
  "name": "memory_search",
  "parameters": {
    "query": "我們之前討論的 API 架構是什麼？",
    "maxResults": 6,
    "minScore": 0.35
  }
}

回傳結果：

1
2
3
4
5
6
7
8
9
10
11
{
  "results": [
    {
      "path": "memory/2026-01-20.md",
      "startLine": 45,
      "endLine": 52,
      "score": 0.87,
      "snippet": "## API 討論\n決定使用 REST 而非 GraphQL..."
    }
  ]
}

memory_get：讀取特定內容

根據搜尋結果讀取完整內容：

1
2
3
4
5
6
7
8
{
  "name": "memory_get",
  "parameters": {
    "path": "memory/2026-01-20.md",
    "from": 45,
    "lines": 15
  }
}

向量索引機制

當記憶檔案被儲存時，Clawdbot 會自動建立向量索引：

1
2
3
4
5
6
7
8
9
10
11
12
13
1. 檔案儲存
   │
   ▼
2. File Watcher 偵測變更（1.5 秒 debounce）
   │
   ▼
3. Chunking（~400 tokens/chunk，80 tokens 重疊）
   │
   ▼
4. Embedding（透過 OpenAI/Gemini 產生向量）
   │
   ▼
5. 儲存至 SQLite（向量 + 全文索引）

混合搜尋策略

Clawdbot 同時使用兩種搜尋策略：

策略用途權重
Vector Search語意相似（「那個資料庫的事」）70%
BM25 Keyword精確匹配（「POSTGRES_URL」）30%

最終分數計算：

1
finalScore = (0.7 × vectorScore) + (0.3 × textScore)

這確保無論搜尋概念性問題還是精確關鍵字，都能獲得好結果。

Compaction：Context 壓縮

當對話接近 Context Window 限制時，Clawdbot 會觸發 Compaction：

1
2
3
4
5
6
7
8
9
壓縮前：
[Turn 1-140] 完整對話歷史（180K tokens）
[Turn 141-150] 最近對話

        ↓ Compaction

壓縮後：
[SUMMARY] "建立 REST API，實作 JWT 認證、Rate Limiting..."
[Turn 141-150] 保留完整內容（45K tokens）

手動觸發

1
/compact 專注於決策和待解問題

Memory Flush：防丟失機制

Compaction 是有損壓縮，可能遺失重要資訊。為了解決這個問題，Clawdbot 在壓縮前會執行 Memory Flush：

1
2
3
4
5
6
7
8
9
10
Context 接近上限（75%）
        │
        ▼
系統觸發 Memory Flush
        │
        ▼
AI 檢視對話，將重要資訊寫入 memory/*.md
        │
        ▼
Compaction 安全進行（重要資訊已保存）

這確保即使對話被壓縮，關鍵決策和資訊也不會丟失。

多代理記憶隔離

Clawdbot 支援多個獨立代理，每個代理擁有獨立的記憶空間：

1
2
3
4
5
6
7
8
9
10
11
~/.clawdbot/memory/
├── main.sqlite      # "main" 代理的向量索引
└── work.sqlite      # "work" 代理的向量索引

~/clawd/             # "main" 代理的工作區
├── MEMORY.md
└── memory/

~/clawd-work/        # "work" 代理的工作區
├── MEMORY.md
└── memory/

應用場景：

  • 「個人」代理用於 WhatsApp 私人對話
  • 「工作」代理用於 Slack 工作討論
  • 各自擁有獨立的記憶與個性

實際應用範例

範例 1：專案決策追蹤

1
2
3
4
5
6
7
8
你：我們之前選了什麼資料庫？

AI：（執行 memory_search）
根據 1 月 15 日的記錄，我們決定使用 PostgreSQL，
主要原因是：
1. 團隊熟悉度高
2. 支援 JSON 欄位
3. 擴展性佳

範例 2：偏好記憶

1
2
3
4
5
你：幫我寫一段程式碼

AI：（根據 MEMORY.md 記錄的偏好）
好的，我用 TypeScript 來寫，因為你之前提過偏好 TS：
...

範例 3：跨日脈絡延續

1
2
3
4
5
你：昨天那個 Bug 修好了嗎？

AI：（搜尋 memory/2026-01-26.md）
是的，昨天下午 3:15 我們找到問題是 null check 遺漏，
已經修復並部署到 staging。

常見問題 FAQ

Q1：記憶檔案可以手動編輯嗎？

可以。所有記憶都是純 Markdown 檔案，你可以直接用任何編輯器修改。修改後 Clawdbot 會自動重新索引。

Q2：記憶會佔用多少空間？

記憶檔案本身很小（純文字）。向量索引儲存在 SQLite 檔案中，通常每個代理幾 MB 到幾十 MB。

Q3：如何備份記憶？

整個 ~/clawd/ 工作區都是普通檔案，可以用 Git 版本控制，或任何備份工具備份。

Q4：多久清理一次舊記憶？

Clawdbot 不會自動刪除記憶。你可以手動清理過時的 daily log，重要資訊應該已經整理到 MEMORY.md。

Q5：記憶搜尋的準確度如何？

混合搜尋（向量 + BM25）在大多數情況下表現良好。如果搜尋結果不理想，可以調整 minScore 閾值或使用更精確的關鍵字。

結語

Clawdbot 的記憶系統體現了幾個重要設計原則：

  1. 透明勝過黑箱：記憶是純 Markdown，可讀、可編輯、可版本控制
  2. 搜尋勝過注入：按需檢索相關記憶，而非塞滿整個 Context
  3. 持久勝過臨時：重要資訊寫入檔案，不怕對話被壓縮
  4. 混合勝過單一：向量 + 關鍵字搜尋，兼顧語意與精確匹配

對於需要長期記憶的 AI 助理應用場景，Clawdbot 的本地化記憶架構提供了一個透明、可控、且有效的解決方案。

參考連結: