工作區記憶體 v2（離線）：研究筆記

目標：Clawd 風格的工作區（agents.defaults.workspace，預設 ~/.openclaw/workspace），其中「記憶體」儲存為每天一個 Markdown 檔案（memory/YYYY-MM-DD.md）加上一小組穩定檔案（如 memory.md、SOUL.md）。

本文件提出一套離線優先的記憶體架構，保留 Markdown 作為正規、可審閱的事實來源，但透過衍生索引新增結構化召回（搜尋、實體摘要、信心更新）。

為何要改變？

目前的設定（每天一個檔案）在以下場景表現出色：

• 「僅附加」式的日誌記錄
• 人工編輯
• git 支援的持久性 + 可稽核性
• 低門檻的擷取（「寫下來就好」）

但在以下場景表現不佳：

• 高召回率檢索（「我們對 X 做了什麼決定？」、「上次嘗試 Y 是什麼時候？」）
• 以實體為中心的回答（「告訴我關於 Alice / The Castle / warelay」）而不需重讀多個檔案
• 意見/偏好的穩定性（以及變更時的佐證）
• 時間約束（「2025 年 11 月期間什麼是成立的？」）和衝突解決

設計目標

• 離線：不需網路即可運作；可在筆電/Castle 上執行；無雲端依賴。
• 可解釋：檢索的項目應可歸因（檔案 + 位置）且與推論分離。
• 低儀式：每日記錄維持 Markdown，無繁重的 schema 工作。
• 漸進式：v1 僅用 FTS 就有用；語義/向量和圖形為選用升級。
• 代理友善：讓「在 token 預算內召回」變得容易（回傳小型事實包）。

終極模型（Hindsight x Letta）

混合兩個方向：

1. Letta/MemGPT 風格的控制迴圈

• 保持小型「核心」始終在上下文中（角色 + 關鍵使用者事實）
• 其他一切在上下文外，透過工具檢索
• 記憶體寫入是明確的工具呼叫（附加/取代/插入），持久化後在下一回合重新注入

2. Hindsight 風格的記憶體基底

• 分開觀察到的、相信的和摘要的
• 支援保留/召回/反思
• 帶信心的意見可隨佐證演化
• 實體感知的檢索 + 時間查詢（即使沒有完整知識圖形）

提議的架構（Markdown 事實來源 + 衍生索引）

正規儲存（git 友善）

保持 ~/.openclaw/workspace 作為正規的人類可讀記憶體。

建議的工作區佈局：

~/.openclaw/workspace/
  memory.md                    # 小型：持久事實 + 偏好（核心級）
  memory/
    YYYY-MM-DD.md              # 每日記錄（附加；敘事）
  bank/                        # 「帶型別」的記憶體頁面（穩定、可審閱）
    world.md                   # 關於世界的客觀事實
    experience.md              # 代理做了什麼（第一人稱）
    opinions.md                # 主觀偏好/判斷 + 信心 + 佐證指標
    entities/
      Peter.md
      The-Castle.md
      warelay.md
      ...

說明：

• 每日記錄維持每日記錄。不需轉為 JSON。
• bank/ 檔案是策展的，由反思工作產生，仍可手動編輯。
• memory.md 維持「小型 + 核心級」：你希望 Clawd 每次 session 都看到的內容。

衍生儲存（機器召回）

在工作區下新增衍生索引（不一定需要 git 追蹤）：

~/.openclaw/workspace/.memory/index.sqlite

以下列為基礎：

• 事實 + 實體連結 + 意見中繼資料的 SQLite schema
• SQLite FTS5 用於詞彙召回（快速、輕量、離線）
• 選用的 embeddings 表用於語義召回（仍離線）

索引始終可從 Markdown 重建。

保留 / 召回 / 反思（操作迴圈）

保留：將每日記錄正規化為「事實」

Hindsight 在此處的關鍵洞見：儲存敘事性、自包含的事實，而非微小的片段。

memory/YYYY-MM-DD.md 的實用規則：

• 在一天結束時（或期間），新增 ## Retain 區段，包含 2-5 個要點：
  • 敘事性（跨回合上下文保留）
  • 自包含（獨立閱讀時有意義）
  • 標記型別 + 實體提及

範例：

## Retain
- W @Peter: Currently in Marrakech (Nov 27–Dec 1, 2025) for Andy's birthday.
- B @warelay: I fixed the Baileys WS crash by wrapping connection.update handlers in try/catch (see memory/2025-11-27.md).
- O(c=0.95) @Peter: Prefers concise replies (<1500 chars) on WhatsApp; long content goes into files.

最小解析：

