AI 클라이언트에게 패턴 저장, 의미론적 검색, 피드백을 통한 랭킹 개선이 가능한 자가 학습형 벡터 메모리를 제공합니다.
다른 이름 ruvnet/agentdb
- 스타
- 99
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 11일
- 라이선스
- MIT
AgentDB MCP란?
AgentDB은(는) MCP server입니다. AI 클라이언트에게 패턴 저장, 의미론적 검색, 피드백을 통한 랭킹 개선이 가능한 자가 학습형 벡터 메모리를 제공합니다.
프로젝트 README에서 생성된 요약
AgentDB MCP server 정보
AgentDB는 지능형 애플리케이션을 구축하는 개발자가 AI 에이전트에게 자가 학습형 인지 컨테이너를 제공할 수 있게 합니다. .rvf 파일 내에 패턴, 기술, 인과 관계 추론을 저장하는 단일 파일 벡터 메모리 역할을 수행합니다. 임베딩만 저장하는 표준 벡터 데이터베이스와 달리, 이 시스템은 Thompson Sampling bandit을 사용하여 에이전트가 실제로 어떤 결과를 사용하는지 관찰하며, 피드백만으로 검색 품질을 최대 36%까지 향상시킬 수 있습니다.
사용자는 이를 npm 라이브러리로 통합하여 커스텀 Node.js 애플리케이션에 사용하거나, MCP server를 통해 41개의 특화된 도구를 Claude Code, Cursor, Cline과 같은 클라이언트에 직접 연결할 수 있습니다. 이 서버는 agentdb_pattern_store, agentdb_pattern_search, agentdb_reflexion과 같은 기능을 제공합니다. 외부 API 키나 월간 구독 없이 Node.js, WASM을 통한 브라우저 또는 edge runtime에서 로컬로 실행됩니다. 기반이 되는 RuVector Rust 엔진은 HNSW 벡터 검색 및 하이브리드 검색에 대해 높은 성능을 보장합니다.
활용 사례
- 1LLM 클라이언트에 메모리 연결정교한 기술 라이브러리와 에피소드 메모리를 기존 코딩 어시스턴트 워크플로에 직접 통합합니다.
- 2복잡한 인지 패턴 저장성공적인 실행 패턴과 메타데이터를 단일 휴대용 파일로 저장하여 장기적인 에이전트 메모리로 활용합니다.
- 3하이브리드 의미론적 검색 수행정확한 키워드 매칭과 밀집 벡터 의도(dense vector intent)를 결합하여 정보를 검색합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
AgentDB MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 AgentDB MCP 설치
$ claude mcp add agentdb -- npx -y agentdbCursor에 AgentDB MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"agentdb": {
"command": "npx",
"args": [
"-y",
"agentdb"
]
}
}
}VS Code에 AgentDB MCP 설치
.vscode/mcp.json
{
"servers": {
"agentdb": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"agentdb"
]
}
}
}VS Code CLI에 AgentDB MCP 설치
$ code --add-mcp '{"name":"agentdb","type":"stdio","command":"npx","args":["-y","agentdb"]}'Claude Desktop에 AgentDB MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"agentdb": {
"command": "npx",
"args": [
"-y",
"agentdb"
]
}
}
}Codex에 AgentDB MCP 설치
$ codex mcp add agentdb -- npx -y agentdbCodex config.toml에 AgentDB MCP 설치
~/.codex/config.toml
[mcp_servers.agentdb] command = "npx" args = ["-y", "agentdb"]
Gemini CLI에 AgentDB MCP 설치
$ gemini mcp add -s user agentdb npx -- -y agentdbGemini settings.json에 AgentDB MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"agentdb": {
"command": "npx",
"args": [
"-y",
"agentdb"
]
}
}
}자동 검사
2026년 11월 12일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음통과
- 원격 엔드포인트가 HTTPS 사용검사되지 않음
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
README
GitHub에서 보기AgentDB
Vector memory that gets smarter every time your agent uses it.
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
rUvon theruvectorRust 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:
| 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/backends/self-learning';
const db = await SelfLearningRvfBackend.create({
dimension: 384,
learning: true,
storagePath: './memory.rvf',
});
// Use your embedding model here; any 384-dim Float32Array works.
const embedding = Float32Array.from({ length: 384 }, (_, i) => Math.sin(i));
await db.insertAsync('doc1', embedding, { text: 'Hello world' });
const hits = await db.searchAsync(embedding, 5);
db.recordFeedback(hits[0].id, 1.0); // it was useful — db gets smarter
Path B — CLI in 10 seconds
# Try it without installing (creates ./agentdb.db)
npx agentdb init
npx agentdb reflexion store "session-1" "implement_auth" 0.95 true "Used OAuth2 with PKCE"
npx agentdb reflexion retrieve "authentication" --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
| Capability | Description |
|---|---|
| 🧠 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 |
| 🐝 Cognitive Memory | 6 human-inspired patterns — episodic replay (Reflexion), skill library, causal reasoning, hierarchical context, semantic clustering, working memory |
| 🤖 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 |
| ⚡ 150× faster than SQLite | RuVector Rust engine via NAPI bindings; HNSW vector search; sub-millisecond reads on 100k+ vectors |
| 🔍 Hybrid Search | BM25 keyword + dense vector fused with Reciprocal Rank Fusion — exact terms and semantic intent in one query |
| 🕸️ Graph Intelligence | Cypher queries, causal edges, GNN 8-head attention (+12.4% recall), hyperedges for n-ary relationships |
| 💾 Single-file Storage | Everything (vectors, indexes, learning state, audit log) in one .rvf "Cognitive Container" — no servers, no API keys, no monthly bills |
| 🎯 Quantization | 4-32× memory reduction with PQ8 / PQ4 / binary quantization; minimal recall loss; runs on commodity hardware |
| 🔌 41 MCP Tools | First-class Claude Code / Cursor / Cline integration — pattern store, search, skill library, reflexion, causal edges, hierarchical recall, delete |
| 🌐 Runs Anywhere | Node, browser (WASM), edge runtimes, fully offline — same API, same .rvf file |
| 🛡️ Enterprise Security | JWT auth, API key rotation, Argon2id hashing, SOC2 / GDPR audit trails, cryptographic witness chain |
| 🔗 agentic-flow Integration | Drop-in for agentic-flow — backs ReasoningBank, MemoryController, NightlyLearner, and 30+ agents |
Optional native integrations
Installed by default as optional dependencies. Each has a JavaScript fallback, so agentdb works without them (ADR-018).
| Package | Powers | Measured |
|---|---|---|
@ruvector/graph-transformer |
Personalized PageRank in SparsificationService and sparse attention |
40x–780x faster than the JS path (500–5,000 nodes) |
@ruvector/mincut-wasm |
Exact global min cut in MincutService and partitioned attention |
cut of 4 edges where the old split cut 1,003 (1,000 nodes) |
@ruvector/rabitq-wasm |
Opt-in 1-bit index for the built-in sql.js backend (quantizedIndex: 'rabitq') |
6.4x faster at 50k vectors, recall@10 1.000 |
aidefence |
Opt-in prompt-injection screening of stored memories (AGENTDB_INJECTION_GUARD=warn|block) |
0.1–10 ms per field |
🧠 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:
- Pattern ranking — which historical pattern matches this new query best?
- RL algorithm selection — Q-Learning for tabular tasks, PPO for continuous control, MCTS for planning, etc.
- Compression tier — full precision when accuracy matters, PQ4 when memory does.
- 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
| Metric | AgentDB | Baseline | Source |
|---|---|---|---|
| Vector search (100k vectors) | <1 ms | ~150 ms (SQLite + cosine loop) | benchmarks/hnsw/ |
| HNSW query (1M vectors) | 2–5 ms | ~100 ms (brute force) | benchmarks/vector-search/ |
| Bulk insert (10k vectors) | <100 ms | ~12 s (sql.js) | benchmarks/database/ |
| Memory footprint (1M × 384d) | ~96 MB (PQ8) | ~1.5 GB (raw f32) | benchmarks/quantization/ |
| Self-learning quality lift | +36% | n/a | benchmarks/ruvector-performance.test.ts |
| GNN attention recall | +12.4% | baseline HNSW | benchmarks/attention-performance.ts |
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):
| LongMemEval_M (≈500 sessions per question) | recall_all@5 | NDCG@5 | recall_all@10 |
|---|---|---|---|
| dense only | 0.630 | 0.692 | 0.751 |
| hybrid (default) | 0.719 | 0.750 | 0.806 |
hybrid + rerank: true |
0.789 | 0.828 | 0.881 |
| LongMemEval paper, best (Contriever + LLM fact keys) | 0.762 | 0.632 | 0.862 |
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:
| Tool | Purpose |
|---|---|
agentdb_pattern_store |
Store a successful pattern with embedding + metadata |
agentdb_pattern_search |
Semantic search for similar past patterns |
agentdb_pattern_stats |
Retrieval stats, cache hits, hit-rate trends |
agentdb_pattern_delete |
Remove a pattern by id |
agentdb_batch_insert |
Bulk insert many patterns at once |
agentdb_batch_search |
Parallel multi-query search |
agentdb_export |
Dump patterns to JSON / CSV |
agentdb_import |
Load patterns from JSON / CSV |
| Tool | Purpose |
|---|---|
agentdb_hierarchical_store |
Tier-aware memory store (working / short / long) |
agentdb_hierarchical_recall |
Tier-filtered retrieval |
agentdb_hierarchical_delete |
Remove hierarchical entry by key |
agentdb_causal_edge |
Add a causal relationship between memories |
agentdb_causal_edge_delete |
Remove a causal edge by id |
agentdb_causal_node_delete |
Cascade-delete a node + incident edges |
agentdb_edges_by_endpoints |
Bulk-delete edges by (from, to, label) |
agentdb_causal_query |
Cypher-like graph queries |
agentdb_causal_explain |
Explain why two memories are connected |
agentdb_attestation_log |
Cryptographic audit trail |
| Tool | Purpose |
|---|---|
agentdb_reflexion_store |
Store an episode (task + outcome + critique) |
agentdb_reflexion_recall |
Retrieve relevant past episodes |
agentdb_reflexion_delete |
Remove an episode |
agentdb_reflexion_rebuild |
Re-hydrate vector index from durable SQL |
agentdb_skill_create |
Create a reusable skill from a pattern |
agentdb_skill_compose |
Chain skills A→B→C with bandit-picked composition |
agentdb_skill_search |
Find skills by intent embedding |
agentdb_critique_summary |
Summarize lessons from past failures |
agentdb_success_strategies |
Surface what worked across past episodes |
agentdb_task_stats |
Per-task win-rate, latency, reward trends |
agentdb_prune |
TTL + quality-based episode pruning |
agentdb_warm_cache |
Pre-populate query cache for a session |
| Tool | Purpose |
|---|---|
agentdb_learning_route |
Route a task to the right RL algorithm |
agentdb_learning_train |
Train a specific RL agent on episodes |
agentdb_learning_predict |
Get an action prediction for a state |
agentdb_bandit_update |
Update bandit reward for an arm |
agentdb_bandit_pick |
Sample the best arm under Thompson Sampling |
agentdb_consolidate |
Run NightlyLearner consolidation pipeline |
agentdb_compose |
Combine memory patterns into a strategy |
agentdb_synthesize |
Build a context window from related memories |
agentdb_explain_recall |
Feature-attributed retrieval results |
agentdb_diversity_rank |
MMR-rerank for diverse top-k |
agentdb_metadata_filter |
Filtered semantic search |
🔗 Used By
AgentDB powers the memory + learning layer in:
| Project | What it uses AgentDB for |
|---|---|
agentic-flow |
ReasoningBank backend, ReflexionMemory, NightlyLearner consolidation, 30+ agent memory namespaces |
ruflo |
Plugin marketplace memory, agent federation audit log, hierarchical recall for /adr-index, swarm coordination patterns |
@ruvector |
Reference downstream for the Rust engine — every release is verified against AgentDB's test suite |
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:
| Target | What | When |
|---|---|---|
| Node native | NAPI bindings (Linux, macOS, Windows; x64 + arm64) | Backend services, CLI, MCP server |
| Node WASM fallback | sql.js + WASM engine | Restricted hosts that can't run NAPI |
| Browser | Pure WASM bundle | Offline-first apps, edge functions, IDE extensions |
| Docker | docker-compose.yml in docker/ |
Local dev, CI, prod deploy |
# Browser
import { createBrowserDb } from 'agentdb/browser';
# Docker
docker compose -f docker/docker-compose.yml up
Documentation
| Doc | When to read it |
|---|---|
| Full README (deep) | Every feature, every API, every option — the complete reference (2,900+ lines) |
| PUBLISHING.md | npm publish flow, dist-tag policy, release verification |
| ADR-071 | WASM integration design |
| ADR-072 | RuVector advanced-feature integration |
| Examples | End-to-end runnable scripts — RAG chatbot, code-review agent, RL training, edge deploy |
| Benchmarks | Reproducible perf harness — HNSW, attention, quantization, RL, end-to-end |
Repository
| 📦 npm | agentdb |
| 🌐 Source | https://github.com/ruvnet/agentdb |
| 🐛 Issues | https://github.com/ruvnet/agentdb/issues |
| 🎨 Marketing site | ui/ (Vite + React + shadcn/ui) |
| 🧬 Engine | @ruvector (Rust + NAPI) |
| 🔗 Reference consumer | agentic-flow (uses this as a git submodule at packages/agentdb/) |
Support
| Resource | Link |
|---|---|
| Documentation | docs/README-full.md |
| Issues & Bugs | GitHub Issues |
| Enterprise | ruv.io |
| Community | Agentics Foundation Discord |
| Engine | ruvector |
| Powered by | Cognitum.one |
License
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/core,@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
Learned memory reranking (3.10)
NeuralReranker learns a small local ruv-FANN scorer from labeled query groups.
It evaluates NDCG and MRR against baseline and active rankings before explicit
promotion. Opt-in neuralRerank queries default to shadow mode, preserving normal
results while exposing scores. Active mode ranks a bounded candidate pool;
revisioned checkpoints support rollback. Ten MCP tools expose training,
evaluation and model management, with admin-only promotion and rollback.
The four versioned inputs are similarity, historical reward, success and recency. Supply independent relevance labels and separate evaluation queries. Included synthetic benchmarks validate the pipeline, not production retrieval quality. Agents can also inspect weights and propose hash-bound WSP edits without training; these candidates must pass the same evaluation gates before promotion.
See the learned memory reranking guide.
Persisted neural models (3.8)
WeightPrograms from agentdb/controllers/WeightPrograms adds durable,
gradient-free weight patches evaluated by real WASM. Caller-authored proposals
are persisted with evaluation evidence; explicit promotion checks stored proposal
identity, generation, hashes and revision. Rollback restores retained checkpoints
as new revisions. Six strict MCP tools expose the workflow with learning/admin
permissions. Acceptance applies to caller-supplied examples and does not prove
generalization. See the weight programs guide.
FannModels from agentdb/controllers/FannModels stores dense ruv-FANN
checkpoints and revisions in your database. It provides real WASM batch inference,
SGD/AdamW training, and bounded prepared-model caching. AgentDB depends on
ruv-fann@0.1.2, which depends on ruv-fann-wasm@0.1.2; no optional native
accelerator is needed for this API.
Six MCP tools (agentdb_neural_create, get, list, predict, train, and
delete, each with the agentdb_neural_ prefix) follow the existing capability
policy. Readonly clients can inspect and predict; learning clients can create
and train; deletion requires admin or an explicit allow. See
the neural-model guide
for usage, persistence semantics and bounded training limits.
AgentDB MCP 질문
AgentDB MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add agentdb -- npx -y agentdb를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
AgentDB MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
Claude Code에 AgentDB를 어떻게 추가하나요?
claude mcp add agentdb -- npx agentdb@latest mcp start를 실행하면 41개의 MCP 도구가 등록됩니다. Claude Code, Cursor, Cline 또는 기타 MCP 호환 클라이언트에서 사용할 수 있습니다.
AgentDB는 몇 개의 MCP 도구를 제공하나요?
AgentDB는 pattern store, search, skill library, reflexion, causal edges, hierarchical recall을 포함한 6개 카테고리에 걸쳐 41개의 MCP 도구를 제공합니다.
AgentDB는 피드백을 통해 어떻게 더 똑똑해지나요?
검색 후 어떤 결과가 유용했는지 피드백을 기록하면, Thompson Sampling bandit이 다음 쿼리를 위해 랭킹, RL 알고리즘 선택 및 압축 티어를 재조정합니다.
AgentDB를 사용하려면 외부 서버나 API 키가 필요한가요?
아니요. 벡터, 인덱스, 학습 상태, 감사 로그를 포함한 모든 데이터가 단일 .rvf 파일에 저장되며 Node, 브라우저 또는 edge runtime에서 오프라인으로 실행됩니다.