Dokumentacja konfiguracji pamięci

Ta strona zawiera listę wszystkich ustawień konfiguracyjnych wyszukiwania pamięci w OpenClaw. Omówienia koncepcyjne znajdziesz tutaj:

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

Wybór dostawcy

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

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

Jawnie określeni dostawcy nielokalni stosują zasadę bezpiecznego odrzucania. Jeśli ustawisz memorySearch.provider na konkretnego dostawcę zdalnego, takiego jak Bedrock, DeepInfra, Gemini, GitHub Copilot, LM Studio, Mistral, Ollama, OpenAI, Voyage lub niestandardowego dostawcę zgodnego z OpenAI, a dostawca ten będzie niedostępny w czasie działania, memory_search zwróci wynik informujący o niedostępności, zamiast niejawnie użyć przywoływania wyłącznie przez FTS. Popraw konfigurację dostawcy lub uwierzytelniania, przełącz się na dostępnego dostawcę albo ustaw provider: "none", jeśli chcesz świadomie korzystać z przywoływania wyłącznie przez FTS.

Niestandardowe identyfikatory dostawców

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

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

Ustalanie klucza API

Zdalne osadzanie wymaga klucza API. Bedrock korzysta zamiast niego z domyślnego łańcucha poświadczeń AWS SDK (ról instancji, SSO, kluczy dostępu lub klucza API Bedrock).

Konfiguracja zdalnego punktu końcowego

Użyj 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 trybie bezpośrednim

Zachowanie indeksowania

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

Konfiguracja wyszukiwania hybrydowego

Wszystkie poniższe ustawienia znajdują się 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 rekurencyjnie w poszukiwaniu plików .md. Obsługa dowiązań symbolicznych zależy od aktywnego mechanizmu: wbudowany mechanizm pomija dowiązania symboliczne, natomiast QMD stosuje zachowanie bazowego skanera QMD.

Do wyszukiwania transkrypcji między agentami w zakresie danego agenta użyj agents.list[].memorySearch.qmd.extraCollections zamiast memory.qmd.paths. Te dodatkowe kolekcje mają ten sam format { path, name, pattern? }, ale są scalane osobno dla każdego agenta i mogą zachowywać jawnie określone współdzielone nazwy, 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 w memorySearch.qmd.extraCollections, QMD zachowuje pierwszy wpis i pomija duplikat.

Pamięć multimodalna (Gemini)

Indeksuj obrazy i dźwięk wraz z plikami Markdown za pomocą 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 tworzeniu osadzeń dla niezmienionego tekstu podczas ponownego indeksowania lub aktualizacji transkrypcji. Pozostaw maxEntries bez wartości, aby pamięć podręczna była nieograniczona; ustaw ją, gdy ograniczenie zajętości dysku jest ważniejsze niż maksymalna szybkość ponownego indeksowania. Po ustawieniu tej wartości i przekroczeniu limitu najstarsze wpisy (według czasu ostatniej aktualizacji) są usuwane jako pierwsze.

Indeksowanie wsadowe

Dostępne dla gemini, openai i voyage. Przetwarzanie wsadowe OpenAI jest zazwyczaj najszybsze i najtańsze w przypadku uzupełniania dużych zbiorów danych.

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

To ustawienie jest niezależne od sync.embeddingBatchTimeoutSeconds, które określa limit czasu bezpośrednich wywołań osadzania.

Wyszukiwanie w pamięci sesji (eksperymentalne)

Indeksuj transkrypcje sesji i udostępniaj je za pomocą memory_search:

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

Poniższe przykłady umieszczają te ustawienia w agents.defaults. Równoważne ustawienia memorySearch można również zastosować w nadpisaniu dla konkretnego agenta, gdy tylko jeden agent ma indeksować i przeszukiwać transkrypcje sesji.

Aby umożliwić przywoływanie wiadomości prywatnych przez Gateway 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 nie eksportują transkrypcji do QMD. Ustaw również memory.qmd.sessions.enabled: true.

Akceleracja wektorowa SQLite (sqlite-vec)

Gdy sqlite-vec jest niedostępne, OpenClaw automatycznie przełącza się na podobieństwo cosinusowe obliczane 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

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

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

rerank: false zmienia wyłącznie 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ę opcję nieustawioną, aby używać domyślnego mechanizmu ponownego szeregowania zapytań QMD.

OpenClaw preferuje aktualne formaty kolekcji QMD i zapytań MCP, ale zachowuje zgodność ze starszymi wersjami QMD, w razie potrzeby wypróbowując zgodne flagi wzorców kolekcji i starsze nazwy narzędzi MCP. Gdy QMD deklaruje obsługę wielu filtrów kolekcji, kolekcje z tego samego źródła są przeszukiwane przez jeden proces QMD; starsze kompilacje QMD zachowują ścieżkę zgodności osobną dla każdej kolekcji. To samo źródło oznacza, że kolekcje trwałej pamięci — domyślne pliki pamięci i niestandardowe ścieżki — są grupowane razem, natomiast kolekcje transkrypcji sesji pozostają osobną grupą, dzięki czemu dywersyfikacja źródeł nadal uwzględnia oba rodzaje danych wejściowych.

Integracja z mcporter

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

Wymaga zainstalowanego programu mcporter, dostępnego w PATH, oraz skonfigurowanego serwera mcporter uruchamiającego qmd mcp. Pozostaw wyłączone w prostszych konfiguracjach lokalnych, w których koszt uruchamiania procesu dla każdego zapytania jest akceptowalny.

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

Gdy inicjalizacja QMD podczas uruchamiania 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 osadzania, podczas uruchamiania używany jest jednorazowy menedżer do wykonania odświeżenia startowego, a następnie zostaje zamknięty. Jeśli skonfigurowano interwał aktualizacji lub osadzania, podczas uruchamiania otwierany jest długotrwały menedżer QMD, który zarządza obserwatorem i licznikami interwałów; update.onBoot: false pomija tylko 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 działania koncepcyjnego i poleceń z ukośnikiem zawiera sekcja 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