Tham chiếu cấu hình bộ nhớ

Trang này liệt kê mọi tùy chọn cấu hình cho chức năng tìm kiếm bộ nhớ của OpenClaw. Để xem tổng quan về khái niệm, hãy tham khảo:

Tất cả cài đặt tìm kiếm bộ nhớ đều nằm trong agents.defaults.memorySearch của openclaw.json (hoặc phần ghi đè agents.list[].memorySearch cho từng tác tử), trừ khi có ghi chú khác.

Lựa chọn nhà cung cấp

Khi chưa đặt provider, OpenClaw sử dụng tính năng nhúng của OpenAI. Hãy đặt rõ provider để sử dụng Bedrock, DeepInfra, Gemini, GitHub Copilot, Mistral, Ollama, Voyage, mô hình GGUF cục bộ hoặc điểm cuối /v1/embeddings tương thích với OpenAI. Các cấu hình cũ vẫn có provider: "auto" sẽ được phân giải thành openai.

Khi provider chưa được đặt, có cấu hình cũ provider: "auto" hoặc provider: "none" được dùng để chủ ý chọn chế độ chỉ dùng FTS, việc truy hồi bộ nhớ vẫn có thể sử dụng xếp hạng FTS theo từ vựng khi tính năng nhúng không khả dụng.

Các nhà cung cấp không cục bộ được chỉ định rõ sẽ đóng khi gặp lỗi. Nếu bạn đặt memorySearch.provider thành một nhà cung cấp cụ thể dựa trên dịch vụ từ xa như Bedrock, DeepInfra, Gemini, GitHub Copilot, LM Studio, Mistral, Ollama, OpenAI, Voyage hoặc một nhà cung cấp tùy chỉnh tương thích với OpenAI và nhà cung cấp đó không khả dụng trong thời gian chạy, memory_search sẽ trả về kết quả không khả dụng thay vì âm thầm sử dụng truy hồi chỉ bằng FTS. Hãy sửa cấu hình nhà cung cấp/xác thực, chuyển sang một nhà cung cấp có thể truy cập hoặc đặt provider: "none" nếu bạn chủ ý muốn truy hồi chỉ bằng FTS.

Mã định danh nhà cung cấp tùy chỉnh

memorySearch.provider có thể trỏ đến một mục models.providers.<id> tùy chỉnh dành cho các bộ điều hợp nhà cung cấp chuyên biệt cho bộ nhớ như ollama, hoặc dành cho các API mô hình tương thích với OpenAI như openai-responses / openai-completions. OpenClaw phân giải bên sở hữu api của nhà cung cấp đó cho bộ điều hợp nhúng, đồng thời giữ nguyên mã định danh nhà cung cấp tùy chỉnh để xử lý điểm cuối, xác thực và tiền tố mô hình. Điều này cho phép các thiết lập nhiều GPU hoặc nhiều máy chủ dành riêng việc nhúng bộ nhớ cho một điểm cuối cục bộ cụ thể:

{  models: {    providers: {      "ollama-5080": {        api: "ollama",        baseUrl: "http://gpu-box.local:11435",        apiKey: "ollama-local",        models: [{ id: "qwen3-embedding:0.6b", name: "Qwen3 Embedding 0.6B" }],      },    },  },  agents: {    defaults: {      memorySearch: {        provider: "ollama-5080",        model: "qwen3-embedding:0.6b",      },    },  },}

Phân giải khóa API

Tính năng nhúng từ xa yêu cầu khóa API. Thay vào đó, Bedrock sử dụng chuỗi thông tin xác thực mặc định của AWS SDK (vai trò phiên bản máy, SSO, khóa truy cập hoặc khóa API Bedrock).

Cấu hình điểm cuối từ xa

Sử dụng provider: "openai-compatible" cho máy chủ /v1/embeddings tương thích chung với OpenAI nhưng không được kế thừa thông tin xác thực trò chuyện OpenAI toàn cục.

