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

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

Tất cả cài đặt tìm kiếm bộ nhớ nằm trong agents.defaults.memorySearch ở openclaw.json trừ khi có ghi chú khác.

# Chọn nhà cung cấp

# Thứ tự tự động phát hiện

Khi provider không được đặt, OpenClaw chọn mục khả dụng đầu tiên:

ollama được hỗ trợ nhưng không được tự động phát hiện (hãy đặt rõ ràng).

# ID nhà cung cấp tùy chỉnh

memorySearch.provider có thể trỏ tới một mục models.providers.<id> tùy chỉnh. OpenClaw phân giải chủ sở hữu api của nhà cung cấp đó cho adapter embedding trong khi vẫn giữ 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 host 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" }],
      },
    },
  },
  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 dùng chuỗi thông tin xác thực mặc định của AWS SDK (vai trò instance, SSO, khóa truy cập).

# Cấu hình endpoint từ xa

Dành cho endpoint tùy chỉnh tương thích OpenAI hoặc ghi đè mặc định của nhà cung cấp:

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

# Cấu hình theo nhà cung cấp

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        remote: {
          baseUrl: "https://embeddings.example/v1",
          apiKey: "env: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 main
openclaw memory index --force --agent main

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

# Cấu hình tìm kiếm lai

Tất cả nằm dưới memorySearch.query.hybrid:

# Ví dụ đầy đủ

{
  agents: {
    defaults: {
      memorySearch: {
        query: {
          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 workspace. Các thư mục được quét đệ quy để tìm tệp .md. Cách xử lý symlink phụ thuộc vào backend đang hoạt động: engine tích hợp bỏ qua symlink, còn QMD tuân theo hành vi của trình quét QMD bên dưới.

Đối với tìm kiếm bản ghi xuyên tác tử trong phạm vi tác tử, hãy dùng agents.list[].memorySearch.qmd.extraCollections thay vì memory.qmd.paths. Các bộ sưu tập bổ sung đó có cùng dạng { path, name, pattern? }, nhưng được hợp nhất theo từng tác tử và có thể giữ lại tên chia sẻ rõ ràng 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:

Đị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 đổi trong quá trình lập chỉ mục lại hoặc cập nhật bản ghi phiên.

# Lập chỉ mục theo lô

Có sẵn cho openai, gemini và voyage. Lô OpenAI thường nhanh nhất và rẻ nhất cho các lần điền ngược dữ liệu 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 là 1 cho 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; đặt giá trị cao hơn trên máy 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ờ 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 phiên và hiển thị chúng qua memory_search:

# Tăng tốc vector SQLite (sqlite-vec)

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

# Lưu trữ chỉ mục

# Cấu hình backend QMD

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

searchMode: "search" chỉ dùng lexical/BM25. OpenClaw không chạy các probe sẵn sàng vector ngữ nghĩa hoặc bảo trì embedding QMD cho chế độ đó, kể cả trong memory status --deep; vsearch và query vẫn tiếp tục yêu cầu QMD vector readiness và embeddings.

OpenClaw ưu tiên collection QMD hiện tại và các dạng truy vấn MCP, nhưng vẫn giữ cho các bản phát hành QMD cũ hoạt động bằng cách thử các cờ mẫu collection tương thích và tên công cụ MCP cũ hơn khi cần. Khi QMD cho biết có hỗ trợ nhiều bộ lọc collection, các collection 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 giữ đường dẫn tương thích theo từng collection. Cùng nguồn nghĩa là các collection bộ nhớ bền vững được nhóm lại với nhau, trong khi các collection bản ghi phiên vẫn là một nhóm riêng để đa dạng hóa nguồn vẫn có cả hai đầu vào.

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

Các lần làm mới khi khởi động QMD dùng đường dẫn tiến trình con one-shot trong lúc gateway khởi động. Trình quản lý QMD chạy lâu dài vẫn sở hữu file watcher thông thường và các bộ hẹn giờ interval khi tìm kiếm bộ nhớ được mở để sử dụng tương tác.

# Ví dụ QMD đầy đủ

{
  memory: {
    backend: "qmd",
    citations: "auto",
    qmd: {
      includeDefaultMemory: true,
      update: { interval: "5m", debounceMs: 15000 },
      limits: { maxResults: 6, 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 dưới plugins.entries.memory-core.config.dreaming, không phải dưới agents.defaults.memorySearch.

Dreaming chạy như một lượt quét được lập lịch và sử dụng các pha light/deep/REM nội bộ như một chi tiết triển khai.

Để biết hành vi khái niệm và các lệnh slash, 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ớ