Kiến trúc memory-lancedb-pro: bộ nhớ vector nhúng cho OpenClaw

Tóm tắt nhanh
memory-lancedb-pro cung cấp cơ chế lưu trữ bộ nhớ dài hạn nhúng cho OpenClaw agent, thay thế cửa sổ ngữ cảnh tạm thời bằng cơ sở dữ liệu vector bền vững được định danh bằng UUID. Xây dựng trên LanceDB và định dạng Apache Arrow, plugin thực hiện truy vấn vector và BM25 trực tiếp trên ổ đĩa cục bộ mà không cần máy chủ ngoài. Tương thích từ OpenClaw 2026.3.22+, plugin can thiệp qua hook before_prompt_build để nạp quyết định vào ngữ cảnh, đồng thời lọc nhiễu qua điểm suy giảm thời gian và cơ chế nhân bản Markdown hai chiều.

Nhu cầu kết hợp truy hồi lai trong bộ nhớ agent nhúng

Khi phiên làm việc kết thúc hoặc ngữ cảnh đầy, AI agent mất các quy tắc kiến trúc và sở thích lập trình đã tích lũy. Việc lặp lại yêu cầu kỹ thuật gây lãng phí thời gian và giảm độ tin cậy. Nếu agent quên quyết định trước đó, hệ thống dễ tái diễn thiết kế lỗi thời hoặc ghi đè cấu trúc đã thống nhất.

Đưa toàn bộ lịch sử vào prompt làm tăng chi phí token và gây pha loãng ngữ cảnh, khiến mô hình bỏ sót chỉ dẫn then chốt. Ngược lại, vector DB từ xa phát sinh độ trễ mạng HTTPS và phụ thuộc hạ tầng ngoài khi vận hành cục bộ.

Lưu trữ LanceDB cùng các truy vấn vector và toàn văn (FTS) chạy hoàn toàn trên ổ đĩa cục bộ. Khởi tạo embedding, reranking và trích xuất thông minh vẫn có thể gọi dịch vụ ngoài tùy cấu hình; sở hữu cơ sở dữ liệu cục bộ không đồng nghĩa mọi tác vụ đều ngoại tuyến.

Trong hệ thống đa agent, thiếu bộ nhớ bền vững dùng chung khiến các vai trò sau không nắm được thử nghiệm trước, gây lặp lại sai lầm và tốn token.

memory-lancedb-pro vận hành LanceDB trong tiến trình agent host; việc lập chỉ mục và đo tương đồng diễn ra thẳng trên vùng đệm Apache Arrow trên đĩa mà không phát sinh độ trễ socket mạng.

Theo package.json L51-L57, dự án phát hành theo giấy phép MIT với các phụ thuộc cốt lõi:

• @lancedb/lancedb (^0.26.2): Động cơ vector nhúng trong tiến trình.
• @sinclair/typebox (0.34.48): Định nghĩa schema tĩnh và kiểm tra runtime.
• apache-arrow (18.1.0): Dữ liệu dạng cột trong bộ nhớ cho truy vấn phân tích.
• openai (^6.21.0): SDK tạo embedding tương thích chuẩn text-embedding-3.
• proper-lockfile (^4.1.2): Khóa tệp liên tiến trình điều phối ghi đồng thời.

Cài đặt bằng lệnh openclaw plugins install memory-lancedb-pro@beta. Tài liệu README yêu cầu tập lệnh AVX2 trên Linux x64 cùng tùy chọn biên dịch dự phòng.

Tích hợp vòng đời agent qua hook before_prompt_build

Bài viết đánh giá phiên bản 1.1.0-beta.11. Dự án chuyển tính năng auto-recall từ hook before_agent_start sang before_prompt_build. Theo README.md L986-L991, plugin yêu cầu OpenClaw từ 2026.3.22 trở lên. Lệnh openclaw doctor --fix hỗ trợ di chuyển và cập nhật cấu hình host.

