Tài liệu tham khảo về cấu hình bộ nhớ

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

Mọi cài đặt tìm kiếm bộ nhớ đều nằm trong agents.defaults.memorySearch tại openclaw.json (hoặc một giá trị ghi đè agents.list[].memorySearch theo từng tác nhân), trừ khi có ghi chú khác.

Ghi nhớ giữa các cuộc trò chuyện

Hãy cấu hình theo từng tác nhân khi chỉ một tác nhân cá nhân đáng tin cậy được phép sử dụng khả năng truy hồi bản chép lời xuyên cuộc trò chuyện:

{  agents: {    list: [      {        id: "personal",        memorySearch: {          rememberAcrossConversations: true,        },      },    ],  },}

Giá trị tuân theo cơ chế kế thừa agents.defaults.memorySearch thông thường với một giá trị ghi đè theo từng tác nhân. Khi chưa đặt, giá trị này chỉ mặc định bật nếu session.dmScope toàn cục chưa được đặt hoặc là "main" và không liên kết nào có giá trị ghi đè session.dmScope. Mọi cấu hình cô lập DM đều khiến giá trị này mặc định tắt. Giá trị true hoặc false được đặt rõ ràng luôn được ưu tiên. Việc bật tính năng này ngụ ý lập chỉ mục bản chép lời phiên và thêm sessions vào các nguồn bộ nhớ đã phân giải của tác nhân. Với QMD, tính năng này cũng bật xuất phiên của tác nhân đó; chế độ này không yêu cầu cài đặt memory.qmd.sessions.enabled riêng.

Nhà cung cấp bộ nhớ tích hợp sẵn của OpenClaw hỗ trợ đường dẫn được bảo vệ này với cả backend tích hợp sẵn và QMD. Các nhà cung cấp bộ nhớ thay thế vẫn có thể tiếp tục sử dụng hook truy hồi riêng và các công cụ Active Memory nâng cao, nhưng cài đặt này sẽ bị bỏ qua trừ khi nhà cung cấp hiện tại hỗ trợ truy hồi bản chép lời riêng tư được bảo vệ. openclaw doctor báo cáo nhà cung cấp không được hỗ trợ hoặc danh sách Active Memory toolsAllow được đặt rõ ràng nhưng không bao gồm memory_search.

Ranh giới truy xuất hẹp hơn so với tìm kiếm phiên thông thường:

• chỉ các cuộc trò chuyện riêng tư được nhận diện của cùng tác nhân mới đủ điều kiện
• cuộc trò chuyện đang được trả lời bị loại trừ
• các nhóm và kênh bị loại khỏi cả nguồn lẫn đích
• các loại cuộc trò chuyện không xác định sẽ từ chối theo nguyên tắc an toàn
• khả năng truy hồi trong sandbox không thể sử dụng quyền đặc biệt xuyên cuộc trò chuyện

Cài đặt này không thay đổi tools.sessions.visibility, khóa phiên, cơ chế lưu trữ bản chép lời, định tuyến phân phối hoặc quyền của sessions_list, sessions_history và sessions_send. Active Memory thực hiện một lượt truy xuất chỉ đọc có giới hạn; việc truy xuất không khả dụng hoặc hết thời gian không chặn phản hồi.

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

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

Khi provider chưa được đặt, provider: "auto" cũ vẫn tồn tại hoặc provider: "none" 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 từ vựng khi embedding không khả dụng.

Các nhà cung cấp không cục bộ được chỉ định rõ ràng sẽ từ chối theo nguyên tắc an toàn. 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 khi 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.

ID 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 dành riêng cho bộ nhớ như ollama, hoặc cho các API mô hình tương thích với OpenAI như openai-responses / openai-completions. OpenClaw phân giải chủ sở hữu api của nhà cung cấp đó cho bộ điều hợp embedding, đồng thời giữ nguyên ID nhà cung cấp tùy chỉnh để xử lý endpoint, 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 embedding bộ nhớ cho một endpoint 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

Embedding 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, SSO, khóa truy cập hoặc khóa API Bedrock).

Cấu hình endpoint từ xa

Sử dụng provider: "openai-compatible" cho một máy chủ /v1/embeddings chung tương thích với OpenAI 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ả nằm trong memorySearch.sync, trừ khi có ghi chú khác:

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

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

Và trong memorySearch.query.hybrid:

Ví dụ đầy đủ

{  agents: {    defaults: {      memorySearch: {        query: {          maxResults: 6,          minScore: 0.35,          hybrid: {            mmr: { enabled: true },            temporalDecay: { enabled: true },          },        },      },    },  },}

Đườ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 backend đang hoạt động: công cụ tích hợp 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.

