Przejdź do głównej treści

Dokumentacja konfiguracji pamięci

Ta strona zawiera wszystkie ustawienia konfiguracyjne wyszukiwania w pamięci w OpenClaw. Aby zapoznać się z omówieniami koncepcyjnymi, zobacz: Wszystkie ustawienia wyszukiwania w pamięci znajdują się w agents.defaults.memorySearch w openclaw.json, o ile nie zaznaczono inaczej. Jeśli szukasz przełącznika funkcji active memory i konfiguracji subagenta, znajdują się one w plugins.entries.active-memory, a nie w memorySearch. Active memory korzysta z modelu dwóch bramek:
  1. Plugin musi być włączony i kierować na bieżący identyfikator agenta
  2. Żądanie musi być kwalifikującą się interaktywną trwałą sesją czatu
Model aktywacji, konfigurację należącą do Plugin, trwałość transkryptu i bezpieczny wzorzec wdrażania opisano w Active Memory.

Wybór dostawcy

KluczTypDomyślnieOpis
providerstringwykrywany automatycznieIdentyfikator adaptera osadzeń: bedrock, gemini, github-copilot, local, mistral, ollama, openai, voyage
modelstringdomyślny dostawcyNazwa modelu osadzeń
fallbackstring"none"Identyfikator zapasowego adaptera, gdy główny zawiedzie
enabledbooleantrueWłącza lub wyłącza wyszukiwanie w pamięci

Kolejność automatycznego wykrywania

Gdy provider nie jest ustawiony, OpenClaw wybiera pierwszy dostępny:
  1. local — jeśli skonfigurowano memorySearch.local.modelPath i plik istnieje.
  2. github-copilot — jeśli można rozpoznać token GitHub Copilot (zmienna środowiskowa lub profil uwierzytelniania).
  3. openai — jeśli można rozpoznać klucz OpenAI.
  4. gemini — jeśli można rozpoznać klucz Gemini.
  5. voyage — jeśli można rozpoznać klucz Voyage.
  6. mistral — jeśli można rozpoznać klucz Mistral.
  7. bedrock — jeśli łańcuch poświadczeń AWS SDK zostanie rozpoznany (rola instancji, klucze dostępu, profil, SSO, tożsamość webowa lub współdzielona konfiguracja).
ollama jest obsługiwany, ale nie jest wykrywany automatycznie (ustaw go jawnie).

Rozpoznawanie kluczy API

Zdalne osadzenia wymagają klucza API. Bedrock zamiast tego używa domyślnego łańcucha poświadczeń AWS SDK (role instancji, SSO, klucze dostępu).
DostawcaZmienna środowiskowaKlucz konfiguracji
Bedrockłańcuch poświadczeń AWSKlucz API nie jest wymagany
GeminiGEMINI_API_KEYmodels.providers.google.apiKey
GitHub CopilotCOPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKENProfil uwierzytelniania przez logowanie urządzenia
MistralMISTRAL_API_KEYmodels.providers.mistral.apiKey
OllamaOLLAMA_API_KEY (placeholder)
OpenAIOPENAI_API_KEYmodels.providers.openai.apiKey
VoyageVOYAGE_API_KEYmodels.providers.voyage.apiKey
OAuth Codex obejmuje tylko chat/completions i nie spełnia wymagań żądań osadzeń.

Konfiguracja zdalnego punktu końcowego

Dla niestandardowych punktów końcowych zgodnych z OpenAI lub nadpisania ustawień domyślnych dostawcy:
KluczTypOpis
remote.baseUrlstringNiestandardowy bazowy URL API
remote.apiKeystringNadpisanie klucza API
remote.headersobjectDodatkowe nagłówki HTTP (łączone z domyślnymi ustawieniami 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

KluczTypDomyślnieOpis
modelstringgemini-embedding-001Obsługuje także gemini-embedding-2-preview
outputDimensionalitynumber3072Dla Embedding 2: 768, 1536 lub 3072
Zmiana modelu lub outputDimensionality uruchamia automatyczne pełne ponowne indeksowanie.

Konfiguracja osadzeń Bedrock

Bedrock używa domyślnego łańcucha poświadczeń AWS SDK — klucze API nie są potrzebne. Jeśli OpenClaw działa na EC2 z rolą instancji z włączonym Bedrock, wystarczy ustawić dostawcę i model:
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0",
      },
    },
  },
}
KluczTypDomyślnieOpis
modelstringamazon.titan-embed-text-v2:0Dowolny identyfikator modelu osadzeń Bedrock
outputDimensionalitynumberdomyślna wartość modeluDla Titan V2: 256, 512 lub 1024

Obsługiwane modele