{  agents: {    defaults: {      memorySearch: {        provider: "openai-compatible",        model: "text-embedding-3-small",        remote: {          baseUrl: "https://api.example.com/v1/",          apiKey: "YOUR_KEY",        },      },    },  },}

Cấu hình dành riêng cho nhà cung cấp

{  agents: {    defaults: {      memorySearch: {        provider: "openai-compatible",        remote: {          baseUrl: "https://embeddings.example/v1",          apiKey: "${EMBEDDINGS_API_KEY}",        },        model: "asymmetric-embedder",        queryInputType: "query",        documentInputType: "passage",      },    },  },}

{  agents: {    defaults: {      memorySearch: {        provider: "bedrock",        model: "amazon.titan-embed-text-v2:0",      },    },  },}

{  "Effect": "Allow",  "Action": "bedrock:InvokeModel",  "Resource": "*"}

arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0

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

Thời gian chờ embedding nội tuyến

Hành vi lập chỉ mục

Tất cả đều thuộc memorySearch.sync, trừ khi có ghi chú khác:

Cấu hình tìm kiếm kết hợp

Tất cả đều nằm trong memorySearch.query:

Và trong memorySearch.query.hybrid:

Ví dụ đầy đủ

{  agents: {    defaults: {      memorySearch: {        query: {          maxResults: 6,          minScore: 0.35,          hybrid: {            vectorWeight: 0.7,            textWeight: 0.3,            mmr: { enabled: true, lambda: 0.7 },            temporalDecay: { enabled: true, halfLifeDays: 30 },          },        },      },    },  },}

Đường dẫn bộ nhớ bổ sung

{  agents: {    defaults: {      memorySearch: {        extraPaths: ["../team-docs", "/srv/shared-notes"],      },    },  },}

Đường dẫn có thể là tuyệt đối hoặc tương đối với không gian làm việc. Các thư mục được quét đệ quy để tìm tệp .md. Cách xử lý liên kết tượng trưng phụ thuộc vào phần phụ trợ đang hoạt động: công cụ tích hợp sẵn bỏ qua liên kết tượng trưng, còn QMD tuân theo hành vi của trình quét QMD nền tảng.

Để tìm kiếm bản chép lời giữa các tác nhân trong phạm vi tác nhân, hãy dùng agents.list[].memorySearch.qmd.extraCollections thay cho memory.qmd.paths. Các bộ sưu tập bổ sung đó có cùng cấu trúc { path, name, pattern? }, nhưng được hợp nhất theo từng tác nhân và có thể giữ nguyên tên dùng chung được chỉ định rõ khi đường dẫn trỏ ra ngoài không gian làm việc hiện tại. Nếu cùng một đường dẫn đã phân giải xuất hiện trong cả memory.qmd.paths và memorySearch.qmd.extraCollections, QMD giữ mục đầu tiên và bỏ qua mục trùng lặp.

Bộ nhớ đa phương thức (Gemini)

Lập chỉ mục hình ảnh và âm thanh cùng với Markdown bằng Gemini Embedding 2:

Các định dạng được hỗ trợ: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (hình ảnh); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (âm thanh).

Bộ nhớ đệm embedding

Ngăn việc tạo lại embedding cho văn bản không thay đổi trong quá trình lập chỉ mục lại hoặc cập nhật bản chép lời. Để maxEntries ở trạng thái chưa thiết lập nếu muốn bộ nhớ đệm không giới hạn; hãy thiết lập giá trị này khi mức tăng dung lượng ổ đĩa quan trọng hơn tốc độ lập chỉ mục lại tối đa. Khi được thiết lập, các mục cũ nhất (theo thời gian cập nhật gần nhất) sẽ bị loại bỏ trước khi bộ nhớ đệm vượt quá giới hạn.

Lập chỉ mục theo lô

Khả dụng cho gemini, openai và voyage. Chế độ theo lô của OpenAI thường nhanh nhất và rẻ nhất khi bổ sung lượng lớn dữ liệu cũ.

