magpie-search

Magpie Search

一个联邦搜索引擎——当 AI Agent 或大模型需要查找可用于推理的真实信息时，它们就会用上这个搜索引擎。

---

你的电脑是否曾突然重启，或是在使用过程中遭遇停电？Agent 保存的所有对话——全都没了。现在，你有了可以找回它们的工具。 再也不用担心 Agent 丢失过往记忆。 Magpie 会在本地索引 AI 处理过的所有内容，让崩溃只成为小插曲，而不是记忆全失。

Magpie 是什么

普通搜索引擎只会在一个地方查找。Magpie 接收一个问题，同时将其扩展到所有重要来源——AI 的全部对话历史、机器上的文件、结构化知识图谱、向量存储和实时网络——再从信息实际所在之处取回答案。 五个来源，一次调用。

它还会以最合适的方式搜索每个来源。如果你知道确切的词元——文件路径、错误信息或代码行——它可以用 grep 查找确切字符串或正则表达式。它可以按关键词搜索，也可以按含义搜索，即使字词不匹配，也能找到相关内容。它还能同时完成所有这些操作。

接着，它会完成让搜索结果值得信赖的关键步骤：将所有内容融合成一个排序后的答案，并为每条结果标注可信度等级——fact > reference > lead > stale。可靠来源会排在前面，较不确定的来源会标记为待核实线索，重复内容会合并，结果也会精简到合适的长度，不会塞满 AI 的上下文。让它深入研究时，它会将一个问题扩展成多个问题，阅读相关页面，并告诉你有多少个独立来源得出了相同结论——无需派出一群 Agent，就能完成全面的研究。

它完全在本机运行。无需服务、账号，也不会收集遥测数据，除非你主动启用。AI 的对话记录和文件绝不会离开本机。它通过 MCP 接入正在运行的 AI，让 Agent 在需要时立即访问所有六个来源。

它是面向 AI 的工具——供 Agent 或大模型使用。

内部构成

其核心是 AI 对话记录的本地索引：一个 SQLite 数据库，内含两种并行构建的结构 —

• FTS5 全文索引（BM25 关键词排序），以及
• 一个 sqlite-vec 向量索引，存储由小型 all-MiniLM-L6-v2 模型在本地生成的 384 维嵌入。

所有内容在摄入时都会脱敏 — 在任何字节进入索引之前，清理器会剔除约 30 类机密信息（密钥、令牌、私钥、连接字符串）。

该索引之上提供五种搜索模式：

模式	功能
grep	字面匹配 / 正则表达式匹配（精确令牌：路径、错误、代码）
lexical	FTS5 / BM25 关键词搜索
semantic	嵌入 K-NN，在向量索引中按余弦距离搜索
hybrid	词法搜索 + 语义搜索，通过 RRF 融合
rerank	混合搜索，然后使用交叉编码器（jina-reranker）重新评估每个候选项

索引周围是联邦层 — 它让系统成为联邦式的：

• 提供方插件系统。 五种后端（对话记录、文件、知识图谱、向量、网络），每种都会返回带有信任等级标签的 Hit 对象。
• 扇出查询： 一个查询会并发发送给所有提供方（≤8 个工作线程），每个查询都有 5 秒超时，并且超时后继续运行 — 响应较慢的来源不会返回结果，但不会阻塞调用。
• 按信任度加权的 RRF 融合 — 倒数排名融合会将各来源的排名乘以其信任权重（fact ×3, reference ×2, lead ×1, stale ×0.3），阻尼常数为 60。这套计算会将六种异构来源合并为一个可信的排序结果。
• 按内容哈希进行跨来源去重 — 在三个位置找到的同一事实会合并为一个命中项，并标注它还出现在哪些位置（佐证信息）。
• 令牌预算裁剪，确保合并后的结果集不会超出调用 AI 的上下文限制。

所有这些功能都会通过 MCP 服务提供给 AI — 它交给 Agent 的工具只有：search、recent、session、list_sessions、stats、reindex。注意其中没有什么：任何用于撰写答案的功能。

为什么它不是 RAG

RAG = 检索增强生成。它是一个两阶段流水线，而决定其性质的是第二阶段：检索器找到文本块 → 将它们填入提示词 → 大模型生成文字答案。名称中的“G”才是关键；如果没有生成器撰写答案，它就不是 RAG。

Magpie 没有 G：

1. 搜索路径中没有任何生成器。 Magpie 中没有任何组件会撰写自然语言答案。最接近模型的组件 — 交叉编码器重排器 — 会为每个结果输出相关性分数，并重新排列列表。它只评分，从不写句子。
2. 它止步于“以下是排序后的命中项”。 RAG 负责组装提示词并调用模型。Magpie 返回融合后、按信任度排序的结果，并通过 MCP 将它们交还。AI 接下来会做什么 — 甚至是否生成任何内容 — 都由 AI 自行负责，超出 Magpie 的职责范围。
3. 它的检索器能力更强，而非更弱。 教科书式 RAG 检索器就是一个向量存储：嵌入查询，按余弦相似度取前 k 项，完成。Magpie 的检索涉及六种来源、五种模式、按信任度加权的融合，以及跨来源去重。它的“R”能力强得多 — 但它仍然只有 R。

