agentdb 3.0.0-alpha.12 β 3.0.0-alpha.14
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 +207 -2834
- package/dist/src/backends/graph/GraphDatabaseAdapter.d.ts +54 -0
- package/dist/src/backends/graph/GraphDatabaseAdapter.d.ts.map +1 -1
- package/dist/src/backends/graph/GraphDatabaseAdapter.js +125 -0
- package/dist/src/backends/graph/GraphDatabaseAdapter.js.map +1 -1
- package/dist/src/controllers/ReflexionMemory.d.ts +14 -0
- package/dist/src/controllers/ReflexionMemory.d.ts.map +1 -1
- package/dist/src/controllers/ReflexionMemory.js +93 -0
- package/dist/src/controllers/ReflexionMemory.js.map +1 -1
- package/package.json +54 -7
package/README.md
CHANGED
|
@@ -1,2940 +1,313 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/agentdb)
|
|
4
|
+
[](https://www.npmjs.com/package/agentdb)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
[](https://www.typescriptlang.org/)
|
|
4
7
|
|
|
5
|
-
[](docs/guides/)
|
|
8
|
+
[](https://github.com/ruvnet/ruvector)
|
|
9
|
+
[](#-self-learning-loop)
|
|
10
|
+
[](#-mcp-integration)
|
|
11
|
+
[](https://github.com/ruvnet/agentdb)
|
|
10
12
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
## What is AgentDB?
|
|
14
|
-
|
|
15
|
-
**AgentDB is a vector memory and database that gets smarter every time you use it.**
|
|
16
|
-
|
|
17
|
-
Most vector databases store and retrieve embeddings. AgentDB does that too β 150x faster β but it also watches which results your AI agent actually used, learns from that feedback, and returns better results next time. Search quality improves by up to **36% automatically**, with zero manual tuning.
|
|
18
|
-
|
|
19
|
-
Everything lives in a **single Cognitive Container** (`.rvf` file) β vectors, indexes, learning state, and a cryptographic audit trail. No external services. No API keys. No monthly bills.
|
|
20
|
-
|
|
21
|
-
> **3 lines to self-learning search:**
|
|
22
|
-
>
|
|
23
|
-
> ```typescript
|
|
24
|
-
> const backend = await SelfLearningRvfBackend.create({
|
|
25
|
-
> learning: true,
|
|
26
|
-
> storagePath: "./my.rvf",
|
|
27
|
-
> });
|
|
28
|
-
> const results = await backend.searchAsync(query, 10); // search
|
|
29
|
-
> backend.recordFeedback("q1", 0.9); // learn β next search is smarter
|
|
30
|
-
> ```
|
|
31
|
-
|
|
32
|
-
### Who is it for?
|
|
33
|
-
|
|
34
|
-
| If you're building... | AgentDB gives you... |
|
|
35
|
-
| ---------------------------- | ------------------------------------------------------------------------------------------------- |
|
|
36
|
-
| **A RAG chatbot** | Search that learns which documents actually answer user questions |
|
|
37
|
-
| **A code review agent** | Pattern memory that remembers what worked across 1000s of reviews |
|
|
38
|
-
| **A research assistant** | Skill library that builds reusable tools from successful strategies |
|
|
39
|
-
| **An RL-powered agent** | 9 algorithms from Q-Learning to PPO, with bandit-guided algorithm selection and transfer learning |
|
|
40
|
-
| **A Claude Code / MCP tool** | 41 tools that plug in with one command |
|
|
41
|
-
| **An offline or edge app** | Full vector DB in the browser via WASM β no server needed |
|
|
42
|
-
| **An enterprise platform** | JWT auth, API key rotation, Argon2id hashing, SOC2/GDPR audit logs |
|
|
43
|
-
|
|
44
|
-
---
|
|
45
|
-
|
|
46
|
-
## Features
|
|
47
|
-
|
|
48
|
-
### Intelligence
|
|
49
|
-
|
|
50
|
-
| | |
|
|
51
|
-
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
52
|
-
| **Self-Learning Search** | Gets 36% better over time β learns from feedback, no manual tuning |
|
|
53
|
-
| **Cognitive Memory** | 6 human-inspired patterns: learn from mistakes, build reusable skills, discover what causes what |
|
|
54
|
-
| **Decision Intelligence** | Thompson Sampling bandit auto-tunes skill selection, pattern ranking, compression tiers, and RL algorithm choice |
|
|
55
|
-
| **9 RL Algorithms** | Q-Learning, SARSA, DQN, PPO, Actor-Critic, Policy Gradient, Decision Transformer, MCTS, Model-Based RL |
|
|
56
|
-
| **Hybrid Search** | BM25 keyword + vector with Reciprocal Rank Fusion β exact matches + semantic understanding |
|
|
57
|
-
| **Graph Intelligence** | Cypher queries, causal reasoning, GNN 8-head attention (+12.4% recall) |
|
|
58
|
-
|
|
59
|
-
### Performance
|
|
60
|
-
|
|
61
|
-
| | |
|
|
62
|
-
| ----------------- | ---------------------------------------------------------------------------------- |
|
|
63
|
-
| **150x Faster** | 61us search with Rust+SIMD β 800x faster than Pinecone, 160x faster than Chroma |
|
|
64
|
-
| **4 Backends** | Auto-selects best available: RuVector (Rust) > RVF > HNSWLib (C++) > sql.js (WASM) |
|
|
65
|
-
| **Runs Anywhere** | Node.js, browsers (WASM), edge functions, fully offline |
|
|
66
|
-
| **AgentDBFast** | 50-200x faster programmatic API β skip CLI overhead for production workloads |
|
|
67
|
-
|
|
68
|
-
### Storage & Data
|
|
69
|
-
|
|
70
|
-
| | |
|
|
71
|
-
| ----------------------------- | ------------------------------------------------------------------------------------------ |
|
|
72
|
-
| **Cognitive Container (RVF)** | Single `.rvf` file β vectors, index, learning state, SHAKE-256 witness chain |
|
|
73
|
-
| **COW Branching** | Instant copy-on-write branches for experiments, with full lineage tracking |
|
|
74
|
-
| **Compression** | 5-tier auto-tiering (hot/warm/cool/cold/archive), scalar 8-bit/4-bit, product quantization |
|
|
75
|
-
| **Metadata Filtering** | 10 MongoDB-style operators ($eq, $gt, $in, $contains, $exists, etc.) |
|
|
76
|
-
|
|
77
|
-
### Integration & Tools
|
|
78
|
-
|
|
79
|
-
| | |
|
|
80
|
-
| ------------------ | ------------------------------------------------------------------------------------------ |
|
|
81
|
-
| **41 MCP Tools** | One command to connect to Claude Code, Cursor, or any MCP-compatible assistant |
|
|
82
|
-
| **Chat UI** | `@agentdb/chat` β deploy a self-learning RAG chatbot in one line |
|
|
83
|
-
| **LLM Router** | Auto-selects best provider: RuvLLM (local), OpenRouter (200+ models), Gemini, Claude, ONNX |
|
|
84
|
-
| **Real-Time Sync** | QUIC transport, multi-instance replication, 4 conflict resolution strategies |
|
|
85
|
-
|
|
86
|
-
### Enterprise & Security
|
|
87
|
-
|
|
88
|
-
| | |
|
|
89
|
-
| ----------------- | ------------------------------------------------------------------------------------------- |
|
|
90
|
-
| **Auth & Audit** | JWT tokens, Argon2id hashing, API key rotation, SOC2/GDPR/HIPAA logging |
|
|
91
|
-
| **Security** | Input validation, XSS/injection prevention, Cypher sanitization, witness chain verification |
|
|
92
|
-
| **Observability** | OpenTelemetry traces, Prometheus metrics, structured logging |
|
|
93
|
-
| **Benchmarking** | 5 built-in benchmarks, custom benchmark classes, Markdown/JSON reports |
|
|
94
|
-
|
|
95
|
-
> **Zero config, zero cost.** `npm install agentdb` and go β fully local, no API keys, no cloud fees.
|
|
96
|
-
|
|
97
|
-
### Install
|
|
98
|
-
|
|
99
|
-
```bash
|
|
100
|
-
npm install agentdb # Latest stable (v2)
|
|
101
|
-
npm install agentdb@alpha # Latest alpha (v3 β unified .rvf, self-learning, SolverBandit)
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
**Zero native dependencies.** AgentDB uses sql.js (WASM SQLite) β no Python, no C++ compiler, no `node-gyp`. Works on Windows, macOS, Linux, and CI containers out of the box. `better-sqlite3` is supported as an optional performance upgrade but never required.
|
|
105
|
-
|
|
106
|
-
---
|
|
107
|
-
|
|
108
|
-
## π§ Agent Memory Intelligence
|
|
109
|
-
|
|
110
|
-
AgentDB v3.0.0-alpha.6 introduces revolutionary **sparse attention** and **graph partitioning** capabilities that enable AI agents to handle massive knowledge graphs with 10-100x performance improvements.
|
|
111
|
-
|
|
112
|
-
### Memory-Oriented Architecture
|
|
113
|
-
|
|
114
|
-
AgentDB is designed as an **agent memory substrate** - a persistent, intelligent memory layer that agents can query, update, and learn from:
|
|
115
|
-
|
|
116
|
-
**Core Memory Capabilities**:
|
|
117
|
-
- π― **Sparse Attention** - 10-100x speedup for large graphs using PPR, random walk, spectral sparsification
|
|
118
|
-
- π **Graph Partitioning** - 50-80% memory reduction with Stoer-Wagner, Karger, flow-based mincut
|
|
119
|
-
- β‘ **Fused Attention** - 10-50x faster kernel fusion (exceeded 20-25% target by 40x!)
|
|
120
|
-
- π **Zero-Copy Indexing** - 90% fewer allocations, 40-50% speedup
|
|
121
|
-
- ποΈ **Clean Architecture** - 6 focused classes replacing 782-line god object
|
|
122
|
-
|
|
123
|
-
### Agent Memory Pattern
|
|
124
|
-
|
|
125
|
-
```typescript
|
|
126
|
-
import { SparsificationService, MincutService, AttentionService } from 'agentdb';
|
|
127
|
-
|
|
128
|
-
// Initialize agent memory layer
|
|
129
|
-
const memory = new AttentionService();
|
|
130
|
-
await memory.initialize();
|
|
131
|
-
|
|
132
|
-
// Sparse attention for agent memory retrieval (10-100x faster)
|
|
133
|
-
const relevantMemories = await memory.sparseAttention(
|
|
134
|
-
agentQuery,
|
|
135
|
-
memoryGraph,
|
|
136
|
-
{
|
|
137
|
-
method: 'ppr', // Personalized PageRank
|
|
138
|
-
topK: 50, // Top 50 most relevant
|
|
139
|
-
sparsificationRatio: 0.1 // Keep 10% of edges
|
|
140
|
-
}
|
|
141
|
-
);
|
|
142
|
-
|
|
143
|
-
// Partitioned attention for distributed agent teams
|
|
144
|
-
const teamMemories = await memory.partitionedAttention(
|
|
145
|
-
teamQuery,
|
|
146
|
-
sharedKnowledge,
|
|
147
|
-
{
|
|
148
|
-
method: 'stoer-wagner', // Optimal partitioning
|
|
149
|
-
maxPartitionSize: 1000 // Max 1000 nodes per partition
|
|
150
|
-
}
|
|
151
|
-
);
|
|
152
|
-
|
|
153
|
-
// Fused attention for rapid memory access (10-50x faster)
|
|
154
|
-
const fastAccess = await memory.fusedAttention(
|
|
155
|
-
query,
|
|
156
|
-
keys,
|
|
157
|
-
values
|
|
158
|
-
);
|
|
159
|
-
```
|
|
160
|
-
|
|
161
|
-
### Performance Metrics
|
|
162
|
-
|
|
163
|
-
| Operation | Before | After | Improvement |
|
|
164
|
-
|-----------|--------|-------|-------------|
|
|
165
|
-
| Sparse Attention (N=10K) | 1000ms | 10-100ms | **10-100x** |
|
|
166
|
-
| Memory Reduction | 100% | 20-50% | **50-80% less** |
|
|
167
|
-
| Fused Attention | 1010ms | 21ms | **49x faster** |
|
|
168
|
-
| Allocations | 100% | 10% | **90% fewer** |
|
|
169
|
-
|
|
170
|
-
### Use Cases
|
|
171
|
-
|
|
172
|
-
**Agent Episodic Memory**:
|
|
173
|
-
```typescript
|
|
174
|
-
// Store agent experiences as sparse graphs
|
|
175
|
-
await sparsification.sparseByPPR(experienceGraph, {
|
|
176
|
-
alpha: 0.15,
|
|
177
|
-
topK: 100
|
|
178
|
-
});
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
**Multi-Agent Knowledge Sharing**:
|
|
182
|
-
```typescript
|
|
183
|
-
// Partition knowledge for team collaboration
|
|
184
|
-
const partitions = await mincut.computeStoerWagner(teamKnowledge);
|
|
185
|
-
```
|
|
186
|
-
|
|
187
|
-
**Rapid Context Retrieval**:
|
|
188
|
-
```typescript
|
|
189
|
-
// Fused attention for instant memory access
|
|
190
|
-
const context = await attention.fusedAttention(Q, K, V);
|
|
191
|
-
```
|
|
192
|
-
|
|
193
|
-
---
|
|
194
|
-
## Comparison
|
|
195
|
-
|
|
196
|
-
> **61 microseconds.** That's 800x faster than Pinecone, 160x faster than Chroma, and the only vector database that learns from your usage and gets better over time.
|
|
197
|
-
|
|
198
|
-
### vs. Other Vector Databases
|
|
199
|
-
|
|
200
|
-
#### Intelligence
|
|
201
|
-
|
|
202
|
-
| Feature | AgentDB v3 | Pinecone | Chroma | Weaviate | pgvector |
|
|
203
|
-
| ---------------------- | --------------------------------------- | -------- | ------ | --------- | -------- |
|
|
204
|
-
| Self-learning pipeline | SONA + contrastive + federated + bandit | No | No | No | No |
|
|
205
|
-
| Reinforcement learning | 9 algorithms (Q-Learning to MCTS) | No | No | No | No |
|
|
206
|
-
| Cognitive memory | 6 patterns | No | No | No | No |
|
|
207
|
-
| Hybrid search | BM25 + vector (RRF fusion) | No | No | BM25 only | No |
|
|
208
|
-
| Graph queries | Cypher | No | No | GraphQL | No |
|
|
209
|
-
|
|
210
|
-
#### Performance & Deployment
|
|
211
|
-
|
|
212
|
-
| Feature | AgentDB v3 | Pinecone | Chroma | Weaviate | pgvector |
|
|
213
|
-
| -------------- | ---------- | -------- | ------ | -------- | -------- |
|
|
214
|
-
| Search latency | **61us** | ~50ms | ~10ms | ~5ms | ~2ms |
|
|
215
|
-
| Runs offline | Full | No | Yes | Yes | Yes |
|
|
216
|
-
| Browser (WASM) | Yes | No | No | No | No |
|
|
217
|
-
|
|
218
|
-
#### Storage
|
|
219
|
-
|
|
220
|
-
| Feature | AgentDB v3 | Pinecone | Chroma | Weaviate | pgvector |
|
|
221
|
-
| ------------------- | ---------------------------------- | -------- | ------ | -------- | -------- |
|
|
222
|
-
| Cognitive Container | Single `.rvf` file + COW branching | No | No | No | No |
|
|
223
|
-
| Monthly cost | **$0** | $70+ | $0 | $0+ | $0+ |
|
|
224
|
-
|
|
225
|
-
#### Integration & Security
|
|
226
|
-
|
|
227
|
-
| Feature | AgentDB v3 | Pinecone | Chroma | Weaviate | pgvector |
|
|
228
|
-
| --------------- | -------------------------------- | ---------- | ------ | --------- | -------- |
|
|
229
|
-
| MCP integration | 41 tools | No | No | No | No |
|
|
230
|
-
| Auth & audit | JWT + Argon2id + compliance logs | No | No | No | No |
|
|
231
|
-
| Local-first | Yes | Cloud only | Yes | Self-host | Postgres |
|
|
232
|
-
|
|
233
|
-
### Backend Performance
|
|
234
|
-
|
|
235
|
-
| Backend | Latency | Recall@10 | Native | Best For |
|
|
236
|
-
| ----------------------------- | ------- | --------- | ------ | ---------------------------- |
|
|
237
|
-
| **RuVector** (Rust + SIMD) | 61us | 96.8% | Yes | Production, high throughput |
|
|
238
|
-
| **Cognitive Container** (RVF) | ~100us | 96.8% | Yes | Portable, branching, lineage |
|
|
239
|
-
| **HNSWLib** (C++) | ~500us | 95%+ | Yes | Compatibility |
|
|
240
|
-
| **sql.js** (WASM) | ~5ms | 90%+ | No | Zero-dependency fallback |
|
|
241
|
-
|
|
242
|
-
AgentDB auto-selects the best available: RuVector > Cognitive Container (RVF) > HNSWLib > sql.js
|
|
243
|
-
|
|
244
|
-
---
|
|
245
|
-
|
|
246
|
-
## Quick Start
|
|
247
|
-
|
|
248
|
-
```bash
|
|
249
|
-
npm install agentdb
|
|
250
|
-
```
|
|
251
|
-
|
|
252
|
-
### Unified AgentDB (recommended)
|
|
253
|
-
|
|
254
|
-
The `AgentDB` class is the simplest way to use AgentDB. Everything β vectors, relational data, learning state β lives in a single `.rvf` file:
|
|
255
|
-
|
|
256
|
-
```typescript
|
|
257
|
-
import { AgentDB } from "agentdb";
|
|
258
|
-
|
|
259
|
-
const db = new AgentDB({ dbPath: "./knowledge.rvf" });
|
|
260
|
-
await db.initialize();
|
|
261
|
-
|
|
262
|
-
// All controllers are ready β reflexion memory, skill library, causal graph
|
|
263
|
-
const reflexion = db.getController("reflexion");
|
|
264
|
-
const skills = db.getController("skills");
|
|
265
|
-
const causal = db.getController("causal");
|
|
266
|
-
|
|
267
|
-
// Store an episode
|
|
268
|
-
await reflexion.storeEpisode({
|
|
269
|
-
sessionId: "session-1",
|
|
270
|
-
task: "Fix auth bug",
|
|
271
|
-
reward: 0.95,
|
|
272
|
-
success: true,
|
|
273
|
-
critique: "OAuth2 PKCE was the right approach",
|
|
274
|
-
});
|
|
275
|
-
|
|
276
|
-
// Create a reusable skill
|
|
277
|
-
await skills.createSkill({
|
|
278
|
-
name: "jwt_auth",
|
|
279
|
-
description: "JWT authentication with refresh tokens",
|
|
280
|
-
code: "implementation...",
|
|
281
|
-
successRate: 0.92,
|
|
282
|
-
});
|
|
283
|
-
|
|
284
|
-
// Save everything to one file and close
|
|
285
|
-
await db.save();
|
|
286
|
-
await db.close();
|
|
287
|
-
```
|
|
288
|
-
|
|
289
|
-
**Configuration options:**
|
|
290
|
-
|
|
291
|
-
| Option | Default | Description |
|
|
292
|
-
| ----------------- | ------------ | ------------------------------------------------------------------------------------------ |
|
|
293
|
-
| `dbPath` | `':memory:'` | Path to `.rvf` file (or `.db` for legacy mode) |
|
|
294
|
-
| `vectorBackend` | `'rvf'` | Backend: `'rvf'` (unified), `'auto'`, `'ruvector'`, `'hnswlib'` |
|
|
295
|
-
| `vectorDimension` | `384` | Embedding dimension (384 for MiniLM, 768 for bge-base) |
|
|
296
|
-
| `forceWasm` | `false` | Force sql.js WASM backend (sql.js is the default; `better-sqlite3` used only if installed) |
|
|
297
|
-
| `enableAttention` | `false` | Enable GNN attention mechanisms |
|
|
298
|
-
|
|
299
|
-
**Controllers:** `db.getController('reflexion')` (ReflexionMemory), `db.getController('skills')` (SkillLibrary), `db.getController('causal')` (CausalMemoryGraph)
|
|
300
|
-
|
|
301
|
-
### CLI β try it in 10 seconds
|
|
302
|
-
|
|
303
|
-
```bash
|
|
304
|
-
npx agentdb init # Initialize a new database
|
|
305
|
-
npx agentdb doctor # Check system health
|
|
306
|
-
npx agentdb rvf status ./store.rvf # Inspect a Cognitive Container
|
|
307
|
-
npx agentdb rvf derive ./prod.rvf ./experiment.rvf # Branch for experiments (instant, COW)
|
|
308
|
-
npx agentdb mcp start # Start MCP server (41 tools)
|
|
309
|
-
npx @agentdb/chat serve --rvf ./kb.rvf --port 3000 # Launch chat UI
|
|
310
|
-
```
|
|
311
|
-
|
|
312
|
-
<details>
|
|
313
|
-
<summary><strong>Complete CLI Reference</strong> β 60+ commands across 8 categories</summary>
|
|
314
|
-
|
|
315
|
-
#### Core
|
|
316
|
-
|
|
317
|
-
```bash
|
|
318
|
-
npx agentdb init # Initialize database
|
|
319
|
-
npx agentdb status # System status and diagnostics
|
|
320
|
-
npx agentdb doctor [--fix] [--verbose] # Health check with auto-fix
|
|
321
|
-
```
|
|
322
|
-
|
|
323
|
-
#### Cognitive Container (RVF) Management
|
|
324
|
-
|
|
325
|
-
```bash
|
|
326
|
-
npx agentdb rvf status ./store.rvf # Container statistics
|
|
327
|
-
npx agentdb rvf compact ./store.rvf # Reclaim space
|
|
328
|
-
npx agentdb rvf derive ./src.rvf ./dst.rvf # COW branch
|
|
329
|
-
npx agentdb rvf segments ./store.rvf # Segment introspection
|
|
330
|
-
npx agentdb rvf detect # SDK availability
|
|
331
|
-
```
|
|
332
|
-
|
|
333
|
-
#### Learning & Training
|
|
334
|
-
|
|
335
|
-
```bash
|
|
336
|
-
npx agentdb learn --session <id> --train # Train a learning session
|
|
337
|
-
npx agentdb learn --status # Learning system status
|
|
338
|
-
```
|
|
339
|
-
|
|
340
|
-
#### Routing
|
|
341
|
-
|
|
342
|
-
```bash
|
|
343
|
-
npx agentdb route --query "search term" # Test semantic routing
|
|
344
|
-
npx agentdb route --list # Show learned intents
|
|
345
|
-
```
|
|
346
|
-
|
|
347
|
-
#### Attention & Hyperbolic
|
|
348
|
-
|
|
349
|
-
```bash
|
|
350
|
-
npx agentdb attention --benchmark # Attention performance test
|
|
351
|
-
npx agentdb hyperbolic --test # Hyperbolic embedding test
|
|
352
|
-
```
|
|
353
|
-
|
|
354
|
-
#### Simulation
|
|
355
|
-
|
|
356
|
-
```bash
|
|
357
|
-
npx agentdb simulate hnsw --iterations 3 # HNSW optimization
|
|
358
|
-
npx agentdb simulate attention --iterations 3 # GNN attention
|
|
359
|
-
npx agentdb simulate self-organizing --days 30 # Self-healing
|
|
360
|
-
npx agentdb simulate --wizard # Interactive wizard
|
|
361
|
-
npx agentdb simulate --custom ./my-scenario.json # Custom simulation
|
|
362
|
-
npx agentdb simulate --report ./output.md # Generate report
|
|
363
|
-
```
|
|
364
|
-
|
|
365
|
-
#### Migration & Import
|
|
366
|
-
|
|
367
|
-
```bash
|
|
368
|
-
npx agentdb migrate --source ./old.db --target ./new.db # Full v1βv2 migration
|
|
369
|
-
npx agentdb migrate --source ./v2.db --to v3 --rvf-path ./unified.rvf # v2βv3 unified .rvf
|
|
370
|
-
npx agentdb migrate --to rvf --rvf-path ./out.rvf # Export to Cognitive Container
|
|
371
|
-
npx agentdb migrate --dry-run --verbose # Preview changes
|
|
372
|
-
```
|
|
373
|
-
|
|
374
|
-
#### MCP Server
|
|
375
|
-
|
|
376
|
-
```bash
|
|
377
|
-
npx agentdb mcp start # Start MCP server (41 tools)
|
|
378
|
-
npx agentdb mcp start --port 8080 # Custom port
|
|
379
|
-
```
|
|
380
|
-
|
|
381
|
-
</details>
|
|
382
|
-
|
|
383
|
-
### Self-Learning Vector Search (the differentiator)
|
|
384
|
-
|
|
385
|
-
Most vector databases return the same results no matter how many times you query them. AgentDB closes the loop: after every search, you tell it which results were actually useful. A contrastive trainer (InfoNCE + hard-negative mining) adjusts a lightweight LoRA adapter in under 1 ms, and EWC++ consolidation keeps old knowledge intact. Over 500 feedback cycles, recall jumps from 54% to 90% β automatically.
|
|
386
|
-
|
|
387
|
-
```typescript
|
|
388
|
-
import { SelfLearningRvfBackend } from "agentdb/backends/rvf/SelfLearningRvfBackend";
|
|
389
|
-
|
|
390
|
-
// Create a self-learning Cognitive Container
|
|
391
|
-
const backend = await SelfLearningRvfBackend.create({
|
|
392
|
-
dimension: 384,
|
|
393
|
-
metric: "cosine",
|
|
394
|
-
storagePath: "./knowledge.rvf",
|
|
395
|
-
learning: true, // enable the learning pipeline
|
|
396
|
-
});
|
|
397
|
-
|
|
398
|
-
// Insert documents
|
|
399
|
-
await backend.insertAsync("doc-1", embedding, { title: "Auth Guide" });
|
|
400
|
-
await backend.insertAsync("doc-2", embedding2, { title: "API Reference" });
|
|
401
|
-
|
|
402
|
-
// Search β automatically routed through the learning pipeline
|
|
403
|
-
const results = await backend.searchAsync(queryEmbedding, 10);
|
|
404
|
-
|
|
405
|
-
// Tell AgentDB which results were useful β this drives learning
|
|
406
|
-
backend.recordFeedback("query-1", 0.95); // great result
|
|
407
|
-
backend.recordFeedback("query-2", 0.2); // poor result
|
|
408
|
-
|
|
409
|
-
// Run a learning tick β trains the model, updates adapters
|
|
410
|
-
await backend.tick();
|
|
411
|
-
// Next search will be smarter based on your feedback
|
|
412
|
-
```
|
|
413
|
-
|
|
414
|
-
### Cognitive Memory (pattern learning)
|
|
415
|
-
|
|
416
|
-
Store and retrieve reasoning patterns β your agent remembers what worked:
|
|
417
|
-
|
|
418
|
-
```typescript
|
|
419
|
-
import { createDatabase, ReasoningBank, EmbeddingService } from "agentdb";
|
|
420
|
-
|
|
421
|
-
const db = await createDatabase("./agent-memory.db");
|
|
422
|
-
const embedder = new EmbeddingService({ model: "Xenova/all-MiniLM-L6-v2" });
|
|
423
|
-
await embedder.initialize();
|
|
424
|
-
|
|
425
|
-
const reasoningBank = new ReasoningBank(db, embedder);
|
|
426
|
-
|
|
427
|
-
// Store what your agent learned
|
|
428
|
-
await reasoningBank.storePattern({
|
|
429
|
-
taskType: "code_review",
|
|
430
|
-
approach: "Security-first analysis",
|
|
431
|
-
successRate: 0.95,
|
|
432
|
-
});
|
|
433
|
-
|
|
434
|
-
// Find similar successful patterns
|
|
435
|
-
const patterns = await reasoningBank.searchPatterns({
|
|
436
|
-
task: "security code review",
|
|
437
|
-
k: 10,
|
|
438
|
-
});
|
|
439
|
-
```
|
|
440
|
-
|
|
441
|
-
### Unified Mode β Everything in One File
|
|
442
|
-
|
|
443
|
-
In v3, `AgentDB` stores vectors, relational data, learning state, and metadata in a single `.rvf` file:
|
|
444
|
-
|
|
445
|
-
```typescript
|
|
446
|
-
import { AgentDB } from "agentdb";
|
|
447
|
-
|
|
448
|
-
// Single-file mode is the default β no configuration needed
|
|
449
|
-
const db = new AgentDB({ dbPath: "./agent.rvf" });
|
|
450
|
-
await db.initialize();
|
|
451
|
-
|
|
452
|
-
// Access the underlying database for advanced queries
|
|
453
|
-
const raw = db.database;
|
|
454
|
-
const stats = raw.prepare("SELECT COUNT(*) as c FROM episodes").get();
|
|
455
|
-
|
|
456
|
-
// Check mode
|
|
457
|
-
console.log(db.isUnifiedMode); // true β everything in one .rvf file
|
|
458
|
-
console.log(db.vectorBackendName); // 'rvf'
|
|
459
|
-
|
|
460
|
-
// Save and reopen β all data persists in agent.rvf
|
|
461
|
-
await db.save();
|
|
462
|
-
await db.close();
|
|
463
|
-
|
|
464
|
-
const db2 = new AgentDB({ dbPath: "./agent.rvf" });
|
|
465
|
-
await db2.initialize(); // All episodes, skills, vectors restored
|
|
466
|
-
```
|
|
467
|
-
|
|
468
|
-
### Chat UI (one-line deployment)
|
|
469
|
-
|
|
470
|
-
Deploy a self-learning RAG chatbot over any Cognitive Container:
|
|
471
|
-
|
|
472
|
-
```bash
|
|
473
|
-
npx @agentdb/chat serve --rvf ./kb.rvf --port 3000
|
|
474
|
-
```
|
|
475
|
-
|
|
476
|
-
---
|
|
477
|
-
|
|
478
|
-
## How the Learning Loop Works
|
|
479
|
-
|
|
480
|
-
Every search automatically triggers a learning cycle. No configuration needed β just call `recordFeedback()` after using results:
|
|
481
|
-
|
|
482
|
-
```mermaid
|
|
483
|
-
graph LR
|
|
484
|
-
A["Your Query"] --> B["Semantic Router<br/>classifies intent"]
|
|
485
|
-
B --> C["Embedding Adapter<br/>adjusts in <1ms"]
|
|
486
|
-
C --> D["HNSW Search<br/>61us, 96.8% recall"]
|
|
487
|
-
D --> E["Results"]
|
|
488
|
-
E --> F["Your Feedback<br/>0.0 - 1.0"]
|
|
489
|
-
F --> G["Contrastive Trainer<br/>learns what's good"]
|
|
490
|
-
G --> C
|
|
491
|
-
style G fill:#2d6,stroke:#1a4,color:#fff
|
|
492
|
-
style A fill:#36f,stroke:#24d,color:#fff
|
|
493
|
-
```
|
|
494
|
-
|
|
495
|
-
> **Result:** Over 10 sessions with 50 episodes each, search quality improved from 54% to 90% β a 36% gain with zero manual tuning.
|
|
496
|
-
|
|
497
|
-
## Architecture
|
|
498
|
-
|
|
499
|
-
```mermaid
|
|
500
|
-
graph TD
|
|
501
|
-
A[Your Application] --> B[AgentDB Core]
|
|
502
|
-
B --> C[Cognitive Memory<br/>6 patterns]
|
|
503
|
-
B --> D[Self-Learning Pipeline<br/>SONA + Contrastive + Federated]
|
|
504
|
-
B --> E[Backend Auto-Selection]
|
|
505
|
-
E --> F[RuVector<br/>Rust+SIMD 61us]
|
|
506
|
-
E --> G[Cognitive Container<br/>RVF single-file COW]
|
|
507
|
-
E --> H[HNSWLib<br/>C++ HNSW]
|
|
508
|
-
E --> I[sql.js<br/>WASM fallback]
|
|
509
|
-
B --> J[NativeAccelerator<br/>15 capability groups]
|
|
510
|
-
B --> K[MCP Server<br/>41 tools]
|
|
511
|
-
B --> L[Graph Intelligence<br/>Cypher + GNN]
|
|
512
|
-
```
|
|
513
|
-
|
|
514
|
-
---
|
|
515
|
-
|
|
516
|
-
## MCP Integration
|
|
517
|
-
|
|
518
|
-
> **One command** to give any AI assistant access to self-learning vector search, cognitive memory, and 37 specialized tools.
|
|
519
|
-
|
|
520
|
-
Connect AgentDB to Claude Code, Cursor, or any MCP-compatible AI assistant:
|
|
521
|
-
|
|
522
|
-
```bash
|
|
523
|
-
claude mcp add agentdb npx agentdb mcp start
|
|
524
|
-
```
|
|
525
|
-
|
|
526
|
-
Or add to `~/.config/claude/claude_desktop_config.json`:
|
|
527
|
-
|
|
528
|
-
```json
|
|
529
|
-
{
|
|
530
|
-
"mcpServers": {
|
|
531
|
-
"agentdb": {
|
|
532
|
-
"command": "npx",
|
|
533
|
-
"args": ["agentdb", "mcp", "start"],
|
|
534
|
-
"env": { "AGENTDB_PATH": "./agentdb.rvf" }
|
|
535
|
-
}
|
|
536
|
-
}
|
|
537
|
-
}
|
|
538
|
-
```
|
|
539
|
-
|
|
540
|
-
### MCP Tools Overview
|
|
541
|
-
|
|
542
|
-
| Category | Tools | Examples |
|
|
543
|
-
| ------------ | ----- | ------------------------------------------------------------------------------------------------ |
|
|
544
|
-
| **Core DB** | 6 | init, insert, batch insert, search, delete, stats |
|
|
545
|
-
| **Patterns** | 4 | store, search, batch store, statistics |
|
|
546
|
-
| **Memory** | 9 | reflexion store/retrieve/batch, skill create/search/batch, causal edges/queries, nightly learner |
|
|
547
|
-
| **Learning** | 10 | RL sessions, predictions, feedback, training, transfer learning, explainability |
|
|
548
|
-
| **Recall** | 2 | explainable recall with provenance certificates, cache management |
|
|
549
|
-
| **Solver** | 4 | solver train, acceptance testing, policy inspection, witness chain audit |
|
|
550
|
-
| **Admin** | 6 | diagnostics, migration, pruning, experience recording, reward signals, legacy stats |
|
|
551
|
-
|
|
552
|
-
All 41 tools support parallel execution markers, batch operations, intelligent caching, and format parameters for token reduction.
|
|
553
|
-
|
|
554
|
-
---
|
|
555
|
-
|
|
556
|
-
## Chat Ecosystem
|
|
557
|
-
|
|
558
|
-
The `@agentdb/chat` package provides a one-line chat UI with self-learning RAG built on top of AgentDB:
|
|
559
|
-
|
|
560
|
-
```bash
|
|
561
|
-
# Serve a chat interface over your knowledge base
|
|
562
|
-
npx @agentdb/chat serve --rvf ./kb.rvf --port 3000
|
|
563
|
-
```
|
|
564
|
-
|
|
565
|
-
Programmatic usage:
|
|
566
|
-
|
|
567
|
-
```typescript
|
|
568
|
-
import { createChatServer } from "@agentdb/chat";
|
|
569
|
-
|
|
570
|
-
const server = await createChatServer("./kb.rvf", {
|
|
571
|
-
port: 3000,
|
|
572
|
-
learning: true,
|
|
573
|
-
});
|
|
574
|
-
```
|
|
575
|
-
|
|
576
|
-
The chat ecosystem includes:
|
|
577
|
-
|
|
578
|
-
- **Chat Server** β streaming inference with any LLM provider
|
|
579
|
-
- **Chat Persistence** β conversation history stored in Cognitive Containers
|
|
580
|
-
- **MCP Bridge** β expose all 37 AgentDB tools through chat
|
|
581
|
-
- **Chat UI** (`@agentdb/chat-ui`) β SvelteKit frontend with real-time tool invocation
|
|
582
|
-
|
|
583
|
-
See the [@agentdb/chat README](../agentdb-chat/README.md) for full documentation.
|
|
584
|
-
|
|
585
|
-
---
|
|
586
|
-
|
|
587
|
-
## Deep Dives
|
|
588
|
-
|
|
589
|
-
> Expand any section below for code examples, configuration, and architecture details.
|
|
590
|
-
|
|
591
|
-
**Getting Started** | [Guides](#guides) | [Tutorials](#tutorials) | [Advanced Usage](#advanced-usage)
|
|
592
|
-
|
|
593
|
-
**Intelligence & Learning** | [Self-Learning Pipeline](#self-learning-pipeline) | [Cognitive Memory](#cognitive-memory-patterns) | [Reinforcement Learning](#reinforcement-learning) | [Hybrid Search](#hybrid-search) | [Graph Intelligence](#graph-intelligence) | [Query Lifecycle](#query-lifecycle)
|
|
594
|
-
|
|
595
|
-
**Performance & Architecture** | [SIMD Acceleration](#simd--native-acceleration) | [Browser & WASM](#browser--wasm-deployment) | [Benchmarks](#performance--benchmarks) | [AgentDBFast](#agentdbfast) | [Benchmark Suite](#benchmark-suite)
|
|
596
|
-
|
|
597
|
-
**Storage & Data** | [Cognitive Container (RVF)](#cognitive-container-rvf-format) | [Quantization](#quantization--compression) | [Metadata Filtering](#metadata-filtering)
|
|
598
|
-
|
|
599
|
-
**Integration & Tools** | [LLM Router](#llm-router) | [Model Import/Export](#model-importexport--embedding-models) | [Multi-Database Sync](#multi-database-coordination) | [Real-Time Sync](#real-time-sync-quic)
|
|
600
|
-
|
|
601
|
-
**Enterprise & Security** | [Security](#security) | [Auth & Audit](#auth--audit) | [Observability](#observability)
|
|
602
|
-
|
|
603
|
-
---
|
|
604
|
-
|
|
605
|
-
### Getting Started
|
|
606
|
-
|
|
607
|
-
Step-by-step guides, tutorials, and advanced configuration for every skill level.
|
|
608
|
-
|
|
609
|
-
<details>
|
|
610
|
-
<summary><strong>Guides</strong> β backend selection, migration, health checks, federated learning</summary>
|
|
611
|
-
|
|
612
|
-
#### Backend Selection
|
|
613
|
-
|
|
614
|
-
```bash
|
|
615
|
-
# Auto-detect best backend (recommended)
|
|
616
|
-
npx agentdb init --backend auto
|
|
617
|
-
|
|
618
|
-
# Force RuVector (fastest, requires native bindings)
|
|
619
|
-
npx agentdb init --backend ruvector
|
|
620
|
-
|
|
621
|
-
# Force Cognitive Container (single-file, portable)
|
|
622
|
-
npx agentdb init --backend rvf --rvf-path ./vectors.rvf
|
|
623
|
-
|
|
624
|
-
# Force HNSWLib (C++ HNSW)
|
|
625
|
-
npx agentdb init --backend hnswlib
|
|
626
|
-
```
|
|
627
|
-
|
|
628
|
-
#### Migration
|
|
629
|
-
|
|
630
|
-
```bash
|
|
631
|
-
# Migrate v1 β v2
|
|
632
|
-
npx agentdb migrate --source ./old.db --target ./new.db
|
|
633
|
-
|
|
634
|
-
# Migrate v2 β v3 unified .rvf (same schemas, data copy)
|
|
635
|
-
npx agentdb migrate --source ./v2.db --to v3 --rvf-path ./unified.rvf
|
|
636
|
-
|
|
637
|
-
# Export to Cognitive Container
|
|
638
|
-
npx agentdb migrate --to rvf --rvf-path ./vectors.rvf
|
|
639
|
-
|
|
640
|
-
# Dry-run migration
|
|
641
|
-
npx agentdb migrate --dry-run --verbose
|
|
642
|
-
```
|
|
643
|
-
|
|
644
|
-
#### Health Checks
|
|
645
|
-
|
|
646
|
-
```bash
|
|
647
|
-
# Full diagnostic
|
|
648
|
-
npx agentdb doctor --verbose
|
|
649
|
-
|
|
650
|
-
# Check specific Cognitive Container
|
|
651
|
-
npx agentdb doctor --rvf-path ./vectors.rvf
|
|
652
|
-
|
|
653
|
-
# Auto-fix issues
|
|
654
|
-
npx agentdb doctor --fix
|
|
655
|
-
```
|
|
656
|
-
|
|
657
|
-
#### Federated Learning Setup
|
|
658
|
-
|
|
659
|
-
Configure cross-session federated learning for continuous improvement:
|
|
660
|
-
|
|
661
|
-
```typescript
|
|
662
|
-
import {
|
|
663
|
-
FederatedLearningCoordinator,
|
|
664
|
-
EphemeralLearningAgent,
|
|
665
|
-
} from "agentdb/services/federated-learning";
|
|
666
|
-
|
|
667
|
-
const coordinator = new FederatedLearningCoordinator({
|
|
668
|
-
agentId: "coordinator-1",
|
|
669
|
-
minQuality: 0.7,
|
|
670
|
-
maxAgents: 100,
|
|
671
|
-
});
|
|
672
|
-
|
|
673
|
-
const agent = new EphemeralLearningAgent({
|
|
674
|
-
agentId: "session-agent-1",
|
|
675
|
-
qualityFiltering: true,
|
|
676
|
-
});
|
|
677
|
-
|
|
678
|
-
const state = agent.exportState();
|
|
679
|
-
await coordinator.aggregate(state);
|
|
680
|
-
const merged = await coordinator.consolidate();
|
|
681
|
-
```
|
|
682
|
-
|
|
683
|
-
</details>
|
|
684
|
-
|
|
685
|
-
---
|
|
686
|
-
|
|
687
|
-
<details>
|
|
688
|
-
<summary><strong>Tutorials</strong> β 6 step-by-step walkthroughs from beginner to advanced</summary>
|
|
689
|
-
|
|
690
|
-
#### Tutorial 1: Build a Learning Code Review Agent
|
|
691
|
-
|
|
692
|
-
```typescript
|
|
693
|
-
import {
|
|
694
|
-
createDatabase,
|
|
695
|
-
ReasoningBank,
|
|
696
|
-
ReflexionMemory,
|
|
697
|
-
EmbeddingService,
|
|
698
|
-
} from "agentdb";
|
|
699
|
-
|
|
700
|
-
const db = await createDatabase("./code-reviewer.db");
|
|
701
|
-
const embedder = new EmbeddingService({ model: "Xenova/all-MiniLM-L6-v2" });
|
|
702
|
-
await embedder.initialize();
|
|
703
|
-
|
|
704
|
-
const reasoningBank = new ReasoningBank(db, embedder);
|
|
705
|
-
const reflexion = new ReflexionMemory(db, embedder);
|
|
706
|
-
|
|
707
|
-
await reasoningBank.storePattern({
|
|
708
|
-
taskType: "code_review",
|
|
709
|
-
approach: "Security scan > Type safety > Code quality > Performance",
|
|
710
|
-
successRate: 0.94,
|
|
711
|
-
});
|
|
712
|
-
|
|
713
|
-
const result = await performCodeReview(code);
|
|
714
|
-
await reflexion.storeEpisode({
|
|
715
|
-
sessionId: "review-1",
|
|
716
|
-
task: "Review authentication PR",
|
|
717
|
-
reward: result.issuesFound > 0 ? 0.9 : 0.6,
|
|
718
|
-
success: true,
|
|
719
|
-
critique: "Found SQL injection β security checks work!",
|
|
720
|
-
input: code,
|
|
721
|
-
output: result.findings,
|
|
722
|
-
});
|
|
723
|
-
|
|
724
|
-
const pastReviews = await reflexion.retrieveRelevant({
|
|
725
|
-
task: "authentication code review",
|
|
726
|
-
k: 5,
|
|
727
|
-
onlySuccesses: true,
|
|
728
|
-
});
|
|
729
|
-
```
|
|
730
|
-
|
|
731
|
-
#### Tutorial 2: RAG with Self-Learning Skills
|
|
732
|
-
|
|
733
|
-
```typescript
|
|
734
|
-
import { createDatabase, SkillLibrary, EmbeddingService } from "agentdb";
|
|
735
|
-
|
|
736
|
-
const db = await createDatabase("./rag-system.db");
|
|
737
|
-
const embedder = new EmbeddingService({ model: "Xenova/all-MiniLM-L6-v2" });
|
|
738
|
-
await embedder.initialize();
|
|
739
|
-
|
|
740
|
-
const skills = new SkillLibrary(db, embedder);
|
|
741
|
-
|
|
742
|
-
await skills.createSkill({
|
|
743
|
-
name: "expand_query",
|
|
744
|
-
description: "Expand user query with domain-specific synonyms",
|
|
745
|
-
signature: { inputs: { query: "string" }, outputs: { expanded: "string[]" } },
|
|
746
|
-
code: `const map = { 'bug': ['issue', 'defect', 'error'] }; ...`,
|
|
747
|
-
successRate: 0.92,
|
|
748
|
-
});
|
|
749
|
-
|
|
750
|
-
const applicable = await skills.searchSkills({
|
|
751
|
-
task: "find technical documentation",
|
|
752
|
-
k: 10,
|
|
753
|
-
});
|
|
754
|
-
```
|
|
755
|
-
|
|
756
|
-
#### Tutorial 3: Run Latent Space Simulations
|
|
757
|
-
|
|
758
|
-
```bash
|
|
759
|
-
npx agentdb simulate hnsw --iterations 3
|
|
760
|
-
npx agentdb simulate attention --iterations 3
|
|
761
|
-
npx agentdb simulate self-organizing --days 30
|
|
762
|
-
npx agentdb simulate --wizard
|
|
763
|
-
```
|
|
764
|
-
|
|
765
|
-
#### Tutorial 4: Cognitive Container Branching
|
|
766
|
-
|
|
767
|
-
```typescript
|
|
768
|
-
import { RvfBackend } from "agentdb/backends/rvf/RvfBackend";
|
|
769
|
-
|
|
770
|
-
const main = new RvfBackend({
|
|
771
|
-
dimension: 384,
|
|
772
|
-
metric: "cosine",
|
|
773
|
-
storagePath: "./main.rvf",
|
|
774
|
-
});
|
|
775
|
-
await main.initialize();
|
|
776
|
-
await main.insertAsync("doc-1", embedding1, { source: "production" });
|
|
777
|
-
await main.flush();
|
|
778
|
-
|
|
779
|
-
// Branch for experiment (copy-on-write, near-instant)
|
|
780
|
-
const experiment = await main.derive("./experiment.rvf");
|
|
781
|
-
await experiment.insertAsync("doc-exp-1", experimentEmbedding);
|
|
782
|
-
console.log(`Lineage depth: ${await experiment.lineageDepth()}`);
|
|
783
|
-
```
|
|
784
|
-
|
|
785
|
-
#### Tutorial 5: Self-Learning RAG Pipeline
|
|
786
|
-
|
|
787
|
-
```typescript
|
|
788
|
-
import { SelfLearningRvfBackend } from "agentdb/backends/rvf/SelfLearningRvfBackend";
|
|
789
|
-
|
|
790
|
-
const backend = await SelfLearningRvfBackend.create({
|
|
791
|
-
dimension: 384,
|
|
792
|
-
metric: "cosine",
|
|
793
|
-
storagePath: "./rag-vectors.rvf",
|
|
794
|
-
learning: true,
|
|
795
|
-
federated: true,
|
|
796
|
-
});
|
|
797
|
-
|
|
798
|
-
for (const doc of documents) {
|
|
799
|
-
await backend.insertAsync(doc.id, doc.embedding, { title: doc.title });
|
|
800
|
-
}
|
|
801
|
-
|
|
802
|
-
const results = await backend.searchAsync(queryEmbedding, 10);
|
|
803
|
-
backend.recordFeedback("query-1", 0.95);
|
|
804
|
-
await backend.tick();
|
|
805
|
-
```
|
|
806
|
-
|
|
807
|
-
#### Tutorial 6: Chat UI with Custom Knowledge Base
|
|
808
|
-
|
|
809
|
-
```bash
|
|
810
|
-
npx agentdb init --backend rvf --rvf-path ./docs.rvf
|
|
811
|
-
npx agentdb import ./docs/ --rvf-path ./docs.rvf
|
|
812
|
-
npx @agentdb/chat serve --rvf ./docs.rvf --port 3000
|
|
813
|
-
```
|
|
814
|
-
|
|
815
|
-
</details>
|
|
816
|
-
|
|
817
|
-
---
|
|
818
|
-
|
|
819
|
-
<details>
|
|
820
|
-
<summary><strong>Advanced Usage</strong> β batch ops, caching, solver tuning, GNN training, context synthesis</summary>
|
|
821
|
-
|
|
822
|
-
#### Batch Operations
|
|
823
|
-
|
|
824
|
-
```typescript
|
|
825
|
-
import { BatchOperations } from "agentdb/optimizations/BatchOperations";
|
|
826
|
-
|
|
827
|
-
const batchOps = new BatchOperations(db, embedder, {
|
|
828
|
-
batchSize: 100,
|
|
829
|
-
parallelism: 4,
|
|
830
|
-
progressCallback: (done, total) => console.log(`${done}/${total}`),
|
|
831
|
-
});
|
|
832
|
-
|
|
833
|
-
await batchOps.insertSkills([...skills]);
|
|
834
|
-
await batchOps.insertEpisodes([...episodes]);
|
|
835
|
-
await batchOps.insertPatterns([...patterns]);
|
|
836
|
-
```
|
|
837
|
-
|
|
838
|
-
#### Custom Backend Selection
|
|
839
|
-
|
|
840
|
-
```typescript
|
|
841
|
-
import { createBackend, detectBackends } from "agentdb/backends/factory";
|
|
842
|
-
|
|
843
|
-
const detection = await detectBackends();
|
|
844
|
-
// { ruvector: { available, native, gnn }, rvf: { sdk, node, wasm }, hnswlib: { available } }
|
|
845
|
-
|
|
846
|
-
const backend = await createBackend({
|
|
847
|
-
type: "rvf",
|
|
848
|
-
dimension: 384,
|
|
849
|
-
metric: "cosine",
|
|
850
|
-
storagePath: "./vectors.rvf",
|
|
851
|
-
});
|
|
852
|
-
```
|
|
853
|
-
|
|
854
|
-
#### Adaptive Index Tuning
|
|
855
|
-
|
|
856
|
-
```typescript
|
|
857
|
-
import { AgentDBSolver } from "agentdb/backends/rvf/RvfSolver";
|
|
858
|
-
|
|
859
|
-
const solver = await AgentDBSolver.create();
|
|
860
|
-
const trainResult = solver.train({
|
|
861
|
-
count: 50,
|
|
862
|
-
minDifficulty: 1,
|
|
863
|
-
maxDifficulty: 10,
|
|
864
|
-
});
|
|
865
|
-
const policy = solver.policy();
|
|
866
|
-
// 18 context buckets (3 range x 3 distractor x 2 noise)
|
|
867
|
-
```
|
|
868
|
-
|
|
869
|
-
#### Federated Session Manager
|
|
870
|
-
|
|
871
|
-
```typescript
|
|
872
|
-
import {
|
|
873
|
-
FederatedLearningCoordinator,
|
|
874
|
-
EphemeralLearningAgent,
|
|
875
|
-
} from "agentdb/services/federated-learning";
|
|
876
|
-
|
|
877
|
-
const coordinator = new FederatedLearningCoordinator({
|
|
878
|
-
agentId: "coord-main",
|
|
879
|
-
minQuality: 0.7,
|
|
880
|
-
maxAgents: 100,
|
|
881
|
-
});
|
|
882
|
-
const sessionAgent = new EphemeralLearningAgent({
|
|
883
|
-
agentId: `session-${Date.now()}`,
|
|
884
|
-
qualityFiltering: true,
|
|
885
|
-
});
|
|
886
|
-
|
|
887
|
-
await sessionAgent.processTask(embedding, 0.9);
|
|
888
|
-
const state = sessionAgent.exportState();
|
|
889
|
-
await coordinator.aggregate(state);
|
|
890
|
-
const merged = await coordinator.consolidate();
|
|
891
|
-
```
|
|
892
|
-
|
|
893
|
-
#### Context Synthesizer
|
|
894
|
-
|
|
895
|
-
```typescript
|
|
896
|
-
import { ContextSynthesizer } from "agentdb/controllers/ContextSynthesizer";
|
|
897
|
-
|
|
898
|
-
const synthesizer = new ContextSynthesizer();
|
|
899
|
-
const context = await synthesizer.synthesize(memories);
|
|
900
|
-
// { summary, patterns, successRate, averageReward, recommendations, keyInsights }
|
|
901
|
-
```
|
|
902
|
-
|
|
903
|
-
#### GNN Learning Backend
|
|
904
|
-
|
|
905
|
-
```typescript
|
|
906
|
-
import { LearningBackend } from "agentdb/backends/LearningBackend";
|
|
907
|
-
|
|
908
|
-
const learner = new LearningBackend({ dimension: 384 });
|
|
909
|
-
const enhanced = learner.enhance(queryEmbedding, neighborEmbeddings, weights);
|
|
910
|
-
learner.addSample(embedding, "positive", 1.0, { source: "feedback" });
|
|
911
|
-
const result = await learner.train(10);
|
|
912
|
-
// { epochs: 10, finalLoss: 0.023, improvement: 15.2, durationMs: 340 }
|
|
913
|
-
```
|
|
914
|
-
|
|
915
|
-
</details>
|
|
916
|
-
|
|
917
|
-
---
|
|
918
|
-
|
|
919
|
-
### Intelligence & Learning
|
|
920
|
-
|
|
921
|
-
How AgentDB learns, reasons, and improves over time β from self-learning search to reinforcement learning and causal graphs.
|
|
922
|
-
|
|
923
|
-
<details>
|
|
924
|
-
<summary><strong>Self-Learning Pipeline</strong> β how search improves 36% automatically</summary>
|
|
925
|
-
|
|
926
|
-
AgentDB's self-learning pipeline continuously improves search quality through a six-phase cycle:
|
|
927
|
-
|
|
928
|
-
```mermaid
|
|
929
|
-
flowchart LR
|
|
930
|
-
Q[Query] --> R[Semantic Router]
|
|
931
|
-
R --> S[SONA Enhancement]
|
|
932
|
-
S --> T[HNSW Search]
|
|
933
|
-
T --> U[Results]
|
|
934
|
-
U --> V[Feedback]
|
|
935
|
-
V --> W[Contrastive Trainer<br/>InfoNCE + Hard Negatives]
|
|
936
|
-
W --> X[Micro-LoRA Update]
|
|
937
|
-
X --> Y[EWC++ Consolidation]
|
|
938
|
-
Y --> Z[Federated Aggregation]
|
|
939
|
-
```
|
|
940
|
-
|
|
941
|
-
### 1. Semantic Query Routing
|
|
942
|
-
|
|
943
|
-
The `SemanticQueryRouter` classifies query intent by comparing against learned intent centroids using efficient min-heap top-k selection (O(n log k)). It lazily loads `@ruvector/router` for sub-millisecond HNSW routing and falls back to brute-force cosine with pre-computed norms when native bindings aren't available.
|
|
944
|
-
|
|
945
|
-
The router also selects the adaptive ef-search arm for the query. Four ef-search levels (50, 100, 200, 400) are chosen based on the solver's Thompson Sampling policy for the matching context bucket.
|
|
946
|
-
|
|
947
|
-
```typescript
|
|
948
|
-
// Router learns intents from usage patterns
|
|
949
|
-
router.addIntent("technical_search", embedding); // up to 100 exemplars per intent
|
|
950
|
-
router.addIntent("conversational", embedding);
|
|
951
|
-
const { intent, confidence } = await router.route(queryEmbedding, k);
|
|
952
|
-
|
|
953
|
-
// Router state persists across restarts (debounced 5s save)
|
|
954
|
-
// Max 1,000 intents, JSON fallback or native persistence
|
|
955
|
-
```
|
|
956
|
-
|
|
957
|
-
### 2. SONA Enhancement
|
|
958
|
-
|
|
959
|
-
Context enrichment from trajectory history. The SONA engine (`@ruvector/sona`) tracks query trajectories and enriches embeddings with session context before search. SONA also applies the base LoRA adapter to the query embedding, adjusting it in sub-millisecond time based on learned patterns.
|
|
960
|
-
|
|
961
|
-
### 3. Contrastive Training
|
|
962
|
-
|
|
963
|
-
InfoNCE contrastive loss with hard negative mining inspired by NV-Retriever's positive-aware filtering:
|
|
964
|
-
|
|
965
|
-
- **Loss function:** `L = -log(exp(sim(anchor, positive) / Ο) / Ξ£ exp(sim(anchor, negative_i) / Ο))`
|
|
966
|
-
- **Hard negative filtering:** Rejects candidates where `sim(candidate, positive) > 0.85`, eliminating ~70% of false negatives
|
|
967
|
-
- **3-stage curriculum:** Progressively increases difficulty β negatives per sample (4 β 8 β 16), hardness threshold (0.5 β 0.3 β 0.1), 100 batches per stage
|
|
968
|
-
- **AdamW optimizer:** Ξ²1=0.9, Ξ²2=0.999, decoupled weight decay, full bias correction
|
|
969
|
-
- **Temperature:** Bounded 0.01-1.0 (default: 0.07)
|
|
970
|
-
|
|
971
|
-
```typescript
|
|
972
|
-
// ContrastiveTrainer handles hard negative mining automatically
|
|
973
|
-
const result = trainer.trainBatch([
|
|
974
|
-
{
|
|
975
|
-
anchor: queryEmb,
|
|
976
|
-
positive: goodResultEmb,
|
|
977
|
-
negatives: [badResult1, badResult2],
|
|
978
|
-
},
|
|
979
|
-
]);
|
|
980
|
-
// result: { loss, gradients, batchSize }
|
|
981
|
-
```
|
|
982
|
-
|
|
983
|
-
When native SIMD is available, cosine similarity and AdamW steps delegate to the NativeAccelerator for hardware-accelerated computation.
|
|
984
|
-
|
|
985
|
-
### 4. Micro-LoRA Adaptation
|
|
986
|
-
|
|
987
|
-
Sub-millisecond embedding adjustment per query. A lightweight projection matrix (W: dΓd + bias: d) is applied to the query embedding before search, specializing for each user's query patterns without modifying the base model. LoRA adapters are updated after each contrastive training batch.
|
|
988
|
-
|
|
989
|
-
### 5. EWC++ Consolidation
|
|
990
|
-
|
|
991
|
-
Elastic Weight Consolidation prevents catastrophic forgetting by penalizing changes to important parameters. The Fisher information matrix is updated incrementally via the NativeAccelerator's `ewcUpdateFisher()` and penalty is computed via `ewcPenalty()`, ensuring previously learned patterns survive new training.
|
|
992
|
-
|
|
993
|
-
### 6. Federated Session Aggregation
|
|
994
|
-
|
|
995
|
-
Cross-session LoRA merging for continuous improvement. Lightweight `EphemeralLearningAgent` instances (~5MB each) export their state to a `FederatedLearningCoordinator` for quality-filtered aggregation (minimum quality threshold: 0.7, up to 100 agents).
|
|
996
|
-
|
|
997
|
-
### How `tick()` Works
|
|
998
|
-
|
|
999
|
-
Each learning tick performs these steps in sequence:
|
|
1000
|
-
|
|
1001
|
-
1. **Flush SONA** β persist trajectory context
|
|
1002
|
-
2. **Train contrastive batch** β 32 samples from recorded feedback
|
|
1003
|
-
3. **Train solver** β 50 puzzles to update Thompson Sampling policy
|
|
1004
|
-
4. **Decay access frequencies** β multiply by 0.99, prune entries below 0.001 (every 50 ticks)
|
|
1005
|
-
5. **Update temporal compressor** β adjust compression tiers
|
|
1006
|
-
6. **Assess health** β latency tracking via health monitor
|
|
1007
|
-
7. **Consolidate federated state** β merge distributed agent states
|
|
1008
|
-
8. **Acceptance check** β every 100 ticks, run A/B/C ablation (mode A: fixed heuristic, mode B: compiler-suggested, mode C: learned Thompson Sampling) to validate adaptive ef-search
|
|
1009
|
-
|
|
1010
|
-
### Full Example
|
|
1011
|
-
|
|
1012
|
-
```typescript
|
|
1013
|
-
import { SelfLearningRvfBackend } from "agentdb/backends/rvf/SelfLearningRvfBackend";
|
|
1014
|
-
|
|
1015
|
-
const backend = await SelfLearningRvfBackend.create({
|
|
1016
|
-
dimension: 384,
|
|
1017
|
-
metric: "cosine",
|
|
1018
|
-
storagePath: "./vectors.rvf",
|
|
1019
|
-
learning: true,
|
|
1020
|
-
federated: true,
|
|
1021
|
-
positiveThreshold: 0.7,
|
|
1022
|
-
negativeThreshold: 0.3,
|
|
1023
|
-
trainingBatchSize: 32,
|
|
1024
|
-
tickIntervalMs: 5000,
|
|
1025
|
-
});
|
|
1026
|
-
|
|
1027
|
-
// Insert vectors
|
|
1028
|
-
await backend.insertAsync("doc-1", embedding, { source: "docs" });
|
|
1029
|
-
|
|
1030
|
-
// Search (automatically enhanced by SONA + router)
|
|
1031
|
-
const results = await backend.searchAsync(queryEmbedding, 10);
|
|
1032
|
-
|
|
1033
|
-
// Record feedback to drive learning
|
|
1034
|
-
backend.recordFeedback("query-123", 0.9); // high quality result
|
|
1035
|
-
|
|
1036
|
-
// Run a learning tick (contrastive training + LoRA update + EWC consolidation)
|
|
1037
|
-
await backend.tick();
|
|
1038
|
-
|
|
1039
|
-
// Check learning progress
|
|
1040
|
-
const stats = backend.getLearningStats();
|
|
1041
|
-
console.log(
|
|
1042
|
-
`Trajectories: ${stats.trajectoryCount}, LoRA rank: ${stats.loraRank}`,
|
|
1043
|
-
);
|
|
1044
|
-
```
|
|
1045
|
-
|
|
1046
|
-
</details>
|
|
1047
|
-
|
|
1048
|
-
---
|
|
1049
|
-
|
|
1050
|
-
<details>
|
|
1051
|
-
<summary><strong>Cognitive Memory Patterns</strong> β 6 ways your agent learns like a human</summary>
|
|
1052
|
-
|
|
1053
|
-
AgentDB implements six cognitive memory patterns inspired by how humans learn:
|
|
1054
|
-
|
|
1055
|
-
### 1. ReasoningBank β Pattern Learning
|
|
1056
|
-
|
|
1057
|
-
Store successful reasoning patterns and retrieve them by semantic similarity. The system learns which approaches work best for different task types.
|
|
1058
|
-
|
|
1059
|
-
```typescript
|
|
1060
|
-
await reasoningBank.storePattern({
|
|
1061
|
-
taskType: "bug_investigation",
|
|
1062
|
-
approach: "Check logs > Reproduce > Binary search for root cause",
|
|
1063
|
-
successRate: 0.92,
|
|
1064
|
-
tags: ["debugging", "systematic"],
|
|
1065
|
-
});
|
|
1066
|
-
|
|
1067
|
-
const patterns = await reasoningBank.searchPatterns({
|
|
1068
|
-
task: "debug memory leak",
|
|
1069
|
-
k: 10,
|
|
1070
|
-
threshold: 0.7,
|
|
1071
|
-
});
|
|
1072
|
-
```
|
|
1073
|
-
|
|
1074
|
-
### 2. Reflexion Memory β Learn from Experience
|
|
1075
|
-
|
|
1076
|
-
Store complete task episodes with self-generated critiques, then replay them to improve future performance. Based on Shinn et al., 2023.
|
|
1077
|
-
|
|
1078
|
-
```typescript
|
|
1079
|
-
await reflexion.storeEpisode({
|
|
1080
|
-
sessionId: "session-1",
|
|
1081
|
-
task: "Fix authentication bug",
|
|
1082
|
-
reward: 0.95,
|
|
1083
|
-
success: true,
|
|
1084
|
-
critique: "OAuth2 PKCE flow was more secure than basic flow",
|
|
1085
|
-
input: "Users cannot log in",
|
|
1086
|
-
output: "Working OAuth2 implementation",
|
|
1087
|
-
latencyMs: 1200,
|
|
1088
|
-
tokensUsed: 500,
|
|
1089
|
-
});
|
|
1090
|
-
|
|
1091
|
-
const similar = await reflexion.retrieveRelevant({
|
|
1092
|
-
task: "authentication issues",
|
|
1093
|
-
k: 10,
|
|
1094
|
-
onlySuccesses: true,
|
|
1095
|
-
});
|
|
1096
|
-
```
|
|
1097
|
-
|
|
1098
|
-
### 3. Skill Library β Lifelong Learning
|
|
1099
|
-
|
|
1100
|
-
Transform successful patterns into reusable, composable skills that improve over time.
|
|
1101
|
-
|
|
1102
|
-
```typescript
|
|
1103
|
-
await skills.createSkill({
|
|
1104
|
-
name: "jwt_authentication",
|
|
1105
|
-
description: "Generate and validate JWT tokens",
|
|
1106
|
-
signature: { inputs: { userId: "string" }, outputs: { token: "string" } },
|
|
1107
|
-
code: "implementation...",
|
|
1108
|
-
successRate: 0.92,
|
|
1109
|
-
});
|
|
1110
|
-
|
|
1111
|
-
const applicable = await skills.searchSkills({
|
|
1112
|
-
task: "user authentication",
|
|
1113
|
-
k: 5,
|
|
1114
|
-
minSuccessRate: 0.7,
|
|
1115
|
-
});
|
|
1116
|
-
```
|
|
1117
|
-
|
|
1118
|
-
### 4. Causal Memory Graph β Intervention Causality
|
|
1119
|
-
|
|
1120
|
-
Track `p(y|do(x))` using doubly robust estimation. Learn what interventions cause what outcomes.
|
|
1121
|
-
|
|
1122
|
-
```typescript
|
|
1123
|
-
import { CausalMemoryGraph } from "agentdb";
|
|
1124
|
-
|
|
1125
|
-
const causalGraph = new CausalMemoryGraph(db);
|
|
1126
|
-
|
|
1127
|
-
const experimentId = causalGraph.createExperiment({
|
|
1128
|
-
name: "test_error_handling",
|
|
1129
|
-
hypothesis: "Try-catch reduces crash rate",
|
|
1130
|
-
treatmentId: 123,
|
|
1131
|
-
treatmentType: "episode",
|
|
1132
|
-
controlId: 124,
|
|
1133
|
-
startTime: Date.now(),
|
|
1134
|
-
sampleSize: 0,
|
|
1135
|
-
status: "running",
|
|
1136
|
-
});
|
|
1137
|
-
|
|
1138
|
-
const { uplift, pValue } = causalGraph.calculateUplift(experimentId);
|
|
1139
|
-
```
|
|
1140
|
-
|
|
1141
|
-
### 5. Explainable Recall β Provenance Certificates
|
|
1142
|
-
|
|
1143
|
-
Every retrieval comes with a cryptographic Merkle proof explaining why specific memories were selected.
|
|
1144
|
-
|
|
1145
|
-
```typescript
|
|
1146
|
-
const result = await causalRecall.recall(
|
|
1147
|
-
"query-123",
|
|
1148
|
-
"How to optimize API response time",
|
|
1149
|
-
12,
|
|
1150
|
-
["performance"],
|
|
1151
|
-
"internal",
|
|
1152
|
-
);
|
|
1153
|
-
|
|
1154
|
-
console.log(`Certificate: ${result.certificate.id}`);
|
|
1155
|
-
console.log(`Completeness: ${result.certificate.completenessScore}`);
|
|
1156
|
-
```
|
|
1157
|
-
|
|
1158
|
-
### 6. Nightly Learner β Automated Discovery
|
|
1159
|
-
|
|
1160
|
-
Background process that discovers causal patterns, consolidates skills, and prunes low-quality data automatically.
|
|
1161
|
-
|
|
1162
|
-
```typescript
|
|
1163
|
-
const learner = new NightlyLearner(db, embedder);
|
|
1164
|
-
const discovered = await learner.discover({
|
|
1165
|
-
minAttempts: 3,
|
|
1166
|
-
minSuccessRate: 0.6,
|
|
1167
|
-
minConfidence: 0.7,
|
|
1168
|
-
dryRun: false,
|
|
1169
|
-
});
|
|
1170
|
-
```
|
|
1171
|
-
|
|
1172
|
-
</details>
|
|
1173
|
-
|
|
1174
|
-
---
|
|
1175
|
-
|
|
1176
|
-
### Storage & Data
|
|
1177
|
-
|
|
1178
|
-
How AgentDB stores vectors, manages compression tiers, and provides MongoDB-style filtering β all in a single Cognitive Container.
|
|
1179
|
-
|
|
1180
|
-
<details>
|
|
1181
|
-
<summary><strong>Cognitive Container (RVF Format)</strong> β single-file storage with crash safety and branching</summary>
|
|
1182
|
-
|
|
1183
|
-
The **Cognitive Container** is AgentDB's native storage format (`.rvf` β RuVector Format). It packs vectors, indexes, learning state, and a cryptographic witness chain into a single file with crash safety, progressive indexing, and full lineage tracking.
|
|
1184
|
-
|
|
1185
|
-
### Structure
|
|
1186
|
-
|
|
1187
|
-
```mermaid
|
|
1188
|
-
graph TB
|
|
1189
|
-
subgraph "store.rvf"
|
|
1190
|
-
H[Header + Magic Bytes]
|
|
1191
|
-
S1[Segment 1<br/>Vectors + Metadata]
|
|
1192
|
-
S2[Segment 2]
|
|
1193
|
-
IX[HNSW Index<br/>Progressive]
|
|
1194
|
-
WC[Witness Chain<br/>SHAKE-256]
|
|
1195
|
-
LN[Lineage Record<br/>Parent ID + Depth]
|
|
1196
|
-
end
|
|
1197
|
-
H --> S1
|
|
1198
|
-
S1 --> S2
|
|
1199
|
-
S2 --> IX
|
|
1200
|
-
IX --> WC
|
|
1201
|
-
WC --> LN
|
|
1202
|
-
```
|
|
1203
|
-
|
|
1204
|
-
### Key Capabilities
|
|
1205
|
-
|
|
1206
|
-
| Feature | Description |
|
|
1207
|
-
| ------------------------- | ------------------------------------------------------------------------- |
|
|
1208
|
-
| **Single-file** | Everything in one Cognitive Container (`.rvf`) β vectors, index, metadata |
|
|
1209
|
-
| **Crash-safe** | Append-only log with checksums, safe concurrent access |
|
|
1210
|
-
| **COW Branching** | Create copy-on-write branches for experiments (near-instant) |
|
|
1211
|
-
| **Lineage Tracking** | `fileId()`, `parentId()`, `lineageDepth()` for file-level provenance |
|
|
1212
|
-
| **Progressive Indexing** | 3-layer HNSW quality tiers, index builds incrementally as data arrives |
|
|
1213
|
-
| **Witness Chains** | SHAKE-256 cryptographic verification (73 bytes per entry) |
|
|
1214
|
-
| **Filter Expressions** | 11 operators for metadata filtering, max 64 depth |
|
|
1215
|
-
| **Auto-Compaction** | `compact()` reclaims space, reports segments compacted & bytes reclaimed |
|
|
1216
|
-
| **Readonly Mode** | `openReadonly()` for concurrent readers without locks |
|
|
1217
|
-
| **Segment Introspection** | `segments()` returns id, type, and payload length per segment |
|
|
1218
|
-
| **Kernel Embedding** | Embed unikernel images directly into Cognitive Containers |
|
|
1219
|
-
| **eBPF Embedding** | Embed and extract eBPF bytecode for programmable queries |
|
|
1220
|
-
|
|
1221
|
-
### Configuration
|
|
1222
|
-
|
|
1223
|
-
```typescript
|
|
1224
|
-
const backend = new RvfBackend({
|
|
1225
|
-
dimension: 384,
|
|
1226
|
-
metric: "cosine", // 'cosine' | 'l2' | 'dotproduct'
|
|
1227
|
-
storagePath: "./vectors.rvf",
|
|
1228
|
-
rvfBackend: "auto", // 'auto' | 'node' (N-API) | 'wasm' (browser)
|
|
1229
|
-
batchThreshold: 100, // Auto-flush after N sync inserts (1-10,000)
|
|
1230
|
-
compression: "none", // 'none' (fp32) | 'scalar' (int8) | 'product' (PQ)
|
|
1231
|
-
hardwareProfile: 0, // 0=Generic | 1=Core | 2=Hot | 3=Full
|
|
1232
|
-
enableStats: true, // Track insert/search/flush/compaction timing
|
|
1233
|
-
});
|
|
1234
|
-
```
|
|
1235
|
-
|
|
1236
|
-
**Hardware profiles** tune internal parameters for your deployment:
|
|
1237
|
-
|
|
1238
|
-
| Profile | Level | Best For |
|
|
1239
|
-
| ----------- | --------------------------- | ----------------------- |
|
|
1240
|
-
| Generic (0) | Conservative defaults | Unknown hardware |
|
|
1241
|
-
| Core (1) | Balanced throughput/latency | Developer machines |
|
|
1242
|
-
| Hot (2) | Aggressive caching | High-throughput servers |
|
|
1243
|
-
| Full (3) | Maximum parallelism | Dedicated vector search |
|
|
1244
|
-
|
|
1245
|
-
### Witness Chains
|
|
1246
|
-
|
|
1247
|
-
Every mutation is recorded in a tamper-evident SHAKE-256 witness chain (73 bytes per entry). This provides cryptographic proof that data has not been modified after the fact:
|
|
1248
|
-
|
|
1249
|
-
```typescript
|
|
1250
|
-
const result = backend.verifyWitnessChain();
|
|
1251
|
-
// { valid: true, entries: 1042, algorithm: 'SHAKE-256' }
|
|
1252
|
-
|
|
1253
|
-
// Verification uses @ruvector/rvf-wasm: rvf_witness_verify(), rvf_witness_count()
|
|
1254
|
-
```
|
|
1255
|
-
|
|
1256
|
-
### Filter Expressions
|
|
1257
|
-
|
|
1258
|
-
RVF supports 11 filter operators for metadata-filtered search. Filters are serialized to a compact field-ID format with a maximum depth of 64 expressions for security:
|
|
1259
|
-
|
|
1260
|
-
```typescript
|
|
1261
|
-
import { FilterBuilder } from "agentdb/backends/rvf/FilterBuilder";
|
|
1262
|
-
|
|
1263
|
-
const filter = new FilterBuilder()
|
|
1264
|
-
.eq("status", "active")
|
|
1265
|
-
.gt("score", 0.5)
|
|
1266
|
-
.range("timestamp", startDate, endDate)
|
|
1267
|
-
.in("category", ["research", "engineering"])
|
|
1268
|
-
.build();
|
|
1269
|
-
|
|
1270
|
-
const results = await backend.searchAsync(queryVector, 10, { filter });
|
|
1271
|
-
|
|
1272
|
-
// Also supports filter-based deletion
|
|
1273
|
-
await backend.deleteByFilter(filter);
|
|
1274
|
-
```
|
|
1275
|
-
|
|
1276
|
-
**Available operators:** `eq`, `ne`, `lt`, `le`, `gt`, `ge`, `in`, `range`, `and`, `or`, `not`
|
|
1277
|
-
|
|
1278
|
-
### Performance Stats
|
|
1279
|
-
|
|
1280
|
-
The RVF backend tracks detailed performance counters:
|
|
1281
|
-
|
|
1282
|
-
```typescript
|
|
1283
|
-
const stats = backend.getPerformanceStats();
|
|
1284
|
-
// {
|
|
1285
|
-
// insertCount: 10432, insertTotalMs: 521.6, avgInsertMs: 0.05,
|
|
1286
|
-
// searchCount: 8891, searchTotalMs: 178.2, avgSearchMs: 0.02,
|
|
1287
|
-
// flushCount: 104, compactionCount: 3
|
|
1288
|
-
// }
|
|
1289
|
-
```
|
|
1290
|
-
|
|
1291
|
-
### Kernel & eBPF Embedding
|
|
1292
|
-
|
|
1293
|
-
Cognitive Containers can embed unikernel images and eBPF bytecode directly, enabling self-contained deployable artifacts:
|
|
1294
|
-
|
|
1295
|
-
```typescript
|
|
1296
|
-
// Embed a kernel image into the Cognitive Container
|
|
1297
|
-
await backend.embedKernel({
|
|
1298
|
-
arch: "x86_64", // 'x86_64' | 'aarch64' | 'riscv64'
|
|
1299
|
-
type: "firecracker", // 'firecracker' | 'qemu' | 'cloud-hypervisor'
|
|
1300
|
-
flags: 0,
|
|
1301
|
-
image: kernelBuffer,
|
|
1302
|
-
apiPort: 8080,
|
|
1303
|
-
cmdline: "console=ttyS0",
|
|
1304
|
-
});
|
|
1305
|
-
|
|
1306
|
-
// Extract it later
|
|
1307
|
-
const kernel = await backend.extractKernel();
|
|
1308
|
-
// { header: { arch, type, ... }, image: Uint8Array }
|
|
1309
|
-
|
|
1310
|
-
// eBPF bytecode for programmable query filters
|
|
1311
|
-
await backend.embedEbpf(ebpfBytecode);
|
|
1312
|
-
const ebpf = await backend.extractEbpf();
|
|
1313
|
-
```
|
|
1314
|
-
|
|
1315
|
-
### CLI Commands
|
|
1316
|
-
|
|
1317
|
-
```bash
|
|
1318
|
-
# Show store status
|
|
1319
|
-
npx agentdb rvf status ./store.rvf
|
|
1320
|
-
|
|
1321
|
-
# Compact to reclaim space
|
|
1322
|
-
npx agentdb rvf compact ./store.rvf
|
|
1323
|
-
|
|
1324
|
-
# Create a branch (copy-on-write)
|
|
1325
|
-
npx agentdb rvf derive ./parent.rvf ./experiment.rvf
|
|
1326
|
-
|
|
1327
|
-
# List segments
|
|
1328
|
-
npx agentdb rvf segments ./store.rvf
|
|
1329
|
-
|
|
1330
|
-
# Detect SDK availability
|
|
1331
|
-
npx agentdb rvf detect
|
|
1332
|
-
```
|
|
1333
|
-
|
|
1334
|
-
### Programmatic Usage
|
|
1335
|
-
|
|
1336
|
-
```typescript
|
|
1337
|
-
import { RvfBackend } from "agentdb/backends/rvf/RvfBackend";
|
|
1338
|
-
|
|
1339
|
-
const backend = new RvfBackend({
|
|
1340
|
-
dimension: 384,
|
|
1341
|
-
metric: "cosine",
|
|
1342
|
-
storagePath: "./vectors.rvf",
|
|
1343
|
-
rvfBackend: "auto", // 'node' for N-API, 'wasm' for browser
|
|
1344
|
-
});
|
|
1345
|
-
await backend.initialize();
|
|
1346
|
-
|
|
1347
|
-
// Async operations (native)
|
|
1348
|
-
await backend.insertAsync("vec-1", embedding, { tag: "example" });
|
|
1349
|
-
const results = await backend.searchAsync(queryVector, 10);
|
|
1350
|
-
await backend.flush();
|
|
1351
|
-
|
|
1352
|
-
// COW branching
|
|
1353
|
-
const branch = await backend.derive("./experiment.rvf");
|
|
1354
|
-
const lineage = await backend.lineageDepth();
|
|
1355
|
-
```
|
|
1356
|
-
|
|
1357
|
-
### Backend Selection
|
|
1358
|
-
|
|
1359
|
-
```bash
|
|
1360
|
-
# Initialize with RVF backend
|
|
1361
|
-
npx agentdb init --backend rvf --rvf-path ./vectors.rvf
|
|
1362
|
-
|
|
1363
|
-
# Migrate v2 database to v3 unified .rvf
|
|
1364
|
-
npx agentdb migrate --source ./v2.db --to v3 --rvf-path ./unified.rvf
|
|
1365
|
-
|
|
1366
|
-
# Migrate existing data to RVF
|
|
1367
|
-
npx agentdb migrate --to rvf --rvf-path ./vectors.rvf
|
|
1368
|
-
|
|
1369
|
-
# Check RVF in diagnostics
|
|
1370
|
-
npx agentdb doctor --rvf-path ./vectors.rvf
|
|
1371
|
-
```
|
|
1372
|
-
|
|
1373
|
-
</details>
|
|
1374
|
-
|
|
1375
|
-
---
|
|
1376
|
-
|
|
1377
|
-
### Performance & Architecture
|
|
1378
|
-
|
|
1379
|
-
The engine behind AgentDB's speed β SIMD acceleration, graph intelligence, browser WASM, and benchmarking.
|
|
1380
|
-
|
|
1381
|
-
<details>
|
|
1382
|
-
<summary><strong>SIMD & Native Acceleration</strong> β 15 capability groups with automatic fallbacks</summary>
|
|
1383
|
-
|
|
1384
|
-
The `NativeAccelerator` provides 15 capability groups bridging 11 `@ruvector` packages, with pure-JS fallbacks for every operation via `SimdFallbacks`.
|
|
1385
|
-
|
|
1386
|
-
### Capability Groups
|
|
1387
|
-
|
|
1388
|
-
| Group | Operations | Package |
|
|
1389
|
-
| -------------------------- | ---------------------------------------------------- | ---------------------- |
|
|
1390
|
-
| **Vector Distance & Math** | cosine, dot, L2, hamming, add, mul, scale, normalize | `ruvector` |
|
|
1391
|
-
| **Activations** | softmax, relu, gelu, sigmoid, layerNorm | `@ruvector/ruvllm` |
|
|
1392
|
-
| **Loss Functions** | InfoNCE (contrastive) | `@ruvector/sona` |
|
|
1393
|
-
| **Optimizers** | AdamW step | `@ruvector/sona` |
|
|
1394
|
-
| **Quantization** | scalar 8-bit/4-bit, product quantization | `@ruvector/rvf` |
|
|
1395
|
-
| **WASM Store** | create, ingest, query, export, close | `@ruvector/rvf-wasm` |
|
|
1396
|
-
| **Verification** | witness chain, segment header | `@ruvector/rvf-node` |
|
|
1397
|
-
| **Graph Transactions** | begin, commit, rollback | `@ruvector/graph-node` |
|
|
1398
|
-
| **Graph Batch Insert** | high-throughput node/edge ingestion | `@ruvector/graph-node` |
|
|
1399
|
-
| **Graph Cypher** | pattern matching, path queries | `@ruvector/graph-node` |
|
|
1400
|
-
| **Core Batch Insert** | native vector batch ingestion | `ruvector` |
|
|
1401
|
-
| **EWC Memory** | penalty calculation, Fisher update | `@ruvector/sona` |
|
|
1402
|
-
| **Router** | save/load state persistence | `@ruvector/router` |
|
|
1403
|
-
| **SONA** | context addition, flush, base LoRA | `@ruvector/sona` |
|
|
1404
|
-
| **Compression** | tensor compress/decompress | `@ruvector/rvf` |
|
|
1405
|
-
|
|
1406
|
-
### Auto-Detection
|
|
1407
|
-
|
|
1408
|
-
Each capability group is lazily loaded β only the packages actually installed on the system are loaded, and each load is tried independently so a missing package never blocks others:
|
|
1409
|
-
|
|
1410
|
-
```typescript
|
|
1411
|
-
import { NativeAccelerator } from "agentdb/backends/rvf/NativeAccelerator";
|
|
1412
|
-
|
|
1413
|
-
const accel = new NativeAccelerator();
|
|
1414
|
-
const stats = await accel.initialize();
|
|
1415
|
-
|
|
1416
|
-
console.log(stats);
|
|
1417
|
-
// AcceleratorStats:
|
|
1418
|
-
// {
|
|
1419
|
-
// simdAvailable: true, // Vector distance + element-wise math
|
|
1420
|
-
// simdActivationsAvailable: true, // softmax, relu, gelu, sigmoid, layerNorm
|
|
1421
|
-
// wasmVerifyAvailable: true, // Witness chain & header verification
|
|
1422
|
-
// wasmStoreAvailable: true, // In-browser HNSW store
|
|
1423
|
-
// wasmQuantizationAvailable: true, // Scalar/product quantization ops
|
|
1424
|
-
// nativeInfoNceAvailable: true, // Hardware-accelerated InfoNCE loss
|
|
1425
|
-
// nativeAdamWAvailable: true, // Hardware-accelerated AdamW optimizer
|
|
1426
|
-
// nativeTensorCompressAvailable: true, // SVD tensor compression
|
|
1427
|
-
// routerPersistAvailable: true, // Semantic router state persistence
|
|
1428
|
-
// sonaExtendedAvailable: true, // SONA trajectory context & base LoRA
|
|
1429
|
-
// }
|
|
1430
|
-
// Additional capabilities (probed separately):
|
|
1431
|
-
// accel.graphTxAvailable // Graph transactions
|
|
1432
|
-
// accel.graphBatchInsertAvailable // Graph batch insert
|
|
1433
|
-
// accel.graphCypherAvailable // Cypher query engine
|
|
1434
|
-
// accel.coreBatchInsertAvailable // Native vector batch insert
|
|
1435
|
-
// accel.ewcManagerAvailable // EWC++ memory consolidation
|
|
1436
|
-
```
|
|
1437
|
-
|
|
1438
|
-
### Pure-JS Fallbacks
|
|
1439
|
-
|
|
1440
|
-
Every SIMD operation has a pure-JS fallback with 4-wide loop unrolling for reasonable performance even without native bindings:
|
|
1441
|
-
|
|
1442
|
-
```typescript
|
|
1443
|
-
import { SimdFallbacks } from "agentdb/backends/rvf/SimdFallbacks";
|
|
1444
|
-
|
|
1445
|
-
// Same API as native, ~10-50x slower but always available
|
|
1446
|
-
const similarity = SimdFallbacks.jsCosineSimilarity(vecA, vecB);
|
|
1447
|
-
const loss = SimdFallbacks.jsInfoNceLoss(
|
|
1448
|
-
anchor,
|
|
1449
|
-
positive,
|
|
1450
|
-
negatives,
|
|
1451
|
-
temperature,
|
|
1452
|
-
);
|
|
1453
|
-
const result = SimdFallbacks.jsAdamWStep(
|
|
1454
|
-
params,
|
|
1455
|
-
grads,
|
|
1456
|
-
m,
|
|
1457
|
-
v,
|
|
1458
|
-
lr,
|
|
1459
|
-
beta1,
|
|
1460
|
-
beta2,
|
|
1461
|
-
weightDecay,
|
|
1462
|
-
t,
|
|
1463
|
-
);
|
|
1464
|
-
```
|
|
1465
|
-
|
|
1466
|
-
### Additional SIMD Operations
|
|
1467
|
-
|
|
1468
|
-
The `SIMDVectorOps` class provides batch operations and platform-specific detection:
|
|
1469
|
-
|
|
1470
|
-
```typescript
|
|
1471
|
-
import { SIMDVectorOps, detectSIMDSupport } from "agentdb/simd";
|
|
1472
|
-
|
|
1473
|
-
const simd = new SIMDVectorOps();
|
|
1474
|
-
const support = detectSIMDSupport();
|
|
1475
|
-
// { wasm: true, x64: false, avx2: false, neon: false }
|
|
1476
|
-
|
|
1477
|
-
const similarities = simd.batchCosineSimilarity(query, [vec1, vec2, vec3]);
|
|
1478
|
-
```
|
|
1479
|
-
|
|
1480
|
-
</details>
|
|
1481
|
-
|
|
1482
|
-
---
|
|
1483
|
-
|
|
1484
|
-
<details>
|
|
1485
|
-
<summary><strong>Graph Intelligence</strong> β Cypher queries, causal reasoning, GNN attention</summary>
|
|
1486
|
-
|
|
1487
|
-
AgentDB integrates `@ruvector/graph-node` for a full graph database with Cypher query support, transactional batch inserts, and GNN-powered attention.
|
|
1488
|
-
|
|
1489
|
-
### Cypher Queries
|
|
1490
|
-
|
|
1491
|
-
Full Neo4j-compatible Cypher syntax including MATCH, RETURN, WHERE, ORDER BY, LIMIT, relationship patterns, and graph traversal:
|
|
1492
|
-
|
|
1493
|
-
```typescript
|
|
1494
|
-
import { GraphDatabaseAdapter } from "agentdb/backends/graph/GraphDatabaseAdapter";
|
|
1495
|
-
|
|
1496
|
-
const graph = new GraphDatabaseAdapter({
|
|
1497
|
-
storagePath: "./graph.db",
|
|
1498
|
-
dimensions: 384,
|
|
1499
|
-
distanceMetric: "Cosine", // 'Cosine' | 'Euclidean' | 'DotProduct' | 'Manhattan'
|
|
1500
|
-
});
|
|
1501
|
-
await graph.initialize();
|
|
1502
|
-
|
|
1503
|
-
// Create nodes and edges
|
|
1504
|
-
await graph.storeEpisode(episode, embedding);
|
|
1505
|
-
await graph.storeSkill(skill, embedding);
|
|
1506
|
-
await graph.createCausalEdge(edge, embedding);
|
|
1507
|
-
|
|
1508
|
-
// Cypher queries
|
|
1509
|
-
const results = await graph.query(`
|
|
1510
|
-
MATCH (e:Episode)-[:CAUSED]->(s:Skill)
|
|
1511
|
-
WHERE e.reward > 0.8
|
|
1512
|
-
RETURN e, s
|
|
1513
|
-
ORDER BY e.reward DESC
|
|
1514
|
-
LIMIT 10
|
|
1515
|
-
`);
|
|
1516
|
-
```
|
|
1517
|
-
|
|
1518
|
-
### Graph Traversal
|
|
1519
|
-
|
|
1520
|
-
Traverse relationships with direction control, depth limits, and label filtering:
|
|
1521
|
-
|
|
1522
|
-
```typescript
|
|
1523
|
-
const paths = await graph.traverse({
|
|
1524
|
-
startNodeId: "episode-42",
|
|
1525
|
-
pattern: "()-[:RELATES_TO]->(:Skill)",
|
|
1526
|
-
direction: "outgoing", // 'outgoing' | 'incoming' | 'both'
|
|
1527
|
-
maxDepth: 3,
|
|
1528
|
-
relationshipTypes: ["CAUSED", "RELATES_TO"],
|
|
1529
|
-
nodeLabels: ["Episode", "Skill"],
|
|
1530
|
-
});
|
|
1531
|
-
```
|
|
1532
|
-
|
|
1533
|
-
### Hybrid Vector + Graph Search
|
|
1534
|
-
|
|
1535
|
-
Combine vector similarity with graph context filtering β find semantically similar nodes that are also connected in the knowledge graph:
|
|
1536
|
-
|
|
1537
|
-
```typescript
|
|
1538
|
-
// Vector similarity within graph structure
|
|
1539
|
-
const results = await graph.vectorSearch(queryEmbedding, 10);
|
|
1540
|
-
// Returns nodes ranked by embedding similarity with graph context
|
|
1541
|
-
|
|
1542
|
-
// Nodes support multi-label classification
|
|
1543
|
-
await graph.createNode({
|
|
1544
|
-
id: "analysis-1",
|
|
1545
|
-
label: ["Episode", "Analyzed", "Security"],
|
|
1546
|
-
properties: { reward: 0.95, task: "auth review" },
|
|
1547
|
-
embedding: embeddingVector,
|
|
1548
|
-
});
|
|
1549
|
-
```
|
|
1550
|
-
|
|
1551
|
-
### Transactional Batch Inserts
|
|
1552
|
-
|
|
1553
|
-
ACID-guaranteed batch operations with rollback support:
|
|
1554
|
-
|
|
1555
|
-
```typescript
|
|
1556
|
-
const txId = await graph.beginTransaction();
|
|
1557
|
-
try {
|
|
1558
|
-
await graph.batchInsert(
|
|
1559
|
-
nodes.map((n) => ({ id: n.id, label: n.type, properties: n.data })),
|
|
1560
|
-
edges.map((e) => ({
|
|
1561
|
-
from: e.source,
|
|
1562
|
-
to: e.target,
|
|
1563
|
-
label: e.type,
|
|
1564
|
-
properties: e.data,
|
|
1565
|
-
})),
|
|
1566
|
-
);
|
|
1567
|
-
await graph.commitTransaction(txId);
|
|
1568
|
-
} catch (err) {
|
|
1569
|
-
await graph.rollbackTransaction(txId);
|
|
1570
|
-
}
|
|
1571
|
-
```
|
|
1572
|
-
|
|
1573
|
-
### GNN 8-Head Attention
|
|
1574
|
-
|
|
1575
|
-
The GNN attention mechanism improves recall by +12.4% with a 3.8ms forward pass and 91% transfer learning retention. Three attention types are available:
|
|
1576
|
-
|
|
1577
|
-
| Type | Algorithm | Best For |
|
|
1578
|
-
| ------ | --------------------------- | ---------------------------------- |
|
|
1579
|
-
| `gat` | Graph Attention Network | Weighted neighbor aggregation |
|
|
1580
|
-
| `gcn` | Graph Convolutional Network | Uniform message passing |
|
|
1581
|
-
| `sage` | GraphSAGE | Inductive learning on unseen nodes |
|
|
1582
|
-
|
|
1583
|
-
```typescript
|
|
1584
|
-
import { AttentionService } from "agentdb/controllers/AttentionService";
|
|
1585
|
-
|
|
1586
|
-
const attention = new AttentionService({
|
|
1587
|
-
numHeads: 8,
|
|
1588
|
-
dimension: 384,
|
|
1589
|
-
attentionType: "gat", // 'gat' | 'gcn' | 'sage'
|
|
1590
|
-
});
|
|
1591
|
-
const enhanced = await attention.forward(queryEmbedding, neighborEmbeddings);
|
|
1592
|
-
```
|
|
1593
|
-
|
|
1594
|
-
### Causal Memory Graph
|
|
1595
|
-
|
|
1596
|
-
Track interventions with `p(y|do(x))` doubly robust estimation and optional Poincare embeddings for hierarchical relationships:
|
|
1597
|
-
|
|
1598
|
-
```typescript
|
|
1599
|
-
import { CausalMemoryGraph } from "agentdb";
|
|
1600
|
-
|
|
1601
|
-
const causal = new CausalMemoryGraph(db, graph, embedder, {
|
|
1602
|
-
ENABLE_HYPERBOLIC_ATTENTION: true, // PoincarΓ© ball distance for hierarchies
|
|
1603
|
-
});
|
|
1604
|
-
|
|
1605
|
-
await causal.addCausalEdge({
|
|
1606
|
-
fromMemoryId: "episode-1",
|
|
1607
|
-
toMemoryType: "skill", // 'episode' | 'skill' | 'note' | 'fact'
|
|
1608
|
-
uplift: 0.15, // E[y|do(x)] - E[y]
|
|
1609
|
-
confidence: 0.92,
|
|
1610
|
-
mechanism: "error-handling improvement",
|
|
1611
|
-
sampleSize: 50,
|
|
1612
|
-
confounderScore: 0.03,
|
|
1613
|
-
});
|
|
1614
|
-
```
|
|
1615
|
-
|
|
1616
|
-
</details>
|
|
1617
|
-
|
|
1618
|
-
---
|
|
1619
|
-
|
|
1620
|
-
<details>
|
|
1621
|
-
<summary><strong>Browser & WASM Deployment</strong> β full vector DB in the browser, no server needed</summary>
|
|
1622
|
-
|
|
1623
|
-
AgentDB runs fully in the browser with WASM-backed vector storage, GNN attention, product quantization, and pure-JS fallbacks.
|
|
1624
|
-
|
|
1625
|
-
### WasmStoreBridge
|
|
1626
|
-
|
|
1627
|
-
The `WasmStoreBridge` provides a full HNSW vector database in the browser by wrapping `@ruvector/rvf-wasm`:
|
|
1628
|
-
|
|
1629
|
-
```typescript
|
|
1630
|
-
import { WasmStoreBridge } from "agentdb/backends/rvf/WasmStoreBridge";
|
|
1631
|
-
|
|
1632
|
-
const bridge = new WasmStoreBridge();
|
|
1633
|
-
await bridge.initialize();
|
|
1634
|
-
|
|
1635
|
-
// Create an in-browser vector store
|
|
1636
|
-
const handle = bridge.wasmStoreCreate(384, 0); // 384 dims, cosine metric
|
|
1637
|
-
|
|
1638
|
-
// Ingest vectors
|
|
1639
|
-
bridge.wasmStoreIngest(handle, vectors, ids, count);
|
|
1640
|
-
|
|
1641
|
-
// Query
|
|
1642
|
-
const results = bridge.wasmStoreQuery(handle, queryVector, 10, 0);
|
|
1643
|
-
// [{ id: 42, distance: 0.12 }, ...]
|
|
1644
|
-
|
|
1645
|
-
// Export to transferable binary (share between tabs/workers)
|
|
1646
|
-
const bytes = bridge.wasmStoreExport(handle);
|
|
1647
|
-
|
|
1648
|
-
bridge.wasmStoreClose(handle);
|
|
1649
|
-
```
|
|
1650
|
-
|
|
1651
|
-
### Browser Attention Mechanisms
|
|
1652
|
-
|
|
1653
|
-
The `AttentionBrowser` provides three advanced attention types compiled to WASM:
|
|
1654
|
-
|
|
1655
|
-
```typescript
|
|
1656
|
-
import { AttentionBrowser } from "agentdb/browser/AttentionBrowser";
|
|
1657
|
-
|
|
1658
|
-
const attention = new AttentionBrowser({ numHeads: 8 });
|
|
1659
|
-
// Loading states: 'idle' β 'loading' β 'loaded' | 'error'
|
|
1660
|
-
|
|
1661
|
-
// Standard multi-head attention
|
|
1662
|
-
const enhanced = await attention.forward(query, neighbors);
|
|
1663
|
-
|
|
1664
|
-
// Flash Attention β O(N) memory instead of O(NΒ²)
|
|
1665
|
-
const flash = await attention.flashAttention(query, keys, values);
|
|
1666
|
-
|
|
1667
|
-
// Hyperbolic Attention β PoincarΓ© ball distance for hierarchical data
|
|
1668
|
-
const hyper = await attention.hyperbolicAttention(query, neighbors);
|
|
1669
|
-
|
|
1670
|
-
// Memory Consolidation β agglomerative clustering to merge similar memories
|
|
1671
|
-
const consolidated = await attention.consolidateMemories(memories, {
|
|
1672
|
-
threshold: 0.85,
|
|
1673
|
-
minClusterSize: 3,
|
|
1674
|
-
});
|
|
1675
|
-
```
|
|
1676
|
-
|
|
1677
|
-
### Product Quantization (Browser)
|
|
1678
|
-
|
|
1679
|
-
Memory-efficient vector storage with three PQ compression levels:
|
|
1680
|
-
|
|
1681
|
-
| Variant | Compression | Subvectors | Centroids | Best For |
|
|
1682
|
-
| -------- | ----------- | ---------- | --------- | ----------------------- |
|
|
1683
|
-
| **PQ8** | 4x | 8 | 256 | Balanced quality/memory |
|
|
1684
|
-
| **PQ16** | 8x | 16 | 256 | Medium datasets |
|
|
1685
|
-
| **PQ32** | 16x | 32 | 256 | Maximum compression |
|
|
1686
|
-
|
|
1687
|
-
```typescript
|
|
1688
|
-
import {
|
|
1689
|
-
createProductQuantizedStore,
|
|
1690
|
-
createScalar8BitStore,
|
|
1691
|
-
} from "agentdb/browser/ProductQuantization";
|
|
1692
|
-
|
|
1693
|
-
// Product quantization with asymmetric distance computation (ADC)
|
|
1694
|
-
const pq = createProductQuantizedStore(384, {
|
|
1695
|
-
numSubvectors: 16,
|
|
1696
|
-
bitsPerCode: 8,
|
|
1697
|
-
// Uses K-means++ initialization for codebook training
|
|
1698
|
-
});
|
|
1699
|
-
pq.add("doc-1", embedding);
|
|
1700
|
-
const results = pq.search(query, 10);
|
|
1701
|
-
```
|
|
1702
|
-
|
|
1703
|
-
### Browser Configuration Presets
|
|
1704
|
-
|
|
1705
|
-
Pre-tuned configurations for common scenarios:
|
|
1706
|
-
|
|
1707
|
-
| Preset | Features | Target |
|
|
1708
|
-
| ------------------- | ----------------------------------- | ------------------ |
|
|
1709
|
-
| `SMALL_DATASET` | GNN only | <1K vectors |
|
|
1710
|
-
| `MEDIUM_DATASET` | HNSW + PQ8 | 1K-10K vectors |
|
|
1711
|
-
| `LARGE_DATASET` | Aggressive compression + HNSW | 10K-100K vectors |
|
|
1712
|
-
| `MEMORY_OPTIMIZED` | PQ32 + SVD (dim 64) | Memory-constrained |
|
|
1713
|
-
| `SPEED_OPTIMIZED` | HNSW max quality | Latency-critical |
|
|
1714
|
-
| `QUALITY_OPTIMIZED` | No compression, max attention heads | Accuracy-critical |
|
|
1715
|
-
|
|
1716
|
-
### Maximal Marginal Relevance (MMR)
|
|
1717
|
-
|
|
1718
|
-
Diversify search results to avoid returning near-duplicate items:
|
|
1719
|
-
|
|
1720
|
-
```typescript
|
|
1721
|
-
import { MMRDiversityRanker } from "agentdb/controllers/MMRDiversityRanker";
|
|
1722
|
-
|
|
1723
|
-
const ranker = new MMRDiversityRanker({
|
|
1724
|
-
lambda: 0.7, // 0=max diversity, 1=max relevance
|
|
1725
|
-
metric: "cosine", // 'cosine' | 'euclidean' | 'dot'
|
|
1726
|
-
});
|
|
1727
|
-
|
|
1728
|
-
// Rerank results: MMR = Ξ» Γ Sim(Di,Q) - (1-Ξ») Γ max Sim(Di,Dj)
|
|
1729
|
-
const diverse = ranker.rerank(queryEmbedding, candidates, 10);
|
|
1730
|
-
const score = ranker.diversityScore(diverse); // average pairwise distance
|
|
1731
|
-
```
|
|
1732
|
-
|
|
1733
|
-
### Browser Bundle
|
|
1734
|
-
|
|
1735
|
-
```typescript
|
|
1736
|
-
import { AgentDB } from "agentdb/browser";
|
|
1737
|
-
|
|
1738
|
-
const db = new AgentDB({ dimension: 384 });
|
|
1739
|
-
await db.initialize();
|
|
1740
|
-
|
|
1741
|
-
await db.insert("doc-1", embedding, { title: "Getting Started" });
|
|
1742
|
-
const results = await db.search(queryEmbedding, 5);
|
|
1743
|
-
```
|
|
1744
|
-
|
|
1745
|
-
### sql.js & SIMD Fallbacks
|
|
1746
|
-
|
|
1747
|
-
For zero-dependency environments, AgentDB falls back to `sql.js` (SQLite compiled to WASM) automatically. Non-WASM browsers get pure-JS implementations with 4-wide loop unrolling (~10-50x slower than native SIMD but fully functional):
|
|
1748
|
-
|
|
1749
|
-
```typescript
|
|
1750
|
-
import { createDatabase } from "agentdb";
|
|
1751
|
-
import { detectSIMDSupport } from "agentdb/simd";
|
|
1752
|
-
|
|
1753
|
-
// In browsers, automatically uses sql.js WASM backend
|
|
1754
|
-
const db = await createDatabase(":memory:");
|
|
1755
|
-
|
|
1756
|
-
const support = detectSIMDSupport();
|
|
1757
|
-
// { wasm: true, x64: false, avx2: false, neon: false }
|
|
1758
|
-
```
|
|
1759
|
-
|
|
1760
|
-
</details>
|
|
1761
|
-
|
|
1762
|
-
---
|
|
1763
|
-
|
|
1764
|
-
<details>
|
|
1765
|
-
<summary><strong>Performance & Benchmarks</strong> β 61us latency, 96.8% recall, 32.6M ops/sec</summary>
|
|
1766
|
-
|
|
1767
|
-
### Core Operations
|
|
1768
|
-
|
|
1769
|
-
| Operation | Throughput | Latency |
|
|
1770
|
-
| ----------------- | ------------------- | --------------------------- |
|
|
1771
|
-
| Pattern search | 32.6M ops/sec | <1ms |
|
|
1772
|
-
| Pattern storage | 388K ops/sec | ~2.5us |
|
|
1773
|
-
| Episode retrieval | 957 ops/sec | ~1ms |
|
|
1774
|
-
| Skill search | 694 ops/sec | ~1.4ms |
|
|
1775
|
-
| Batch insert | 5,556-7,692 ops/sec | 3-4x faster than sequential |
|
|
1776
|
-
|
|
1777
|
-
### Scaling Behavior
|
|
1778
|
-
|
|
1779
|
-
```
|
|
1780
|
-
500 patterns: 1,475/sec, 2MB memory
|
|
1781
|
-
2,000 patterns: 3,818/sec, 0MB delta
|
|
1782
|
-
5,000 patterns: 4,536/sec, 4MB memory (super-linear)
|
|
1783
|
-
```
|
|
1784
|
-
|
|
1785
|
-
### Self-Learning Improvement
|
|
1786
|
-
|
|
1787
|
-
```
|
|
1788
|
-
Adaptive Learning (10 sessions, 50 episodes each)
|
|
1789
|
-
Initial success rate: 54%
|
|
1790
|
-
Final success rate: 90%
|
|
1791
|
-
Improvement: +36%
|
|
1792
|
-
```
|
|
1793
|
-
|
|
1794
|
-
### Latent Space Validation (31 scenarios, 98.2% reproducibility)
|
|
1795
|
-
|
|
1796
|
-
| Scenario | Result |
|
|
1797
|
-
| ------------------- | ----------------------------------------------- |
|
|
1798
|
-
| HNSW Optimization | 61us p50, 96.8% recall@10, 8.2x vs hnswlib |
|
|
1799
|
-
| GNN Attention | +12.4% recall, 3.8ms forward pass, 91% transfer |
|
|
1800
|
-
| Self-Healing | 97.9% degradation prevention, <100ms repair |
|
|
1801
|
-
| Neural Augmentation | +29.4% improvement, -32% memory, -52% hops |
|
|
1802
|
-
|
|
1803
|
-
### Adaptive Solver (Thompson Sampling)
|
|
1804
|
-
|
|
1805
|
-
The solver uses 18 context-bucketed bandits (3 range x 3 distractor x 2 noise levels) to dynamically tune search parameters:
|
|
1806
|
-
|
|
1807
|
-
```typescript
|
|
1808
|
-
const solver = await AgentDBSolver.create();
|
|
1809
|
-
|
|
1810
|
-
// Train the solver with puzzles of varying difficulty
|
|
1811
|
-
const result = solver.train({ count: 50, minDifficulty: 1, maxDifficulty: 10 });
|
|
1812
|
-
|
|
1813
|
-
// Inspect the policy β shows Thompson Sampling alpha/beta per context bucket
|
|
1814
|
-
const policy = solver.policy();
|
|
1815
|
-
console.log(policy.contextStats);
|
|
1816
|
-
// { '0_0_0': { alphaSafety: 12.5, betaSafety: 2.1, costEma: 0.03 }, ... }
|
|
1817
|
-
|
|
1818
|
-
// A/B/C acceptance testing
|
|
1819
|
-
const manifest = solver.acceptance({ holdoutSize: 100, cycles: 3 });
|
|
1820
|
-
console.log(`Passed: ${manifest.passed}, Score: ${manifest.score}`);
|
|
1821
|
-
|
|
1822
|
-
// SHAKE-256 witness chain for audit
|
|
1823
|
-
const chain = solver.witnessChain();
|
|
1824
|
-
```
|
|
1825
|
-
|
|
1826
|
-
Three-loop architecture:
|
|
1827
|
-
|
|
1828
|
-
1. **Fast loop** β constraint propagation (~0.1ms)
|
|
1829
|
-
2. **Medium loop** β PolicyKernel with Thompson Sampling (~1ms)
|
|
1830
|
-
3. **Slow loop** β KnowledgeCompiler for long-term patterns (~10ms)
|
|
1831
|
-
|
|
1832
|
-
### SolverBandit β Decision Intelligence Across Controllers (ADR-010)
|
|
1833
|
-
|
|
1834
|
-
The `SolverBandit` is a general-purpose Thompson Sampling bandit that provides explore/exploit decisions for any context-dependent selection problem. It powers adaptive decision-making in 5 AgentDB controllers:
|
|
1835
|
-
|
|
1836
|
-
| Controller | What the Bandit Decides | Context Key |
|
|
1837
|
-
| ---------------------- | -------------------------------------------------- | ------------------- |
|
|
1838
|
-
| **SkillLibrary** | Rerank retrieved skills by task type | `taskType` string |
|
|
1839
|
-
| **ReasoningBank** | Rerank matching patterns by task type | query text |
|
|
1840
|
-
| **NightlyLearner** | Prioritize experiment candidates | `'experiment'` |
|
|
1841
|
-
| **LearningSystem** | Select best RL algorithm (9 options) | task description |
|
|
1842
|
-
| **TemporalCompressor** | Choose compression tier (none/half/pq8/pq4/binary) | `hot`/`warm`/`cold` |
|
|
1843
|
-
|
|
1844
|
-
Each controller uses the bandit optionally β when no bandit is provided, behavior is unchanged from v2. When present, the bandit reranks results using Thompson-sampled Beta distributions, and controllers feed outcomes back via `recordReward()`.
|
|
1845
|
-
|
|
1846
|
-
```typescript
|
|
1847
|
-
import { SolverBandit } from "agentdb/backends/rvf/SolverBandit";
|
|
1848
|
-
|
|
1849
|
-
const bandit = new SolverBandit();
|
|
1850
|
-
|
|
1851
|
-
// Select best arm for a context
|
|
1852
|
-
const skill = bandit.selectArm("code_review", [
|
|
1853
|
-
"lint_first",
|
|
1854
|
-
"test_first",
|
|
1855
|
-
"security_scan",
|
|
1856
|
-
]);
|
|
1857
|
-
|
|
1858
|
-
// Record outcome
|
|
1859
|
-
bandit.recordReward("code_review", skill, 0.85, /* latencyMs */ 120);
|
|
1860
|
-
|
|
1861
|
-
// Rerank candidates by learned performance
|
|
1862
|
-
const ranked = bandit.rerank("code_review", [
|
|
1863
|
-
"lint_first",
|
|
1864
|
-
"test_first",
|
|
1865
|
-
"security_scan",
|
|
1866
|
-
]);
|
|
1867
|
-
|
|
1868
|
-
// Serialize for cross-session persistence
|
|
1869
|
-
const state = bandit.serialize(); // JSON-safe
|
|
1870
|
-
const restored = SolverBandit.deserialize(state);
|
|
1871
|
-
```
|
|
1872
|
-
|
|
1873
|
-
**Performance:** 100K `selectArm` calls in <200ms, 100K `recordReward` calls in <100ms.
|
|
1874
|
-
|
|
1875
|
-
**Wire into AgentDB controllers:**
|
|
1876
|
-
|
|
1877
|
-
```typescript
|
|
1878
|
-
import {
|
|
1879
|
-
SolverBandit,
|
|
1880
|
-
SkillLibrary,
|
|
1881
|
-
ReasoningBank,
|
|
1882
|
-
LearningSystem,
|
|
1883
|
-
} from "agentdb";
|
|
1884
|
-
|
|
1885
|
-
const bandit = new SolverBandit({ costWeight: 0.01, explorationBonus: 0.1 });
|
|
1886
|
-
|
|
1887
|
-
// Pass as optional last parameter to any controller
|
|
1888
|
-
const skills = new SkillLibrary(db, embedder, undefined, bandit);
|
|
1889
|
-
const patterns = new ReasoningBank(db, embedder, undefined, bandit);
|
|
1890
|
-
const learning = new LearningSystem(db, undefined, bandit);
|
|
1891
|
-
|
|
1892
|
-
// Controllers automatically rerank results and accept feedback
|
|
1893
|
-
const algorithm = learning.recommendAlgorithm("navigation task");
|
|
1894
|
-
learning.recordAlgorithmOutcome("navigation task", algorithm, 0.92, 340);
|
|
1895
|
-
```
|
|
1896
|
-
|
|
1897
|
-
</details>
|
|
1898
|
-
|
|
1899
|
-
---
|
|
1900
|
-
|
|
1901
|
-
### Enterprise & Security
|
|
1902
|
-
|
|
1903
|
-
Production-ready authentication, audit logging, and defense-in-depth security with cryptographic verification.
|
|
1904
|
-
|
|
1905
|
-
<details>
|
|
1906
|
-
<summary><strong>Security</strong> β defense-in-depth with cryptographic audit trails</summary>
|
|
1907
|
-
|
|
1908
|
-
AgentDB provides defense-in-depth security with validation at every system boundary.
|
|
1909
|
-
|
|
1910
|
-
### Input Validation
|
|
1911
|
-
|
|
1912
|
-
```typescript
|
|
1913
|
-
import {
|
|
1914
|
-
validateVector,
|
|
1915
|
-
validateVectorId,
|
|
1916
|
-
validateSearchOptions,
|
|
1917
|
-
validateHNSWParams,
|
|
1918
|
-
sanitizeMetadata,
|
|
1919
|
-
validateCypherParams,
|
|
1920
|
-
validateLabel,
|
|
1921
|
-
validateBatchSize,
|
|
1922
|
-
} from "agentdb/security/validation";
|
|
1923
|
-
|
|
1924
|
-
// Vector validation β prevents NaN/Infinity injection
|
|
1925
|
-
validateVector(embedding, 384, "embedding");
|
|
1926
|
-
|
|
1927
|
-
// ID validation β prevents path traversal (../, etc.)
|
|
1928
|
-
validateVectorId("doc-123", "id");
|
|
1929
|
-
|
|
1930
|
-
// Search bounds β k, threshold, efSearch range checking
|
|
1931
|
-
validateSearchOptions({ k: 10, threshold: 0.7 });
|
|
1932
|
-
|
|
1933
|
-
// HNSW parameter validation β M, efConstruction, efSearch
|
|
1934
|
-
validateHNSWParams({ M: 16, efConstruction: 200, efSearch: 100 });
|
|
1935
|
-
|
|
1936
|
-
// Metadata sanitization β strips password, token, key, apiKey, auth fields
|
|
1937
|
-
const safe = sanitizeMetadata(userInput);
|
|
1938
|
-
|
|
1939
|
-
// Cypher injection prevention
|
|
1940
|
-
validateCypherParams(params);
|
|
1941
|
-
```
|
|
1942
|
-
|
|
1943
|
-
### XSS & Injection Prevention
|
|
1944
|
-
|
|
1945
|
-
```typescript
|
|
1946
|
-
import {
|
|
1947
|
-
validateTaskString,
|
|
1948
|
-
validateNumericRange,
|
|
1949
|
-
validateEnum,
|
|
1950
|
-
} from "agentdb/security/input-validation";
|
|
1951
|
-
|
|
1952
|
-
const task = validateTaskString(input, "task"); // XSS pattern detection
|
|
1953
|
-
const k = validateNumericRange(kVal, "k", 1, 100);
|
|
1954
|
-
const format = validateEnum(fmt, "format", ["json", "concise", "detailed"]);
|
|
1955
|
-
```
|
|
1956
|
-
|
|
1957
|
-
### Security Limits
|
|
1958
|
-
|
|
1959
|
-
| Parameter | Limit |
|
|
1960
|
-
| ----------------------- | ---------- |
|
|
1961
|
-
| Max vectors | 10,000,000 |
|
|
1962
|
-
| Max dimension | 4,096 |
|
|
1963
|
-
| Max batch size | 10,000 |
|
|
1964
|
-
| Max k | 10,000 |
|
|
1965
|
-
| Max metadata size | 64 KB |
|
|
1966
|
-
| Max ID length | 256 chars |
|
|
1967
|
-
| Filter expression depth | 64 |
|
|
1968
|
-
| ef-search range | 1 - 1,000 |
|
|
1969
|
-
| ef-construction range | 4 - 500 |
|
|
1970
|
-
| M range | 2 - 64 |
|
|
1971
|
-
|
|
1972
|
-
### Witness Chain Verification
|
|
1973
|
-
|
|
1974
|
-
SHAKE-256 cryptographic witness chains provide tamper-evident audit trails:
|
|
1975
|
-
|
|
1976
|
-
```typescript
|
|
1977
|
-
const result = backend.verifyWitnessChain();
|
|
1978
|
-
if (!result.valid) {
|
|
1979
|
-
console.error("Data integrity compromised!");
|
|
1980
|
-
}
|
|
1981
|
-
```
|
|
1982
|
-
|
|
1983
|
-
### Provenance Certificates (Explainable Recall)
|
|
1984
|
-
|
|
1985
|
-
Every search result can include a Merkle proof explaining why it was selected:
|
|
1986
|
-
|
|
1987
|
-
```typescript
|
|
1988
|
-
const { results, certificate } = await causalRecall.recall(
|
|
1989
|
-
"query-id",
|
|
1990
|
-
"optimization strategies",
|
|
1991
|
-
10,
|
|
1992
|
-
["performance"],
|
|
1993
|
-
"internal",
|
|
1994
|
-
);
|
|
1995
|
-
console.log(`Certificate ID: ${certificate.id}`);
|
|
1996
|
-
console.log(`Completeness: ${certificate.completenessScore}`);
|
|
1997
|
-
```
|
|
1998
|
-
|
|
1999
|
-
</details>
|
|
2000
|
-
|
|
2001
|
-
---
|
|
2002
|
-
|
|
2003
|
-
<details>
|
|
2004
|
-
<summary><strong>Quantization & Compression</strong> β up to 32x memory reduction with 5-tier auto-tiering</summary>
|
|
2005
|
-
|
|
2006
|
-
AgentDB supports multiple quantization strategies to reduce memory footprint while maintaining search quality.
|
|
2007
|
-
|
|
2008
|
-
### Scalar Quantization
|
|
13
|
+
# AgentDB
|
|
2009
14
|
|
|
2010
|
-
|
|
15
|
+
**Vector memory that gets smarter every time your agent uses it.**
|
|
2011
16
|
|
|
2012
|
-
|
|
2013
|
-
import {
|
|
2014
|
-
createScalar8BitStore,
|
|
2015
|
-
createProductQuantizedStore,
|
|
2016
|
-
} from "agentdb/browser/ProductQuantization";
|
|
2017
|
-
|
|
2018
|
-
// 8-bit quantization β 4x memory reduction
|
|
2019
|
-
const store8 = createScalar8BitStore(384);
|
|
2020
|
-
store8.add("doc-1", embedding);
|
|
2021
|
-
const results = store8.search(query, 10);
|
|
2022
|
-
|
|
2023
|
-
// Product quantization β up to 32x memory reduction
|
|
2024
|
-
const storePQ = createProductQuantizedStore(384, {
|
|
2025
|
-
numSubvectors: 48,
|
|
2026
|
-
bitsPerCode: 8,
|
|
2027
|
-
});
|
|
2028
|
-
storePQ.add("doc-1", embedding);
|
|
2029
|
-
const results = storePQ.search(query, 10);
|
|
2030
|
-
```
|
|
17
|
+
</div>
|
|
2031
18
|
|
|
2032
|
-
|
|
19
|
+
A single-file cognitive container β vectors, indexes, learning state, and a cryptographic audit trail in one `.rvf`. Self-learning search improves up to **36% from feedback alone**, with no manual tuning. Runs in Node, the browser, edge runtimes, and offline.
|
|
2033
20
|
|
|
2034
|
-
|
|
21
|
+
### Why AgentDB?
|
|
2035
22
|
|
|
2036
|
-
|
|
2037
|
-
| ----------- | -------------- | ------ | ------- | ---------------------------- |
|
|
2038
|
-
| **Hot** | None | 100% | 100% | Recent / frequently accessed |
|
|
2039
|
-
| **Warm** | Half-precision | 50% | ~99% | Moderate age |
|
|
2040
|
-
| **Cool** | PQ-8 | ~12% | ~95% | Older data |
|
|
2041
|
-
| **Cold** | PQ-4 | ~6% | ~90% | Rarely accessed |
|
|
2042
|
-
| **Archive** | Binary | ~3% | ~80% | Archival storage |
|
|
23
|
+
> Most vector databases store embeddings and call it done. AgentDB watches *which* results your agent actually used, learns from that signal, and ranks the next query better. The bandit underneath also picks the right RL algorithm, the right compression tier, and the right pattern weighting on its own β so the database itself gets sharper while you focus on the agent.
|
|
2043
24
|
|
|
2044
|
-
|
|
25
|
+
> The name: a database that thinks like an agent β episodic memory, skill library, causal reasoning, and a learning loop, all in one file. Built by [`rUv`](https://ruv.io) on the [`ruvector`](https://github.com/ruvnet/ruvector) Rust engine.
|
|
2045
26
|
|
|
2046
|
-
|
|
27
|
+
### What AgentDB Does
|
|
2047
28
|
|
|
2048
|
-
```typescript
|
|
2049
|
-
// Models trained with Matryoshka loss support dimension truncation
|
|
2050
|
-
// 384d -> 128d with minimal quality loss
|
|
2051
|
-
const truncated = embedding.slice(0, 128);
|
|
2052
29
|
```
|
|
30
|
+
Self-Learning Vector Memory
|
|
2053
31
|
|
|
2054
|
-
|
|
2055
|
-
|
|
2056
|
-
|
|
2057
|
-
|
|
2058
|
-
|
|
2059
|
-
|
|
2060
|
-
|
|
2061
|
-
|
|
2062
|
-
// Load scalar quantization parameters
|
|
2063
|
-
accel.loadSqParams(mins, scales);
|
|
2064
|
-
const restored = accel.dequantI8(quantizedBytes);
|
|
2065
|
-
|
|
2066
|
-
// Product quantization with codebook
|
|
2067
|
-
accel.loadPqCodebook(codebook, numSubvectors, bitsPerCode);
|
|
2068
|
-
const distances = accel.pqDistances(query, codes);
|
|
32
|
+
Agent βββΊ AgentDB (.rvf) βββΊ HNSW search βββΊ top-k results
|
|
33
|
+
β β
|
|
34
|
+
βΌ βΌ
|
|
35
|
+
recordFeedback(id, reward) βββ agent uses some, ignores rest
|
|
36
|
+
β
|
|
37
|
+
βΌ
|
|
38
|
+
Bandit re-tunes ranking / RL choice / compression βββΊ next query is smarter
|
|
2069
39
|
```
|
|
2070
40
|
|
|
2071
|
-
|
|
41
|
+
> **3 lines to self-learning search:**
|
|
42
|
+
> ```typescript
|
|
43
|
+
> const backend = await SelfLearningRvfBackend.create({ learning: true, storagePath: "./my.rvf" });
|
|
44
|
+
> const results = await backend.searchAsync(query, 10); // search
|
|
45
|
+
> backend.recordFeedback(results[0].id, 0.9); // learn β next search is smarter
|
|
46
|
+
> ```
|
|
2072
47
|
|
|
2073
48
|
---
|
|
2074
49
|
|
|
2075
|
-
|
|
2076
|
-
|
|
2077
|
-
Connect AgentDB to LLM providers, embedding models, and distributed systems with real-time sync.
|
|
2078
|
-
|
|
2079
|
-
<details>
|
|
2080
|
-
<summary><strong>Model Import/Export & Embedding Models</strong> β 5 local models, no API keys</summary>
|
|
2081
|
-
|
|
2082
|
-
### Embedding Models
|
|
2083
|
-
|
|
2084
|
-
AgentDB supports multiple embedding models. No API key required β all Xenova models run locally.
|
|
2085
|
-
|
|
2086
|
-
| Model | Dimension | Quality | Speed | Best For |
|
|
2087
|
-
| ------------------------------ | --------- | --------- | -------- | ----------------- |
|
|
2088
|
-
| **all-MiniLM-L6-v2** (default) | 384 | Good | Fastest | Prototyping |
|
|
2089
|
-
| **bge-small-en-v1.5** | 384 | Excellent | Fast | Best 384d quality |
|
|
2090
|
-
| **bge-base-en-v1.5** | 768 | Excellent | Moderate | Production |
|
|
2091
|
-
| **all-mpnet-base-v2** | 768 | Excellent | Moderate | All-around |
|
|
2092
|
-
| **e5-base-v2** | 768 | Excellent | Moderate | Multilingual |
|
|
2093
|
-
|
|
2094
|
-
```bash
|
|
2095
|
-
# Default (384d, fast)
|
|
2096
|
-
npx agentdb init
|
|
2097
|
-
|
|
2098
|
-
# Production (768d, high quality)
|
|
2099
|
-
npx agentdb init --dimension 768 --model "Xenova/bge-base-en-v1.5"
|
|
2100
|
-
```
|
|
2101
|
-
|
|
2102
|
-
### Offline Embeddings (Bundled Model)
|
|
50
|
+
## Quick Start
|
|
2103
51
|
|
|
2104
|
-
|
|
52
|
+
There are **three ways to use AgentDB** depending on what you're building. Pick whichever matches your stack:
|
|
2105
53
|
|
|
2106
|
-
**
|
|
54
|
+
| | **npm library** | **CLI** | **MCP server** |
|
|
55
|
+
|---|---|---|---|
|
|
56
|
+
| **What you get** | TypeScript / JS API for any Node app | `agentdb` binary, scriptable from any shell | 41 tools callable from Claude Code, Cursor, Cline, etc. |
|
|
57
|
+
| **Install** | `npm i agentdb` | `npx agentdb β¦` (no install) | `claude mcp add agentdb -- npx agentdb mcp start` |
|
|
58
|
+
| **Best for** | Embedding the engine in your own code | Quick experiments, CI scripts, ad-hoc memory | Plugging memory + learning into an LLM agent |
|
|
2107
59
|
|
|
2108
|
-
|
|
2109
|
-
2. Bundled `.rvf` at `dist/models/all-MiniLM-L6-v2.rvf`
|
|
2110
|
-
3. Existing `@xenova/transformers` cache
|
|
2111
|
-
4. Network download (fallback)
|
|
60
|
+
### Path A β npm library
|
|
2112
61
|
|
|
2113
62
|
```bash
|
|
2114
|
-
|
|
2115
|
-
npm run build:model
|
|
2116
|
-
|
|
2117
|
-
# Or specify a custom source directory
|
|
2118
|
-
node scripts/build-model-rvf.mjs --source /path/to/model/files
|
|
63
|
+
npm install agentdb
|
|
2119
64
|
```
|
|
2120
65
|
|
|
2121
66
|
```typescript
|
|
2122
|
-
|
|
2123
|
-
import { ModelCacheLoader } from "agentdb/model";
|
|
2124
|
-
|
|
2125
|
-
const cached = await ModelCacheLoader.resolve("all-MiniLM-L6-v2");
|
|
2126
|
-
if (cached) {
|
|
2127
|
-
console.log(cached.localPath); // path to extracted model
|
|
2128
|
-
console.log(cached.fromBundle); // true if loaded from .rvf
|
|
2129
|
-
}
|
|
2130
|
-
```
|
|
2131
|
-
|
|
2132
|
-
Set `AGENTDB_MODEL_PATH` to point to a custom model directory:
|
|
2133
|
-
|
|
2134
|
-
```bash
|
|
2135
|
-
export AGENTDB_MODEL_PATH=/opt/models
|
|
2136
|
-
# expects: /opt/models/Xenova/all-MiniLM-L6-v2/onnx/model_quantized.onnx
|
|
2137
|
-
```
|
|
67
|
+
import { SelfLearningRvfBackend } from 'agentdb';
|
|
2138
68
|
|
|
2139
|
-
|
|
2140
|
-
|
|
2141
|
-
|
|
2142
|
-
|
|
2143
|
-
```typescript
|
|
2144
|
-
import { isRuvLLMInstalled } from "agentdb/wrappers";
|
|
69
|
+
const db = await SelfLearningRvfBackend.create({
|
|
70
|
+
learning: true,
|
|
71
|
+
storagePath: './memory.rvf',
|
|
72
|
+
});
|
|
2145
73
|
|
|
2146
|
-
|
|
2147
|
-
|
|
2148
|
-
|
|
74
|
+
await db.insertAsync('doc1', new Float32Array(384), { text: 'Hello world' });
|
|
75
|
+
const hits = await db.searchAsync(queryEmbedding, 5);
|
|
76
|
+
db.recordFeedback(hits[0].id, 1.0); // it was useful β db gets smarter
|
|
2149
77
|
```
|
|
2150
78
|
|
|
2151
|
-
###
|
|
2152
|
-
|
|
2153
|
-
Export vector stores to the portable Cognitive Container format:
|
|
79
|
+
### Path B β CLI in 10 seconds
|
|
2154
80
|
|
|
2155
81
|
```bash
|
|
2156
|
-
#
|
|
2157
|
-
npx agentdb
|
|
2158
|
-
|
|
2159
|
-
|
|
2160
|
-
npx agentdb migrate --to rvf --rvf-path ./vectors.rvf
|
|
2161
|
-
|
|
2162
|
-
# Import from Cognitive Container into a new backend
|
|
2163
|
-
npx agentdb migrate --from rvf --rvf-path ./vectors.rvf --target ./new.db
|
|
82
|
+
# Try it without installing
|
|
83
|
+
npx agentdb init my-memory.rvf
|
|
84
|
+
npx agentdb add my-memory.rvf "vector memory that learns"
|
|
85
|
+
npx agentdb search my-memory.rvf "self-improving search" --top-k 5
|
|
2164
86
|
```
|
|
2165
87
|
|
|
2166
|
-
###
|
|
2167
|
-
|
|
2168
|
-
Export a WASM store to a transferable binary for sharing between browser tabs or workers:
|
|
2169
|
-
|
|
2170
|
-
```typescript
|
|
2171
|
-
const bytes = bridge.wasmStoreExport(handle); // Uint8Array
|
|
2172
|
-
// Transfer to another worker or save to IndexedDB
|
|
2173
|
-
```
|
|
2174
|
-
|
|
2175
|
-
</details>
|
|
2176
|
-
|
|
2177
|
-
---
|
|
88
|
+
### Path C β MCP server (Claude Code, Cursor, etc.)
|
|
2178
89
|
|
|
2179
|
-
|
|
2180
|
-
|
|
2181
|
-
|
|
2182
|
-
The full lifecycle of a query through AgentDB's self-learning pipeline:
|
|
2183
|
-
|
|
2184
|
-
```mermaid
|
|
2185
|
-
sequenceDiagram
|
|
2186
|
-
participant App
|
|
2187
|
-
participant Router as Semantic Router
|
|
2188
|
-
participant SONA
|
|
2189
|
-
participant HNSW as HNSW Index
|
|
2190
|
-
participant Trainer as Contrastive Trainer
|
|
2191
|
-
|
|
2192
|
-
App->>Router: query(embedding)
|
|
2193
|
-
Router->>Router: classify intent
|
|
2194
|
-
Router->>SONA: enhance(embedding, trajectories)
|
|
2195
|
-
SONA->>SONA: apply micro-LoRA
|
|
2196
|
-
SONA->>HNSW: searchAsync(enhanced, k, ef)
|
|
2197
|
-
HNSW-->>App: results[]
|
|
2198
|
-
App->>Trainer: recordFeedback(quality)
|
|
2199
|
-
Trainer->>Trainer: InfoNCE + hard negatives
|
|
2200
|
-
Trainer->>SONA: updateLoRA(gradients)
|
|
2201
|
-
Note over SONA: EWC++ consolidation<br/>prevents forgetting
|
|
90
|
+
```bash
|
|
91
|
+
claude mcp add agentdb -- npx agentdb@latest mcp start
|
|
2202
92
|
```
|
|
2203
93
|
|
|
2204
|
-
|
|
2205
|
-
|
|
2206
|
-
1. **Routing** β `SemanticQueryRouter` classifies query intent via HNSW-indexed embeddings and selects the optimal search strategy
|
|
2207
|
-
2. **Enhancement** β SONA engine enriches the query embedding using trajectory history and context
|
|
2208
|
-
3. **LoRA Application** β Micro-LoRA adapter adjusts the embedding in sub-millisecond time
|
|
2209
|
-
4. **Search** β HNSW index returns top-k results with adaptive ef-search
|
|
2210
|
-
5. **Feedback** β Application records result quality (0.0-1.0)
|
|
2211
|
-
6. **Training** β Contrastive trainer runs InfoNCE loss with hard negative mining
|
|
2212
|
-
7. **Update** β LoRA gradients update the adapter weights
|
|
2213
|
-
8. **Consolidation** β EWC++ prevents catastrophic forgetting of previously learned patterns
|
|
2214
|
-
|
|
2215
|
-
</details>
|
|
94
|
+
That registers 41 MCP tools β `agentdb_pattern_store`, `agentdb_pattern_search`, `agentdb_hierarchical_store`, `agentdb_causal_edge`, `agentdb_skill_library`, `agentdb_reflexion`, etc. They call the same engine the npm library does, just over Claude's tool-calling surface.
|
|
2216
95
|
|
|
2217
96
|
---
|
|
2218
97
|
|
|
2219
|
-
|
|
2220
|
-
|
|
2221
|
-
Multi-database coordination, real-time replication, and production observability.
|
|
2222
|
-
|
|
2223
|
-
<details>
|
|
2224
|
-
<summary><strong>Multi-Database Coordination</strong> β distributed sync with conflict resolution</summary>
|
|
2225
|
-
|
|
2226
|
-
The `MultiDatabaseCoordinator` enables distributed sync between multiple AgentDB instances with configurable conflict resolution.
|
|
2227
|
-
|
|
2228
|
-
```typescript
|
|
2229
|
-
import { MultiDatabaseCoordinator } from "agentdb/coordination/MultiDatabaseCoordinator";
|
|
2230
|
-
|
|
2231
|
-
const coordinator = new MultiDatabaseCoordinator({
|
|
2232
|
-
replicationFactor: 3,
|
|
2233
|
-
syncIntervalMs: 5000,
|
|
2234
|
-
conflictResolution: "merge", // 'last-write-wins' | 'merge' | 'manual'
|
|
2235
|
-
autoFailover: true,
|
|
2236
|
-
maxRetries: 3,
|
|
2237
|
-
});
|
|
2238
|
-
|
|
2239
|
-
// Register database instances
|
|
2240
|
-
await coordinator.registerInstance({
|
|
2241
|
-
id: "primary",
|
|
2242
|
-
url: "file:///data/primary.rvf",
|
|
2243
|
-
role: "primary",
|
|
2244
|
-
});
|
|
2245
|
-
await coordinator.registerInstance({
|
|
2246
|
-
id: "replica-1",
|
|
2247
|
-
url: "file:///data/replica-1.rvf",
|
|
2248
|
-
role: "replica",
|
|
2249
|
-
});
|
|
2250
|
-
|
|
2251
|
-
// Sync a specific instance
|
|
2252
|
-
const result = await coordinator.syncInstance("replica-1");
|
|
2253
|
-
console.log(`Synced: ${result.recordsSynced}, Conflicts: ${result.conflicts}`);
|
|
98
|
+
## What You Get
|
|
2254
99
|
|
|
2255
|
-
|
|
2256
|
-
|
|
2257
|
-
|
|
2258
|
-
|
|
2259
|
-
|
|
2260
|
-
|
|
2261
|
-
|
|
2262
|
-
|
|
2263
|
-
|
|
2264
|
-
|
|
2265
|
-
|
|
2266
|
-
|
|
2267
|
-
|
|
2268
|
-
|
|
2269
|
-
|
|
2270
|
-
| Strategy | Description | Best For |
|
|
2271
|
-
| ------------------- | ------------------------------------- | --------------------------------------- |
|
|
2272
|
-
| **last-write-wins** | Most recent write wins (LWW) | Simple setups, eventual consistency |
|
|
2273
|
-
| **merge** | Quality-based weighted average | Learning systems, federated aggregation |
|
|
2274
|
-
| **manual** | Returns conflicts for user resolution | Critical data, compliance requirements |
|
|
2275
|
-
|
|
2276
|
-
</details>
|
|
100
|
+
| Capability | Description |
|
|
101
|
+
|------------|-------------|
|
|
102
|
+
| π§ **Self-Learning Search** | Up to **+36% search quality** from feedback alone β Thompson Sampling bandit re-tunes ranking, RL choice, and compression tier with zero manual config |
|
|
103
|
+
| π **Cognitive Memory** | 6 human-inspired patterns β episodic replay (Reflexion), skill library, causal reasoning, hierarchical context, semantic clustering, working memory |
|
|
104
|
+
| π€ **9 RL Algorithms** | Q-Learning, SARSA, DQN, PPO, Actor-Critic, Policy Gradient, Decision Transformer, MCTS, Model-Based RL β bandit picks the right one per task |
|
|
105
|
+
| β‘ **150Γ faster than SQLite** | RuVector Rust engine via NAPI bindings; HNSW vector search; sub-millisecond reads on 100k+ vectors |
|
|
106
|
+
| π **Hybrid Search** | BM25 keyword + dense vector fused with Reciprocal Rank Fusion β exact terms *and* semantic intent in one query |
|
|
107
|
+
| πΈοΈ **Graph Intelligence** | Cypher queries, causal edges, GNN 8-head attention (+12.4% recall), hyperedges for n-ary relationships |
|
|
108
|
+
| πΎ **Single-file Storage** | Everything (vectors, indexes, learning state, audit log) in one `.rvf` "Cognitive Container" β no servers, no API keys, no monthly bills |
|
|
109
|
+
| π― **Quantization** | 4-32Γ memory reduction with PQ8 / PQ4 / binary quantization; minimal recall loss; runs on commodity hardware |
|
|
110
|
+
| π **41 MCP Tools** | First-class Claude Code / Cursor / Cline integration β pattern store, search, skill library, reflexion, causal edges, hierarchical recall, delete |
|
|
111
|
+
| π **Runs Anywhere** | Node, browser (WASM), edge runtimes, fully offline β same API, same `.rvf` file |
|
|
112
|
+
| π‘οΈ **Enterprise Security** | JWT auth, API key rotation, Argon2id hashing, SOC2 / GDPR audit trails, cryptographic witness chain |
|
|
113
|
+
| π **agentic-flow Integration** | Drop-in for [`agentic-flow`](https://github.com/ruvnet/agentic-flow) β backs ReasoningBank, MemoryController, NightlyLearner, and 30+ agents |
|
|
2277
114
|
|
|
2278
115
|
---
|
|
2279
116
|
|
|
2280
|
-
|
|
2281
|
-
<summary><strong>Real-Time Sync (QUIC)</strong> β bidirectional replication with 0-RTT resumption</summary>
|
|
2282
|
-
|
|
2283
|
-
AgentDB supports real-time bidirectional sync between instances using QUIC transport and a high-level `SyncCoordinator`.
|
|
2284
|
-
|
|
2285
|
-
### QUIC Transport
|
|
2286
|
-
|
|
2287
|
-
QUIC provides multiplexed streams over a single connection with zero head-of-line blocking, connection migration between networks, and 0-RTT session resumption:
|
|
2288
|
-
|
|
2289
|
-
```typescript
|
|
2290
|
-
import { QUICServer } from "agentdb/controllers/QUICServer";
|
|
2291
|
-
|
|
2292
|
-
const server = new QUICServer({
|
|
2293
|
-
port: 4433,
|
|
2294
|
-
maxConnections: 100,
|
|
2295
|
-
rateLimit: {
|
|
2296
|
-
requestsPerMin: 1000,
|
|
2297
|
-
bytesPerMin: 10_000_000,
|
|
2298
|
-
},
|
|
2299
|
-
authToken: "secret", // optional token validation
|
|
2300
|
-
});
|
|
2301
|
-
|
|
2302
|
-
// Stale connections auto-cleaned after 5 minutes idle
|
|
2303
|
-
// Sync types: 'episodes' | 'skills' | 'edges' | 'full'
|
|
2304
|
-
// Incremental sync via `since` parameter and cursor-based pagination
|
|
2305
|
-
```
|
|
2306
|
-
|
|
2307
|
-
### Sync Coordinator
|
|
2308
|
-
|
|
2309
|
-
High-level bidirectional sync with conflict resolution, progress tracking, and auto-sync:
|
|
2310
|
-
|
|
2311
|
-
```typescript
|
|
2312
|
-
import { SyncCoordinator } from "agentdb/controllers/SyncCoordinator";
|
|
117
|
+
## π§ Self-Learning Loop
|
|
2313
118
|
|
|
2314
|
-
|
|
2315
|
-
conflictStrategy: "latest-wins", // 'local-wins' | 'remote-wins' | 'latest-wins' | 'merge'
|
|
2316
|
-
batchSize: 100,
|
|
2317
|
-
autoSyncInterval: 60000, // Auto-sync every 60 seconds
|
|
2318
|
-
});
|
|
119
|
+
Most retrieval systems are read-only. AgentDB closes the loop:
|
|
2319
120
|
|
|
2320
|
-
// Push local changes, pull remote changes, resolve conflicts
|
|
2321
|
-
const report = await sync.sync();
|
|
2322
|
-
console.log(report);
|
|
2323
|
-
// {
|
|
2324
|
-
// success: true,
|
|
2325
|
-
// durationMs: 342,
|
|
2326
|
-
// itemsPushed: 15,
|
|
2327
|
-
// itemsPulled: 8,
|
|
2328
|
-
// conflictsResolved: 2,
|
|
2329
|
-
// bytesTransferred: 48200,
|
|
2330
|
-
// errors: [],
|
|
2331
|
-
// }
|
|
2332
|
-
|
|
2333
|
-
// Progress tracking through 5 phases:
|
|
2334
|
-
// detecting β pushing β pulling β resolving β applying
|
|
2335
|
-
|
|
2336
|
-
// Sync state persists across restarts
|
|
2337
|
-
await sync.saveSyncState();
|
|
2338
|
-
// Tracks: lastSyncAt, lastEpisodeSync, lastSkillSync, lastEdgeSync,
|
|
2339
|
-
// totalItemsSynced, totalBytesSynced, syncCount
|
|
2340
121
|
```
|
|
2341
|
-
|
|
2342
|
-
|
|
2343
|
-
|
|
2344
|
-
|
|
2345
|
-
|
|
2346
|
-
|
|
2347
|
-
|
|
2348
|
-
|
|
2349
|
-
|
|
2350
|
-
|
|
2351
|
-
</details>
|
|
2352
|
-
|
|
2353
|
-
---
|
|
2354
|
-
|
|
2355
|
-
<details>
|
|
2356
|
-
<summary><strong>Observability</strong> β OpenTelemetry traces and Prometheus metrics built in</summary>
|
|
2357
|
-
|
|
2358
|
-
AgentDB integrates with OpenTelemetry for production monitoring.
|
|
2359
|
-
|
|
2360
|
-
### Traces
|
|
2361
|
-
|
|
2362
|
-
Automatic span creation for search, insert, and sync operations:
|
|
2363
|
-
|
|
2364
|
-
```typescript
|
|
2365
|
-
import { initTelemetry } from "agentdb/observability";
|
|
2366
|
-
|
|
2367
|
-
initTelemetry({
|
|
2368
|
-
serviceName: "my-agent",
|
|
2369
|
-
exporterUrl: "http://localhost:4318", // OTLP HTTP endpoint
|
|
2370
|
-
});
|
|
2371
|
-
|
|
2372
|
-
// All AgentDB operations automatically generate spans:
|
|
2373
|
-
// - agentdb.search (with k, backend, latency attributes)
|
|
2374
|
-
// - agentdb.insert (with batchSize, backend)
|
|
2375
|
-
// - agentdb.sync (with itemsSynced, conflicts)
|
|
122
|
+
search βββΊ top-k βββΊ agent picks the useful ones βββΊ recordFeedback()
|
|
123
|
+
β
|
|
124
|
+
βΌ
|
|
125
|
+
Thompson Sampling bandit
|
|
126
|
+
β
|
|
127
|
+
βΌ
|
|
128
|
+
re-weights ranking Β· re-picks RL algorithm Β· re-tunes compression
|
|
129
|
+
β
|
|
130
|
+
βΌ
|
|
131
|
+
next search is sharper
|
|
2376
132
|
```
|
|
2377
133
|
|
|
2378
|
-
|
|
2379
|
-
|
|
2380
|
-
Prometheus-compatible metrics for latency, throughput, and error rates:
|
|
134
|
+
The bandit isn't a gimmick β it's used at four decision points:
|
|
2381
135
|
|
|
2382
|
-
|
|
2383
|
-
|
|
2384
|
-
|
|
2385
|
-
|
|
2386
|
-
- `agentdb_vector_count` β total vectors stored
|
|
136
|
+
1. **Pattern ranking** β which historical pattern matches this new query best?
|
|
137
|
+
2. **RL algorithm selection** β Q-Learning for tabular tasks, PPO for continuous control, MCTS for planning, etc.
|
|
138
|
+
3. **Compression tier** β full precision when accuracy matters, PQ4 when memory does.
|
|
139
|
+
4. **Skill composition** β chain skill AβBβC or skill AβDβE?
|
|
2387
140
|
|
|
2388
|
-
|
|
141
|
+
Each decision logs reward over time. Bad arms decay fast. Good arms stick.
|
|
2389
142
|
|
|
2390
143
|
---
|
|
2391
144
|
|
|
2392
|
-
|
|
2393
|
-
|
|
2394
|
-
Reinforcement learning, hybrid search, LLM routing, authentication, and high-performance wrappers.
|
|
2395
|
-
|
|
2396
|
-
<details>
|
|
2397
|
-
<summary><strong>Reinforcement Learning</strong> β 9 algorithms from Q-Learning to Monte Carlo Tree Search</summary>
|
|
2398
|
-
|
|
2399
|
-
AgentDB includes a complete reinforcement learning system with 9 algorithms for building agents that learn optimal strategies through interaction:
|
|
2400
|
-
|
|
2401
|
-
### Available Algorithms
|
|
2402
|
-
|
|
2403
|
-
| Algorithm | Type | Best For |
|
|
2404
|
-
| --------------------------- | -------------- | ------------------------------------------------------- |
|
|
2405
|
-
| **Q-Learning** | Value-based | Simple discrete action spaces |
|
|
2406
|
-
| **SARSA** | Value-based | On-policy learning, safer exploration |
|
|
2407
|
-
| **Deep Q-Network (DQN)** | Value-based | Complex state spaces with neural function approximation |
|
|
2408
|
-
| **Policy Gradient** | Policy-based | Continuous action spaces |
|
|
2409
|
-
| **Actor-Critic** | Hybrid | Balances value and policy learning |
|
|
2410
|
-
| **PPO** | Policy-based | Stable training with clipped objectives |
|
|
2411
|
-
| **Decision Transformer** | Sequence-based | Offline RL from logged trajectories |
|
|
2412
|
-
| **Monte Carlo Tree Search** | Planning | Game-like decision trees, look-ahead planning |
|
|
2413
|
-
| **Model-Based RL** | Model-based | Sample-efficient learning with world models |
|
|
2414
|
-
|
|
2415
|
-
### Usage
|
|
2416
|
-
|
|
2417
|
-
```typescript
|
|
2418
|
-
import { LearningSystem } from "agentdb";
|
|
2419
|
-
|
|
2420
|
-
const learner = new LearningSystem(db, {
|
|
2421
|
-
algorithm: "ppo", // any of the 9 algorithms
|
|
2422
|
-
learningRate: 0.001,
|
|
2423
|
-
discountFactor: 0.99,
|
|
2424
|
-
explorationRate: 0.1,
|
|
2425
|
-
});
|
|
2426
|
-
|
|
2427
|
-
// Start a learning session
|
|
2428
|
-
const session = await learner.createSession({
|
|
2429
|
-
task: "optimize_api_responses",
|
|
2430
|
-
maxEpisodes: 100,
|
|
2431
|
-
});
|
|
2432
|
-
|
|
2433
|
-
// Predict next action
|
|
2434
|
-
const prediction = await learner.predict(session.id, currentState);
|
|
2435
|
-
// { action, confidence, explorationUsed }
|
|
2436
|
-
|
|
2437
|
-
// Record outcome
|
|
2438
|
-
await learner.recordReward(session.id, prediction.action, reward);
|
|
2439
|
-
|
|
2440
|
-
// Train on accumulated experience
|
|
2441
|
-
await learner.train(session.id);
|
|
2442
|
-
|
|
2443
|
-
// Transfer learning to new tasks
|
|
2444
|
-
await learner.transfer(sourceSessionId, targetSessionId);
|
|
2445
|
-
```
|
|
2446
|
-
|
|
2447
|
-
### MCP Tools for RL
|
|
145
|
+
## β‘ Performance
|
|
2448
146
|
|
|
2449
|
-
|
|
147
|
+
| Metric | AgentDB | Baseline | Source |
|
|
148
|
+
|---|---|---|---|
|
|
149
|
+
| Vector search (100k vectors) | **<1 ms** | ~150 ms (SQLite + cosine loop) | `benchmarks/hnsw/` |
|
|
150
|
+
| HNSW query (1M vectors) | **2β5 ms** | ~100 ms (brute force) | `benchmarks/vector-search/` |
|
|
151
|
+
| Bulk insert (10k vectors) | **<100 ms** | ~12 s (sql.js) | `benchmarks/database/` |
|
|
152
|
+
| Memory footprint (1M Γ 384d) | **~96 MB (PQ8)** | ~1.5 GB (raw f32) | `benchmarks/quantization/` |
|
|
153
|
+
| Self-learning quality lift | **+36%** | n/a | `benchmarks/ruvector-performance.test.ts` |
|
|
154
|
+
| GNN attention recall | **+12.4%** | baseline HNSW | `benchmarks/attention-performance.ts` |
|
|
2450
155
|
|
|
2451
|
-
|
|
2452
|
-
- `agentdb_rl_predict` β get next action recommendation
|
|
2453
|
-
- `agentdb_rl_record_reward` β record outcome feedback
|
|
2454
|
-
- `agentdb_rl_train` β trigger training round
|
|
2455
|
-
- `agentdb_rl_transfer` β transfer learned policy to new task
|
|
2456
|
-
- `agentdb_rl_explain` β explain why a prediction was made
|
|
2457
|
-
|
|
2458
|
-
</details>
|
|
156
|
+
Run them yourself: `npm run bench` from this repo.
|
|
2459
157
|
|
|
2460
158
|
---
|
|
2461
159
|
|
|
2462
|
-
|
|
2463
|
-
<summary><strong>Hybrid Search</strong> β BM25 keyword + vector fusion for best-of-both-worlds retrieval</summary>
|
|
2464
|
-
|
|
2465
|
-
Combine traditional keyword search (BM25) with vector similarity for retrieval that handles both exact matches and semantic meaning:
|
|
2466
|
-
|
|
2467
|
-
```typescript
|
|
2468
|
-
import { createHybridSearch, createKeywordIndex } from "agentdb";
|
|
2469
|
-
|
|
2470
|
-
// Create keyword index (BM25)
|
|
2471
|
-
const keywordIndex = createKeywordIndex({
|
|
2472
|
-
k1: 1.2, // term frequency saturation
|
|
2473
|
-
b: 0.75, // document length normalization
|
|
2474
|
-
avgDocLength: 100,
|
|
2475
|
-
});
|
|
2476
|
-
|
|
2477
|
-
// Index documents
|
|
2478
|
-
keywordIndex.add("doc-1", "JWT authentication with refresh token rotation");
|
|
2479
|
-
keywordIndex.add("doc-2", "OAuth2 PKCE flow for mobile applications");
|
|
2480
|
-
|
|
2481
|
-
// Create hybrid search (keyword + vector)
|
|
2482
|
-
const hybrid = createHybridSearch(keywordIndex, vectorBackend, {
|
|
2483
|
-
fusion: "rrf", // 'rrf' (Reciprocal Rank Fusion) | 'linear' | 'max'
|
|
2484
|
-
keywordWeight: 0.3, // 30% keyword, 70% vector
|
|
2485
|
-
vectorWeight: 0.7,
|
|
2486
|
-
});
|
|
2487
|
-
|
|
2488
|
-
// Search with both keyword and semantic matching
|
|
2489
|
-
const results = await hybrid.search({
|
|
2490
|
-
text: "JWT refresh token", // keyword query
|
|
2491
|
-
embedding: queryEmbedding, // vector query
|
|
2492
|
-
k: 10,
|
|
2493
|
-
});
|
|
2494
|
-
// Results fused from both sources β exact term matches + semantic similarity
|
|
2495
|
-
```
|
|
2496
|
-
|
|
2497
|
-
### Fusion Strategies
|
|
2498
|
-
|
|
2499
|
-
| Strategy | How it works | Best For |
|
|
2500
|
-
| ----------------- | ------------------------------------------------------------------- | -------------------------------- |
|
|
2501
|
-
| **RRF** (default) | `1/(k + rank)` β rank-based fusion, no score calibration needed | General use |
|
|
2502
|
-
| **Linear** | `Ξ± Γ keyword_score + Ξ² Γ vector_score` β weighted score combination | When you know the right balance |
|
|
2503
|
-
| **Max** | `max(keyword_score, vector_score)` β takes highest signal | When either source is sufficient |
|
|
2504
|
-
|
|
2505
|
-
> **When to use hybrid search:** When your data contains domain-specific terms (function names, error codes, product IDs) that vector embeddings might miss, but you also want semantic understanding for natural language queries.
|
|
2506
|
-
|
|
2507
|
-
</details>
|
|
160
|
+
## π MCP Integration
|
|
2508
161
|
|
|
2509
|
-
|
|
162
|
+
41 tools across six families, all callable from Claude Code, Cursor, Cline, or any MCP-compatible client:
|
|
2510
163
|
|
|
2511
164
|
<details>
|
|
2512
|
-
<summary><strong>
|
|
2513
|
-
|
|
2514
|
-
|
|
2515
|
-
|
|
2516
|
-
|
|
2517
|
-
|
|
2518
|
-
|
|
2519
|
-
|
|
2520
|
-
|
|
2521
|
-
|
|
2522
|
-
|
|
2523
|
-
|
|
2524
|
-
anthropic: { apiKey: process.env.ANTHROPIC_KEY }, // Claude models
|
|
2525
|
-
onnx: { enabled: true }, // Local models via transformers.js
|
|
2526
|
-
},
|
|
2527
|
-
strategy: "auto", // auto-selects based on constraints below
|
|
2528
|
-
constraints: {
|
|
2529
|
-
maxCostPerQuery: 0.001, // max $0.001 per query
|
|
2530
|
-
minQuality: 0.8, // minimum quality score
|
|
2531
|
-
preferLocal: true, // prefer local models when possible
|
|
2532
|
-
requirePrivacy: false, // if true, only uses local providers
|
|
2533
|
-
},
|
|
2534
|
-
});
|
|
2535
|
-
|
|
2536
|
-
const response = await router.generate("Summarize this document...", {
|
|
2537
|
-
maxTokens: 500,
|
|
2538
|
-
temperature: 0.7,
|
|
2539
|
-
});
|
|
2540
|
-
```
|
|
2541
|
-
|
|
2542
|
-
### Provider Comparison
|
|
2543
|
-
|
|
2544
|
-
| Provider | Latency | Cost | Privacy | Models |
|
|
2545
|
-
| -------------- | ------- | --------- | ------------ | ---------------------------------------- |
|
|
2546
|
-
| **RuvLLM** | Fastest | Free | Full (local) | SIMD-optimized local models |
|
|
2547
|
-
| **ONNX** | Fast | Free | Full (local) | transformers.js models |
|
|
2548
|
-
| **OpenRouter** | ~500ms | $0.0001+ | Cloud | 200+ models (GPT-4, Claude, Llama, etc.) |
|
|
2549
|
-
| **Gemini** | ~300ms | Free tier | Cloud | Gemini Pro, Flash |
|
|
2550
|
-
| **Anthropic** | ~1s | $0.003+ | Cloud | Claude Opus, Sonnet, Haiku |
|
|
2551
|
-
|
|
2552
|
-
```typescript
|
|
2553
|
-
// Check what's available locally
|
|
2554
|
-
import { isRuvLLMInstalled } from "agentdb";
|
|
2555
|
-
if (await isRuvLLMInstalled()) {
|
|
2556
|
-
// Local inference available β no API keys needed
|
|
2557
|
-
}
|
|
2558
|
-
```
|
|
165
|
+
<summary><strong>Pattern Store / Search (8 tools)</strong></summary>
|
|
166
|
+
|
|
167
|
+
| Tool | Purpose |
|
|
168
|
+
|---|---|
|
|
169
|
+
| `agentdb_pattern_store` | Store a successful pattern with embedding + metadata |
|
|
170
|
+
| `agentdb_pattern_search` | Semantic search for similar past patterns |
|
|
171
|
+
| `agentdb_pattern_stats` | Retrieval stats, cache hits, hit-rate trends |
|
|
172
|
+
| `agentdb_pattern_delete` | Remove a pattern by id |
|
|
173
|
+
| `agentdb_batch_insert` | Bulk insert many patterns at once |
|
|
174
|
+
| `agentdb_batch_search` | Parallel multi-query search |
|
|
175
|
+
| `agentdb_export` | Dump patterns to JSON / CSV |
|
|
176
|
+
| `agentdb_import` | Load patterns from JSON / CSV |
|
|
2559
177
|
|
|
2560
178
|
</details>
|
|
2561
179
|
|
|
2562
|
-
---
|
|
2563
|
-
|
|
2564
180
|
<details>
|
|
2565
|
-
<summary><strong>
|
|
2566
|
-
|
|
2567
|
-
|
|
2568
|
-
|
|
2569
|
-
|
|
2570
|
-
|
|
2571
|
-
|
|
2572
|
-
|
|
2573
|
-
|
|
2574
|
-
|
|
2575
|
-
|
|
2576
|
-
|
|
2577
|
-
|
|
2578
|
-
|
|
2579
|
-
lockoutDuration: "30m",
|
|
2580
|
-
});
|
|
2581
|
-
|
|
2582
|
-
// User registration (Argon2id password hashing)
|
|
2583
|
-
const user = await auth.register({ email, password, role: "user" });
|
|
2584
|
-
|
|
2585
|
-
// Login β returns access + refresh token pair
|
|
2586
|
-
const { accessToken, refreshToken } = await auth.login(email, password);
|
|
2587
|
-
|
|
2588
|
-
// Token verification
|
|
2589
|
-
const payload = await auth.verifyAccessToken(accessToken);
|
|
2590
|
-
|
|
2591
|
-
// API key management
|
|
2592
|
-
const apiKey = await auth.generateApiKey(userId, {
|
|
2593
|
-
name: "prod-key",
|
|
2594
|
-
scopes: ["read", "write"],
|
|
2595
|
-
});
|
|
2596
|
-
await auth.rotateApiKey(apiKey.id); // automatic rotation
|
|
2597
|
-
```
|
|
2598
|
-
|
|
2599
|
-
### Audit Logging
|
|
2600
|
-
|
|
2601
|
-
```typescript
|
|
2602
|
-
import { AuditLogger } from "agentdb/services/audit-logger";
|
|
2603
|
-
|
|
2604
|
-
const audit = new AuditLogger({
|
|
2605
|
-
retention: "90d", // log retention period
|
|
2606
|
-
compliance: ["SOC2", "GDPR"], // compliance frameworks
|
|
2607
|
-
autoRotate: true, // automatic log rotation
|
|
2608
|
-
});
|
|
2609
|
-
|
|
2610
|
-
// 13 audit event types tracked automatically:
|
|
2611
|
-
// - jwt_auth, api_key_create, api_key_rotate, api_key_revoke
|
|
2612
|
-
// - login_success, login_failure, registration
|
|
2613
|
-
// - config_change, permission_change
|
|
2614
|
-
// - rate_limit_exceeded, sensitive_data_access
|
|
2615
|
-
// - data_export, data_deletion
|
|
2616
|
-
```
|
|
2617
|
-
|
|
2618
|
-
### Security Utilities
|
|
2619
|
-
|
|
2620
|
-
```typescript
|
|
2621
|
-
import {
|
|
2622
|
-
hashPassword,
|
|
2623
|
-
verifyPassword,
|
|
2624
|
-
generateApiKey,
|
|
2625
|
-
} from "agentdb/utils/crypto";
|
|
2626
|
-
|
|
2627
|
-
const hash = await hashPassword("user-password"); // Argon2id
|
|
2628
|
-
const valid = await verifyPassword("user-password", hash);
|
|
2629
|
-
const key = generateApiKey(); // cryptographically random
|
|
2630
|
-
```
|
|
181
|
+
<summary><strong>Hierarchical / Causal Memory (10 tools)</strong></summary>
|
|
182
|
+
|
|
183
|
+
| Tool | Purpose |
|
|
184
|
+
|---|---|
|
|
185
|
+
| `agentdb_hierarchical_store` | Tier-aware memory store (working / short / long) |
|
|
186
|
+
| `agentdb_hierarchical_recall` | Tier-filtered retrieval |
|
|
187
|
+
| `agentdb_hierarchical_delete` | Remove hierarchical entry by key |
|
|
188
|
+
| `agentdb_causal_edge` | Add a causal relationship between memories |
|
|
189
|
+
| `agentdb_causal_edge_delete` | Remove a causal edge by id |
|
|
190
|
+
| `agentdb_causal_node_delete` | Cascade-delete a node + incident edges |
|
|
191
|
+
| `agentdb_edges_by_endpoints` | Bulk-delete edges by `(from, to, label)` |
|
|
192
|
+
| `agentdb_causal_query` | Cypher-like graph queries |
|
|
193
|
+
| `agentdb_causal_explain` | Explain why two memories are connected |
|
|
194
|
+
| `agentdb_attestation_log` | Cryptographic audit trail |
|
|
2631
195
|
|
|
2632
196
|
</details>
|
|
2633
197
|
|
|
2634
|
-
---
|
|
2635
|
-
|
|
2636
198
|
<details>
|
|
2637
|
-
<summary><strong>
|
|
2638
|
-
|
|
2639
|
-
|
|
2640
|
-
|
|
2641
|
-
|
|
2642
|
-
|
|
2643
|
-
|
|
2644
|
-
|
|
2645
|
-
|
|
2646
|
-
|
|
2647
|
-
|
|
2648
|
-
|
|
2649
|
-
|
|
2650
|
-
|
|
2651
|
-
|
|
2652
|
-
|
|
2653
|
-
|
|
2654
|
-
// Patterns matching complex criteria
|
|
2655
|
-
const patterns = await filter.filterPatterns(db, {
|
|
2656
|
-
successRate: { $gte: 0.7, $lte: 1.0 },
|
|
2657
|
-
taskType: { $ne: "deprecated" },
|
|
2658
|
-
createdAt: { $gt: lastWeekTimestamp },
|
|
2659
|
-
});
|
|
2660
|
-
```
|
|
2661
|
-
|
|
2662
|
-
### Supported Operators
|
|
2663
|
-
|
|
2664
|
-
| Operator | Description | Example |
|
|
2665
|
-
| ----------- | --------------------- | ----------------------------------- |
|
|
2666
|
-
| `$eq` | Equal | `{ status: { $eq: 'active' } }` |
|
|
2667
|
-
| `$ne` | Not equal | `{ role: { $ne: 'admin' } }` |
|
|
2668
|
-
| `$gt` | Greater than | `{ reward: { $gt: 0.5 } }` |
|
|
2669
|
-
| `$gte` | Greater than or equal | `{ score: { $gte: 0.8 } }` |
|
|
2670
|
-
| `$lt` | Less than | `{ age: { $lt: 90 } }` |
|
|
2671
|
-
| `$lte` | Less than or equal | `{ priority: { $lte: 3 } }` |
|
|
2672
|
-
| `$in` | In array | `{ type: { $in: ['a', 'b'] } }` |
|
|
2673
|
-
| `$nin` | Not in array | `{ status: { $nin: ['deleted'] } }` |
|
|
2674
|
-
| `$contains` | Contains substring | `{ tags: { $contains: 'auth' } }` |
|
|
2675
|
-
| `$exists` | Field exists | `{ metadata: { $exists: true } }` |
|
|
199
|
+
<summary><strong>Reflexion + Skill Library (12 tools)</strong></summary>
|
|
200
|
+
|
|
201
|
+
| Tool | Purpose |
|
|
202
|
+
|---|---|
|
|
203
|
+
| `agentdb_reflexion_store` | Store an episode (task + outcome + critique) |
|
|
204
|
+
| `agentdb_reflexion_recall` | Retrieve relevant past episodes |
|
|
205
|
+
| `agentdb_reflexion_delete` | Remove an episode |
|
|
206
|
+
| `agentdb_reflexion_rebuild` | Re-hydrate vector index from durable SQL |
|
|
207
|
+
| `agentdb_skill_create` | Create a reusable skill from a pattern |
|
|
208
|
+
| `agentdb_skill_compose` | Chain skills AβBβC with bandit-picked composition |
|
|
209
|
+
| `agentdb_skill_search` | Find skills by intent embedding |
|
|
210
|
+
| `agentdb_critique_summary` | Summarize lessons from past failures |
|
|
211
|
+
| `agentdb_success_strategies` | Surface what worked across past episodes |
|
|
212
|
+
| `agentdb_task_stats` | Per-task win-rate, latency, reward trends |
|
|
213
|
+
| `agentdb_prune` | TTL + quality-based episode pruning |
|
|
214
|
+
| `agentdb_warm_cache` | Pre-populate query cache for a session |
|
|
2676
215
|
|
|
2677
216
|
</details>
|
|
2678
217
|
|
|
2679
|
-
---
|
|
2680
|
-
|
|
2681
218
|
<details>
|
|
2682
|
-
<summary><strong>
|
|
2683
|
-
|
|
2684
|
-
|
|
2685
|
-
|
|
2686
|
-
|
|
2687
|
-
|
|
2688
|
-
|
|
2689
|
-
|
|
2690
|
-
|
|
2691
|
-
|
|
2692
|
-
|
|
2693
|
-
|
|
2694
|
-
|
|
2695
|
-
|
|
2696
|
-
|
|
2697
|
-
const results = await db.search(queryEmbedding, 10);
|
|
2698
|
-
await db.batchInsert(documents);
|
|
2699
|
-
|
|
2700
|
-
// Performance wrapper includes:
|
|
2701
|
-
// - Direct function calls (no CLI arg parsing)
|
|
2702
|
-
// - Pre-initialized connections (no startup cost per call)
|
|
2703
|
-
// - Batched operations
|
|
2704
|
-
// - Connection pooling
|
|
2705
|
-
```
|
|
2706
|
-
|
|
2707
|
-
### Wrapper Performance vs CLI
|
|
2708
|
-
|
|
2709
|
-
| Operation | CLI | AgentDBFast | Speedup |
|
|
2710
|
-
| ------------------ | ------ | ----------- | ------- |
|
|
2711
|
-
| Single insert | ~20ms | ~0.1ms | 200x |
|
|
2712
|
-
| Search (k=10) | ~15ms | ~0.08ms | 187x |
|
|
2713
|
-
| Batch insert (100) | ~500ms | ~10ms | 50x |
|
|
2714
|
-
|
|
2715
|
-
### Attention Wrappers
|
|
2716
|
-
|
|
2717
|
-
Production-ready attention implementations with 11-22x speedup over naive:
|
|
2718
|
-
|
|
2719
|
-
```typescript
|
|
2720
|
-
import {
|
|
2721
|
-
MultiHeadAttention,
|
|
2722
|
-
FlashAttention,
|
|
2723
|
-
LinearAttention,
|
|
2724
|
-
HyperbolicAttention,
|
|
2725
|
-
MoEAttention,
|
|
2726
|
-
} from "agentdb/wrappers";
|
|
2727
|
-
|
|
2728
|
-
// Flash Attention β O(N) memory instead of O(N^2)
|
|
2729
|
-
const flash = new FlashAttention({ numHeads: 8 });
|
|
2730
|
-
const result = await flash.forward(query, keys, values);
|
|
2731
|
-
|
|
2732
|
-
// Mixture of Experts β routes to specialized attention heads
|
|
2733
|
-
const moe = new MoEAttention({ numExperts: 4, topK: 2 });
|
|
2734
|
-
const result = await moe.forward(query, keys, values);
|
|
2735
|
-
```
|
|
2736
|
-
|
|
2737
|
-
### Embedding Providers
|
|
2738
|
-
|
|
2739
|
-
Multiple embedding backends with automatic fallback:
|
|
2740
|
-
|
|
2741
|
-
```typescript
|
|
2742
|
-
import {
|
|
2743
|
-
OpenAIEmbeddingService,
|
|
2744
|
-
TransformersEmbeddingService,
|
|
2745
|
-
MockEmbeddingService,
|
|
2746
|
-
} from "agentdb/wrappers";
|
|
2747
|
-
|
|
2748
|
-
// OpenAI (cloud)
|
|
2749
|
-
const openai = new OpenAIEmbeddingService({ apiKey: process.env.OPENAI_KEY });
|
|
2750
|
-
|
|
2751
|
-
// Transformers.js (local, free)
|
|
2752
|
-
const local = new TransformersEmbeddingService({
|
|
2753
|
-
model: "Xenova/all-MiniLM-L6-v2",
|
|
2754
|
-
});
|
|
2755
|
-
|
|
2756
|
-
// Mock (testing)
|
|
2757
|
-
const mock = new MockEmbeddingService({ dimension: 384 });
|
|
2758
|
-
```
|
|
219
|
+
<summary><strong>Learning + Routing (11 tools)</strong></summary>
|
|
220
|
+
|
|
221
|
+
| Tool | Purpose |
|
|
222
|
+
|---|---|
|
|
223
|
+
| `agentdb_learning_route` | Route a task to the right RL algorithm |
|
|
224
|
+
| `agentdb_learning_train` | Train a specific RL agent on episodes |
|
|
225
|
+
| `agentdb_learning_predict` | Get an action prediction for a state |
|
|
226
|
+
| `agentdb_bandit_update` | Update bandit reward for an arm |
|
|
227
|
+
| `agentdb_bandit_pick` | Sample the best arm under Thompson Sampling |
|
|
228
|
+
| `agentdb_consolidate` | Run NightlyLearner consolidation pipeline |
|
|
229
|
+
| `agentdb_compose` | Combine memory patterns into a strategy |
|
|
230
|
+
| `agentdb_synthesize` | Build a context window from related memories |
|
|
231
|
+
| `agentdb_explain_recall` | Feature-attributed retrieval results |
|
|
232
|
+
| `agentdb_diversity_rank` | MMR-rerank for diverse top-k |
|
|
233
|
+
| `agentdb_metadata_filter` | Filtered semantic search |
|
|
2759
234
|
|
|
2760
235
|
</details>
|
|
2761
236
|
|
|
2762
237
|
---
|
|
2763
238
|
|
|
2764
|
-
|
|
2765
|
-
<summary><strong>Benchmark Suite</strong> β 5 built-in benchmarks with custom benchmark support</summary>
|
|
2766
|
-
|
|
2767
|
-
Run performance benchmarks to validate your deployment:
|
|
2768
|
-
|
|
2769
|
-
```typescript
|
|
2770
|
-
import { BenchmarkSuite, runBenchmarks, formatReportAsMarkdown } from "agentdb";
|
|
2771
|
-
|
|
2772
|
-
// Run all built-in benchmarks
|
|
2773
|
-
const report = await runBenchmarks({
|
|
2774
|
-
dimension: 384,
|
|
2775
|
-
iterations: 100,
|
|
2776
|
-
warmup: 10,
|
|
2777
|
-
});
|
|
2778
|
-
|
|
2779
|
-
console.log(formatReportAsMarkdown(report));
|
|
2780
|
-
```
|
|
2781
|
-
|
|
2782
|
-
### Built-in Benchmarks
|
|
2783
|
-
|
|
2784
|
-
| Benchmark | Measures | Key Metrics |
|
|
2785
|
-
| ------------------------- | --------------------- | --------------------------------------- |
|
|
2786
|
-
| **VectorInsertBenchmark** | Insert throughput | ops/sec, p50/p99 latency |
|
|
2787
|
-
| **VectorSearchBenchmark** | Search performance | ops/sec, recall@k, latency distribution |
|
|
2788
|
-
| **MemoryUsageBenchmark** | RAM consumption | bytes per vector, total footprint |
|
|
2789
|
-
| **ConcurrencyBenchmark** | Parallel performance | throughput under load, contention |
|
|
2790
|
-
| **QuantizationBenchmark** | Compression tradeoffs | quality loss vs memory savings |
|
|
239
|
+
## π Used By
|
|
2791
240
|
|
|
2792
|
-
|
|
241
|
+
AgentDB powers the memory + learning layer in:
|
|
2793
242
|
|
|
2794
|
-
|
|
2795
|
-
|
|
2796
|
-
|
|
2797
|
-
|
|
2798
|
-
|
|
2799
|
-
|
|
2800
|
-
async setup() {
|
|
2801
|
-
/* prepare data */
|
|
2802
|
-
}
|
|
2803
|
-
async run() {
|
|
2804
|
-
/* measure this */
|
|
2805
|
-
}
|
|
2806
|
-
async teardown() {
|
|
2807
|
-
/* cleanup */
|
|
2808
|
-
}
|
|
2809
|
-
}
|
|
2810
|
-
|
|
2811
|
-
const suite = new BenchmarkSuite();
|
|
2812
|
-
suite.add(new MyBenchmark());
|
|
2813
|
-
const report = await suite.run({ iterations: 50 });
|
|
2814
|
-
|
|
2815
|
-
// Compare reports across runs
|
|
2816
|
-
import { formatComparisonAsMarkdown } from "agentdb";
|
|
2817
|
-
console.log(formatComparisonAsMarkdown(reportBefore, reportAfter));
|
|
2818
|
-
```
|
|
2819
|
-
|
|
2820
|
-
### CLI Benchmarks
|
|
2821
|
-
|
|
2822
|
-
```bash
|
|
2823
|
-
npm run benchmark # Quick benchmark
|
|
2824
|
-
npm run benchmark:full # Full suite
|
|
2825
|
-
npm run benchmark:attention # Attention mechanism performance
|
|
2826
|
-
npm run benchmark:backends # Compare all backends
|
|
2827
|
-
npm run benchmark:ruvector # RuVector-specific benchmarks
|
|
2828
|
-
npm run benchmark:all # Everything
|
|
2829
|
-
```
|
|
243
|
+
| Project | What it uses AgentDB for |
|
|
244
|
+
|---|---|
|
|
245
|
+
| [**`agentic-flow`**](https://github.com/ruvnet/agentic-flow) | ReasoningBank backend, ReflexionMemory, NightlyLearner consolidation, 30+ agent memory namespaces |
|
|
246
|
+
| [**`ruflo`**](https://github.com/ruvnet/ruflo) | Plugin marketplace memory, agent federation audit log, hierarchical recall for /adr-index, swarm coordination patterns |
|
|
247
|
+
| [**`@ruvector`**](https://github.com/ruvnet/ruvector) | Reference downstream for the Rust engine β every release is verified against AgentDB's test suite |
|
|
2830
248
|
|
|
2831
|
-
|
|
249
|
+
If you ship something on top of AgentDB, [open an issue](https://github.com/ruvnet/agentdb/issues) and we'll add you.
|
|
2832
250
|
|
|
2833
251
|
---
|
|
2834
252
|
|
|
2835
|
-
##
|
|
2836
|
-
|
|
2837
|
-
<details>
|
|
2838
|
-
<summary><strong>Test Suite</strong> β unit, integration, performance, security, and browser tests</summary>
|
|
2839
|
-
|
|
2840
|
-
AgentDB ships with a comprehensive test suite covering every layer of the stack. All tests run via [Vitest](https://vitest.dev/) with parallel execution.
|
|
2841
|
-
|
|
2842
|
-
### Quick Commands
|
|
2843
|
-
|
|
2844
|
-
```bash
|
|
2845
|
-
npm test # Run all tests (watch mode)
|
|
2846
|
-
npm run test:unit # Unit tests only (single run)
|
|
2847
|
-
npm run test:browser # Browser bundle + WASM tests
|
|
2848
|
-
npm run test:ci # CI pipeline: browser tests + build + bundle verification
|
|
2849
|
-
```
|
|
253
|
+
## π³ Docker / Edge / Browser
|
|
2850
254
|
|
|
2851
|
-
|
|
255
|
+
AgentDB compiles to four targets from one source:
|
|
2852
256
|
|
|
2853
|
-
|
|
|
2854
|
-
|
|
2855
|
-
| **
|
|
2856
|
-
| **
|
|
2857
|
-
| **
|
|
2858
|
-
| **
|
|
2859
|
-
| **Security tests** | Input validation, injection prevention, witness chain verification | XSS patterns, SQL injection, path traversal, Cypher sanitization, SHAKE-256 |
|
|
2860
|
-
|
|
2861
|
-
### Benchmarks
|
|
257
|
+
| Target | What | When |
|
|
258
|
+
|---|---|---|
|
|
259
|
+
| **Node native** | NAPI bindings (Linux, macOS, Windows; x64 + arm64) | Backend services, CLI, MCP server |
|
|
260
|
+
| **Node WASM fallback** | sql.js + WASM engine | Restricted hosts that can't run NAPI |
|
|
261
|
+
| **Browser** | Pure WASM bundle | Offline-first apps, edge functions, IDE extensions |
|
|
262
|
+
| **Docker** | `docker-compose.yml` in `docker/` | Local dev, CI, prod deploy |
|
|
2862
263
|
|
|
2863
264
|
```bash
|
|
2864
|
-
|
|
2865
|
-
|
|
2866
|
-
npm run benchmark:attention # Attention mechanism performance
|
|
2867
|
-
npm run benchmark:backends # Compare RuVector vs RVF vs HNSWLib vs sql.js
|
|
2868
|
-
npm run benchmark:ruvector # RuVector-specific benchmarks
|
|
2869
|
-
npm run benchmark:all # Run everything
|
|
2870
|
-
```
|
|
265
|
+
# Browser
|
|
266
|
+
import { createBrowserDb } from 'agentdb/browser';
|
|
2871
267
|
|
|
2872
|
-
|
|
2873
|
-
|
|
2874
|
-
The CI pipeline runs `test:ci` which executes:
|
|
2875
|
-
|
|
2876
|
-
1. **Browser bundle tests** β verifies WASM and JS fallbacks work
|
|
2877
|
-
2. **TypeScript build** β full `tsc` compilation
|
|
2878
|
-
3. **Bundle verification** β ensures all export paths resolve correctly
|
|
2879
|
-
|
|
2880
|
-
### Writing Custom Tests
|
|
2881
|
-
|
|
2882
|
-
```typescript
|
|
2883
|
-
import { describe, it, expect } from "vitest";
|
|
2884
|
-
import { createDatabase, ReasoningBank, EmbeddingService } from "agentdb";
|
|
2885
|
-
|
|
2886
|
-
describe("My Agent Memory", () => {
|
|
2887
|
-
it("stores and retrieves patterns", async () => {
|
|
2888
|
-
const db = await createDatabase(":memory:");
|
|
2889
|
-
const embedder = new EmbeddingService({ model: "Xenova/all-MiniLM-L6-v2" });
|
|
2890
|
-
await embedder.initialize();
|
|
2891
|
-
|
|
2892
|
-
const bank = new ReasoningBank(db, embedder);
|
|
2893
|
-
await bank.storePattern({
|
|
2894
|
-
taskType: "test",
|
|
2895
|
-
approach: "TDD",
|
|
2896
|
-
successRate: 0.95,
|
|
2897
|
-
});
|
|
2898
|
-
|
|
2899
|
-
const results = await bank.searchPatterns({ task: "testing", k: 5 });
|
|
2900
|
-
expect(results.length).toBeGreaterThan(0);
|
|
2901
|
-
});
|
|
2902
|
-
});
|
|
268
|
+
# Docker
|
|
269
|
+
docker compose -f docker/docker-compose.yml up
|
|
2903
270
|
```
|
|
2904
271
|
|
|
2905
|
-
</details>
|
|
2906
|
-
|
|
2907
272
|
---
|
|
2908
273
|
|
|
2909
274
|
## Documentation
|
|
2910
275
|
|
|
2911
|
-
|
|
|
2912
|
-
|
|
2913
|
-
| [
|
|
2914
|
-
| [
|
|
2915
|
-
| [
|
|
2916
|
-
| [
|
|
2917
|
-
| [
|
|
2918
|
-
| [
|
|
276
|
+
| Doc | When to read it |
|
|
277
|
+
|---|---|
|
|
278
|
+
| [**Full README** (deep)](docs/README-full.md) | Every feature, every API, every option β the complete reference (2,900+ lines) |
|
|
279
|
+
| [**PUBLISHING.md**](docs/PUBLISHING.md) | npm publish flow, dist-tag policy, release verification |
|
|
280
|
+
| [**ADR-071**](docs/ADR-071-agentdb-ruvector-wasm-capabilities-review.md) | WASM integration design |
|
|
281
|
+
| [**ADR-072**](docs/ADR-072-ruvector-advanced-features-integration.md) | RuVector advanced-feature integration |
|
|
282
|
+
| [**Examples**](examples/) | End-to-end runnable scripts β RAG chatbot, code-review agent, RL training, edge deploy |
|
|
283
|
+
| [**Benchmarks**](benchmarks/) | Reproducible perf harness β HNSW, attention, quantization, RL, end-to-end |
|
|
2919
284
|
|
|
2920
285
|
---
|
|
2921
286
|
|
|
2922
|
-
##
|
|
287
|
+
## Repository
|
|
2923
288
|
|
|
2924
|
-
|
|
289
|
+
| | |
|
|
290
|
+
|---|---|
|
|
291
|
+
| π¦ **npm** | [`agentdb`](https://www.npmjs.com/package/agentdb) |
|
|
292
|
+
| π **Source** | https://github.com/ruvnet/agentdb |
|
|
293
|
+
| π **Issues** | https://github.com/ruvnet/agentdb/issues |
|
|
294
|
+
| π¨ **Marketing site** | [`ui/`](./ui) (Vite + React + shadcn/ui) |
|
|
295
|
+
| 𧬠**Engine** | [`@ruvector`](https://github.com/ruvnet/ruvector) (Rust + NAPI) |
|
|
296
|
+
| π **Reference consumer** | [`agentic-flow`](https://github.com/ruvnet/agentic-flow) (uses this as a git submodule at `packages/agentdb/`) |
|
|
2925
297
|
|
|
2926
298
|
---
|
|
2927
299
|
|
|
2928
|
-
##
|
|
2929
|
-
|
|
2930
|
-
MIT OR Apache-2.0 β See [LICENSE-MIT](LICENSE-MIT) and [LICENSE-APACHE](LICENSE-APACHE).
|
|
2931
|
-
|
|
2932
|
-
---
|
|
300
|
+
## Support
|
|
2933
301
|
|
|
2934
|
-
|
|
302
|
+
| Resource | Link |
|
|
303
|
+
|---|---|
|
|
304
|
+
| Documentation | [docs/README-full.md](docs/README-full.md) |
|
|
305
|
+
| Issues & Bugs | [GitHub Issues](https://github.com/ruvnet/agentdb/issues) |
|
|
306
|
+
| Enterprise | [ruv.io](https://ruv.io) |
|
|
307
|
+
| Community | [Agentics Foundation Discord](https://discord.com/invite/dfxmpwkG2D) |
|
|
308
|
+
| Engine | [`ruvector`](https://github.com/ruvnet/ruvector) |
|
|
309
|
+
| Powered by | [Cognitum.one](https://cognitum.one) |
|
|
2935
310
|
|
|
2936
|
-
|
|
2937
|
-
npm install agentdb
|
|
2938
|
-
```
|
|
311
|
+
## License
|
|
2939
312
|
|
|
2940
|
-
[
|
|
313
|
+
[MIT](LICENSE) OR Apache-2.0 β [RuvNet](https://github.com/ruvnet)
|