Ana içeriğe atla

Bellek yapılandırma başvurusu

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çinde agents.defaults.memorySearch altında bulunur. Etkin bellek özellik anahtarını ve alt aracı yapılandırmasını arıyorsanız, bunlar memorySearch yerine plugins.entries.active-memory altında bulunur. Etkin bellek iki kapılı bir model kullanır:
  1. eklentinin etkin olması ve geçerli aracı kimliğini hedeflemesi gerekir
  2. isteğin uygun bir etkileşimli kalıcı sohbet oturumu olması gerekir
Etkinleştirme modeli, eklentiye ait yapılandırma, döküm kalıcılığı ve güvenli dağıtım deseni için Etkin Bellek bölümüne bakın.

Sağlayıcı seçimi

AnahtarTürVarsayılanAçıklama
providerstringotomatik algılanırGömme bağdaştırıcısı kimliği: openai, gemini, voyage, mistral, bedrock, ollama, local
modelstringsağlayıcı varsayılanıGömme modeli adı
fallbackstring"none"Birincil başarısız olduğunda kullanılacak yedek bağdaştırıcı kimliği
enabledbooleantrueBellek aramasını etkinleştirir veya devre dışı bırakır

Otomatik algılama sırası

provider ayarlanmamışsa OpenClaw kullanılabilir ilk seçeneği seçer:
  1. localmemorySearch.local.modelPath yapılandırılmışsa ve dosya mevcutsa.
  2. openai — bir OpenAI anahtarı çözümlenebiliyorsa.
  3. gemini — bir Gemini anahtarı çözümlenebiliyorsa.
  4. voyage — bir Voyage anahtarı çözümlenebiliyorsa.
  5. mistral — bir Mistral anahtarı çözümlenebiliyorsa.
  6. bedrock — AWS SDK kimlik bilgisi zinciri çözümleniyorsa (instance role, access keys, profile, SSO, web identity veya shared config).
ollama desteklenir ancak otomatik algılanmaz (açıkça ayarlayın).

API anahtarı çözümleme

Uzak gömmeler bir API anahtarı gerektirir. Bunun yerine Bedrock, AWS SDK varsayılan kimlik bilgisi zincirini kullanır (instance role, SSO, access keys).
SağlayıcıOrtam değişkeniYapılandırma anahtarı
OpenAIOPENAI_API_KEYmodels.providers.openai.apiKey
GeminiGEMINI_API_KEYmodels.providers.google.apiKey
VoyageVOYAGE_API_KEYmodels.providers.voyage.apiKey
MistralMISTRAL_API_KEYmodels.providers.mistral.apiKey
BedrockAWS kimlik bilgisi zinciriAPI anahtarı gerekmez
OllamaOLLAMA_API_KEY (yer tutucu)
Codex OAuth yalnızca chat/completions işlemlerini kapsar ve gömme isteklerini karşılamaz.

Uzak uç nokta yapılandırması

Özel OpenAI uyumlu uç noktalar veya sağlayıcı varsayılanlarını geçersiz kılmak için:
AnahtarTürAçıklama
remote.baseUrlstringÖzel API temel URL’si
remote.apiKeystringAPI anahtarını geçersiz kılar
remote.headersobjectEk HTTP üstbilgileri (sağlayıcı varsayılanlarıyla birleştirilir)
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}

Gemini’ye özgü yapılandırma

AnahtarTürVarsayılanAçıklama
modelstringgemini-embedding-001Ayrıca gemini-embedding-2-preview desteklenir
outputDimensionalitynumber3072Embedding 2 için: 768, 1536 veya 3072
model veya outputDimensionality değiştirilirse otomatik olarak tam yeniden dizinleme tetiklenir.

Bedrock gömme yapılandırması

