Dokumentacja referencyjna konfiguracji pamięci

Ta strona wymienia wszystkie ustawienia konfiguracji wyszukiwania pamięci OpenClaw. Omówienia koncepcyjne znajdziesz tutaj:

Wszystkie ustawienia wyszukiwania pamięci znajdują się w agents.defaults.memorySearch w openclaw.json, chyba że zaznaczono inaczej.

Wybór dostawcy

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

Gdy provider nie jest ustawiony, obecne jest starsze provider: "auto" albo provider: "none" celowo wybiera tryb tylko FTS, przywoływanie pamięci nadal może używać leksykalnego rankingu FTS, gdy osadzenia są niedostępne.

Jawni dostawcy nielokalni zawodzą w trybie zamkniętym. Jeśli ustawisz memorySearch.provider na konkretnego dostawcę opartego na zdalnym backendzie, takiego jak OpenAI, Gemini, Voyage, Mistral, Bedrock, GitHub Copilot, DeepInfra, Ollama, LM Studio albo zgodnego z OpenAI dostawcę niestandardowego, i ten dostawca jest niedostępny w czasie działania, memory_search zwraca wynik niedostępności zamiast po cichu używać przywoływania tylko FTS. Napraw konfigurację dostawcy/uwierzytelniania, przełącz się na osiągalnego dostawcę albo ustaw provider: "none", jeśli chcesz celowego przywoływania tylko FTS.

Niestandardowe identyfikatory dostawców

memorySearch.provider może wskazywać niestandardowy wpis models.providers.<id> dla adapterów dostawców specyficznych dla pamięci, takich jak ollama, albo dla zgodnych z OpenAI API modeli, takich jak openai-responses / openai-completions. OpenClaw rozwiązuje właściciela api tego dostawcy dla adaptera osadzania, zachowując jednocześnie niestandardowy identyfikator dostawcy na potrzeby obsługi punktu końcowego, uwierzytelniania i prefiksu modelu. Dzięki temu konfiguracje z wieloma GPU lub wieloma hostami mogą przeznaczyć osadzenia pamięci dla 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" }],      },    },  },  agents: {    defaults: {      memorySearch: {        provider: "ollama-5080",        model: "qwen3-embedding:0.6b",      },    },  },}

Rozwiązywanie klucza API

Zdalne osadzenia wymagają klucza API. Bedrock używa zamiast tego domyślnego łańcucha poświadczeń AWS SDK (role instancji, SSO, klucze dostępu).

Konfiguracja zdalnego punktu końcowego

Użyj provider: "openai-compatible" dla ogólnego zgodnego z OpenAI serwera /v1/embeddings, 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 specyficzna 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 embeddingów inline

Konfiguracja wyszukiwania hybrydowego

Wszystko pod memorySearch.query.hybrid:

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

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

Ścieżki mogą być bezwzględne albo względne względem obszaru roboczego. Katalogi są skanowane rekurencyjnie w poszukiwaniu plików .md. Obsługa dowiązań symbolicznych zależy od aktywnego backendu: wbudowany silnik ignoruje dowiązania symboliczne, natomiast QMD stosuje zachowanie bazowego skanera QMD.

W przypadku wyszukiwania transkrypcji między agentami w zakresie 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 nazwy współdzielone, gdy ścieżka wskazuje poza bieżący obszar roboczy. Jeśli ta sama rozwiązana ścieżka pojawia się 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 audio razem 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 (audio).

Pamięć podręczna embeddingów

Zapobiega ponownemu embeddingowi niezmienionego tekstu podczas ponownego indeksowania lub aktualizacji transkrypcji.

Indeksowanie wsadowe

Dostępne dla openai, gemini i voyage. Wsad OpenAI jest zwykle najszybszy i najtańszy przy dużych uzupełnieniach historycznych.

remote.nonBatchConcurrency kontroluje wywołania embeddingów inline używane przez lokalnych/samodzielnie hostowanych dostawców oraz dostawców hostowanych, gdy API wsadowe dostawcy nie są aktywne. Ollama domyślnie używa 1 dla indeksowania niewsadowego, aby uniknąć przeciążenia mniejszych hostów lokalnych; ustaw wyższą wartość na większych maszynach.

Jest to niezależne od sync.embeddingBatchTimeoutSeconds, które kontroluje limit czasu wywołań embeddingów inline.

Wyszukiwanie w pamięci sesji (eksperymentalne)

Indeksuj transkrypcje sesji i udostępniaj je przez memory_search:

Trafienia transkrypcji sesji również respektują tools.sessions.visibility. Domyślna widoczność tree udostępnia tylko bieżącą sesję oraz sesje przez nią utworzone. Aby przywołać niepowiązaną sesję tego samego agenta wysłaną przez Gateway z innej sesji, takiej jak DM, celowo rozszerz widoczność do agent (lub do all tylko wtedy, gdy wymagane jest także przywoływanie między agentami i zezwala na to polityka agent-agent).

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

Dla przywoływania Gateway-do-DM 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 używania QMD, agents.defaults.memorySearch.experimental.sessionMemory oraz sources: ["sessions"] same z siebie nie eksportują transkrypcji do QMD. Ustaw również memory.qmd.sessions.enabled: true.

Przyspieszenie wektorowe SQLite (sqlite-vec)

Gdy sqlite-vec jest niedostępny, OpenClaw automatycznie przełącza się na podobieństwo cosinusowe w procesie.

Przechowywanie indeksów

Wbudowane indeksy pamięci znajdują się w bazie danych OpenClaw SQLite każdego agenta pod 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" działa wyłącznie leksykalnie/BM25. OpenClaw nie uruchamia sond gotowości wektorów semantycznych ani utrzymania embeddingów QMD dla tego trybu, także podczas memory status --deep; vsearch i query nadal wymagają gotowości wektorowej QMD oraz embeddingów.

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 opartym na mcporter przekazuje rerank: false do ujednoliconego narzędzia zapytań QMD. Pozostaw to nieustawione, aby używać domyślnego zachowania ponownego rankingowania zapytań QMD.

OpenClaw preferuje bieżące kształty kolekcji QMD i zapytań MCP, ale utrzymuje działanie starszych wydań 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 z tego samego źródła są przeszukiwane jednym procesem QMD; starsze kompilacje QMD zachowują ścieżkę zgodności dla pojedynczych kolekcji. To samo źródło oznacza, że trwałe kolekcje pamięci są grupowane razem, natomiast kolekcje transkrypcji sesji pozostają osobną grupą, aby dywersyfikacja źródeł nadal miała oba wejścia.

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

Gdy inicjalizacja QMD przy starcie Gateway jest włączona, OpenClaw uruchamia QMD tylko dla kwalifikujących się agentów. Jeśli update.onBoot ma wartość true i nie skonfigurowano konserwacji interwału ani osadzania, uruchomienie używa jednorazowego menedżera do odświeżenia przy starcie i zamyka go. Jeśli skonfigurowano interwał aktualizacji lub osadzania, uruchomienie otwiera długotrwałego menedżera QMD, aby mógł posiadać obserwator i liczniki interwałów; update.onBoot: false pomija tylko natychmiastowe odświeżenie przy starcie.

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

Dreaming konfiguruje się w plugins.entries.memory-core.config.dreaming, a nie w agents.defaults.memorySearch.

Dreaming działa jako jedno zaplanowane przemiatanie i używa wewnętrznych faz lekkiej/głębokiej/REM jako szczegółu implementacyjnego.

Opis zachowania koncepcyjnego i poleceń z ukośnikiem znajdziesz w 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