remote.nonBatchConcurrency kiểm soát các lệnh gọi embedding trực tiếp được dùng bởi các nhà cung cấp cục bộ/tự lưu trữ và các nhà cung cấp được lưu trữ khi API theo lô của nhà cung cấp không hoạt động. Ollama mặc định là 1 đối với việc lập chỉ mục không theo lô để tránh làm quá tải các máy chủ cục bộ nhỏ hơn; hãy đặt giá trị cao hơn trên các máy có cấu hình mạnh hơn.

Thiết lập này tách biệt với sync.embeddingBatchTimeoutSeconds, vốn kiểm soát thời gian chờ tối đa cho các lệnh gọi embedding trực tiếp.

Tìm kiếm bộ nhớ phiên (thử nghiệm)

Lập chỉ mục bản chép lời phiên và cung cấp chúng qua memory_search:

Các kết quả khớp từ bản chép lời phiên cũng tuân theo tools.sessions.visibility. Chế độ hiển thị mặc định tree chỉ cho phép truy cập phiên hiện tại và các phiên do phiên đó tạo ra. Để truy xuất một phiên không liên quan của cùng tác nhân, được Gateway điều phối từ một phiên khác, chẳng hạn như tin nhắn trực tiếp, hãy chủ động mở rộng chế độ hiển thị thành agent (hoặc chỉ dùng all khi cũng cần truy xuất giữa các tác nhân và chính sách giữa tác nhân với tác nhân cho phép).

Các ví dụ bên dưới đặt những thiết lập này trong agents.defaults. Bạn cũng có thể áp dụng các thiết lập memorySearch tương đương trong phần ghi đè theo từng tác nhân khi chỉ một tác nhân cần lập chỉ mục và tìm kiếm bản chép lời phiên.

Để truy xuất từ Gateway sang tin nhắn trực tiếp trong cùng tác nhân:

{  agents: {    defaults: {      memorySearch: {        experimental: { sessionMemory: true },        sources: ["memory", "sessions"],      },    },  },  tools: {    sessions: { visibility: "agent" },  },}

{  agents: {    defaults: {      memorySearch: {        experimental: { sessionMemory: true },        sources: ["memory", "sessions"],      },    },  },  memory: {    backend: "qmd",    qmd: {      sessions: { enabled: true },    },  },  tools: {    sessions: { visibility: "agent" },  },}

Khi sử dụng QMD, riêng agents.defaults.memorySearch.experimental.sessionMemory và sources: ["sessions"] không xuất bản chép lời vào QMD. Đồng thời hãy đặt memory.qmd.sessions.enabled: true.

Tăng tốc vectơ SQLite (sqlite-vec)

Khi sqlite-vec không khả dụng, OpenClaw tự động chuyển sang sử dụng độ tương đồng cosin trong tiến trình.

Lưu trữ chỉ mục

Các chỉ mục bộ nhớ tích hợp nằm trong cơ sở dữ liệu SQLite OpenClaw của từng tác nhân tại agents/<agentId>/agent/openclaw-agent.sqlite.

Cấu hình backend QMD

Đặt memory.backend = "qmd" để bật. Tất cả cài đặt QMD nằm trong memory.qmd:

searchMode: "search" chỉ sử dụng tìm kiếm từ vựng/BM25. OpenClaw không chạy các phép kiểm tra mức độ sẵn sàng của vectơ ngữ nghĩa hoặc bảo trì embedding QMD cho chế độ đó, kể cả trong memory status --deep; vsearch và query vẫn yêu cầu vectơ QMD sẵn sàng và có embedding.

rerank: false chỉ thay đổi chế độ query của QMD và yêu cầu QMD 2.1 trở lên. Trong chế độ CLI trực tiếp, OpenClaw truyền --no-rerank; trong chế độ MCP dựa trên mcporter, OpenClaw truyền rerank: false đến công cụ truy vấn hợp nhất của QMD. Không đặt giá trị này để sử dụng hành vi xếp hạng lại truy vấn mặc định của QMD.

