​

Tham khảo cấu hình bộ nhớ

​

Mặc định tìm kiếm bộ nhớ

• Được kích hoạt mặc định.
• Theo dõi các file bộ nhớ để phát hiện thay đổi (debounced).
• Cấu hình tìm kiếm bộ nhớ dưới agents.defaults.memorySearch (không phải memorySearch cấp cao nhất).
• Sử dụng embedding từ xa mặc định. Nếu memorySearch.provider không được thiết lập, OpenClaw tự động chọn:
  1. local nếu memorySearch.local.modelPath được cấu hình và file tồn tại.
  2. openai nếu có thể giải quyết khóa OpenAI.
  3. gemini nếu có thể giải quyết khóa Gemini.
  4. voyage nếu có thể giải quyết khóa Voyage.
  5. mistral nếu có thể giải quyết khóa Mistral.
  6. Nếu không, tìm kiếm bộ nhớ sẽ bị vô hiệu hóa cho đến khi được cấu hình.
• Chế độ local sử dụng node-llama-cpp và có thể yêu cầu pnpm approve-builds.
• Sử dụng sqlite-vec (khi có sẵn) để tăng tốc tìm kiếm vector trong SQLite.
• memorySearch.provider = "ollama" cũng được hỗ trợ cho embedding Ollama local/self-hosted (/api/embeddings), nhưng không được tự động chọn.

​

Backend QMD (thử nghiệm)

​

Yêu cầu