Obsługiwane są następujące modele (z wykrywaniem rodziny i domyślnymi wymiarami):
Model IDDostawcaDomyślne wymiaryKonfigurowalne wymiary
amazon.titan-embed-text-v2:0Amazon1024256, 512, 1024
amazon.titan-embed-text-v1Amazon1536
amazon.titan-embed-g1-text-02Amazon1536
amazon.titan-embed-image-v1Amazon1024
amazon.nova-2-multimodal-embeddings-v1:0Amazon1024256, 384, 1024, 3072
cohere.embed-english-v3Cohere1024
cohere.embed-multilingual-v3Cohere1024
cohere.embed-v4:0Cohere1536256-1536
twelvelabs.marengo-embed-3-0-v1:0TwelveLabs512
twelvelabs.marengo-embed-2-7-v1:0TwelveLabs1024
Warianty z sufiksem przepustowości (na przykład amazon.titan-embed-text-v1:2:8k) dziedziczą konfigurację modelu bazowego.

Uwierzytelnianie

Uwierzytelnianie Bedrock używa standardowej kolejności rozpoznawania poświadczeń AWS SDK:
  1. Zmienne środowiskowe (AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
  2. Pamięć podręczna tokenów SSO
  3. Poświadczenia tokena tożsamości webowej
  4. Współdzielone pliki poświadczeń i konfiguracji
  5. Poświadczenia metadanych ECS lub EC2
Region jest rozpoznawany na podstawie AWS_REGION, AWS_DEFAULT_REGION, baseUrl dostawcy amazon-bedrock albo domyślnie przyjmuje wartość us-east-1.

Uprawnienia IAM

Rola lub użytkownik IAM potrzebuje:
{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "*"
}
Aby zachować zasadę najmniejszych uprawnień, ogranicz InvokeModel do konkretnego modelu:
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0

Konfiguracja lokalnych osadzeń

KluczTypDomyślnieOpis
local.modelPathstringpobierany automatycznieŚcieżka do pliku modelu GGUF
local.modelCacheDirstringdomyślna wartość node-llama-cppKatalog pamięci podręcznej dla pobranych modeli
Domyślny model: 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:
KluczTypDomyślnieOpis
enabledbooleantrueWłącza hybrydowe wyszukiwanie BM25 + wektorowe
vectorWeightnumber0.7Waga dla wyników wektorowych (0-1)
textWeightnumber0.3Waga dla wyników BM25 (0-1)
candidateMultipliernumber4Mnożnik rozmiaru puli kandydatów

MMR (różnorodność)

KluczTypDomyślnieOpis
mmr.enabledbooleanfalseWłącza ponowne rangowanie MMR
mmr.lambdanumber0.70 = maksymalna różnorodność, 1 = maksymalna trafność

Rozpad czasowy (świeżość)

KluczTypDomyślnieOpis
temporalDecay.enabledbooleanfalseWłącza premiowanie świeżości
temporalDecay.halfLifeDaysnumber30Wynik spada o połowę co N dni
Pliki evergreen (MEMORY.md, pliki bez daty w memory/) nigdy nie podlegają rozpadowi.

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

KluczTypOpis
extraPathsstring[]Dodatkowe katalogi lub pliki do indeksowania
{
  agents: {
    defaults: {
      memorySearch: {
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },
    },
  },
}
Ścieżki mogą być bezwzględne lub względne względem workspace. Katalogi są skanowane rekurencyjnie pod kątem 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. Do wyszukiwania transkryptów 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 współdzielone 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 wraz z Markdown przy użyciu Gemini Embedding 2:
KluczTypDomyślnieOpis
multimodal.enabledbooleanfalseWłącza indeksowanie multimodalne
multimodal.modalitiesstring[]["image"], ["audio"] lub ["all"]
multimodal.maxFileBytesnumber10000000Maksymalny rozmiar pliku do indeksowania
Dotyczy tylko plików w extraPaths. Domyślne katalogi główne 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).

Pamięć podręczna osadzeń

KluczTypDomyślnieOpis
cache.enabledbooleanfalseBuforuje osadzenia fragmentów w SQLite
cache.maxEntriesnumber50000Maksymalna liczba buforowanych osadzeń
Zapobiega ponownemu tworzeniu osadzeń dla niezmienionego tekstu podczas ponownego indeksowania lub aktualizacji transkryptów.

Indeksowanie wsadowe

KluczTypDomyślnieOpis
remote.batch.enabledbooleanfalseWłącza interfejs API osadzeń wsadowych
remote.batch.concurrencynumber2Równoległe zadania wsadowe
remote.batch.waitbooleantrueCzeka na ukończenie wsadu
remote.batch.pollIntervalMsnumberInterwał odpytywania
remote.batch.timeoutMinutesnumberLimit czasu wsadu
Dostępne dla openai, gemini i voyage. Wsad OpenAI jest zwykle najszybszy i najtańszy przy dużych uzupełnieniach wstecznych.

Wyszukiwanie pamięci sesji (eksperymentalne)

Indeksuje transkrypty sesji i udostępnia je przez memory_search:
KluczTypDomyślnieOpis
experimental.sessionMemorybooleanfalseWłącza indeksowanie sesji
sourcesstring[]["memory"]Dodaj "sessions", aby uwzględnić transkrypty
sync.sessions.deltaBytesnumber100000Próg bajtów dla ponownego indeksowania
sync.sessions.deltaMessagesnumber50Próg liczby wiadomości dla ponownego indeksowania
Indeksowanie sesji jest opcjonalne i działa asynchronicznie. Wyniki mogą być nieco nieaktualne. Logi sesji są przechowywane na dysku, więc granicą zaufania jest dostęp do systemu plików.

