Wake up already knowing.
Autonomic long-term memory and agent continuity for OpenClaw agents. Same Xanima engine, but in-process. No child process. No tool calls to remember. The agent just knows.
Formerly OpenWave. Same plugin, new name — your setup keeps working.
openclaw plugins install npm:xanima-openclaw --force --accept-capabilities
The Xanima MCP server works great 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.
Xanima for OpenClaw 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 on your own disk — not behind a socket you have to keep alive.
It does everything the MCP server does, plus the parts an MCP server structurally can’t. Same engine. Different surface.
On every session start, every turn, every heartbeat, and every compaction, Xanima 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. No tool call. The agent never has to remember to look.
Consolidation runs inside the agent’s process on timers — slow-wave and REM passes, awake replay, LLM fact extraction. No separate service to keep alive. Patterns promote into semantic nodes; faded memories go dormant instead of being deleted.
A decision ledger, versioned goals with drift detection, reflection and experience replay, commitments and plans, a portable Soul Package, shared rooms, and an identity the agent can evolve under guardrails.
The retrieval, consolidation, FSRS decay, graph edges — all of it is the exact same xanima-core code that ships in the standalone npx -y xanima MCP server. Bundled at build time, so each surface always ships the engine it was built against.
One plugin serves any number of agents. Each agent’s brain lives in its own SQLite file at ~/.xanima/<agentId>/brain.db — isolated, never cross-contaminated. List them in config.agents, or use "*" for every agent in your OpenClaw config.
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.
openclaw plugins install npm:xanima-openclaw --force --accept-capabilities
cd ~/.openclaw/npm/projects/xanima-openclaw && npm rebuild better-sqlite3--force acknowledges an npm (non-ClawHub) source. 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”. Run it wherever OpenClaw installed the package, and re-run it after any openclaw plugins update xanima.
git clone https://github.com/Enlightened-Republic/xanima-openclaw
cd xanima-openclaw && npm ci && npm run buildThen 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/xanima-openclaw"] }
}
}openclaw.json
{
"plugins": {
"allow": ["...your other plugin ids...", "xanima"],
"entries": {
"xanima": {
"enabled": true,
"hooks": { "allowConversationAccess": true },
"config": { "agents": ["main"] }
}
}
}
}hooks.allowConversationAccess: true — required. Xanima 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 the served-agent list. An agent not listed gets no injection, no episode logging, no sleep system. List every agent you want Xanima to serve, or use "*".enabled: true — flips the plugin on. Setting false (or omitting the entry) makes register return immediately: no tools, no hooks.plugins.allow — if you use it, it’s an exclusive allowlist, so xanima must be in it.Restart the gateway with a full restart, not a soft reload: openclaw gateway restart.
Confirm from the log:
[xanima] {"op":"config.source","outcome":"xanima"}
[xanima] {"op":"register","outcome":"ok","agents":<N>,"tools":43,"engine":"xanima-core",...}
[xanima] {"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 Xanima needs.
Move over once, on your own schedule.
The plugin id is now xanima, and it carries the old id as a legacy id. When plugins.entries.xanima has no settings of its own, the plugin reads your old plugins.entries.openwave.config and logs a one-time deprecation warning. To move over, run the bundled upgrade tool:
xanima-openclaw-upgrade --config ~/.openclaw/openclaw.json # dry run: prints what would change
xanima-openclaw-upgrade --config ~/.openclaw/openclaw.json --write # timestamped backup first, then writesIt copies your old block to plugins.entries.xanima, disables (doesn’t delete) the old entry so the two never both register the brain_* tools, and adds "xanima" to plugins.allow / plugins.deny. It never overwrites an entries.xanima block that already has settings.
~/.xanima/<agentId>/brain.db. While ~/.xanima doesn’t exist and ~/.sharpwave does, the old folder is used (with a one-time notice). xanima-server migrate copies it over; the old folder is never moved or deleted.XANIMA_* replaces the old names. The old names are still read with a deprecation warning, for now.brain_*) are unchanged and permanent.entries.xanima (or restore the .bak the upgrade wrote), restart.Rides in as a never-compacted system block. The agent always knows who it is and what it’s working on. A small goals block can add an alignment note when a goal has stalled, or a nudge for an overdue commitment.
Per-turn: hybrid FTS + vector + spreading activation across the graph, sized to a token budget (default contextBudget: 2000). Top-K default 10. Each line says when it was learned and flags low-confidence or disputed beliefs.
Verified procedures and hand-written rules surface in every turn. A sentence sleep merely extracted from a pasted page never does.
A short log of what happened in the recent past, so the agent knows where it left off.
Replays recent episodes, promotes recurring patterns into durable semantic nodes, and synthesises higher-level schemas. Runs from a host cron job (default 04:30) that never wakes the agent. Gated by consolidationTimeGateHours (default 4h) and consolidationEpisodeGate (default 10 new episodes).
Background replay of recent episodes every 30 minutes between consolidation passes — keeps the graph warm without waiting for the next sleep cycle.
Episodes above llmExtractionMinImportance (default 0.4) are queued for extraction into graph nodes when llmExtractionEnabled is on, harvested hourly. Off by default; heuristic extractor only when off. Model: ingestionModel (default openrouter/deepseek/deepseek-v4-flash).
Memories that fade go dormant, not deleted — an explicit search brings them back. A plan the agent carried out becomes a step-by-step procedure; after two successful runs it’s verified and injected as an operational rule.
Definitions and executors come from xanima-core’s unified tool module — so this plugin and the standalone Xanima MCP server can’t expose a drifted schema. (The MCP server publishes 32 of them.)
| Group | Tools |
|---|---|
| Memory | brain_query, brain_write, brain_link, brain_supersede, brain_stats, brain_history, brain_expand, brain_review, brain_forget, brain_edges, brain_reset, brain_update_self_model, brain_generate_skill, brain_workspace, brain_docs |
| Beliefs | brain_retract, brain_status |
| Decisions & goals | brain_record_decision, brain_update_decision_outcome, brain_query_decisions, brain_set_goal, brain_update_goal, brain_list_goals |
| Reflection, open items & plans | brain_reflect, brain_replay, brain_hypothesis, brain_question, brain_list_open, brain_commit, brain_commitments, brain_plan, brain_changes, brain_conflicts, brain_briefing, brain_forget_impact |
| Soul | brain_export_soul |
| Rooms | brain_room, brain_publish, brain_unpublish, brain_room_query, brain_subscribe — need the brain service (remote mode) |
| Focus & identity | brain_focus, brain_identity |
Most memory work needs no tool call — Xanima injects and logs automatically. The tools are for deliberate deep recall, corrections with a reason, and introspection.
brain_reset is refused unless allowAgentReset: true. The agent knows its own id, so the confirm guard alone wouldn’t stop a prompt injection. brain_identity changes who the agent is only through conversations with its owner; changes proposed anywhere else are held for review or refused.
agentId.openclaw plugins disable xanima, add the xanima MCP entry back, restart. Brain moves with you.By default the plugin opens each agent’s brain.db in-process (brainMode: "local"). With brainMode: "remote" it talks to the Xanima brain service (xanima-server) over MCP Streamable HTTP with a per-agent bearer token. The service owns storage and sleep, and one service can serve several agents, a shared brain, and rooms.
"config": {
"agents": ["main"],
"brainMode": "remote",
"brainUrl": "http://127.0.0.1:18790",
"brainTokenFile": "~/.xanima/tokens/{agentId}.token"
}xanima-server isn’t on npm — build it from the xanima repo. In remote mode 39 of the 43 tools are proxied to the service; brain_update_self_model, brain_generate_skill, brain_workspace and brain_docs are local-only.
The engine is the same; the surfaces are different.
xanima-core — the shared memory engine. Published to npm as xanima-core. Bundled into both consumers at build time so each surface always ships the engine it was built against — no version-skew path.xanima — the standalone stdio MCP server. Lives in the xanima repo. Point any MCP client at npx -y xanima and go. Works with Claude Code, Cursor, Claude Desktop.xanima-openclaw — the OpenClaw plugin. Lives in the xanima-openclaw repo. What this page is about. Same engine, in-process, with autonomic wake-up and the sleep system.All three are at 0.6.0, MIT licensed. The plugin and the xanima 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 v27 — no data loss.
Brain dbs live at ~/.xanima/<agentId>/brain.db (plus SQLite -wal / -shm sidecars). Redirect with XANIMA_DATA_DIR (parent dir) or XANIMA_DB_PATH (exact file).
Xanima (formerly SharpWave) is the standalone MCP server — point any MCP client at it and go. Works with Claude Code, Cursor, Claude Desktop, any MCP client. 32 brain_* tools.
Xanima for OpenClaw is the OpenClaw plugin — 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 43 brain_* tools.