knowledge-base/wiki/architecture/memory-system.md

---
created: 2026-06-16
updated: 2026-06-16
sources: [other/2026-06-16_openclaw-releases-v2026.6.8.md]
tags: [architecture, memory, knowledge-base]
---

# Memory System Architecture

> Migriert aus ByteRover context-tree (April 2026)

## Schichten-Modell (4 Layer)

| Layer | Name | Status |
|-------|------|--------|
| **S1** | Flat-File (MEMORY.md + `memory/*.md`) mit Tags | ✅ Aktiv |
| **S1.5** | KNOWLEDGE.md — kuratierte Langzeit-Memos | ⚠️ Geplant, nie implementiert |
| **S2** | OpenClaw built-in Memory (Voyage voyage-3-lite) | ✅ Aktiv |
| **S3** | LanceDB Vector Store | ❌ Entfernt (2026-04-06) |

### Tag-System (S1)

Vier Tags strukturieren die Flat-File-Erinnerungen:

- `[PREF]` — Präferenzen (z.B. Prefer functional over OOP)
- `[FACT]` — Fakten (z.B. We use PostgreSQL 15)
- `[DECISION]` — Architekturentscheidungen (z.B. Chose ByteRover over LanceDB)
- `[ENTITY]` — Personen/Systeme (z.B. Hector is the bot identity)

## Evolution

1. **Phase 1:** Flat-Files mit Tags — funktional bis heute
2. **Phase 1.5:** KNOWLEDGE.md geplant, nie gebaut
3. **LanceDB-Versuch:** 3 Container-Resets → Datenverlust → entfernt
4. **ByteRover (brv):** Semantic Layer mit Voyage Embeddings → Query funktioniert, Curate blockiert durch OAuth-Token-Verlust bei Container-Reset

Siehe auch: `decisions/2026-04-volume-persistence.md`

## Update 2026-06-16: OpenClaw v2026.6.8 Memory + State Recoveries

Mit [v2026.6.8](https://github.com/openclaw/openclaw/releases/tag/v2026.6.8) (und
z.T. v2026.6.7) hat OpenClaw mehrere Memory-relevante Fixes geliefert, die unsere
S2-Schicht direkt betreffen:

### QMD Memory Search: stabilisiert in transient mode

**QMD** (Queryable Memory Database) ist die JSON-basierte In-Memory-Suchschicht
innerhalb von OpenClaws S2. Vorher konnte QMD in **transient mode** (z.B. während
eines Reindex) komplett ausfallen — der Indexer stoppte und Fallbacks schlugen
ebenfalls fehl, was zu "Memory temporarily unavailable"-Fehlern führte.

**Jetzt (v2026.6.7 + v2026.6.8):** QMD bleibt im transient mode **verfügbar**,
Startup-Failures werden zusätzlich zu den Fallback-Errors reported, sodass die
Fail-Recovery-Kette sichtbar wird.

**Implikation für uns:** Weniger Memory-Outages während intensiver Subagent-
Spawns. **Kein Action-Item**, nur Benefit.

### SQLite vermeidet WAL auf NFS State Volumes

Wenn unser State-Volume ein NFS-Mount ist (was in containerisierten Setups
häufig vorkommt), hat SQLite mit WAL-Mode (Write-Ahead Log) Performance-
und Locking-Probleme. OpenClaw v2026.6.8 detektiert NFS-Volumes und
**deaktiviert WAL automatisch** in diesem Fall.

**Implikation für uns:** Unser `bot-hector`-Container läuft mit lokalem
Volume (`/home/node/workspace`), kein NFS. **Kein Action-Item**, aber gut
zu wissen für mögliche Cloud-Migrationen.

### Oversized OpenAI embedding batches: jetzt split vor 431s

Vorher konnte ein Embedding-Request an OpenAI mit einem 431-Status
("Request Header Fields Too Large") fehlschlagen, wenn der Batch zu groß
wurde. OpenClaw v2026.6.8 splittet solche Batches **automatisch vor dem
Send** und rekonstruiert das Ergebnis.

**Implikation für uns:** Wir nutzen S2 (Voyage Embeddings), nicht OpenAI
Embeddings — daher kein direkter Impact. Falls wir jemals auf OpenAI-
Embeddings umstellen, ist die Resilience eingebaut.

### Raw Memory Wiki source pages: explizit als Source Evidence

**Wichtig für unser Wiki-Pattern:** OpenClaw behandelt **raw Memory Wiki
source pages** (also Wiki-Pages, die als Quelle in anderen Wiki-Pages
referenziert werden) jetzt explizit als **source evidence** und
indexiert sie korrekt. Vorher wurden sie manchmal als "malformed" markiert
und von der Suche ausgeschlossen.

**Implikation für uns:** Genau das `raw/ → wiki/`-Pattern, das wir im
RamaDama-Knowledge-Base praktizieren, ist damit nativ von OpenClaw
unterstützt. Siehe [[concepts/llm/llm-knowledge-base.md]] für die
konzeptionelle Grundlage.

### Stuck-Session Recovery: Warning-Backoff wird nicht mehr resettet

Vorher konnte die Recovery-Scheduling-Warteschlange ihren Warning-Backoff
bei jedem Recovery-Trigger zurücksetzen, was zu "thundering herd"-Problemen
führte. Jetzt bleibt der Backoff erhalten, was die Recovery gleichmäßiger
verteilt.

**Implikation für uns:** Kein direkter Impact auf unseren Workflow, aber
verbessert die Stabilität bei vielen parallelen Sessions.

### Full Memory Reindexes: Rollback/Cache Recovery preserved

Bei einem vollen Memory-Reindex gehen jetzt die **Rollback-Punkte** und
**Cache-Snapshots** nicht mehr verloren. Falls der Reindex mittendrin
fehlschlägt, kann auf den letzten konsistenten Stand zurückgerollt werden
ohne Datenverlust.

**Implikation für uns:** Massiv relevant für den **WMT-003-Wiki-Lint-Workflow** —
bei größeren Wiki-Cleanups (Stubs auflösen, Cross-Refs nachziehen) machen
wir effektiv einen S2-Reindex. Mit v2026.6.8 ist dieser Prozess deutlich
robuster.

## Verwandte externe Ressourcen

- OpenClaw S2 (built-in Memory): siehe [OpenClaw Repository](https://github.com/openclaw/openclaw) und [Releases v2026.6.8](https://github.com/openclaw/openclaw/releases/tag/v2026.6.8) (S2-Konzept im Memory-Block dokumentiert)
- QMD-Konzept: Queryable Memory Database (JSON-basiert, transient + persistent mode)
- [Raw Memory Wiki source pages support in v2026.6.8](https://github.com/openclaw/openclaw/releases/tag/v2026.6.8)