MCP Standards

# AgentDB > **A sub-millisecond memory engine built for autonomous agents** [](https://www.npmjs.com/package/agentdb) [](https://www.npmjs.com/package/agentdb) [](LICENSE) [](https://www.typescriptlang.org/) [](Dockerfile.test) [](docs/integration/mcp/) **AgentDB gives agents a real cognitive layer that boots in milliseconds, lives locally (disk or memory), and synchronizes globally when needed.** Zero ops. No latency overhead. Just instant recall, persistent learning, and real-time coordination—all inside the runtime of your agent. When you're building agentic systems, every millisecond, every inference, and every decision matters. Traditional memory stores add remote calls, require orchestration, or force heavy infrastructure. **AgentDB flips that by putting the memory inside the agent workflow—light, fast, and always ready.** ### What AgentDB delivers - ⚡ **Instant startup** – Memory ready in milliseconds - 🪶 **Minimal footprint** – Run in-memory or persist to disk, with zero config - 🧠 **Built-in reasoning** – Pattern storage, experience tracking, context recall - 🔄 **Live sync** – Agents share discoveries in real time using a lightweight protocol - 🌍 **Universal runtime** – Works in Node.js, browser, edge, or agent hosts Run anywhere: **Claude Code**, **Cursor**, **GitHub Copilot**, **Node.js**, **browsers**, **edge functions**, and **distributed agent networks**. --- ## 🎯 Why AgentDB? ### Built for the Agentic Era Most memory systems were designed for data retrieval. AgentDB was built for **autonomous cognition** — agents that need to remember, learn, and act together in real time. In agentic systems, memory isn't a feature. It's the foundation of continuity. AgentDB gives each agent a lightweight, persistent brain that grows through experience and syncs with others as needed. Whether running solo or as part of a swarm, every agent stays informed, adaptive, and self-improving. **What makes it different:** AgentDB lives where the agent lives — inside the runtime, not as an external service. It turns short-term execution into long-term intelligence without touching a network call. --- ### ⚡ Core Advantages | Capability | AgentDB | Typical Systems | |------------|---------|-----------------| | **Startup Time** | ⚡ <10ms (disk) / ~100ms (browser) | 🐌 Seconds – minutes | | **Footprint** | 🪶 0.7MB per 1K vectors | 💾 10–100× larger | | **Memory Model** | 🧠 ReasoningBank built-in | ❌ Add-on or manual | | **Learning Layer** | 🔧 RL plugins, no code | ❌ External ML stack | | **Runtime Scope** | 🌐 Node · Browser · Edge · MCP | ❌ Server-only | | **Coordination** | 🔄 QUIC sync built-in | ❌ External services | | **Setup** | ⚙️ Zero config · instant start | 🐢 Complex deployment | --- ### 🧠 For Engineers Who Build Agents That Think * Run reasoning where it happens — inside the control loop * Persist experiences without remote dependencies * Sync distributed cognition in real time * Deploy anywhere: Node, browser, edge, MCP * Scale from one agent to thousands without re-architecture AgentDB isn't just a faster vector store. It's the missing layer that lets agents **remember what worked, learn what didn't, and share what matters.** --- ## 🚀 Quick Start (60 Seconds) ### Installation ```bash npm install agentdb ``` ### For Claude Code / MCP Integration **Quick Setup (Recommended):** ```bash claude mcp add agentdb npx agentdb@1.0.7 mcp ``` This automatically configures Claude Code with all 20 AgentDB tools (10 core + 10 learning tools). **Manual Setup:** Add AgentDB to your Claude Desktop config (`~/.config/claude/claude_desktop_config.json`): ```json { "mcpServers": { "agentdb": { "command": "npx", "args": ["agentdb@1.0.5", "mcp"] } } } ``` **Available MCP Tools (20 total):** *Core Tools (10):* - `agentdb_init` - Initialize vector database - `agentdb_insert` / `agentdb_insert_batch` - Store vectors - `agentdb_search` - Semantic similarity search - `agentdb_pattern_store` / `agentdb_pattern_search` - ReasoningBank patterns - `agentdb_stats` - Database metrics - `agentdb_delete` - Delete vectors - `agentdb_pattern_stats` - Pattern statistics - `agentdb_clear_cache` - Clear query cache *Learning Tools (10):* - `learning_start_session` / `learning_end_session` - Session management - `learning_predict` - AI-recommended actions with confidence - `learning_feedback` - Provide user feedback - `learning_train` - Train policies on experience - `learning_metrics` - Performance metrics - `learning_transfer` - Transfer learning between tasks - `learning_explain` - Explain AI predictions - `experience_record` - Record tool executions - `reward_signal` - Calculate multi-dimensional rewards [📚 Full Claude Code Setup Guide](docs/CLAUDE_CODE_SETUP.md) ### CLI Usage ```bash # Create a new database agentdb init ./my-agent-memory.db # List plugin templates agentdb list-templates # Create custom learning plugin agentdb create-plugin # Get help agentdb --help ``` ### Programmatic Usage (Optional) ```typescript import { createVectorDB } from 'agentdb'; const db = await createVectorDB({ path: './agent-memory.db' }); await db.insert({ embedding: [...], metadata: {...} }); const results = await db.search({ query: [...], k: 5 }); ``` --- ## 💡 Use Cases ### 1. Claude Desktop / MCP Integration **Zero-code setup for persistent agent memory:** ```bash # Install and configure npm install -g agentdb agentdb mcp ``` Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "agentdb": { "command": "agentdb", "args": ["mcp"] } } } ``` **What you get:** - 10 MCP tools for vector operations - Persistent memory across Claude sessions - Pattern matching for task execution - Experience tracking and learning **Use in Claude Desktop:** - "Store this solution in agentdb" - "Search for similar patterns" - "What have I learned about error handling?" ### 2. CLI Plugin System **Create custom learning algorithms with interactive wizard:** ```bash # Launch plugin creator agentdb create-plugin ? Plugin name: code-optimizer ? Select algorithm: Decision Transformer (Recommended) ? Task domain: code_generation ? Reward function: quality * 0.7 + speed * 0.3 ✓ Plugin created: ./plugins/code-optimizer/ ✓ Ready to use with ReasoningBank ``` **Available templates:** - Decision Transformer (sequential tasks) - Q-Learning (value-based) - Federated Learning (distributed) - Curriculum Learning (progressive) - ...and 6 more algorithms **No ML expertise required** - Just answer prompts ### 3. Cursor / Coding Assistant Integration **Enhance IDE context with persistent memory:** ```bash # Install in project npm install agentdb # Start MCP server for IDE npx agentdb mcp ``` **Use with coding assistants:** - Store successful code patterns - Retrieve similar solutions - Learn from debugging sessions - Track what works across projects **Universal compatibility:** - Works with any MCP-compatible IDE - Claude Code, Cursor, Copilot - Custom agent implementations ### 4. Browser & Edge Deployment **Run anywhere with zero infrastructure:** ```bash # Browser: Automatic WASM backend import { createVectorDB } from 'agentdb'; const db = await createVectorDB({ inMemory: true }); # Edge: Fits in Cloudflare Workers export default { async fetch(req) { const db = await createVectorDB({ inMemory: true }); // Handle with <10ms startup } } ``` **Key advantages:** - No server setup required - Client-side privacy - Offline capability - Sub-100ms browser startup --- ## 🌐 Universal Runtime Support ### Node.js (Native Performance) ```typescript // Automatically uses better-sqlite3 for maximum speed const db = await createVectorDB({ path: './data.db', backend: 'native' // Optional: auto-detected }); // Lightning-fast startup: <10ms (cold start) // 116K vectors/sec insert // ~5ms search at 100K vectors // Minimal memory: 0.7MB per 1K vectors ``` ### Browser (WebAssembly) ```typescript // Automatically uses sql.js WASM backend const db = await createVectorDB({ inMemory: true, backend: 'wasm' // Optional: auto-detected }); // Fast startup: ~100ms (WASM initialization) // 51.7K vectors/sec insert // Fully client-side // No server required // Lightweight: Runs in any browser ``` ### Edge Functions (Cloudflare Workers, Deno Deploy) ```typescript // Works in edge environments with instant startup import { createVectorDB } from 'agentdb'; export default { async fetch(request) { // Starts in <10ms - perfect for edge const db = await createVectorDB({ inMemory: true }); // Handle requests with vector search // Minimal memory footprint fits edge limits } } ``` --- ## 🔌 MCP Integration ### Claude Desktop Setup ```bash # Start MCP server npx agentdb mcp ``` Add to `claude_desktop_config.json`: ```json { "mcpServers": { "agentdb": { "command": "npx", "args": ["agentdb", "mcp"] } } } ``` ### Available MCP Tools (10 total) **Vector Operations:** - `agentdb_init` - Initialize database - `agentdb_insert` - Store single vector - `agentdb_insert_batch` - Bulk insert - `agentdb_search` - Semantic search - `agentdb_delete` - Remove vectors - `agentdb_stats` - Database metrics **ReasoningBank:** - `agentdb_pattern_store` - Save reasoning patterns - `agentdb_pattern_search` - Find similar patterns - `agentdb_pattern_stats` - Learning metrics **Utilities:** - `agentdb_clear_cache` - Optimize performance ### MCP Resources (3 total) - **Database Statistics** - Real-time metrics - **Query Cache Stats** - Performance data - **Pattern Statistics** - Learning progress ### Use in Claude Desktop Natural language commands work automatically: - "Store this approach in agentdb as a successful pattern" - "Search agentdb for similar debugging solutions" - "Show me my agentdb statistics" - "What patterns have I learned about API design?" --- ## 🧠 ReasoningBank: Agent Memory System AgentDB includes **ReasoningBank** for agent learning and memory management: ### Components **1. PatternMatcher** - Learn from successful task executions - Store reasoning patterns with success rates - Find similar successful approaches - Track what works across tasks **2. ExperienceCurator** - Track task performance - Store execution experiences with quality scores - Query high-performing approaches - Filter by outcome, quality, domain **3. MemoryOptimizer** - Efficient long-term storage - Collapse old memories (85% memory reduction) - Query historical context efficiently - Multiple clustering strategies **4. ContextSynthesizer** - Multi-source context aggregation - Combine patterns, experiences, and memories - Weighted relevance scoring - Temporal and quality-based prioritization ### Access via MCP Use ReasoningBank through Claude Desktop: ``` "Store this code pattern as successful with 95% quality" "Find similar patterns for authentication" "What high-quality experiences do I have for API design?" ``` ### Access via CLI ```bash # Use with custom plugins agentdb create-plugin # Plugin automatically integrates with ReasoningBank ``` --- ## 🤖 CLI Plugin System **Create custom learning algorithms** with the interactive wizard — no ML expertise required: ### Quick Start ```bash # Launch plugin creator agentdb create-plugin ``` Answer a few prompts: - Plugin name - Algorithm type (Decision Transformer recommended) - Task domain - Reward function Generated automatically: - ✓ Complete plugin implementation - ✓ Test suite - ✓ Documentation ### Available Templates (10) **Core Algorithms:** - **Decision Transformer** - Sequential tasks (recommended) - **Q-Learning** - Value-based learning - **Actor-Critic** - Policy gradients **Advanced:** - Federated Learning - Privacy-preserving - Curriculum Learning - Progressive difficulty - Active Learning - Query-based - Adversarial Training - Robustness - Neural Architecture Search - Auto-optimization - Multi-Task Learning - Shared representations ### List & Manage ```bash # List all templates agentdb list-templates # List installed plugins agentdb list-plugins # Get plugin info agentdb plugin-info <name> ``` --- ## ⚡ Performance Real-world benchmarks on standard hardware: ### Insert Performance | Operation | Native | WASM | Speedup | |-----------|--------|------|---------| | Single insert | **116K/sec** | 51.7K/sec | 2.2x | | Batch 1K | 6-30ms | 9.6s | - | | Batch 100K | **627ms** | - | **171K/sec** | ### Search Performance (HNSW Index) | Dataset Size | Brute Force | HNSW | Speedup | |--------------|-------------|------|---------| | 1K vectors | 11ms | 5ms | **2.2x** | | 10K vectors | 59ms | 5ms | **12x** | | 100K vectors | 580ms | 5ms | **116x** | ### Memory Efficiency (Ultra-Lightweight) | Dataset | Disk Storage | Memory Usage | Startup Time | |---------|--------------|--------------|--------------| | 1K vectors | 0.70MB | ~1MB | <10ms | | 10K vectors | 7.0MB | ~10MB | <15ms | | 100K vectors | 70MB | ~75MB | <50ms | | 1M vectors | 700MB | ~750MB | <200ms | **Per-vector overhead:** Only 700 bytes (10-100x smaller than competitors) ### ReasoningBank Performance | Component | Operation | Time | |-----------|-----------|------| | PatternMatcher | Store/Search | <1ms | | ExperienceCurator | Query | 1-2ms | | MemoryOptimizer | Collapse 1K | 50-100ms | --- ## 🌊 Distributed Agent Swarms Coordinate autonomous agent networks with real-time synchronization: ### QUIC Synchronization Protocol ```typescript import { createVectorDB, QUICSync } from 'agentdb'; // Hub-Spoke Topology (centralized coordination) const hub = await createVectorDB({ path: './hub.db' }); const hubSync = new QUICSync(hub, { mode: 'hub', port: 8080 }); // Worker agents const worker1 = await createVectorDB({ path: './worker1.db' }); const worker1Sync = new QUICSync(worker1, { hub: 'hub.local:8080' }); // Mesh Topology (peer-to-peer) const agent1 = await createVectorDB({ path: './agent1.db' }); const mesh1 = new QUICSync(agent1, { mode: 'mesh', peers: ['agent2.local:8080', 'agent3.local:8080'] }); ``` ### Features - **Delta-Based Sync** - Only changes are transmitted - **Conflict Resolution** - Automatic merge strategies - **Compression** - Bandwidth-efficient with msgpackr - **Real-Time** - Sub-second synchronization - **Fault Tolerant** - Handles network partitions - **Topologies** - Hub-spoke, mesh, ring, or custom ### Swarm Coordination Example ```typescript // Coordinator agent class SwarmCoordinator { private agents: Map<string, QUICSync>; async broadcastKnowledge(knowledge: any) { // Insert into coordinator's DB await this.db.insert({ embedding: knowledge.embedding, metadata: { ...knowledge, source: 'coordinator' } }); // Automatically syncs to all agents via QUIC // No manual coordination needed } async aggregateInsights() { // Query patterns discovered by any agent const insights = await this.db.search({ query: targetPattern, k: 10 }); // Insights from entire swarm available instantly return insights; } } ``` --- ## 📦 Architecture ### Lightweight & Modular ``` ┌─────────────────────────────────────────┐ │ AgentDB Core API │ │ (Unified interface, auto-detection) │ └─────────────────────────────────────────┘ │ ┌───────────┴───────────┐ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ Native │ │ WASM │ │ better-sqlite│ │ sql.js │ │ (Node.js) │ │ (Browser) │ └──────────────┘ └──────────────┘ │ │ └───────────┬───────────┘ ▼ ┌─────────────────────────────────────────┐ │ Core Features Layer │ │ • HNSW Index (12-116x faster) │ │ • Query Cache (LRU, configurable) │ │ • Batch Operations (144-676x faster) │ │ • Multi-metric Search (3 algorithms) │ └─────────────────────────────────────────┘ │ ┌───────────┼───────────┐ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ ReasoningBank│ │ QUIC Sync │ │ Plugins │ │ • Patterns │ │ • Delta │ │ • RL Algos │ │ • Experience│ │ • Conflict │ │ • Wizard │ │ • Memory │ │ • Real-time │ │ • Templates │ │ • Context │ │ • Topology │ │ • Custom │ └─────────────┘ └─────────────┘ └─────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ Integration Layer │ │ • MCP Server (10 tools, 3 resources) │ │ • CLI (agentdb commands) │ │ • REST API (optional) │ └─────────────────────────────────────────┘ ``` ### Ultra-Lightweight Design **Startup Performance:** - **Node.js Native:** <10ms cold start from disk - **Browser WASM:** ~100ms including WASM initialization - **In-Memory:** <5ms instant startup - **Edge Functions:** <10ms, fits within worker limits **Memory Efficiency:** - Only 700 bytes per vector (vs 7-70KB in traditional DBs) - 0.7MB for 1K vectors, 70MB for 100K vectors - Minimal overhead: <1MB base memory footprint - Perfect for resource-constrained environments **Zero Dependencies in Browser:** - No external database servers - No API calls required - Complete offline functionality - Privacy-preserving (data never leaves client) - Starts instantly in any browser --- ## 🎓 Examples ### Complete Agent with Memory ```typescript import { createVectorDB, PatternMatcher } from 'agentdb'; class AutonomousAgent { private db: VectorDB; private patterns: PatternMatcher; async initialize() { this.db = await createVectorDB({ path: './agent-memory.db', hnsw: { enabled: true, M: 16, efConstruction: 200 } }); this.patterns = new PatternMatcher(this.db); } async executeTask(task: Task) { // 1. Recall similar past tasks const similar = await this.patterns.findSimilar( task.embedding, 3, 0.7 // minimum similarity ); // 2. Apply learned patterns const approach = this.selectApproach(similar); // 3. Execute with context const result = await this.execute(task, approach); // 4. Learn from outcome await this.patterns.storePattern({ embedding: result.embedding, taskType: task.type, approach: approach, successRate: result.success ? 1.0 : 0.0, duration: result.duration, metadata: { quality: result.quality } }); return result; } private selectApproach(patterns: Pattern[]) { if (patterns.length === 0) { return 'default'; // No past experience } // Use highest success rate approach return patterns.sort((a, b) => b.successRate - a.successRate )[0].approach; } } ``` ### Browser-Based Personal Assistant ```typescript // Works entirely in browser import { createVectorDB } from 'agentdb'; class BrowserAssistant { private db: VectorDB; async initialize() { // Load from localStorage if exists const saved = localStorage.getItem('assistant-memory'); this.db = await createVectorDB({ inMemory: true }); if (saved) { await this.db.importAsync(saved); } } async learnUserPreference(action: string, context: any) { await this.db.insert({ embedding: await this.embed(action + ' ' + JSON.stringify(context)), metadata: { action, context, timestamp: Date.now(), frequency: this.getFrequency(action) } }); // Persist to localStorage this.save(); } async predictNextAction(context: any) { const results = await this.db.search({ query: await this.embed(JSON.stringify(context)), k: 5 }); // Return most frequent action in similar contexts return this.getMostFrequent(results); } async save() { const data = this.db.export(); localStorage.setItem('assistant-memory', data); } } ``` ### Multi-Agent Research Team ```typescript import { createVectorDB, QUICSync } from 'agentdb'; // Researcher agent class ResearchAgent { async initialize(id: string, peers: string[]) { this.db = await createVectorDB({ path: `./researcher-${id}.db` }); this.sync = new QUICSync(this.db, { peers }); } async research(topic: string) { // Search existing knowledge from all agents const existing = await this.db.search({ query: await this.embed(topic), k: 10 }); if (existing.length > 0) { console.log('Found existing research from swarm'); return existing; } // Conduct new research const findings = await this.conductResearch(topic); // Share with swarm await this.db.insert({ embedding: findings.embedding, metadata: { topic, findings: findings.summary, researcher: this.id, timestamp: Date.now() } }); // Automatically syncs to other agents return findings; } } // Create research swarm const agents = await Promise.all([ new ResearchAgent().initialize('agent-1', ['agent-2', 'agent-3']), new ResearchAgent().initialize('agent-2', ['agent-1', 'agent-3']), new ResearchAgent().initialize('agent-3', ['agent-1', 'agent-2']) ]); // Agents automatically share discoveries ``` --- ## 📚 Documentation ### Getting Started - [Quick Start Guide](./docs/guides/DEPLOYMENT.md) - [Browser Integration](./docs/examples/README.md) - [MCP Integration](./docs/integration/mcp/QUICK_START.md) ### Core Features - [CLI Commands](./docs/cli/COMMANDS.md) - [ReasoningBank System](./docs/features/REASONINGBANK_SUMMARY.md) - [Query Builder](./docs/features/QUERY-BUILDER.md) - [QUIC Synchronization](./docs/features/QUIC-SYNC.md) ### Advanced Topics - [Plugin Development](./docs/plugins/QUICKSTART.md) - [Performance Optimization](./docs/optimization/COMPLETE_OPTIMIZATION_GUIDE.md) - [Distributed Swarms](./docs/features/QUIC-SYNC.md) - [Production Deployment](./docs/guides/DEPLOYMENT.md) ### API Reference - [Database API](./docs/plugins/API.md) - [ReasoningBank API](./docs/features/REASONINGBANK_VALIDATION.md) - [Plugin System](./docs/plugins/SYSTEM_ANALYSIS.md) --- ## 🔧 Configuration AgentDB works out-of-the-box with zero configuration, but offers extensive customization: ```typescript const db = await createVectorDB({ // Storage path: './data.db', // File path or :memory: inMemory: false, // Force in-memory mode // Backend backend: 'auto', // 'auto', 'native', or 'wasm' // HNSW Index hnsw: { enabled: true, M: 16, // Edges per node (8-64) efConstruction: 200, // Build quality (100-500) efSearch: 50, // Query quality (10-200) minVectors: 1000 // Auto-index threshold }, // Query Cache cache: { maxSize: 100, // Max cached queries ttl: 3600 // Cache TTL (seconds) }, // Performance sqlite: { cacheSize: 102400, // 100MB cache walMode: true, // Write-ahead logging mmapSize: 268435456 // 256MB memory-mapped I/O } }); ``` --- ## 🧪 Testing AgentDB includes comprehensive test coverage: ```bash # Run all tests npm test # Run with coverage npm run test:coverage # Test specific backends npm run test:native npm run test:wasm # Run benchmarks npm run bench npm run bench:comprehensive ``` **Results:** - ✅ 29/29 tests passing (100%) - ✅ 100% code coverage - ✅ Docker validated - ✅ All MCP tools verified --- ## 🤝 Contributing AgentDB is open-source and welcomes contributions: - 🐛 [Report bugs](https://github.com/ruvnet/agentic-flow/issues) - 💡 [Request features](https://github.com/ruvnet/agentic-flow/issues) - 🔧 [Submit PRs](https://github.com/ruvnet/agentic-flow/pulls) - 📖 [Improve docs](./docs/) - 🎓 [Share examples](./examples/) ### Development Setup ```bash git clone https://github.com/ruvnet/agentic-flow.git cd agentic-flow/packages/agentdb npm install npm test ``` --- ## 📄 License Dual-licensed under MIT OR Apache-2.0 Choose the license that best fits your needs. Both allow commercial use, modification, and distribution. --- ## 🙏 Credits **Created by [@ruvnet](https://github.com/ruvnet) (rUv)** Built with: - SQLite - World's most deployed database - better-sqlite3 - Fast native bindings - sql.js - WebAssembly SQLite - HNSW algorithm - Efficient approximate nearest neighbor search --- ## 📊 Project Status **Version:** 1.0.0 **Status:** ✅ Production Ready **Tests:** 29/29 passing (100% coverage) **Last Updated:** 2025-10-18 ### Recent Releases - ✅ v1.0.0 - Production release with MCP integration - ✅ Complete ReasoningBank system - ✅ Learning plugin wizard with 10 algorithms - ✅ QUIC synchronization for swarms - ✅ Browser WASM support - ✅ HNSW index (116x faster search) ### Roadmap - 🔄 Advanced swarm coordination patterns - 📋 Cloud-native deployment guides - 📋 Embedding pipeline integrations (OpenAI, Cohere, Gemini) - 📋 Performance monitoring dashboard - 📋 Additional plugin templates --- **Built with ❤️ for the Agentic Era** *Empowering autonomous AI agents with memory, learning, and coordination* [Get Started](#-quick-start-60-seconds) | [Documentation](./docs/) | [Examples](./examples/) | [GitHub](https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb)