Workspace Memory v2 (offline): ghi chú nghiên cứu

Mục tiêu: Workspace kiểu Clawd (agents.defaults.workspace, mặc định là ~/.openclaw/workspace) nơi “memory” được lưu dưới dạng một file Markdown mỗi ngày (memory/YYYY-MM-DD.md) cộng với một số file ổn định (ví dụ memory.md, SOUL.md).

Tài liệu này đề xuất một kiến trúc memory offline-first giữ Markdown làm nguồn chính thật có thể xem xét được, nhưng thêm structured recall (tìm kiếm, tóm tắt entity, cập nhật độ tin cậy) thông qua index phái sinh.

Tại sao cần thay đổi?

Cách setup hiện tại (một file mỗi ngày) rất tốt cho:

  • Ghi nhật ký kiểu “append-only”
  • Chỉnh sửa bằng tay
  • Độ bền + khả năng kiểm tra với git
  • Ghi chép dễ dàng (“cứ viết ra thôi”)

Nhưng yếu ở:

  • Truy xuất recall cao (“chúng ta đã quyết định gì về X?”, “lần trước thử Y thế nào?”)
  • Trả lời theo entity (“cho biết về Alice / The Castle / warelay”) mà không cần đọc lại nhiều file
  • Tính ổn định của ý kiến/sở thích (và bằng chứng khi nó thay đổi)
  • Ràng buộc thời gian (“điều gì đúng trong tháng 11/2025?”) và giải quyết xung đột

Mục tiêu thiết kế

  • Offline: hoạt động không cần mạng; có thể chạy trên laptop/Castle; không phụ thuộc cloud.
  • Explainable: các item được truy xuất phải có nguồn gốc rõ ràng (file + vị trí) và tách biệt khỏi suy luận.
  • Low ceremony: ghi log hàng ngày vẫn là Markdown, không cần schema phức tạp.
  • Incremental: v1 hữu ích chỉ với FTS; semantic/vector và graph là các nâng cấp tùy chọn.
  • Agent-friendly: giúp “recall trong giới hạn token” dễ dàng (trả về các gói fact nhỏ).

Mô hình hướng tới (Hindsight × Letta)

Hai phần cần kết hợp:

  1. Control loop kiểu Letta/MemGPT
  • giữ một “core” nhỏ luôn trong context (persona + các fact quan trọng về user)
  • mọi thứ khác nằm ngoài context và được truy xuất qua tool
  • ghi memory là các lời gọi tool rõ ràng (append/replace/insert), được lưu lại, rồi inject lại ở lượt tiếp theo
  1. Memory substrate kiểu Hindsight
  • tách biệt cái gì được quan sát vs cái gì được tin tưởng vs cái gì được tóm tắt
  • hỗ trợ retain/recall/reflect
  • các ý kiến có độ tin cậy có thể phát triển theo bằng chứng
  • truy xuất theo entity + truy vấn theo thời gian (ngay cả khi không có knowledge graph đầy đủ)

Kiến trúc đề xuất (Markdown source-of-truth + derived index)

Canonical store (thân thiện với git)

Giữ ~/.openclaw/workspace làm memory chính có thể đọc được.

Layout workspace gợi ý:

~/.openclaw/workspace/
  memory.md                    # nhỏ: các fact bền vững + preferences (core-ish)
  memory/
    YYYY-MM-DD.md              # log hàng ngày (append; narrative)
  bank/                        # các trang memory "có kiểu" (ổn định, có thể xem xét)
    world.md                   # các fact khách quan về thế giới
    experience.md              # những gì agent đã làm (góc nhìn ngôi thứ nhất)
    opinions.md                # các pref/đánh giá chủ quan + độ tin cậy + con trỏ bằng chứng
    entities/
      Peter.md
      The-Castle.md
      warelay.md
      ...

Lưu ý:

  • Log hàng ngày vẫn là log hàng ngày. Không cần chuyển thành JSON.
  • Các file bank/ được curated, tạo ra bởi các reflection job, và vẫn có thể chỉnh sửa bằng tay.
  • memory.md vẫn “nhỏ + core-ish”: những thứ các bạn muốn Clawd thấy mỗi session.

Derived store (machine recall)

Thêm một index phái sinh dưới workspace (không nhất thiết phải track bằng git):

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

Hỗ trợ bởi:

  • SQLite schema cho fact + entity link + opinion metadata
  • SQLite FTS5 cho lexical recall (nhanh, nhỏ, offline)
  • bảng embeddings tùy chọn cho semantic recall (vẫn offline)

Index luôn có thể rebuild từ Markdown.

Retain / Recall / Reflect (vòng lặp vận hành)

Retain: chuẩn hóa log hàng ngày thành “fact”

Insight quan trọng của Hindsight ở đây: lưu các fact narrative, tự chứa, không phải các snippet nhỏ.

Quy tắc thực tế cho memory/YYYY-MM-DD.md:

  • vào cuối ngày (hoặc trong ngày), thêm một section ## Retain với 2–5 bullet là:
    • narrative (giữ nguyên context xuyên suốt các lượt)
    • tự chứa (đứng độc lập vẫn có nghĩa sau này)
    • được tag với type + đề cập entity

Ví dụ:

## Retain
- W @Peter: Hiện đang ở Marrakech (27/11–01/12/2025) cho sinh nhật Andy.
- B @warelay: Mình đã fix lỗi crash Baileys WS bằng cách wrap connection.update handler trong try/catch (xem memory/2025-11-27.md).
- O(c=0.95) @Peter: Thích reply ngắn gọn (<1500 ký tự) trên WhatsApp; nội dung dài thì cho vào file.

