Referensi konfigurasi memori

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

Semua pengaturan pencarian memori berada di bawah agents.defaults.memorySearch dalam openclaw.json (atau penggantian per agen agents.list[].memorySearch), kecuali dinyatakan lain.

Pemilihan penyedia

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

Ketika provider tidak ditetapkan, provider: "auto" lama digunakan, atau provider: "none" sengaja memilih mode FTS saja, pemanggilan kembali memori masih dapat menggunakan pemeringkatan FTS leksikal ketika embedding tidak tersedia.

Penyedia nonlokal yang ditetapkan secara eksplisit akan gagal secara tertutup. Jika Anda menetapkan memorySearch.provider ke penyedia konkret yang didukung layanan jarak jauh seperti Bedrock, DeepInfra, Gemini, GitHub Copilot, LM Studio, Mistral, Ollama, OpenAI, Voyage, atau penyedia khusus yang kompatibel dengan OpenAI, dan penyedia tersebut tidak tersedia saat runtime, memory_search mengembalikan hasil tidak tersedia alih-alih diam-diam menggunakan pemanggilan kembali FTS saja. Perbaiki konfigurasi penyedia/autentikasi, beralihlah ke penyedia yang dapat dijangkau, atau tetapkan provider: "none" jika Anda sengaja menginginkan pemanggilan kembali FTS saja.

ID penyedia khusus

memorySearch.provider dapat mengarah ke entri khusus models.providers.<id> untuk adaptor penyedia khusus memori seperti ollama, atau untuk API model yang kompatibel dengan OpenAI seperti openai-responses / openai-completions. OpenClaw meresolusikan pemilik api penyedia tersebut untuk adaptor embedding sambil mempertahankan ID penyedia khusus untuk penanganan endpoint, autentikasi, dan prefiks model. Hal ini memungkinkan konfigurasi 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", name: "Qwen3 Embedding 0.6B" }],      },    },  },  agents: {    defaults: {      memorySearch: {        provider: "ollama-5080",        model: "qwen3-embedding:0.6b",      },    },  },}

Resolusi kunci API

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

Konfigurasi endpoint jarak jauh

Gunakan provider: "openai-compatible" untuk server generik /v1/embeddings yang kompatibel dengan OpenAI dan tidak boleh mewarisi kredensial obrolan 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 penyedia

{  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

Batas waktu embedding sebaris

Perilaku pengindeksan

Semua berada di bawah memorySearch.sync, kecuali jika disebutkan lain:

Konfigurasi pencarian hibrida

Semuanya berada di bawah memorySearch.query:

Dan di bawah memorySearch.query.hybrid:

Contoh lengkap

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

Jalur memori tambahan

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

Jalur dapat berupa jalur absolut atau relatif terhadap ruang kerja. Direktori dipindai secara rekursif untuk mencari berkas .md. Penanganan symlink bergantung pada backend yang aktif: mesin bawaan melewati symlink, sedangkan 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 tambahan tersebut mengikuti bentuk { path, name, pattern? } yang sama, tetapi digabungkan per agen dan dapat mempertahankan nama bersama yang ditetapkan secara eksplisit saat jalur mengarah ke luar ruang kerja saat ini. Jika jalur terselesaikan yang sama muncul di memory.qmd.paths dan memorySearch.qmd.extraCollections, QMD mempertahankan entri pertama dan melewati duplikatnya.

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. Biarkan maxEntries tidak diatur untuk cache tanpa batas; atur nilainya ketika pertumbuhan penggunaan disk lebih penting daripada kecepatan puncak pengindeksan ulang. Jika diatur, entri terlama (berdasarkan waktu pembaruan terakhir) akan dipangkas terlebih dahulu setelah cache melampaui batas.

Pengindeksan batch

Tersedia untuk gemini, openai, dan voyage. Batch OpenAI biasanya paling cepat dan paling murah untuk pengisian kembali data dalam jumlah besar.

remote.nonBatchConcurrency mengontrol panggilan embedding inline yang digunakan oleh penyedia lokal/yang dihosting sendiri serta penyedia yang dihosting ketika API batch penyedia tidak aktif. Ollama menggunakan bawaan 1 untuk pengindeksan non-batch agar tidak membebani host lokal yang lebih kecil secara berlebihan; tetapkan nilai yang lebih tinggi pada mesin yang lebih besar.

Ini terpisah dari sync.embeddingBatchTimeoutSeconds, yang mengontrol batas waktu 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 bawaan tree hanya mengekspos sesi saat ini dan sesi yang dibuatnya. Untuk mengingat sesi lain dari agen yang sama yang didistribusikan oleh Gateway dari sesi berbeda, seperti DM, perluas visibilitas secara sengaja ke agent (atau all hanya ketika pengingatan lintas agen juga diperlukan dan kebijakan antaragen mengizinkannya).

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

Untuk pengingatan dari Gateway ke DM oleh 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"] tidak mengekspor transkrip ke QMD dengan sendirinya. Atur juga memory.qmd.sessions.enabled: true.

Akselerasi vektor SQLite (sqlite-vec)

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

Penyimpanan indeks

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

Konfigurasi backend QMD

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

searchMode: "search" hanya menggunakan leksikal/BM25. OpenClaw tidak menjalankan pemeriksaan kesiapan vektor semantik atau pemeliharaan penyematan QMD untuk mode tersebut, termasuk selama memory status --deep; vsearch dan query tetap memerlukan kesiapan vektor dan penyematan 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 berbasis mcporter, OpenClaw meneruskan rerank: false ke alat kueri terpadu QMD. Biarkan tidak diatur untuk menggunakan perilaku pemeringkatan ulang kueri bawaan QMD.

OpenClaw mengutamakan bentuk koleksi dan kueri MCP QMD terbaru, tetapi tetap mendukung rilis QMD lama dengan mencoba tanda 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; versi QMD lama tetap menggunakan jalur kompatibilitas per koleksi. Sumber yang sama berarti koleksi memori persisten (berkas memori bawaan beserta jalur khusus) dikelompokkan bersama, sedangkan koleksi transkrip sesi tetap menjadi kelompok terpisah agar diversifikasi sumber tetap memiliki kedua masukan.

Integrasi mcporter

Semuanya berada di bawah memory.qmd.mcporter. Mengarahkan pencarian QMD melalui daemon MCP mcporter berumur panjang alih-alih menjalankan qmd untuk setiap kueri, sehingga mengurangi beban awal dingin untuk model yang lebih besar.

Memerlukan mcporter yang terpasang dan tersedia di PATH, serta server mcporter terkonfigurasi yang menjalankan qmd mcp. Biarkan dinonaktifkan untuk penyiapan lokal yang lebih sederhana ketika biaya menjalankan proses per kueri masih dapat diterima.

{  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, proses awal menggunakan pengelola sekali jalan untuk penyegaran saat boot lalu menutupnya. Jika interval pembaruan atau embed dikonfigurasi, proses awal membuka pengelola QMD berumur panjang agar dapat mengelola pemantau dan pewaktu interval; update.onBoot: false hanya melewati penyegaran langsung saat boot.

Contoh QMD lengkap

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

Dreaming berjalan sebagai satu penyisiran terjadwal dan menggunakan fase internal ringan/dalam/REM sebagai detail implementasi.

Untuk perilaku konseptual dan perintah garis miring, 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