• Vô hiệu hóa mặc định. Chọn tham gia theo cấu hình (memory.backend = "qmd").
• Cài đặt CLI QMD riêng (bun install -g https://github.com/tobi/qmd hoặc tải bản phát hành) và đảm bảo binary qmd có trong PATH của gateway.
• QMD cần một bản dựng SQLite cho phép mở rộng (brew install sqlite trên macOS).
• QMD chạy hoàn toàn local qua Bun + node-llama-cpp và tự động tải xuống các mô hình GGUF từ HuggingFace khi sử dụng lần đầu (không cần daemon Ollama riêng).
• Gateway chạy QMD trong một XDG home tự chứa dưới ~/.openclaw/agents/<agentId>/qmd/ bằng cách thiết lập XDG_CONFIG_HOME và XDG_CACHE_HOME.
• Hỗ trợ hệ điều hành: macOS và Linux hoạt động ngay khi Bun + SQLite được cài đặt. Windows được hỗ trợ tốt nhất qua WSL2.

​

Cách sidecar hoạt động

• Gateway ghi một QMD home tự chứa dưới ~/.openclaw/agents/<agentId>/qmd/ (cấu hình + cache + sqlite DB).
• Các bộ sưu tập được tạo qua qmd collection add từ memory.qmd.paths (cộng với các file bộ nhớ workspace mặc định), sau đó qmd update + qmd embed chạy khi khởi động và theo một khoảng thời gian có thể cấu hình (memory.qmd.update.interval, mặc định 5 phút).
• Gateway hiện khởi tạo trình quản lý QMD khi khởi động, vì vậy các bộ đếm thời gian cập nhật định kỳ được kích hoạt ngay cả trước khi gọi memory_search đầu tiên.
• Làm mới khi khởi động hiện chạy nền mặc định để khởi động chat không bị chặn; thiết lập memory.qmd.update.waitForBootSync = true để giữ hành vi chặn trước đó.
• Tìm kiếm chạy qua memory.qmd.searchMode (mặc định qmd search --json; cũng hỗ trợ vsearch và query). Nếu chế độ đã chọn từ chối cờ trên bản dựng QMD của bạn, OpenClaw thử lại với qmd query. Nếu QMD thất bại hoặc binary bị thiếu, OpenClaw tự động quay lại trình quản lý SQLite tích hợp để các công cụ bộ nhớ tiếp tục hoạt động.
• OpenClaw không tiết lộ điều chỉnh kích thước batch QMD embed hôm nay; hành vi batch được kiểm soát bởi chính QMD.
• Tìm kiếm đầu tiên có thể chậm: QMD có thể tải xuống các mô hình GGUF local (reranker/query expansion) khi chạy qmd query lần đầu tiên.
  • OpenClaw thiết lập XDG_CONFIG_HOME/XDG_CACHE_HOME tự động khi chạy QMD.
  • Nếu bạn muốn tải xuống các mô hình thủ công trước (và làm nóng cùng một index OpenClaw sử dụng), chạy một truy vấn một lần với các thư mục XDG của agent. Trạng thái QMD của OpenClaw nằm dưới thư mục trạng thái của bạn (mặc định là ~/.openclaw). Bạn có thể chỉ định qmd vào cùng một index bằng cách xuất các biến XDG giống như OpenClaw sử dụng:
    Sao chép

    Hỏi AI

    # Chọn cùng thư mục trạng thái mà OpenClaw sử dụng
    STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
    
    export XDG_CONFIG_HOME="$STATE_DIR/agents/main/qmd/xdg-config"
    export XDG_CACHE_HOME="$STATE_DIR/agents/main/qmd/xdg-cache"
    
    # (Tùy chọn) buộc làm mới index + embeddings
    qmd update
    qmd embed
    
    # Làm nóng / kích hoạt tải xuống mô hình lần đầu
    qmd query "test" -c memory-root --json >/dev/null 2>&1
    

​

Bề mặt cấu hình (memory.qmd.*)

• command (mặc định qmd): ghi đè đường dẫn thực thi.
• searchMode (mặc định search): chọn lệnh QMD nào hỗ trợ memory_search (search, vsearch, query).
• includeDefaultMemory (mặc định true): tự động lập chỉ mục MEMORY.md + memory/**/*.md.
• paths[]: thêm thư mục/file bổ sung (path, pattern tùy chọn, name ổn định tùy chọn).
• sessions: chọn tham gia lập chỉ mục JSONL phiên (enabled, retentionDays, exportDir).
• update: kiểm soát tần suất làm mới và thực thi bảo trì: (interval, debounceMs, onBoot, waitForBootSync, embedInterval, commandTimeoutMs, updateTimeoutMs, embedTimeoutMs).
• limits: giới hạn tải trọng recall (maxResults, maxSnippetChars, maxInjectedChars, timeoutMs).
• scope: cùng schema như session.sendPolicy. Mặc định là chỉ DM (deny tất cả, allow chat trực tiếp); nới lỏng để hiển thị kết quả QMD trong nhóm/kênh.
  • match.keyPrefix khớp với khóa phiên đã chuẩn hóa (viết thường, loại bỏ bất kỳ agent:<id>: nào ở đầu). Ví dụ: discord:channel:.
  • match.rawKeyPrefix khớp với khóa phiên thô (viết thường), bao gồm agent:<id>:. Ví dụ: agent:main:discord:.
  • Legacy: match.keyPrefix: "agent:..." vẫn được coi là một tiền tố khóa thô, nhưng nên sử dụng rawKeyPrefix để rõ ràng.
• Khi scope từ chối một tìm kiếm, OpenClaw ghi lại cảnh báo với channel/chatType đã được suy ra để dễ dàng gỡ lỗi kết quả trống.
• Các đoạn trích nguồn từ bên ngoài workspace xuất hiện dưới dạng qmd/<collection>/<relative-path> trong kết quả memory_search; memory_get hiểu tiền tố đó và đọc từ gốc bộ sưu tập QMD đã cấu hình.
• Khi memory.qmd.sessions.enabled = true, OpenClaw xuất các bản ghi phiên đã được làm sạch (User/Assistant turns) vào một bộ sưu tập QMD chuyên dụng dưới ~/.openclaw/agents/<id>/qmd/sessions/, vì vậy memory_search có thể nhớ lại các cuộc trò chuyện gần đây mà không cần chạm vào index SQLite tích hợp.
• Các đoạn trích memory_search hiện bao gồm một footer Source: <path#line> khi memory.citations là auto/on; thiết lập memory.citations = "off" để giữ thông tin metadata nội bộ (agent vẫn nhận được đường dẫn cho memory_get, nhưng văn bản đoạn trích bỏ qua footer và hệ thống nhắc nhở agent không trích dẫn nó).

​

Ví dụ QMD

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" } },
        // Tiền tố khóa phiên đã chuẩn hóa (loại bỏ `agent:<id>:`).
        { action: "deny", match: { keyPrefix: "discord:channel:" } },
        // Tiền tố khóa phiên thô (bao gồm `agent:<id>:`).
        { action: "deny", match: { rawKeyPrefix: "agent:main:discord:" } },
      ]
    },
    paths: [
      { name: "docs", path: "~/notes", pattern: "**/*.md" }
    ]
  }
}

