Dokumentacja konfiguracji pamięci

Ta strona zawiera listę wszystkich opcji konfiguracji wyszukiwania w pamięci OpenClaw. Omówienia koncepcyjne znajdują się tutaj:

Wszystkie ustawienia wyszukiwania w pamięci znajdują się w sekcji agents.defaults.memorySearch pliku openclaw.json (lub w zastępującej ją sekcji agents.list[].memorySearch dla poszczególnych agentów), chyba że zaznaczono inaczej.

Wybór dostawcy

Gdy provider nie jest ustawione, OpenClaw używa osadzeń OpenAI. Aby użyć Bedrock, DeepInfra, Gemini, GitHub Copilot, Mistral, Ollama, Voyage, lokalnego modelu GGUF lub punktu końcowego /v1/embeddings zgodnego z OpenAI, należy jawnie ustawić provider. Starsze konfiguracje, które nadal zawierają provider: "auto", są rozpoznawane jako openai.

Gdy provider nie jest ustawione, obecne jest starsze provider: "auto" lub provider: "none" celowo wybiera tryb wyłącznie FTS, przywoływanie z pamięci może nadal korzystać z leksykalnego rankingu FTS, gdy osadzenia są niedostępne.

Jawnie określeni dostawcy nielokalni stosują zasadę bezpiecznego odrzucania. Jeśli memorySearch.provider zostanie ustawione na konkretnego dostawcę korzystającego ze zdalnego backendu, takiego jak Bedrock, DeepInfra, Gemini, GitHub Copilot, LM Studio, Mistral, Ollama, OpenAI, Voyage lub niestandardowy dostawca zgodny z OpenAI, a dostawca ten będzie niedostępny w czasie działania, memory_search zwróci wynik wskazujący niedostępność zamiast niejawnie używać przywoływania wyłącznie FTS. Należy poprawić konfigurację dostawcy lub uwierzytelniania, przełączyć się na osiągalnego dostawcę albo ustawić provider: "none", jeśli celowo ma być używane przywoływanie wyłącznie FTS.

Niestandardowe identyfikatory dostawców

memorySearch.provider może wskazywać niestandardowy wpis models.providers.<id> dla adapterów dostawców przeznaczonych do pamięci, takich jak ollama, albo dla interfejsów API modeli zgodnych z OpenAI, takich jak openai-responses / openai-completions. OpenClaw rozpoznaje właściciela api tego dostawcy na potrzeby adaptera osadzania, zachowując niestandardowy identyfikator dostawcy do obsługi punktu końcowego, uwierzytelniania i prefiksu modelu. Dzięki temu konfiguracje z wieloma procesorami GPU lub hostami mogą przeznaczyć określony lokalny punkt końcowy na osadzenia pamięci:

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

Rozpoznawanie klucza API

Zdalne osadzenia wymagają klucza API. Bedrock używa zamiast niego domyślnego łańcucha poświadczeń AWS SDK (ról instancji, SSO, kluczy dostępu lub klucza API Bedrock).

Konfiguracja zdalnego punktu końcowego

Należy użyć provider: "openai-compatible" dla ogólnego serwera /v1/embeddings zgodnego z OpenAI, który nie powinien dziedziczyć globalnych poświadczeń czatu OpenAI.

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

Konfiguracja właściwa dla dostawcy

