Long-term memory for AI agents.
A real forgetting curve. A memory graph. Sleep-cycle consolidation. Drop it into Claude Code, Cursor, or any MCP client.
Formerly SharpWave. Same engine, new name.
npx -y xanima
Your agent forgets everything the moment a session ends. The usual fix is to dump conversation history into a vector store and retrieve the most similar chunks — which works until it doesn’t:
Human memory doesn’t work that way. It decays on a curve, strengthens what gets used, consolidates related things into concepts, and lets the rest fade. Xanima models that — and on top of memory, it keeps track of what the agent believes, how sure it is, what it decided, and what it’s working toward.
Sharp-wave ripples are the hippocampal events that replay and consolidate memories during rest. That’s the mechanism this is built around, not a metaphor bolted on afterward.
Every memory carries FSRS-6 stability and retrievability. Unused memories decay on a power-law curve and drop out of recall. Faded memories go dormant instead of being deleted — an explicit search (include_dormant) brings them back.
A background pass replays recent episodes, promotes recurring patterns into durable semantic nodes, synthesises clusters into higher-level schemas, and downscales the noise — modelled on slow-wave and REM sleep. Plans the agent carried out become step-by-step procedures, verified by repeated success.
Memories connect through typed edges — caused_by, supports, contradicts, supersedes, instance_of and more. Retrieval spreads activation across those edges.
Every memory carries a confidence, a source and a status. brain_retract and brain_supersede correct a memory with a reason and keep the history; as_of asks what the agent believed on a given date.
Full-text search fused with vector similarity via reciprocal rank fusion, then spread across the graph. Vector search is optional — full-text and graph retrieval work with no embedding provider at all.
One Xanima process can back any number of agents at once. Each agent’s memories live in their own database — isolated, never cross-contaminated — under a single config entry.
Point any MCP client at it. Node.js 22 or newer.
{
"mcpServers": {
"xanima": {
"command": "npx",
"args": ["-y", "xanima"]
}
}
}claude mcp add xanima -- npx -y xanima
openclaw mcp add xanima --command npx --arg -y --arg xanima
openclaw mcp doctor xanima --probeMemory lands in ~/.xanima/ as a SQLite database. Nothing leaves your machine unless you configure a remote embedding provider.
Leave XANIMA_AGENT_ID unset and one process serves the whole fleet: every brain_* call carries the calling agent’s agent id and is routed to its own ~/.xanima/<agent>/brain.db. Set it to pin the server to one agent.
The sharpwave command still works — it’s kept as an alias of xanima. Your data is safe where it is: while ~/.xanima doesn’t exist and ~/.sharpwave does, the old folder is used (with a one-time notice). xanima-server migrate (the brain service, built from the xanima repo) copies it over, verifies every brain’s counts, and never moves or deletes the old folder. XANIMA_* env vars replace SHARPWAVE_*; the old names are still read with a deprecation warning.
Memory, beliefs, decisions, goals, reflection and plans. Every schema comes from xanima-core’s unified tool module, the same one the OpenClaw plugin uses.
| 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 |
| 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 — export the agent’s own brain as a portable xanima-soul/1 package |
| Highlights | What it does |
|---|---|
brain_query | Hybrid FTS + vector + spreading activation. as_of for what the agent believed at a past time; include_dormant to search and revive faded memories. |
brain_expand | Full detail for a node: content, FSRS metrics, encoding context. source_turns prints the original conversation the memory came from. |
brain_supersede | Replace an outdated node with a reason. The old version is kept as history but never injected again. |
brain_retract | Retract a memory that is wrong. Kept as history with your reason; never recalled again. |
brain_status | Short self-status: last sleep, low-confidence and disputed counts, hot conflicts, anything that needs attention. |
brain_reset | Wipe an agent’s brain back to empty (a .db backup is taken first). confirm must equal the agent id. |
Xanima 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 (formerly OpenWave) is the OpenClaw plugin — same engine, but in-process: it injects memory into every turn automatically, runs the sleep system (slow-wave/REM consolidation, awake replay, LLM fact extraction) inside your agent’s process, and registers all 43 brain_* tools, including rooms, focus and identity. Full persistence, no child process.