Referensi konfigurasi memori

Halaman ini mencantumkan setiap kenop konfigurasi untuk pencarian memori OpenClaw. Untuk ikhtisar konseptual, lihat:

Semua pengaturan pencarian memori berada di bawah agents.defaults.memorySearch dalam openclaw.json, kecuali dinyatakan lain.

Pemilihan provider

Ketika provider tidak diatur, OpenClaw menggunakan embedding OpenAI. Atur provider secara eksplisit untuk menggunakan Gemini, Voyage, Mistral, DeepInfra, Bedrock, GitHub Copilot, Ollama, model GGUF lokal, atau endpoint /v1/embeddings yang kompatibel dengan OpenAI. Konfigurasi lama yang masih menyatakan provider: "auto" diselesaikan menjadi openai.

Ketika provider tidak ditetapkan, provider: "auto" lama ada, atau provider: "none" sengaja memilih mode hanya FTS, recall memori masih dapat menggunakan peringkat FTS leksikal saat embedding tidak tersedia.

Provider non-lokal eksplisit gagal secara tertutup. Jika Anda mengatur memorySearch.provider ke provider konkret yang didukung jarak jauh seperti OpenAI, Gemini, Voyage, Mistral, Bedrock, GitHub Copilot, DeepInfra, Ollama, LM Studio, atau provider kustom yang kompatibel dengan OpenAI, dan provider tersebut tidak tersedia saat runtime, memory_search mengembalikan hasil tidak tersedia alih-alih diam-diam menggunakan recall hanya FTS. Perbaiki konfigurasi provider/auth, beralih ke provider yang dapat dijangkau, atau atur provider: "none" jika Anda menginginkan recall hanya FTS secara sengaja.

ID provider kustom

memorySearch.provider dapat menunjuk ke entri models.providers.<id> kustom untuk adaptor provider khusus memori seperti ollama, atau untuk API model kompatibel OpenAI seperti openai-responses / openai-completions. OpenClaw menyelesaikan pemilik api provider tersebut untuk adaptor embedding sambil mempertahankan ID provider kustom untuk penanganan endpoint, auth, dan prefiks model. Ini memungkinkan setup multi-GPU atau multi-host mendedikasikan embedding memori ke endpoint lokal tertentu:

