AgentDB Vector Search

AgentDB ベクトル検索

このスキルでできること

AgentDB の高性能ベクトルデータベースを使用して、従来のソリューションより150 倍～12,500 倍高速なベクトルベースのセマンティック検索を実装します。HNSW インデックス作成、量子化、サブミリ秒検索（<100µs）に対応しています。

前提条件

• Node.js 18+
• AgentDB v1.0.7+（agentic-flow 経由またはスタンドアロン）
• OpenAI API キー（埋め込み用）またはカスタム埋め込みモデル

CLI でのクイックスタート

ベクトルデータベースの初期化

# Initialize with default dimensions (1536 for OpenAI ada-002)
npx agentdb@latest init .$vectors.db

# Custom dimensions for different embedding models
npx agentdb@latest init .$vectors.db --dimension 768  # sentence-transformers
npx agentdb@latest init .$vectors.db --dimension 384  # all-MiniLM-L6-v2

# Use preset configurations
npx agentdb@latest init .$vectors.db --preset small   # <10K vectors
npx agentdb@latest init .$vectors.db --preset medium  # 10K-100K vectors
npx agentdb@latest init .$vectors.db --preset large   # >100K vectors

# In-memory database for testing
npx agentdb@latest init .$vectors.db --in-memory

ベクトルデータベースへのクエリ

# Basic similarity search
npx agentdb@latest query .$vectors.db "[0.1,0.2,0.3,...]"

# Top-k results
npx agentdb@latest query .$vectors.db "[0.1,0.2,0.3]" -k 10

# With similarity threshold (cosine similarity)
npx agentdb@latest query .$vectors.db "0.1 0.2 0.3" -t 0.75 -m cosine

# Different distance metrics
npx agentdb@latest query .$vectors.db "[...]" -m euclidean  # L2 distance
npx agentdb@latest query .$vectors.db "[...]" -m dot        # Dot product

# JSON output for automation
npx agentdb@latest query .$vectors.db "[...]" -f json -k 5

# Verbose output with distances
npx agentdb@latest query .$vectors.db "[...]" -v

ベクトルのインポート／エクスポート

# Export vectors to JSON
npx agentdb@latest export .$vectors.db .$backup.json

# Import vectors from JSON
npx agentdb@latest import .$backup.json

# Get database statistics
npx agentdb@latest stats .$vectors.db

API でのクイックスタート

import { createAgentDBAdapter, computeEmbedding } from 'agentic-flow$reasoningbank';

// Initialize with vector search optimizations
const adapter = await createAgentDBAdapter({
  dbPath: '.agentdb$vectors.db',
  enableLearning: false,       // Vector search only
  enableReasoning: true,       // Enable semantic matching
  quantizationType: 'binary',  // 32x memory reduction
  cacheSize: 1000,             // Fast retrieval
});

// Store document with embedding
const text = "The quantum computer achieved 100 qubits";
const embedding = await computeEmbedding(text);

await adapter.insertPattern({
  id: '',
  type: 'document',
  domain: 'technology',
  pattern_data: JSON.stringify({
    embedding,
    text,
    metadata: { category: "quantum", date: "2025-01-15" }
  }),
  confidence: 1.0,
  usage_count: 0,
  success_count: 0,
  created_at: Date.now(),
  last_used: Date.now(),
});

// Semantic search with MMR (Maximal Marginal Relevance)
const queryEmbedding = await computeEmbedding("quantum computing advances");
const results = await adapter.retrieveWithReasoning(queryEmbedding, {
  domain: 'technology',
  k: 10,
  useMMR: true,              // Diverse results
  synthesizeContext: true,    // Rich context
});

主な機能

1. ベクトルの保存

// Store with automatic embedding
await db.storeWithEmbedding({
  content: "Your document text",
  metadata: { source: "docs", page: 42 }
});

2. 類似検索

// Find similar documents
const similar = await db.findSimilar("quantum computing", {
  limit: 5,
  minScore: 0.75
});

3. ハイブリッド検索（ベクトル + メタデータ）

// Combine vector similarity with metadata filtering
const results = await db.hybridSearch({
  query: "machine learning models",
  filters: {
    category: "research",
    date: { $gte: "2024-01-01" }
  },
  limit: 20
});

高度な使い方

RAG（検索拡張生成）

// Build RAG pipeline
async function ragQuery(question: string) {
  // 1. Get relevant context
  const context = await db.searchSimilar(
    await embed(question),
    { limit: 5, threshold: 0.7 }
  );

  // 2. Generate answer with context
  const prompt = `Context: ${context.map(c => c.text).join('\n')}
Question: ${question}`;

  return await llm.generate(prompt);
}

バッチ処理

// Efficient batch storage
await db.batchStore(documents.map(doc => ({
  text: doc.content,
  embedding: doc.vector,
  metadata: doc.meta
})));

