Architectuurwiki

ClawMem als lokale geheugenlaag voor OpenClaw

Een visuele toelichting op de geïmplementeerde oplossing: twee duurzame geheugenplanes, expliciete sessie-ankers, cross-channel operation threads en een lokale MCP/CLI interface.

Bekijk de opbouw Herimplementatiegids
2

Duurzame planes

5

Architectuurlagen

15

MCP-tools

1

Lokale embedded runtime

01

Doel en oplossingsvorm

ClawMem is geen algemene knowledge base voor een hele machine, maar een lokale geheugenlaag die OpenClaw voorspelbaar toegang geeft tot projectcontext, toolingkennis en geselecteerde sessiehistorie.

Wat het oplost

  • Scheiding tussen projectspecifieke en globale kennis
  • Deterministische routering zonder LLM-afhankelijkheid
  • Expliciete bookmarks naar waardevolle sessiemomenten
  • Cross-channel operationele opvolging

Wat het bewust niet doet

  • Geen volledige code-indexering
  • Geen automatische transcript-mining
  • Geen remote of multi-tenant runtime
  • Geen vrije filesystem-tools via MCP

Technische houding

  • Lokaal en embedded
  • Kleine, uitlegbare datamodellen
  • JSON-payloads in relationele tabellen
  • CLI en MCP boven dezelfde service-laag
02

Geheugenmodel

De oplossing rust op twee duurzame planes, plus twee expliciete geheugenconstructies erbovenop.

Project plane

Projectspecifieke context, conventies, docs, notes en runbooks.

Tooling plane

Werkstation-, OpenClaw-, shell- en operatorkennis die niet in projectgeheugen hoort.

Flash memory

Expliciet sessie-anker binnen project of tooling, met snapshot van het excerpt.

Operation threads

Cross-channel container voor één operationeel onderwerp met events en gelinkte flashes.

03

Logische architectuurlagen

Een functioneel gelijke oplossing hoeft niet dezelfde code te hebben, maar wel dezelfde grenzen.

1

Configuratie

JSON-config met `projects`, `watchRoots`, `environmentSources`, router-drempels en retrievalgewichten.

2

Ingestie

Bestanden worden geselecteerd op extensie, ignore-rules en diepte. Daarna ontstaan documenten, chunks, entities en edges.

3

Persistente opslag

PGlite bewaart plane-data, flash memories, operation threads en importjobs. Plane-data wordt per import vervangen; expliciete memory-objecten blijven bestaan.

4

Retrieval en geheugenoperaties

De service bouwt snapshots in memory, routeert queries, scoort chunks en beheert flash/thread-logica.

5

CLI en MCP

Beide interfaces zijn dunne adapters boven `ClawMemService` en delen dezelfde contracten.

04

Dataflow van bron naar context

De onderstaande stroom beschrijft hoe tekstbestanden uiteindelijk een OpenClaw-contextbundle worden.

Bronbestanden
→
Ingestie
→
Documents / Chunks
Entities / Edges
→
PGlite
→
Snapshot in memory
Router
→
Hybrid scoring
→
Contextbundle / Searchresultaat

Chunking en extractie

  • Headings bepalen sectiegrenzen
  • Tags en links worden apart geëxtraheerd
  • Tooling-documenten krijgen extra tool/mcp/command entities
  • Deterministische embeddings worden lokaal berekend

Scoringscomponenten

  • Lexicale overlap
  • Vectorovereenkomst
  • Graph-degree benadering
  • Recency, source-priority en structural weight
05

Flash memory

Flash memory is de expliciete koppeling tussen OpenClaw sessiehistorie en duurzaam geheugen. De implementatie is ontworpen voor herleidbaarheid én degradatiebestendigheid.

Opslaggedrag

  • Resolutie via `sessionId` of `sessionKey`
  • Strikte validatie van toegestane transcriptdirectories
  • Canonieke regelrange uit message ids of line numbers
  • Persistente snapshot van `excerptEntries` bij creatie

Expand-semantiek

  • `live_session`: excerpt uit huidige transcriptlog
  • `snapshot`: fallback uit opgeslagen snapshot
  • Zo blijft een bookmark bruikbaar als OpenClaw logs roteert of verwijdert
06

Operation threads

Threads modelleren één operationeel onderwerp over meerdere kanalen heen. Ze zijn complementair aan flash memories: de thread bewaart de lijn, de flash bewaart het exacte fragment.

Thread

Status, tags, channels, outcome, activity timestamps

Signal event

Melding of vraag

TUI event

Analyse of fix

Cron event

Verificatie of follow-up

Flash memory

Exact gesprekssnippet gelinkt aan de thread

07

Externe interfaces

De oplossing heeft twee operatorinterfaces: CLI en MCP. De onderliggende businesslogica is identiek.

clawmem import
clawmem query
clawmem suggest-context
clawmem flash-create
clawmem flash-expand
clawmem thread-create
clawmem thread-summary
clawmem mcp
clawmem_suggest_context
clawmem_search
clawmem_context
clawmem_flash_create
clawmem_flash_preview
clawmem_flash_expand
clawmem_thread_create
clawmem_thread_add_event
clawmem_thread_summary
08

Beveiligingsgrenzen

De belangrijkste ontwerpkwaliteit is grensbewaking: welke inputs en files mogen wel of niet worden gelezen.

Sessies

Alleen `.jsonl` transcripts onder toegestane OpenClaw sessiedirectories zijn geldig.

MCP-oppervlak

Geen vrije file paths of admin-tools; alleen expliciete, smalle toolcontracten.

Plane-scheiding

Tooling-sources mogen projectroots niet impliciet opslokken; selectie blijft expliciet.

09

Wat een volgende Codex-sessie minimaal moet behouden

Dit is de checklist voor een functioneel gelijke herimplementatie, zelfs als de code anders wordt.

1

Twee duurzame planes: `project` en `tooling`.

2

Deterministische routering op aliases, keywords, cwd en tooling tokens.

3

Plane-data als vervangbare importsnapshots, expliciete memory-objecten apart.

4

Document → chunk → entity/edge ingestie voor tekstbestanden.

5

Hybride retrieval met lexical, vector, graph, recency en structurele signalen.

6

Flash memories met exact sessie-anker én opgeslagen excerpt snapshot.

7

Operation threads voor cross-channel continuïteit.

8

CLI en MCP boven één service-laag, niet twee verschillende implementaties.

9

Strikte session-file validatie tot OpenClaw transcriptdirectories.

10

Debounced single-flight watchers voor incremental sync.