Architecture
The services that make up MemClaw, what each one is responsible for, and how a write flows from client through core-api, the event bus, the worker, and storage.
Three services, one event bus, Postgres + pgvector underneath. Synchronous on the response path, async on the heavy work.
How a write flows through MemClaw
Three services, one event bus. Synchronous on the response path, async on the heavy work.
core-api
FastAPI service. Handles HTTP and MCP requests — the MCP server is mounted at /mcp on the same app, so a single deployment serves both surfaces. It applies auth and quotas, writes raw memories, and serves recall reads. After a successful write, core-api publishes embed-requested / enrich-requested events to the event bus for the worker to pick up. Contradiction detection runs post-commit, fire-and-forget via an async track_task (see services/contradiction_detector.py's detect_contradictions_async) — the write itself does not block on it.
core-worker
Async worker. Subscribes to embed-requested and enrich-requested events on the event bus (in-process for OSS single-process; Pub/Sub on the enterprise platform). Calls the configured embedding + entity-extraction providers, then writes the structured rows back through core-storage-api.
core-storage-api
Thin Postgres gateway used by both core-api and core-worker for memory CRUD and pgvector ops. Two-worker default; bulk operations cap at ~60 req/s — bump to 8 workers via an override before backfills.
Event bus
OSS default is an in-process bus; the enterprise / managed deployment uses Google Pub/Sub. The /api/v1/health route's event_bus field reports the current backend's status.
OpenClaw plugin (optional)
Lives inside an OpenClaw gateway and claims the memory slot, replacing memory-core and exposing the memclaw_* tools to every agent that runs through the gateway. See OpenClaw integration.