A sub-millisecond memory engine built for autonomous agents.

agentdb.md

AgentDB

A sub-millisecond memory engine built for autonomous agents

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.

• Start: npx agenticdb
• Visit: https://agentdb.ruv.io/

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

npm install agentdb

For Claude Desktop / MCP Integration

Add AgentDB as an MCP server in your Claude Desktop config:

{
  "mcpServers": {
    "agentdb": {
      "command": "npx",
      "args": ["agentdb", "mcp"]
    }
  }
}

Available MCP Tools:

• agentdb_init - Initialize vector database
• agentdb_insert / agentdb_insert_batch - Store vectors
• agentdb_search - Semantic search
• agentdb_pattern_store / agentdb_pattern_search - ReasoningBank
• agentdb_stats - Database metrics
• ...and 5 more tools

CLI Usage

# 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)

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:

# Install and configure
npm install -g agentdb
agentdb mcp

Add to ~/Library/Application Support/Claude/claude_desktop_config.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:

# 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:

# 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:

# 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)

// 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)

// 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)

// 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

# Start MCP server
npx agentdb mcp

Add to claude_desktop_config.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

# 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

# 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

# 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

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

// 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

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

// 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

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
• Browser Integration
• MCP Integration

Core Features

• CLI Commands
• ReasoningBank System
• Query Builder
• QUIC Synchronization

Advanced Topics

• Plugin Development
• Performance Optimization
• Distributed Swarms
• Production Deployment

API Reference

• Database API
• ReasoningBank API
• Plugin System

---

🔧 Configuration

AgentDB works out-of-the-box with zero configuration, but offers extensive customization:

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:

# 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
• 💡 Request features
• 🔧 Submit PRs
• 📖 Improve docs
• 🎓 Share examples

Development Setup

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 (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 | Documentation | Examples | GitHub