{  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",      },    },  },}

Resolusi kunci API

Embedding jarak jauh memerlukan kunci API. Bedrock menggunakan rantai kredensial default AWS SDK sebagai gantinya (peran instance, SSO, kunci akses).

Konfigurasi endpoint jarak jauh

Gunakan provider: "openai-compatible" untuk server /v1/embeddings generik yang kompatibel dengan OpenAI dan tidak boleh mewarisi kredensial chat OpenAI global.

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

Konfigurasi khusus provider

{  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

Timeout embedding inline

Konfigurasi pencarian hibrida

Semuanya berada di bawah memorySearch.query.hybrid:

Contoh lengkap

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

Jalur memori tambahan

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

Jalur dapat berupa absolut atau relatif terhadap workspace. Direktori dipindai secara rekursif untuk file .md. Penanganan symlink bergantung pada backend aktif: mesin bawaan mengabaikan symlink, sementara QMD mengikuti perilaku pemindai QMD yang mendasarinya.

Untuk pencarian transkrip lintas agen dengan cakupan agen, gunakan agents.list[].memorySearch.qmd.extraCollections alih-alih memory.qmd.paths. Koleksi ekstra tersebut mengikuti bentuk { path, name, pattern? } yang sama, tetapi digabungkan per agen dan dapat mempertahankan nama bersama eksplisit ketika jalur mengarah ke luar workspace saat ini. Jika jalur terselesaikan yang sama muncul di memory.qmd.paths dan memorySearch.qmd.extraCollections, QMD mempertahankan entri pertama dan melewati duplikat.

Memori multimodal (Gemini)

Indeks gambar dan audio bersama Markdown menggunakan Gemini Embedding 2:

Format yang didukung: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (gambar); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (audio).

Cache embedding

Mencegah embedding ulang teks yang tidak berubah selama pengindeksan ulang atau pembaruan transkrip.

Pengindeksan batch

Tersedia untuk openai, gemini, dan voyage. Batch OpenAI biasanya paling cepat dan paling murah untuk backfill besar.

remote.nonBatchConcurrency mengontrol panggilan embedding inline yang digunakan oleh penyedia lokal/self-hosted dan penyedia hosted ketika API batch penyedia tidak aktif. Ollama default ke 1 untuk pengindeksan non-batch agar tidak membebani host lokal yang lebih kecil; tetapkan nilai lebih tinggi pada mesin yang lebih besar.

Ini terpisah dari sync.embeddingBatchTimeoutSeconds, yang mengontrol timeout untuk panggilan embedding inline.

Pencarian memori sesi (eksperimental)

Indeks transkrip sesi dan tampilkan melalui memory_search:

Hasil transkrip sesi juga mematuhi tools.sessions.visibility. Visibilitas default tree hanya mengekspos sesi saat ini dan sesi yang dibuat olehnya. Untuk memanggil kembali sesi tidak terkait yang dikirim Gateway untuk agen yang sama dari sesi berbeda, seperti DM, perluas visibilitas secara sengaja ke agent (atau all hanya ketika pemanggilan lintas agen juga diperlukan dan kebijakan agen-ke-agen mengizinkannya).

Contoh di bawah menempatkan pengaturan ini di bawah agents.defaults. Anda juga dapat menerapkan pengaturan memorySearch yang setara dalam override per agen ketika hanya satu agen yang harus mengindeks dan mencari transkrip sesi.

Untuk pemanggilan kembali dari Gateway ke DM pada agen yang sama:

{  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" },  },}

Saat menggunakan QMD, agents.defaults.memorySearch.experimental.sessionMemory dan sources: ["sessions"] saja tidak mengekspor transkrip ke QMD. Tetapkan juga memory.qmd.sessions.enabled: true.

Akselerasi vektor SQLite (sqlite-vec)

Saat sqlite-vec tidak tersedia, OpenClaw secara otomatis beralih ke kemiripan kosinus dalam proses.

Penyimpanan indeks

Indeks memori bawaan berada di basis data SQLite OpenClaw milik setiap agen di agents/<agentId>/agent/openclaw-agent.sqlite.

Konfigurasi backend QMD

Tetapkan memory.backend = "qmd" untuk mengaktifkannya. Semua pengaturan QMD berada di bawah memory.qmd:

searchMode: "search" hanya leksikal/BM25. OpenClaw tidak menjalankan pemeriksaan kesiapan vektor semantik atau pemeliharaan embedding QMD untuk mode tersebut, termasuk selama memory status --deep; vsearch dan query tetap memerlukan kesiapan vektor dan embedding QMD.

rerank: false hanya mengubah mode query QMD dan memerlukan QMD 2.1 atau yang lebih baru. Dalam mode CLI langsung, OpenClaw meneruskan --no-rerank; dalam mode MCP yang didukung mcporter, OpenClaw meneruskan rerank: false ke alat kueri terpadu QMD. Biarkan tidak ditetapkan untuk menggunakan perilaku reranking kueri default QMD.

OpenClaw memprioritaskan bentuk koleksi QMD dan kueri MCP saat ini, tetapi tetap membuat rilis QMD lama berfungsi dengan mencoba flag pola koleksi yang kompatibel dan nama alat MCP lama bila diperlukan. Ketika QMD menyatakan dukungan untuk beberapa filter koleksi, koleksi dari sumber yang sama dicari dengan satu proses QMD; build QMD lama tetap menggunakan jalur kompatibilitas per koleksi. Sumber yang sama berarti koleksi memori tahan lama dikelompokkan bersama, sementara koleksi transkrip sesi tetap menjadi grup terpisah sehingga diversifikasi sumber tetap memiliki kedua input.

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

Saat inisialisasi QMD ketika Gateway dimulai diaktifkan, OpenClaw memulai QMD hanya untuk agen yang memenuhi syarat. Jika update.onBoot bernilai true dan tidak ada pemeliharaan interval/embed yang dikonfigurasi, startup menggunakan manajer sekali pakai untuk penyegaran boot dan menutupnya. Jika interval pembaruan atau embed dikonfigurasi, startup membuka manajer QMD berumur panjang agar dapat memiliki watcher dan timer interval; update.onBoot: false hanya melewati penyegaran boot langsung.

Contoh QMD lengkap

{  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 dikonfigurasi di bawah plugins.entries.memory-core.config.dreaming, bukan di bawah agents.defaults.memorySearch.

Dreaming berjalan sebagai satu sweep terjadwal dan menggunakan fase internal light/deep/REM sebagai detail implementasi.

Untuk perilaku konseptual dan perintah slash, lihat Dreaming.

Pengaturan pengguna

Contoh

{  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",          },        },      },    },  },}

Terkait

• Referensi konfigurasi
• Ikhtisar memori
• Pencarian memori