• 型別前綴：W（世界）、B（經驗/傳記）、O（意見）、S（觀察/摘要；通常自動生成）
• 實體：@Peter、@warelay 等（slug 對應至 bank/entities/*.md）
• 意見信心：O(c=0.0..1.0) 選用

若不想讓撰寫者思考太多：反思工作可從記錄的其餘內容推論這些要點，但擁有明確的 ## Retain 區段是最簡單的「品質槓桿」。

召回：對衍生索引的查詢

召回應支援：

• 詞彙：「找到確切詞彙/名稱/指令」（FTS5）
• 實體：「告訴我關於 X」（實體頁面 + 實體連結的事實）
• 時間：「11 月 27 日前後發生什麼」/「上週以來」
• 意見：「Peter 偏好什麼？」（搭配信心 + 佐證）

回傳格式應代理友善並引用來源：

• kind（world|experience|opinion|observation）
• timestamp（來源日期，或若有的話抽取的時間範圍）
• entities（["Peter","warelay"]）
• content（敘事性事實）
• source（memory/2025-11-27.md#L12 等）

反思：產生穩定頁面 + 更新信念

反思是排程工作（每日或心跳 ultrathink），功能包含：

• 從近期事實更新 bank/entities/*.md（實體摘要）
• 依據強化/矛盾更新 bank/opinions.md 信心
• 選用地對 memory.md 提出編輯建議（「核心級」持久事實）

意見演化（簡單、可解釋）：

• 每個意見有：
  • 陳述
  • 信心 c 屬於 [0,1]
  • last_updated
  • 佐證連結（支持 + 矛盾的事實 ID）
• 新事實到達時：
  • 透過實體重疊 + 相似度找候選意見（先 FTS，之後 embeddings）
  • 以小幅度更新信心；大幅跳躍需要強烈矛盾 + 重複佐證

CLI 整合：獨立 vs 深度整合

建議：深度整合至 OpenClaw，但保持可分離的核心函式庫。

為何整合至 OpenClaw？

• OpenClaw 已經知道：
  • 工作區路徑（agents.defaults.workspace）
  • session 模型 + 心跳
  • 日誌 + 故障排除模式
• 你想讓代理自己呼叫工具：
  • openclaw memory recall "…" --k 25 --since 30d
  • openclaw memory reflect --since 7d

為何仍分離函式庫？

• 讓記憶體邏輯在不含 gateway/runtime 的情況下可測試
• 可從其他情境重用（本地腳本、未來的桌面應用等）

形式： 記憶體工具預期為小型的 CLI + 函式庫層，但目前僅為探索性質。

「S-Collide」/ SuCo：何時使用（研究）

若「S-Collide」指的是 SuCo（Subspace Collision）：這是一種 ANN 檢索方法，透過在子空間中使用學習/結構化碰撞來達到強召回/延遲的權衡（論文：arXiv 2411.14754, 2024）。

針對 ~/.openclaw/workspace 的務實觀點：

• 不要一開始就用 SuCo。
• 從 SQLite FTS +（選用）簡單 embeddings 開始；你會立即獲得大部分 UX 效益。
• 僅在以下情況考慮 SuCo/HNSW/ScaNN 級方案：
  • 語料庫很大（數萬/數十萬區塊）
  • 暴力 embedding 搜尋變得太慢
  • 召回品質明顯被詞彙搜尋瓶頸限制

離線友善的替代方案（依複雜度遞增）：

• SQLite FTS5 + 中繼資料過濾（零 ML）
• Embeddings + 暴力搜尋（區塊數少時效果出奇地好）
• HNSW 索引（常見、穩健；需要函式庫綁定）
• SuCo（研究級；如果有可嵌入的穩固實作就很有吸引力）

待決問題：

• 在你的機器（筆電 + 桌機）上，「個人助理記憶體」的最佳離線 embedding 模型是什麼？
  • 若已有 Ollama：用本地模型 embed；否則在工具鏈中附帶小型 embedding 模型。

最小可用原型

若要一個最小但仍有用的版本：

• 新增 bank/ 實體頁面和每日記錄中的 ## Retain 區段。
• 使用 SQLite FTS 進行帶引用的召回（路徑 + 行號）。
• 僅在召回品質或規模需要時才加入 embeddings。

參考資料

• Letta / MemGPT 概念：「核心記憶體區塊」+「檔案記憶體」+ 工具驅動的自我編輯記憶體。
• Hindsight 技術報告：「保留 / 召回 / 反思」、四網路記憶體、敘事性事實抽取、意見信心演化。
• SuCo：arXiv 2411.14754 (2024)：「Subspace Collision」近似最近鄰檢索。