Memory

Moltbot 記憶體是agent 工作區中的純 Markdown。檔案是真相來源；模型只「記住」寫入磁碟的內容。

記憶體搜尋工具由作用中的記憶體外掛提供（預設：memory-core）。使用 plugins.slots.memory = "none" 停用記憶體外掛。

記憶體檔案（Markdown）

預設工作區佈局使用兩層記憶體：

• memory/YYYY-MM-DD.md
  • 每日日誌（僅附加）。
  • 在 session 開始時讀取今天 + 昨天。
• MEMORY.md（選用）
  • 策劃的長期記憶體。
  • 僅在主要、私人 session 中載入（絕不在群組上下文中）。

這些檔案位於工作區下（agents.defaults.workspace，預設為 ~/clawd）。完整佈局參見 Agent workspace。

何時寫入記憶體

• 決策、偏好和持久事實放入 MEMORY.md。
• 日常筆記和執行上下文放入 memory/YYYY-MM-DD.md。
• 如果有人說「記住這個」，寫下來（不要保留在 RAM 中）。
• 這個領域仍在演進中。提醒模型儲存記憶體會有幫助；它會知道該怎麼做。
• 如果您想讓某些東西保留下來，要求機器人將它寫入記憶體。

自動記憶體刷新（預壓縮 ping）

當 session 接近自動壓縮時，Moltbot 會觸發靜默的代理回合，提醒模型在上下文被壓縮之前寫入持久記憶體。預設提示明確表示模型可以回覆，但通常 NO_REPLY 是正確的回應，因此使用者永遠不會看到這個回合。

這由 agents.defaults.compaction.memoryFlush 控制：

{
  agents: {
    defaults: {
      compaction: {
        reserveTokensFloor: 20000,
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 4000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
        }
      }
    }
  }
}

詳細資訊：

• 軟閾值：當 session token 估計超過 contextWindow - reserveTokensFloor - softThresholdTokens 時觸發刷新。
• 預設靜默：提示包含 NO_REPLY，因此不會傳遞任何內容。
• 兩個提示：使用者提示加上系統提示附加提醒。
• 每個壓縮週期一次刷新（在 sessions.json 中追蹤）。
• 工作區必須可寫：如果 session 以 workspaceAccess: "ro" 或 "none" 沙箱執行，則跳過刷新。

完整壓縮生命週期參見 Session 管理 + 壓縮。

向量記憶體搜尋

Moltbot 可以在 MEMORY.md 和 memory/*.md 上建立小型向量索引，因此語義查詢可以找到相關筆記，即使措辭不同。

預設值：

• 預設啟用。
• 監視記憶體檔案的變更（去抖動）。
• 預設使用遠端嵌入。如果未設定 memorySearch.provider，Moltbot 會自動選擇：
  1. local 如果設定了 memorySearch.local.modelPath 且檔案存在。
  2. openai 如果可以解析 OpenAI 金鑰。
  3. gemini 如果可以解析 Gemini 金鑰。
  4. 否則記憶體搜尋保持停用狀態，直到設定完成。
• 本機模式使用 node-llama-cpp，可能需要 pnpm approve-builds。
• 使用 sqlite-vec（可用時）加速 SQLite 內的向量搜尋。

遠端嵌入需要嵌入提供者的 API 金鑰。Moltbot 從驗證設定檔、models.providers.*.apiKey 或環境變數解析金鑰。Codex OAuth 僅涵蓋對話/完成，不能滿足記憶體搜尋的嵌入需求。對於 Gemini，請使用 GEMINI_API_KEY 或 models.providers.google.apiKey。當使用自訂 OpenAI 相容端點時，設定 memorySearch.remote.apiKey（以及選用的 memorySearch.remote.headers）。

Gemini 嵌入（原生）

將提供者設定為 gemini 以直接使用 Gemini 嵌入 API：

agents: {
  defaults: {
    memorySearch: {
      provider: "gemini",
      model: "gemini-embedding-001",
      remote: {
        apiKey: "YOUR_GEMINI_API_KEY"
      }
    }
  }
}

注意事項：

• remote.baseUrl 是選用的（預設為 Gemini API 基本 URL）。
• remote.headers 讓您在需要時新增額外的標頭。
• 預設模型：gemini-embedding-001。

如果您想使用自訂 OpenAI 相容端點（OpenRouter、vLLM 或代理），您可以使用 OpenAI 提供者的 remote 設定：

agents: {
  defaults: {
    memorySearch: {
      provider: "openai",
      model: "text-embedding-3-small",
      remote: {
        baseUrl: "https://api.example.com/v1/",
        apiKey: "YOUR_OPENAI_COMPAT_API_KEY",
        headers: { "X-Custom-Header": "value" }
      }
    }
  }
}

如果您不想設定 API 金鑰，請使用 memorySearch.provider = "local" 或設定 memorySearch.fallback = "none"。

備援：

• memorySearch.fallback 可以是 openai、gemini、local 或 none。
• 僅當主要嵌入提供者失敗時才使用備援提供者。

批次索引（OpenAI + Gemini）：

• 預設為 OpenAI 和 Gemini 嵌入啟用。設定 agents.defaults.memorySearch.remote.batch.enabled = false 以停用。
• 預設行為等待批次完成；如需要調整 remote.batch.wait、remote.batch.pollIntervalMs 和 remote.batch.timeoutMinutes。

記憶體工具（memory_search + memory_get）

模型可以透過 memory_search 語義查詢記憶體，並透過 memory_get 讀取特定片段：

memory_search(query="專案優先順序")
  → [ { path: "MEMORY.md", lines: [42, 45], score: 0.89 } ]

memory_get(path="MEMORY.md", from=42, lines=5)
  → "## 專案優先順序\n1. docs.moltbot.tw 翻譯\n..."

這些工具由 memory-core 外掛提供，並在系統提示中宣告，因此模型知道在需要回憶時使用它們。

最佳實踐

1. 定期維護：在心跳期間審查每日檔案並更新 MEMORY.md。
2. 保持 MEMORY.md 整潔：策劃的長期記憶體，而非原始日誌。
3. 使用 memory_search：在回答有關先前工作、決策、日期、偏好的問題之前。
4. 寫下它：如果您想記住某些東西，寫入檔案。「心智筆記」不會在 session 重新啟動後存活。
5. 隱私意識：MEMORY.md 僅在主要 session 中載入；它不會洩漏到群組或共享上下文中。

相關文件

• Agent workspace — 完整工作區佈局
• Compaction — 壓縮生命週期和記憶體刷新時機
• Session management — Session 持久化和重設