Przyspieszenie wektorowe SQLite (sqlite-vec)

KluczTypDomyślnieOpis
store.vector.enabledbooleantrueUżywa sqlite-vec do zapytań wektorowych
store.vector.extensionPathstringbundledNadpisuje ścieżkę sqlite-vec
Gdy sqlite-vec jest niedostępne, OpenClaw automatycznie przechodzi na obliczanie podobieństwa cosinusowego w procesie.

Magazyn indeksu

KluczTypDomyślnieOpis
store.pathstring~/.openclaw/memory/{agentId}.sqliteLokalizacja indeksu (obsługuje token {agentId})
store.fts.tokenizerstringunicode61Tokenizer FTS5 (unicode61 lub trigram)

Konfiguracja backendu QMD

Aby włączyć, ustaw memory.backend = "qmd". Wszystkie ustawienia QMD znajdują się w memory.qmd:
KluczTypDomyślnieOpis
commandstringqmdŚcieżka do pliku wykonywalnego QMD
searchModestringsearchPolecenie wyszukiwania: search, vsearch, query
includeDefaultMemorybooleantrueAutomatycznie indeksuje MEMORY.md + memory/**/*.md
paths[]arrayDodatkowe ścieżki: { name, path, pattern? }
sessions.enabledbooleanfalseIndeksuje transkrypty sesji
sessions.retentionDaysnumberCzas przechowywania transkryptów
sessions.exportDirstringKatalog eksportu
OpenClaw preferuje bieżące kształty kolekcji QMD i zapytań MCP, ale zachowuje zgodność ze starszymi wydaniami QMD, przechodząc w razie potrzeby na starsze flagi kolekcji --mask i starsze nazwy narzędzi MCP. Nadpisania modeli QMD pozostają po stronie QMD, a nie w konfiguracji OpenClaw. Jeśli chcesz globalnie nadpisać modele QMD, ustaw zmienne środowiskowe takie jak QMD_EMBED_MODEL, QMD_RERANK_MODEL i QMD_GENERATE_MODEL w środowisku uruchomieniowym Gateway.

Harmonogram aktualizacji

KluczTypDomyślnieOpis
update.intervalstring5mInterwał odświeżania
update.debounceMsnumber15000Debounce zmian plików
update.onBootbooleantrueOdświeżanie przy uruchomieniu
update.waitForBootSyncbooleanfalseBlokuje uruchamianie do ukończenia odświeżania
update.embedIntervalstringOsobna kadencja osadzania
update.commandTimeoutMsnumberLimit czasu dla poleceń QMD
update.updateTimeoutMsnumberLimit czasu dla operacji aktualizacji QMD
update.embedTimeoutMsnumberLimit czasu dla operacji osadzania QMD

Limity

KluczTypDomyślnieOpis
limits.maxResultsnumber6Maksymalna liczba wyników wyszukiwania
limits.maxSnippetCharsnumberOgranicza długość fragmentu
limits.maxInjectedCharsnumberOgranicza łączną liczbę wstrzykniętych znaków
limits.timeoutMsnumber4000Limit 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" } }],
      },
    },
  },
}
Dostarczana domyślna konfiguracja zezwala na sesje bezpośrednie i kanałowe, nadal odrzucając grupy. Domyślnie tylko DM. match.keyPrefix dopasowuje znormalizowany klucz sesji; match.rawKeyPrefix dopasowuje surowy klucz wraz z agent:<id>:.

Cytowania

memory.citations dotyczy wszystkich backendów:
WartośćZachowanie
auto (domyślnie)Dodaje stopkę Source: <path#line> we fragmentach
onZawsze dodaje stopkę
offPomija 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

Dreaming jest konfigurowane w plugins.entries.memory-core.config.dreaming, a nie w agents.defaults.memorySearch. Dreaming działa jako jeden zaplanowany przebieg i wykorzystuje wewnętrzne fazy light/deep/REM jako szczegół implementacyjny. Aby zapoznać się z zachowaniem koncepcyjnym i poleceniami slash, zobacz Dreaming.

Ustawienia użytkownika

KluczTypDomyślnieOpis
enabledbooleanfalseWłącza lub wyłącza Dreaming całkowicie
frequencystring0 3 * * *Opcjonalna kadencja Cron dla pełnego przebiegu Dreaming

Przykład

{
  plugins: {
    entries: {
      "memory-core": {
        config: {
          dreaming: {
            enabled: true,
            frequency: "0 3 * * *",
          },
        },
      },
    },
  },
}
Uwagi:
  • Dreaming zapisuje stan maszyny w memory/.dreams/.
  • Dreaming zapisuje czytelne dla człowieka dane wyjściowe narracji do DREAMS.md (lub istniejącego dreams.md).
  • Zasady faz light/deep/REM i progi są zachowaniem wewnętrznym, a nie konfiguracją dostępną dla użytkownika.