OpenWave

OPEN SOURCE / OPENCLAW

Autonomic long-term memory for OpenClaw agents. Pulls the right memories into every turn before the model sees the prompt. Runs the sleep system — slow-wave/REM consolidation, awake replay, LLM fact extraction — in-process. The engine is sharpwave-core, bundled at build time. Free, MIT, open source.

openclaw plugins install clawhub:openwave --accept-capabilities

Autonomic Wake In-Process Sleep Zero Amnesia Multi-Agent No Child Process

Star on GitHub See SharpWave (MCP) →

Wake up already knowing. Memory is there before the first turn. Sleep runs on its own schedule.

Why a plugin instead of an MCP server?

SharpWave works great as a standalone MCP server for Claude Code, Cursor, Claude Desktop, and any other MCP client. But OpenClaw agents are different — they run continuously, they wake up autonomously, they sleep and consolidate. An MCP child process is structurally a tool the agent has to remember to call. OpenClaw agents don't call tools to remember — they wake up already knowing.

OpenWave is the same engine, but it lives inside the agent process. Memory is there before the first prompt. Sleep runs without scheduling it. Wake-up injections don't have to cross a process boundary, and the database sits in your agent's own data dir — not behind a socket you have to keep alive.

Full persistence. Same engine. Different surface.

What it adds over the MCP server

Autonomic wake-up

Before every turn, every heartbeat, and every compaction, OpenWave pulls the memories relevant to what the agent is about to do and injects them into context. Identity and goals ride in as a never-compacted system header. Query-relevant recall, always-on operational rules, and a last-24h activity digest ride in as prepended context. No tool call. The agent never has to remember to look.

In-process sleep

Consolidation runs inside the agent's process on timers — slow-wave and REM pass, awake replay, LLM fact extraction. No scheduling overhead. No separate service to keep alive. Patterns promote into semantic nodes; noise gets pruned.

Full persistence

The database is on disk in your agent's own data dir (~/.sharpwave/<agentId>/brain.db). No external service to crash, no MCP round-trip to time out. Memory is always there.

Same engine, two surfaces

The retrieval, consolidation, FSRS decay, graph edges — all of it is the exact same sharpwave-core code that ships in the standalone npx -y sharpwave MCP server. Bundled at build time, so each surface always ships the engine it was built against.

Multi-agent by design

One OpenWave process serves any number of agents. Each agent's brain lives in its own SQLite file — isolated, never cross-contaminated — listed in config.agents. Add an agent, add its id to the list. That's it.

OpenClaw native

Drop-in plugin. Loads with OpenClaw's standard plugin system on startup ("activation": { "onStartup": true }). Hooks before_prompt_build, agent_turn_prepare, llm_output, agent_end — the lifecycle surface OpenClaw exposes for memory.

Install

OpenWave installs like any OpenClaw plugin. Three options — pick the one that fits how you source your stack.

From ClawHub (recommended)

openclaw plugins install clawhub:openwave --accept-capabilities

From npm

openclaw plugins install npm:openwave --force --accept-capabilities
cd ~/.openclaw/npm/projects/openwave && npm rebuild better-sqlite3

The npm rebuild step is required. OpenClaw's plugin installer runs npm install --ignore-scripts, so better-sqlite3's native binary isn't fetched or built during install. Skip the rebuild and every db.init fails with "Could not locate the bindings file". Re-run it after any openclaw plugins update openwave.

From source (development)

git clone https://github.com/Enlightened-Republic/openwave
cd openwave && npm install && npm run build

Then point plugins.load.paths at the checkout directory (not dist/index.js — OpenClaw reads openclaw.plugin.json next to it):

{
  "plugins": {
    "load": { "paths": ["/abs/path/to/openwave"] }
  }
}

Configure `openclaw.json`

All three install methods converge on the same config block. If you have a plugins.allow allowlist, OpenWave has to be in it.

{
  "plugins": {
    // If plugins.allow is set, openwave MUST be in it (exclusive allowlist).
    "allow": ["...your other plugin ids...", "openwave"],
    "entries": {
      "openwave": {
        "enabled": true,
        "hooks": { "allowConversationAccess": true },
        "config": { "agents": ["main"] }
      }
    }
  }
}

Why each field

hooks.allowConversationAccess: true — required. OpenWave is a non-bundled plugin and its hooks read conversation content. Without this, the hooks return empty and the agent gets no injection.
config.agents — required, no safe default on multi-agent gateways. Every hook and tool call guards on config.agents.includes(agentId). An agent not listed gets no injection, no episode logging, no sleep system. List every agent you want OpenWave to serve.
enabled: true — flips the plugin on. Setting false (or omitting the entry) makes register return immediately: no tools, no hooks.

Restart & confirm

Restart the gateway with a full restart, not a soft reload: openclaw gateway restart.

Confirm from the log — you should see both lines:

[openwave] {"op":"register","outcome":"ok","agents":<N>,"tools":16,...}
[openwave] {"op":"gateway_start","outcome":"ready",...}

Compatibility: pluginApi >= 2026.5.0, minGatewayVersion 2026.5.0. Older gateways don't expose the hook and session-workflow surface OpenWave needs.

What the agent sees at wake-up

OpenWave hooks OpenClaw's turn lifecycle. On every session start, every turn, every heartbeat, and every compaction it pulls the memories relevant to what the agent is about to do out of that agent's brain and injects them into context automatically. The agent wakes up already knowing.

