Multi-user multi-agent memory system for OpenClaw. Replaces the default file-backed memory with an intelligent, layered architecture featuring ACT-R activation scoring, Ebbinghaus forgetting curves, Zettelkasten-style note linking, and automatic consolidation.
Agents automatically receive the right memories at the right time without explicit tool calls. Memories are:
- Scoped by domain and visibility (open / scoped / private / user-only)
- Ranked by ACT-R activation (base-level + spreading + stochastic noise)
- Decayed by Ebbinghaus adaptive half-life forgetting
- Consolidated from episodes into durable knowledge via nightly "sleep cycles"
For a detailed explanation of each technique and the research behind it, see docs/RESEARCH.md.
| Layer | Scope | Purpose |
|---|---|---|
| L1 Working Memory | Per-session, in-process | Ephemeral scratchpad with activation-based promotion |
| L2 User Shared | Per-user, persistent | Zettelkasten note store with semantic search |
| L3 Knowledge Commons | Cross-agent | Transactive memory index, pub/sub coordination |
| L4 Daemon | Background | Decay sweeps, consolidation, conflict detection |
| L5 Plugin | OpenClaw integration | Hooks, tools, CLI, lifecycle management |
See docs/GETTING_STARTED.md for a step-by-step walkthrough from install to first use.
openclaw plugins install @risitech/memory-mumaRequires Node.js 22+. Uses Redis Stack 7.2+ for full features or SQLite as a zero-dependency fallback.
For local development, storage backend setup, and building from source, see docs/INSTALLATION.md.
After installation, add MUMA-Mem to your openclaw.json:
{
"plugins": {
"enabled": true,
"slots": {
"memory": "memory-muma"
},
"entries": {
"memory-muma": {
"enabled": true,
"config": {
"embedding": {
"provider": "local",
"model": "Xenova/all-MiniLM-L6-v2"
},
"llm": {
"provider": "openai",
"model": "gpt-4o-mini",
"apiKey": "sk-..."
}
}
}
}
}
}The LLM config is optional — without it, the system runs without the write pipeline and consolidation. The plugin ships with an openclaw.plugin.json manifest, so OpenClaw auto-discovers it from node_modules without extra path configuration.
All settings have sensible defaults. Override what you need in the config block. The identityMap option lets the same human using multiple channels (e.g. Telegram + Discord) share one memory store — keys are canonical user names, values are channel identities that resolve to them.
For a full reference of every config variable, defaults, and valid values, see docs/CONFIGURATION.md.
10 tools are registered automatically when the plugin loads. Each agent session receives its own tool instances scoped to the correct userId and agentId.
| Tool | Description |
|---|---|
memory_write |
Store a memory with automatic deduplication |
memory_query |
Search memories by semantic similarity |
memory_forget |
Mark a memory for forgetting |
memory_pin |
Pin a memory (exempt from decay) |
memory_set_visibility |
Change memory visibility level |
memory_get_context |
Get current session context (L1 + L2) |
memory_stats |
Get memory statistics for the user |
memory_link |
Create explicit links between notes |
memory_search_agents |
Query transactive memory index |
memory_consolidate |
Trigger manual consolidation |
The plugin registers 9 hooks into OpenClaw's lifecycle:
| Hook | What it does |
|---|---|
gateway_start |
Initialize storage, embeddings, LLM, event bus, sync, and background schedulers |
session_start |
Create L1 working memory and map sessionKey to sessionId |
before_agent_start |
Inject combined L1 + L2 memory context into the agent prompt |
message_received |
Capture user messages as episodic memories in L2 |
after_tool_call |
Capture tool results in L1 (working memory) and L2 (persistent) |
before_compaction |
Promote high-activation L1 items to L2 (session continues) |
before_reset |
Promote all L1 items to L2 and clear working memory |
session_end |
Promote remaining L1 items and clean up session state |
gateway_stop |
Shut down all subsystems and release resources |
Direct memory management without running OpenClaw:
# Show memory counts, activation distribution, and domains
muma stats --user alice
# Export memories to JSON
muma export --user alice --output memories.json
# Trigger manual consolidation
muma consolidate --user alice
# List detected conflicts
muma conflicts --user alice --allThe standalone CLI reads config from .muma.json in the current directory or home directory.
When loaded as a plugin, the same commands are available under openclaw memory:
openclaw memory stats --user alice
openclaw memory export --user alice --output memories.json
openclaw memory consolidate --user alice
openclaw memory conflicts --user alice --allWhen new information arrives, MUMA-Mem processes it through six stages:
- Extract — LLM extracts discrete facts from raw input
- Construct — Creates note objects with metadata, tags, visibility
- Retrieve — Finds existing similar notes via vector search
- Decide — LLM decides: ADD new, UPDATE existing, DELETE obsolete, or NOOP
- Link — Connects related notes via vector similarity
- Evolve — LLM enriches context of linked notes
Memory retrieval uses ACT-R cognitive architecture:
- Base-level activation:
B(m) = ln(sum(t - t_i)^(-d))— frequently/recently accessed memories score higher - Spreading activation:
w * cos_sim(query, embedding)— contextually relevant memories get boosted - Stochastic noise: Gaussian noise (sigma=1.2) for natural recall variation — not every retrieval returns the same results
Memories below the retrieval threshold are effectively "forgotten" but not deleted until the background daemon prunes them.
- Decay sweeps run every 60 minutes (configurable), pruning memories whose activation has fallen below threshold
- Consolidation runs daily, clustering related episodic memories into durable knowledge summaries
- Conflict detection identifies contradictory memories across agents and flags them for resolution
Memories are bidirectionally synced to ~/clawd/memory/ as human-readable markdown files with YAML frontmatter. You can inspect, edit, or add memories directly through the filesystem.
src/
├── access/ # Visibility rules, transactive memory index
├── activation/ # ACT-R scoring, Ebbinghaus decay, activation tracking
├── cli/ # Standalone CLI + OpenClaw CLI registrar
├── consolidation/ # Clustering, conflict detection, summarization
├── daemon/ # Background sweep and consolidation schedulers
├── embedding/ # Local (HuggingFace) and remote embedding providers
├── llm/ # LLM provider abstraction (OpenAI-compatible)
├── memory/ # L1 working memory implementation
├── pipeline/ # 6-stage write pipeline + read/search pipeline
├── store/ # Redis and SQLite storage backends
├── sync/ # Event bus + filesystem sync
├── types/ # Core types, note schema, OpenClaw SDK types
├── utils/ # userId derivation, shared utilities
├── config.ts # Zod config schema with defaults
├── index.ts # Plugin definition export
└── plugin.ts # Hook handlers and registration logic
# Install dependencies
pnpm install
# Type check
pnpm run typecheck
# Run tests (98 tests across 8 test files)
pnpm test
# Build
pnpm build- TypeScript 5.9 / ESM / Node.js 22+
- Redis Stack 7.2+ with RediSearch (optional)
- SQLite via better-sqlite3 + sqlite-vec (fallback)
- @huggingface/transformers for local embeddings
- Zod 4 for config validation
- Vitest 4 for testing
Business Source License 1.1 (BUSL-1.1)
Free for non-production use (development, testing, personal projects). Production use requires a commercial license from RisiTech.
Converts to Apache 2.0 on 2029-02-17 (3 years from initial release).
See LICENSE for full terms.