fusionpact-vectordb

⚡ FusionPact

エージェントネイティブな検索エンジン

AI エージェント向けの、ベクトル検索＋推論＋メモリ

類似性 ≠ 関連性。 FusionPact は、HNSW ベクトル検索、推論ベースのツリー検索、エージェントメモリを単一のプラットフォームに統合した初の検索エンジンです。AI エージェントとマルチエージェントシステム専用に設計されています。

クイックスタート · ハイブリッド検索 · エージェントメモリ · マルチエージェント · MCP サーバー · ツリーインデックス · RAG パイプライン · API リファレンス · ベンチマーク · コントリビューション

---

FusionPact を選ぶ理由

従来のベクトルデータベースは類似した情報を検索します。しかし、類似性は関連性とは異なります。ベクトル DB に「2024 年第 3 四半期の売上高」を問い合わせると、第 2 四半期や第 4 四半期のデータが返されることがあります。意味的には類似していますが、答えが間違っています。

FusionPact は、3 つの検索方式を組み合わせることでこの問題を解決します。

戦略	仕組み	最適な用途
ベクトル検索（HNSW）	埋め込みの類似度、O(log N)	大規模なコレクションを横断する幅広い検索
ツリー推論	LLM がドキュメント構造をたどる	構造化ドキュメント内の正確な検索
キーワード検索（BM25）	用語頻度の照合	完全一致が必要な場合

さらに、エージェントメモリ、マルチエージェントオーケストレーション、MCP サーバーを専用機能として備えています。すべて依存関係ゼロ、ローカル優先、無料です。

┌──────────────────────────────────────────────────────────┐
│             FusionPact Retrieval Engine                   │
│                                                          │
│  ┌────────────┐  ┌─────────────┐  ┌────────────────┐   │
│  │ Vector     │  │ Tree        │  │ Keyword        │   │
│  │ (HNSW)     │  │ (Reasoning) │  │ (BM25)         │   │
│  └─────┬──────┘  └──────┬──────┘  └───────┬────────┘   │
│        └────────────┬────┴─────────────────┘            │
│                     ▼                                    │
│           Reciprocal Rank Fusion                         │
│                     ▼                                    │
│  ┌──────────────────────────────────────────────────┐   │
│  │        Agent Memory (Multi-Agent)                │   │
│  │  Episodic │ Semantic │ Procedural │ Shared       │   │
│  └──────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────┐   │
│  │        MCP Server (Claude, Cursor, etc.)         │   │
│  └──────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────┘

---

⚡ クイックスタート

# Install
npm install fusionpact

# Run the demo
npx fusionpact demo

# Start HTTP + MCP server
npx fusionpact serve --port 8080

# Start MCP server for Claude Desktop
npx fusionpact mcp

10 行のコード

const { create } = require('fusionpact');

const fp = create({ embedder: 'ollama' }); // or 'mock' for zero-config

// Ingest a document — auto-chunks, embeds, indexes
await fp.rag.ingest('Your document text here...', { source: 'doc.pdf' });

// Hybrid search — vector + reasoning + keyword, fused automatically
const results = await fp.retriever.retrieve('What safety protocols exist?', {
  collection: 'default',
  strategy: 'hybrid'
});

// Or build LLM-ready context directly
const context = await fp.rag.buildContext('What safety protocols exist?');
console.log(context.prompt); // Ready to paste into any LLM

---

🔀 ハイブリッド検索エンジン

中核となる差別化要因は、複数の検索戦略を通じてクエリをインテリジェントに振り分け、逆順位融合を使って結果を統合する単一の API です。

const { create } = require('fusionpact');

const fp = create({
  embedder: 'ollama',        // Local, free, private
  llmProvider: 'ollama',     // For tree reasoning
  enableHybrid: true
});

// Index a structured document with tree structure
await fp.treeIndex.indexDocument('annual-report', reportText, {
  format: 'markdown'
});

// Hybrid retrieval — automatically uses the best strategy
const results = await fp.retriever.retrieve(
  'What were the total deferred tax assets in Q3?',
  {
    collection: 'documents',       // Vector search here
    docId: 'annual-report',        // Tree reasoning here
    topK: 5,
    strategy: 'hybrid'            // Fuse all strategies
  }
);

// Each result includes:
// - score: Fused relevance score
// - content: Retrieved text
// - sources: Which strategies contributed { vector: 0.8, tree: 0.9, keyword: 0.3 }
// - citation: "Section 3 > Financial Data > Table 3.2.1"
// - reasoning: Full tree traversal reasoning trace