将 Magpie 接入 AI，两者便可以组成 RAG — Magpie 是 R，你带来的 AI 是 G。但 Magpie 本身只提供 R，而且比通常的 R 更强。它查找并排序真实信息，但从不生成答案。

深度网络搜索——拓宽研究范围，不增加 Token 开销

“深度研究”中开销最大的部分是推理，多 Agent 方法会将这部分成本扩大 N 倍——每个 Agent 都需要一个完整的大模型上下文，单个问题往往就要消耗数百万个 Token。但推理不必分散进行；一个已经在上下文中的强大模型就能完成综合。只有搜索需要拓宽范围——而网络搜索纯粹是检索，不消耗大模型 Token。

magpie-search deepweb 正是利用了这种不对称性。它会并行向网络发起多个子查询，通过基于可信度加权的 RRF 和按 URL 去重，将结果融合成一组精简、按 Token 预算裁剪的来源；还可选择读取排名靠前页面的文本（仍然不消耗 Token），并报告有多少个独立域名支持该结果——这是一种无需 Agent 的验证方式，而研究型 Agent 群需要付出 Agent 成本才能做到这一点。

这样一来，你就能获得多 Agent 深度搜索的广度、页面阅读和交叉印证，但模型只需对裁剪后的结果集进行一次综合。

Token 成本实测——一个深度问题：

方案	模型消耗的 Token
多 Agent 深度研究群（N 个 Agent 各自将页面读入独立上下文）	~2,000,000
magpie-search deepweb --thorough（6 个角度 → 12 个来源，完整读取 12 个页面）	~1,050

这意味着 Token 数量减少约 2,000 倍——成本约为 1/2000——因为搜索和页面阅读纯粹是检索（不消耗大模型 Token）；模型只需对裁剪后且经过交叉印证的结果集进行最终综合。

# one question, several angles, read the top pages — all token-free retrieval
magpie-search deepweb "the question" --q "another angle" --q "a third angle" --thorough

随后，你工作流中的模型只需对合并后且经过交叉印证的结果集进行一次综合。这就是全部节省所在：拓宽搜索范围无需成本，你只需为答案付费。

---

安装

pip install magpie-search

实时网络搜索和 deepweb 需要安装 web extra：

pip install "magpie-search[web]"

若未安装，--sources web 和 deepweb 将返回无结果——网络提供程序采用软失败设计，因此绝不会中断联合搜索；所以缺少依赖时，看起来就和搜索没有找到任何内容一样。从 1.3.1 开始，它还会在 stderr 上输出一行原因说明，而不再静默失败。

或者直接从源代码安装最新版本：

pip install "git+https://github.com/xfloukiex-lab/magpie-search.git#egg=magpie-search[web]"

可选——添加本地大模型功能（交叉编码器重排器在基础安装中即可运行；会话摘要器需要 Ollama）：

# 1. Install Ollama (free, runs entirely locally) — https://ollama.com/download
# 2. Pull the model magpie-search uses
ollama pull phi3.5

适用于 Windows、macOS 和 Linux 上的 Python 3.10+。

快速开始

magpie-search index                               # build the index (incremental)
magpie-search search "that retry backoff thing"   # keyword search
magpie-search search --mode hybrid "..."          # keyword + semantic, fused
magpie-search search --mode rerank "..."          # + cross-encoder rerank
magpie-search stats                               # sanity-check the index

将其连接到你的 AI（MCP）

Magpie 支持 Model Context Protocol，因此任何支持 MCP 的 Agent 都可以调用它。将客户端指向捆绑的服务：

// e.g. an MCP client config
{
  "mcpServers": {
    "magpie": { "command": "magpie-search-mcp" }
  }
}

随后，Agent 就可以使用 search、recent、session、list_sessions、stats 和 reindex——支持联合搜索、按可信度排序，并按上下文预算裁剪结果。

CLI 参考

命令	说明
magpie-search index	对 ~/.claude/projects/ 进行增量索引
magpie-search search "q"	搜索——--mode grep|lexical|semantic|hybrid|rerank
magpie-search recent --n 30	最新会话中的最近 30 条消息
magpie-search session SESSION-ID	一个会话的完整记录
magpie-search list	最近的会话
magpie-search stats	索引大小、上次索引时间、行数
magpie-search backup	将 ~/.claude/projects/ 备份到可配置的目标位置

在任意命令后添加 --help 可查看完整选项。

Python API

import magpie_search

