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.

Explore the wider ecosystem

Building agents that remember? Explore the wider ecosystem.

Explore Cognitum One · Try ruOS, an agentic desktop in your browser.

Why AgentDB?

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.

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 on the ruvector Rust engine.

What AgentDB Does

Self-Learning Vector Memory

Agent ──► AgentDB (.rvf) ──► HNSW search ──► top-k results
   │                                              │
   ▼                                              ▼
recordFeedback(id, reward)  ◄──  agent uses some, ignores rest
   │
   ▼
Bandit re-tunes ranking / RL choice / compression  ──► next query is smarter

3 lines to self-learning search:

const backend = await SelfLearningRvfBackend.create({ learning: true, storagePath: "./my.rvf" });
const results = await backend.searchAsync(query, 10);   // search
backend.recordFeedback(results[0].id, 0.9);             // learn — next search is smarter

Quick Start

Node.js 20.9.0 or newer is required, matching the patched sharp runtime used by local Transformers embeddings and better-sqlite3 12. Node 18 is no longer supported.

There are three ways to use AgentDB depending on what you're building. Pick whichever matches your stack:

Path A — npm library

npm install agentdb

import { SelfLearningRvfBackend } from 'agentdb';

const db = await SelfLearningRvfBackend.create({
  learning: true,
  storagePath: './memory.rvf',
});

await db.insertAsync('doc1', new Float32Array(384), { text: 'Hello world' });
const hits = await db.searchAsync(queryEmbedding, 5);
db.recordFeedback(hits[0].id, 1.0);  // it was useful — db gets smarter

Path B — CLI in 10 seconds

# Try it without installing
npx agentdb init my-memory.rvf
npx agentdb add my-memory.rvf "vector memory that learns"
npx agentdb search my-memory.rvf "self-improving search" --top-k 5

Path C — MCP server (Claude Code, Cursor, etc.)

claude mcp add agentdb -- npx agentdb@latest mcp start

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.

What You Get

Optional native integrations

Installed by default as optional dependencies. Each has a JavaScript fallback, so agentdb works without them (ADR-018).

🧠 Self-Learning Loop

Most retrieval systems are read-only. AgentDB closes the loop:

search ──► top-k ──► agent picks the useful ones ──► recordFeedback()
                                                            │
                                                            ▼
                                              Thompson Sampling bandit
                                                            │
                                                            ▼
                       re-weights ranking · re-picks RL algorithm · re-tunes compression
                                                            │
                                                            ▼
                                                   next search is sharper

The bandit isn't a gimmick — it's used at four decision points:

1. Pattern ranking — which historical pattern matches this new query best?
2. RL algorithm selection — Q-Learning for tabular tasks, PPO for continuous control, MCTS for planning, etc.
3. Compression tier — full precision when accuracy matters, PQ4 when memory does.
4. Skill composition — chain skill A→B→C or skill A→D→E?

Each decision logs reward over time. Bad arms decay fast. Good arms stick.

⚡ Performance

Run them yourself: npm run bench from this repo.

Long-term memory retrieval (LongMemEval)

Episode search fuses BM25 keyword ranking with vector ranking by default (hybrid: false turns it off), and rerank: true adds a local cross-encoder over the top candidates. Session retrieval on LongMemEval, default MiniLM embedder, local models only, official protocol (470 questions):

The harness (benchmarks/longmemeval/) runs the same ranking functions over turn chunks; protocol, S-split numbers, other rerankers and limits are in ADR-016.

🔌 MCP Integration

41 tools across six families, all callable from Claude Code, Cursor, Cline, or any MCP-compatible client:

🔗 Used By

AgentDB powers the memory + learning layer in:

If you ship something on top of AgentDB, open an issue and we'll add you.

🐳 Docker / Edge / Browser

AgentDB compiles to four targets from one source:

# Browser
import { createBrowserDb } from 'agentdb/browser';

# Docker
docker compose -f docker/docker-compose.yml up

Documentation

Repository

Support

License

MIT OR Apache-2.0 — RuvNet

Works with / Used by

Part of the ruv.io open-source stack for agent memory, vector database, AI agents.

• Works with (its runtime dependencies): @ruvector/attention, @ruvector/gnn, @ruvector/graph-node, @ruvector/graph-transformer, @ruvector/mincut-wasm, @ruvector/rabitq-wasm, @ruvector/router, @ruvector/ruvllm, @ruvector/rvf, @ruvector/rvf-node, @ruvector/rvf-solver, @ruvector/rvf-wasm, @ruvector/sona, @ruvnet/sublinear-core, aidefence, ruvector, ruvector-attention-wasm, ruvector-graph-transformer-wasm
• Used by (published packages that depend on it): @agentic-robotics/mcp, @agentic-robotics/self-learning, @claude-flow/aidefence, @claude-flow/cli, @claude-flow/memory, @claude-flow/neural, @foxruv/iris, @foxruv/iris-ultrathink, @foxruv/nova-medicina, @neural-trader/agentic-accounting-agents, @neural-trader/agentic-accounting-core, @neural-trader/example-dynamic-pricing

Built by rUv · ruv.io · Source