戦略の重み

const retriever = new HybridRetriever({
  engine, treeIndex, embedder,
  weights: {
    vector: 0.4,   // 40% weight to vector similarity
    tree: 0.4,     // 40% weight to reasoning-based retrieval
    keyword: 0.2   // 20% weight to keyword matching
  }
});

適応的学習

FusionPact は、さまざまなクエリパターンでどの検索戦略が最も効果的かを学習します。

// Record feedback on result quality
retriever.recordFeedback('financial query', 'tree', 0.95);
retriever.recordFeedback('general search', 'vector', 0.85);

// Get recommended weights for a new query
const weights = retriever.getAdaptiveWeights('new financial query');
// → { vector: 0.25, tree: 0.6, keyword: 0.15 }

---

🌲 ツリーインデックス

構造化ドキュメント向けの推論ベースの検索です。階層ツリー（インテリジェントな目次のようなもの）を構築し、LLM の推論を利用して最も関連性の高いセクションをたどります。

const { TreeIndex, LLMProvider } = require('fusionpact');

const llm = new LLMProvider({ provider: 'ollama' }); // Free, local
const tree = new TreeIndex({ llmProvider: llm });

// Index a document
await tree.indexDocument('sec-filing', filingText, {
  format: 'markdown',
  metadata: { source: '10-K', year: 2024 }
});

// Reasoning-based search
const results = await tree.search('sec-filing', 'Total deferred tax assets', {
  maxResults: 3,
  includeReasoning: true
});

// results[0]:
// {
//   content: "Table 5.2: Deferred Tax Assets...",
//   relevanceScore: 0.95,
//   citation: "Financial Statements > Note 5 > Tax Assets > Table 5.2",
//   reasoningPath: [
//     { title: "Financial Statements", reasoning: "Deferred tax assets are in financial notes", action: "explore" },
//     { title: "Note 5: Income Taxes", reasoning: "This note covers tax-related assets", action: "explore" },
//     { title: "Table 5.2", reasoning: "Contains the deferred tax asset breakdown", action: "retrieve" }
//   ]
// }

LLM がなくても動作

LLM プロバイダーが設定されていない場合、TreeIndex はキーワードベースのツリー走査にフォールバックします。推論経路は使えませんが、それでも役立ちます。

const tree = new TreeIndex(); // No LLM — keyword fallback
await tree.indexDocument('doc', text, { format: 'markdown' });
const results = await tree.search('doc', 'safety protocols');

---

🧠 エージェントメモリ

AI エージェント向けに特化した、4 種類のメモリを備えるメモリシステムです。

メモリの種類	保存する内容	例
エピソード	出来事、会話、観察	「ユーザーが Lab B の化学物質保管について質問した」
セマンティック	事実、ドメイン知識、学習した情報	「OSHA 1910.106 は可燃性液体を対象としている」
手続き	ツールスキーマ、API 仕様、ワークフロー	search_incidents ツールの定義
共有	エージェント間で共有する知識プール	「顧客 ACME は ISO 14001 を希望している」

const { create } = require('fusionpact');
const fp = create({ embedder: 'ollama', enableMemory: true });

// Episodic — remember what happened
await fp.memory.remember('agent-1', {
  content: 'User prefers dark mode and concise answers',
  role: 'system',
  importance: 0.8
});

// Semantic — learn knowledge
await fp.memory.learn('agent-1',
  'OSHA 29 CFR 1910 covers general industry safety standards.',
  { source: 'regulations', category: 'compliance' }
);

// Procedural — register tools
await fp.memory.registerTool('agent-1', {
  name: 'search_incidents',
  description: 'Search EHS incident reports by category and severity',
  schema: { type: 'object', properties: { severity: { type: 'string' } } }
});

// Recall — cross-memory search
const memories = await fp.memory.recall('agent-1', 'safety compliance');
// → { episodic: [...], semantic: [...], procedural: [...], shared: [...] }

// Conversation memory
fp.memory.addMessage('agent-1', 'thread-001', { role: 'user', content: 'What are the PPE requirements?' });
fp.memory.addMessage('agent-1', 'thread-001', { role: 'assistant', content: 'PPE requirements include...' });
const history = fp.memory.getConversation('agent-1', 'thread-001');

// GDPR-friendly forget
fp.memory.forget('agent-1', { type: 'all' });

---

🤖 マルチエージェントオーケストレーション

メモリの分離、知識の共有、メッセージのルーティングにより、複数の AI エージェントを連携させます。

const { create, AgentOrchestrator } = require('fusionpact');

