@claude-flow/memory 3.0.0-alpha.18 → 3.0.0-alpha.19
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 +858 -647
- package/dist/agentdb-backend.js +26 -26
- package/dist/auto-memory-bridge.d.ts +12 -1
- package/dist/auto-memory-bridge.d.ts.map +1 -1
- package/dist/auto-memory-bridge.js +45 -5
- package/dist/auto-memory-bridge.js.map +1 -1
- package/dist/auto-memory-bridge.test.js +92 -33
- package/dist/auto-memory-bridge.test.js.map +1 -1
- package/dist/sqlite-backend.js +79 -79
- package/dist/sqljs-backend.js +36 -36
- package/package.json +48 -48
package/README.md
CHANGED
|
@@ -1,647 +1,858 @@
|
|
|
1
|
-
# @claude-flow/memory
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/@claude-flow/memory)
|
|
4
|
-
[](https://www.npmjs.com/package/@claude-flow/memory)
|
|
4
|
+
[](https://github.com/ruvnet/ruflo/blob/main/data/clone-data.proof.json)
|
|
5
|
+
[](https://github.com/ruvnet/ruflo/blob/main/data/clone-data.ledger.json)
|
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
|
7
|
+
[](https://www.typescriptlang.org/)
|
|
8
|
+
[](./benchmarks/results/)
|
|
9
|
+
|
|
10
|
+
> High-performance memory for Claude Flow V3 — one canonical `MemoryService` API on top of a real hybrid backend (sql.js + AgentDB), persistent HNSW vector search that survives restart, a memory-bound consolidator, graceful keyword (FTS5) fallback when the embedder isn't available, plus the AutoMemoryBridge, self-learning, and knowledge-graph layers that build on top.
|
|
11
|
+
|
|
12
|
+
## What's new in `3.0.0-alpha.18` (ADR-125)
|
|
13
|
+
|
|
14
|
+
This release closes out [ADR-125 — Memory Consolidation](../../../v3/docs/adr/ADR-125-memory-consolidation.md). If you're upgrading from `3.0.0-alpha.17` or earlier, this is the headline:
|
|
15
|
+
|
|
16
|
+
- **One canonical entry point.** `MemoryService` replaces the old `UnifiedMemoryService` name (both still exported — the old one is `@deprecated` and will be removed at `3.0.0-rc`). See [Migration](#migrating-from-30-0-alpha-17-or-earlier) below.
|
|
17
|
+
- **A real hybrid default.** `createHybridService(...)` finally returns a service whose backend is an actual `HybridBackend` (sql.js + AgentDB). Earlier releases silently downgraded this to AgentDB-only — ADR-009's promise wasn't delivered until now.
|
|
18
|
+
- **Persistent HNSW.** Closing a service snapshots its HNSW index to a sidecar (`<dbPath>.hnsw` + `<dbPath>.meta.json`). Reopening on the same path restores in milliseconds rather than rebuilding from scratch — search-ready cold start.
|
|
19
|
+
- **`MemoryConsolidator`.** A background service that evicts expired entries from indexes *and* HNSW, deduplicates by content hash, and rebuilds the HNSW index when it gets fragmented. Auto-runs on a configurable timer (default 6 hours) so memory stays bounded.
|
|
20
|
+
- **Graceful retrieval.** `service.search('query')` no longer throws when `@claude-flow/embeddings` is unavailable — it degrades to FTS5 keyword search and emits `health.embedder = 'degraded'`. The full hybrid path also adds real Reciprocal Rank Fusion + MMR diversity rerank.
|
|
21
|
+
- **Reproducible benchmarks.** `npm run bench` now actually runs. The HNSW search baseline (single-threaded, 1k × 128-dim cosine vectors on Apple Silicon, Node 22): **0.53 ms / search · 1,889 ops/s · 533 ms to build 1k**. See [`benchmarks/results/baseline-20260519T212453Z.md`](./benchmarks/results/baseline-20260519T212453Z.md).
|
|
22
|
+
- **Node 26 install support** ([#1867](https://github.com/ruvnet/ruflo/issues/1867)) — `better-sqlite3` is fully optional; installs succeed on Node 24/26 and the package falls back to sql.js when the native build isn't available.
|
|
23
|
+
|
|
24
|
+
## Features
|
|
25
|
+
|
|
26
|
+
- **Canonical `MemoryService` API** — one entry point for store / retrieve / search / hybrid query
|
|
27
|
+
- **Real hybrid backend** — `HybridBackend` (sql.js + AgentDB) for structured + vector queries (ADR-009 / ADR-125 Phase 2)
|
|
28
|
+
- **Persistent HNSW** — index survives `close()` and restart; auto-snapshots every Nth write (ADR-125 Phase 3)
|
|
29
|
+
- **`MemoryConsolidator`** — `sweepExpired()` + `dedup()` + `compactHnsw()` + auto-run timer (ADR-125 Phase 4)
|
|
30
|
+
- **Graceful retrieval** — automatic FTS5 keyword fallback when embedder is unreachable; RRF + MMR for hybrid (ADR-125 Phase 5)
|
|
31
|
+
- **HNSW vector search** — measured **0.53 ms / search at 1k × 128 dim** on Apple Silicon; see baseline above
|
|
32
|
+
- **Auto Memory Bridge** — Bidirectional sync between Claude Code auto memory and AgentDB (ADR-048)
|
|
33
|
+
- **Self-Learning** — LearningBridge connects insights to SONA/ReasoningBank neural pipeline (ADR-049)
|
|
34
|
+
- **Knowledge Graph** — PageRank + label propagation community detection over memory entries (ADR-049)
|
|
35
|
+
- **Agent-Scoped Memory** — 3-scope agent memory (project/local/user) with cross-agent knowledge transfer (ADR-049)
|
|
36
|
+
- **Vector Quantization** — Binary, scalar, and product quantization for 4–32x memory reduction
|
|
37
|
+
- **Multiple Distance Metrics** — Cosine, Euclidean, dot product, and Manhattan
|
|
38
|
+
- **Query Builder** — Fluent API for building complex memory queries
|
|
39
|
+
- **Cache Manager** — LRU caching with configurable size and TTL
|
|
40
|
+
- **Migration Tools** — `MemoryMigrator` for moving from V2 memory systems
|
|
41
|
+
- **Cross-platform** — Works on Linux, macOS, and Windows; Node 18+ (including Node 24/26)
|
|
42
|
+
|
|
43
|
+
## Installation
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npm install @claude-flow/memory
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Standalone use (without the Ruflo CLI)
|
|
50
|
+
|
|
51
|
+
This package works on its own — you don't need `@claude-flow/cli` or the
|
|
52
|
+
full Ruflo install. Use it any time you want HNSW vector search, an
|
|
53
|
+
AgentDB façade, or the v3 controller registry from your own app.
|
|
54
|
+
|
|
55
|
+
Two recipes that exercise the most-installed surface:
|
|
56
|
+
|
|
57
|
+
### Recipe 1 — HNSW index with built-in quantization (no other deps)
|
|
58
|
+
|
|
59
|
+
```typescript
|
|
60
|
+
// recipe.mjs
|
|
61
|
+
import { HNSWIndex } from '@claude-flow/memory';
|
|
62
|
+
|
|
63
|
+
const index = new HNSWIndex({
|
|
64
|
+
dimensions: 8,
|
|
65
|
+
M: 16,
|
|
66
|
+
efConstruction: 200,
|
|
67
|
+
metric: 'cosine',
|
|
68
|
+
});
|
|
69
|
+
|
|
70
|
+
// Add a few vectors
|
|
71
|
+
await index.addPoint('doc-a', new Float32Array([1, 0, 0, 0, 0, 0, 0, 0]));
|
|
72
|
+
await index.addPoint('doc-b', new Float32Array([0.9, 0.1, 0, 0, 0, 0, 0, 0]));
|
|
73
|
+
await index.addPoint('doc-c', new Float32Array([0, 1, 0, 0, 0, 0, 0, 0]));
|
|
74
|
+
|
|
75
|
+
// Search — top 2 nearest to "doc-a"-shaped query
|
|
76
|
+
const hits = await index.search(new Float32Array([1, 0, 0, 0, 0, 0, 0, 0]), 2);
|
|
77
|
+
console.log(hits); // [{ id: 'doc-a', distance: 0 }, { id: 'doc-b', distance: ~0.005 }]
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
### Recipe 2 — Drive the controller registry against your own AgentDB
|
|
81
|
+
|
|
82
|
+
The registry coordinates 15+ memory controllers (learning bridge, memory
|
|
83
|
+
graph, tiered cache, vector backend, etc.) on top of an AgentDB instance
|
|
84
|
+
you own. Useful when you already have an AgentDB lifecycle and just
|
|
85
|
+
want the v3 governance layer (issue #2019 added the `agentdb` injection
|
|
86
|
+
field that makes this clean).
|
|
87
|
+
|
|
88
|
+
```typescript
|
|
89
|
+
import { ControllerRegistry } from '@claude-flow/memory';
|
|
90
|
+
import { AgentDB } from 'agentdb';
|
|
91
|
+
|
|
92
|
+
const agentdb = new AgentDB({ dbPath: ':memory:' });
|
|
93
|
+
await agentdb.initialize();
|
|
94
|
+
|
|
95
|
+
const registry = new ControllerRegistry();
|
|
96
|
+
await registry.initialize({ agentdb });
|
|
97
|
+
|
|
98
|
+
// Now everything backed by AgentDB is reachable through the registry
|
|
99
|
+
const reflexion = registry.get('reflexion'); // ReflexionMemory
|
|
100
|
+
const vectorBackend = registry.get('vectorBackend'); // live vector backend
|
|
101
|
+
const enabled = registry.isEnabled('skills'); // true
|
|
102
|
+
|
|
103
|
+
const health = await registry.healthCheck();
|
|
104
|
+
console.log(`${health.activeControllers}/${health.controllers.length} controllers active`);
|
|
105
|
+
|
|
106
|
+
await registry.shutdown();
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## Quick Start
|
|
110
|
+
|
|
111
|
+
The fastest way to get a full-featured memory service — hybrid backend, HNSW vector index, FTS5 keyword fallback, persistent snapshots, consolidation timer — is `createHybridService`:
|
|
112
|
+
|
|
113
|
+
```typescript
|
|
114
|
+
import { createHybridService } from '@claude-flow/memory';
|
|
115
|
+
|
|
116
|
+
async function embedder(text: string): Promise<Float32Array> {
|
|
117
|
+
// Use any embedding provider — OpenAI, @claude-flow/embeddings, your own model.
|
|
118
|
+
// If the embedder ever fails, MemoryService falls back to FTS5 keyword search
|
|
119
|
+
// automatically (emitting `health.embedder = 'degraded'`).
|
|
120
|
+
return new Float32Array(/* ... */);
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
const memory = await createHybridService('./data/memory.db', embedder, 1536);
|
|
124
|
+
await memory.initialize();
|
|
125
|
+
|
|
126
|
+
// Store an entry — content is embedded and added to both SQLite and HNSW
|
|
127
|
+
await memory.store({
|
|
128
|
+
key: 'auth-patterns',
|
|
129
|
+
content: 'OAuth 2.0 implementation patterns for secure authentication',
|
|
130
|
+
tags: ['auth', 'security', 'patterns'],
|
|
131
|
+
});
|
|
132
|
+
|
|
133
|
+
// Semantic search via HNSW
|
|
134
|
+
const similar = await memory.semanticSearch('user authentication best practices', 5);
|
|
135
|
+
|
|
136
|
+
// Keyword search via FTS5 (also used as the automatic fallback)
|
|
137
|
+
const exact = await memory.searchKeyword('OAuth 2.0', { limit: 10 });
|
|
138
|
+
|
|
139
|
+
// Hybrid search — RRF-fused dense + sparse, MMR-diversified
|
|
140
|
+
const blended = await memory.search('authentication patterns', { limit: 10 });
|
|
141
|
+
|
|
142
|
+
// Clean shutdown — flushes the consolidator timer and snapshots HNSW to disk
|
|
143
|
+
await memory.close();
|
|
144
|
+
|
|
145
|
+
// Reopen the same path — entries AND HNSW index are restored from sidecar
|
|
146
|
+
const reopened = await createHybridService('./data/memory.db', embedder, 1536);
|
|
147
|
+
await reopened.initialize();
|
|
148
|
+
// memory.search() is immediately fast — no rebuild
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
You can also use the lower-level primitives directly. `HNSWIndex` is exported and works without any of the service layer if you just want a vector index:
|
|
152
|
+
|
|
153
|
+
```typescript
|
|
154
|
+
import { HNSWIndex } from '@claude-flow/memory';
|
|
155
|
+
|
|
156
|
+
const index = new HNSWIndex({
|
|
157
|
+
dimensions: 1536, // OpenAI embedding size
|
|
158
|
+
M: 16, // Max connections per node
|
|
159
|
+
efConstruction: 200,
|
|
160
|
+
metric: 'cosine',
|
|
161
|
+
});
|
|
162
|
+
|
|
163
|
+
await index.addPoint('memory-1', new Float32Array(embedding));
|
|
164
|
+
await index.addPoint('memory-2', new Float32Array(embedding2));
|
|
165
|
+
|
|
166
|
+
const results = await index.search(queryVector, 10);
|
|
167
|
+
// [{ id: 'memory-1', distance: 0.05 }, { id: 'memory-2', distance: 0.12 }]
|
|
168
|
+
|
|
169
|
+
// New in 3.0.0-alpha.18: persist the index to a buffer for restore later
|
|
170
|
+
const snapshot: Buffer = index.serialize();
|
|
171
|
+
const restored = HNSWIndex.deserialize(snapshot);
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
## Migrating from `3.0.0-alpha.17` or earlier
|
|
175
|
+
|
|
176
|
+
If you're already using this package:
|
|
177
|
+
|
|
178
|
+
```typescript
|
|
179
|
+
// Before
|
|
180
|
+
import { UnifiedMemoryService } from '@claude-flow/memory';
|
|
181
|
+
const memory = new UnifiedMemoryService({ /* ... */ });
|
|
182
|
+
|
|
183
|
+
// After (recommended) — both names resolve to the same class
|
|
184
|
+
import { MemoryService } from '@claude-flow/memory';
|
|
185
|
+
const memory = new MemoryService({ /* ... */ });
|
|
186
|
+
|
|
187
|
+
// `UnifiedMemoryService` continues to work through 3.0.0-rc as a `@deprecated` alias.
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Two other things changed in `3.0.0-alpha.18`:
|
|
191
|
+
|
|
192
|
+
1. **`createHybridService` now does what its name says.** If you were relying on the old AgentDB-only downgrade, you'll get a real `HybridBackend` now — semantic search and structured queries both work without extra wiring.
|
|
193
|
+
2. **`semanticSearch` no longer throws when the embedder is absent.** Code that relied on a thrown error to detect a misconfigured embedder should listen for `health.embedder = 'degraded'` events instead. See [Graceful retrieval](#graceful-retrieval-fts5-fallback) below.
|
|
194
|
+
|
|
195
|
+
The `HnswLite` and `RvfBackend` classes are no longer top-level exports (they were internal implementation details). If your code imported them, switch to `HNSWIndex` (more capable, persistent) — they're verified to have zero external importers.
|
|
196
|
+
|
|
197
|
+
## Persistence
|
|
198
|
+
|
|
199
|
+
In `3.0.0-alpha.18` the HNSW index survives `close()` and restart. Snapshots happen automatically:
|
|
200
|
+
|
|
201
|
+
- On `service.close()`, the index is serialized to `<dbPath>.hnsw` and the in-memory entry/namespace/key/tag maps go to `<dbPath>.meta.json`.
|
|
202
|
+
- During the lifetime of the service, the index also auto-snapshots every Nth `store()` call (default `N=1000`, configurable via `MemoryServiceConfig.snapshotInterval`).
|
|
203
|
+
- On initialize, if both sidecars exist, they're restored. The service emits one of three `health.persistence` events: `'restored'` (success), `'fresh'` (no sidecar found — first run), or `'corrupt'` (deserialize failed — automatic fallback to fresh state).
|
|
204
|
+
|
|
205
|
+
```typescript
|
|
206
|
+
import { MemoryService, HNSWIndex } from '@claude-flow/memory';
|
|
207
|
+
|
|
208
|
+
const memory = new MemoryService({
|
|
209
|
+
persistenceEnabled: true,
|
|
210
|
+
persistencePath: './data/memory.db',
|
|
211
|
+
snapshotInterval: 500, // snapshot every 500 stores
|
|
212
|
+
embeddingGenerator,
|
|
213
|
+
});
|
|
214
|
+
|
|
215
|
+
memory.on('health.persistence', (status) => {
|
|
216
|
+
// 'restored' | 'fresh' | 'corrupt'
|
|
217
|
+
console.log('Persistence state:', status);
|
|
218
|
+
});
|
|
219
|
+
|
|
220
|
+
await memory.initialize();
|
|
221
|
+
// ...store, query...
|
|
222
|
+
await memory.close(); // flushes a final snapshot
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
Manual snapshot/restore on a raw `HNSWIndex`:
|
|
226
|
+
|
|
227
|
+
```typescript
|
|
228
|
+
const buf: Buffer = index.serialize();
|
|
229
|
+
// write buf to disk, transfer between processes, etc.
|
|
230
|
+
|
|
231
|
+
const restored = HNSWIndex.deserialize(buf);
|
|
232
|
+
// search works immediately — no rebuild
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
The serialized format is versioned with a magic header (`HNSW\x01`) — a corrupted or stale snapshot is detected and rejected loudly rather than silently producing wrong neighbors.
|
|
236
|
+
|
|
237
|
+
## Memory consolidation
|
|
238
|
+
|
|
239
|
+
`MemoryConsolidator` keeps the index bounded. Three operations:
|
|
240
|
+
|
|
241
|
+
```typescript
|
|
242
|
+
import { MemoryConsolidator } from '@claude-flow/memory';
|
|
243
|
+
|
|
244
|
+
const consolidator = new MemoryConsolidator(memory, {
|
|
245
|
+
dedupStrategy: 'merge-tags', // 'keep-newest' | 'keep-oldest' | 'merge-tags'
|
|
246
|
+
intervalMs: 6 * 60 * 60 * 1000, // auto-run every 6h
|
|
247
|
+
});
|
|
248
|
+
|
|
249
|
+
// Evict expired entries from all indexes (including HNSW)
|
|
250
|
+
const swept = await consolidator.sweepExpired();
|
|
251
|
+
// { removed: 142, remaining: 8503 }
|
|
252
|
+
|
|
253
|
+
// Deduplicate by SHA-256 content hash
|
|
254
|
+
const dedup = await consolidator.dedup('keep-newest');
|
|
255
|
+
// { merged: 23 }
|
|
256
|
+
|
|
257
|
+
// Rebuild HNSW to reclaim space after large churn
|
|
258
|
+
const compaction = await consolidator.compactHnsw();
|
|
259
|
+
// { before: 8503, after: 8503, durationMs: 198 }
|
|
260
|
+
|
|
261
|
+
// Or run all three in sequence
|
|
262
|
+
const result = await consolidator.runAll();
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
You don't have to construct it manually — `MemoryService` will wire it up if you opt in:
|
|
266
|
+
|
|
267
|
+
```typescript
|
|
268
|
+
const memory = new MemoryService({
|
|
269
|
+
consolidator: {
|
|
270
|
+
autoRun: true, // start a setInterval that runs runAll()
|
|
271
|
+
intervalMs: 6 * 60 * 60 * 1000, // every 6h (default)
|
|
272
|
+
},
|
|
273
|
+
});
|
|
274
|
+
|
|
275
|
+
memory.on('consolidation.complete', (result) => {
|
|
276
|
+
console.log(`Swept ${result.swept.removed}, deduped ${result.dedup.merged}`);
|
|
277
|
+
});
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
The `nightlyLearner` controller in the AgentDB controller registry now delegates to `MemoryConsolidator.runAll()` instead of the old AgentDB pass-through, so the consolidator is invoked from every layer that expects the "nightly memory hygiene" hook.
|
|
281
|
+
|
|
282
|
+
## Graceful retrieval (FTS5 fallback)
|
|
283
|
+
|
|
284
|
+
`MemoryService.search()` and `semanticSearch()` no longer hard-fail when `@claude-flow/embeddings` (or whatever embedder you injected) is unavailable. They:
|
|
285
|
+
|
|
286
|
+
1. Try the embedder.
|
|
287
|
+
2. If it throws or is missing, emit `health.embedder = 'degraded'`.
|
|
288
|
+
3. Run the same query through FTS5 keyword search (porter + unicode61 tokenizer) and return those results.
|
|
289
|
+
|
|
290
|
+
```typescript
|
|
291
|
+
const memory = new MemoryService({
|
|
292
|
+
// No embeddingGenerator — semantic queries will fall back to FTS5
|
|
293
|
+
});
|
|
294
|
+
await memory.initialize();
|
|
295
|
+
|
|
296
|
+
memory.on('health.embedder', (state) => {
|
|
297
|
+
// 'available' | 'degraded'
|
|
298
|
+
console.warn(`Embedder is ${state}`);
|
|
299
|
+
});
|
|
300
|
+
|
|
301
|
+
await memory.store({ key: 'note-1', content: 'OAuth pattern review' });
|
|
302
|
+
const results = await memory.search('OAuth', { limit: 5 });
|
|
303
|
+
// Returns FTS-ranked matches; no throw
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
When **both** dense (HNSW) and sparse (FTS5) paths are available, `service.search(query)` runs both, fuses the rankings with Reciprocal Rank Fusion (`k=60`), and reranks with MMR (`λ=0.7`) for diversity. This is what the AgentDB `hybridSearch` controller exposes too — it used to be a stub that returned `null`; in `3.0.0-alpha.18` it's a real implementation.
|
|
307
|
+
|
|
308
|
+
## API Reference
|
|
309
|
+
|
|
310
|
+
### HNSW Index
|
|
311
|
+
|
|
312
|
+
```typescript
|
|
313
|
+
import { HNSWIndex } from '@claude-flow/memory';
|
|
314
|
+
|
|
315
|
+
const index = new HNSWIndex({
|
|
316
|
+
dimensions: 1536,
|
|
317
|
+
M: 16, // Max connections per layer
|
|
318
|
+
efConstruction: 200, // Construction-time search depth
|
|
319
|
+
maxElements: 1000000, // Max vectors
|
|
320
|
+
metric: 'cosine', // 'cosine' | 'euclidean' | 'dot' | 'manhattan'
|
|
321
|
+
quantization: { // Optional quantization
|
|
322
|
+
type: 'scalar', // 'binary' | 'scalar' | 'product'
|
|
323
|
+
bits: 8
|
|
324
|
+
}
|
|
325
|
+
});
|
|
326
|
+
|
|
327
|
+
// Add vectors
|
|
328
|
+
await index.addPoint(id: string, vector: Float32Array);
|
|
329
|
+
|
|
330
|
+
// Search
|
|
331
|
+
const results = await index.search(
|
|
332
|
+
query: Float32Array,
|
|
333
|
+
k: number,
|
|
334
|
+
ef?: number // Search-time depth (higher = more accurate)
|
|
335
|
+
);
|
|
336
|
+
|
|
337
|
+
// Search with filters
|
|
338
|
+
const filtered = await index.searchWithFilters(
|
|
339
|
+
query,
|
|
340
|
+
k,
|
|
341
|
+
(id) => id.startsWith('session-')
|
|
342
|
+
);
|
|
343
|
+
|
|
344
|
+
// Remove vectors
|
|
345
|
+
await index.removePoint(id);
|
|
346
|
+
|
|
347
|
+
// Get statistics
|
|
348
|
+
const stats = index.getStats();
|
|
349
|
+
// { vectorCount, memoryUsage, avgSearchTime, compressionRatio }
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
### AgentDB Adapter
|
|
353
|
+
|
|
354
|
+
```typescript
|
|
355
|
+
import { AgentDBAdapter } from '@claude-flow/memory';
|
|
356
|
+
|
|
357
|
+
const adapter = new AgentDBAdapter({
|
|
358
|
+
dimension: 1536,
|
|
359
|
+
indexType: 'hnsw',
|
|
360
|
+
metric: 'cosine',
|
|
361
|
+
hnswM: 16,
|
|
362
|
+
hnswEfConstruction: 200,
|
|
363
|
+
enableCache: true,
|
|
364
|
+
cacheSizeMb: 256
|
|
365
|
+
});
|
|
366
|
+
|
|
367
|
+
await adapter.initialize();
|
|
368
|
+
|
|
369
|
+
// Store memory
|
|
370
|
+
await adapter.store({
|
|
371
|
+
id: 'mem-123',
|
|
372
|
+
content: 'User prefers dark mode',
|
|
373
|
+
embedding: vector,
|
|
374
|
+
metadata: { type: 'preference', agentId: 'agent-1' }
|
|
375
|
+
});
|
|
376
|
+
|
|
377
|
+
// Semantic search
|
|
378
|
+
const memories = await adapter.search(queryVector, {
|
|
379
|
+
limit: 10,
|
|
380
|
+
threshold: 0.7,
|
|
381
|
+
filter: { type: 'preference' }
|
|
382
|
+
});
|
|
383
|
+
|
|
384
|
+
// Cross-agent memory sharing
|
|
385
|
+
await adapter.enableCrossAgentSharing({
|
|
386
|
+
shareTypes: ['patterns', 'preferences'],
|
|
387
|
+
excludeTypes: ['secrets']
|
|
388
|
+
});
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
### Cache Manager
|
|
392
|
+
|
|
393
|
+
```typescript
|
|
394
|
+
import { CacheManager } from '@claude-flow/memory';
|
|
395
|
+
|
|
396
|
+
const cache = new CacheManager({
|
|
397
|
+
maxSize: 1000,
|
|
398
|
+
ttlMs: 3600000, // 1 hour
|
|
399
|
+
strategy: 'lru'
|
|
400
|
+
});
|
|
401
|
+
|
|
402
|
+
// Cache operations
|
|
403
|
+
cache.set('key', value);
|
|
404
|
+
const value = cache.get('key');
|
|
405
|
+
const exists = cache.has('key');
|
|
406
|
+
cache.delete('key');
|
|
407
|
+
cache.clear();
|
|
408
|
+
|
|
409
|
+
// Statistics
|
|
410
|
+
const stats = cache.getStats();
|
|
411
|
+
// { size, hits, misses, hitRate }
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
### Query Builder
|
|
415
|
+
|
|
416
|
+
```typescript
|
|
417
|
+
import { QueryBuilder } from '@claude-flow/memory';
|
|
418
|
+
|
|
419
|
+
const results = await new QueryBuilder()
|
|
420
|
+
.semantic(queryVector)
|
|
421
|
+
.where('agentId', '=', 'agent-1')
|
|
422
|
+
.where('type', 'in', ['pattern', 'strategy'])
|
|
423
|
+
.where('createdAt', '>', Date.now() - 86400000)
|
|
424
|
+
.orderBy('relevance', 'desc')
|
|
425
|
+
.limit(20)
|
|
426
|
+
.execute();
|
|
427
|
+
```
|
|
428
|
+
|
|
429
|
+
### Migration
|
|
430
|
+
|
|
431
|
+
```typescript
|
|
432
|
+
import { MemoryMigrator, createMigrator } from '@claude-flow/memory';
|
|
433
|
+
|
|
434
|
+
const migrator = createMigrator({
|
|
435
|
+
source: './data/v2-memory.db',
|
|
436
|
+
destination: './data/v3-memory.db',
|
|
437
|
+
});
|
|
438
|
+
|
|
439
|
+
// Inspect what will be migrated
|
|
440
|
+
const preview = await migrator.preview();
|
|
441
|
+
console.log(`Will migrate ${preview.recordCount} records`);
|
|
442
|
+
|
|
443
|
+
// Execute migration
|
|
444
|
+
await migrator.execute({
|
|
445
|
+
batchSize: 1000,
|
|
446
|
+
onProgress: (progress) => console.log(`${progress.percent}%`),
|
|
447
|
+
});
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
## Quantization Options
|
|
451
|
+
|
|
452
|
+
```typescript
|
|
453
|
+
// Binary quantization (32x compression)
|
|
454
|
+
const binaryIndex = new HNSWIndex({
|
|
455
|
+
dimensions: 1536,
|
|
456
|
+
quantization: { type: 'binary' }
|
|
457
|
+
});
|
|
458
|
+
|
|
459
|
+
// Scalar quantization (4x compression)
|
|
460
|
+
const scalarIndex = new HNSWIndex({
|
|
461
|
+
dimensions: 1536,
|
|
462
|
+
quantization: { type: 'scalar', bits: 8 }
|
|
463
|
+
});
|
|
464
|
+
|
|
465
|
+
// Product quantization (8x compression)
|
|
466
|
+
const productIndex = new HNSWIndex({
|
|
467
|
+
dimensions: 1536,
|
|
468
|
+
quantization: { type: 'product', subquantizers: 8 }
|
|
469
|
+
});
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
## Auto Memory Bridge (ADR-048)
|
|
473
|
+
|
|
474
|
+
Bidirectional sync between Claude Code's [auto memory](https://code.claude.com/docs/en/memory) files and AgentDB. Auto memory is a persistent directory (`~/.claude/projects/<project>/memory/`) where Claude writes learnings as markdown. `MEMORY.md` (first 200 lines) is loaded into the system prompt; topic files are read on demand.
|
|
475
|
+
|
|
476
|
+
### Quick Start
|
|
477
|
+
|
|
478
|
+
```typescript
|
|
479
|
+
import { AutoMemoryBridge } from '@claude-flow/memory';
|
|
480
|
+
|
|
481
|
+
const bridge = new AutoMemoryBridge(memoryBackend, {
|
|
482
|
+
workingDir: '/workspaces/my-project',
|
|
483
|
+
syncMode: 'on-session-end', // 'on-write' | 'on-session-end' | 'periodic'
|
|
484
|
+
pruneStrategy: 'confidence-weighted', // 'confidence-weighted' | 'fifo' | 'lru'
|
|
485
|
+
});
|
|
486
|
+
|
|
487
|
+
// Record an insight (stores in AgentDB + optionally writes to files)
|
|
488
|
+
await bridge.recordInsight({
|
|
489
|
+
category: 'debugging',
|
|
490
|
+
summary: 'HNSW index requires initialization before search',
|
|
491
|
+
source: 'agent:tester',
|
|
492
|
+
confidence: 0.95,
|
|
493
|
+
});
|
|
494
|
+
|
|
495
|
+
// Sync buffered insights to auto memory files
|
|
496
|
+
const syncResult = await bridge.syncToAutoMemory();
|
|
497
|
+
|
|
498
|
+
// Import existing auto memory files into AgentDB (on session start)
|
|
499
|
+
const importResult = await bridge.importFromAutoMemory();
|
|
500
|
+
|
|
501
|
+
// Curate MEMORY.md index (stays under 200-line limit)
|
|
502
|
+
await bridge.curateIndex();
|
|
503
|
+
|
|
504
|
+
// Check status
|
|
505
|
+
const status = bridge.getStatus();
|
|
506
|
+
```
|
|
507
|
+
|
|
508
|
+
### Sync Modes
|
|
509
|
+
|
|
510
|
+
| Mode | Behavior |
|
|
511
|
+
|------|----------|
|
|
512
|
+
| `on-write` | Writes to files immediately on `recordInsight()` |
|
|
513
|
+
| `on-session-end` | Buffers insights, flushes on `syncToAutoMemory()` |
|
|
514
|
+
| `periodic` | Auto-syncs on a configurable interval |
|
|
515
|
+
|
|
516
|
+
### Insight Categories
|
|
517
|
+
|
|
518
|
+
| Category | Topic File | Description |
|
|
519
|
+
|----------|-----------|-------------|
|
|
520
|
+
| `project-patterns` | `patterns.md` | Code patterns and conventions |
|
|
521
|
+
| `debugging` | `debugging.md` | Bug fixes and debugging insights |
|
|
522
|
+
| `architecture` | `architecture.md` | Design decisions and module relationships |
|
|
523
|
+
| `performance` | `performance.md` | Benchmarks and optimization results |
|
|
524
|
+
| `security` | `security.md` | Security findings and CVE notes |
|
|
525
|
+
| `preferences` | `preferences.md` | User and project preferences |
|
|
526
|
+
| `swarm-results` | `swarm-results.md` | Multi-agent swarm outcomes |
|
|
527
|
+
|
|
528
|
+
### Key Optimizations
|
|
529
|
+
|
|
530
|
+
- **Batch import** - `bulkInsert()` instead of individual `store()` calls
|
|
531
|
+
- **Pre-fetched hashes** - Single query for content-hash dedup during import
|
|
532
|
+
- **Async I/O** - `node:fs/promises` for non-blocking writes
|
|
533
|
+
- **Exact dedup** - `hasSummaryLine()` uses bullet-prefix matching, not substring
|
|
534
|
+
- **O(1) sync tracking** - `syncedInsightKeys` Set prevents double-write race
|
|
535
|
+
- **Prune-before-build** - Avoids O(n^2) index rebuild loop
|
|
536
|
+
|
|
537
|
+
### Utility Functions
|
|
538
|
+
|
|
539
|
+
```typescript
|
|
540
|
+
import {
|
|
541
|
+
resolveAutoMemoryDir, // Derive auto memory path from working dir
|
|
542
|
+
findGitRoot, // Walk up to find .git root
|
|
543
|
+
parseMarkdownEntries, // Parse ## headings into structured entries
|
|
544
|
+
extractSummaries, // Extract bullet summaries, strip metadata
|
|
545
|
+
formatInsightLine, // Format insight as markdown bullet
|
|
546
|
+
hashContent, // SHA-256 truncated to 16 hex chars
|
|
547
|
+
pruneTopicFile, // Keep topic files under line limit
|
|
548
|
+
hasSummaryLine, // Exact bullet-prefix dedup check
|
|
549
|
+
} from '@claude-flow/memory';
|
|
550
|
+
```
|
|
551
|
+
|
|
552
|
+
### Types
|
|
553
|
+
|
|
554
|
+
```typescript
|
|
555
|
+
import type {
|
|
556
|
+
AutoMemoryBridgeConfig,
|
|
557
|
+
MemoryInsight,
|
|
558
|
+
InsightCategory,
|
|
559
|
+
SyncDirection,
|
|
560
|
+
SyncMode,
|
|
561
|
+
PruneStrategy,
|
|
562
|
+
SyncResult,
|
|
563
|
+
ImportResult,
|
|
564
|
+
} from '@claude-flow/memory';
|
|
565
|
+
```
|
|
566
|
+
|
|
567
|
+
## Self-Learning Bridge (ADR-049)
|
|
568
|
+
|
|
569
|
+
Connects insights to the `@claude-flow/neural` learning pipeline. When neural is unavailable, all operations degrade to no-ops.
|
|
570
|
+
|
|
571
|
+
### Quick Start
|
|
572
|
+
|
|
573
|
+
```typescript
|
|
574
|
+
import { AutoMemoryBridge, LearningBridge } from '@claude-flow/memory';
|
|
575
|
+
|
|
576
|
+
const bridge = new AutoMemoryBridge(backend, {
|
|
577
|
+
workingDir: '/workspaces/my-project',
|
|
578
|
+
learning: {
|
|
579
|
+
sonaMode: 'balanced',
|
|
580
|
+
confidenceDecayRate: 0.005, // Per-hour decay
|
|
581
|
+
accessBoostAmount: 0.03, // Boost per access
|
|
582
|
+
consolidationThreshold: 10, // Min insights before consolidation
|
|
583
|
+
},
|
|
584
|
+
});
|
|
585
|
+
|
|
586
|
+
// Insights now trigger learning trajectories automatically
|
|
587
|
+
await bridge.recordInsight({
|
|
588
|
+
category: 'debugging',
|
|
589
|
+
summary: 'Connection pool exhaustion on high load',
|
|
590
|
+
source: 'agent:tester',
|
|
591
|
+
confidence: 0.9,
|
|
592
|
+
});
|
|
593
|
+
|
|
594
|
+
// Consolidation runs JUDGE/DISTILL/CONSOLIDATE pipeline
|
|
595
|
+
await bridge.syncToAutoMemory(); // Calls consolidate() first
|
|
596
|
+
```
|
|
597
|
+
|
|
598
|
+
### Standalone Usage
|
|
599
|
+
|
|
600
|
+
```typescript
|
|
601
|
+
import { LearningBridge } from '@claude-flow/memory';
|
|
602
|
+
|
|
603
|
+
const lb = new LearningBridge(backend, {
|
|
604
|
+
// Optional: inject neural loader for custom setups
|
|
605
|
+
neuralLoader: async () => {
|
|
606
|
+
const { NeuralLearningSystem } = await import('@claude-flow/neural');
|
|
607
|
+
return new NeuralLearningSystem();
|
|
608
|
+
},
|
|
609
|
+
});
|
|
610
|
+
|
|
611
|
+
// Boost confidence when insight is accessed
|
|
612
|
+
await lb.onInsightAccessed('entry-123'); // +0.03 confidence
|
|
613
|
+
|
|
614
|
+
// Apply time-based decay
|
|
615
|
+
const decayed = await lb.decayConfidences('default'); // -0.005/hour
|
|
616
|
+
|
|
617
|
+
// Find similar patterns via ReasoningBank
|
|
618
|
+
const patterns = await lb.findSimilarPatterns('connection pooling');
|
|
619
|
+
|
|
620
|
+
// Get learning statistics
|
|
621
|
+
const stats = lb.getStats();
|
|
622
|
+
// { totalTrajectories, activeTrajectories, completedTrajectories,
|
|
623
|
+
// totalConsolidations, accessBoosts, ... }
|
|
624
|
+
```
|
|
625
|
+
|
|
626
|
+
### Confidence Lifecycle
|
|
627
|
+
|
|
628
|
+
| Event | Effect | Range |
|
|
629
|
+
|-------|--------|-------|
|
|
630
|
+
| Insight recorded | Initial confidence from source | 0.1 - 1.0 |
|
|
631
|
+
| Insight accessed | +0.03 per access | Capped at 1.0 |
|
|
632
|
+
| Time decay | -0.005 per hour since last access | Floored at 0.1 |
|
|
633
|
+
| Consolidation | Neural pipeline may adjust | 0.1 - 1.0 |
|
|
634
|
+
|
|
635
|
+
## Knowledge Graph (ADR-049)
|
|
636
|
+
|
|
637
|
+
Pure TypeScript knowledge graph with PageRank and community detection. No external graph libraries required.
|
|
638
|
+
|
|
639
|
+
### Quick Start
|
|
640
|
+
|
|
641
|
+
```typescript
|
|
642
|
+
import { AutoMemoryBridge, MemoryGraph } from '@claude-flow/memory';
|
|
643
|
+
|
|
644
|
+
const bridge = new AutoMemoryBridge(backend, {
|
|
645
|
+
workingDir: '/workspaces/my-project',
|
|
646
|
+
graph: {
|
|
647
|
+
similarityThreshold: 0.8,
|
|
648
|
+
pageRankDamping: 0.85,
|
|
649
|
+
maxNodes: 5000,
|
|
650
|
+
},
|
|
651
|
+
});
|
|
652
|
+
|
|
653
|
+
// Graph builds automatically on import
|
|
654
|
+
await bridge.importFromAutoMemory();
|
|
655
|
+
|
|
656
|
+
// Curation uses PageRank to prioritize influential insights
|
|
657
|
+
await bridge.curateIndex();
|
|
658
|
+
```
|
|
659
|
+
|
|
660
|
+
### Standalone Usage
|
|
661
|
+
|
|
662
|
+
```typescript
|
|
663
|
+
import { MemoryGraph } from '@claude-flow/memory';
|
|
664
|
+
|
|
665
|
+
const graph = new MemoryGraph({
|
|
666
|
+
pageRankDamping: 0.85,
|
|
667
|
+
pageRankIterations: 50,
|
|
668
|
+
pageRankConvergence: 1e-6,
|
|
669
|
+
maxNodes: 5000,
|
|
670
|
+
});
|
|
671
|
+
|
|
672
|
+
// Build from backend entries
|
|
673
|
+
await graph.buildFromBackend(backend, 'my-namespace');
|
|
674
|
+
|
|
675
|
+
// Or build manually
|
|
676
|
+
graph.addNode(entry);
|
|
677
|
+
graph.addEdge('entry-1', 'entry-2', 'reference', 1.0);
|
|
678
|
+
graph.addEdge('entry-1', 'entry-3', 'similar', 0.9);
|
|
679
|
+
|
|
680
|
+
// Compute PageRank (power iteration)
|
|
681
|
+
const ranks = graph.computePageRank();
|
|
682
|
+
|
|
683
|
+
// Detect communities (label propagation)
|
|
684
|
+
const communities = graph.detectCommunities();
|
|
685
|
+
|
|
686
|
+
// Graph-aware ranking: blend vector score + PageRank
|
|
687
|
+
const ranked = graph.rankWithGraph(searchResults, 0.7);
|
|
688
|
+
// alpha=0.7 means 70% vector score + 30% PageRank
|
|
689
|
+
|
|
690
|
+
// Get most influential insights for MEMORY.md
|
|
691
|
+
const topNodes = graph.getTopNodes(20);
|
|
692
|
+
|
|
693
|
+
// BFS traversal for related insights
|
|
694
|
+
const neighbors = graph.getNeighbors('entry-1', 2); // depth=2
|
|
695
|
+
```
|
|
696
|
+
|
|
697
|
+
### Edge Types
|
|
698
|
+
|
|
699
|
+
| Type | Source | Description |
|
|
700
|
+
|------|--------|-------------|
|
|
701
|
+
| `reference` | `MemoryEntry.references` | Explicit cross-references between entries |
|
|
702
|
+
| `similar` | HNSW search | Auto-created when similarity > threshold |
|
|
703
|
+
| `temporal` | Timestamps | Entries created in same time window |
|
|
704
|
+
| `co-accessed` | Access patterns | Entries frequently accessed together |
|
|
705
|
+
| `causal` | Learning pipeline | Cause-effect relationships |
|
|
706
|
+
|
|
707
|
+
### Performance
|
|
708
|
+
|
|
709
|
+
| Operation | Result | Target |
|
|
710
|
+
|-----------|--------|--------|
|
|
711
|
+
| Graph build (1k nodes) | 2.78 ms | <200 ms |
|
|
712
|
+
| PageRank (1k nodes) | 12.21 ms | <100 ms |
|
|
713
|
+
| Community detection (1k) | 19.62 ms | — |
|
|
714
|
+
| `rankWithGraph(10)` | 0.006 ms | — |
|
|
715
|
+
| `getTopNodes(20)` | 0.308 ms | — |
|
|
716
|
+
| `getNeighbors(d=2)` | 0.005 ms | — |
|
|
717
|
+
|
|
718
|
+
## Agent-Scoped Memory (ADR-049)
|
|
719
|
+
|
|
720
|
+
Maps Claude Code's 3-scope agent memory directories for per-agent knowledge isolation and cross-agent transfer.
|
|
721
|
+
|
|
722
|
+
### Quick Start
|
|
723
|
+
|
|
724
|
+
```typescript
|
|
725
|
+
import { createAgentBridge, transferKnowledge } from '@claude-flow/memory';
|
|
726
|
+
|
|
727
|
+
// Create a bridge for a specific agent scope
|
|
728
|
+
const agentBridge = createAgentBridge(backend, {
|
|
729
|
+
agentName: 'my-coder',
|
|
730
|
+
scope: 'project', // 'project' | 'local' | 'user'
|
|
731
|
+
workingDir: '/workspaces/my-project',
|
|
732
|
+
});
|
|
733
|
+
|
|
734
|
+
// Record insights scoped to this agent
|
|
735
|
+
await agentBridge.recordInsight({
|
|
736
|
+
category: 'debugging',
|
|
737
|
+
summary: 'Use connection pooling for DB calls',
|
|
738
|
+
source: 'agent:my-coder',
|
|
739
|
+
confidence: 0.95,
|
|
740
|
+
});
|
|
741
|
+
|
|
742
|
+
// Transfer high-confidence insights between agents
|
|
743
|
+
const result = await transferKnowledge(sourceBackend, targetBridge, {
|
|
744
|
+
sourceNamespace: 'learnings',
|
|
745
|
+
minConfidence: 0.8, // Only transfer confident insights
|
|
746
|
+
maxEntries: 20,
|
|
747
|
+
categories: ['debugging', 'architecture'],
|
|
748
|
+
});
|
|
749
|
+
// { transferred: 15, skipped: 5 }
|
|
750
|
+
```
|
|
751
|
+
|
|
752
|
+
### Scope Paths
|
|
753
|
+
|
|
754
|
+
| Scope | Directory | Use Case |
|
|
755
|
+
|-------|-----------|----------|
|
|
756
|
+
| `project` | `<gitRoot>/.claude/agent-memory/<agent>/` | Project-specific learnings |
|
|
757
|
+
| `local` | `<gitRoot>/.claude/agent-memory-local/<agent>/` | Machine-local data |
|
|
758
|
+
| `user` | `~/.claude/agent-memory/<agent>/` | Cross-project user knowledge |
|
|
759
|
+
|
|
760
|
+
### Utilities
|
|
761
|
+
|
|
762
|
+
```typescript
|
|
763
|
+
import {
|
|
764
|
+
resolveAgentMemoryDir, // Get scope directory path
|
|
765
|
+
createAgentBridge, // Create scoped AutoMemoryBridge
|
|
766
|
+
transferKnowledge, // Cross-agent knowledge sharing
|
|
767
|
+
listAgentScopes, // Discover existing agent scopes
|
|
768
|
+
} from '@claude-flow/memory';
|
|
769
|
+
|
|
770
|
+
// Resolve path for an agent scope
|
|
771
|
+
const dir = resolveAgentMemoryDir('my-agent', 'project');
|
|
772
|
+
// → /workspaces/my-project/.claude/agent-memory/my-agent/
|
|
773
|
+
|
|
774
|
+
// List all agent scopes in a directory
|
|
775
|
+
const scopes = await listAgentScopes('/workspaces/my-project');
|
|
776
|
+
// [{ agentName: 'coder', scope: 'project', path: '...' }, ...]
|
|
777
|
+
```
|
|
778
|
+
|
|
779
|
+
## Performance Benchmarks
|
|
780
|
+
|
|
781
|
+
Reproducible benchmarks ship in `benchmarks/*.bench.ts`. Run them yourself:
|
|
782
|
+
|
|
783
|
+
```bash
|
|
784
|
+
cd v3/@claude-flow/memory
|
|
785
|
+
npm run build
|
|
786
|
+
npm run bench # runs benchmarks/*.bench.ts under vitest
|
|
787
|
+
```
|
|
788
|
+
|
|
789
|
+
### HNSW search baseline ([`baseline-20260519T212453Z.md`](./benchmarks/results/baseline-20260519T212453Z.md))
|
|
790
|
+
|
|
791
|
+
Measured on Apple Silicon (M-series), Node 22.22.1, vitest 4.0.16. Scenario: 1,000 random 128-dim cosine-normalized vectors loaded into a single `HNSWIndex`, then 200 query iterations after warmup.
|
|
792
|
+
|
|
793
|
+
| Metric | Value | Notes |
|
|
794
|
+
|---|---|---|
|
|
795
|
+
| `build_time_ms` | **533.42 ms** | Sequential `addPoint()` × 1,000 |
|
|
796
|
+
| `search_k10_avg_ms` | **0.5294 ms** | Post-warmup, average of 200 iterations |
|
|
797
|
+
| `search_k50_avg_ms` | **0.5235 ms** | k=50 ≈ k=10 — heap-based selection dominates |
|
|
798
|
+
| `add_avg_ms` | **0.8656 ms** | Incremental insert after the initial 1k |
|
|
799
|
+
| `search_k10_ops_per_sec` | **1,888.9 ops/s** | Derived |
|
|
800
|
+
| `search_k50_ops_per_sec` | **1,910.1 ops/s** | Derived |
|
|
801
|
+
|
|
802
|
+
These numbers are device-specific; CI baselines will replace this file once the GitHub Actions bench job lands. ADR-125 Phase 3 (persistent HNSW) means **cold-start** restoration should be a small fraction of `build_time_ms` once the snapshot benchmark is added.
|
|
803
|
+
|
|
804
|
+
### ADR-049 Benchmarks
|
|
805
|
+
|
|
806
|
+
| Operation | Actual | Target | Headroom |
|
|
807
|
+
|-----------|--------|--------|----------|
|
|
808
|
+
| Graph build (1k nodes) | 2.78 ms | <200 ms | **71.9x** |
|
|
809
|
+
| PageRank (1k nodes) | 12.21 ms | <100 ms | **8.2x** |
|
|
810
|
+
| Insight recording | 0.12 ms/each | <5 ms/each | **41.0x** |
|
|
811
|
+
| Consolidation | 0.26 ms | <500 ms | **1,955x** |
|
|
812
|
+
| Confidence decay (1k) | 0.23 ms | <50 ms | **215x** |
|
|
813
|
+
| Knowledge transfer | 1.25 ms | <100 ms | **80.0x** |
|
|
814
|
+
|
|
815
|
+
## TypeScript Types
|
|
816
|
+
|
|
817
|
+
```typescript
|
|
818
|
+
import type {
|
|
819
|
+
// Core
|
|
820
|
+
HNSWConfig, HNSWStats, SearchResult, MemoryEntry,
|
|
821
|
+
QuantizationConfig, DistanceMetric,
|
|
822
|
+
|
|
823
|
+
// Auto Memory Bridge (ADR-048)
|
|
824
|
+
AutoMemoryBridgeConfig, MemoryInsight, InsightCategory,
|
|
825
|
+
SyncDirection, SyncMode, PruneStrategy,
|
|
826
|
+
SyncResult, ImportResult,
|
|
827
|
+
|
|
828
|
+
// Learning Bridge (ADR-049)
|
|
829
|
+
LearningBridgeConfig, LearningStats,
|
|
830
|
+
ConsolidateResult, PatternMatch,
|
|
831
|
+
|
|
832
|
+
// Knowledge Graph (ADR-049)
|
|
833
|
+
MemoryGraphConfig, GraphNode, GraphEdge,
|
|
834
|
+
GraphStats, RankedResult, EdgeType,
|
|
835
|
+
|
|
836
|
+
// Agent Scope (ADR-049)
|
|
837
|
+
AgentMemoryScope, AgentScopedConfig,
|
|
838
|
+
TransferOptions, TransferResult,
|
|
839
|
+
} from '@claude-flow/memory';
|
|
840
|
+
```
|
|
841
|
+
|
|
842
|
+
## Dependencies
|
|
843
|
+
|
|
844
|
+
- `agentdb` `^3.0.0-alpha.14` — Vector database engine
|
|
845
|
+
- `sql.js` — SQLite driver via WASM (always available; no native build required)
|
|
846
|
+
- `better-sqlite3` — **Optional** native SQLite driver for higher throughput. The package works without it (sql.js fallback), so installs succeed on Node 24/26 even when the native build can't compile ([#1867](https://github.com/ruvnet/ruflo/issues/1867))
|
|
847
|
+
- `@claude-flow/embeddings` — **Optional** for semantic search. When absent or failing, `search()` automatically falls back to FTS5 keyword (see [Graceful retrieval](#graceful-retrieval-fts5-fallback))
|
|
848
|
+
- `@claude-flow/neural` — **Optional** peer dependency for self-learning (graceful fallback when unavailable)
|
|
849
|
+
|
|
850
|
+
## Related Packages
|
|
851
|
+
|
|
852
|
+
- [@claude-flow/neural](../neural) - Neural learning integration (SONA, ReasoningBank, EWC++)
|
|
853
|
+
- [@claude-flow/shared](../shared) - Shared types and utilities
|
|
854
|
+
- [@claude-flow/hooks](../hooks) - Session lifecycle hooks for auto memory sync
|
|
855
|
+
|
|
856
|
+
## License
|
|
857
|
+
|
|
858
|
+
MIT
|