fusionpact-vectordb

⚡ FusionPact

面向 Agent 的检索引擎

为 AI Agent 提供向量检索 + 推理 + 记忆

相似 ≠ 相关。 FusionPact 是首个将 HNSW 向量搜索、基于推理的树检索和 Agent 记忆整合到单一平台的检索引擎，专为 AI Agent 和多 Agent 系统打造。

快速开始 · 混合检索 · Agent 记忆 · 多 Agent · MCP 服务 · 树索引 · RAG 流水线 · API 参考 · 基准测试 · 贡献

---

为什么选择 FusionPact？

传统向量数据库检索的是相似内容。但相似 ≠ 相关。向向量数据库查询“2024 年第三季度收入”，你可能会得到第二季度或第四季度的数据——语义相似，却是错误答案。

FusionPact 通过结合三种检索范式解决这一问题：

策略	工作原理	最适用场景
向量搜索（HNSW）	嵌入相似度，O(log N)	在大型集合中进行广泛搜索
树推理	大模型导航文档结构	在结构化文档中精准检索
关键词搜索（BM25）	词频匹配	需要精确匹配的场景

此外还提供专为 Agent 记忆、多 Agent 编排和 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 智能地将查询路由到多种检索策略，并使用倒数排名融合（Reciprocal Rank Fusion）合并结果。

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 }

---

🌲 树索引

面向结构化文档的推理式检索。构建分层树（如同智能目录），并利用大模型推理导航至最相关的章节。

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" }
//   ]
// }

无需大模型也能使用

如果未配置大模型提供商，TreeIndex 会回退到基于关键词的树遍历——依然有用，只是不会采用推理路径：

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

---

🧠 Agent 记忆

专为 AI Agent 打造的记忆系统，包含四种记忆类型：

记忆类型	存储内容	示例
情景记忆	事件、对话、观察	“用户询问了 B 实验室的化学品存储”
语义记忆	事实、领域知识、学习到的信息	“OSHA 1910.106 涵盖易燃液体”
程序记忆	工具架构、API 规范、工作流	search_incidents 工具定义
共享记忆	跨 Agent 知识池	“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' });

---

🤖 多 Agent 编排

通过隔离的记忆、共享知识和消息路由来协调多个 AI Agent：

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 Agent（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	构建适用于大模型的上下文
fusionpact_memory_remember	存储情景记忆
fusionpact_memory_recall	回忆相关记忆
fusionpact_memory_learn	添加语义知识
fusionpact_memory_share	共享跨 Agent 知识
fusionpact_memory_forget	类 GDPR 的记忆擦除
fusionpact_memory_conversation	管理对话线程

---

📄 RAG 流水线

一次调用即可完成端到端 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/百万个 token
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
混合检索（向量 + 树 + 关键词）	✅	❌	❌	❌	❌
基于推理的树索引	✅	✅	❌	❌	❌
Agent 记忆架构	✅	❌	❌	❌	❌
多 Agent 编排	✅	❌	❌	❌	❌
MCP 服务（原生支持 Agent）	✅	✅	❌	❌	❌
一键式 RAG	✅	❌	❌	❌	❌
多租户	✅	❌	✅	❌	✅
本地优先 / 零成本	✅	✅	❌	✅	✅
HNSW 向量索引	✅	❌	✅	✅	✅
零依赖	✅	❌	❌	❌	❌

---

📖 API 参考

完整文档：docs/API.md

核心类

类	描述
FusionEngine	核心数据库引擎、集合管理和 CRUD
HNSWIndex	HNSW 近似最近邻索引
TreeIndex	用于推理检索的分层文档索引
HybridRetriever	使用排名融合的多策略检索
AgentMemory	多类型 Agent 记忆系统
AgentOrchestrator	多 Agent 协调层
RAGPipeline	端到端 RAG 流水线
MCPServer	模型上下文协议服务
OllamaEmbedder	Ollama 嵌入提供方
OpenAIEmbedder	OpenAI 嵌入提供方
MockEmbedder	用于测试和演示的嵌入器
LLMProvider	多提供方大模型接口

---

🗺 路线图

• 支持可配置 M/ef 参数的 HNSW 索引
• 采用软隔离的多租户
• 一键式 RAG 流水线
• Agent 记忆（情景、语义、程序性、共享）
• 多 Agent 编排
• 树索引（基于推理的检索）
• 混合检索器（向量 + 树 + 关键词融合）
• MCP 服务（stdio + HTTP）
• HTTP API 服务
• Ollama + OpenAI 嵌入提供方
• 自适应检索学习
• SQLite/PostgreSQL 持久化
• Python SDK（pip install fusionpact）
• LangChain 集成
• LlamaIndex 集成
• CrewAI / AutoGen 集成
• 视觉 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. 倾心打造 ❤️

如果您觉得这个仓库有用，请点个星标！