Catches memories that contradict each other. Notes rewrite themselves as new ones arrive and link into a graph. Memories are kept per agent, and tagged per person in direct chats. Runs on a small model. Requires a local Qdrant. 中文走 jieba 分词,提示词有中文版。
openclaw-amem
Memory for OpenClaw agents that catches its own contradictions.
A nightly pass re-reads what changed and flags memories that no longer agree with each other. This is the failure mode every long-lived memory store eventually has. The plugin also extracts facts instead of storing transcripts. It rewrites notes as new ones arrive, links them into a Zettelkasten-style graph, and retrieves them with hybrid BM25 + dense search over 2-hop expansion. The plugin scopes memories per agent (owner/readers/writers) and filters searches by subject inside the Qdrant query rather than after it. In direct chats it tags what it captures with the speaker (<channel>:<sender id>) and searches as that speaker by default. In a direct chat the memory tools accept only the current speaker as subject, and in a group none; anything else returns an error. In runs with no sender (cron, heartbeat, CLI) a model can still name any subject and a search sees everyone's memories. This is not a general access-control system: tools that OpenClaw itself calls are unscoped in direct chats, and a group that shares the main session is not detected.
The plugin runs on a small model — gpt-4o-mini, haiku, a local Ollama. It does not require Python.
中文走 jieba 分词,提示词有完整中文版(AMEM_PROMPT_LOCALE=zh),embedding 模型本身多语言。
Requires a local Qdrant. Implements A-MEM (arXiv 2502.12110); the engine itself is @amemhq/core.
📖 Full guides, architecture & references: amem.owo.lc.
⭐ Useful? Star it on GitHub.
Highlights
- 🔄 Memories evolve — new facts update/link related memories (EVOLVE / CONFLICT / EXPAND / NEW), not silent overwrite.
- 🔍 Hybrid retrieval — BM25 (Jieba for Chinese) + dense vectors (RRF) + 2-hop graph expansion with a relevance gate.
- 🧠 Knowledge vs episodic — durable knowledge notes skip consolidation & time-decay. Topic tags for precise recall.
- 🧹 Self-consolidating — daily 02:30 in-process merge of semantic duplicates with link cascading.
- 🔐 Per-agent isolation — private by default. Explicit
owner/readers/writers. Mode A (shared collection) or Mode B (dedicated collection). - 🀄 Chinese-optimized & local embeddings (Transformers.js) — no Python, no external embedding API.
→ Full feature list & internals: @amemhq/core README · docs.
Requirements
- OpenClaw v2026.4+
- Node.js 24 (18+ works, 24/26 supported)
- Qdrant running on
:6333 - An LLM:
ANTHROPIC_API_KEYby default, or any OpenAI-compatible provider — see LLM provider - ~1.1 GB of disk for the embedding model, downloaded once on first run
Installation
1. Install the plugin
# From ClawHub (recommended)
openclaw plugins install clawhub:openclaw-amem
# From npm
openclaw plugins install openclaw-amem
# From a local checkout of the amem monorepo
pnpm --filter openclaw-amem build
openclaw plugins install --link ./packages/openclaw-amem
Updating:
openclaw plugins update openclaw-amem
The gateway does not load the new build until it restarts. Run openclaw gateway restart after the update.
An update rebuilds node_modules. The model cache lives there by default, so the plugin re-downloads 2.27 GB unless AMEM_MODEL_CACHE points somewhere outside the plugin directory. Set that once and updates cost nothing.
2. Configure ~/.openclaw/openclaw.json
Add openclaw-amem to your allowed plugins and hook it into the memory slot:
{
"plugins": {
"allow": ["openclaw-amem"],
"entries": {
"openclaw-amem": {
"enabled": true,
"config": {
"agentId": "main",
"topK": 5
}
}
},
"slots": {
"memory": "openclaw-amem"
}
}
}
⚠️ Memory slot conflict: If your
openclaw.jsonalready assigns thememoryslot to another plugin (for example,memory-core), you must change it toopenclaw-amem. On OpenClaw 2026.8.1 the slot alone is not enough. The other plugin still loads and takes thememory_searchtool name, because the gateway loads built-in plugins before installed ones. Memory keeps working through the slot, but the tool an agent calls is then the other plugin's. Set"memory-core": { "enabled": false }inentriesas well. Note thatmemory-corealso writes its dream diary, and disabling it stops that too.
3. Restart OpenClaw
openclaw gateway restart
First run downloads the embedding model (bge-m3, 2.27 GB) and caches it. Later
restarts are instant. If that is too much, the only smaller model worth setting is
AMEM_EMBED_MODEL=Xenova/bge-small-zh-v1.5 — 25 MB, Chinese only, and it caps at
512 tokens. Set it before you have memories, because changing it afterwards means
a migration.
Upgrading from 1.x downloads nothing. Your existing memories keep the model that built them, and the plugin shows this at startup along with the one command that moves them.
LLM provider
The plugin calls an LLM for note construction, linking, and evolution. Pick the backend with AMEM_LLM_PROVIDER:
anthropic(default) — the Anthropic Messages API. SetANTHROPIC_API_KEY.openai— the OpenAI Chat Completions API, which every OpenAI-compatible endpoint speaks. SetAMEM_LLM_PROVIDER=openai, pointAMEM_LLM_BASE_URLat the endpoint, and setAMEM_LLM_API_KEY(or the standardOPENAI_API_KEY). Covers OpenAI, DeepSeek, OpenRouter, Groq, Together, and local servers (Ollama, vLLM, LM Studio — no key needed). The plugin handles reasoning models (o1,o3,gpt-5) automatically.
Choose the model with AMEM_LLM_MODEL. Full env-var reference and examples: amem.owo.lc/reference/configuration.
Configuration Reference
| Key | Type | Default | Description |
|---|---|---|---|
agentId | string | "main" | Agent namespace for memory isolation |
topK | number | 5 | Maximum memories to retrieve during search |
agents | Record<string, {agentId?, collection?}> | {} | Per-agent overrides. Set collection for Mode B physical isolation. |
hooks.allowConversationAccess | boolean | false | Required for automatic memory write-back. Without it, the agent_end hook is silently blocked by OpenClaw's security policy. |
crudRetire | "off" | "auto" | "off" | Whether the plugin may hide a memory on its own at the end of a turn. off never hides one. Hidden memories can be brought back. |
Tools
Once installed, the plugin exposes five tools to the agent:
| Tool | What it does |
|---|---|
memory_add | Write a memory — hash dedup, LLM note construction, bidirectional linking, evolution. |
memory_search | Search via RRF (BM25 + cosine) with heat ranking + 2-hop BFS graph expansion. Accepts topicsFilter. |
memory_list | Total active note count for the current agent namespace. |
memory_consolidate | Manually trigger category-based semantic dedup + link cascading. |
memory_quality_scan | Scan for low-quality/expired/conflicting notes → Obsidian-compatible review batch file. |
Undoing a change
After each turn, the plugin saves what it learned. It rewrites a memory it already
has only when the owner wrote in a direct chat with the agent. The owner is the
account listed in OpenClaw's commands.ownerAllowFrom. In group chats and in other
people's chats, this step only adds new memories. It hides a memory only when
crudRetire is "auto", and then in any chat. The memory_add and
memory_consolidate tools, and the nightly cleanup, can still change memories.
To see and undo changes, run these where OpenClaw runs:
openclaw amem retired # hidden memories, newest first
openclaw amem restore <id> # bring one back
openclaw amem revert <id> # put back what a memory said before its last change
Both restore and revert show the memory and ask before they change it.
Security & data flow
A memory plugin's job is to read configuration from the environment and send memory data to backends you control, so registry static scanners flag its env + network pattern (for example, ClawHub's suspicious.env_credential_access). This is structurally expected for any configurable memory/LLM plugin. The audit outcome is advisory (Review), not Malicious, and VirusTotal reports the bundle clean.
What it actually does — all of it declared in openclaw.plugin.json:
- Environment variables it reads (its configuration surface, supplied by you):
AMEM_LLM_PROVIDER,AMEM_LLM_API_KEY,OPENAI_API_KEY,AMEM_LLM_BASE_URL,AMEM_LLM_MODEL,AMEM_COLLECTION,AMEM_DATA_DIR,AMEM_EVO_COUNTER_PATH,AMEM_REVIEW_DIR,AMEM_PROMPT_LOCALE. No credential is bundled, hardcoded, or logged. - Network destinations: only your local Qdrant (
http://localhost:6333) and your configured LLM endpoint (Anthropic by default, or any OpenAI-compatible endpoint viaAMEM_LLM_PROVIDER=openai+AMEM_LLM_BASE_URL). It sends memory text/embeddings there to store and evolve notes — its stated purpose. It does not phone home. - The plugin processes conversation content for memory only when you set
hooks.allowConversationAccess: true. Keep Qdrant and review-output paths scoped to locations you control.
Development
This package is part of the amem monorepo. From the repo root:
pnpm install
pnpm -r build # build all packages
pnpm --filter openclaw-amem build # build just the plugin
pnpm --filter openclaw-amem test # vitest (needs Qdrant on :6333)
Docs & References
Full guides, architecture, and academic references: amem.owo.lc · engine: @amemhq/core · paper: A-MEM (arXiv:2502.12110).
License
MIT