Bedrock, AWS SDK varsayılan kimlik bilgisi zincirini kullanır — API anahtarı gerekmez. OpenClaw, Bedrock etkin bir instance role ile EC2 üzerinde çalışıyorsa sağlayıcıyı ve modeli ayarlamanız yeterlidir:
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0",
      },
    },
  },
}
AnahtarTürVarsayılanAçıklama
modelstringamazon.titan-embed-text-v2:0Herhangi bir Bedrock gömme modeli kimliği
outputDimensionalitynumbermodel varsayılanıTitan V2 için: 256, 512 veya 1024

Desteklenen modeller

Aşağıdaki modeller desteklenir (aile algılama ve boyut varsayılanlarıyla birlikte):
Model kimliğiSağlayıcıVarsayılan BoyutYapılandırılabilir Boyutlar
amazon.titan-embed-text-v2:0Amazon1024256, 512, 1024
amazon.titan-embed-text-v1Amazon1536
amazon.titan-embed-g1-text-02Amazon1536
amazon.titan-embed-image-v1Amazon1024
amazon.nova-2-multimodal-embeddings-v1:0Amazon1024256, 384, 1024, 3072
cohere.embed-english-v3Cohere1024
cohere.embed-multilingual-v3Cohere1024
cohere.embed-v4:0Cohere1536256-1536
twelvelabs.marengo-embed-3-0-v1:0TwelveLabs512
twelvelabs.marengo-embed-2-7-v1:0TwelveLabs1024
Aktarım hızı sonekli varyantlar (ör. amazon.titan-embed-text-v1:2:8k) temel modelin yapılandırmasını devralır.

Kimlik doğrulama

