agentdb-causal

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.

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

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

	npm library	CLI	MCP server
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.
Install	npm i agentdb	npx agentdb … (no install)	claude mcp add agentdb -- npx agentdb mcp start
Best for	Embedding the engine in your own code	Quick experiments, CI scripts, ad-hoc memory	Plugging memory + learning into an LLM agent

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