​

Trích dẫn và dự phòng

• memory.citations áp dụng bất kể backend (auto/on/off).
• Khi qmd chạy, chúng tôi gắn thẻ status().backend = "qmd" để chẩn đoán hiển thị động cơ nào đã phục vụ kết quả. Nếu quy trình con QMD thoát hoặc đầu ra JSON không thể phân tích, trình quản lý tìm kiếm ghi lại cảnh báo và trả về nhà cung cấp tích hợp (embedding Markdown hiện có) cho đến khi QMD phục hồi.

​

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

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

• Đường dẫn có thể là tuyệt đối hoặc tương đối với workspace.
• Thư mục được quét đệ quy cho các file .md.
• Mặc định, chỉ các file Markdown được lập chỉ mục.
• Nếu memorySearch.multimodal.enabled = true, OpenClaw cũng lập chỉ mục các file hình ảnh/âm thanh được hỗ trợ chỉ dưới extraPaths. Các gốc bộ nhớ mặc định (MEMORY.md, memory.md, memory/**/*.md) vẫn chỉ là Markdown.
• Symlinks bị bỏ qua (file hoặc thư mục).

​

File bộ nhớ đa phương tiện (hình ảnh + âm thanh Gemini)

agents: {
  defaults: {
    memorySearch: {
      provider: "gemini",
      model: "gemini-embedding-2-preview",
      extraPaths: ["assets/reference", "voice-notes"],
      multimodal: {
        enabled: true,
        modalities: ["image", "audio"], // hoặc ["all"]
        maxFileBytes: 10000000
      },
      remote: {
        apiKey: "YOUR_GEMINI_API_KEY"
      }
    }
  }
}

• Bộ nhớ đa phương tiện hiện chỉ được hỗ trợ cho gemini-embedding-2-preview.
• Lập chỉ mục đa phương tiện chỉ áp dụng cho các file được phát hiện qua memorySearch.extraPaths.
• Các loại hình thức được hỗ trợ trong giai đoạn này: hình ảnh và âm thanh.
• memorySearch.fallback phải giữ là "none" trong khi bộ nhớ đa phương tiện được kích hoạt.
• Các byte file hình ảnh/âm thanh phù hợp được tải lên endpoint embedding Gemini đã cấu hình trong quá trình lập chỉ mục.
• Các phần mở rộng hình ảnh được hỗ trợ: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif.
• Các phần mở rộng âm thanh được hỗ trợ: .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac.
• Các truy vấn tìm kiếm vẫn là văn bản, nhưng Gemini có thể so sánh các truy vấn văn bản đó với các embedding hình ảnh/âm thanh đã lập chỉ mục.
• memory_get vẫn chỉ đọc Markdown; các file nhị phân có thể tìm kiếm nhưng không được trả về dưới dạng nội dung file thô.

​

Embedding Gemini (native)

agents: {
  defaults: {
    memorySearch: {
      provider: "gemini",
      model: "gemini-embedding-001",
      remote: {
        apiKey: "YOUR_GEMINI_API_KEY"
      }
    }
  }
}

