Zum Hauptinhalt springen

Referenz zur Speicherkonfiguration

Diese Seite listet alle Konfigurationsoptionen für die OpenClaw-Speichersuche auf. Für konzeptionelle Übersichten siehe: Alle Einstellungen für die Speichersuche befinden sich unter agents.defaults.memorySearch in openclaw.json, sofern nicht anders angegeben. Wenn Sie nach dem Feature-Schalter für Active Memory und der Konfiguration des Sub-Agenten suchen, finden Sie diese unter plugins.entries.active-memory statt unter memorySearch. Active Memory verwendet ein Modell mit zwei Gates:
  1. Das Plugin muss aktiviert sein und auf die aktuelle Agent-ID zielen
  2. Die Anfrage muss eine geeignete interaktive persistente Chat-Sitzung sein
Siehe Active Memory für das Aktivierungsmodell, die Plugin-eigene Konfiguration, die Persistenz von Transkripten und ein sicheres Rollout-Muster.

Providerauswahl

SchlüsselTypStandardBeschreibung
providerstringautomatisch erkanntEmbedding-Adapter-ID: openai, gemini, voyage, mistral, bedrock, ollama, local
modelstringProvider-StandardName des Embedding-Modells
fallbackstring"none"Fallback-Adapter-ID, wenn der primäre fehlschlägt
enabledbooleantrueSpeichersuche aktivieren oder deaktivieren

Reihenfolge der automatischen Erkennung

Wenn provider nicht gesetzt ist, wählt OpenClaw den ersten verfügbaren:
  1. local — wenn memorySearch.local.modelPath konfiguriert ist und die Datei existiert.
  2. openai — wenn ein OpenAI-Schlüssel aufgelöst werden kann.
  3. gemini — wenn ein Gemini-Schlüssel aufgelöst werden kann.
  4. voyage — wenn ein Voyage-Schlüssel aufgelöst werden kann.
  5. mistral — wenn ein Mistral-Schlüssel aufgelöst werden kann.
  6. bedrock — wenn die AWS-SDK-Credential-Chain aufgelöst wird (Instance Role, Access Keys, Profile, SSO, Web Identity oder Shared Config).
ollama wird unterstützt, aber nicht automatisch erkannt (explizit setzen).

Auflösung von API-Schlüsseln

Remote-Embeddings erfordern einen API-Schlüssel. Bedrock verwendet stattdessen die standardmäßige AWS-SDK-Credential-Chain (Instance Roles, SSO, Access Keys).
ProviderEnv-VariableKonfigurationsschlüssel
OpenAIOPENAI_API_KEYmodels.providers.openai.apiKey
GeminiGEMINI_API_KEYmodels.providers.google.apiKey
VoyageVOYAGE_API_KEYmodels.providers.voyage.apiKey
MistralMISTRAL_API_KEYmodels.providers.mistral.apiKey
BedrockAWS-Credential-ChainKein API-Schlüssel erforderlich
OllamaOLLAMA_API_KEY (Platzhalter)
Codex OAuth gilt nur für Chat/Completions und erfüllt Embedding- Anfragen nicht.

Konfiguration von Remote-Endpunkten

Für benutzerdefinierte OpenAI-kompatible Endpunkte oder zum Überschreiben von Provider-Standards:
SchlüsselTypBeschreibung
remote.baseUrlstringBenutzerdefinierte API-Basis-URL
remote.apiKeystringAPI-Schlüssel überschreiben
remote.headersobjectZusätzliche HTTP-Header (mit Provider-Standards zusammengeführt)
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}

Gemini-spezifische Konfiguration

SchlüsselTypStandardBeschreibung
modelstringgemini-embedding-001Unterstützt auch gemini-embedding-2-preview
outputDimensionalitynumber3072Für Embedding 2: 768, 1536 oder 3072
Das Ändern von model oder outputDimensionality löst eine automatische vollständige Neuindizierung aus.

Bedrock-Embedding-Konfiguration

