Voice
Memory Cdc
By An OpenClaw plugin that turns agent memory into an event stream. When one agent learns something, every other agent that cares finds out automatically.
Install
npm install
pnpmConfiguration Example
// Hub machine
{ "mode": "hub", "port": 4222 }
// Leaf machine
{ "mode": "leaf", "hub": "nats://hub.tailscale:4222" }README
# openclaw-memory-cdc
An OpenClaw plugin that turns agent memory into an event stream. When one agent learns something, every other agent that cares finds out automatically. No polling, no cron jobs, no external databases. Just NATS and hooks.
## How It Works
```
Agent A learns something → writes to memory → plugin diffs the change
→ publishes to NATS → Agent B gets a message → plugin injects sync
→ Agent B sees the update in its daily log
```
Two publishing triggers:
- **`session:compact:after`** — high-signal: fires after the agent distills its most important learnings
- **`message:sent`** — lightweight: fires on explicit "remember this" writes (mtime check, usually a no-op)
One subscribing trigger:
- **`message:received`** — drains pending events into today's daily log before the agent processes anything
Agents self-configure their subscriptions via the `MEMORY_CDC` skill. No human configuration needed.
## Architecture
```
┌──────────────────────────────────────────────────┐
│ OpenClaw Gateway │
│ │
│ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │Agent A │ │Agent B │ │Agent C │ │
│ └───┬────┘ └───┬────┘ └───┬────┘ │
│ │ │ │ │
│ ┌───▼────────────▼────────────▼──────┐ │
│ │ Memory CDC Plugin │ │
│ │ Hooks Tools Publisher Sub │ │
│ └──────────────────┬─────────────────┘ │
│ │ │
│ ┌──────────────────▼─────────────────┐ │
│ │ Embedded NATS Server │ │
│ │ PubSub ◄──► JetStream │ │
│ │ Stream: SWARM_MEMORY │ │
│ └────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘
```
For multi-machine setups, NATS leaf nodes transparently bridge events across machines with zero code changes.
## Prerequisites
- Node.js >= 18
- OpenClaw Gateway
## Installation
```bash
openclaw plugins install clawhub:openclaw-memory-cdc
openclaw config set plugins.entries.openclaw-memory-cdc.enabled true
openclaw gateway restart
```
Optional remote config:
```json
// Hub machine
{ "mode": "hub", "port": 4222 }
// Leaf machine
{ "mode": "leaf", "hub": "nats://hub.tailscale:4222" }
```
## Project Structure
```
├── openclaw.plugin.json # Plugin manifest
├── src/
│ ├── index.ts # Plugin entry (definePluginEntry)
│ ├── config.ts # Config types
│ ├── nats/ # NATS server, client, JetStream
│ ├── publisher/ # Differ, formatter, batcher
│ ├── subscriber/ # Drain, dedup, injector
│ └── tools/ # 5 agent-facing CDC tools
├── tests/ # Vitest tests (mirrors src/)
├── skills/
│ └── MEMORY_CDC/ # Agent self-configuration skill
└── docs/
├── specs/ # Module design specs
└── concepts/ # Cross-cutting concepts
```
## Development
```bash
pnpm install
pnpm build # TypeScript compilation
pnpm test # Run Vitest
pnpm test:coverage # Coverage report
pnpm lint # ESLint
pnpm format # Prettier
```
## Documentation
Design specs and architectural concepts live in `docs/`:
- `docs/specs/` — one file per source module (nats, publisher, subscriber, tools, config)
- `docs/concepts/` — cross-cutting topics (topology, data flow, self-config, safety)
## License
ISC
voice
Comments
Sign in to leave a comment