agentdb 1.0.0

package/README.md

@@ -0,0 +1,953 @@
+# AgentDB
+
+> **A sub-millisecond memory engine built for autonomous agents**
+
+[![npm version](https://img.shields.io/npm/v/agentdb.svg?style=flat-square)](https://www.npmjs.com/package/agentdb)
+[![npm downloads](https://img.shields.io/npm/dm/agentdb.svg?style=flat-square)](https://www.npmjs.com/package/agentdb)
+[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-green?style=flat-square)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
+[![Tests](https://img.shields.io/badge/tests-29%2F29%20passing-brightgreen?style=flat-square)](Dockerfile.test)
+[![MCP Compatible](https://img.shields.io/badge/MCP-10%20tools%20%7C%203%20resources-blueviolet?style=flat-square)](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 Desktop / MCP Integration
+
+Add AgentDB as an MCP server in your Claude Desktop config:
+
+```json
+{
+  "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
+
+```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)