Đối với tìm kiếm bản ghi hội thoại giữa các agent trong phạm vi agent, hãy dùng agents.list[].memorySearch.qmd.extraCollections thay cho memory.qmd.paths. Các bộ sưu tập bổ sung đó tuân theo cùng cấu trúc { path, name, pattern? }, nhưng được hợp nhất theo từng agent và có thể giữ nguyên tên dùng chung được chỉ định rõ khi đường dẫn trỏ ra ngoài workspace 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 khi lập lại chỉ mục hoặc cập nhật bản ghi hội thoại.

Lập chỉ mục theo lô

Khả dụng cho gemini, openai và voyage. Tác vụ theo lô của OpenAI thường nhanh nhất và tiết kiệm chi phí nhất khi điền bù dữ liệu quy mô lớn.

remote.nonBatchConcurrency kiểm soát các lệnh gọi embedding nội tuyến được dùng bởi nhà cung cấp cục bộ/tự lưu trữ và 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 dùng 1 cho việc lập chỉ mục không theo lô để tránh gây quá tải cho 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 lớn hơn.

Thiết lập này tách biệt với sync.embeddingBatchTimeoutSeconds, thiết lập kiểm soát thời gian chờ cho các lệnh gọi embedding nội tuyến.

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

Lập chỉ mục bản ghi hội thoại phiên và hiển thị chúng qua memory_search:

Tìm kiếm bản ghi hội thoại phiên thông thường do mô hình gọi tuân theo tools.sessions.visibility. Phạm vi hiển thị tree mặc định cho phép truy cập phiên hiện tại, các phiên do phiên đó tạo ra và các phiên nhóm của cùng agent được theo dõi thông qua nhận biết nhóm ngầm định. Các phiên không liên quan khác yêu cầu phạm vi hiển thị agent (hoặc all chỉ khi cũng cần truy hồi giữa các agent và chính sách agent-với-agent cho phép).

rememberAcrossConversations không mở rộng thiết lập đó. Nó cung cấp một quyền riêng biệt chỉ dành cho thời gian chạy, giới hạn ở các bản ghi hội thoại riêng tư của cùng agent trong lượt Active Memory có giới hạn.

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 agent khi chỉ một agent cần lập chỉ mục và tìm kiếm bản ghi hội thoại phiên.

Để truy hồi từ gateway đến DM trong cùng agent:

{  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 dùng QMD, bản thân agents.defaults.memorySearch.experimental.sessionMemory và sources: ["sessions"] không xuất bản ghi hội thoại vào QMD. Hãy đặt cả memory.qmd.sessions.enabled: true. Thiết lập cấp cao hơn rememberAcrossConversations: true là ngoại lệ: nó ngầm bật việc xuất phiên QMD bắt buộc cho agent đó. Các bản xuất ngầm định vẫn ở chế độ riêng tư: chúng luôn dùng vị trí xuất nội bộ mặc định (cấu hình sessions.exportDir chỉ áp dụng cho các bản xuất tường minh), chỉ được tìm kiếm trong quá trình truy hồi giữa các cuộc hội thoại của agent đó, và memory_get thông thường không thể đọc chúng. Việc đặt tường minh memory.qmd.sessions.enabled: true giữ nguyên hành vi hiện có và biến các bản ghi hội thoại đã xuất thành một phần của kho ngữ liệu bộ nhớ thông thường.

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

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

Lưu trữ chỉ mục

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

Cấu hình backend QMD

Đặt memory.backend = "qmd" để bật. Tất cả thiết lập QMD nằm trong memory.qmd:

searchMode: "search" chỉ dùng tìm kiếm từ vựng/BM25. OpenClaw không chạy các bước thăm dò 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 QMD sẵn sàng xử lý vectơ 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 cho công cụ truy vấn hợp nhất của QMD. Để trống thiết lập 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 cấu trúc 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 của các bản phát hành QMD cũ 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 công bố 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 theo từng bộ sưu tập. Cùng nguồn 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, trong khi các bộ sưu tập bản ghi hội thoại phiên vẫn là một nhóm riêng để quá trình đ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 tìm kiếm QMD qua daemon MCP mcporter hoạt động lâu dài thay vì khởi chạy 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 cấu hình để chạy qmd mcp. Giữ trạng thái tắt cho các thiết lập cục bộ đơn giản hơn, nơi chi phí khởi chạy tiến trình cho mỗi truy vấn là chấp nhận được.

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

Khi bật khởi tạo QMD lúc Gateway khởi động, 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/tạo embedding, quá trình khởi động sẽ dùng trình quản lý dùng một lần để làm mới khi khởi động rồi đóng lại. Nếu cấu hình khoảng thời gian cập nhật hoặc tạo embedding, quá trình khởi động sẽ mở trình quản lý QMD dài hạn để trình này quản lý bộ 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 nhẹ/sâu/REM nội bộ 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ớ