• remote.baseUrl là tùy chọn (mặc định là URL cơ sở API Gemini).
• remote.headers cho phép bạn thêm các header bổ sung nếu cần.
• Mô hình mặc định: gemini-embedding-001.
• gemini-embedding-2-preview cũng được hỗ trợ: giới hạn 8192 token và các kích thước có thể cấu hình (768 / 1536 / 3072, mặc định 3072).

​

Embedding Gemini 2 (preview)

agents: {
  defaults: {
    memorySearch: {
      provider: "gemini",
      model: "gemini-embedding-2-preview",
      outputDimensionality: 3072,  // tùy chọn: 768, 1536, hoặc 3072 (mặc định)
      remote: {
        apiKey: "YOUR_GEMINI_API_KEY"
      }
    }
  }
}

Yêu cầu lập chỉ mục lại: Chuyển từ gemini-embedding-001 (768 dimensions) sang gemini-embedding-2-preview (3072 dimensions) thay đổi kích thước vector. Điều tương tự cũng xảy ra nếu bạn thay đổi outputDimensionality giữa 768, 1536 và 3072. OpenClaw sẽ tự động lập chỉ mục lại khi phát hiện thay đổi mô hình hoặc kích thước.

​

Endpoint tương thích OpenAI tùy chỉnh

agents: {
  defaults: {
    memorySearch: {
      provider: "openai",
      model: "text-embedding-3-small",
      remote: {
        baseUrl: "https://api.example.com/v1/",
        apiKey: "YOUR_OPENAI_COMPAT_API_KEY",
        headers: { "X-Custom-Header": "value" }
      }
    }
  }
}

​

Dự phòng

• memorySearch.fallback có thể là openai, gemini, voyage, mistral, ollama, local, hoặc none.
• Nhà cung cấp dự phòng chỉ được sử dụng khi nhà cung cấp embedding chính thất bại.

​

Lập chỉ mục batch (OpenAI + Gemini + Voyage)

• Vô hiệu hóa mặc định. Thiết lập agents.defaults.memorySearch.remote.batch.enabled = true để kích hoạt cho lập chỉ mục corpus lớn (OpenAI, Gemini, và Voyage).
• Hành vi mặc định chờ hoàn thành batch; điều chỉnh remote.batch.wait, remote.batch.pollIntervalMs, và remote.batch.timeoutMinutes nếu cần.
• Thiết lập remote.batch.concurrency để kiểm soát số lượng công việc batch chúng tôi gửi song song (mặc định: 2).
• Chế độ batch áp dụng khi memorySearch.provider = "openai" hoặc "gemini" và sử dụng API key tương ứng.
• Công việc batch Gemini sử dụng endpoint batch embedding không đồng bộ và yêu cầu khả dụng API Batch Gemini.

• Đối với các backfill lớn, OpenAI thường là tùy chọn nhanh nhất chúng tôi hỗ trợ vì chúng tôi có thể gửi nhiều yêu cầu embedding trong một công việc batch duy nhất và để OpenAI xử lý chúng không đồng bộ.
• OpenAI cung cấp giá ưu đãi cho các công việc API Batch, vì vậy các lần chạy lập chỉ mục lớn thường rẻ hơn so với gửi cùng các yêu cầu đó đồng bộ.
• Xem tài liệu API Batch OpenAI và giá cả để biết chi tiết:
  • https://platform.openai.com/docs/api-reference/batch
  • https://platform.openai.com/pricing

agents: {
  defaults: {
    memorySearch: {
      provider: "openai",
      model: "text-embedding-3-small",
      fallback: "openai",
      remote: {
        batch: { enabled: true, concurrency: 2 }
      },
      sync: { watch: true }
    }
  }
}

​

Cách các công cụ bộ nhớ hoạt động