MCP サーバーとの統合

# Start AgentDB MCP server for Claude Code
npx agentdb@latest mcp

# Add to Claude Code (one-time setup)
claude mcp add agentdb npx agentdb@latest mcp

# Now use MCP tools in Claude Code:
# - agentdb_query: Semantic vector search
# - agentdb_store: Store documents with embeddings
# - agentdb_stats: Database statistics

パフォーマンスのベンチマーク

# Run comprehensive benchmarks
npx agentdb@latest benchmark

# Results:
# ✅ Pattern Search: 150x faster (100µs vs 15ms)
# ✅ Batch Insert: 500x faster (2ms vs 1s for 100 vectors)
# ✅ Large-scale Query: 12,500x faster (8ms vs 100s at 1M vectors)
# ✅ Memory Efficiency: 4-32x reduction with quantization

量子化オプション

AgentDB では、メモリ効率を高めるために複数の量子化方式を利用できます。

バイナリ量子化（32 倍の削減）

const adapter = await createAgentDBAdapter({
  quantizationType: 'binary',  // 768-dim → 96 bytes
});

スカラー量子化（4 倍の削減）

const adapter = await createAgentDBAdapter({
  quantizationType: 'scalar',  // 768-dim → 768 bytes
});

積量子化（8～16 倍の削減）

const adapter = await createAgentDBAdapter({
  quantizationType: 'product',  // 768-dim → 48-96 bytes
});

距離指標

# Cosine similarity (default, best for most use cases)
npx agentdb@latest query .$db.sqlite "[...]" -m cosine

# Euclidean distance (L2 norm)
npx agentdb@latest query .$db.sqlite "[...]" -m euclidean

# Dot product (for normalized vectors)
npx agentdb@latest query .$db.sqlite "[...]" -m dot

高度な機能

HNSW インデックス作成

• O(log n) の検索計算量
• サブミリ秒での検索（<100µs）
• インデックスの自動構築

キャッシュ

• 1000 パターンのインメモリキャッシュ
• <1ms でのパターン検索
• キャッシュの自動無効化

MMR（最大限界関連性）

• 多様な結果セット
• 冗長性の回避
• 関連性と多様性のバランス

パフォーマンスのヒント

1. HNSW インデックス作成を有効にする：AgentDB では自動で有効になり、10～100 倍高速になります
2. 量子化を使用する：バイナリ（32 倍）、スカラー（4 倍）、積（8～16 倍）でメモリを削減できます
3. バッチ処理を使用する：一括挿入が 500 倍高速になります
4. 次元数を合わせる：1536（OpenAI）、768（sentence-transformers）、384（MiniLM）
5. 類似度のしきい値：品質を重視する場合は 0.7 から始め、用途に応じて調整します
6. キャッシュを有効にする：頻繁なクエリには 1000 パターンのキャッシュを使用します

トラブルシューティング

問題：検索パフォーマンスが遅い

# Check if HNSW indexing is enabled (automatic)
npx agentdb@latest stats .$vectors.db

# Expected: <100µs search time

問題：メモリ使用量が多い

# Enable binary quantization (32x reduction)
# Use in adapter: quantizationType: 'binary'

問題：関連性が低い

# Adjust similarity threshold
npx agentdb@latest query .$db.sqlite "[...]" -t 0.8  # Higher threshold

# Or use MMR for diverse results
# Use in adapter: useMMR: true

問題：次元数が正しくない

# Check embedding model dimensions:
# - OpenAI ada-002: 1536
# - sentence-transformers: 768
# - all-MiniLM-L6-v2: 384

npx agentdb@latest init .$db.sqlite --dimension 768

データベースの統計情報

# Get comprehensive stats
npx agentdb@latest stats .$vectors.db

# Shows:
# - Total patterns$vectors
# - Database size
# - Average confidence
# - Domains distribution
# - Index status

パフォーマンス特性

• ベクトル検索：<100µs（HNSW インデックス作成）
• パターン検索：<1ms（キャッシュ使用時）
• バッチ挿入：100 個のベクトルで 2ms
• メモリ効率：量子化により 4～32 倍削減
• スケーラビリティ：100 万個以上のベクトルを効率的に処理
• レイテンシ：ほとんどの処理でサブミリ秒

詳細情報

• GitHub：https:/$github.com$ruvnet$agentic-flow$tree$main$packages$agentdb
• ドキュメント：node_modules$agentic-flow/docs/AGENTDB_INTEGRATION.md
• MCP 統合：Claude Code では npx agentdb@latest mcp を使用します
• ウェブサイト：https:/$agentdb.ruv.io
• CLI ヘルプ：npx agentdb@latest --help
• コマンドのヘルプ：npx agentdb@latest help <command>