English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Sessions and memory

Công cụ bộ nhớ tích hợp sẵn

Công cụ tích hợp là backend bộ nhớ mặc định. Nó lưu chỉ mục bộ nhớ của bạn trong cơ sở dữ liệu SQLite riêng cho từng agent và không cần phụ thuộc bổ sung để bắt đầu.

Nó cung cấp gì

  • Tìm kiếm từ khóa qua lập chỉ mục toàn văn FTS5 (chấm điểm BM25).
  • Tìm kiếm vector qua embedding từ bất kỳ nhà cung cấp được hỗ trợ nào.
  • Tìm kiếm hybrid kết hợp cả hai để có kết quả tốt nhất.
  • Hỗ trợ CJK qua token hóa trigram cho tiếng Trung, tiếng Nhật và tiếng Hàn.
  • Tăng tốc sqlite-vec cho truy vấn vector trong cơ sở dữ liệu (tùy chọn).

Bắt đầu

Nếu bạn có API key cho OpenAI, Gemini, Voyage, Mistral hoặc DeepInfra, công cụ tích hợp sẽ tự động phát hiện và bật tìm kiếm vector. Không cần cấu hình.

Để đặt rõ nhà cung cấp:

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
      },
    },
  },
}

Khi không có nhà cung cấp embedding, chỉ có tìm kiếm từ khóa.

Để buộc dùng nhà cung cấp embedding cục bộ tích hợp, hãy cài đặt gói runtime tùy chọn node-llama-cpp bên cạnh OpenClaw, rồi trỏ local.modelPath đến một tệp GGUF:

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "local",
        fallback: "none",
        local: {
          modelPath: "~/.node-llama-cpp/models/embeddinggemma-300m-qat-Q8_0.gguf",
        },
      },
    },
  },
}

Nhà cung cấp embedding được hỗ trợ

Nhà cung cấp ID Tự động phát hiện Ghi chú
OpenAI openai Có Mặc định: text-embedding-3-small
Gemini gemini Có Hỗ trợ đa phương thức (ảnh + âm thanh)
Voyage voyage Có
Mistral mistral Có
DeepInfra deepinfra Có Mặc định: BAAI/bge-m3
Ollama ollama Không Cục bộ, đặt rõ ràng
Cục bộ local Có (đầu tiên) Runtime node-llama-cpp tùy chọn

Tự động phát hiện chọn nhà cung cấp đầu tiên có thể phân giải API key, theo thứ tự hiển thị. Đặt memorySearch.provider để ghi đè.

Cách lập chỉ mục hoạt động

OpenClaw lập chỉ mục MEMORY.md và memory/*.md thành các đoạn (~400 token với phần chồng lấn 80 token) và lưu chúng trong cơ sở dữ liệu SQLite riêng cho từng agent.

  • Vị trí chỉ mục: ~/.openclaw/memory/<agentId>.sqlite
  • Bảo trì lưu trữ: Các tệp phụ SQLite WAL được giới hạn bằng checkpoint định kỳ và khi tắt.
  • Theo dõi tệp: thay đổi trong các tệp bộ nhớ kích hoạt lập chỉ mục lại có debounce (1,5 giây).
  • Tự động lập chỉ mục lại: khi nhà cung cấp embedding, mô hình hoặc cấu hình chia đoạn thay đổi, toàn bộ chỉ mục sẽ tự động được xây dựng lại.
  • Lập chỉ mục lại theo yêu cầu: openclaw memory index --force

Khi nào nên dùng

Công cụ tích hợp là lựa chọn phù hợp cho hầu hết người dùng:

  • Hoạt động ngay không cần phụ thuộc bổ sung.
  • Xử lý tốt tìm kiếm từ khóa và vector.
  • Hỗ trợ tất cả nhà cung cấp embedding.
  • Tìm kiếm hybrid kết hợp điểm mạnh nhất của cả hai cách truy xuất.

Cân nhắc chuyển sang QMD nếu bạn cần xếp hạng lại, mở rộng truy vấn, hoặc muốn lập chỉ mục các thư mục bên ngoài workspace.

Cân nhắc Honcho nếu bạn muốn bộ nhớ xuyên phiên với mô hình hóa người dùng tự động.

Khắc phục sự cố

Tìm kiếm bộ nhớ bị tắt? Kiểm tra openclaw memory status. Nếu không có nhà cung cấp nào được phát hiện, hãy đặt rõ một nhà cung cấp hoặc thêm API key.

Không phát hiện nhà cung cấp cục bộ? Xác nhận đường dẫn cục bộ tồn tại rồi chạy:

openclaw memory status --deep --agent main
openclaw memory index --force --agent main

Cả lệnh CLI độc lập và Gateway đều dùng cùng id nhà cung cấp local. Nếu nhà cung cấp được đặt thành auto, embedding cục bộ chỉ được xét trước tiên khi memorySearch.local.modelPath trỏ đến một tệp cục bộ hiện có.

Kết quả cũ? Chạy openclaw memory index --force để xây dựng lại. Trình theo dõi có thể bỏ sót thay đổi trong một số trường hợp hiếm.

sqlite-vec không tải được? OpenClaw tự động fallback về độ tương đồng cosine trong tiến trình. openclaw memory status --deep báo cáo kho vector cục bộ tách biệt với nhà cung cấp embedding, vì vậy Vector store: unavailable chỉ đến việc tải sqlite-vec, còn Embeddings: unavailable chỉ đến nhà cung cấp/xác thực hoặc trạng thái sẵn sàng của mô hình. Kiểm tra log để biết lỗi tải cụ thể.

Cấu hình

Để thiết lập nhà cung cấp embedding, tinh chỉnh tìm kiếm hybrid (trọng số, MMR, suy giảm theo thời gian), lập chỉ mục theo lô, bộ nhớ đa phương thức, sqlite-vec, đường dẫn bổ sung và mọi núm cấu hình khác, hãy xem tham chiếu cấu hình bộ nhớ.

Liên quan