recallforge (Brianmeyer)

RecallForge

每种模式，一次搜索。本地优先。

标准RAG仅适用于文本。拖放一个包含图表、白板照片或视频记录的PDF——你的AI代理就会失明。RecallForge为代理商提供 密切关注本地文件系统。文本、图像、文档和视频都存在于一个统一的搜索空间中，任何东西都不会离开你的机器。

这能带来什么

你： “上次会议的白板是什么样子的？” 克劳德： *（搜索您的本地 ~/Documents，从iPhone中查找白板的照片，通过Qwen3 VL读取笔迹，并显示带有上下文的图像。)*

你： “从我上周下载的PDF中找到架构图。” 克劳德： *（对PDF进行索引，将您的查询与提取的文本和嵌入的图形进行匹配，返回相关页面。）*

你： *（掉落电路板的图像）* “查找我与此相关的笔记。” 克劳德： *（在索引笔记中反向图像到文本搜索。返回匹配的文档。）*

一个查询。任何形式。都是当地人。

是什么让RecallForge与众不同

在以下情况下使用RecallForge： 您需要为完全在您的机器上运行的AI代理提供多模式内存，特别是在Apple Silicon上。在文本、图像、文档和视频中进行一次搜索。

在以下情况下使用其他东西： 你需要云托管、大规模（数百万向量）或JS/TS优先的生态系统。

演出

4种模态（文本、图像、文档、视频）统一在单个MLX优化的局部向量空间中。嵌入模式下的搜索延迟低于60毫秒。驻留内存低于400MB。

管道消融（Mac mini M4 16GB，MLX 4位）

管道的每个阶段都提高了检索质量。再评级是质量峰值。

重新登录者交付 +RRF融合上20.7%的R@1 将R@10提高到97.8%。嵌入模式为您提供20ms的搜索速度敏感的工作负载。当质量很重要时，混合模式为您提供85.9%的R@1。

*基准类别：仅文本（30个查询）、仅图像（30个）、长查询（12个查询）和打字错误查询（20个查询）。看 benchmarks/results/pipeline_ablation_modality_results.json 完全崩溃。*

对于发布验证，请使用 benchmarks/cross_modal_ablation.py。它现在在运行时检查JSON输出，因此长时间的MLX基准测试会话在中断时仍会留下部分工件。

延迟和资源使用

*\*MLX通过内存映射文件懒洋洋地映射模型权重。RSS反映的是驻留页面，而不是完整的模型大小（~1.7GB嵌入器+~1.7GB磁盘重新登录器）。实际内存压力低。*

COCO 1K检索（原始嵌入，无管道）

透明度：原始嵌入质量在标准COCO基准上（1000张图像，无BM25/重新分级/扩展）。这些数字仅反映了Qwen3-VL-2B嵌入器，而不是整个管道。

*Qwen3-VL是一种生成性VLM，而不是像CLIP那样的对比模型。上述管道消融显示了BM25融合和重新分级是如何弥补这一点的。*

安装

pip install recallforge[mlx]       # Apple Silicon (recommended, 4-bit quantization)
pip install "recallforge[mlx,server]"  # Apple Silicon + HTTP/SSE server
pip install recallforge[cuda]      # NVIDIA GPU
pip install recallforge[torch]     # CPU / other PyTorch targets
pip install recallforge[docs]      # add richer PDF extraction (optional)

注： pip install recallforge 在没有后端的情况下安装核心。 您至少需要以下之一 [mlx], [cuda]，或 [torch] 进行推理。 添加 [server] 仅当您需要HTTP/SSE传输时(recallforge serve --http).

来源：

git clone https://github.com/brianmeyer/recallforge.git
cd recallforge
pip install -e ".[mlx]"

需求

• 需要Python 3.12或3.13（3.14尚不支持，正在等待pyarrow轮）
• 磁盘：首次运行时可免费下载约2-5GB的模型
• 内存（MLX 4位）：~1.7GB(embed)至约3.4GB(hybrid)
• ffmpeg 建议用于视频索引/搜索
• 首次运行会自动下载模型，可能需要几分钟时间

MCP服务器（主要用途）

RecallForge被设计为 AI代理的模型上下文协议服务器.在Claude Desktop（或任何兼容MCP的代理主机）中配置：

{
  "mcpServers": {
    "recallforge": {
      "command": "recallforge",
      "args": ["serve", "--mode", "hybrid"]
    }
  }
}

手动运行（stdio）：

recallforge serve --mode embed --backend mlx --quantize 4bit

通过HTTP/SSE运行：

recallforge serve --http --host 127.0.0.1 --port 7433 --mode embed

