--- name: sessions-memory description: OpenClaw Memory-System für persistente Speicherung von Sitzungen und Erinnerungen. Verwende memory_search und memory_get Tools für semantische Suche und gezieltes Lesen von Markdown-Speicherdateien. Nutze automatische Speicherspülung vor Verdichtung und konfiguriere Vektorspeichersuche für optimale Ergebnisse. --- # Sitzungen und Erinnerung ## Überblick Das OpenClaw-Speichersystem verwendet Markdown-Dateien im Agenten-Arbeitsbereich als Quelle der Wahrheit. Das Modell "erinnert sich" nur an das, was auf die Festplatte geschrieben wird. ## Speicherdateien (Markdown) ### Standard-Layout ``` memory/YYYY-MM-DD.md # Tägliches Protokoll (nur für Apps) MEMORY.md # Kuratiertes Langzeitgedächtnis (optional) ``` **Wichtige Regeln:** - `memory/YYYY-MM-DD.md`: Tägliches Protokoll, wird heute + gestern zu Beginn der Sitzung gelesen - `MEMORY.md`: Nur in der privaten Hauptsitzung laden (niemals in Gruppenkontexten) - Dateien befinden sich unter dem Arbeitsbereich (`agents.defaults.workspace`, default: `~/.openclaw/workspace`) ## Speicherwerkzeuge ### memory_search Semantischer Rückruf über indizierte Snippets. Gibt zurück: - Snippet-Text (~700 Zeichen gecappt) - Dateipfad - Zeilenbereich - Score - Provider/Modell - Fallback-Status (local → remote) ### memory_get Gezieltes Lesen einer bestimmten Markdown-Datei nach Pfad (optional: Startzeile + N Zeilen). **Wichtig:** `memory_get` degradiert gracefully wenn eine Datei nicht existiert (z.B. heutiges Tagesprotokoll vor dem ersten Schreiben). Gibt `{ text: "", path }` zurück statt Fehler zu werfen. ## Wann Speicher schreiben? | Typ | Ziel-Datei | Verwendung | |-----|------------|------------| | Entscheidungen, Präferenzen, dauerhafte Fakten | `MEMORY.md` | Langzeitgedächtnis | | Tagesnotizen, laufender Kontext | `memory/YYYY-MM-DD.md` | Tägliches Protokoll | | "Erinnern Sie sich daran" | Entsprechende Datei | Sofort aufschreiben | **Regel:** Wenn jemand sagt "Erinnern Sie sich daran", schreiben Sie es auf (nicht nur im RAM behalten). ## Automatische Speicherspülung Vor der automatischen Verdichtung wird eine stille, agentische Runde ausgelöst, die das Modell daran erinnert, dauerhafte Erinnerungen zu speichern. **Konfiguration:** ```json { "agents": { "defaults": { "compaction": { "reserveTokensFloor": 20000, "memoryFlush": { "enabled": true, "softThresholdTokens": 4000, "systemPrompt": "Session nearing compaction. Store durable memories now.", "prompt": "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store." } } } } } ``` **Details:** - Soft-Schwellenwert: Flush wird ausgelöst bei `contextWindow - reserveTokensFloor - softThresholdTokens` - Standardmäßig stumm: Prompts enthalten `NO_REPLY` damit nichts geliefert wird - Eine Spülung pro Verdichtungszyklus (verfolgt in `sessions.json`) - Workspace muss beschreibbar sein (bei `workspaceAccess: "ro"` oder `"none"` wird Flush übersprungen) ## Vektorspeichersuche ### Standardwerte - Standardmäßig aktiviert - Überwacht Speicherdateien auf Änderungen (debounced) - Konfiguration unter `agents.defaults.memorySearch` (nicht top-level) ### Provider-Auswahl (Auto) Wenn `memorySearch.provider` nicht gesetzt ist, wählt OpenClaw automatisch: 1. `local` wenn `memorySearch.local.modelPath` konfiguriert und Datei existiert 2. `openai` wenn OpenAI-Schlüssel aufgelöst werden kann 3. `gemini` wenn Gemini-Schlüssel aufgelöst werden kann 4. `voyage` wenn Voyage-Schlüssel aufgelöst werden kann 5. `mistral` wenn Mistral-Schlüssel aufgelöst werden kann 6. Andernfalls bleibt Speichersuche deaktiviert ### Remote Embeddings Erfordern API-Schlüssel für den Embedding-Provider. OpenClaw löst Schlüssel auf von: - Auth-Profiles - `models.providers.*.apiKey` - Umgebungsvariablen **Hinweis:** Codex OAuth deckt nur Chat/Completions ab, nicht Embeddings für Speichersuche. ### Lokaler Modus - Setze `memorySearch.provider = "local"` - Stelle `memorySearch.local.modelPath` bereit (GGUF oder `hf:` URI) - Verwendet `node-llama-cpp` (erfordert möglicherweise `pnpm approve-builds`) - Standardmodell: `hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 GB) - Auto-Download wenn GGUF fehlt ## Hybridsuche (BM25 + Vektor) Kombiniert: - **Vektorähnlichkeit:** Semantische Übereinstimmung (Formulierung kann abweichen) - **BM25-Schlüsselwort-Relevanz:** Exakte Token (IDs, env vars, Codesymbole) **Warum Hybrid?** - Vektorsuche: Stark bei "das bedeutet dasselbe" - BM25: Stark bei exakten Token, schwächer bei Paraphrasen - Hybrid: Pragmatischer Mittelweg für beide Abrufsignale **Konfiguration:** ```json { "agents": { "defaults": { "memorySearch": { "query": { "hybrid": { "enabled": true, "vectorWeight": 0.7, "textWeight": 0.3, "candidateMultiplier": 4 } } } } } } ``` ## Post-Processing-Pipeline ### MMR-Reranking (Vielfalt) Reduziert redundante oder sich überschneidende Ergebnisse. **Konfiguration:** ```json { "memorySearch": { "query": { "hybrid": { "mmr": { "enabled": true, "lambda": 0.7 // 0 = max diversity, 1 = max relevance } } } } } ``` **Wann aktivieren:** Wenn `memory_search` redundante oder Near-Duplikat-Snippets zurückgibt. ### Zeitlicher Verfall (Rezitätsschub) Boostet neuere Erinnerungen, lässt alte verblassen. **Konfiguration:** ```json { "memorySearch": { "query": { "hybrid": { "temporalDecay": { "enabled": true, "halfLifeDays": 30 // Score halbiert sich alle 30 Tage } } } } } ``` **Evergreen-Dateien:** `MEMORY.md` und nicht-datierte Dateien in `memory/` verfallen nie. **Wann aktivieren:** Wenn Agent monatelange tägliche Notizen hat und alte Informationen den aktuellen Kontext übertreffen. ## QMD-Backend (experimentell) Setze `memory.backend = "qmd"` für lokale Suche mit BM25 + Vektoren + Reranking. **Voraussetzungen:** - QMD CLI separat installieren (`bun install -g https://github.com/tobi/qmd`) - SQLite mit Extensions-Unterstützung (`brew install sqlite` auf macOS) - Läuft vollständig lokal via Bun + node-llama-cpp **Konfiguration:** ```json { "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" } } ] } } } } ``` ## Zusätzliche Speicherpfade Für Markdown-Dateien außerhalb des Standard-Layouts: ```json { "agents": { "defaults": { "memorySearch": { "extraPaths": ["../team-docs", "/srv/shared-notes/overview.md"] } } } } ``` **Hinweise:** - Pfade können absolut oder arbeitsraumrelativ sein - Verzeichnisse werden rekursiv auf `.md`-Dateien gescannt - Nur Markdown-Dateien werden indiziert - Symlinks werden ignoriert ## Embedding-Cache Zwischenspeichern von Chunk-Einbettungen in SQLite: ```json { "agents": { "defaults": { "memorySearch": { "cache": { "enabled": true, "maxEntries": 50000 } } } } } ``` ## Sitzungsspeichersuche (experimentell) Opt-in Indizierung von Sitzungstranskripten: ```json { "agents": { "defaults": { "memorySearch": { "experimental": { "sessionMemory": true }, "sources": ["memory", "sessions"] } } } } ``` **Hinweise:** - Opt-in (standardmäßig ausgeschaltet) - Sitzungsaktualisierungen werden entwertet und asynchron indiziert - `memory_search` blockiert nie bei Indizierung - Ergebnisse können etwas veraltet sein bis Hintergrundsynchronisation abgeschlossen ist - Pro Agent isoliert ## SQLite-Vektorbeschleunigung (sqlite-vec) Wenn verfügbar, speichert OpenClaw Embeddings in einer SQLite Virtual Table (`vec0`): ```json { "agents": { "defaults": { "memorySearch": { "store": { "vector": { "enabled": true, "extensionPath": "/path/to/sqlite-vec" } } } } } } ``` **Hinweise:** - Standardmäßig `enabled: true` - Wenn sqlite-vec fehlt, fällt auf JS-Fallback zurück (kein harter Fehler) ## Zitate & Fallback - `memory.citations`: Gilt unabhängig vom Backend (`auto`/`on`/`off`) - Wenn QMD läuft: `status().backend = "qmd"` für Diagnose - Bei QMD-Fehler: Fallback auf Built-in Provider ## Batch-Indexierung Für große Auffüllungen mit OpenAI, Gemini oder Voyage: ```json { "agents": { "defaults": { "memorySearch": { "provider": "openai", "model": "text-embedding-3-small", "remote": { "batch": { "enabled": true, "concurrency": 2 } } } } } } ``` **Warum OpenAI Batch schnell + billig ist:** - Viele Embedding-Anfragen in einem Batch-Job - OpenAI verarbeitet asynchron - Ermäßigte Preise für Batch-API-Workloads ## Was wird indiziert? - **Dateityp:** Nur Markdown (`MEMORY.md`, `memory/**/*.md`) - **Index-Speicher:** Pro-Agent SQLite bei `~/.openclaw/memory/.sqlite` - **Freshness:** Watcher auf `MEMORY.md` + `memory/` markiert Index als dirty (debounce 1.5s) - **Sync:** Geplant bei Sitzungsstart, bei Suche oder in Intervallen, läuft asynchron - **Reindex-Trigger:** Automatischer Reset wenn Embedding-Provider/Modell/Endpoint-Fingerprint/Chunking-Params sich ändern ## Werkzeuge-Zusammenfassung | Tool | Funktion | Rückgabe | |------|----------|----------| | `memory_search` | Semantische Suche über indizierte Snippets | Snippets mit Pfad, Zeilenbereich, Score | | `memory_get` | Gezieltes Lesen einer Speicherdatei | Dateiinhalt (oder `{ text: "", path }` wenn nicht existent) | **Beide Tools sind nur aktiviert wenn `memorySearch.enabled` für den Agenten `true` ist.** ## Referenz Für vollständige Details siehe [MEMORY_REFERENCE.md](MEMORY_REFERENCE.md)