Tools
Xanima Openclaw
By Xanima for OpenClaw (formerly OpenWave): automatic long-term memory and identity continuity for OpenClaw agents. npm/ClawHub: xanima-openclaw.
Install
npm install --ignore-scripts`,Configuration Example
"plugins": {
"load": { "paths": ["/abs/path/to/xanima-openclaw"] }
}README
# Xanima for OpenClaw (`xanima-openclaw`, formerly openwave)
**Autonomic long-term memory and agent continuity for [OpenClaw](https://openclaw.ai) agents.**
Xanima 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 — no tool call**. Identity and goals ride in as a never-compacted
system header; query-relevant recall (with confidence and relative-time labels),
always-on procedural rules, and a last-24h activity digest ride in as prepended
context. The agent wakes up already knowing.
It also runs the sleep system in-process on timers — slow-wave/REM consolidation,
awake replay, and LLM fact extraction — so the graph keeps improving between
sessions without anything calling it. On top of memory it keeps the agent
*continuous*: 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 engine is [`xanima-core`](https://www.npmjs.com/package/xanima-core)
(formerly sharpwave-core), the same memory engine behind the
[`xanima`](https://www.npmjs.com/package/xanima) MCP server (formerly
`sharpwave`). **Use the `xanima` MCP server for Claude Code / Cursor / Claude
Desktop. Use this plugin for OpenClaw** — it does everything the MCP server
does, plus the automatic per-turn injection and the in-process sleep system that
an MCP server structurally cannot.
| | |
|---|---|
| npm package | [`xanima-openclaw`](https://www.npmjs.com/package/xanima-openclaw) 0.5.0 |
| ClawHub | `clawhub:xanima` |
| plugin id | `xanima` (manifest `legacyPluginIds: ["openwave"]`) |
| config entry | `plugins.entries.xanima` |
| engine | `xanima-core` 0.5.0, schema v25 |
| brain files | `~/.xanima/<agentId>/brain.db` |
| tools | 43 `brain_*` tools (names unchanged since openwave and permanent) |
| brain service | `xanima-server` (formerly sharpwave-server; see [Remote brain mode](#remote-brain-mode)) |
---
## Install
### From ClawHub (recommended)
```bash
openclaw plugins install clawhub:xanima --accept-capabilities
```
Published by `@EnlightenedRepublic`, source-linked to this repo. If `db.init`
fails with "Could not locate the bindings file" after install, run the native
rebuild step shown under **From npm** below (in the plugin's install directory).
### From npm
```bash
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 is not fetched/built during install. Without
it, every `db.init` fails with "Could not locate the bindings file". Run it in
whatever directory OpenClaw installed the package to, and re-run it after any
`openclaw plugins update xanima`.
### From source (development)
```bash
git clone https://github.com/Enlightened-Republic/xanima-openclaw
cd xanima-openclaw && npm ci && npm run build
```
Then point `plugins.load.paths` at the checkout directory (not `dist/index.js` —
OpenClaw reads `openclaw.plugin.json` next to it):
```jsonc
"plugins": {
"load": { "paths": ["/abs/path/to/xanima-openclaw"] }
}
```
### Configure (all install methods)
Add the entry to `openclaw.json`:
```jsonc
"plugins": {
// If plugins.allow is set (it's an exclusive allowlist), xanima MUST be in it.
"allow": ["...your other plugin ids...", "xanima"],
"entries": {
"xanima": {
"enabled": true,
"hooks": { "allowConversationAccess": true },
"config": { "agents": ["main"] }
}
}
}
```
Then restart the gateway (`openclaw gateway restart` — a full restart, not a soft
reload) and 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",...}
```
**`hooks.allowConversationAccess: true` is required** — xanima is a non-bundled
plugin and its `before_prompt_build` / `agent_turn_prepare` / `llm_output` /
`agent_end` hooks read conversation content.
**`config.agents` is required and has no safe default on a multi-agent gateway.**
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 `"agents": "*"` (see
[Automatic agents](#automatic-agents-and-provisioning-remote-mode)).
**Compatibility:** `pluginApi >= 2026.5.0`, `minGatewayVersion 2026.5.0`. Older
gateways don't expose the hook and session-workflow surface xanima needs.
---
## Upgrading from openwave
openwave 0.2.x installs keep working: the plugin id `xanima` carries
`legacyPluginIds: ["openwave"]`, and when `plugins.entries.xanima` has no
settings of its own the plugin reads `plugins.entries.openwave.config` and logs
a one-time `[xanima] DEPRECATED` warning. Move over once, then the warnings stop:
```bash
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 writes
```
The upgrade **copies** the openwave block to `plugins.entries.xanima`, disables
(does not delete) `plugins.entries.openwave` so the two never both register the
`brain_*` tools, and adds `"xanima"` next to `"openwave"` in `plugins.allow` /
`plugins.deny`. It never overwrites an `entries.xanima` block that already has
settings. `--config` defaults to `$OPENCLAW_CONFIG_PATH`, then
`$OPENCLAW_STATE_DIR/openclaw.json`, then `~/.openclaw/openclaw.json`. The file
must be plain JSON (no comments); otherwise copy the block by hand.
What else changed:
- **Brain files** live in `~/.xanima/<agentId>/brain.db`. While `~/.xanima` does
not 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. After migrating, `xanima-openclaw-upgrade --data-paths --write`
repoints `.sharpwave` paths in your config (`brainTokenFile`,
`provisionTokenFile`, …) at `.xanima`, but only for targets that exist there.
- **Env vars**: `$XANIMA_BRAIN_TOKEN` replaces `$OPENWAVE_BRAIN_TOKEN`; the
engine's `XANIMA_DATA_DIR` / `XANIMA_DB_PATH` / `XANIMA_EMBEDDING_MODEL` /
`XANIMA_OPENROUTER_API_KEY` replace the `SHARPWAVE_` names. The old names are
still read in 0.5.0 with a deprecation warning and will be dropped in a later
release.
- **Tool names** (`brain_*`) are unchanged and permanent. The host cron id stays
`openwave:consolidation` (renaming it is deferred).
- **Rollback**: re-enable `plugins.entries.openwave`, disable `entries.xanima`
(or restore the `openclaw.json.pre-xanima-*.bak` the upgrade wrote), restart.
---
## Configuration
xanima's config is `xanima-core`'s `BrainConfig` plus the host-only fields
below. Everything under `plugins.entries.xanima.config` is merged over the
manifest defaults and passed straight into the engine.
| field | type | default | meaning |
|---|---|---|---|
| `agents` | `string[]` \| `"*"` | `["main"]` | **Required.** OpenClaw agent ids xanima serves (`"*"` = every agent in the OpenClaw config). Local mode routes each to `~/.xanima/<id>/brain.db`. |
| `excludeAgents` | `string[]` | `[]` | Agent ids never served (applies to `"*"` and explicit lists). |
| `enabled` | `boolean` | `true` | `false` (or `entries.xanima.enabled: false`) → `register` returns immediately, no tools, no hooks. |
| `llmExtractionEnabled` | `boolean` | `false` | `true` → `message_received` / `llm_output` episodes at or above `llmExtractionMinImportance` are queued for LLM fact extraction into graph nodes. `false` → heuristic extractor only. |
| `llmExtractionMinImportance` | `number` | `0.4` | Importance floor for queueing an episode for extraction. |
| `skipSystemTurns` | `boolean` | `true` | Skip OpenClaw system turns on every memory-writing path (local and remote): heartbeat polls and their replies, `[OpenClaw exec completion]` / cron / session-event wakes, `NO_REPLY` / `HEARTBEAT_OK` replies, memory-flush runs. Skipped turns get **no episode and no extraction**. See [System turns](#system-turns). |
| `systemTurnPatterns` | `string[]` | `[]` | Extra case-insensitive regexes; a turn whose trimmed text matches is skipped like a system turn. Invalid entries are ignored (warned once). |
| `ingestionModel` | `string` | `"openrouter/deepseek/deepseek-v4-flash"` | Model for LLM fact extraction and generative REM. `openrouter/provider/model` or bare `provider/model` both work. |
| `openRouterApiKey` | `string` | `$OPENROUTER_API_KEY` / `$XANIMA_OPENROUTER_API_KEY` / `""` | OpenRouter key for engine LLM calls. Empty → extraction and generative-REM degrade to heuristic mode (non-fatal). Prefer the env var over putting the key in `openclaw.json`. |
| `consolidationCron` | `string` | `"30 4 * * *"` | Host cron expression for the `openwave:consolidation` job (LLM consolidation), staggered after memory-core dreaming. |
| `consolidationCronEnabled` | `boolean` | `true` | Register the consolidation host cron on `gateway_start`. |
| `curatedTierDedupe` | `boolean` | `true` | When `MEMORY.md` / `USER.md` is present, tell the engine so durable identity/goals are not double-injected. |
| `personaOverrides` | `object` | `{}` | Per-agent-id overrides of the numeric tunables below, keyed by OpenClaw agent id. Missing keys inherit the flat value. |
Engine (`BrainConfig`) fields you can also override, passed through to
`xanima-core` (defaults from `core.DEFAULT_CONFIG`):
| field | type | default | meaning |
|---|---|---|---|
| `contextBudget` | `number` | `20
... (truncated)
tools
Comments
Sign in to leave a comment