Parsing tối thiểu:

  • Type prefix: W (world), B (experience/biographical), O (opinion), S (observation/summary; thường được tạo tự động)
  • Entity: @Peter, @warelay, v.v. (slug map tới bank/entities/*.md)
  • Opinion confidence: O(c=0.0..1.0) tùy chọn

Nếu các bạn không muốn tác giả phải nghĩ về nó: reflection job có thể suy ra các bullet này từ phần còn lại của log, nhưng có section ## Retain rõ ràng là “đòn bẩy chất lượng” dễ nhất.

Recall: truy vấn trên derived index

Recall nên hỗ trợ:

  • lexical: “tìm các term / tên / lệnh chính xác” (FTS5)
  • entity: “cho biết về X” (entity page + các fact liên kết entity)
  • temporal: “chuyện gì xảy ra khoảng 27/11” / “từ tuần trước”
  • opinion: “Peter thích gì?” (với độ tin cậy + bằng chứng)

Format trả về nên thân thiện với agent và trích dẫn nguồn:

  • kind (world|experience|opinion|observation)
  • timestamp (ngày nguồn, hoặc khoảng thời gian được trích xuất nếu có)
  • entities (["Peter","warelay"])
  • content (fact narrative)
  • source (memory/2025-11-27.md#L12 v.v.)

Reflect: tạo các trang ổn định + cập nhật belief

Reflection là một scheduled job (hàng ngày hoặc heartbeat ultrathink) để:

  • cập nhật bank/entities/*.md từ các fact gần đây (tóm tắt entity)
  • cập nhật độ tin cậy bank/opinions.md dựa trên củng cố/mâu thuẫn
  • tùy chọn đề xuất chỉnh sửa memory.md (các fact bền vững “core-ish”)

Opinion evolution (đơn giản, có thể giải thích):

  • mỗi opinion có:
    • statement
    • confidence c ∈ [0,1]
    • last_updated
    • evidence link (các fact ID hỗ trợ + mâu thuẫn)
  • khi có fact mới:
    • tìm các opinion ứng viên bằng entity overlap + similarity (FTS trước, embedding sau)
    • cập nhật confidence bằng delta nhỏ; bước nhảy lớn cần mâu thuẫn mạnh + bằng chứng lặp lại

Tích hợp CLI: độc lập vs tích hợp sâu

Khuyến nghị: tích hợp sâu vào OpenClaw, nhưng giữ một core library tách biệt.

Tại sao tích hợp vào OpenClaw?

  • OpenClaw đã biết:
    • đường dẫn workspace (agents.defaults.workspace)
    • session model + heartbeat
    • các pattern logging + troubleshooting
  • Các bạn muốn chính agent gọi các tool:
    • openclaw memory recall "…" --k 25 --since 30d
    • openclaw memory reflect --since 7d

Tại sao vẫn tách library?

  • giữ logic memory có thể test được mà không cần gateway/runtime
  • tái sử dụng từ các context khác (script local, desktop app tương lai, v.v.)

Hình dạng: Memory tooling được dự định là một layer CLI + library nhỏ, nhưng đây chỉ là khám phá thôi.

”S-Collide” / SuCo: khi nào dùng nó (nghiên cứu)

Nếu “S-Collide” ám chỉ SuCo (Subspace Collision): đây là một phương pháp truy xuất ANN nhắm tới sự cân bằng recall/latency mạnh bằng cách dùng collision đã học/có cấu trúc trong subspace (paper: arXiv 2411.14754, 2024).

Quan điểm thực tế cho ~/.openclaw/workspace:

  • đừng bắt đầu với SuCo.
  • bắt đầu với SQLite FTS + (tùy chọn) embedding đơn giản; các bạn sẽ có hầu hết lợi ích UX ngay lập tức.
  • chỉ xem xét các giải pháp class SuCo/HNSW/ScaNN khi:
    • corpus lớn (hàng chục/hàng trăm nghìn chunk)
    • tìm kiếm embedding brute-force trở nên quá chậm
    • chất lượng recall bị nghẽn cổ chai đáng kể bởi lexical search

Các lựa chọn thay thế thân thiện offline (theo độ phức tạp tăng dần):

  • SQLite FTS5 + metadata filter (zero ML)
  • Embedding + brute force (hoạt động tốt đến ngạc nhiên nếu số lượng chunk thấp)
  • HNSW index (phổ biến, mạnh mẽ; cần library binding)
  • SuCo (research-grade; hấp dẫn nếu có implementation vững chắc có thể embed)

Câu hỏi mở:

  • embedding model offline tốt nhất cho “personal assistant memory” trên máy các bạn (laptop + desktop) là gì?
    • nếu đã có Ollama: embed với local model; nếu không thì ship một embedding model nhỏ trong toolchain.

Pilot nhỏ nhất hữu ích

Nếu các bạn muốn một phiên bản tối thiểu nhưng vẫn hữu ích:

  • Thêm các entity page bank/ và một section ## Retain trong log hàng ngày.
  • Dùng SQLite FTS cho recall với citation (đường dẫn + số dòng).
  • Chỉ thêm embedding nếu chất lượng recall hoặc quy mô yêu cầu.

Tài liệu tham khảo

  • Letta / MemGPT concept: “core memory block” + “archival memory” + tool-driven self-editing memory.
  • Hindsight Technical Report: “retain / recall / reflect”, four-network memory, narrative fact extraction, opinion confidence evolution.
  • SuCo: arXiv 2411.14754 (2024): “Subspace Collision” approximate nearest neighbor retrieval.