​

Bellek

​

Bellek dosyaları (Markdown)

• memory/YYYY-MM-DD.md
  • Günlük kayıt (yalnızca ekleme).
  • Oturum başlangıcında bugün + dün okunur.
• MEMORY.md (isteğe bağlı)
  • Küratörlü uzun vadeli bellek.
  • Yalnızca ana, özel oturumda yüklenir (grup bağlamlarında asla).

​

When to write memory

• Kararlar, tercihler ve kalıcı gerçekler MEMORY.md dosyasına gider.
• Günlük notlar ve akan bağlam memory/YYYY-MM-DD.md dosyasına gider.
• Birisi “bunu hatırla” derse, yazın (RAM’de tutmayın).
• Bu alan hâlâ gelişiyor. Modele anıları kaydetmesini hatırlatmak yardımcı olur; ne yapacağını bilir.
• Bir şeyin kalıcı olmasını istiyorsanız, botun belleğe yazmasını isteyin.

​

Otomatik bellek boşaltma (ön-sıkıştırma ping’i)

{
  agents: {
    defaults: {
      compaction: {
        reserveTokensFloor: 20000,
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 4000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

• Yumuşak eşik: oturum belirteç tahmini contextWindow - reserveTokensFloor - softThresholdTokens değerini geçtiğinde boşaltma tetiklenir.
• Varsayılan olarak sessiz: istemler, hiçbir şeyin iletilmemesi için NO_REPLY içerir.
• İki istem: bir kullanıcı istemi ve bir sistem istemi hatırlatmayı ekler.
• Sıkıştırma döngüsü başına tek boşaltma (sessions.json içinde izlenir).
• Çalışma alanı yazılabilir olmalıdır: oturum workspaceAccess: "ro" veya "none" ile sandbox içinde çalışıyorsa boşaltma atlanır.

​

Vektör bellek araması

• Varsayılan olarak etkindir.
• Bellek dosyalarındaki değişiklikleri izler (debounce’lu).
• Bellek aramasını agents.defaults.memorySearch altında yapılandırın (üst seviye memorySearch değil).
• Varsayılan olarak uzak embedding’ler kullanır. memorySearch.provider ayarlı değilse OpenClaw otomatik olarak seçer:
  1. local (bir memorySearch.local.modelPath yapılandırılmışsa ve dosya varsa).
  2. Bir OpenAI anahtarı çözümlenebiliyorsa openai.
  3. Bir Gemini anahtarı çözümlenebiliyorsa gemini.
  4. Bir Voyage anahtarı çözümlenebiliyorsa voyage.
  5. Aksi hâlde yapılandırılana kadar bellek araması devre dışı kalır.
• Yerel mod node-llama-cpp kullanır ve pnpm approve-builds gerektirebilir.
• SQLite içinde vektör aramasını hızlandırmak için (mevcutsa) sqlite-vec kullanır.

​

QMD arka ucu (deneysel)

• Varsayılan olarak kapalıdır. Yapılandırma bazında etkinleştirin (memory.backend = "qmd").
• QMD CLI’yi ayrı olarak kurun (bun install -g https://github.com/tobi/qmd veya bir sürüm indirin) ve qmd ikilisinin gateway’in PATH’inde olduğundan emin olun.
• QMD, uzantılara izin veren bir SQLite derlemesine ihtiyaç duyar (macOS’ta brew install sqlite).
• QMD, Bun + node-llama-cpp üzerinden tamamen yerel çalışır ve ilk kullanımda HuggingFace’ten GGUF modellerini otomatik indirir (ayrı bir Ollama daemon’u gerekmez).
• Gateway, XDG_CONFIG_HOME ve XDG_CACHE_HOME ayarlayarak QMD’yi ~/.openclaw/agents/<agentId>/qmd/ altında kendi kendine yeten bir XDG evinde çalıştırır.
• OS desteği: macOS ve Linux, Bun + SQLite kurulduktan sonra kutudan çıktığı gibi çalışır. Windows için WSL2 önerilir.

• Gateway, ~/.openclaw/agents/<agentId>/qmd/ altında kendi kendine yeten bir QMD evi yazar (yapılandırma + önbellek + sqlite DB).
• Koleksiyonlar, memory.qmd.paths’dan (qmd collection add ile) oluşturulur (varsayılan çalışma alanı bellek dosyaları dâhil); ardından qmd update + qmd embed açılışta ve yapılandırılabilir bir aralıkta (memory.qmd.update.interval, varsayılan 5 dk) çalışır.
• Gateway artık QMD yöneticisini başlangıçta başlatır, böylece ilk memory_search çağrısından önce bile periyodik güncelleme zamanlayıcıları etkinleştirilmiş olur.
• Açılış yenilemesi artık varsayılan olarak arka planda çalışır; sohbet başlatma engellenmez. Önceki engelleyici davranışı korumak için memory.qmd.update.waitForBootSync = true’ı ayarlayın.
• Aramalar qmd query --json üzerinden çalışır. Seçilen mod QMD derlemenizde bayrakları reddederse, OpenClaw qmd query ile yeniden dener. QMD başarısız olursa veya ikili yoksa, OpenClaw otomatik olarak yerleşik SQLite yöneticisine geri döner; böylece bellek araçları çalışmaya devam eder.
• OpenClaw bugün QMD embed batch-size ayarını sunmaz; batch davranışı QMD’nin kendisi tarafından denetlenir.
• İlk arama yavaş olabilir: QMD, ilk qmd query çalıştırmada yerel GGUF modellerini (yeniden sıralayıcı/sorgu genişletme) indirebilir.
  • OpenClaw, QMD’yi çalıştırırken XDG_CONFIG_HOME/XDG_CACHE_HOME’ü otomatik ayarlar.
  • Modelleri manuel olarak önceden indirmek (ve OpenClaw’ın kullandığı aynı dizini ısıtmak) isterseniz, ajan XDG dizinleriyle tek seferlik bir sorgu çalıştırın. OpenClaw’ın QMD durumu durum dizininiz altında bulunur (varsayılan ~/.openclaw). OpenClaw’ın kullandığı XDG değişkenlerinin aynısını dışa aktararak qmd’yı tam olarak aynı dizine yönlendirebilirsiniz:
    # Pick the same state dir OpenClaw uses
    STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
    if [ -d "$HOME/.moltbot" ] && [ ! -d "$HOME/.openclaw" ] \
      && [ -z "${OPENCLAW_STATE_DIR:-}" ]; then
      STATE_DIR="$HOME/.moltbot"
    fi
    
    export XDG_CONFIG_HOME="$STATE_DIR/agents/main/qmd/xdg-config"
    export XDG_CACHE_HOME="$STATE_DIR/agents/main/qmd/xdg-cache"
    
    # (Optional) force an index refresh + embeddings
    qmd update
    qmd embed
    
    # Warm up / trigger first-time model downloads
    qmd query "test" -c memory-root --json >/dev/null 2>&1
    

• command (varsayılan qmd): çalıştırılabilir dosya yolunu geçersiz kılar.
• searchMode (varsayılan search): memory_search için hangi QMD komutunun kullanılacağını seçin (search, vsearch, query).
• includeDefaultMemory (varsayılan true): MEMORY.md + memory/**/*.md’ü otomatik indeksler.
• paths[]: ek dizin/dosyalar ekler (path, isteğe bağlı pattern, isteğe bağlı kararlı name).
• sessions: oturum JSONL indekslemesine katılım (enabled, retentionDays, exportDir).
• update: yenileme sıklığını ve bakım yürütümünü denetler: (interval, debounceMs, onBoot, waitForBootSync, embedInterval, commandTimeoutMs, updateTimeoutMs, embedTimeoutMs).
• limits: geri çağırma yükünü sınırlar (maxResults, maxSnippetChars, maxInjectedChars, timeoutMs).
• scope: session.sendPolicy ile aynı şema. Varsayılan DM-only’dir (deny tümü, allow doğrudan sohbetler); grup/kanallarda QMD sonuçlarını göstermek için gevşetin.
  • match.keyPrefix, normalize edilmiş oturum anahtarıyla eşleşir (küçük harfe dönüştürülmüş ve baştaki agent:<id>: kaldırılmış). Örnek: discord:channel:.
  • match.rawKeyPrefix, agent:<id>: dahil olmak üzere ham oturum anahtarıyla (küçük harfe dönüştürülmüş) eşleşir. Örnek: agent:main:discord:.
  • Eski kullanım: match.keyPrefix: "agent:..." hâlâ ham anahtar öneki olarak değerlendirilir, ancak açıklık için rawKeyPrefix tercih edilmelidir.
• scope bir aramayı reddettiğinde, OpenClaw türetilmiş channel/chatType ile bir uyarı kaydeder; böylece boş sonuçların hata ayıklaması kolaylaşır.
• Çalışma alanı dışından kaynaklanan parçalar, memory_search sonuçlarında qmd/<collection>/<relative-path> olarak görünür; memory_get bu öneki anlar ve yapılandırılmış QMD koleksiyon kökünden okur.
• memory.qmd.sessions.enabled = true olduğunda OpenClaw, temizlenmiş oturum dökümlerini (Kullanıcı/Yardımcı turları) ~/.openclaw/agents/<id>/qmd/sessions/ altında özel bir QMD koleksiyonuna dışa aktarır; böylece memory_search, yerleşik SQLite dizinine dokunmadan yakın konuşmaları geri çağırabilir.
• memory_search parçaları, memory.citations auto/on olduğunda artık bir Source: <path#line> altbilgisi içerir; yol meta verisini dahili tutmak için memory.citations = "off"’i ayarlayın (ajan yine memory_get için yolu alır, ancak parça metni altbilgiyi içermez ve sistem istemi ajana bunu alıntılamamasını söyler).

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" }
    ]
  }
}

• memory.citations, arka uçtan bağımsız olarak geçerlidir (auto/on/off).
• qmd çalıştığında, tanılamalarda hangi motorun sonuçları sunduğunu göstermek için status().backend = "qmd" etiketleriz. QMD alt süreci çıkarsa veya JSON çıktısı ayrıştırılamazsa, arama yöneticisi bir uyarı kaydeder ve QMD toparlanana kadar yerleşik sağlayıcıyı (mevcut Markdown embedding’leri) döndürür.

​

Ek bellek yolları

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

• Yollar mutlak veya çalışma alanına göreli olabilir.
• Dizinler .md dosyaları için özyinelemeli taranır.
• Yalnızca Markdown dosyaları indekslenir.
• Symlink’ler yok sayılır (dosya veya dizin).

​

Gemini embedding’leri (yerel)

agents: {
  defaults: {
    memorySearch: {
      provider: "gemini",
      model: "gemini-embedding-001",
      remote: {
        apiKey: "YOUR_GEMINI_API_KEY"
      }
    }
  }
}

• remote.baseUrl isteğe bağlıdır (varsayılan Gemini API taban URL’sidir).
• remote.headers, gerekirse ek başlıklar eklemenizi sağlar.
• Varsayılan model: gemini-embedding-001.

agents: {
  defaults: {
    memorySearch: {
      provider: "openai",
      model: "text-embedding-3-small",
      remote: {
        baseUrl: "https://api.example.com/v1/",
        apiKey: "YOUR_OPENAI_COMPAT_API_KEY",
        headers: { "X-Custom-Header": "value" }
      }
    }
  }
}

• memorySearch.fallback, openai, gemini, local veya none olabilir.
• Geri dönüş sağlayıcısı yalnızca birincil embedding sağlayıcısı başarısız olduğunda kullanılır.

• OpenAI ve Gemini embedding’leri için varsayılan olarak etkindir. Devre dışı bırakmak için agents.defaults.memorySearch.remote.batch.enabled = false’yi ayarlayın.
• Varsayılan davranış batch tamamlanmasını bekler; gerekirse remote.batch.wait, remote.batch.pollIntervalMs ve remote.batch.timeoutMinutes’i ayarlayın.
• Paralel gönderilecek batch iş sayısını denetlemek için remote.batch.concurrency’yı ayarlayın (varsayılan: 2).
• Batch modu, memorySearch.provider = "openai" veya "gemini" olduğunda uygulanır ve ilgili API anahtarını kullanır.
• Gemini batch işleri, async embeddings batch uç noktasını kullanır ve Gemini Batch API erişimi gerektirir.

• Büyük geri doldurmalar için OpenAI, tek bir batch işinde çok sayıda embedding isteği gönderebildiğimiz ve OpenAI’nin bunları asenkron işlemesine izin verdiği için genellikle desteklediğimiz en hızlı seçenektir.
• OpenAI, Batch API iş yükleri için indirimli fiyatlandırma sunar; bu nedenle büyük indeksleme çalışmaları çoğu zaman aynı istekleri eşzamanlı göndermekten daha ucuzdur.
• Ayrıntılar için OpenAI Batch API belgeleri ve fiyatlandırmasına bakın:
  • https://platform.openai.com/docs/api-reference/batch
  • https://platform.openai.com/pricing

agents: {
  defaults: {
    memorySearch: {
      provider: "openai",
      model: "text-embedding-3-small",
      fallback: "openai",
      remote: {
        batch: { enabled: true, concurrency: 2 }
      },
      sync: { watch: true }
    }
  }
}

• memory_search — dosya + satır aralıklarıyla parçalar döndürür.
• memory_get — yola göre bellek dosyası içeriğini okur.

• agents.defaults.memorySearch.provider = "local"’i ayarlayın.
• agents.defaults.memorySearch.local.modelPath sağlayın (GGUF veya hf: URI).
• İsteğe bağlı: uzak geri dönüşü önlemek için agents.defaults.memorySearch.fallback = "none"’ü ayarlayın.

​

Bellek araçları nasıl çalışır

• memory_search, MEMORY.md + memory/**/*.md içindeki Markdown parçalarını anlamsal olarak arar (~400 belirteç hedefi, 80 belirteç örtüşme). Parça metnini (~700 karakter sınırı), dosya yolunu, satır aralığını, skoru, sağlayıcı/modeli ve yerel → uzak embedding’lere geri düşülüp düşülmediğini döndürür. Tam dosya içeriği döndürülmez.
• memory_get, belirli bir bellek Markdown dosyasını (çalışma alanına göreli), isteğe bağlı olarak bir başlangıç satırından ve N satır boyunca okur. MEMORY.md / memory/ dışındaki yollar reddedilir.
• Her iki araç da yalnızca ajan için memorySearch.enabled true çözümlendiğinde etkindir.

​

Neler indekslenir (ve ne zaman)

• Dosya türü: yalnızca Markdown (MEMORY.md, memory/**/*.md).
• Dizin depolama: ajan başına SQLite, ~/.openclaw/memory/<agentId>.sqlite’te ( agents.defaults.memorySearch.store.path ile yapılandırılabilir, {agentId} belirteci desteklenir).
• Tazelik: MEMORY.md + memory/ üzerinde izleyici dizini kirli işaretler (debounce 1,5 sn). Eşitleme oturum başlangıcında, aramada veya bir aralıkta zamanlanır ve asenkron çalışır. Oturum dökümleri, arka plan eşitlemeyi tetiklemek için delta eşiklerini kullanır.
• Yeniden indeksleme tetikleyicileri: dizin, embedding sağlayıcı/model + uç nokta parmak izi + parçalara ayırma parametrelerini saklar. Bunlardan biri değişirse OpenClaw tüm depoyu otomatik olarak sıfırlar ve yeniden indeksler.

​

Hibrit arama (BM25 + vektör)

• Vektör benzerliği (anlamsal eşleşme, ifade farklı olabilir)
• BM25 anahtar kelime uygunluğu (ID’ler, env değişkenleri, kod sembolleri gibi tam belirteçler)

​

Neden hibrit?

• “Mac Studio gateway ana makinesi” vs “gateway’i çalıştıran makine”
• “dosya güncellemelerini debounce et” vs “her yazmada indekslemeyi önle”

• ID’ler (a828e60, b3b9895a…)
• kod sembolleri (memorySearch.query.hybrid)
• hata dizeleri (“sqlite-vec unavailable”)

​

Sonuçları nasıl birleştiriyoruz (mevcut tasarım)

1. Her iki taraftan aday havuzu alın:

• Vektör: kosinüs benzerliğine göre en iyi maxResults * candidateMultiplier.
• BM25: FTS5 BM25 sıralamasına göre en iyi maxResults * candidateMultiplier (daha düşük daha iyidir).

2. BM25 sıralamasını 0..1 benzeri bir skora dönüştürün:

• textScore = 1 / (1 + max(0, bm25Rank))

3. Union candidates by chunk id and compute a weighted score:

• finalScore = vectorWeight * vectorScore + textWeight * textScore

• vectorWeight + textWeight, yapılandırma çözümlemesinde 1,0’a normalize edilir; böylece ağırlıklar yüzde gibi davranır.
• Embedding’ler kullanılamıyorsa (veya sağlayıcı sıfır vektör döndürürse), BM25 yine çalıştırılır ve anahtar kelime eşleşmeleri döndürülür.
• FTS5 oluşturulamıyorsa, yalnızca vektör aramayı koruruz (sert hata yok).

agents: {
  defaults: {
    memorySearch: {
      query: {
        hybrid: {
          enabled: true,
          vectorWeight: 0.7,
          textWeight: 0.3,
          candidateMultiplier: 4
        }
      }
    }
  }
}

​

Embedding cache

agents: {
  defaults: {
    memorySearch: {
      cache: {
        enabled: true,
        maxEntries: 50000
      }
    }
  }
}

​

Oturum belleği araması (deneysel)

agents: {
  defaults: {
    memorySearch: {
      experimental: { sessionMemory: true },
      sources: ["memory", "sessions"]
    }
  }
}

• Oturum indeksleme isteğe bağlıdır (varsayılan olarak kapalı).
• Oturum güncellemeleri debounce edilir ve delta eşiklerini aştıktan sonra asenkron olarak indekslenir (en iyi çaba).
• memory_search indekslemeyi asla beklemez; arka plan eşitlemesi bitene kadar sonuçlar biraz eski olabilir.
• Sonuçlar yine yalnızca parçaları içerir; memory_get bellek dosyalarıyla sınırlı kalır.
• Oturum indeksleme ajan başına yalıtılmıştır (yalnızca o ajanın oturum günlükleri indekslenir).
• Oturum günlükleri diskte yaşar (~/.openclaw/agents/<agentId>/sessions/*.jsonl). Dosya sistemi erişimi olan herhangi bir süreç/kullanıcı okuyabilir; bu nedenle disk erişimini güven sınırı olarak değerlendirin. Daha sıkı yalıtım için ajanları ayrı OS kullanıcıları veya ana makineler altında çalıştırın.

agents: {
  defaults: {
    memorySearch: {
      sync: {
        sessions: {
          deltaBytes: 100000,   // ~100 KB
          deltaMessages: 50     // JSONL lines
        }
      }
    }
  }
}

​

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

agents: {
  defaults: {
    memorySearch: {
      store: {
        vector: {
          enabled: true,
          extensionPath: "/path/to/sqlite-vec"
        }
      }
    }
  }
}

• enabled varsayılan olarak true’dur; devre dışı bırakıldığında arama, saklanan embedding’ler üzerinde süreç içi kosinüs benzerliğine geri döner.
• sqlite-vec uzantısı yoksa veya yüklenemezse OpenClaw hatayı kaydeder ve JS geri dönüşüyle devam eder (vektör tablo yok).
• extensionPath, paketlenmiş sqlite-vec yolunu geçersiz kılar (özel derlemeler veya standart dışı kurulumlar için yararlı).

​

Yerel embedding otomatik indirme

• Varsayılan yerel embedding modeli: hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf (~0,6 GB).
• memorySearch.provider = "local" olduğunda node-llama-cpp, modelPath’i çözümler; GGUF eksikse önbelleğe (veya ayarlıysa local.modelCacheDir) otomatik indirir, sonra yükler. İndirmeler yeniden denemede devam eder.
• Yerel derleme gereksinimi: pnpm approve-builds çalıştırın, node-llama-cpp’i seçin, ardından pnpm rebuild node-llama-cpp.
• Geri dönüş: yerel kurulum başarısız olursa ve memorySearch.fallback = "openai" ise, otomatik olarak uzak embedding’lere geçeriz (openai/text-embedding-3-small varsayılan, aksi belirtilmedikçe) ve nedeni kaydederiz.

​

Özel OpenAI-uyumlu uç nokta örneği

agents: {
  defaults: {
    memorySearch: {
      provider: "openai",
      model: "text-embedding-3-small",
      remote: {
        baseUrl: "https://api.example.com/v1/",
        apiKey: "YOUR_REMOTE_API_KEY",
        headers: {
          "X-Organization": "org-id",
          "X-Project": "project-id"
        }
      }
    }
  }
}

• remote.*, models.providers.openai.*’ya göre önceliklidir.
• remote.headers, OpenAI başlıklarıyla birleştirilir; anahtar çakışmalarında uzak taraf kazanır. OpenAI varsayılanlarını kullanmak için remote.headers’i atlayın.