Bedrock verwendet die standardmäßige AWS-SDK-Credential-Chain — keine API-Schlüssel erforderlich. Wenn OpenClaw auf EC2 mit einer Bedrock-fähigen Instance Role läuft, setzen Sie einfach Provider und Modell:
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0",
      },
    },
  },
}
SchlüsselTypStandardBeschreibung
modelstringamazon.titan-embed-text-v2:0Beliebige Bedrock-Embedding-Modell-ID
outputDimensionalitynumberModellstandardFür Titan V2: 256, 512 oder 1024

Unterstützte Modelle

Die folgenden Modelle werden unterstützt (mit Familienerkennung und Standardwerten für Dimensionen):
Modell-IDProviderStandard-DimensionenKonfigurierbare Dimensionen
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
Varianten mit Durchsatzsuffix (z. B. amazon.titan-embed-text-v1:2:8k) übernehmen die Konfiguration des Basismodells.

Authentifizierung

Bedrock-Auth verwendet die standardmäßige Reihenfolge der AWS-SDK-Credential-Auflösung:
  1. Umgebungsvariablen (AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
  2. SSO-Token-Cache
  3. Credentials über Web-Identity-Token
  4. Gemeinsame Credentials- und Konfigurationsdateien
  5. ECS- oder EC2-Metadaten-Credentials
Die Region wird aus AWS_REGION, AWS_DEFAULT_REGION, der amazon-bedrock-baseUrl des Providers ermittelt oder fällt standardmäßig auf us-east-1 zurück.

IAM-Berechtigungen

Die IAM-Rolle oder der IAM-Benutzer benötigt:
{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "*"
}
Für Least-Privilege beschränken Sie InvokeModel auf das konkrete Modell:
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0

Konfiguration lokaler Embeddings

SchlüsselTypStandardBeschreibung
local.modelPathstringautomatisch heruntergeladenPfad zur GGUF-Modelldatei
local.modelCacheDirstringnode-llama-cpp-StandardCache-Verzeichnis für heruntergeladene Modelle
Standardmodell: embeddinggemma-300m-qat-Q8_0.gguf (~0,6 GB, wird automatisch heruntergeladen). Erfordert einen nativen Build: pnpm approve-builds und dann pnpm rebuild node-llama-cpp.

Konfiguration der Hybridsuche

Alles unter memorySearch.query.hybrid:
SchlüsselTypStandardBeschreibung
enabledbooleantrueHybride BM25- + Vektorsuche aktivieren
vectorWeightnumber0.7Gewicht für Vektor-Scores (0-1)
textWeightnumber0.3Gewicht für BM25-Scores (0-1)
candidateMultipliernumber4Multiplikator für die Größe des Kandidatenpools

MMR (Diversität)

SchlüsselTypStandardBeschreibung
mmr.enabledbooleanfalseMMR-Re-Ranking aktivieren
mmr.lambdanumber0.70 = maximale Diversität, 1 = maximale Relevanz

Zeitlicher Zerfall (Aktualität)

SchlüsselTypStandardBeschreibung
temporalDecay.enabledbooleanfalseAktualitäts-Boost aktivieren
temporalDecay.halfLifeDaysnumber30Score halbiert sich alle N Tage
Immergrüne Dateien (MEMORY.md, nicht datierte Dateien in memory/) unterliegen nie einem Zerfall.

Vollständiges Beispiel

{
  agents: {
    defaults: {
      memorySearch: {
        query: {
          hybrid: {
            vectorWeight: 0.7,
            textWeight: 0.3,
            mmr: { enabled: true, lambda: 0.7 },
            temporalDecay: { enabled: true, halfLifeDays: 30 },
          },
        },
      },
    },
  },
}

Zusätzliche Speicherpfade

SchlüsselTypBeschreibung
extraPathsstring[]Zusätzliche Verzeichnisse oder Dateien zur Indizierung
{
  agents: {
    defaults: {
      memorySearch: {
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },
    },
  },
}
Pfade können absolut oder relativ zum Workspace sein. Verzeichnisse werden rekursiv nach .md-Dateien durchsucht. Die Behandlung von Symlinks hängt vom aktiven Backend ab: Die Builtin Engine ignoriert Symlinks, während QMD dem Verhalten des zugrunde liegenden QMD- Scanners folgt. Für agentenspezifische agentenübergreifende Transkriptsuche verwenden Sie agents.list[].memorySearch.qmd.extraCollections statt memory.qmd.paths. Diese zusätzlichen Collections folgen derselben Form { path, name, pattern? }, werden jedoch pro Agent zusammengeführt und können explizite gemeinsame Namen beibehalten, wenn der Pfad außerhalb des aktuellen Workspace liegt. Wenn derselbe aufgelöste Pfad sowohl in memory.qmd.paths als auch in memorySearch.qmd.extraCollections erscheint, behält QMD den ersten Eintrag und überspringt das Duplikat.

Multimodaler Speicher (Gemini)

Indizieren Sie Bilder und Audio zusammen mit Markdown mit Gemini Embedding 2:
SchlüsselTypStandardBeschreibung
multimodal.enabledbooleanfalseMultimodale Indizierung aktivieren
multimodal.modalitiesstring[]["image"], ["audio"] oder ["all"]
multimodal.maxFileBytesnumber10000000Maximale Dateigröße für die Indizierung
Gilt nur für Dateien in extraPaths. Standard-Speicher-Roots bleiben nur für Markdown. Erfordert gemini-embedding-2-preview. fallback muss "none" sein. Unterstützte Formate: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (Bilder); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (Audio).

Embedding-Cache

SchlüsselTypStandardBeschreibung
cache.enabledbooleanfalseChunk-Embeddings in SQLite cachen
cache.maxEntriesnumber50000Maximale Anzahl gecachter Embeddings
Verhindert das erneute Erzeugen von Embeddings für unveränderten Text bei Neuindizierung oder Transkript-Updates.

Batch-Indizierung

SchlüsselTypStandardBeschreibung
remote.batch.enabledbooleanfalseBatch-Embedding-API aktivieren
remote.batch.concurrencynumber2Parallele Batch-Jobs
remote.batch.waitbooleantrueAuf Abschluss des Batch warten
remote.batch.pollIntervalMsnumberPolling-Intervall
remote.batch.timeoutMinutesnumberBatch-Timeout
Verfügbar für openai, gemini und voyage. OpenAI-Batches sind in der Regel am schnellsten und günstigsten für große Backfills.

Sitzungs-Speichersuche (experimentell)

Indizieren Sie Sitzungs-Transkripte und stellen Sie sie über memory_search bereit:
SchlüsselTypStandardBeschreibung
experimental.sessionMemorybooleanfalseSitzungsindizierung aktivieren
sourcesstring[]["memory"]"sessions" hinzufügen, um Transkripte einzubeziehen
sync.sessions.deltaBytesnumber100000Byte-Schwelle für Neuindizierung
sync.sessions.deltaMessagesnumber50Nachrichten-Schwelle für Neuindizierung
Die Sitzungsindizierung ist Opt-in und läuft asynchron. Ergebnisse können leicht veraltet sein. Sitzungslogs liegen auf dem Datenträger, daher sollte der Dateisystemzugriff als Vertrauensgrenze betrachtet werden.

SQLite-Vektorbeschleunigung (sqlite-vec)

SchlüsselTypStandardBeschreibung
store.vector.enabledbooleantruesqlite-vec für Vektorabfragen verwenden
store.vector.extensionPathstringgebündeltPfad zu sqlite-vec überschreiben
Wenn sqlite-vec nicht verfügbar ist, fällt OpenClaw automatisch auf In-Process-Kosinus- Ähnlichkeit zurück.

Indexspeicherung

SchlüsselTypStandardBeschreibung
store.pathstring~/.openclaw/memory/{agentId}.sqliteSpeicherort des Index (unterstützt Token {agentId})
store.fts.tokenizerstringunicode61FTS5-Tokenizer (unicode61 oder trigram)

Konfiguration des QMD-Backends

Setzen Sie memory.backend = "qmd", um es zu aktivieren. Alle QMD-Einstellungen befinden sich unter memory.qmd:
SchlüsselTypStandardBeschreibung
commandstringqmdPfad zur QMD-Executable
searchModestringsearchSuchbefehl: search, vsearch, query
includeDefaultMemorybooleantrueMEMORY.md + memory/**/*.md automatisch indizieren
paths[]arrayZusätzliche Pfade: { name, path, pattern? }
sessions.enabledbooleanfalseSitzungs-Transkripte indizieren
sessions.retentionDaysnumberAufbewahrung von Transkripten
sessions.exportDirstringExportverzeichnis
OpenClaw bevorzugt die aktuellen QMD-Collection- und MCP-Abfrageformen, hält aber ältere QMD-Releases funktionsfähig, indem bei Bedarf auf veraltete --mask-Collection-Flags und ältere MCP-Tool-Namen zurückgefallen wird. QMD-Modell-Overrides bleiben auf der QMD-Seite, nicht in der OpenClaw-Konfiguration. Wenn Sie QMD-Modelle global überschreiben müssen, setzen Sie Umgebungsvariablen wie QMD_EMBED_MODEL, QMD_RERANK_MODEL und QMD_GENERATE_MODEL in der Gateway- Laufzeitumgebung.

Update-Zeitplan

SchlüsselTypStandardBeschreibung
update.intervalstring5mAktualisierungsintervall
update.debounceMsnumber15000Entprellung für Dateiveränderungen
update.onBootbooleantrueBeim Start aktualisieren
update.waitForBootSyncbooleanfalseStart blockieren, bis Aktualisierung abgeschlossen ist
update.embedIntervalstringSeparate Embedding-Taktung
update.commandTimeoutMsnumberTimeout für QMD-Befehle
update.updateTimeoutMsnumberTimeout für QMD-Update-Vorgänge
update.embedTimeoutMsnumberTimeout für QMD-Embedding-Vorgänge

Limits

SchlüsselTypStandardBeschreibung
limits.maxResultsnumber6Maximale Suchergebnisse
limits.maxSnippetCharsnumberSnippet-Länge begrenzen
limits.maxInjectedCharsnumberInsgesamt eingefügte Zeichen begrenzen
limits.timeoutMsnumber4000Such-Timeout

Geltungsbereich

Steuert, welche Sitzungen QMD-Suchergebnisse erhalten können. Gleiches Schema wie session.sendPolicy:
{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}
Der mitgelieferte Standard erlaubt direkte Sitzungen und Kanalsitzungen, verweigert aber weiterhin Gruppen. Standard ist nur DM. match.keyPrefix vergleicht mit dem normalisierten Sitzungsschlüssel; match.rawKeyPrefix mit dem rohen Schlüssel einschließlich agent:<id>:.

Zitate

memory.citations gilt für alle Backends:
WertVerhalten
auto (Standard)Source: <path#line>-Fußzeile in Snippets einfügen
onFußzeile immer einfügen
offFußzeile weglassen (Pfad wird intern weiterhin an den Agenten übergeben)

Vollständiges QMD-Beispiel

{
  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 (experimentell)

Dreaming wird unter plugins.entries.memory-core.config.dreaming konfiguriert, nicht unter agents.defaults.memorySearch. Dreaming läuft als ein geplanter Sweep und verwendet interne Light-/Deep-/REM-Phasen als Implementierungsdetail. Für konzeptionelles Verhalten und Slash-Befehle siehe Dreaming.

Benutzereinstellungen

SchlüsselTypStandardBeschreibung
enabledbooleanfalseDreaming vollständig aktivieren oder deaktivieren
frequencystring0 3 * * *Optionaler Cron-Takt für den vollständigen Dreaming-Sweep

Beispiel

{
  plugins: {
    entries: {
      "memory-core": {
        config: {
          dreaming: {
            enabled: true,
            frequency: "0 3 * * *",
          },
        },
      },
    },
  },
}
Hinweise:
  • Dreaming schreibt Maschinenstatus nach memory/.dreams/.
  • Dreaming schreibt menschenlesbare narrative Ausgabe nach DREAMS.md (oder in eine vorhandene dreams.md).
  • Die Richtlinien und Schwellenwerte für Light-/Deep-/REM-Phasen sind internes Verhalten, keine benutzerseitige Konfiguration.