• memory_search tìm kiếm ngữ nghĩa các đoạn Markdown (~400 token mục tiêu, 80-token chồng chéo) từ MEMORY.md + memory/**/*.md. Nó trả về văn bản đoạn trích (giới hạn ~700 ký tự), đường dẫn file, phạm vi dòng, điểm số, nhà cung cấp/mô hình, và liệu chúng tôi có dự phòng từ embedding local sang từ xa hay không. Không có tải trọng file đầy đủ nào được trả về.
• memory_get đọc một file Markdown bộ nhớ cụ thể (tương đối với workspace), tùy chọn từ một dòng bắt đầu và trong N dòng. Các đường dẫn ngoài MEMORY.md / memory/ bị từ chối.
• Cả hai công cụ chỉ được kích hoạt khi memorySearch.enabled giải quyết đúng cho agent.

​

Những gì được lập chỉ mục (và khi nào)

• Loại file: Chỉ Markdown (MEMORY.md, memory/**/*.md).
• Lưu trữ chỉ mục: SQLite per-agent tại ~/.openclaw/memory/<agentId>.sqlite (có thể cấu hình qua agents.defaults.memorySearch.store.path, hỗ trợ token {agentId}).
• Tính mới: watcher trên MEMORY.md + memory/ đánh dấu chỉ mục là bẩn (debounce 1.5s). Đồng bộ được lên lịch khi bắt đầu phiên, khi tìm kiếm, hoặc theo khoảng thời gian và chạy không đồng bộ. Bản ghi phiên sử dụng ngưỡng delta để kích hoạt đồng bộ nền.
• Kích hoạt lập chỉ mục lại: chỉ mục lưu trữ embedding provider/model + endpoint fingerprint + chunking params. Nếu bất kỳ điều nào trong số đó thay đổi, OpenClaw tự động đặt lại và lập chỉ mục lại toàn bộ cửa hàng.

​

Tìm kiếm kết hợp (BM25 + vector)

• Vector similarity (khớp ngữ nghĩa, cách diễn đạt có thể khác)
• BM25 keyword relevance (các token chính xác như ID, biến môi trường, ký hiệu mã)

​

Tại sao kết hợp

• “Máy chủ gateway Mac Studio” so với “máy chạy gateway”
• “debounce cập nhật file” so với “tránh lập chỉ mục trên mỗi lần ghi”

• ID (a828e60, b3b9895a...)
• ký hiệu mã (memorySearch.query.hybrid)
• chuỗi lỗi (“sqlite-vec không khả dụng”)

​

Cách chúng tôi hợp nhất kết quả (thiết kế hiện tại)

1. Truy xuất một pool ứng viên từ cả hai bên:

• Vector: top maxResults * candidateMultiplier theo cosine similarity.
• BM25: top maxResults * candidateMultiplier theo xếp hạng BM25 FTS5 (thấp hơn là tốt hơn).

2. Chuyển đổi xếp hạng BM25 thành điểm 0..1-ish:

• textScore = 1 / (1 + max(0, bm25Rank))

3. Hợp nhất ứng viên theo id chunk và tính toán điểm có trọng số:

• finalScore = vectorWeight * vectorScore + textWeight * textScore

• vectorWeight + textWeight được chuẩn hóa thành 1.0 trong giải quyết cấu hình, vì vậy trọng số hoạt động như phần trăm.
• Nếu embedding không khả dụng (hoặc nhà cung cấp trả về một vector không), chúng tôi vẫn chạy BM25 và trả về các khớp từ khóa.
• Nếu FTS5 không thể được tạo, chúng tôi giữ tìm kiếm chỉ vector (không có lỗi nghiêm trọng).

​

Quy trình xử lý hậu kỳ

Vector + Keyword -> Weighted Merge -> Temporal Decay -> Sort -> MMR -> Top-K Results

​

MMR re-ranking (đa dạng)

1. Kết quả được chấm điểm theo sự liên quan ban đầu của chúng (điểm có trọng số vector + BM25).
2. MMR chọn lặp lại các kết quả tối đa hóa: lambda x relevance - (1-lambda) x max_similarity_to_selected.
3. Sự tương đồng giữa các kết quả được đo bằng sự tương đồng văn bản Jaccard trên nội dung đã được token hóa.