results = magpie_search.search("retry backoff", mode="hybrid", k=5)
for h in results["hits"]:
    print(h["trust"], h["source"], h["snippet"])

# LLM features (needs Ollama + phi3.5)
import magpie_search.llm
ranked  = magpie_search.llm.search_rerank(query="retry backoff", k=3, pool=10)
summary = magpie_search.llm.summarize(session_id="abc-123", n_messages=80)

备份

magpie-search backup 会将你的记录目录树复制到所选目标位置——本地文件夹（默认，无需配置）、远程 SSH 目标（NAS / 家用服务器），或支持虚拟机启动/挂起的远程 SSH 目标。在 ~/.magpie-search/backup.env 中配置：

[email protected]
MAGPIE_SEARCH_BACKUP_SSH_DEST=~/claude-transcripts/

常用标志：--dry-run、--no-suspend、--show-config。备份只会复制文件，绝不会删除原始文件。

配置

所有配置均由环境变量驱动，并提供合理的默认值。

变量	默认值	说明
MAGPIE_SEARCH_HOME	~/.magpie-search	数据目录（数据库、模型、日志）
MAGPIE_SEARCH_MODELS_DIR	$MAGPIE_SEARCH_HOME/models	fastembed 模型缓存
MAGPIE_SEARCH_OLLAMA_HOST	http://localhost:11434	Ollama 服务 URL
MAGPIE_SEARCH_TOKENIZER	heuristic	设置为 tiktoken 以精确计算预算
MAGPIE_SEARCH_AUDIT_LOG	$MAGPIE_SEARCH_HOME/llm-audit.jsonl	每次调用的审计日志

摘要器会通过由 6 项探针组成的防护链（长度、专有名词安全、标识符安全、拒绝漂移、语义依据、自我验证）；全部通过后，trust: clean 才成立。任何一项未通过都会抑制摘要并返回 trust: degraded——宁可安静，也不要出错。原始消息仍可通过 magpie-search session SESSION-ID 访问。

隐私

Magpie Search 是本地工具。没有服务、账号、自动更新或崩溃报告器，除非你明确选择加入，否则不会收集遥测数据（见下文）。你的对话记录、索引、审计日志、模型缓存和备份都保存在你的计算机上。

选择加入遥测。 遥测默认关闭——在你运行 magpie-search telemetry enable（或设置 MAGPIE_SEARCH_TELEMETRY=1）之前，magpie 不会发送任何内容。开启后，它只会发送匿名使用数据：运行的命令、搜索模式、结果／命中数量、延迟、错误类别，以及你的 magpie/python/OS 版本，并附带随机安装 ID。它绝不会发送你的查询、文件路径、结果、对话记录内容、用户名或 IP——telemetry.py 中严格的内容防火墙会丢弃任何非数字或非短枚举标记的内容。你可以随时运行 magpie-search telemetry disable 将其关闭；运行 magpie-search telemetry status 可查看状态。它发起的网络调用仅限：你的本地 Ollama 服务（LLM 功能）、你自己的备份目标（仅在你运行 backup 时），以及首次运行时从 Hugging Face 下载一次模型。你可以使用 tcpdump、Wireshark 或网络受限的沙盒自行验证。

定时任务

按计划运行 magpie-search index（也可选择运行 backup）。installers/ 中提供了现成的配置，适用于 systemd（Linux）、launchd（macOS）和 Task Scheduler（Windows）。

故障排除

• “rsync not on PATH” — 将回退到 scp -r。在 Windows 上，安装附带 rsync 的 Git for Windows。
• 搜索没有返回结果 — 运行 magpie-search stats；如果 last_indexed_at 为 null，则运行 magpie-search index。
• --sources web 或 deepweb 没有返回结果 — 未安装 web 扩展：pip install "magpie-search[web]"。运行以下命令检查： python -c "from magpie_search.providers.web import WebProvider; print(WebProvider().health())" — 你需要看到 ok: True。如果显示 ok: True 但仍没有结果，说明搜索引擎拒绝了你的请求；数据中心或 VPS 的地址段经常会遇到这种情况。请尝试使用其他网络，或通过提供程序的 backends= 配置指定不同的引擎顺序。
• 摘要器始终显示 degraded — 这是按设计工作的误报防护。原始对话记录仍可通过 session SESSION-ID 获取。

---

关于

Magpie Search 由 VektorGeist LLC 构建。

我们为使用自有 AI 的用户构建本地优先工具。Magpie 是搜索核心；我们的 Agent 平台位于 vektorgeist.com。

• 网站：vektorgeist.com
• 联系方式：[email protected]
• 问题与贡献：在此代码库中提交 issue 或 PR。

许可证

基于 Apache License 2.0 授权——详见 LICENSE。 版权所有 © 2026 VektorGeist LLC。

“Magpie Search”和 magpie 标志是 VektorGeist LLC 的商标。代码以 Apache-2.0 开源；品牌和名称予以保留。