Bellek yapılandırması referansı

Bu sayfa, OpenClaw bellek araması için tüm yapılandırma seçeneklerini listeler. Kavramsal genel bakışlar için bkz.:

Aksi belirtilmedikçe tüm bellek araması ayarları, openclaw.json içindeki agents.defaults.memorySearch altında (veya aracı başına bir agents.list[].memorySearch geçersiz kılması olarak) bulunur.

Sağlayıcı seçimi

provider ayarlanmadığında OpenClaw, OpenAI gömmelerini kullanır. Bedrock, DeepInfra, Gemini, GitHub Copilot, Mistral, Ollama, Voyage, yerel bir GGUF modeli veya OpenAI uyumlu bir /v1/embeddings uç noktası kullanmak için provider değerini açıkça ayarlayın. Hâlâ provider: "auto" belirten eski yapılandırmalar openai olarak çözümlenir.

provider ayarlanmamışsa, eski provider: "auto" mevcutsa veya provider: "none" kasıtlı olarak yalnızca FTS modunu seçiyorsa gömmeler kullanılamadığında bellekten geri çağırma yine de sözcüksel FTS sıralamasını kullanabilir.

Açıkça belirtilen yerel olmayan sağlayıcılar kapalı şekilde başarısız olur. memorySearch.provider değerini Bedrock, DeepInfra, Gemini, GitHub Copilot, LM Studio, Mistral, Ollama, OpenAI, Voyage veya OpenAI uyumlu özel bir sağlayıcı gibi uzak bir arka uca dayanan somut bir sağlayıcıya ayarlarsanız ve bu sağlayıcı çalışma zamanında kullanılamazsa memory_search, sessizce yalnızca FTS geri çağırmasını kullanmak yerine kullanılamıyor sonucu döndürür. Sağlayıcı/kimlik doğrulama yapılandırmasını düzeltin, erişilebilir bir sağlayıcıya geçin veya yalnızca FTS geri çağırmasını bilinçli olarak kullanmak istiyorsanız provider: "none" değerini ayarlayın.

Özel sağlayıcı kimlikleri

memorySearch.provider, ollama gibi belleğe özgü sağlayıcı bağdaştırıcıları veya openai-responses / openai-completions gibi OpenAI uyumlu model API'leri için özel bir models.providers.<id> girdisine işaret edebilir. OpenClaw; uç nokta, kimlik doğrulama ve model öneki işlemleri için özel sağlayıcı kimliğini korurken gömme bağdaştırıcısı için bu sağlayıcının api sahibini çözümler. Bu, çoklu GPU veya çoklu ana makine kurulumlarının bellek gömmeleri için belirli bir yerel uç noktayı tahsis etmesini sağlar:

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

API anahtarı çözümleme

Uzak gömmeler bir API anahtarı gerektirir. Bedrock bunun yerine AWS SDK varsayılan kimlik bilgisi zincirini kullanır (örnek rolleri, SSO, erişim anahtarları veya bir Bedrock API anahtarı).

Uzak uç nokta yapılandırması

Genel OpenAI sohbet kimlik bilgilerini devralmaması gereken, OpenAI uyumlu genel bir /v1/embeddings sunucusu için provider: "openai-compatible" kullanın.

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

Sağlayıcıya özgü yapılandırma