• lambda = 1.0 — chỉ sự liên quan (không có hình phạt đa dạng)
• lambda = 0.0 — đa dạng tối đa (bỏ qua sự liên quan)
• Mặc định: 0.7 (cân bằng, hơi thiên về sự liên quan)

memory/2026-02-10.md  -> "Đã cấu hình router Omada, đặt VLAN 10 cho thiết bị IoT"
memory/2026-02-08.md  -> "Đã cấu hình router Omada, chuyển IoT sang VLAN 10"
memory/2026-02-05.md  -> "Đã thiết lập DNS AdGuard trên 192.168.10.2"
memory/network.md     -> "Router: Omada ER605, AdGuard: 192.168.10.2, VLAN 10: IoT"

1. memory/2026-02-10.md  (điểm: 0.92)  <- router + VLAN
2. memory/2026-02-08.md  (điểm: 0.89)  <- router + VLAN (gần như trùng lặp!)
3. memory/network.md     (điểm: 0.85)  <- tài liệu tham khảo

1. memory/2026-02-10.md  (điểm: 0.92)  <- router + VLAN
2. memory/network.md     (điểm: 0.85)  <- tài liệu tham khảo (đa dạng!)
3. memory/2026-02-05.md  (điểm: 0.78)  <- DNS AdGuard (đa dạng!)

​

Suy giảm theo thời gian (tăng cường gần đây)

decayedScore = score x e^(-lambda x ageInDays)

• Ghi chú hôm nay: 100% điểm gốc
• 7 ngày trước: ~84%
• 30 ngày trước: 50%
• 90 ngày trước: 12.5%
• 180 ngày trước: ~1.6%

• MEMORY.md (file bộ nhớ gốc)
• Các file không có ngày trong memory/ (ví dụ: memory/projects.md, memory/network.md)
• Chúng chứa thông tin tham khảo bền vững nên luôn xếp hạng bình thường.

memory/2025-09-15.md  -> "Rod làm việc từ thứ Hai đến thứ Sáu, họp đứng lúc 10 giờ sáng, ghép đôi lúc 2 giờ chiều"  (148 ngày tuổi)
memory/2026-02-10.md  -> "Rod có họp đứng lúc 14:15, 1:1 với Zeb lúc 14:45"    (hôm nay)
memory/2026-02-03.md  -> "Rod bắt đầu nhóm mới, họp đứng chuyển sang 14:15"        (7 ngày tuổi)

1. memory/2025-09-15.md  (điểm: 0.91)  <- khớp ngữ nghĩa tốt nhất, nhưng cũ!
2. memory/2026-02-10.md  (điểm: 0.82)
3. memory/2026-02-03.md  (điểm: 0.80)

1. memory/2026-02-10.md  (điểm: 0.82 x 1.00 = 0.82)  <- hôm nay, không suy giảm
2. memory/2026-02-03.md  (điểm: 0.80 x 0.85 = 0.68)  <- 7 ngày, suy giảm nhẹ
3. memory/2025-09-15.md  (điểm: 0.91 x 0.03 = 0.03)  <- 148 ngày, gần như biến mất

​

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

agents: {
  defaults: {
    memorySearch: {
      query: {
        hybrid: {
          enabled: true,
          vectorWeight: 0.7,
          textWeight: 0.3,
          candidateMultiplier: 4,
          // Đa dạng: giảm kết quả trùng lặp
          mmr: {
            enabled: true,    // mặc định: false
            lambda: 0.7       // 0 = đa dạng tối đa, 1 = liên quan tối đa
          },
          // Gần đây: tăng cường ký ức mới hơn
          temporalDecay: {
            enabled: true,    // mặc định: false
            halfLifeDays: 30  // điểm giảm một nửa mỗi 30 ngày
          }
        }
      }
    }
  }
}

