@icex-labs/openclaw-memory-engine 4.1.2 → 4.2.0

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.
Files changed (2) hide show
  1. package/README.md +140 -224
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,29 +1,32 @@
1
1
  # @icex-labs/openclaw-memory-engine
2
2
 
3
- > Persistent, structured memory for AI agents — inspired by MemGPT.
3
+ > Your agent remembers everything. Automatically.
4
4
 
5
5
  [![npm](https://img.shields.io/npm/v/@icex-labs/openclaw-memory-engine)](https://www.npmjs.com/package/@icex-labs/openclaw-memory-engine)
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
7
7
 
8
- An [OpenClaw](https://openclaw.ai) plugin that gives your agent 19 tools to manage its own memory — what to remember, what to recall, what to forget, and what patterns to notice.
8
+ An [OpenClaw](https://openclaw.ai) plugin that gives your agent persistent, structured memory. Every conversation is automatically captured — the agent doesn't need to do anything. No "let me save that" messages, no manual tool calls. Memory just happens.
9
9
 
10
10
  ---
11
11
 
12
12
  ## The Problem
13
13
 
14
- OpenClaw agents wake up fresh every session. Without persistent memory, they forget who you are, what you discussed, and what matters to you. Stuffing everything into a system prompt bloats the context window and degrades quality.
14
+ OpenClaw agents wake up fresh every session. They forget who you are, what you discussed, and what matters to you.
15
+
16
+ Previous solutions required the agent to manually call memory tools — but agents forget to do that too.
15
17
 
16
18
  ## The Solution
17
19
 
18
- Five-layer memory architecture inspired by [MemGPT/Letta](https://github.com/cpacker/MemGPT):
20
+ **Passive memory capture via hooks** + five-layer architecture inspired by [MemGPT/Letta](https://github.com/cpacker/MemGPT):
19
21
 
20
- 1. **Core Memory** (~500 tokens) — identity, relationship, preferences. Always loaded.
21
- 2. **Archival Memory** (unlimited) — facts with importance scoring. Hybrid semantic search.
22
- 3. **Knowledge Graph** — entity relations. "Who is my doctor?" → graph traversal.
23
- 4. **Episodic Memory** — conversation summaries. "What did we discuss last time?"
24
- 5. **Reflective Memory** — behavioral pattern analysis. "What topics dominate this week?"
22
+ 1. **Auto-Capture Hooks** — every message in/out is automatically analyzed and stored. Zero agent effort.
23
+ 2. **Core Memory** (~500 tokens) — identity, relationship, preferences. Always loaded.
24
+ 3. **Archival Memory** (unlimited) — facts with importance scoring. Hybrid semantic search.
25
+ 4. **Knowledge Graph** — entity relations, auto-extracted. "Who is my doctor?" → graph traversal.
26
+ 5. **Episodic Memory** — conversation summaries. "What did we discuss last time?"
27
+ 6. **Reflective Memory** — behavioral pattern analysis. Topic trends, mood shifts.
25
28
 
26
- The agent manages all five layers autonomously using 19 purpose-built tools.
29
+ The agent doesn't say "I'll remember that." It just remembers.
27
30
 
28
31
  ---
29
32
 
@@ -37,173 +40,157 @@ openclaw gateway restart
37
40
 
38
41
  ### What setup.sh does
39
42
 
40
- 1. **Interactive core memory setup** — prompts for name, location, role, relationship dynamic
41
- 2. **Legacy data migration** — detects existing MEMORY.md / daily logs and imports them into archival (with dedup)
42
- 3. **Platform scheduler** — installs daily maintenance (macOS LaunchAgent / Linux systemd / Windows schtasks)
43
- 4. **Config patching** — enables plugin in `openclaw.json`
44
- 5. **Agent instructions** — patches AGENTS.md with memory tool guide
43
+ 1. **Interactive core memory setup** — prompts for name, location, role, relationship
44
+ 2. **Legacy data migration** — detects existing MEMORY.md / daily logs, imports into archival with dedup
45
+ 3. **Data quality pass** — re-classifies entities, re-rates importance, extracts graph triples
46
+ 4. **Platform scheduler** — daily maintenance (macOS LaunchAgent / Linux systemd / Windows schtasks)
47
+ 5. **Config + agent instructions** — patches `openclaw.json` and `AGENTS.md`
45
48
  6. **Cron registration** — 4 automated jobs (reflection, consolidation, dedup, dashboard)
46
- 7. **Embedding backfill** — on next gateway restart, missing embeddings are auto-computed in background
49
+ 7. **Embedding backfill** — on next restart, missing embeddings auto-computed in background
47
50
 
48
51
  `--non-interactive` flag available for scripted installs.
49
52
 
50
53
  ---
51
54
 
52
- ## Architecture
55
+ ## How It Works
56
+
57
+ ### Passive Capture (Hooks)
58
+
59
+ ```
60
+ User sends message on Telegram/Discord/WhatsApp
61
+ │
62
+ ├─→ Hook: message:received
63
+ │ Content ≥ 20 chars? Not a greeting? Not already stored?
64
+ │ → Auto-store in archival (entity inferred, importance scored)
65
+ │ → Auto-extract knowledge graph triples
66
+ │ → Embedding computed in background
67
+ │
68
+ ├─→ Agent processes and replies
69
+ │
70
+ └─→ Hook: message:sent
71
+ Reply ≥ 50 chars? Not duplicate (60s window)?
72
+ → Auto-store agent reply
73
+
74
+ No tool calls needed. No "I'll remember that." Just memory.
75
+ ```
76
+
77
+ ### Dedup Safety
78
+
79
+ - **60-second content hash** — prevents duplicate captures from streaming/retry events
80
+ - **Keyword overlap check** — if agent already stored the same fact via manual `archival_insert`, hook skips it
81
+ - **Result:** exactly one copy of each fact, regardless of who stores it first
82
+
83
+ ### Multi-Agent Isolation
84
+
85
+ ```
86
+ Session key "agent:wife:telegram:..." → workspace-wife/
87
+ Session key "agent:main:telegram:..." → workspace/
88
+
89
+ Each agent's hooks + tools operate on their own workspace.
90
+ Zero cross-contamination. Automatic.
91
+ ```
53
92
 
54
- ### Memory Layers
93
+ ---
94
+
95
+ ## Architecture
55
96
 
56
97
  ```
57
98
  ┌──────────────────────────────────────────────────────────────────┐
58
99
  │ Agent Context Window │
59
100
  │ │
101
+ │ ┌─ Passive: Auto-Capture Hooks ──────────────────────────────┐ │
102
+ │ │ message:received → analyze → store fact + graph + embed │ │
103
+ │ │ message:sent → analyze → store reply (deduped) │ │
104
+ │ │ No agent action needed. Runs on every conversation. │ │
105
+ │ └────────────────────────────────────────────────────────────┘ │
106
+ │ │
60
107
  │ ┌─ Layer 1: Core Memory ─────────────────────────────────────┐ │
61
108
  │ │ core_memory_read() → core.json (~500 tokens) │ │
62
109
  │ │ Identity, relationship, preferences, current_focus │ │
63
- │ │ Agent reads on session start, updates atomically │ │
64
110
  │ └────────────────────────────────────────────────────────────┘ │
65
111
  │ │
66
112
  │ ┌─ Layer 2: Archival Memory ─────────────────────────────────┐ │
67
- │ │ archival_insert(fact, entity, tags, importance) │ │
68
113
  │ │ archival_search(query) → hybrid 5-signal ranking │ │
69
- │ │ Unlimited JSONL. Each record: content + entity + tags + │ │
70
- │ │ importance (1-10) + access tracking + embedding vector │ │
114
+ │ │ Unlimited JSONL. Auto-populated by hooks. │ │
71
115
  │ └────────────────────────────────────────────────────────────┘ │
72
116
  │ │
73
117
  │ ┌─ Layer 3: Knowledge Graph ─────────────────────────────────┐ │
74
- │ │ graph_query(entity, relation?, depth?) │ │
75
- │ │ Triple store: (subject, relation, object) │ │
76
- │ │ Auto-extracted from archival_insert content │ │
77
- │ │ "who is my doctor?" → User→has_doctor→Dr. Smith │ │
118
+ │ │ graph_query(entity) → traverse relations │ │
119
+ │ │ Auto-extracted from every captured message. │ │
78
120
  │ └────────────────────────────────────────────────────────────┘ │
79
121
  │ │
80
122
  │ ┌─ Layer 4: Episodic Memory ─────────────────────────────────┐ │
81
- │ │ episode_save(summary, decisions, mood, topics) │ │
82
- │ │ episode_recall(query) → hybrid search over conversations │ │
83
- │ │ "what did we discuss about the car?" → full context │ │
123
+ │ │ episode_save / episode_recall │ │
124
+ │ │ Conversation summaries with decisions, mood, topics. │ │
84
125
  │ └────────────────────────────────────────────────────────────┘ │
85
126
  │ │
86
127
  │ ┌─ Layer 5: Reflective Memory ───────────────────────────────┐ │
87
- │ │ memory_reflect(window_days) → pattern analysis report │ │
88
- │ │ Topic trends, time distribution, mood shifts, │ │
89
- │ │ neglected entities, forgetting candidates │ │
128
+ │ │ memory_reflect → pattern analysis report │ │
129
+ │ │ Topic trends, time distribution, mood shifts. │ │
90
130
  │ └────────────────────────────────────────────────────────────┘ │
91
131
  └──────────────────────────────────────────────────────────────────┘
92
132
  ```
93
133
 
94
- ### Data Flow
95
-
96
- ```
97
- User says something important
98
- │
99
- ▼
100
- archival_insert(content, entity, tags, importance)
101
- │
102
- ├──→ archival.jsonl (append fact)
103
- ├──→ graph.jsonl (auto-extract relations)
104
- └──→ embeddings cache (background, async)
105
-
106
- User asks a question
107
- │
108
- ▼
109
- archival_search(query)
110
- │
111
- ├──→ Keyword matching (2× weight per term)
112
- ├──→ Embedding cosine similarity (5× weight)
113
- ├──→ Recency boost (0-1, decays over 1 year)
114
- ├──→ Access frequency boost (0-0.5)
115
- └──→ Importance × forgetting curve (0.5× weight)
116
-
117
- End of conversation
118
- │
119
- ▼
120
- episode_save(summary, decisions, mood)
121
- │
122
- └──→ episodes.jsonl + embedding
123
-
124
- Gateway restart
125
- │
126
- ▼
127
- Auto-detect missing embeddings across ALL workspaces
128
- │
129
- └──→ Batch backfill (100/batch, 200ms rate limit, crash-safe)
130
- ```
131
-
132
- ### Multi-Agent Isolation
133
-
134
- ```
135
- openclaw.json
136
- agents:
137
- ├── main → workspace/ ← Agent A's memory (2700+ records)
138
- ├── wife → workspace-wife/ ← Agent B's memory (300+ records)
139
- └── discord → workspace/ ← Shares Agent A's memory
140
-
141
- Plugin uses ToolFactory pattern:
142
- ctx.sessionKey = "agent:wife:telegram:..."
143
- ↓
144
- extractAgentId() → "wife"
145
- ↓
146
- openclaw.json lookup → workspace-wife/
147
- ↓
148
- All 19 tools bound to correct workspace via closure
149
- ```
134
+ ---
150
135
 
151
- Each agent's tools are bound to its own workspace at registration time. No cross-contamination. Privacy flag `"sharing": false` available for multi-user setups.
136
+ ## Tools (20) + Hooks (2)
152
137
 
153
- ---
138
+ ### Hooks (Passive — No Agent Action)
154
139
 
155
- ## Tools (19)
140
+ | Hook | Trigger | What it does |
141
+ |------|---------|-------------|
142
+ | `memory-engine-capture-received` | Every incoming message | Auto-stores facts, infers entity + importance, extracts graph triples |
143
+ | `memory-engine-capture-sent` | Every agent reply | Auto-stores replies (deduped, 60s window) |
156
144
 
157
- ### Core Memory — Identity (3)
145
+ ### Core Memory (3 tools)
158
146
 
159
147
  | Tool | Description |
160
148
  |------|-------------|
161
149
  | `core_memory_read` | Load identity block. Call every session start. |
162
- | `core_memory_replace` | Update a field by dot-path (e.g., `user.location`). Auto-parses JSON strings. 3KB hard limit. |
163
- | `core_memory_append` | Append to an array field (e.g., `current_focus`). |
150
+ | `core_memory_replace` | Update field by dot-path. Auto-parses JSON strings. 3KB limit. |
151
+ | `core_memory_append` | Append to array field. |
164
152
 
165
- ### Archival Memory — Facts (5)
153
+ ### Archival Memory (5 tools)
166
154
 
167
155
  | Tool | Description |
168
156
  |------|-------------|
169
- | `archival_insert` | Store a fact with entity, tags, and importance (1-10). Auto-extracts knowledge graph triples. Embedding computed in background. |
157
+ | `archival_insert` | Manually store a fact (only needed for non-conversation sources). |
170
158
  | `archival_search` | Hybrid 5-signal search: keyword + semantic + recency + access + importance. |
171
- | `archival_update` | Correct an existing record by ID. Re-indexes embedding. |
172
- | `archival_delete` | Remove an outdated record. Cleans embedding cache. |
173
- | `archival_stats` | Record count, entity/tag distribution, embedding coverage, storage size. |
159
+ | `archival_update` | Correct an existing record. |
160
+ | `archival_delete` | Remove outdated record. |
161
+ | `archival_stats` | Record count, entity/tag distribution, embedding coverage. |
174
162
 
175
- ### Knowledge Graph — Relations (2)
163
+ ### Knowledge Graph (2 tools)
176
164
 
177
165
  | Tool | Description |
178
166
  |------|-------------|
179
- | `graph_query` | Traverse from entity with depth control. Answers relational questions. |
180
- | `graph_add` | Manually add a relation triple `(subject, relation, object)`. |
181
-
182
- Auto-extraction patterns on `archival_insert`: has_doctor, lives_in, has_condition, treated_by, owns, works_at, attends, price, has_lawyer, spouse, has_child.
167
+ | `graph_query` | Traverse entity relations with depth control. |
168
+ | `graph_add` | Manually add a relation triple. |
183
169
 
184
- ### Episodic Memory — Conversations (2)
170
+ ### Episodic Memory (2 tools)
185
171
 
186
172
  | Tool | Description |
187
173
  |------|-------------|
188
- | `episode_save` | Save conversation summary with decisions, mood, topics, participants. |
189
- | `episode_recall` | Search past conversations by topic/keyword, or get recent N. Hybrid search with embedding. |
174
+ | `episode_save` | Save conversation summary with decisions, mood, topics. |
175
+ | `episode_recall` | Search past conversations by topic or get recent N. |
190
176
 
191
- ### Intelligence (3)
177
+ ### Intelligence (4 tools)
192
178
 
193
179
  | Tool | Description |
194
180
  |------|-------------|
195
- | `memory_reflect` | Statistical analysis: topic frequency, time-of-day distribution, mood trend, importance distribution, neglected entities, forgetting candidates. Configurable window (7/14/30 days). |
196
- | `archival_deduplicate` | Find near-duplicates via embedding cosine similarity (≥0.92 threshold). Preview or auto-remove. |
197
- | `memory_consolidate` | Extract structured facts from text blocks. Sentence-level splitting (Chinese + English), generic entity inference, keyword dedup against existing records. |
181
+ | `memory_reflect` | Analyze behavioral patterns over configurable time window. |
182
+ | `archival_deduplicate` | Find/remove near-duplicates via embedding cosine similarity. |
183
+ | `memory_consolidate` | Extract structured facts from text blocks. |
184
+ | `memory_quality` | Re-classify entities, re-rate importance, extract missing graph triples. |
198
185
 
199
- ### Backup & Admin (4)
186
+ ### Backup & Admin (4 tools)
200
187
 
201
188
  | Tool | Description |
202
189
  |------|-------------|
203
- | `memory_export` | Full snapshot: core + archival + embeddings → single JSON file. Versioned format. |
204
- | `memory_import` | Restore from snapshot. `merge` (add missing) or `replace` (overwrite) mode. |
205
- | `memory_migrate` | Migrate from JSONL to SQLite with FTS5 full-text search. Preserves JSONL as backup. |
206
- | `memory_dashboard` | Generate self-contained HTML dashboard: facts (searchable), graph, episodes, core memory, reflection report. Dark theme. |
190
+ | `memory_export` | Full snapshot → JSON file. |
191
+ | `memory_import` | Restore with merge or replace mode. |
192
+ | `memory_migrate` | JSONL → SQLite with FTS5. |
193
+ | `memory_dashboard` | Generate browsable HTML dashboard. |
207
194
 
208
195
  ---
209
196
 
@@ -214,26 +201,24 @@ Auto-extraction patterns on `archival_insert`: has_doctor, lives_in, has_conditi
214
201
  | Signal | Weight | Description |
215
202
  |--------|--------|-------------|
216
203
  | Keyword | 2× per term | Term presence in content + entity + tags |
217
- | Semantic | 5× | Cosine similarity via OpenAI `text-embedding-3-small` (512 dimensions) |
218
- | Recency | 0–1 | Linear decay over 1 year from creation date |
219
- | Access | 0–0.5 | Boost for recently accessed records (decays over 180 days) |
220
- | Importance | 0.5× | Forgetting curve: `importance × e^(-0.01 × days_since_access)` |
204
+ | Semantic | 5× | Cosine similarity via OpenAI `text-embedding-3-small` (512d) |
205
+ | Recency | 0–1 | Linear decay over 1 year |
206
+ | Access | 0–0.5 | Boost for recently accessed records |
207
+ | Importance | 0.5× | Forgetting curve: `importance × e^(-0.01 × days)` |
221
208
 
222
- Falls back to keyword-only if no OpenAI key is configured — no errors, just reduced quality. Cost with embeddings: ~$0.001/session for search, ~$0.02/1M tokens for batch indexing.
209
+ Falls back to keyword-only without OpenAI key. Cost: ~$0.001/session.
223
210
 
224
211
  ---
225
212
 
226
213
  ## Self-Healing
227
214
 
228
- The plugin automatically detects and fixes issues on gateway restart:
229
-
230
215
  | Issue | Auto-fix |
231
216
  |-------|----------|
232
- | Missing embeddings after migration | Batch backfill across all workspaces (100/batch, rate limited) |
233
- | Core memory value serialized as JSON string | Auto-parse on `core_memory_replace` |
234
- | Near-duplicate facts accumulating | Weekly `archival_deduplicate` cron |
235
- | Daily logs piling up | Daily `memory-maintenance.sh` merges 7-day-old logs into weekly summaries |
236
- | Stale `current_focus` items | Agent prompted to update via `memory_reflect` analysis |
217
+ | Missing embeddings | Batch backfill on restart (all workspaces) |
218
+ | Agent forgets to save | Hooks capture everything passively |
219
+ | Duplicate facts | 60s dedup + keyword overlap + weekly cron |
220
+ | Flat importance scores | `memory_quality` pass after migration |
221
+ | General entity labels | `memory_quality` re-classifies with 50+ patterns |
237
222
 
238
223
  ---
239
224
 
@@ -268,41 +253,15 @@ Semantic search requires `OPENAI_API_KEY` in environment (optional — graceful
268
253
 
269
254
  ## Automated Maintenance
270
255
 
271
- ### Cron Jobs (registered by setup.sh)
272
-
273
256
  | Schedule | Job | Description |
274
257
  |----------|-----|-------------|
275
- | Daily 9:00am | `memory-reflect-daily` | Analyze patterns, store observations |
276
- | Every 6h | `memory-consolidate-6h` | Extract missed facts from daily logs |
277
- | Weekly Sunday 4am | `memory-dedup-weekly` | Clean near-duplicate records |
278
- | Daily 9:30am | `memory-dashboard-daily` | Refresh browsable HTML dashboard |
279
-
280
- ### File Maintenance (daily 3am)
281
-
282
- | Action | Trigger | Description |
283
- |--------|---------|-------------|
284
- | Size check | MEMORY.md >4KB | Warn alert |
285
- | Size check | MEMORY.md >5KB | Critical alert |
286
- | Log merge | Daily logs >7 days old | Merge into weekly summaries |
287
- | Archive | Weekly summaries >60 days | Move to archive/ |
288
- | Topic check | Topic file >8KB | Warn alert |
289
-
290
- Alerts written to `memory/maintenance-alerts.json`, checked by agent during heartbeats.
291
-
292
- ---
293
-
294
- ## Storage Files
258
+ | Every 6h | Consolidate | Extract missed facts from daily logs |
259
+ | Daily 9am | Reflect | Analyze patterns, store observations |
260
+ | Daily 9:30am | Dashboard | Refresh browsable HTML report |
261
+ | Weekly Sunday | Dedup | Clean near-duplicate records |
262
+ | Daily 3am | File cleanup | Merge old logs, archive old summaries |
295
263
 
296
- | File | Purpose | Growth | Format |
297
- |------|---------|--------|--------|
298
- | `memory/core.json` | Identity block | Fixed ~1-3KB | JSON |
299
- | `memory/archival.jsonl` | Fact storage | Grows with usage | JSONL |
300
- | `memory/graph.jsonl` | Knowledge graph | Grows with relations | JSONL |
301
- | `memory/episodes.jsonl` | Conversation summaries | Grows per conversation | JSONL |
302
- | `memory/archival.embeddings.json` | Embedding vectors | ~2KB per record | JSON |
303
- | `memory/memory.sqlite` | SQLite index (optional) | After `memory_migrate` | SQLite |
304
- | `memory/dashboard.html` | Browsable report | Regenerated daily | HTML |
305
- | `memory/maintenance-alerts.json` | Health alerts | Regenerated daily | JSON |
264
+ Per-agent crons auto-registered for agents with separate workspaces.
306
265
 
307
266
  ---
308
267
 
@@ -310,85 +269,42 @@ Alerts written to `memory/maintenance-alerts.json`, checked by agent during hear
310
269
 
311
270
  ```
312
271
  memory-engine/
313
- ├── index.js # Plugin entry — 19 tools via ToolFactory pattern
272
+ ├── index.js # Plugin entry: 20 tools + 2 hooks (ToolFactory pattern)
314
273
  ├── lib/
315
- │ ├── paths.js # Constants, multi-workspace resolution, agent mapping
316
- │ ├── core.js # Core memory CRUD + dot-path + auto-parse
274
+ │ ├── paths.js # Constants, multi-workspace resolution
275
+ │ ├── core.js # Core memory CRUD + auto-parse
317
276
  │ ├── archival.js # JSONL storage + in-memory cache
318
277
  │ ├── embedding.js # OpenAI embedding API + cache + batch backfill
319
278
  │ ├── search.js # Hybrid 5-signal search with forgetting curve
320
- │ ├── graph.js # Knowledge graph: triple store + traversal + auto-extract
321
- │ ├── episodes.js # Episodic memory: save + hybrid recall
322
- │ ├── reflection.js # Statistical pattern analysis (8 dimensions)
323
- │ ├── consolidate.js # Text → structured facts (sentence split + entity inference)
324
- │ ├── dedup.js # Embedding cosine similarity deduplication
325
- │ ├── backup.js # Export / import with format versioning
326
- │ ├── store-sqlite.js # SQLite backend with FTS5 + WAL mode
327
- │ └── dashboard.js # Self-contained HTML dashboard generator
279
+ │ ├── graph.js # Knowledge graph: triples + traversal + auto-extract
280
+ │ ├── episodes.js # Episodic memory: save + recall
281
+ │ ├── reflection.js # Statistical pattern analysis
282
+ │ ├── consolidate.js # Text → facts extraction
283
+ │ ├── dedup.js # Embedding similarity dedup
284
+ │ ├── backup.js # Export / import
285
+ │ ├── store-sqlite.js # SQLite backend (FTS5)
286
+ │ ├── dashboard.js # HTML dashboard generator
287
+ │ ├── quality.js # Data quality: entity + importance + graph
288
+ │ └── auto-capture.js # Passive hooks: message → archival
328
289
  ├── extras/
329
- │ ├── memory-maintenance.sh # Daily file cleanup script
330
- │ ├── migrate-legacy.mjs # Standalone legacy data migration tool
290
+ │ ├── memory-maintenance.sh
291
+ │ ├── migrate-legacy.mjs
331
292
  │ └── auto-consolidation-crons.json
332
- ├── setup.sh # One-command install (interactive, cross-platform)
333
- ├── .claude/CLAUDE.md # Development guide for Claude Code
334
- ├── ROADMAP.md # Planned features
335
- ├── openclaw.plugin.json # Plugin manifest with config schema
293
+ ├── setup.sh
294
+ ├── openclaw.plugin.json
336
295
  └── package.json
337
296
  ```
338
297
 
339
- ---
340
-
341
- ## Migrating from File-Based Memory
342
-
343
- If you already have MEMORY.md and daily log files, `setup.sh` handles migration automatically:
344
-
345
- ```
346
- 📦 Found 15 legacy memory files.
347
- Migrate into archival memory? [Y/n]: Y
348
- MEMORY.md: +87 facts
349
- 2026-03-28.md: +42 facts
350
- 2026-03-30.md: +29 facts
351
- ✅ Migration complete: 158 facts imported, 3 skipped
352
- ```
353
-
354
- Manual migration: `node ~/.openclaw/extensions/memory-engine/extras/migrate-legacy.mjs [workspace_path]`
355
-
356
- After migration, embeddings are auto-computed on next gateway restart (no manual step needed).
357
-
358
- ---
359
-
360
298
  ## Platforms
361
299
 
362
- | Platform | Maintenance Scheduler | Status |
363
- |----------|----------------------|--------|
300
+ | Platform | Scheduler | Status |
301
+ |----------|----------|--------|
364
302
  | macOS | LaunchAgent | Full support |
365
- | Linux | systemd user timer | Full support |
303
+ | Linux | systemd timer | Full support |
366
304
  | Windows | schtasks | Guided setup |
367
305
 
368
306
  ---
369
307
 
370
- ## Roadmap
371
-
372
- See [ROADMAP.md](ROADMAP.md) for details.
373
-
374
- - [x] Core memory with size guard + auto-parse
375
- - [x] Archival CRUD + hybrid 5-signal search
376
- - [x] Knowledge graph with auto-extraction
377
- - [x] Episodic memory with conversation recall
378
- - [x] Importance scoring + forgetting curves
379
- - [x] Behavioral reflection + auto-consolidation
380
- - [x] SQLite backend (FTS5) + HTML dashboard
381
- - [x] Multi-workspace isolation (ToolFactory pattern)
382
- - [x] Legacy data migration + embedding auto-backfill
383
- - [x] Cross-platform support (macOS / Linux / Windows)
384
- - [ ] LanceDB vector-native backend
385
- - [ ] Memory importance auto-rating via LLM
386
- - [ ] Web dashboard served via gateway HTTP route
387
-
388
- ---
389
-
390
308
  ## License
391
309
 
392
- MIT
393
-
394
- Built for [OpenClaw](https://openclaw.ai). Inspired by [MemGPT/Letta](https://github.com/cpacker/MemGPT).
310
+ MIT — Built for [OpenClaw](https://openclaw.ai). Inspired by [MemGPT/Letta](https://github.com/cpacker/MemGPT).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@icex-labs/openclaw-memory-engine",
3
- "version": "4.1.2",
3
+ "version": "4.2.0",
4
4
  "description": "MemGPT-style hierarchical memory plugin for OpenClaw — core memory block + archival storage with semantic search",
5
5
  "type": "module",
6
6
  "main": "index.js",