Trong openclaw.plugin.json L17-L19, plugin đặt hooks.allowConversationAccess: true để đọc ngữ cảnh trong lúc dựng prompt:

[Người dùng gửi yêu cầu]
          │
          ▼
[OpenClaw Agent Core]
          │
          ├──► (Phát sự kiện before_prompt_build)
          │
          ▼
[Trình xử lý hook memory-lancedb-pro]
          │
          ├── 1. Trích xuất biểu diễn ngữ nghĩa của truy vấn
          ├── 2. Kích hoạt tìm kiếm lai (Vector Cosine + BM25)
          ├── 3. Lọc theo độ suy giảm thời gian và ngưỡng tương đồng
          └── 4. Lọc thông tin hồ sơ theo quy tắc heuristic
          │
          ▼
[Đoạn prompt bộ nhớ bổ sung]──►[Ngữ cảnh LLM]──►[Agent xử lý tác vụ]
                                                         │
                                                         ▼
                                                [Ghi nhận sau phiên]
                                         (LanceDB + Markdown Mirror)

Quy trình truy hồi kết hợp vector đậm đặc và từ khóa thưa BM25: vector bắt ngữ nghĩa khái niệm, còn BM25 so khớp chính xác tên hàm, ticket ID hoặc đường dẫn tệp.

Hệ thống tính điểm suy giảm theo thời gian: ký ức ít dùng sẽ giảm dần thứ tự ưu tiên, nhường chỗ cho các quyết định mới hơn.

Kiểm soát tranh chấp ghi, phân tách không gian và cơ chế Markdown Mirror

Khóa liên tiến trình điều phối các lượt ghi dùng chung cơ sở dữ liệu và cấu hình khóa theo docs/lock-management.md L7-L46. Khóa advisory qua proper-lockfile tuần tự hóa các sửa đổi trên đĩa và giảm tranh chấp ghi. Khi cập nhật nhiều bước, src/store.ts L3372-L3422 xử lý việc hủy hiệu lực từng phần trong thao tác supersede.

Plugin yêu cầu cấu hình embedding kèm apiKey bắt buộc theo openclaw.plugin.json L175-L188:

{
  "plugins": {
    "slots": {
      "memory": "memory-lancedb-pro"
    },
    "entries": {
      "memory-lancedb-pro": {
        "enabled": true,
        "config": {
          "embedding": {
            "provider": "openai-compatible",
            "apiKey": "${OPENAI_API_KEY}",
            "model": "text-embedding-3-small"
          },
          "autoCapture": true,
          "autoRecall": true,
          "mdMirror": {
            "enabled": true
          },
          "memoryCompaction": {
            "enabled": true,
            "minAgeDays": 7,
            "similarityThreshold": 0.90
          },
          "sessionCompression": {
            "enabled": true,
            "minScoreToKeep": 0.35
          }
        }
      }
    }
  }
}

Khi bật qua openclaw.plugin.json L1627-L1677, Markdown mirror nối thêm mục nhật ký theo ngày vào workspace agent. Theo index.ts L2155-L2196, cơ chế gộp các dòng ngắt đoạn thành một hàng và cắt ngắn ở 500 ký tự. Theo index.ts L5029-L5043, database commit trước khi ghi mirror, và hệ thống chấp nhận lỗi mirror. Đây là nhật ký kiểm tra trực quan, không phải đồng bộ hai chiều tự động hay bản backup cơ sở dữ liệu.

Khi workspaceBoundary.userMdExclusive.enabled là true, logic heuristic trong src/workspace-boundary.ts L64-L123 lọc profile, tên chuẩn và cách xưng hô khỏi luồng ghi. Tùy chọn này mặc định tắt và phân loại heuristic chứ không đọc nội dung USER.md.

Các đội ngũ đa agent có thể thiết lập phân quyền qua scopes.definitions và scopes.agentAccess trong src/scopes.ts L188-L245. Cấu hình này giới hạn thao tác plugin vào phạm vi chỉ định cho từng agent. Mặc định, agent đọc thêm phạm vi global. Kiểm soát scope nằm ở tầng API plugin chứ không tạo cô lập hệ thống tệp cấp hệ điều hành.

