{
  "markdown": "# ⚡ FusionPact\n\n### The Agent-Native Retrieval Engine\n\n**Hybrid Vector + Reasoning + Memory for AI Agents**\n\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D18-green.svg)](https://nodejs.org)\n[![npm](https://img.shields.io/npm/v/fusionpact.svg)](https://www.npmjs.com/package/fusionpact)\n\n> **Similarity ≠ Relevance.** FusionPact is the first retrieval engine that combines HNSW vector search, reasoning-based tree retrieval, and agent memory in a single platform — purpose-built for AI agents and multi-agent systems.\n\n[Quickstart](#-quickstart) · [Hybrid Retrieval](#-hybrid-retrieval-engine) · [Agent Memory](#-agent-memory) · [Multi-Agent](#-multi-agent-orchestration) · [MCP Server](#-mcp-server) · [Tree Index](#-tree-index) · [RAG Pipeline](#-rag-pipeline) · [API Reference](#-api-reference) · [Benchmarks](#-benchmarks) · [Contributing](#-contributing)\n\n---\n\n## Why FusionPact?\n\nTraditional vector databases retrieve what's **similar**. But similar ≠ relevant. Ask a vector DB for \"Q3 2024 revenue\" and you might get Q2 or Q4 data — semantically similar, but the **wrong answer**.\n\nFusionPact solves this by combining **three retrieval paradigms**:\n\n| Strategy | How It Works | Best For |\n|---|---|---|\n| **Vector Search** (HNSW) | Embedding similarity, O(log N) | Broad search across large collections |\n| **Tree Reasoning** | LLM navigates document structure | Precise retrieval in structured documents |\n| **Keyword Search** (BM25) | Term frequency matching | Exact match requirements |\n\nPlus purpose-built **agent memory**, **multi-agent orchestration**, and **MCP server** — all zero-dependency, local-first, and free.\n\n```\n┌──────────────────────────────────────────────────────────┐\n│             FusionPact Retrieval Engine                   │\n│                                                          │\n│  ┌────────────┐  ┌─────────────┐  ┌────────────────┐   │\n│  │ Vector     │  │ Tree        │  │ Keyword        │   │\n│  │ (HNSW)     │  │ (Reasoning) │  │ (BM25)         │   │\n│  └─────┬──────┘  └──────┬──────┘  └───────┬────────┘   │\n│        └────────────┬────┴─────────────────┘            │\n│                     ▼                                    │\n│           Reciprocal Rank Fusion                         │\n│                     ▼                                    │\n│  ┌──────────────────────────────────────────────────┐   │\n│  │        Agent Memory (Multi-Agent)                │   │\n│  │  Episodic │ Semantic │ Procedural │ Shared       │   │\n│  └──────────────────────────────────────────────────┘   │\n│  ┌──────────────────────────────────────────────────┐   │\n│  │        MCP Server (Claude, Cursor, etc.)         │   │\n│  └──────────────────────────────────────────────────┘   │\n└──────────────────────────────────────────────────────────┘\n```\n\n---\n\n## ⚡ Quickstart\n\n```bash\n# Install\nnpm install fusionpact\n\n# Run the demo\nnpx fusionpact demo\n\n# Start HTTP + MCP server\nnpx fusionpact serve --port 8080\n\n# Start MCP server for Claude Desktop\nnpx fusionpact mcp\n```\n\n### 10 Lines of Code\n\n```javascript\nconst { create } = require('fusionpact');\n\nconst fp = create({ embedder: 'ollama' }); // or 'mock' for zero-config\n\n// Ingest a document — auto-chunks, embeds, indexes\nawait fp.rag.ingest('Your document text here...', { source: 'doc.pdf' });\n\n// Hybrid search — vector + reasoning + keyword, fused automatically\nconst results = await fp.retriever.retrieve('What safety protocols exist?', {\n  collection: 'default',\n  strategy: 'hybrid'\n});\n\n// Or build LLM-ready context directly\nconst context = await fp.rag.buildContext('What safety protocols exist?');\nconsole.log(context.prompt); // Ready to paste into any LLM\n```\n\n---\n\n## 🔀 Hybrid Retrieval Engine\n\nThe core differentiator: a single API that intelligently routes queries through multiple retrieval strategies and fuses results using Reciprocal Rank Fusion.\n\n```javascript\nconst { create } = require('fusionpact');\n\nconst fp = create({\n  embedder: 'ollama',        // Local, free, private\n  llmProvider: 'ollama',     // For tree reasoning\n  enableHybrid: true\n});\n\n// Index a structured document with tree structure\nawait fp.treeIndex.indexDocument('annual-report', reportText, {\n  format: 'markdown'\n});\n\n// Hybrid retrieval — automatically uses the best strategy\nconst results = await fp.retriever.retrieve(\n  'What were the total deferred tax assets in Q3?',\n  {\n    collection: 'documents',       // Vector search here\n    docId: 'annual-report',        // Tree reasoning here\n    topK: 5,\n    strategy: 'hybrid'            // Fuse all strategies\n  }\n);\n\n// Each result includes:\n// - score: Fused relevance score\n// - content: Retrieved text\n// - sources: Which strategies contributed { vector: 0.8, tree: 0.9, keyword: 0.3 }\n// - citation: \"Section 3 > Financial Data > Table 3.2.1\"\n// - reasoning: Full tree traversal reasoning trace\n```\n\n### Strategy Weights\n\n```javascript\nconst retriever = new HybridRetriever({\n  engine, treeIndex, embedder,\n  weights: {\n    vector: 0.4,   // 40% weight to vector similarity\n    tree: 0.4,     // 40% weight to reasoning-based retrieval\n    keyword: 0.2   // 20% weight to keyword matching\n  }\n});\n```\n\n### Adaptive Learning\n\nFusionPact learns which retrieval strategy works best for different query patterns:\n\n```javascript\n// Record feedback on result quality\nretriever.recordFeedback('financial query', 'tree', 0.95);\nretriever.recordFeedback('general search', 'vector', 0.85);\n\n// Get recommended weights for a new query\nconst weights = retriever.getAdaptiveWeights('new financial query');\n// → { vector: 0.25, tree: 0.6, keyword: 0.15 }\n```\n\n---\n\n## 🌲 Tree Index\n\nReasoning-based retrieval for structured documents. Builds a hierarchical tree (like an intelligent table of contents) and uses LLM reasoning to navigate to the most relevant sections.\n\n```javascript\nconst { TreeIndex, LLMProvider } = require('fusionpact');\n\nconst llm = new LLMProvider({ provider: 'ollama' }); // Free, local\nconst tree = new TreeIndex({ llmProvider: llm });\n\n// Index a document\nawait tree.indexDocument('sec-filing', filingText, {\n  format: 'markdown',\n  metadata: { source: '10-K', year: 2024 }\n});\n\n// Reasoning-based search\nconst results = await tree.search('sec-filing', 'Total deferred tax assets', {\n  maxResults: 3,\n  includeReasoning: true\n});\n\n// results[0]:\n// {\n//   content: \"Table 5.2: Deferred Tax Assets...\",\n//   relevanceScore: 0.95,\n//   citation: \"Financial Statements > Note 5 > Tax Assets > Table 5.2\",\n//   reasoningPath: [\n//     { title: \"Financial Statements\", reasoning: \"Deferred tax assets are in financial notes\", action: \"explore\" },\n//     { title: \"Note 5: Income Taxes\", reasoning: \"This note covers tax-related assets\", action: \"explore\" },\n//     { title: \"Table 5.2\", reasoning: \"Contains the deferred tax asset breakdown\", action: \"retrieve\" }\n//   ]\n// }\n```\n\n### Works Without LLM Too\n\nIf no LLM provider is configured, TreeIndex falls back to keyword-based tree traversal — still useful, just without the reasoning path:\n\n```javascript\nconst tree = new TreeIndex(); // No LLM — keyword fallback\nawait tree.indexDocument('doc', text, { format: 'markdown' });\nconst results = await tree.search('doc', 'safety protocols');\n```\n\n---\n\n## 🧠 Agent Memory\n\nPurpose-built memory system for AI agents with four memory types:\n\n| Memory Type | What It Stores | Example |\n|---|---|---|\n| **Episodic** | Events, conversations, observations | \"User asked about Lab B chemical storage\" |\n| **Semantic** | Facts, domain knowledge, learned info | \"OSHA 1910.106 covers flammable liquids\" |\n| **Procedural** | Tool schemas, API specs, workflows | search_incidents tool definition |\n| **Shared** | Cross-agent knowledge pool | \"Customer ACME prefers ISO 14001\" |\n\n```javascript\nconst { create } = require('fusionpact');\nconst fp = create({ embedder: 'ollama', enableMemory: true });\n\n// Episodic — remember what happened\nawait fp.memory.remember('agent-1', {\n  content: 'User prefers dark mode and concise answers',\n  role: 'system',\n  importance: 0.8\n});\n\n// Semantic — learn knowledge\nawait fp.memory.learn('agent-1',\n  'OSHA 29 CFR 1910 covers general industry safety standards.',\n  { source: 'regulations', category: 'compliance' }\n);\n\n// Procedural — register tools\nawait fp.memory.registerTool('agent-1', {\n  name: 'search_incidents',\n  description: 'Search EHS incident reports by category and severity',\n  schema: { type: 'object', properties: { severity: { type: 'string' } } }\n});\n\n// Recall — cross-memory search\nconst memories = await fp.memory.recall('agent-1', 'safety compliance');\n// → { episodic: [...], semantic: [...], procedural: [...], shared: [...] }\n\n// Conversation memory\nfp.memory.addMessage('agent-1', 'thread-001', { role: 'user', content: 'What are the PPE requirements?' });\nfp.memory.addMessage('agent-1', 'thread-001', { role: 'assistant', content: 'PPE requirements include...' });\nconst history = fp.memory.getConversation('agent-1', 'thread-001');\n\n// GDPR-friendly forget\nfp.memory.forget('agent-1', { type: 'all' });\n```\n\n---\n\n## 🤖 Multi-Agent Orchestration\n\nCoordinate multiple AI agents with isolated memory, shared knowledge, and message routing:\n\n```javascript\nconst { create, AgentOrchestrator } = require('fusionpact');\n\nconst fp = create({ embedder: 'ollama', enableMemory: true });\nconst orchestrator = new AgentOrchestrator({\n  engine: fp.engine,\n  memory: fp.memory,\n  retriever: fp.retriever\n});\n\n// Register agents\norchestrator.registerAgent({\n  agentId: 'researcher',\n  name: 'Research Agent',\n  role: 'Find and analyze information',\n  capabilities: ['search', 'analysis', 'summarization']\n});\n\norchestrator.registerAgent({\n  agentId: 'writer',\n  name: 'Writing Agent',\n  role: 'Generate reports and documentation',\n  capabilities: ['writing', 'formatting', 'editing']\n});\n\n// Agent-to-agent communication\nawait orchestrator.send({\n  from: 'researcher',\n  to: 'writer',\n  type: 'result',\n  payload: { findings: 'Safety incidents decreased 12% YoY...' }\n});\n\n// Capability-based task delegation\nawait orchestrator.delegate('coordinator', 'Write a safety summary report', {\n  requiredCapabilities: ['writing', 'formatting']\n});\n// → Automatically routes to 'writer' agent\n\n// Collaborative retrieval across all agents\nconst results = await orchestrator.collaborativeRecall('safety compliance');\n// → Returns memories from all agents, plus shared knowledge\n\n// Message handling\norchestrator.onMessage('writer', async (msg) => {\n  console.log(`Writer received: ${msg.type} from ${msg.from}`);\n  // Process task...\n});\n```\n\n---\n\n## 🔌 MCP Server\n\nFusionPact ships as an MCP (Model Context Protocol) server. Any AI agent (Claude, Cursor, Windsurf) can use it as persistent memory — no custom integration needed.\n\n### Claude Desktop Setup\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"fusionpact\": {\n      \"command\": \"npx\",\n      \"args\": [\"fusionpact\", \"mcp\"],\n      \"env\": {\n        \"EMBEDDING_PROVIDER\": \"ollama\"\n      }\n    }\n  }\n}\n```\n\n### Available MCP Tools\n\n| Tool | Description |\n|---|---|\n| `fusionpact_create_collection` | Create HNSW-indexed vector collection |\n| `fusionpact_search` | Semantic vector search |\n| `fusionpact_hybrid_search` | Hybrid retrieval (vector + tree + keyword) |\n| `fusionpact_rag_ingest` | One-click RAG ingestion |\n| `fusionpact_rag_query` | Build LLM-ready context |\n| `fusionpact_memory_remember` | Store episodic memory |\n| `fusionpact_memory_recall` | Recall relevant memories |\n| `fusionpact_memory_learn` | Add semantic knowledge |\n| `fusionpact_memory_share` | Share cross-agent knowledge |\n| `fusionpact_memory_forget` | GDPR-style memory erasure |\n| `fusionpact_memory_conversation` | Manage conversation threads |\n\n---\n\n## 📄 RAG Pipeline\n\nEnd-to-end RAG in one call:\n\n```javascript\nconst fp = require('fusionpact').create({ embedder: 'ollama' });\n\n// Ingest — auto-chunks, embeds, indexes\nawait fp.rag.ingest(documentText, {\n  source: 'safety-manual.pdf',\n  title: 'Safety Manual 2024'\n});\n\n// Build context for any LLM\nconst ctx = await fp.rag.buildContext('What PPE is required?', {\n  topK: 5,\n  maxTokens: 4000,\n  strategy: 'hybrid'  // Uses HybridRetriever if available\n});\n\n// ctx.prompt → Ready for any LLM\n// ctx.sources → Source citations\n// ctx.chunks → Number of chunks used\n```\n\n### Chunking Strategies\n\n```javascript\nconst rag = new RAGPipeline(engine, {\n  chunkStrategy: 'recursive',  // 'recursive' | 'sentence' | 'paragraph'\n  chunkSize: 512,\n  chunkOverlap: 50\n});\n```\n\n---\n\n## 🔒 Multi-Tenancy\n\nZero-trust soft-isolation — tenants can never see each other's data:\n\n```javascript\nconst tenantA = engine.tenant('shared-collection', 'acme_corp');\nconst tenantB = engine.tenant('shared-collection', 'globex_inc');\n\ntenantA.insert([{ id: 'doc-1', vector: [...], metadata: { doc: 'Acme Plan' } }]);\n\n// Tenant A queries — only sees Acme data. Always.\nconst results = tenantA.search(queryVec, { topK: 10 });\n```\n\n---\n\n## 🔌 Embedding Providers\n\n| Provider | Setup | Dimensions | Cost |\n|---|---|---|---|\n| **Ollama** (recommended) | `ollama pull nomic-embed-text` | 768 | Free |\n| **OpenAI** | Set `OPENAI_API_KEY` | 1536 | ~$0.02/1M tokens |\n| **Mock** (testing) | None | 64 | Free |\n\n```javascript\n// Ollama (local, free, private)\nconst fp = create({ embedder: 'ollama' });\n\n// OpenAI\nconst fp = create({ embedder: 'openai', openaiConfig: { apiKey: 'sk-...' } });\n\n// Mock (for demos/testing — no dependencies)\nconst fp = create({ embedder: 'mock' });\n```\n\n---\n\n## 📊 Benchmarks\n\n### HNSW Performance (128D vectors)\n\n| Vectors | Insert | Search (p50) | QPS |\n|---|---|---|---|\n| 1,000 | 15ms | 0.2ms | ~5,000 |\n| 10,000 | 180ms | 0.3ms | ~3,300 |\n| 100,000 | 2.8s | 0.5ms | ~2,000 |\n\nRun your own:\n\n```bash\nnpx fusionpact bench --count 10000\n```\n\n---\n\n## 🆚 Comparison\n\n| Feature | FusionPact | PageIndex | Pinecone | Chroma | Qdrant |\n|---|---|---|---|---|---|\n| **Hybrid Retrieval (Vector+Tree+Keyword)** | ✅ | ❌ | ❌ | ❌ | ❌ |\n| **Reasoning-Based Tree Index** | ✅ | ✅ | ❌ | ❌ | ❌ |\n| **Agent Memory Architecture** | ✅ | ❌ | ❌ | ❌ | ❌ |\n| **Multi-Agent Orchestration** | ✅ | ❌ | ❌ | ❌ | ❌ |\n| **MCP Server (Agent-Native)** | ✅ | ✅ | ❌ | ❌ | ❌ |\n| **One-Click RAG** | ✅ | ❌ | ❌ | ❌ | ❌ |\n| **Multi-Tenancy** | ✅ | ❌ | ✅ | ❌ | ✅ |\n| **Local-First / Zero-Cost** | ✅ | ✅ | ❌ | ✅ | ✅ |\n| **HNSW Vector Index** | ✅ | ❌ | ✅ | ✅ | ✅ |\n| **Zero Dependencies** | ✅ | ❌ | ❌ | ❌ | ❌ |\n\n---\n\n## 📖 API Reference\n\nFull documentation: [docs/API.md](docs/API.md)\n\n### Core Classes\n\n| Class | Description |\n|---|---|\n| `FusionEngine` | Core database engine, collection management, CRUD |\n| `HNSWIndex` | HNSW approximate nearest neighbor index |\n| `TreeIndex` | Hierarchical document index for reasoning retrieval |\n| `HybridRetriever` | Multi-strategy retrieval with rank fusion |\n| `AgentMemory` | Multi-type agent memory system |\n| `AgentOrchestrator` | Multi-agent coordination layer |\n| `RAGPipeline` | End-to-end RAG pipeline |\n| `MCPServer` | Model Context Protocol server |\n| `OllamaEmbedder` | Ollama embedding provider |\n| `OpenAIEmbedder` | OpenAI embedding provider |\n| `MockEmbedder` | Testing/demo embedder |\n| `LLMProvider` | Multi-provider LLM interface |\n\n---\n\n## 🗺 Roadmap\n\n- [x] HNSW indexing with configurable M/ef parameters\n- [x] Multi-tenancy with soft-isolation\n- [x] One-Click RAG pipeline\n- [x] Agent Memory (episodic, semantic, procedural, shared)\n- [x] Multi-agent orchestration\n- [x] Tree Index (reasoning-based retrieval)\n- [x] Hybrid Retriever (vector + tree + keyword fusion)\n- [x] MCP server (stdio + HTTP)\n- [x] HTTP API server\n- [x] Ollama + OpenAI embedding providers\n- [x] Adaptive retrieval learning\n- [ ] SQLite/PostgreSQL persistence\n- [ ] Python SDK (`pip install fusionpact`)\n- [ ] LangChain integration\n- [ ] LlamaIndex integration\n- [ ] CrewAI / AutoGen integration\n- [ ] Vision RAG (PDF page images)\n- [ ] Rust core (NAPI bindings)\n- [ ] FusionPact Cloud (managed hosting)\n- [ ] Dashboard UI\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n```bash\ngit clone https://github.com/FusionpactTech/fusionpact-vectordb.git\ncd fusionpact-vectordb\nnpm install\nnpm test\nnpx fusionpact demo\n```\n\n---\n\n## 📜 Attribution\n\nFusionPact is built and maintained by **[FusionPact Technologies Inc.](https://fusionpact.com)**\n\nIf you use FusionPact in your project, please include attribution in one of the following ways:\n\n- Include \"Powered by FusionPact\" in your application's about page or documentation\n- Keep the `NOTICE` file in your distribution\n- Reference FusionPact Technologies Inc. in your project's acknowledgements\n\nSee [ATTRIBUTION.md](ATTRIBUTION.md) for full details.\n\n## License\n\n[Apache 2.0](LICENSE) — Use freely in commercial and open-source projects.\n\nThe Apache 2.0 license requires that you:\n1. Include a copy of the license in any redistribution\n2. Include the NOTICE file with attribution to FusionPact Technologies Inc.\n3. State any significant changes you made to the code\n\n---\n\n**Built with ❤️ by [FusionPact Technologies Inc.](https://fusionpact.com)**\n\n⭐ Star this repo if you find it useful!\n",
  "bytes": 17202,
  "sha": "74b7eaa95e9502af8639839d713a15cd4042ed672fac3eda2d23d4d030ad8264",
  "repo_slug": "fusionpacttech/fusionpact-vectordb",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_atul_fusionpact_fusionpact_vec_93283900/readme"
}