Dokumentacja konfiguracji pamięci
Ta strona zawiera wszystkie opcje konfiguracji wyszukiwania pamięci w OpenClaw. Aby zapoznać się z omówieniami koncepcyjnymi, zobacz:
Wszystkie ustawienia wyszukiwania pamięci znajdują się w agents.defaults.memorySearch w pliku
openclaw.json, o ile nie zaznaczono inaczej.
Wybór dostawcy
| Klucz | Typ | Domyślnie | Opis |
|---|
provider | string | wykrywany automatycznie | Identyfikator adaptera embeddingów: openai, gemini, voyage, mistral, ollama, local |
model | string | domyślny dostawcy | Nazwa modelu embeddingów |
fallback | string | "none" | Identyfikator adaptera zapasowego, gdy główny zawiedzie |
enabled | boolean | true | Włącza lub wyłącza wyszukiwanie pamięci |
Kolejność automatycznego wykrywania
Gdy provider nie jest ustawiony, OpenClaw wybiera pierwszy dostępny:
local — jeśli skonfigurowano memorySearch.local.modelPath i plik istnieje.openai — jeśli można rozwiązać klucz OpenAI.gemini — jeśli można rozwiązać klucz Gemini.voyage — jeśli można rozwiązać klucz Voyage.mistral — jeśli można rozwiązać klucz Mistral.
ollama jest obsługiwana, ale nie jest wykrywana automatycznie (ustaw ją jawnie).
Rozpoznawanie klucza API
Zdalne embeddingi wymagają klucza API. OpenClaw rozpoznaje go z:
profili auth, models.providers.*.apiKey lub zmiennych środowiskowych.
| Dostawca | Zmienna środowiskowa | Klucz konfiguracji |
|---|
| OpenAI | OPENAI_API_KEY | models.providers.openai.apiKey |
| Gemini | GEMINI_API_KEY | models.providers.google.apiKey |
| Voyage | VOYAGE_API_KEY | models.providers.voyage.apiKey |
| Mistral | MISTRAL_API_KEY | models.providers.mistral.apiKey |
| Ollama | OLLAMA_API_KEY (placeholder) | — |
Konfiguracja zdalnego punktu końcowego
Dla niestandardowych punktów końcowych zgodnych z OpenAI lub nadpisania ustawień domyślnych dostawcy:
| Klucz | Typ | Opis |
|---|
remote.baseUrl | string | Niestandardowy bazowy URL API |
remote.apiKey | string | Nadpisanie klucza API |
remote.headers | object | Dodatkowe nagłówki HTTP (scalane z domyślnymi dostawcy) |
{
agents: {
defaults: {
memorySearch: {
provider: "openai",
model: "text-embedding-3-small",
remote: {
baseUrl: "https://api.example.com/v1/",
apiKey: "YOUR_KEY",
},
},
},
},
}
Konfiguracja specyficzna dla Gemini
| Klucz | Typ | Domyślnie | Opis |
|---|
model | string | gemini-embedding-001 | Obsługuje także gemini-embedding-2-preview |
outputDimensionality | number | 3072 | Dla Embedding 2: 768, 1536 lub 3072 |
Zmiana modelu lub outputDimensionality powoduje automatyczne pełne ponowne indeksowanie.
Konfiguracja lokalnych embeddingów
| Klucz | Typ | Domyślnie | Opis |
|---|
local.modelPath | string | pobierany automatycznie | Ścieżka do pliku modelu GGUF |
local.modelCacheDir | string | domyślne node-llama-cpp | Katalog cache dla pobranych modeli |
embeddinggemma-300m-qat-Q8_0.gguf (~0.6 GB, pobierany automatycznie).
Wymaga natywnego buildu: pnpm approve-builds, a następnie pnpm rebuild node-llama-cpp.
Konfiguracja wyszukiwania hybrydowego
Wszystko w memorySearch.query.hybrid:
| Klucz | Typ | Domyślnie | Opis |
|---|
enabled | boolean | true | Włącza hybrydowe wyszukiwanie BM25 + wektorowe |
vectorWeight | number | 0.7 | Waga dla wyników wektorowych (0-1) |
textWeight | number | 0.3 | Waga dla wyników BM25 (0-1) |
candidateMultiplier | number | 4 | Mnożnik rozmiaru puli kandydatów |
MMR (różnorodność)
| Klucz | Typ | Domyślnie | Opis |
|---|
mmr.enabled | boolean | false | Włącza ponowne rankingowanie MMR |
mmr.lambda | number | 0.7 | 0 = maks. różnorodność, 1 = maks. trafność |
Zanikanie czasowe (świeżość)
| Klucz | Typ | Domyślnie | Opis |
|---|
temporalDecay.enabled | boolean | false | Włącza premiowanie świeżości |
temporalDecay.halfLifeDays | number | 30 | Wynik zmniejsza się o połowę co N dni |
MEMORY.md, pliki bez daty w memory/) nigdy nie podlegają zanikaniu.
Pełny przykład
{
agents: {
defaults: {
memorySearch: {
query: {
hybrid: {
vectorWeight: 0.7,
textWeight: 0.3,
mmr: { enabled: true, lambda: 0.7 },
temporalDecay: { enabled: true, halfLifeDays: 30 },
},
},
},
},
},
}
Dodatkowe ścieżki pamięci
| Klucz | Typ | Opis |
|---|
extraPaths | string[] | Dodatkowe katalogi lub pliki do indeksowania |
{
agents: {
defaults: {
memorySearch: {
extraPaths: ["../team-docs", "/srv/shared-notes"],
},
},
},
}
.md. Obsługa symlinków zależy od aktywnego backendu:
wbudowany silnik ignoruje symlinki, a QMD podąża za zachowaniem skanera QMD.
Do wyszukiwania transkryptów między agentami w zakresie konkretnego agenta użyj
agents.list[].memorySearch.qmd.extraCollections zamiast memory.qmd.paths.
Te dodatkowe kolekcje mają ten sam kształt { path, name, pattern? }, ale
są scalane per agent i mogą zachowywać jawne wspólne nazwy, gdy ścieżka
wskazuje poza bieżący workspace.
Jeśli ta sama rozpoznana ścieżka pojawi się zarówno w memory.qmd.paths, jak i
memorySearch.qmd.extraCollections, QMD zachowuje pierwszy wpis i pomija
duplikat.
Pamięć multimodalna (Gemini)
Indeksuj obrazy i audio obok Markdown przy użyciu Gemini Embedding 2:
| Klucz | Typ | Domyślnie | Opis |
|---|
multimodal.enabled | boolean | false | Włącza indeksowanie multimodalne |
multimodal.modalities | string[] | — | ["image"], ["audio"] lub ["all"] |
multimodal.maxFileBytes | number | 10000000 | Maksymalny rozmiar pliku do indeksowania |
extraPaths. Domyślne korzenie pamięci pozostają tylko dla Markdown.
Wymaga gemini-embedding-2-preview. fallback musi mieć wartość "none".
Obsługiwane formaty: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif
(obrazy); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (audio).
Cache embeddingów
| Klucz | Typ | Domyślnie | Opis |
|---|
cache.enabled | boolean | false | Cache embeddingów chunków w SQLite |
cache.maxEntries | number | 50000 | Maksymalna liczba zapisanych embeddingów |
Indeksowanie wsadowe
| Klucz | Typ | Domyślnie | Opis |
|---|
remote.batch.enabled | boolean | false | Włącza API embeddingów wsadowych |
remote.batch.concurrency | number | 2 | Równoległe zadania wsadowe |
remote.batch.wait | boolean | true | Czeka na zakończenie wsadu |
remote.batch.pollIntervalMs | number | — | Interwał odpytywania |
remote.batch.timeoutMinutes | number | — | Limit czasu wsadu |
openai, gemini i voyage. Wsadowe API OpenAI jest zwykle
najszybsze i najtańsze przy dużych backfillach.
Wyszukiwanie pamięci sesji (eksperymentalne)
Indeksuj transkrypty sesji i udostępniaj je przez memory_search:
| Klucz | Typ | Domyślnie | Opis |
|---|
experimental.sessionMemory | boolean | false | Włącza indeksowanie sesji |
sources | string[] | ["memory"] | Dodaj "sessions", aby uwzględnić transkrypty |
sync.sessions.deltaBytes | number | 100000 | Próg bajtów do ponownego indeksowania |
sync.sessions.deltaMessages | number | 50 | Próg wiadomości do ponownego indeksowania |
Akceleracja wektorowa SQLite (sqlite-vec)
| Klucz | Typ | Domyślnie | Opis |
|---|
store.vector.enabled | boolean | true | Używa sqlite-vec do zapytań wektorowych |
store.vector.extensionPath | string | wbudowana | Nadpisuje ścieżkę sqlite-vec |
Przechowywanie indeksu
| Klucz | Typ | Domyślnie | Opis |
|---|
store.path | string | ~/.openclaw/memory/{agentId}.sqlite | Lokalizacja indeksu (obsługuje token {agentId}) |
store.fts.tokenizer | string | unicode61 | Tokenizer FTS5 (unicode61 lub trigram) |
Konfiguracja backendu QMD
Ustaw memory.backend = "qmd", aby włączyć. Wszystkie ustawienia QMD znajdują się w
memory.qmd:
| Klucz | Typ | Domyślnie | Opis |
|---|
command | string | qmd | Ścieżka do pliku wykonywalnego QMD |
searchMode | string | search | Polecenie wyszukiwania: search, vsearch, query |
includeDefaultMemory | boolean | true | Automatycznie indeksuje MEMORY.md + memory/**/*.md |
paths[] | array | — | Dodatkowe ścieżki: { name, path, pattern? } |
sessions.enabled | boolean | false | Indeksuje transkrypty sesji |
sessions.retentionDays | number | — | Retencja transkryptów |
sessions.exportDir | string | — | Katalog eksportu |
Harmonogram aktualizacji
| Klucz | Typ | Domyślnie | Opis |
|---|
update.interval | string | 5m | Interwał odświeżania |
update.debounceMs | number | 15000 | Debounce zmian w plikach |
update.onBoot | boolean | true | Odświeżanie przy uruchomieniu |
update.waitForBootSync | boolean | false | Blokuje uruchomienie do zakończenia odświeżania |
update.embedInterval | string | — | Oddzielny harmonogram embeddingów |
update.commandTimeoutMs | number | — | Limit czasu dla poleceń QMD |
update.updateTimeoutMs | number | — | Limit czasu dla operacji aktualizacji QMD |
update.embedTimeoutMs | number | — | Limit czasu dla operacji embeddingów QMD |
Limity
| Klucz | Typ | Domyślnie | Opis |
|---|
limits.maxResults | number | 6 | Maksymalna liczba wyników wyszukiwania |
limits.maxSnippetChars | number | — | Ogranicza długość fragmentu |
limits.maxInjectedChars | number | — | Ogranicza łączną liczbę wstrzykniętych znaków |
limits.timeoutMs | number | 4000 | Limit czasu wyszukiwania |
Zakres
Kontroluje, które sesje mogą otrzymywać wyniki wyszukiwania QMD. Ten sam schemat co
session.sendPolicy:
{
memory: {
qmd: {
scope: {
default: "deny",
rules: [{ action: "allow", match: { chatType: "direct" } }],
},
},
},
}
match.keyPrefix dopasowuje znormalizowany klucz sesji;
match.rawKeyPrefix dopasowuje surowy klucz zawierający agent:<id>:.
Cytowania
memory.citations dotyczy wszystkich backendów:
| Wartość | Zachowanie |
|---|
auto (domyślnie) | Dołącza stopkę Source: <path#line> do fragmentów |
on | Zawsze dołącza stopkę |
off | Pomija stopkę (ścieżka nadal jest przekazywana wewnętrznie do agenta) |
Pełny przykład QMD
{
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 (eksperymentalne)
Dreaming konfiguruje się w plugins.entries.memory-core.config.dreaming,
a nie w agents.defaults.memorySearch. Szczegóły koncepcyjne i polecenia
czatu znajdziesz w Dreaming.
| Klucz | Typ | Domyślnie | Opis |
|---|
mode | string | "off" | Preset: off, core, rem lub deep |
cron | string | domyślnie dla presetu | Nadpisanie wyrażenia cron dla harmonogramu |
timezone | string | strefa czasowa użytkownika | Strefa czasowa używana do obliczania harmonogramu |
limit | number | domyślnie dla presetu | Maksymalna liczba kandydatów do promowania na cykl |
minScore | number | domyślnie dla presetu | Minimalny ważony wynik do promowania |
minRecallCount | number | domyślnie dla presetu | Minimalny próg liczby przywołań |
minUniqueQueries | number | domyślnie dla presetu | Minimalny próg liczby różnych zapytań |
Domyślne wartości presetów
| Tryb | Częstotliwość | minScore | minRecallCount | minUniqueQueries |
|---|
off | Wyłączone | — | — | — |
core | Codziennie 3:00 | 0.75 | 3 | 2 |
rem | Co 6 godzin | 0.85 | 4 | 3 |
deep | Co 12 godzin | 0.80 | 3 | 3 |
Przykład
{
plugins: {
entries: {
"memory-core": {
config: {
dreaming: {
mode: "core",
timezone: "America/New_York",
},
},
},
},
},
}