OpenClaw ưu tiên các dạng truy vấn MCP và bộ sưu tập QMD hiện tại, nhưng vẫn duy trì khả năng hoạt động với các bản phát hành QMD cũ hơn bằng cách thử các cờ mẫu bộ sưu tập tương thích và tên công cụ MCP cũ hơn khi cần. Khi QMD thông báo hỗ trợ nhiều bộ lọc bộ sưu tập, các bộ sưu tập cùng nguồn được tìm kiếm bằng một tiến trình QMD; các bản dựng QMD cũ hơn tiếp tục dùng đường dẫn tương thích riêng cho từng bộ sưu tập. Cùng nguồn có nghĩa là các bộ sưu tập bộ nhớ bền vững (các tệp bộ nhớ mặc định cùng với đường dẫn tùy chỉnh) được nhóm lại với nhau, trong khi các bộ sưu tập bản ghi phiên vẫn là một nhóm riêng để việc đa dạng hóa nguồn vẫn có cả hai đầu vào.

Tích hợp mcporter

Tất cả nằm trong memory.qmd.mcporter. Định tuyến các lượt tìm kiếm QMD qua một trình nền MCP mcporter chạy lâu dài thay vì tạo qmd cho mỗi truy vấn, giúp giảm chi phí khởi động nguội đối với các mô hình lớn hơn.

Yêu cầu cài đặt mcporter và có trong PATH, cùng với một máy chủ mcporter đã cấu hình để chạy qmd mcp. Giữ trạng thái tắt đối với các thiết lập cục bộ đơn giản hơn, nơi chi phí tạo tiến trình cho từng truy vấn ở mức chấp nhận được.

{  memory: {    qmd: {      scope: {        default: "deny",        rules: [{ action: "allow", match: { chatType: "direct" } }],      },    },  },}

Khi tính năng khởi tạo QMD lúc Gateway khởi động được bật, OpenClaw chỉ khởi động QMD cho các tác tử đủ điều kiện. Nếu update.onBoot là true và không cấu hình bảo trì theo khoảng thời gian/nhúng, quá trình khởi động sử dụng một trình quản lý chạy một lần để làm mới khi khởi động rồi đóng trình quản lý đó. Nếu cấu hình khoảng thời gian cập nhật hoặc nhúng, quá trình khởi động sẽ mở trình quản lý QMD dài hạn để quản lý trình theo dõi và các bộ hẹn giờ theo khoảng thời gian; update.onBoot: false chỉ bỏ qua lần làm mới ngay khi khởi động.

Ví dụ QMD đầy đủ

{  memory: {    backend: "qmd",    citations: "auto",    qmd: {      includeDefaultMemory: true,      update: { interval: "5m", debounceMs: 15000 },      limits: { maxResults: 4, timeoutMs: 4000 },      scope: {        default: "deny",        rules: [{ action: "allow", match: { chatType: "direct" } }],      },      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],    },  },}

Dreaming

Dreaming được cấu hình trong plugins.entries.memory-core.config.dreaming, không phải trong agents.defaults.memorySearch.

Dreaming chạy dưới dạng một lượt quét theo lịch duy nhất và sử dụng các giai đoạn nội bộ nhẹ/sâu/REM như một chi tiết triển khai.

Để tìm hiểu hành vi khái niệm và các lệnh gạch chéo, hãy xem Dreaming.

Cài đặt người dùng

Ví dụ

{  plugins: {    entries: {      "memory-core": {        subagent: {          allowModelOverride: true,          allowedModels: ["anthropic/claude-sonnet-4-6"],        },        config: {          dreaming: {            enabled: true,            frequency: "0 3 * * *",            model: "anthropic/claude-sonnet-4-6",          },        },      },    },  },}

Liên quan

• Tham chiếu cấu hình
• Tổng quan về bộ nhớ
• Tìm kiếm bộ nhớ