Referensi konfigurasi memori

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

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

Mengingat lintas percakapan

Konfigurasikan per agen jika hanya agen pribadi tepercaya yang boleh menggunakan pengingatan transkrip lintas percakapan:

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

Nilai tersebut mengikuti pewarisan agents.defaults.memorySearch normal dengan penggantian per agen. Jika tidak ditetapkan, nilai tersebut secara default hanya aktif jika session.dmScope global tidak ditetapkan atau "main" dan tidak ada binding yang memiliki penggantian session.dmScope. Isolasi DM apa pun yang dikonfigurasi akan menonaktifkannya secara default. true atau false yang eksplisit selalu diutamakan. Mengaktifkannya menyiratkan pengindeksan transkrip sesi dan menambahkan sessions ke sumber memori agen yang telah diresolusi. Dengan QMD, tindakan ini juga mengaktifkan ekspor sesi agen tersebut; pengaturan memory.qmd.sessions.enabled terpisah tidak diperlukan untuk mode ini.

Penyedia memori bawaan OpenClaw mendukung jalur terlindungi ini dengan backend bawaan maupun QMD. Penyedia memori alternatif dapat terus menggunakan hook pengingatan dan alat Active Memory tingkat lanjut miliknya sendiri, tetapi pengaturan ini dilewati kecuali penyedia saat ini mendukung pengingatan transkrip pribadi yang terlindungi. openclaw doctor melaporkan penyedia yang tidak didukung atau daftar Active Memory toolsAllow eksplisit yang tidak menyertakan memory_search.

Batas pengambilannya lebih sempit daripada pencarian sesi umum:

• hanya percakapan pribadi yang dikenali milik agen yang sama yang memenuhi syarat
• percakapan yang sedang dijawab dikecualikan
• grup dan kanal dikecualikan sebagai sumber dan tujuan
• jenis percakapan yang tidak diketahui ditolak secara default
• pengingatan dalam sandbox tidak dapat menggunakan otorisasi lintas percakapan khusus

Pengaturan ini tidak mengubah tools.sessions.visibility, kunci sesi, penyimpanan transkrip, perutean pengiriman, atau izin sessions_list, sessions_history, dan sessions_send. Active Memory melakukan tahap pengambilan hanya-baca yang terbatas; pengambilan yang tidak tersedia atau kehabisan waktu tidak memblokir balasan.

Pemilihan penyedia

Jika 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 menyatakan provider: "auto" diresolusi menjadi openai.

Jika provider tidak ditetapkan, provider: "auto" lama tersedia, atau provider: "none" sengaja memilih mode khusus FTS, pengingatan memori tetap dapat menggunakan pemeringkatan FTS leksikal ketika embedding tidak tersedia.

Penyedia nonlokal eksplisit ditolak secara default. 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 kustom yang kompatibel dengan OpenAI, dan penyedia tersebut tidak tersedia saat runtime, memory_search mengembalikan hasil tidak tersedia alih-alih diam-diam menggunakan pengingatan khusus FTS. Perbaiki konfigurasi penyedia/autentikasi, beralihlah ke penyedia yang dapat dijangkau, atau tetapkan provider: "none" jika Anda menginginkan pengingatan khusus FTS secara sengaja.

ID penyedia kustom

memorySearch.provider dapat mengarah ke entri models.providers.<id> kustom untuk adaptor penyedia khusus memori seperti ollama, atau untuk API model yang kompatibel dengan OpenAI seperti openai-responses / openai-completions. OpenClaw meresolusi pemilik api penyedia tersebut untuk adaptor embedding sambil mempertahankan ID penyedia kustom untuk penanganan endpoint, autentikasi, dan prefiks model. Hal ini memungkinkan penyiapan 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 /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 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 inline

Perilaku pengindeksan

Semua berada di bawah memorySearch.sync kecuali dinyatakan lain:

Konfigurasi pencarian hibrida

Semua berada di bawah memorySearch.query:

Dan di bawah memorySearch.query.hybrid:

Contoh lengkap

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

Jalur memori tambahan

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

Jalur dapat bersifat 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 sebagai pengganti memory.qmd.paths. Koleksi tambahan tersebut mengikuti bentuk { path, name, pattern? } yang sama, tetapi digabungkan per agen dan dapat mempertahankan nama bersama yang eksplisit ketika jalurnya 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 pembuatan ulang embedding untuk teks yang tidak berubah selama pengindeksan ulang atau pembaruan transkrip.

Pengindeksan batch

Tersedia untuk gemini, openai, dan voyage. Batch OpenAI biasanya paling cepat dan paling murah untuk pengisian ulang berskala besar.

remote.nonBatchConcurrency mengontrol panggilan embedding inline yang digunakan oleh penyedia lokal/yang di-host sendiri dan penyedia yang di-host ketika API batch penyedia tidak aktif. Ollama secara bawaan menggunakan 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:

Pencarian transkrip sesi biasa yang dipanggil model mematuhi tools.sessions.visibility. Visibilitas bawaan tree mengekspos sesi saat ini, sesi yang dibuat olehnya, dan sesi grup dengan agen yang sama yang dipantau melalui kesadaran grup ambien. Sesi lain yang tidak terkait memerlukan visibilitas agent (atau all hanya ketika pengingatan lintas agen juga diperlukan dan kebijakan agen-ke-agen mengizinkannya).

rememberAcrossConversations tidak memperluas pengaturan tersebut. Pengaturan ini menyediakan otorisasi terpisah yang hanya berlaku saat runtime dan terbatas pada transkrip privat dengan agen yang sama selama proses Active Memory yang dibatasi.

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 perlu mengindeks dan mencari transkrip sesi.

Untuk pengingatan gateway-ke-DM dengan 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. Tetapkan juga memory.qmd.sessions.enabled: true. Pengaturan tingkat lebih tinggi rememberAcrossConversations: true merupakan pengecualian: pengaturan ini menyiratkan ekspor sesi QMD yang diperlukan untuk agen tersebut. Ekspor tersirat tetap privat: ekspor tersebut selalu menggunakan lokasi ekspor internal bawaan (sessions.exportDir yang dikonfigurasi hanya berlaku untuk ekspor eksplisit), hanya dicari selama pengingatan lintas percakapan agen tersebut, dan memory_get biasa tidak dapat membacanya. memory.qmd.sessions.enabled: true yang eksplisit mempertahankan perilaku yang ada dan menjadikan transkrip yang diekspor bagian dari korpus memori biasa.

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 database 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 bersifat 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 pemeringkatan ulang kueri bawaan QMD.

OpenClaw mengutamakan bentuk koleksi dan kueri MCP QMD terkini, tetapi tetap mendukung rilis QMD lama dengan mencoba flag pola koleksi yang kompatibel dan nama alat MCP lama bila diperlukan. Ketika QMD menyatakan dukungan untuk beberapa filter koleksi, koleksi dengan sumber yang sama dicari menggunakan satu proses QMD; build QMD lama tetap menggunakan jalur kompatibilitas per koleksi. Sumber yang sama berarti koleksi memori persisten (file memori bawaan ditambah jalur khusus) dikelompokkan bersama, sementara koleksi transkrip sesi tetap menjadi grup terpisah agar diversifikasi sumber tetap memiliki kedua masukan.

Integrasi mcporter

Semuanya berada di bawah memory.qmd.mcporter. Merutekan pencarian QMD melalui daemon MCP mcporter yang berumur panjang, alih-alih membuat qmd untuk setiap kueri, sehingga mengurangi overhead cold-start 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 pembuatan 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/penyematan yang dikonfigurasi, proses awal menggunakan pengelola sekali jalan untuk penyegaran saat boot lalu menutupnya. Jika interval pembaruan atau penyematan 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 penyapuan 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