openclaw-amem 1.0.0 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +45 -276
- package/dist/index.js +448 -4568
- package/openclaw.plugin.json +2 -2
- package/package.json +19 -22
package/README.md
CHANGED
|
@@ -1,196 +1,39 @@
|
|
|
1
1
|
# openclaw-amem
|
|
2
2
|
|
|
3
3
|
<p align="center">
|
|
4
|
-
<img src="https://
|
|
4
|
+
<img src="https://amem.owo.lc/logo.webp" width="120" alt="A-MEM Logo" />
|
|
5
5
|
</p>
|
|
6
6
|
|
|
7
|
-
[](LICENSE)
|
|
7
|
+
[](../../LICENSE)
|
|
8
8
|
[](https://www.npmjs.com/package/openclaw-amem)
|
|
9
9
|
[](https://arxiv.org/abs/2502.12110)
|
|
10
|
-
[](https://github.com/heichaowo/openclaw-amem/actions)
|
|
11
10
|
|
|
12
|
-
**A-MEM agentic memory backend for [OpenClaw](https://github.com/openclaw/openclaw)**
|
|
11
|
+
**A-MEM agentic memory backend for [OpenClaw](https://github.com/openclaw/openclaw)** — memories **evolve**, not just accumulate.
|
|
13
12
|
|
|
14
|
-
|
|
13
|
+
The first open-source A-MEM memory plugin for OpenClaw: dynamic graph linking, hybrid (BM25 + dense) retrieval with 2-hop graph expansion, and LLM-driven memory evolution. Backed by Qdrant + local Transformers.js. **No Python required.**
|
|
15
14
|
|
|
16
|
-
|
|
15
|
+
> 🧠 The memory **engine** lives in **[`amem-core`](../amem-core)**; this package is the thin OpenClaw plugin around it.
|
|
16
|
+
> 📖 Full guides, architecture & references: **[amem.owo.lc](https://amem.owo.lc)**.
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
⭐ Useful? [Star it on GitHub](https://github.com/heichaowo/amem).
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
## Highlights
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
- 🔄 **Memories evolve** — new facts update/link related memories (EVOLVE / CONFLICT / EXPAND / NEW), not silent overwrite.
|
|
23
|
+
- 🔍 **Hybrid retrieval** — BM25 (Jieba for Chinese) + dense vectors (RRF) + 2-hop graph expansion with a relevance gate.
|
|
24
|
+
- 🧠 **Knowledge vs episodic** — durable knowledge notes skip consolidation & time-decay; topic tags for precise recall.
|
|
25
|
+
- 🧹 **Self-consolidating** — daily 02:30 in-process merge of semantic duplicates with link cascading.
|
|
26
|
+
- 🔐 **Per-agent isolation** — private by default; explicit `owner`/`readers`/`writers`; Mode A (shared collection) or Mode B (dedicated collection).
|
|
27
|
+
- 🀄 **Chinese-optimized** & local embeddings (Transformers.js, 384-dim) — no Python, no external embedding API.
|
|
23
28
|
|
|
24
|
-
|
|
25
|
-
- 🔗 **Automatic Link Generation** — New memories automatically link bidirectionally to existing related memories via embedding similarity + LLM verification.
|
|
26
|
-
- 🧬 **Memory Evolution & Strengthening** — Linked memories update context/tags/embeddings when new details arrive. Supports active link strengthening and tag propagation.
|
|
27
|
-
- 🚦 **LLM CRUD Decision Gate** — Hooked into OpenClaw's `agent_end` dialog termination. Analyses user-assistant dialogue context, running `NEW` / `UPDATE` / `DELETE` / `NONE` decisions to keep memory clean.
|
|
28
|
-
- 🧹 **Same-Day Semantic Merger** — Automatically merge semantic duplicates written during the same day (≥ 0.80 cosine similarity).
|
|
29
|
-
- 📅 **In-Process Daily Consolidation** — Endogenous in-process `setTimeout` scheduler running at 02:30 AM. Groups notes by `category`, merges semantic duplicates (≥ 0.75) into clean unified knowledge notes, and **cascades all link references** automatically to preserve graph topology.
|
|
30
|
-
- ⏳ **Temporal Invalidation & Soft-Delete** — Outdated/conflicting memories are marked `is_active: false` (soft-deleted) and excluded from searches using zero-migration Qdrant filters.
|
|
31
|
-
- 🔥 **Retrieval Heat Tracking with Time Decay** — Incorporates `retrieval_count` and `last_accessed` timestamps in hybrid scoring. Frequently retrieved memories receive a logarithmic heat boost, dampened by elapsed time since last access so stale memories do not permanently outrank fresh ones:
|
|
32
|
-
|
|
33
|
-
```
|
|
34
|
-
Final Score = RRF Score × (1 + 0.05 × ln(1 + retrieval_count) / (age_days + 1))
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
A note last accessed 60 days ago with 10 retrievals gets boost ≈ 1.002; the same note accessed today gets ≈ 1.060.
|
|
38
|
-
|
|
39
|
-
- 🔍 **2-hop Graph Traversal with Relevance Gate** — After vector retrieval, BFS walks the link graph up to 2 hops from each anchor result. Only nodes passing an embedding relevance gate (cosine similarity ≥ 0.25 against the query) are admitted, preventing noise from distant graph neighborhoods.
|
|
40
|
-
- 🀄 **Chinese-Optimized BM25** — The BM25 pipeline uses [Jieba](https://github.com/fxsjy/jieba) (via `@node-rs/jieba`) for CJK word segmentation instead of character-level splitting, dramatically improving recall for Chinese queries. English and mixed-language text fall back to whitespace tokenization automatically.
|
|
41
|
-
- 🧠 **Knowledge Type Classification** — Notes are automatically classified as `memory` (episodic, time-sensitive) or `knowledge` (durable reference, timeless) by LLM. Knowledge notes are excluded from Daily Consolidation merging and time-decay heat penalties, ensuring durable facts remain reliably retrievable regardless of age.
|
|
42
|
-
- 🏷️ **Topic Tags for Knowledge Notes** — `knowledge`-type notes carry a `topics: string[]` field (1-5 concise subject labels, e.g. `["TypeScript", "Qdrant"]`). The `memory_search` tool accepts a `topicsFilter` parameter (AND semantics, case-insensitive) for precise knowledge retrieval by subject.
|
|
43
|
-
- 🛡️ **Strict Quality Controls** — Full Vitest test coverage for embeddings, storage, link-cascading consolidation, tokenization, and BFS gate behavior, integrated into ESLint + Prettier + import boundary CI checks running on GitHub Actions.
|
|
44
|
-
- 📊 **Quality Scoring & Auto-Review** — Write-time quality gate rejects content under 10 characters and marks temporal/ephemeral content (containing signal words like '待跑', '等确认'). The `memory_quality_scan` tool scans the full memory store, identifies low-quality entries (too short, expired ephemeral >7 days, unresolved conflicts), and generates Obsidian-compatible review batch files for human curation.
|
|
45
|
-
- 🔐 **Per-Agent Memory Isolation** — Each agent operates in its own private memory namespace. Memories written by `main` are invisible to `dev` by default. A `shared` scope lets the writing agent publish memories readable by all agents, with explicit `owner`/`readers`/`writers` access fields on every note. Two modes: Mode A (shared Qdrant collection, filtered by `agent_id`) and Mode B (dedicated collection per agent, full physical isolation).
|
|
46
|
-
- 🔔 **Hook Self-Check** — If the `agent_end` hook has never fired within 10 minutes of startup (likely blocked by OpenClaw's security policy), the plugin logs a warning and appends a visible notice to every `memory_search` result so you know automatic write-back is disabled.
|
|
47
|
-
|
|
48
|
-
---
|
|
49
|
-
|
|
50
|
-
## Why A-MEM? (vs Traditional RAG) 🎯
|
|
51
|
-
|
|
52
|
-
| Dimension | Traditional RAG | A-MEM (Zettelkasten Graph) |
|
|
53
|
-
| :--------------------------- | :--------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
|
|
54
|
-
| **Retrieval Mode** | Single-vector similarity | **BM25 + Dense Vector Hybrid (RRF) + 2-hop Graph Expansion** |
|
|
55
|
-
| **Chinese Recall** | Character-level n-gram / single char split | **Jieba word segmentation for accurate CJK BM25 indexing** |
|
|
56
|
-
| **Fact Evolution** | Static chunking — cannot update historical entries | **Dynamic Attribute Evolution & Connection Strengthening** |
|
|
57
|
-
| **Temporal Conflicts** | Recalls contradictory facts simultaneously | **`is_active` soft-invalidation** shields outdated facts |
|
|
58
|
-
| **Memory Bloat** | Fragmented memories stack up infinitely | **Daily Consolidation** merges semantic duplicates |
|
|
59
|
-
| **Stale Memory Suppression** | High-retrieval old memories permanently outrank fresh ones | **Time-decayed heat boost** — age dampens retrieval_count influence |
|
|
60
|
-
| **Graph Noise** | N/A | **BFS Relevance Gate** filters low-similarity linked nodes |
|
|
61
|
-
| **Knowledge vs. Episodic** | All memories treated equally | **`note_type` field** separates durable knowledge from episodic events; knowledge notes skip consolidation merge and time-decay |
|
|
62
|
-
| **Topic-Based Recall** | Only similarity-based | **`topics` tags + `topicsFilter`** enables precise subject-level knowledge retrieval |
|
|
63
|
-
|
|
64
|
-
---
|
|
65
|
-
|
|
66
|
-
## What is A-MEM?
|
|
67
|
-
|
|
68
|
-
A-MEM is an advanced memory architecture for LLM agents inspired by the Zettelkasten method. Unlike traditional flat vector databases, A-MEM maintains memory as a living, self-evolving semantic graph:
|
|
69
|
-
|
|
70
|
-
1. **Note Construction** — On write, LLM extracts keywords, tags, a context summary, categorizes the note (Technical, Business, Personal, Project, Research, System, General), classifies it as `memory` (episodic) or `knowledge` (durable), and for knowledge notes extracts 1-5 `topics` subject tags.
|
|
71
|
-
2. **Link Generation** — Retrieves top-6 candidates; LLM judges whether to link bidirectionally (similarity > 0.3).
|
|
72
|
-
3. **Memory Evolution & Strengthening** — Up to 3 linked memories have their attributes evolved based on the new context, potentially triggering additional links.
|
|
73
|
-
4. **Hybrid Retrieval** — Fuses vector search (Transformers.js ONNX local `paraphrase-multilingual-MiniLM-L12-v2`, 384-dim) and BM25 using Reciprocal Rank Fusion (RRF), boosted by retrieval frequency (heat).
|
|
74
|
-
5. **2-hop BFS Graph Expansion** — After RRF top-K selection, BFS traverses the link graph up to 2 hops, appending up to 8 contextually linked notes that may be semantically distant but graph-connected. Each candidate passes an embedding relevance gate (cos-sim ≥ 0.25) before admission. This is the key architectural advantage over flat vector memory systems like mem0.
|
|
75
|
-
|
|
76
|
-
Academic Paper: _A-MEM: Agentic Memory for LLM Agents_ — [arXiv:2502.12110](https://arxiv.org/abs/2502.12110) (NeurIPS 2025)
|
|
77
|
-
|
|
78
|
-
---
|
|
79
|
-
|
|
80
|
-
## Architecture
|
|
81
|
-
|
|
82
|
-
```
|
|
83
|
-
OpenClaw Agent
|
|
84
|
-
│
|
|
85
|
-
├── memory_search(query) ──► openclaw-amem plugin (TypeScript, in-process)
|
|
86
|
-
└── memory_add(text) ──► │
|
|
87
|
-
▼
|
|
88
|
-
┌──────────────┼──────────────┐
|
|
89
|
-
▼ ▼ ▼
|
|
90
|
-
Qdrant Transformers.js LLM (Anthropic)
|
|
91
|
-
(vector store) (ONNX embed) (CRUD decision
|
|
92
|
-
:6333 384-dim local + link judgment
|
|
93
|
-
agent_id ISO + Jieba BM25 + evolution)
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
---
|
|
97
|
-
|
|
98
|
-
## Evolution Mechanism (Story 30)
|
|
99
|
-
|
|
100
|
-
When new memories are borderline-similar to existing ones (cosine similarity 0.72–0.85), A-MEM marks them `pending_merge` and routes them through an **LLM-driven evolution judgment** instead of simple deduplication. The LLM classifies the relationship between the old and new memory into one of four paths:
|
|
101
|
-
|
|
102
|
-
| Type | Meaning | Action |
|
|
103
|
-
| ------------ | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
|
|
104
|
-
| **EVOLVE** | New info deepens/updates the old memory (e.g. "wants to buy Model 3" → "decided on standard RWD Model 3") | Old note content updated, `evolution_history` appended, new note absorbed |
|
|
105
|
-
| **CONFLICT** | Old and new info contradict each other (e.g. "lives in Riverstone" vs "moved to Eastholm") | Both notes kept, both marked `conflict: true` |
|
|
106
|
-
| **EXPAND** | New info complements the old memory (e.g. "has a sister" + "sister works in finance in Northvale") | Content merged into old note, `evolution_history` appended, new note absorbed |
|
|
107
|
-
| **NEW** | Unrelated information, no real connection | Both notes kept as-is |
|
|
108
|
-
|
|
109
|
-
This is the key differentiator from mem0-style flat memory systems: memories **evolve** rather than being silently overwritten. The `evolution_history` field provides a full audit trail of how each memory changed over time.
|
|
110
|
-
|
|
111
|
-
---
|
|
112
|
-
|
|
113
|
-
## Quality Scoring & Auto-Review (Story 31)
|
|
114
|
-
|
|
115
|
-
A-MEM enforces quality at both **write time** and **periodic scan**:
|
|
116
|
-
|
|
117
|
-
### Write-Time Quality Gate
|
|
118
|
-
|
|
119
|
-
Every `memory_add` call passes through `checkQuality()` before any LLM or embedding work:
|
|
120
|
-
|
|
121
|
-
- **Content < 10 characters** → write rejected, error returned
|
|
122
|
-
- **Contains temporal signal words** (`待跑`, `等确认`, `昨日`, `明天完成`) → written with `ephemeral: true` flag
|
|
123
|
-
|
|
124
|
-
### Periodic Quality Scan
|
|
125
|
-
|
|
126
|
-
The `memory_quality_scan` tool scans the entire memory store and identifies:
|
|
127
|
-
|
|
128
|
-
| Reason | Condition |
|
|
129
|
-
| ------------------- | ------------------------------------------------------------ |
|
|
130
|
-
| `too_short` | Content < 10 characters (legacy notes that predate the gate) |
|
|
131
|
-
| `expired_ephemeral` | `ephemeral=true` and written > 7 days ago |
|
|
132
|
-
| `pending_conflict` | `conflict=true` (contradictory evolution detected) |
|
|
133
|
-
|
|
134
|
-
Flagged notes are patched with `low_quality: true` in Qdrant.
|
|
135
|
-
|
|
136
|
-
---
|
|
137
|
-
|
|
138
|
-
## Agent Isolation (Story 32)
|
|
139
|
-
|
|
140
|
-
Each OpenClaw agent gets its own private memory namespace. Memories written by `main` are not visible to `dev` or other agents by default.
|
|
141
|
-
|
|
142
|
-
### Mode A — Shared Collection (default)
|
|
143
|
-
|
|
144
|
-
All agents share one Qdrant collection (`amem_notes`), isolated by `agent_id` filter at query time:
|
|
145
|
-
|
|
146
|
-
| Scope | `agent_id` in Qdrant | `readers` | Visible to |
|
|
147
|
-
| ----------------- | -------------------- | ---------- | ---------------------- |
|
|
148
|
-
| Private (default) | `"main"` | `["main"]` | Only the writing agent |
|
|
149
|
-
| Shared | `"shared"` | `["*"]` | All agents |
|
|
150
|
-
|
|
151
|
-
### Mode B — Dedicated Collection
|
|
152
|
-
|
|
153
|
-
Each agent gets a physically isolated Qdrant collection:
|
|
154
|
-
|
|
155
|
-
```json
|
|
156
|
-
"agents": {
|
|
157
|
-
"dev": {
|
|
158
|
-
"agentId": "dev",
|
|
159
|
-
"collection": "amem_notes_dev"
|
|
160
|
-
}
|
|
161
|
-
}
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
In Mode B, `dev` reads and writes only `amem_notes_dev`. Shared notes written by `main` are not visible to `dev` (no cross-collection sharing).
|
|
165
|
-
|
|
166
|
-
### Access fields on every note
|
|
167
|
-
|
|
168
|
-
Every `MemoryNote` carries three access fields:
|
|
169
|
-
|
|
170
|
-
```ts
|
|
171
|
-
{
|
|
172
|
-
owner: "main", // the agent that wrote this note
|
|
173
|
-
readers: ["main"], // ["*"] = all agents; ["main"] = private
|
|
174
|
-
writers: ["main"] // writers enforcement: Story 33
|
|
175
|
-
}
|
|
176
|
-
```
|
|
177
|
-
|
|
178
|
-
### Design rationale
|
|
179
|
-
|
|
180
|
-
amem uses an **explicit** `agent_id="shared"` marker rather than mem0's implicit null-scoping (omitting `agent_id` to indicate shared access). Per [arXiv:2604.16548], isolation should be the default; sharing is an explicit, auditable exception. amem's approach makes shared notes immediately identifiable in the database.
|
|
181
|
-
|
|
182
|
-
Consolidation runs per-agent scope: `dev`'s consolidation never touches `main`'s private notes or shared notes.
|
|
183
|
-
|
|
184
|
-
---
|
|
29
|
+
→ Full feature list & internals: **[amem-core README](../amem-core)** · **[docs](https://amem.owo.lc)**.
|
|
185
30
|
|
|
186
31
|
## Requirements
|
|
187
32
|
|
|
188
33
|
- OpenClaw v2026.4+
|
|
189
|
-
- Node.js 18+
|
|
34
|
+
- Node.js 24 (18+ works; 24/26 supported)
|
|
190
35
|
- Qdrant running on `:6333`
|
|
191
|
-
- Anthropic API key (`ANTHROPIC_API_KEY`
|
|
192
|
-
|
|
193
|
-
---
|
|
36
|
+
- Anthropic API key (`ANTHROPIC_API_KEY`) — or set `AMEM_LLM_BASE_URL` for a compatible proxy
|
|
194
37
|
|
|
195
38
|
## Installation
|
|
196
39
|
|
|
@@ -203,11 +46,9 @@ openclaw plugins install clawhub:@heichaowo/openclaw-amem
|
|
|
203
46
|
# From npm
|
|
204
47
|
openclaw plugins install openclaw-amem
|
|
205
48
|
|
|
206
|
-
# From
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
# From local checkout
|
|
210
|
-
openclaw plugins install --link ./openclaw-amem
|
|
49
|
+
# From a local checkout of the amem monorepo
|
|
50
|
+
pnpm --filter openclaw-amem build
|
|
51
|
+
openclaw plugins install --link ./packages/openclaw-amem
|
|
211
52
|
```
|
|
212
53
|
|
|
213
54
|
### 2. Configure `~/.openclaw/openclaw.json`
|
|
@@ -234,7 +75,7 @@ Add `openclaw-amem` to your allowed plugins and hook it into the `memory` slot:
|
|
|
234
75
|
}
|
|
235
76
|
```
|
|
236
77
|
|
|
237
|
-
> **⚠️ Memory slot conflict:** If your `openclaw.json` already assigns the `memory` slot to another plugin (e.g. `memory-core`), you **must** change it to `openclaw-amem`. The gateway only loads one plugin per slot — any additional `memory`-kind plugins are **silently skipped
|
|
78
|
+
> **⚠️ Memory slot conflict:** If your `openclaw.json` already assigns the `memory` slot to another plugin (e.g. `memory-core`), you **must** change it to `openclaw-amem`. The gateway only loads one plugin per slot — any additional `memory`-kind plugins are **silently skipped**. Set `"memory-core": { "enabled": false }` in `entries` to disable the old plugin.
|
|
238
79
|
|
|
239
80
|
### 3. Restart OpenClaw
|
|
240
81
|
|
|
@@ -242,113 +83,41 @@ Add `openclaw-amem` to your allowed plugins and hook it into the `memory` slot:
|
|
|
242
83
|
openclaw gateway restart
|
|
243
84
|
```
|
|
244
85
|
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
## Plugin Configuration Reference
|
|
248
|
-
|
|
249
|
-
| Key | Type | Default | Description |
|
|
250
|
-
| ------------------------------- | ----------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
251
|
-
| `agentId` | `string` | `"main"` | Agent namespace for memory isolation |
|
|
252
|
-
| `topK` | `number` | `5` | Maximum memories to retrieve during search |
|
|
253
|
-
| `agents` | `Record<string, {agentId?, collection?}>` | `{}` | Per-agent overrides. Set `collection` for Mode B physical isolation. |
|
|
254
|
-
| `hooks.allowConversationAccess` | `boolean` | `false` | **Required** for automatic memory write-back. Must be set explicitly in `plugins.entries.openclaw-amem.hooks`; without it, the `agent_end` hook is silently blocked by OpenClaw's security policy. |
|
|
255
|
-
|
|
256
|
-
---
|
|
257
|
-
|
|
258
|
-
## Usage & Tools
|
|
259
|
-
|
|
260
|
-
Once installed, the plugin exposes the following capabilities:
|
|
261
|
-
|
|
262
|
-
### `memory_add`
|
|
263
|
-
|
|
264
|
-
Writes a new memory. Automatically evaluates exact-hash duplicate checks, runs LLM note construction, generates bidirectional links, and evaluates memory evolution.
|
|
265
|
-
|
|
266
|
-
```js
|
|
267
|
-
memory_add((text = 'vendor profile'))
|
|
268
|
-
```
|
|
269
|
-
|
|
270
|
-
### `memory_search`
|
|
271
|
-
|
|
272
|
-
Searches long-term memories using fused RRF (BM25 + Cosine similarity) with heat-based ranking and 2-hop BFS graph expansion.
|
|
273
|
-
|
|
274
|
-
```js
|
|
275
|
-
memory_search((query = 'database configuration'), (limit = 5))
|
|
276
|
-
```
|
|
86
|
+
## Configuration Reference
|
|
277
87
|
|
|
278
|
-
|
|
88
|
+
| Key | Type | Default | Description |
|
|
89
|
+
| ------------------------------- | ----------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
|
90
|
+
| `agentId` | `string` | `"main"` | Agent namespace for memory isolation |
|
|
91
|
+
| `topK` | `number` | `5` | Maximum memories to retrieve during search |
|
|
92
|
+
| `agents` | `Record<string, {agentId?, collection?}>` | `{}` | Per-agent overrides. Set `collection` for Mode B physical isolation. |
|
|
93
|
+
| `hooks.allowConversationAccess` | `boolean` | `false` | **Required** for automatic memory write-back. Without it, the `agent_end` hook is silently blocked by OpenClaw's security policy. |
|
|
279
94
|
|
|
280
|
-
|
|
95
|
+
## Tools
|
|
281
96
|
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
Exposes the memory consolidation tool to manually trigger category-based semantic deduplication and link cascading.
|
|
285
|
-
|
|
286
|
-
### `memory_quality_scan`
|
|
287
|
-
|
|
288
|
-
Scans all memories for quality issues (content < 10 chars, expired ephemeral notes > 7 days, unresolved conflicts) and generates an Obsidian-compatible review batch markdown file.
|
|
289
|
-
|
|
290
|
-
```js
|
|
291
|
-
memory_quality_scan() // auto-generates batch file in Obsidian vault
|
|
292
|
-
memory_quality_scan((outputPath = '/tmp/review.md')) // custom output path
|
|
293
|
-
```
|
|
97
|
+
Once installed, the plugin exposes five tools to the agent:
|
|
294
98
|
|
|
295
|
-
|
|
99
|
+
| Tool | What it does |
|
|
100
|
+
| --- | --- |
|
|
101
|
+
| `memory_add` | Write a memory — hash dedup, LLM note construction, bidirectional linking, evolution. |
|
|
102
|
+
| `memory_search` | Search via RRF (BM25 + cosine) with heat ranking + 2-hop BFS graph expansion. Accepts `topicsFilter`. |
|
|
103
|
+
| `memory_list` | Total active note count for the current agent namespace. |
|
|
104
|
+
| `memory_consolidate` | Manually trigger category-based semantic dedup + link cascading. |
|
|
105
|
+
| `memory_quality_scan` | Scan for low-quality/expired/conflicting notes → Obsidian-compatible review batch file. |
|
|
296
106
|
|
|
297
|
-
## Development
|
|
107
|
+
## Development
|
|
298
108
|
|
|
299
|
-
|
|
109
|
+
This package is part of the **[amem monorepo](../../)**. From the repo root:
|
|
300
110
|
|
|
301
111
|
```bash
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
npm run test # Run Vitest unit & integration tests
|
|
307
|
-
npm run check # Run entire validation suite (format + lint + test)
|
|
308
|
-
```
|
|
309
|
-
|
|
310
|
-
Test coverage spans embedding, storage, memory operations, tokenization, BFS gate, heat decay, quality gate, evolution mechanism, and agent isolation.
|
|
311
|
-
|
|
312
|
-
---
|
|
313
|
-
|
|
314
|
-
## References & Prior Work
|
|
315
|
-
|
|
316
|
-
This plugin implements and extends the following prior work:
|
|
317
|
-
|
|
318
|
-
| Reference | Role |
|
|
319
|
-
| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
320
|
-
| Xu et al., _A-MEM: Agentic Memory for LLM Agents_, NeurIPS 2025 · [arXiv:2502.12110](https://arxiv.org/abs/2502.12110) | Core architecture: note construction, link generation, memory evolution, RRF hybrid retrieval |
|
|
321
|
-
| Robertson & Zaragoza, _The Probabilistic Relevance Framework: BM25 and Beyond_, 2009 | BM25 ranking formula (k1=1.5, b=0.75) used in hybrid retrieval |
|
|
322
|
-
| Weller et al., _On the Theoretical Limitations of Embedding-Based Retrieval_, arXiv:2508.21038, 2025 | Motivation for BM25 hybrid: single-vector models cannot scale to combinatorial query complexity |
|
|
323
|
-
| Sun et al., _E5: Text Embeddings by Weakly Supervised Contrastive Pre-training_, arXiv:2212.03533, 2022 | Embedding model family reference for multilingual retrieval quality benchmarks |
|
|
324
|
-
| Sun et al., _Jieba Chinese Text Segmentation_ · [github.com/fxsjy/jieba](https://github.com/fxsjy/jieba) | Chinese word segmentation for BM25 (via `@node-rs/jieba`, Rust port) |
|
|
325
|
-
| Cormack et al., _Reciprocal Rank Fusion outperforms Condorcet and individual Rank Learning Methods_, SIGIR 2009 | RRF fusion formula used to merge BM25 and dense vector ranked lists |
|
|
326
|
-
| Chhikara et al., _Mem0: Building Production-Ready AI Agents with Scalable Long-Term Memory_, ECAI 2025 · [arXiv:2504.19413](https://arxiv.org/abs/2504.19413) | Multi-dimensional scope isolation (user_id/agent_id/run_id/app_id); amem's explicit shared marker vs mem0's implicit null-scoping |
|
|
327
|
-
| _Multi-Agent Memory from a Computer Architecture Perspective_, arXiv:2603.10062, 2026 | Private/shared/distributed memory hierarchy; access protocol design |
|
|
328
|
-
| _Security of Long-Term Memory in LLM Agents_, arXiv:2604.16548, 2026 | Isolation-by-default principle; explicit sharing as exception |
|
|
329
|
-
| Kerestecioglu et al., _Human-Inspired Memory Architecture for LLM Agents_, arXiv:2605.08538, Microsoft, 2026 | Sleep-phase consolidation design |
|
|
330
|
-
| _Governing Evolving Memory in LLM Agents: SSGM Framework_, arXiv:2603.11768, 2026 | Memory evolution taxonomy (EVOLVE/CONFLICT/EXPAND/NEW) |
|
|
331
|
-
| _Graph-based Agent Memory: Taxonomy, Techniques, and Applications_, arXiv:2602.05665, 2026 | Conflict detection in graph memory updates |
|
|
332
|
-
| _Memory in the LLM Era_, arXiv:2604.01707, 2026 | Memory operations taxonomy |
|
|
333
|
-
|
|
334
|
-
---
|
|
335
|
-
|
|
336
|
-
## Citation
|
|
337
|
-
|
|
338
|
-
If you use this memory system in your research, please cite the original A-MEM paper:
|
|
339
|
-
|
|
340
|
-
```bibtex
|
|
341
|
-
@inproceedings{xu2025amem,
|
|
342
|
-
title={A-Mem: Agentic Memory for LLM Agents},
|
|
343
|
-
author={Xu, Wujiang and Liang, Zujie and Mei, Kai and Gao, Hang and Tan, Juntao and Zhang, Yongfeng},
|
|
344
|
-
booktitle={Advances in Neural Information Processing Systems (NeurIPS)},
|
|
345
|
-
year={2025}
|
|
346
|
-
}
|
|
112
|
+
pnpm install
|
|
113
|
+
pnpm -r build # build all packages
|
|
114
|
+
pnpm --filter openclaw-amem build # build just the plugin
|
|
115
|
+
pnpm --filter openclaw-amem test # vitest (needs Qdrant on :6333)
|
|
347
116
|
```
|
|
348
117
|
|
|
349
|
-
|
|
118
|
+
## Docs & References
|
|
350
119
|
|
|
351
|
-
|
|
120
|
+
Full guides, architecture, and academic references: **[amem.owo.lc](https://amem.owo.lc)** · engine: **[amem-core](../amem-core)** · paper: [A-MEM (arXiv:2502.12110)](https://arxiv.org/abs/2502.12110).
|
|
352
121
|
|
|
353
122
|
## License
|
|
354
123
|
|