• Chỉ MMR — hữu ích khi bạn có nhiều ghi chú tương tự nhưng tuổi không quan trọng.
• Chỉ suy giảm theo thời gian — hữu ích khi gần đây quan trọng nhưng kết quả của bạn đã đa dạng.
• Cả hai — được khuyến nghị cho các agent có lịch sử ghi chú hàng ngày lớn, lâu dài.

​

Bộ nhớ đệm embedding

agents: {
  defaults: {
    memorySearch: {
      cache: {
        enabled: true,
        maxEntries: 50000
      }
    }
  }
}

​

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

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

• Lập chỉ mục phiên là tùy chọn (tắt mặc định).
• Cập nhật phiên được debounce và lập chỉ mục không đồng bộ khi chúng vượt qua ngưỡng delta (nỗ lực tốt nhất).
• memory_search không bao giờ chặn lập chỉ mục; kết quả có thể hơi cũ cho đến khi đồng bộ nền hoàn thành.
• Kết quả vẫn chỉ bao gồm các đoạn trích; memory_get vẫn giới hạn ở các file bộ nhớ.
• Lập chỉ mục phiên được cách ly theo agent (chỉ các bản ghi phiên của agent đó được lập chỉ mục).
• Bản ghi phiên sống trên đĩa (~/.openclaw/agents/<agentId>/sessions/*.jsonl). Bất kỳ quy trình/người dùng nào có quyền truy cập hệ thống file đều có thể đọc chúng, vì vậy hãy coi quyền truy cập đĩa là ranh giới tin cậy. Để cách ly nghiêm ngặt hơn, chạy các agent dưới các người dùng hoặc máy chủ OS riêng biệt.

agents: {
  defaults: {
    memorySearch: {
      sync: {
        sessions: {
          deltaBytes: 100000,   // ~100 KB
          deltaMessages: 50     // dòng JSONL
        }
      }
    }
  }
}

​

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

agents: {
  defaults: {
    memorySearch: {
      store: {
        vector: {
          enabled: true,
          extensionPath: "/path/to/sqlite-vec"
        }
      }
    }
  }
}

• enabled mặc định là true; khi bị vô hiệu hóa, tìm kiếm quay lại với cosine similarity trong quá trình xử lý trên các embedding đã lưu trữ.
• Nếu phần mở rộng sqlite-vec bị thiếu hoặc không tải được, OpenClaw ghi lại lỗi và tiếp tục với phương án dự phòng JS (không có bảng vector).
• extensionPath ghi đè đường dẫn sqlite-vec đi kèm (hữu ích cho các bản dựng tùy chỉnh hoặc vị trí cài đặt không chuẩn).

​

Tự động tải xuống embedding local

• Mô hình embedding local mặc định: hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf (~0.6 GB).
• Khi memorySearch.provider = "local", node-llama-cpp giải quyết modelPath; nếu GGUF bị thiếu, nó tự động tải xuống vào cache (hoặc local.modelCacheDir nếu được thiết lập), sau đó tải nó. Tải xuống tiếp tục khi thử lại.
• Yêu cầu xây dựng native: chạy pnpm approve-builds, chọn node-llama-cpp, sau đó pnpm rebuild node-llama-cpp.
• Dự phòng: nếu thiết lập local thất bại và memorySearch.fallback = "openai", chúng tôi tự động chuyển sang embedding từ xa (openai/text-embedding-3-small trừ khi được ghi đè) và ghi lại lý do.

​

Ví dụ endpoint tương thích OpenAI tùy chỉnh

agents: {
  defaults: {
    memorySearch: {
      provider: "openai",
      model: "text-embedding-3-small",
      remote: {
        baseUrl: "https://api.example.com/v1/",
        apiKey: "YOUR_REMOTE_API_KEY",
        headers: {
          "X-Organization": "org-id",
          "X-Project": "project-id"
        }
      }
    }
  }
}

• remote.* có ưu tiên hơn models.providers.openai.*.
• remote.headers hợp nhất với các header OpenAI; remote thắng trong các xung đột khóa. Bỏ qua remote.headers để sử dụng mặc định của OpenAI.