Bedrock kimlik doğrulaması, standart AWS SDK kimlik bilgisi çözümleme sırasını kullanır:
  1. Ortam değişkenleri (AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
  2. SSO belirteç önbelleği
  3. Web kimliği belirteci kimlik bilgileri
  4. Paylaşılan kimlik bilgisi ve yapılandırma dosyaları
  5. ECS veya EC2 meta veri kimlik bilgileri
Bölge; AWS_REGION, AWS_DEFAULT_REGION, amazon-bedrock sağlayıcısının baseUrl değeri üzerinden çözülür veya varsayılan olarak us-east-1 kullanılır.

IAM izinleri

IAM rolü veya kullanıcısının şuna ihtiyacı vardır:
{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "*"
}
En az ayrıcalık için InvokeModel iznini belirli modele daraltın:
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0

Yerel gömme yapılandırması

AnahtarTürVarsayılanAçıklama
local.modelPathstringotomatik indirilirGGUF model dosyasının yolu
local.modelCacheDirstringnode-llama-cpp varsayılanıİndirilen modeller için önbellek dizini
Varsayılan model: embeddinggemma-300m-qat-Q8_0.gguf (~0.6 GB, otomatik indirilir). Yerel derleme gerektirir: pnpm approve-builds ardından pnpm rebuild node-llama-cpp.

Hibrit arama yapılandırması

Tamamı memorySearch.query.hybrid altında bulunur:
AnahtarTürVarsayılanAçıklama
enabledbooleantrueHibrit BM25 + vektör aramasını etkinleştirir
vectorWeightnumber0.7Vektör puanları için ağırlık (0-1)
textWeightnumber0.3BM25 puanları için ağırlık (0-1)
candidateMultipliernumber4Aday havuzu boyutu çarpanı

MMR (çeşitlilik)

AnahtarTürVarsayılanAçıklama
mmr.enabledbooleanfalseMMR yeniden sıralamayı etkinleştirir
mmr.lambdanumber0.70 = en yüksek çeşitlilik, 1 = en yüksek ilgi

Zamansal azalma (güncellik)

AnahtarTürVarsayılanAçıklama
temporalDecay.enabledbooleanfalseGüncellik artırmasını etkinleştirir
temporalDecay.halfLifeDaysnumber30Puan her N günde yarıya iner
Her zaman geçerli dosyalar (MEMORY.md, memory/ içindeki tarih içermeyen dosyalar) hiçbir zaman azaltılmaz.

Tam örnek

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

Ek bellek yolları

AnahtarTürAçıklama
extraPathsstring[]Dizinlenecek ek dizinler veya dosyalar
{
  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ı işleme, etkin arka uca bağlıdır: yerleşik motor sembolik bağlantıları yok sayarken, QMD alttaki QMD tarayıcı davranışını izler. Aracı kapsamlı çapraz aracı döküm 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 aracı başına birleştirilir ve yol geçerli çalışma alanının dışına işaret ettiğinde açık paylaşılan adları koruyabilir. Aynı çözümlenmiş yol hem memory.qmd.paths hem de memorySearch.qmd.extraCollections içinde görünürse, QMD ilk girişi tutar ve yineleneni atlar.

Çok kipli bellek (Gemini)

Gemini Embedding 2 kullanarak görselleri ve sesleri Markdown ile birlikte dizinleyin:
AnahtarTürVarsayılanAçıklama
multimodal.enabledbooleanfalseÇok kipli dizinlemeyi etkinleştirir
multimodal.modalitiesstring[]["image"], ["audio"] veya ["all"]
multimodal.maxFileBytesnumber10000000Dizinleme için en büyük dosya boyutu
Yalnızca extraPaths içindeki dosyalara uygulanır. Varsayılan bellek kökleri yalnızca Markdown olarak kalır. gemini-embedding-2-preview gerektirir. fallback değeri "none" olmalıdır. Desteklenen biçimler: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (görseller); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (ses).

Gömme önbelleği

AnahtarTürVarsayılanAçıklama
cache.enabledbooleanfalseParça gömmelerini SQLite içinde önbelleğe alır
cache.maxEntriesnumber50000En fazla önbelleğe alınan gömme sayısı
Yeniden dizinleme veya döküm güncellemeleri sırasında değişmemiş metnin yeniden gömülmesini önler.

Toplu dizinleme

AnahtarTürVarsayılanAçıklama
remote.batch.enabledbooleanfalseToplu gömme API’sini etkinleştirir
remote.batch.concurrencynumber2Paralel toplu işler
remote.batch.waitbooleantrueToplu işin tamamlanmasını bekler
remote.batch.pollIntervalMsnumberYoklama aralığı
remote.batch.timeoutMinutesnumberToplu iş zaman aşımı
openai, gemini ve voyage için kullanılabilir. OpenAI toplu işleme, büyük geri doldurmalar için genellikle en hızlı ve en ucuz seçenektir.

Oturum belleği araması (deneysel)

Oturum dökümlerini dizinleyin ve bunları memory_search üzerinden gösterin:
AnahtarTürVarsayılanAçıklama
experimental.sessionMemorybooleanfalseOturum dizinlemeyi etkinleştirir
sourcesstring[]["memory"]Dökümleri dahil etmek için "sessions" ekleyin
sync.sessions.deltaBytesnumber100000Yeniden dizinleme için bayt eşiği
sync.sessions.deltaMessagesnumber50Yeniden dizinleme için ileti eşiği
Oturum dizinleme isteğe bağlıdır ve eşzamansız çalışır. Sonuçlar biraz eski olabilir. Oturum günlükleri diskte bulunduğundan, dosya sistemi erişimini güven sınırı olarak değerlendirin.

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

AnahtarTürVarsayılanAçıklama
store.vector.enabledbooleantrueVektör sorguları için sqlite-vec kullanır
store.vector.extensionPathstringbundledsqlite-vec yolunu geçersiz kılar
sqlite-vec kullanılamadığında OpenClaw otomatik olarak işlem içi kosinüs benzerliğine geri döner.

Dizin depolama

AnahtarTürVarsayılanAçıklama
store.pathstring~/.openclaw/memory/{agentId}.sqliteDizin konumu ({agentId} belirteçini destekler)
store.fts.tokenizerstringunicode61FTS5 tokenleştiricisi (unicode61 veya trigram)

QMD arka uç yapılandırması

Etkinleştirmek için memory.backend = "qmd" ayarlayın. Tüm QMD ayarları memory.qmd altında bulunur:
AnahtarTürVarsayılanAçıklama
commandstringqmdQMD yürütülebilir dosya yolu
searchModestringsearchArama komutu: search, vsearch, query
includeDefaultMemorybooleantrueMEMORY.md + memory/**/*.md otomatik dizinleme
paths[]arrayEk yollar: { name, path, pattern? }
sessions.enabledbooleanfalseOturum dökümlerini dizinler
sessions.retentionDaysnumberDöküm saklama süresi
sessions.exportDirstringDışa aktarma dizini
OpenClaw, geçerli QMD koleksiyonu ve MCP sorgu şekillerini tercih eder, ancak gerektiğinde eski --mask koleksiyon bayraklarına ve daha eski MCP araç adlarına geri dönerek eski QMD sürümlerini de çalışır durumda tutar. QMD model geçersiz kılmaları OpenClaw yapılandırmasında değil, QMD tarafında kalır. QMD modellerini genel olarak geçersiz kılmanız gerekiyorsa ağ geçidi çalışma zamanı ortamında QMD_EMBED_MODEL, QMD_RERANK_MODEL ve QMD_GENERATE_MODEL gibi ortam değişkenlerini ayarlayın.

Güncelleme takvimi

AnahtarTürVarsayılanAçıklama
update.intervalstring5mYenileme aralığı
update.debounceMsnumber15000Dosya değişikliklerini debounce eder
update.onBootbooleantrueBaşlangıçta yeniler
update.waitForBootSyncbooleanfalseYenileme tamamlanana kadar başlangıcı engeller
update.embedIntervalstringAyrı gömme sıklığı
update.commandTimeoutMsnumberQMD komutları için zaman aşımı
update.updateTimeoutMsnumberQMD güncelleme işlemleri için zaman aşımı
update.embedTimeoutMsnumberQMD gömme işlemleri için zaman aşımı

Sınırlar

AnahtarTürVarsayılanAçıklama
limits.maxResultsnumber6En fazla arama sonucu
limits.maxSnippetCharsnumberParça uzunluğunu sınırlar
limits.maxInjectedCharsnumberToplam eklenen karakterleri sınırlar
limits.timeoutMsnumber4000Arama zaman aşımı

Kapsam

Hangi oturumların QMD arama sonuçları alabileceğini kontrol eder. Şeması session.sendPolicy ile aynıdır:
{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}
Varsayılan yalnızca DM’dir. match.keyPrefix, normalize edilmiş oturum anahtarıyla eşleşir; match.rawKeyPrefix ise agent:<id>: dahil ham anahtarla eşleşir.

Atıflar

memory.citations tüm arka uçlara uygulanır:
DeğerDavranış
auto (varsayılan)Parçalara Source: <path#line> alt bilgisini ekler
onAlt bilgiyi her zaman ekler
offAlt bilgiyi çıkarır (yol yine de aracıya dahili olarak iletilir)

Tam QMD örneği

{
  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 (deneysel)

Dreaming, agents.defaults.memorySearch altında değil, plugins.entries.memory-core.config.dreaming altında yapılandırılır. Dreaming, tek bir zamanlanmış tarama olarak çalışır ve içsel hafif/derin/REM aşamalarını bir uygulama ayrıntısı olarak kullanır. Kavramsal davranış ve slash komutları için bkz. Dreaming.

Kullanıcı ayarları

AnahtarTürVarsayılanAçıklama
enabledbooleanfalseDreaming’i tamamen etkinleştirir veya devre dışı bırakır
frequencystring0 3 * * *Tam dreaming taraması için isteğe bağlı cron sıklığı

Örnek

{
  plugins: {
    entries: {
      "memory-core": {
        config: {
          dreaming: {
            enabled: true,
            frequency: "0 3 * * *",
          },
        },
      },
    },
  },
}
Notlar:
  • Dreaming, makine durumunu memory/.dreams/ içine yazar.
  • Dreaming, insanlar tarafından okunabilir anlatı çıktısını DREAMS.md içine (veya mevcutsa dreams.md) yazar.
  • Hafif/derin/REM aşama ilkesi ve eşikleri, kullanıcıya dönük yapılandırma değil, içsel davranıştır.