const fp = create({ embedder: 'ollama', enableMemory: true });
const orchestrator = new AgentOrchestrator({
  engine: fp.engine,
  memory: fp.memory,
  retriever: fp.retriever
});

// Register agents
orchestrator.registerAgent({
  agentId: 'researcher',
  name: 'Research Agent',
  role: 'Find and analyze information',
  capabilities: ['search', 'analysis', 'summarization']
});

orchestrator.registerAgent({
  agentId: 'writer',
  name: 'Writing Agent',
  role: 'Generate reports and documentation',
  capabilities: ['writing', 'formatting', 'editing']
});

// Agent-to-agent communication
await orchestrator.send({
  from: 'researcher',
  to: 'writer',
  type: 'result',
  payload: { findings: 'Safety incidents decreased 12% YoY...' }
});

// Capability-based task delegation
await orchestrator.delegate('coordinator', 'Write a safety summary report', {
  requiredCapabilities: ['writing', 'formatting']
});
// → Automatically routes to 'writer' agent

// Collaborative retrieval across all agents
const results = await orchestrator.collaborativeRecall('safety compliance');
// → Returns memories from all agents, plus shared knowledge

// Message handling
orchestrator.onMessage('writer', async (msg) => {
  console.log(`Writer received: ${msg.type} from ${msg.from}`);
  // Process task...
});

---

🔌 MCP サーバー

FusionPact は MCP（Model Context Protocol）サーバーとして提供されます。どの AI エージェント（Claude、Cursor、Windsurf）でも、カスタム統合なしで永続メモリとして利用できます。

Claude Desktop の設定

~/Library/Application Support/Claude/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "fusionpact": {
      "command": "npx",
      "args": ["fusionpact", "mcp"],
      "env": {
        "EMBEDDING_PROVIDER": "ollama"
      }
    }
  }
}

利用可能な MCP ツール

ツール	説明
fusionpact_create_collection	HNSW インデックス付きベクターコレクションを作成
fusionpact_search	セマンティックベクター検索
fusionpact_hybrid_search	ハイブリッド検索（ベクター＋ツリー＋キーワード）
fusionpact_rag_ingest	ワンクリックで RAG データを取り込み
fusionpact_rag_query	LLM 用のコンテキストを構築
fusionpact_memory_remember	エピソード記憶を保存
fusionpact_memory_recall	関連する記憶を呼び出し
fusionpact_memory_learn	セマンティック知識を追加
fusionpact_memory_share	エージェント間で知識を共有
fusionpact_memory_forget	GDPR 準拠の記憶消去
fusionpact_memory_conversation	会話スレッドを管理

---

📄 RAG パイプライン

1 回の呼び出しでエンドツーエンドの RAG を実行します。

const fp = require('fusionpact').create({ embedder: 'ollama' });

// Ingest — auto-chunks, embeds, indexes
await fp.rag.ingest(documentText, {
  source: 'safety-manual.pdf',
  title: 'Safety Manual 2024'
});

// Build context for any LLM
const ctx = await fp.rag.buildContext('What PPE is required?', {
  topK: 5,
  maxTokens: 4000,
  strategy: 'hybrid'  // Uses HybridRetriever if available
});

// ctx.prompt → Ready for any LLM
// ctx.sources → Source citations
// ctx.chunks → Number of chunks used

チャンク化戦略

const rag = new RAGPipeline(engine, {
  chunkStrategy: 'recursive',  // 'recursive' | 'sentence' | 'paragraph'
  chunkSize: 512,
  chunkOverlap: 50
});

---

🔒 マルチテナント

ゼロトラストのソフト分離により、テナント同士が互いのデータを見ることはできません。

const tenantA = engine.tenant('shared-collection', 'acme_corp');
const tenantB = engine.tenant('shared-collection', 'globex_inc');

tenantA.insert([{ id: 'doc-1', vector: [...], metadata: { doc: 'Acme Plan' } }]);

// Tenant A queries — only sees Acme data. Always.
const results = tenantA.search(queryVec, { topK: 10 });

---

🔌 埋め込みプロバイダー

プロバイダー	セットアップ	次元数	コスト
Ollama（推奨）	ollama pull nomic-embed-text	768	無料
OpenAI	OPENAI_API_KEY を設定	1536	約 $0.02／100 万トークン
Mock（テスト用）	不要	64	無料

// Ollama (local, free, private)
const fp = create({ embedder: 'ollama' });

// OpenAI
const fp = create({ embedder: 'openai', openaiConfig: { apiKey: 'sk-...' } });