RecallForge现已公开 20个MCP工具 跨搜索、摄取、内存、集合管理和运行时配置。HTTP/SSE模式也公开了 /health, /sse，以及 /messages/.

看 docs/mcp-tools.md 以获取完整的工具参考。

搜索模式

视频\[Beta\]注释： 视频支持需要 ffmpeg火炬后端视频路径存在已知的上游问题（参见 QwenLM/Qwen3.5#58).

运作原理

RecallForge使用Qwen3 VL将文本、图像和视频帧编码到相同的2048维向量空间中。这意味着无论图表是文本、图像还是视频中的帧，“查找此图表的注释”都有效。其余部分由三级管道处理：

graph TD
    subgraph Local Filesystem
        Docs[📄 Documents]
        Imgs[🖼️ Images]
        Vids[🎬 Video]
    end

    subgraph RecallForge Ingest
        Docs --> TxtExt[Text Extractor]
        Imgs --> VLM[Qwen3-VL Encoder]
        Vids --> Frame[Frame & Audio Extractor]
        Frame --> VLM
        TxtExt --> VLM
    end

    subgraph LanceDB Storage
        VLM -->|2048-dim Vectors| VecDB[(Vector Space)]
        TxtExt -->|Text/Transcripts| FTS[(Tantivy FTS)]
    end

    subgraph MCP Search Pipeline
        Query[Agent Query] --> BM25[BM25 Text Search]
        Query --> Dense[Vector Similarity Search]
        BM25 --> RRF[RRF Fusion]
        Dense --> RRF
        RRF --> Rerank[Cross-Encoder Reranker]
        Rerank --> Output[Final Context to Agent]
    end

管道： BM25探头→ 平行BM25+矢量→ RRF融合→ 重新分级（混合动力模式）→ 分数混合

CLI（开发与调试）

# Index anything
recallforge index ./photos ./docs
recallforge index ~/Movies/demo.mp4
recallforge index ~/Documents/roadmap.pptx

# Search any modality
recallforge search "whiteboard diagram from last meeting"
recallforge search --image ./photos/whiteboard.png
recallforge search --video ~/Movies/demo.mp4

# Watch a folder for changes (auto-index)
recallforge watch start ~/Documents --collection docs
recallforge watch list
recallforge watch stop ~/Documents

# Status
recallforge status

RecallForge自动检测苹果Silicon上的MLX，其他地方的PyTorch。

Python API

from recallforge import get_backend, get_storage
from recallforge.search import HybridSearcher

backend = get_backend()
storage = get_storage()
backend.warm_up()

# Index
storage.index_document(
    path="notes.md",
    text="My notes about AI...",
    collection="my_docs",
    model="Qwen3-VL-Embedding-2B",
    embed_func=backend.embed_text,
)

# Search
searcher = HybridSearcher(backend=backend, storage=storage, limit=10)
results = searcher.search("artificial intelligence")
for r in results:
    print(f"[{r.score:.3f}] {r.title}")

配置

完整参考（包括高级调优和服务器/存储内部）： docs/ENV_VARS.md

项目结构

src/recallforge/
├── backends/
│   ├── mlx_backend.py    # MLX 4-bit/bf16 (Apple Silicon)
│   └── torch_backend.py  # PyTorch (CUDA/MPS/CPU)
├── storage/
│   └── lancedb_backend.py # LanceDB + Tantivy FTS
├── cache.py              # LRU embedding cache
├── search.py             # Hybrid search pipeline (BM25 + vector + RRF)
├── server.py             # MCP server (20 tools, stdio + HTTP/SSE)
├── documents.py          # PDF/DOCX/PPTX extraction
├── video.py              # Frame/transcript extraction
├── watch_folder.py       # Folder monitoring with dedup
└── cli.py                # CLI interface

发展

pytest tests/ -m "not live"    # Unit tests (no model download needed)
pytest tests/ -m live -v       # Integration tests (requires models)

发布工作流

CI in .github/workflows/ci.yml 运行测试矩阵，构建发行版，运行 twine check，冒烟测试轮子安装，冒烟测试内置轮子之外的HTTP服务器。标签推送匹配 v* 触发 .github/workflows/publish.yml，它以受信任的发布方式发布到PyPI。

在标记发布之前，请运行repo测试套件和install/CLI UAT脚本，如果您在有能力的主机上，请运行实时集成切片和扩展基准测试。完整的检查表位于 docs/RELEASE.md.

看 贡献.md 获取完整的开发指南。

归因

RecallForge的灵感来自 QMD QMD开创了多阶段检索管道（嵌入、重新排序）。RecallForge通过跨模式检索和多后端支持将此模式扩展到视觉语言。

许可证

MIT许可证