Để tinh chỉnh truy hồi cho từng vai trò agent, cấu hình hỗ trợ autoRecallExcludeAgents và autoRecallIncludeAgents. Nhà phát triển có thể cấp quyền auto-recall cho agent quan trọng và loại trừ các subagent phụ trợ.

Chu kỳ dreaming ngầm và cơ chế nén phiên hội thoại

Thách thức trong vận hành AI agent dài hạn là phình bộ nhớ: ghi toàn bộ hội thoại tạm thời sẽ làm cạn dung lượng và giảm độ chính xác truy hồi.

memory-lancedb-pro cung cấp hai phân hệ lọc dữ liệu:

1. Nén phiên (Session compression): Theo openclaw.plugin.json L1722-L1738, nén phiên tùy chọn chấm điểm văn bản trước trích xuất. Nội dung trong ngân sách ký tự được giữ nguyên. Khi vượt ngân sách, hệ thống ưu tiên giữ lời gọi công cụ và kết quả, với ngưỡng minScoreToKeep mặc định 0.3.
2. Chu kỳ dreaming: Chạy theo lịch cron (như 0 3 * * *), dreaming xử lý dữ liệu khi OpenClaw gateway đang chạy. Triển khai tại src/dreaming-engine.ts L673-L730, hệ thống thực hiện ba pha: Light lưu trữ bản ghi gần trùng theo tương đồng cosine, Deep thăng hạng ký ức truy xuất nhiều lên tầng bền vững, và REM tổng hợp bản ghi phản tư. Lịch trình không đợi máy nhàn rỗi. Compaction lúc khởi động là nhánh tùy chọn riêng theo minAgeDays và cooldown.

Giao diện dòng lệnh quản trị và hợp đồng công cụ cho Agent

Bên cạnh tự động nạp ký ức, memory-lancedb-pro cung cấp công cụ quản trị rõ ràng cho lập trình viên và agent.

Plugin khai báo 18 tên công cụ trong openclaw.plugin.json L2469-L2489. Khi khởi chạy, src/tools.ts L3325-L3350 đăng ký 7 công cụ cốt lõi:

• Truy hồi: memory_recall, memory_search, memory_get và memory_fact_query.
• Đột biến trạng thái: memory_store, memory_forget và memory_update.

Các công cụ như memory_compact, memory_stats và memory_explain_rank cần enableManagementTools: true. Nhóm tự cải tiến gồm self_improvement_log, self_improvement_extract_skill và self_improvement_review có điều kiện bật riêng.

# Kiểm tra tình trạng plugin và di chuyển cấu hình host
openclaw doctor --fix

# Xem trước kế hoạch đối soát và hợp nhất ký ức giữa các luồng
openclaw memory-pro consolidate --agent main

# Áp dụng hợp nhất ở chế độ không tương tác kèm cờ xác nhận
openclaw memory-pro consolidate --agent main --apply --yes

# Xem thông số thống kê số lượng ký ức và trạng thái bảng vector
openclaw memory-pro stats

# Chạy bộ kiểm thử và đánh giá benchmark truy hồi
npm run bench:locomo
npm run bench:longmemeval

Theo package.json L35-L49, kỹ sư xác thực hệ thống qua các bài kiểm thử test:storage-and-schema và test:llm-clients-and-auth.

Động cơ hợp nhất trong cli.ts L2507-L2534 xử lý bản ghi dư thừa hoặc xung đột ngữ nghĩa. Lệnh openclaw memory-pro consolidate --agent main hiển thị kế hoạch xem trước. Thêm cờ --apply để thực thi; tiến trình tự động cần --yes để chấp nhận chi phí gọi mô hình. Hợp nhất giúp giảm bản ghi dư thừa; tác động tới độ trễ phụ thuộc quy mô dữ liệu và cấu hình lập chỉ mục.