{  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

Satır içi gömme zaman aşımı

İndeksleme davranışı

Aksi belirtilmedikçe tümü memorySearch.sync altındadır:

Hibrit arama yapılandırması

Tümü memorySearch.query altındadır:

Ayrıca memorySearch.query.hybrid altında:

Tam örnek

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

Ek bellek yolları

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

Yollar mutlak veya çalışma alanına göreli olabilir. Dizinler .md dosyaları için özyinelemeli olarak taranır. Sembolik bağlantıların işlenmesi etkin arka uca bağlıdır: yerleşik altyapı sembolik bağlantıları atlarken QMD, temel QMD tarayıcısının davranışını izler.

Ajan kapsamlı, ajanlar arası transkript araması için memory.qmd.paths yerine agents.list[].memorySearch.qmd.extraCollections kullanın. Bu ek koleksiyonlar aynı { path, name, pattern? } biçimini izler ancak ajan başına birleştirilir ve yol geçerli çalışma alanının dışını gösterdiğinde açıkça belirtilmiş paylaşılan adları koruyabilir. Çözümlenen aynı yol hem memory.qmd.paths hem de memorySearch.qmd.extraCollections içinde görünürse QMD ilk girdiyi tutar ve yinelenen girdiyi atlar.

Çok modlu bellek (Gemini)

Gemini Embedding 2 kullanarak Markdown ile birlikte görüntüleri ve sesleri indeksleyin:

Desteklenen biçimler: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (görüntüler); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (ses).

Gömme önbelleği

Yeniden indeksleme veya transkript güncellemeleri sırasında değişmemiş metnin yeniden gömülmesini önler. Sınırsız bir önbellek için maxEntries değerini ayarlamadan bırakın; disk büyümesi, en yüksek yeniden indeksleme hızından daha önemliyse bu değeri ayarlayın. Ayarlandığında, önbellek sınırı aştığı anda en eski girdiler (son güncellenme zamanına göre) önce budanır.

Toplu indeksleme

gemini, openai ve voyage için kullanılabilir. OpenAI toplu işlemi, büyük geriye dönük doldurmalar için genellikle en hızlı ve en ucuz seçenektir.

remote.nonBatchConcurrency, yerel/kendi kendine barındırılan sağlayıcıların ve sağlayıcı toplu işlem API'leri etkin olmadığında barındırılan sağlayıcıların kullandığı satır içi gömme çağrılarını denetler. Daha küçük yerel ana makineleri aşırı yüklememek için Ollama, toplu olmayan indekslemede varsayılan olarak 1 kullanır; daha büyük makinelerde daha yüksek bir değer ayarlayın.

Bu, satır içi gömme çağrılarının zaman aşımını denetleyen sync.embeddingBatchTimeoutSeconds ayarından ayrıdır.

Oturum belleği araması (deneysel)

Oturum transkriptlerini indeksleyin ve memory_search aracılığıyla sunun:

Oturum transkripti eşleşmeleri ayrıca tools.sessions.visibility ayarına uyar. Varsayılan tree görünürlüğü yalnızca mevcut oturumu ve onun oluşturduğu oturumları gösterir. Farklı bir oturumdan, örneğin bir DM'den, aynı aracıya ait ilgisiz ve gateway tarafından gönderilmiş bir oturumu hatırlamak için görünürlüğü bilinçli olarak agent değerine genişletin (veya yalnızca aracılar arası hatırlama da gerekliyken ve aracılar arası politika buna izin veriyorsa all değerine).

Aşağıdaki örnekler bu ayarları agents.defaults altına yerleştirir. Yalnızca bir aracının oturum transkriptlerini indeksleyip araması gerekiyorsa, aracı başına geçersiz kılmada eşdeğer memorySearch ayarlarını da uygulayabilirsiniz.

Aynı aracıda gateway'den DM'e hatırlama için:

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

QMD kullanılırken agents.defaults.memorySearch.experimental.sessionMemory ve sources: ["sessions"] tek başlarına transkriptleri QMD'ye dışa aktarmaz. Ayrıca memory.qmd.sessions.enabled: true ayarını da yapın.

SQLite vektör hızlandırması (sqlite-vec)

sqlite-vec kullanılamadığında OpenClaw otomatik olarak işlem içi kosinüs benzerliğine geri döner.

İndeks depolama

Yerleşik bellek indeksleri, her aracının OpenClaw SQLite veritabanında agents/<agentId>/agent/openclaw-agent.sqlite konumunda bulunur.

QMD arka uç yapılandırması

Etkinleştirmek için memory.backend = "qmd" ayarını yapın. Tüm QMD ayarları memory.qmd altında bulunur:

searchMode: "search" yalnızca sözcüksel/BM25'tir. OpenClaw, memory status --deep sırasında da dahil olmak üzere bu mod için anlamsal vektör hazır olma yoklamalarını veya QMD gömme bakımını çalıştırmaz; vsearch ve query, QMD vektör hazırlığını ve gömmeleri gerektirmeye devam eder.

rerank: false yalnızca QMD query modunu değiştirir ve QMD 2.1 veya daha yeni bir sürüm gerektirir. Doğrudan CLI modunda OpenClaw, --no-rerank iletir; mcporter destekli MCP modunda ise QMD'nin birleşik sorgu aracına rerank: false iletir. QMD'nin varsayılan sorgu yeniden sıralama davranışını kullanmak için ayarlamadan bırakın.

OpenClaw, güncel QMD koleksiyonu ve MCP sorgu biçimlerini tercih eder ancak gerektiğinde uyumlu koleksiyon kalıbı bayraklarını ve eski MCP araç adlarını deneyerek eski QMD sürümlerinin çalışmasını sürdürür. QMD birden fazla koleksiyon filtresi desteği sunduğunda, aynı kaynaktaki koleksiyonlar tek bir QMD işlemiyle aranır; eski QMD derlemeleri koleksiyon başına uyumluluk yolunu korur. Aynı kaynak, kalıcı bellek koleksiyonlarının (varsayılan bellek dosyaları ile özel yollar) birlikte gruplandırılması anlamına gelir; oturum transkripti koleksiyonları ise kaynak çeşitlendirmesinin her iki girdiyi de koruması için ayrı bir grup olarak kalır.

mcporter entegrasyonu

Tümü memory.qmd.mcporter altında bulunur. QMD aramalarını sorgu başına qmd oluşturmak yerine uzun ömürlü bir mcporter MCP daemon'ı üzerinden yönlendirerek daha büyük modellerde soğuk başlatma yükünü azaltır.

mcporter öğesinin kurulu ve PATH üzerinde olmasını, ayrıca qmd mcp çalıştıran yapılandırılmış bir mcporter sunucusunu gerektirir. Sorgu başına işlem oluşturma maliyetinin kabul edilebilir olduğu daha basit yerel kurulumlarda devre dışı bırakın.

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

Gateway başlangıcı QMD ilklendirmesi etkinleştirildiğinde OpenClaw, QMD'yi yalnızca uygun agentler için başlatır. update.onBoot true ise ve hiçbir aralık/gömme bakımı yapılandırılmamışsa başlangıç, açılış yenilemesi için tek seferlik bir yönetici kullanır ve ardından yöneticiyi kapatır. Bir güncelleme veya gömme aralığı yapılandırılmışsa başlangıç, izleyiciyi ve aralık zamanlayıcılarını yönetebilmesi için uzun ömürlü QMD yöneticisini açar; update.onBoot: false yalnızca anında açılış yenilemesini atlar.

Tam QMD örneği

{  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, agents.defaults.memorySearch altında değil, plugins.entries.memory-core.config.dreaming altında yapılandırılır.

Dreaming, zamanlanmış tek bir tarama olarak çalışır ve dahili hafif/derin/REM aşamalarını uygulama ayrıntısı olarak kullanır.

Kavramsal davranış ve eğik çizgi komutları için Dreaming sayfasına bakın.

Kullanıcı ayarları

Örnek

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

İlgili

• Yapılandırma referansı
• Belleğe genel bakış
• Bellek araması