Identity & goals — system header. Rides in as a never-compacted system block. The agent always knows who it is, what it's working on, and what the standing operational rules are.
Query-relevant recall. Per-turn: hybrid FTS + vector + spreading activation across the graph, sized to a token budget (default contextBudget: 2000). Top-K default 10.
Always-on operational rules. Verified patterns, hard rules, and standing intents the agent has encoded into the brain surface in every turn.
Last-24h activity digest. A short log of what happened in the recent past, so the agent knows where it left off.

First-open runs the additive-only schema migration to v17 (adds nodes.inject_count / nodes.inject_hits, backfills 0 — no data loss).

What runs while the agent sleeps

Sleep is in-process, on timers, no scheduling required.

Slow-wave pass. Replays recent episodes and promotes recurring patterns into durable semantic nodes — modelled on hippocampal sharp-wave ripples. Time gate: consolidationTimeGateHours (default 4h). Episode gate: consolidationEpisodeGate (default 10 new episodes).
REM synthesis. Clusters related nodes and synthesises higher-level schemas. Optional generative REM via ingestionModel (default openrouter/deepseek/deepseek-v4-flash); falls through to remModel if set, then to heuristic.
Awake replay. Background replay of recent episodes between consolidation passes — keeps the graph warm without waiting for the next sleep cycle.
LLM fact extraction. Episodes above llmExtractionMinImportance (default 0.4) are queued for extraction into graph nodes when llmExtractionEnabled is on. Off by default; heuristic extractor only when off.
Pruning. Low-value nodes older than pruneAfterDays (default 90) are pruned.

Tools — all 16

OpenWave registers all 16 brain_* tools. Definitions and executors come from sharpwave-core's unified tool module — so OpenWave and the standalone SharpWave MCP server can't expose a drifted schema. (The MCP server publishes a narrower 11-tool subset.)

Most memory work needs no tool call — OpenWave injects and logs automatically. The tools are for deliberate deep recall (brain_query), deliberate writes (brain_write), and introspection.

Tool	What it does
`brain_query`	Hybrid FTS + vector + spreading activation. The core recall call.
`brain_write`	Store a memory node. Auto-queues for embedding and PRISM/NEXUS auto-linking.
`brain_link`	Create a typed edge between two existing nodes.
`brain_supersede`	Replace a stale node with updated content. Keeps graph temporal integrity.
`brain_stats`	Node/edge/episode counts, neuromodulator state, consolidation status, embedding coverage.
`brain_history`	Search raw conversation turns (episodes) by keyword.
`brain_expand`	Full detail for a node: content, FSRS metrics, encoding context, source episodes.
`brain_review`	Apply an FSRS-6 spaced-repetition review. Updates stability, retrievability, SIGMA.
`brain_forget`	Physically delete a node. Refuses if the node has active edges (pass `force=true`).
`brain_edges`	Get all active incoming and outgoing edges for a node.
`brain_reset`	Wipe the brain back to empty. Agent-callable. Guarded: `confirm` must match the agent id; a timestamped `.db` backup is taken first. Never `DROP` — just `DELETE FROM` learned-state tables and re-seed an empty self-model.
`brain_update_self_model`	Update the agent's self-model nodes — identity, goals, operational rules — that ride in as the never-compacted system header.
`brain_reflect`	Run a reflection pass over recent episodes; promote durable patterns into semantic nodes.
`brain_generate_skill`	Generate a draft reusable skill from patterns that have repeated enough times. Output goes to `workspaceSkillsDir`.
`brain_workspace`	Read / write files in the agent's workspace skills dir (the output target for skill evolution).
`brain_docs`	Search the configured `brainDocsDir` corpus for procedural context.

What it gives your OpenClaw agent

No tool calls for recall. Memories are injected before the model sees the prompt. The agent never has to remember to look.
Cross-session memory. Daily notes, long-term knowledge, episodic recall from the brain graph — all stitched together automatically.
Consolidation that runs. The sleep pass runs on its own schedule. Patterns get promoted. Noise gets pruned.
Failure-resistant. No MCP process to die. No network call to fail. The database is on disk in the agent's own data dir.
Multi-agent fleets. Each agent's brain lives in its own SQLite file. One OpenWave process, isolated brains per agentId.
Rollback to MCP any time. Same brain db, same schema, no migration. plugins disable openwave, add the sharpwave MCP entry back, restart. Brain moves with you.

How it fits in the architecture

Three packages, two repos. The engine is the same; the surfaces are different.

sharpwave-core — the shared memory engine. Published to npm as sharpwave-core. Bundled into both consumers at build time so each surface always ships the engine it was built against — no version-skew path.
sharpwave — the standalone stdio MCP server. Lives in the sharpwave repo. Point any MCP client at npx -y sharpwave and go. Works with Claude Code, Cursor, Claude Desktop.
openwave — the OpenClaw plugin. Lives in this repo. What this page is about. Same engine, in-process, with autonomic wake-up and the sleep system.

OpenWave and the sharpwave MCP server read and write the same files with the same engine code. An agent can be moved between them with no data migration. First open runs the additive-only schema migration to v17.

Brain dbs live at ~/.sharpwave/<agentId>/brain.db (plus SQLite -wal / -shm sidecars). Redirect with SHARPWAVE_DATA_DIR (parent dir) or SHARPWAVE_DB_PATH (exact file).

SharpWave vs OpenWave

Same engine. Two surfaces.

SharpWave is the standalone MCP server — point any MCP client at it and go. Works with Claude Code, Cursor, Claude Desktop, any MCP client. 11 brain_* tools, the headline subset.

OpenWave is the OpenClaw plugin version — same engine, but with in-process autonomic wake-up that injects memory into every turn, and the sleep system runs inside your agent's process. Full persistence, no child process, all 16 brain_* tools.

Learn more about SharpWave → ← Back to .tech