{  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

Limit czasu osadzania w procesie

Zachowanie indeksowania

Wszystkie opcje znajdują się w memorySearch.sync, chyba że zaznaczono inaczej:

Konfiguracja wyszukiwania hybrydowego

Wszystkie opcje w memorySearch.query:

Oraz w memorySearch.query.hybrid:

Pełny przykład

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

Dodatkowe ścieżki pamięci

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

Ścieżki mogą być bezwzględne lub względne wobec obszaru roboczego. Katalogi są skanowane rekursywnie w poszukiwaniu plików .md. Obsługa dowiązań symbolicznych zależy od aktywnego backendu: wbudowany silnik pomija dowiązania symboliczne, natomiast QMD postępuje zgodnie z zachowaniem bazowego skanera QMD.

Do wyszukiwania transkrypcji między agentami w zakresie agenta należy użyć agents.list[].memorySearch.qmd.extraCollections zamiast memory.qmd.paths. Te dodatkowe kolekcje mają ten sam kształt { path, name, pattern? }, ale są scalane osobno dla każdego agenta i mogą zachowywać jawne nazwy współdzielone, gdy ścieżka wskazuje poza bieżący obszar roboczy. Jeśli ta sama rozwiązana ścieżka występuje zarówno w memory.qmd.paths, jak i memorySearch.qmd.extraCollections, QMD zachowuje pierwszy wpis i pomija duplikat.

Pamięć multimodalna (Gemini)

Indeksowanie obrazów i dźwięku wraz z Markdown przy użyciu Gemini Embedding 2:

Obsługiwane formaty: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (obrazy); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (dźwięk).

Pamięć podręczna osadzeń

Zapobiega ponownemu generowaniu osadzeń niezmienionego tekstu podczas ponownego indeksowania lub aktualizacji transkrypcji. Pozostaw maxEntries bez wartości, aby pamięć podręczna była nieograniczona; ustaw tę wartość, gdy ograniczenie przyrostu zajętości dysku jest ważniejsze niż maksymalna szybkość ponownego indeksowania. Po ustawieniu, gdy pamięć podręczna przekroczy limit, najstarsze wpisy (według czasu ostatniej aktualizacji) są usuwane jako pierwsze.

Indeksowanie wsadowe

Dostępne dla gemini, openai i voyage. Przetwarzanie wsadowe OpenAI jest zwykle najszybsze i najtańsze w przypadku dużego uzupełniania danych historycznych.

remote.nonBatchConcurrency steruje bezpośrednimi wywołaniami osadzania używanymi przez dostawców lokalnych/samodzielnie hostowanych oraz dostawców hostowanych, gdy ich wsadowe API nie są aktywne. W przypadku indeksowania niewsadowego Ollama domyślnie używa 1, aby nie przeciążać mniejszych hostów lokalnych; na większych maszynach można ustawić wyższą wartość.

Jest to ustawienie odrębne od sync.embeddingBatchTimeoutSeconds, które steruje limitem czasu bezpośrednich wywołań osadzania.

Wyszukiwanie w pamięci sesji (eksperymentalne)

Indeksuj transkrypcje sesji i udostępniaj je za pośrednictwem memory_search:

Trafienia z transkrypcji sesji również podlegają ustawieniu tools.sessions.visibility. Domyślna widoczność tree udostępnia tylko bieżącą sesję i sesje przez nią uruchomione. Aby przywołać z innej sesji niepowiązaną sesję tego samego agenta wysłaną przez Gateway, na przykład wiadomość prywatną, należy świadomie rozszerzyć widoczność do agent (lub all tylko wtedy, gdy wymagane jest również przywoływanie między agentami i zezwalają na to zasady komunikacji między agentami).

Poniższe przykłady umieszczają te ustawienia w agents.defaults. Można także zastosować równoważne ustawienia memorySearch w nadpisaniu dla konkretnego agenta, jeśli tylko jeden agent ma indeksować i przeszukiwać transkrypcje sesji.

Aby umożliwić przywoływanie z Gateway do wiadomości prywatnych w obrębie tego samego agenta:

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

Podczas korzystania z QMD ustawienia agents.defaults.memorySearch.experimental.sessionMemory i sources: ["sessions"] same w sobie nie eksportują transkrypcji do QMD. Należy również ustawić memory.qmd.sessions.enabled: true.

Akceleracja wektorowa SQLite (sqlite-vec)

Gdy sqlite-vec jest niedostępne, OpenClaw automatycznie przechodzi na obliczanie podobieństwa cosinusowego w procesie.

Przechowywanie indeksów

Wbudowane indeksy pamięci znajdują się w bazie danych SQLite OpenClaw każdego agenta pod ścieżką agents/<agentId>/agent/openclaw-agent.sqlite.

Konfiguracja backendu QMD

Ustaw memory.backend = "qmd", aby włączyć. Wszystkie ustawienia QMD znajdują się w memory.qmd:

searchMode: "search" korzysta wyłącznie z wyszukiwania leksykalnego/BM25. W tym trybie OpenClaw nie wykonuje semantycznych testów gotowości wektorowej ani obsługi osadzeń QMD, również podczas memory status --deep; vsearch i query nadal wymagają gotowości wektorowej i osadzeń QMD.

rerank: false zmienia tylko tryb query QMD i wymaga QMD 2.1 lub nowszego. W bezpośrednim trybie CLI OpenClaw przekazuje --no-rerank; w trybie MCP obsługiwanym przez mcporter przekazuje rerank: false do ujednoliconego narzędzia zapytań QMD. Pozostaw tę wartość nieustawioną, aby używać domyślnego mechanizmu ponownego szeregowania zapytań QMD.

OpenClaw preferuje aktualne formaty kolekcji i zapytań MCP QMD, ale zachowuje obsługę starszych wersji QMD, próbując w razie potrzeby zgodnych flag wzorców kolekcji i starszych nazw narzędzi MCP. Gdy QMD deklaruje obsługę wielu filtrów kolekcji, kolekcje tego samego źródła są przeszukiwane w jednym procesie QMD; starsze kompilacje QMD zachowują ścieżkę zgodności dla poszczególnych kolekcji. To samo źródło oznacza, że kolekcje trwałej pamięci (domyślne pliki pamięci oraz ścieżki niestandardowe) są grupowane razem, natomiast kolekcje transkrypcji sesji pozostają odrębną grupą, dzięki czemu dywersyfikacja źródeł nadal korzysta z obu danych wejściowych.

Integracja z mcporter

Wszystkie ustawienia znajdują się w memory.qmd.mcporter. Kieruje wyszukiwania QMD przez długotrwale działający demon MCP mcporter zamiast uruchamiać qmd dla każdego zapytania, ograniczając narzut zimnego startu w przypadku większych modeli.

Wymaga zainstalowanego mcporter dostępnego w PATH oraz skonfigurowanego serwera mcporter, który uruchamia qmd mcp. W prostszych konfiguracjach lokalnych, w których koszt uruchamiania procesu dla każdego zapytania jest akceptowalny, należy pozostawić tę opcję wyłączoną.

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

Gdy inicjalizacja QMD przy uruchamianiu Gateway jest włączona, OpenClaw uruchamia QMD tylko dla kwalifikujących się agentów. Jeśli update.onBoot ma wartość true i nie skonfigurowano okresowej konserwacji aktualizacji ani osadzeń, podczas uruchamiania używany jest jednorazowy menedżer na potrzeby odświeżenia startowego, który następnie zostaje zamknięty. Jeśli skonfigurowano interwał aktualizacji lub osadzania, podczas uruchamiania otwierany jest długotrwały menedżer QMD, aby zarządzał obserwatorem i licznikami interwałów; update.onBoot: false pomija wyłącznie natychmiastowe odświeżenie startowe.

Pełny przykład QMD

{  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 konfiguruje się w plugins.entries.memory-core.config.dreaming, a nie w agents.defaults.memorySearch.

Dreaming działa jako jedno zaplanowane przetwarzanie i wykorzystuje wewnętrzne fazy lekką, głęboką i REM jako szczegół implementacyjny.

Opis zachowania koncepcyjnego i poleceń z ukośnikiem zawiera strona Dreaming.

Ustawienia użytkownika

Przykład

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

Powiązane

• Dokumentacja konfiguracji
• Omówienie pamięci
• Wyszukiwanie w pamięci