// Mock (for demos/testing — no dependencies)
const fp = create({ embedder: 'mock' });

---

📊 ベンチマーク

HNSW のパフォーマンス（128D ベクター）

ベクター数	挿入	検索（p50）	QPS
1,000	15ms	0.2ms	約 5,000
10,000	180ms	0.3ms	約 3,300
100,000	2.8s	0.5ms	約 2,000

独自に実行するには：

npx fusionpact bench --count 10000

---

🆚 比較

機能	FusionPact	PageIndex	Pinecone	Chroma	Qdrant
ハイブリッド検索（ベクター＋ツリー＋キーワード）	✅	❌	❌	❌	❌
推論ベースのツリーインデックス	✅	✅	❌	❌	❌
エージェントメモリーアーキテクチャ	✅	❌	❌	❌	❌
マルチエージェントオーケストレーション	✅	❌	❌	❌	❌
MCP サーバー（エージェントネイティブ）	✅	✅	❌	❌	❌
ワンクリック RAG	✅	❌	❌	❌	❌
マルチテナント	✅	❌	✅	❌	✅
ローカルファースト／ゼロコスト	✅	✅	❌	✅	✅
HNSW ベクターインデックス	✅	❌	✅	✅	✅
依存関係ゼロ	✅	❌	❌	❌	❌

---

📖 API リファレンス

詳細なドキュメントはこちら：docs/API.md

コアクラス

クラス	説明
FusionEngine	コアデータベースエンジン、コレクション管理、CRUD
HNSWIndex	HNSW 近似最近傍インデックス
TreeIndex	推論検索用の階層型ドキュメントインデックス
HybridRetriever	順位融合による複数戦略の検索
AgentMemory	複数の種類に対応したエージェントメモリーシステム
AgentOrchestrator	マルチエージェント調整レイヤー
RAGPipeline	エンドツーエンドの RAG パイプライン
MCPServer	Model Context Protocol サーバー
OllamaEmbedder	Ollama 埋め込みプロバイダー
OpenAIEmbedder	OpenAI 埋め込みプロバイダー
MockEmbedder	テスト／デモ用埋め込みプロバイダー
LLMProvider	複数プロバイダー対応の LLM インターフェース

---

🗺 ロードマップ

• M／ef パラメーターを設定可能な HNSW インデックス
• ソフト分離によるマルチテナント
• ワンクリック RAG パイプライン
• エージェントメモリー（エピソード記憶、セマンティック記憶、手続き記憶、共有記憶）
• マルチエージェントオーケストレーション
• ツリーインデックス（推論ベースの検索）
• ハイブリッドリトリーバー（ベクター＋ツリー＋キーワードの融合）
• MCP サーバー（stdio＋HTTP）
• HTTP API サーバー
• Ollama および OpenAI の埋め込みプロバイダー
• 適応型検索学習
• SQLite／PostgreSQL の永続化
• Python SDK（pip install fusionpact）
• LangChain 統合
• LlamaIndex 統合
• CrewAI／AutoGen 統合
• Vision RAG（PDF ページ画像）
• Rust コア（NAPI バインディング）
• FusionPact Cloud（マネージドホスティング）
• ダッシュボード UI

---

🤝 コントリビューション

コントリビューションを歓迎します！ガイドラインについてはCONTRIBUTING.mdをご覧ください。

git clone https://github.com/FusionpactTech/fusionpact-vectordb.git
cd fusionpact-vectordb
npm install
npm test
npx fusionpact demo

---

📜 著作権表示

FusionPact は FusionPact Technologies Inc. が開発・保守しています。

プロジェクトで FusionPact を使用する場合は、次のいずれかの方法で著作権表示を含めてください。

• アプリケーションの概要ページまたはドキュメントに「Powered by FusionPact」を含める
• 配布物に NOTICE ファイルを含める
• プロジェクトの謝辞に FusionPact Technologies Inc. を記載する

詳細は ATTRIBUTION.md をご覧ください。

ライセンス

Apache 2.0 — 商用プロジェクトおよびオープンソースプロジェクトで自由にご利用いただけます。

Apache 2.0 ライセンスでは、次のことが求められます。

1. 再配布する際は、ライセンスのコピーを含めること
2. FusionPact Technologies Inc. の著作権表示を記載した NOTICE ファイルを含めること
3. コードに加えた重要な変更を明記すること

---

FusionPact Technologies Inc. が ❤️ を込めて開発

役に立ったら、このリポジトリに ⭐ を付けてください！