Voice

Memory Cdc

Name: Memory Cdc
Rating: 3.5 (1 reviews)
Author: marcdshark

By marcdshark 👁 5 views ▲ 0 votes

An OpenClaw plugin that turns agent memory into an event stream. When one agent learns something, every other agent that cares finds out automatically.

GitHub

Install

npm install
pnpm

Configuration 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