igrep

面向 Agent 的 filesystem-native retrieval kernel。

igrep 直接在本地代码和文档上做自然语言检索，不需要预建向量索引；返回可定位到文件和行号的证据，也可以继续生成带引用的研究回答。CLI、MCP、Web 管理台和编辑器集成复用同一套检索语义。

igrep search "鉴权失败后在哪里重试" ~/code/my-project
igrep ask "这个项目如何加载配置？" ~/code/my-project

它解决什么问题

• 代码与文档检索：自然语言查询、文件类型和 glob 过滤、git diff 范围、结构化输出。
• 无需向量索引：文本和代码直接搜索；PDF、Office 文档和图片按需预处理成隐藏 sidecar。
• Agent 原生接入：Claude Code 和 Codex 的默认 MCP code 配置只提供 semantic search，精确符号导航交给宿主自己的 rg 和原生 LSP；为主流编码 Agent 提供一键配置。
• 多种证据源：本地文件、公开 Web、单个公开文档、内部搜索源和已授权网站各自保持清晰边界。
• Local-first：可使用 Apple Silicon 上的本地 oMLX，也可连接自管或云端的 OpenAI-compatible 服务。

igrep 不是通用 RAG 平台。igrep search 是主入口；ask、dig 和 chat 在检索证据之上工作；serve 是本机管理与 host 层，不改变检索语义。

安装

公开 distribution 是 igrep2，安装后的命令和 import 仍是 igrep。当前版本需要 Python 3.14。

推荐使用隔离的 uv tool 环境：

uv tool install --python 3.14 igrep2
igrep --version

也可以安装到已有的 Python 3.14 环境：

python3.14 -m pip install igrep2

组织可以用自己的 setup bundle 批量安装内部 source 插件与 Web provider 扩展；igrep2 本身不依赖任何此类 bundle。

升级已有安装：

igrep upgrade

选择 AI runtime

安装 CLI 后，选择一种运行方式：

完成后检查能力状态：

igrep doctor

doctor 默认只报告问题；在 CI 或安装脚本中需要非零退出码时使用 igrep doctor --strict。

5 分钟上手

搜本地代码和文档

# 当前目录
igrep search "配置在哪里加载"

# 指定目录和文件类型
igrep search "重试策略" ~/code/my-project --type py

# rg 风格 glob；可重复，! 表示排除
igrep search "鉴权逻辑" . -g 'src/**' -g '!**/test_*'

# 只搜相对 HEAD 的 git 变更文件
igrep search "可能破坏兼容性的改动" . --diff

# 供程序或 Agent 消费的单个 JSON document
igrep search "错误处理" . --format json

# 流式消费者使用一行一个结果的 JSONL
igrep search "错误处理" . --format jsonl

查询也可以来自 Unix pipe。结构化输入可显式指定 text、jsonl、markdown、git 或 log：

git diff | igrep search "潜在回归" --stdin-format git

选择检索强度

igrep search "请求从入口到持久化的完整流程" . --mode ultra

模式只调整质量、延迟和远端调用量，不改变输出协议。缺少可选后端时，对应通道关闭，基础文件检索仍保留。

搜索后继续研究

# 单次、有界、带引用的回答
igrep ask "配置优先级是什么？" .

# 分阶段深度研究，只把最终答案写到 stdout
igrep dig "一次搜索请求经过哪些模块？" .

# 交互式多轮 REPL
igrep chat

ask / dig 的 --detail 把紧凑进度写到 stderr，--verbose 输出调试 trace，--json 输出单个 JSON document。chat 是交互式终端，不是 JSON 接口；机器消费者应使用 igrep chat <subcommand> 或 igrep ask --stream。

多格式文件

代码、Markdown 和普通文本无需准备即可搜索。PDF、DOCX、PPTX、XLSX 等二进制文件需要先转换；图片内容需要 OCR/VLM augment。igrep index build 一步完成：

igrep index build ~/Documents          # 转换后立即可搜；图片描述交给 igrep serve 后台完成（需 `igrep project add`）
igrep index build ~/Documents --full   # 同时在本进程完成 OCR/VLM 图片描述再返回
igrep prepare --only augment ~/Documents    # 单阶段：只生成图片描述 sidecar

转换和增强把 .igrep.md、.igrep.images/ 和 .igrep.vision.md 产物写进源文件所在目录的隐藏容器 .igrep.d/（每个目录一个；需要时把 .igrep.d/ 加进 .gitignore），不修改用户原始 Markdown。之后仍用普通的 igrep search 查询。

可选词法索引

igrep index build 默认在准备文档之后构建持久化词法 store 和全部词元统计（TF/DF/IDF），增量构建自动更新。普通本地搜索默认使用 rg；开启词法后端并由 igrep serve 维护新鲜度时，索引可为 rg 提名文件：

igrep index build .
igrep index status .
igrep index terms . --term retrieval --json

fast 稀疏扩词为实验选项，默认关闭。配置 IGREP_SPARSE_URL、IGREP_SPARSE_MODEL 与 IGREP_SPARSE_TOKENIZER_PATH，并设 IGREP_FAST_SPARSE_EXPANSION=1，可结合新鲜索引的统计筛选扩词。

命令边界见 CLI 进程契约 §1.1，参数以 igrep index --help 为准。

Web、内部源与网站源

这些入口与本地文件搜索相互独立，不做隐式联邦融合。

# 配置 SearXNG / Tavily / Serper / Exa 等 provider
igrep setup web-search
igrep web-search "Python 3.14 release notes"
igrep web-dig "比较 Python 3.13 与 3.14 的并发变化"

# 在调用方给定的一个公开文档内找证据
igrep page-search https://example.com/spec.pdf "timeout policy"

# 查看并使用已配置的内部只读 source
igrep source list
igrep isearch "支付失败如何重试" --source <installed-plugin-source>

igrep isearch 还支持单文件 Python 插件和 command-backed source。安装插件前必须用 3–5 条真实查询通过资质验证，完整协议见内部搜索插件指南。

对于只有你登录后的 Chrome 才能搜到的网站（公司 wiki、内网工具、个人账号应用）， 网站源借用你已登录的浏览器身份，把该站点自己的搜索变成 isearch 来源—— 公开内容走 web-search，有 API/token 的系统写插件，只有这类站点用它：

igrep serve start
igrep setup chrome
igrep source site list
igrep isearch "query" --site <source-id>

网站源只重放用户审核并启用的搜索请求；运行时返回站点搜索结果，不跟随结果 URL 抓取正文，也不保存 cookie/token。完整上手流程见网站搜索源指南。

自动修复：网站改版导致搜索失效时，失败信息会直接给出修复命令——

igrep source site repair <source-id> --queries 词1,词2,词3 --approve

igrep 用脱敏后的失败证据（字段名、路径候选，绝不含 cookie 和页面内容）让 AI 提出修复提案——本机装了 Codex CLI 就走它的禁网沙箱，否则走你已配置的 ask LLM 路由——再用你的 3–5 个真实搜索词重新验证、终审重放后才激活。AI 只出提案，不碰信任门。

接入编码 Agent

igrep setup <platform> 安装该宿主支持的最小原生接入面。MCP 类宿主可按 --help 使用 --scope project；OpenClaw、Hermes、Pi 和 DeepSeek Harness 使用各自的插件或包管理机制，不接受通用 --scope。

OpenClaw 只有在明确要替换其 memory slot 时才使用 igrep setup openclaw --flavor memory。Hermes 的 MemoryProvider 也是显式可选项： igrep setup hermes --with-memory-provider --activate-memory-provider；已有其他 provider 时不会自动覆盖。

Claude Code 和 Codex 默认使用窄的 code toolset，只包含：

• semantic_search：按自然语言意图检索代码和已准备的文档

其余 MCP 宿主默认 agent toolset，在同一个 semantic_search 之上按配置追加 web 与 isearch；另有 repo 可显式选择。igrep 不提供符号 / LSP 导航：按名字查定义和 引用用宿主的 rg，按光标的语义导航用宿主原生 LSP。安装、体检和回报流程见 Agent 安装指南。

Agent 记忆

igrep mem 是给 Agent 宿主用的 file-backed 记忆：宿主把可见对话 ingest 进 <workspace>/.igrep/mem（增量、只追加，不必每轮调），maintain 抽取用户 profile 并顺带补齐没交过来的会话，session 开始用 wake 注入常驻 profile， 模型随时用 recall 按问题检索。

igrep mem ingest --workspace ~/agent-ws --transcript turns.jsonl --session-id s1
igrep mem maintain --workspace ~/agent-ws
igrep mem wake --workspace ~/agent-ws --format markdown
igrep mem recall "用户偏好什么 Python 工具" --workspace ~/agent-ws

workspace 目录就是隔离单元。一个 agent 服务很多人时不用自己管目录：用 --store ROOT --user U [--tenant T] 代替 --workspace，igrep 在 ROOT 下给每个 (tenant, user) 解析一个私有 workspace（哈希目录，读不建、写才建），--rows - 直接喂 对话行，maintain --pending 一次处理整个 store，mem store list|purge|sweep 做 枚举、删除与不活跃清理：

printf '%s\n' '{"role":"user","content":"以后回复用中文"}' \
  | igrep mem ingest --store /srv/mem --tenant acme --user alice --session-id s1 --rows -
igrep mem maintain --store /srv/mem --pending
igrep mem recall "回复语言偏好" --store /srv/mem --tenant acme --user alice
igrep mem store sweep --store /srv/mem --inactive-days 90          # 只报告；--apply 才删

OpenClaw / Hermes / Pi / DeepSeek Harness 的现成接入见上表；自己的宿主按 记忆宿主接入指南接入。

管理台与项目

igrep project add ~/code/my-project
igrep serve run

serve 是唯一管理入口，提供项目、搜索、聊天、后端状态和诊断界面。后台运行和 OS service 管理使用：

igrep serve start
igrep serve open     # 在浏览器中登录 Web UI
igrep serve status
igrep serve stop

/api/* 与 /v1/* 始终需要 control token：首次启动时生成于 ~/.igreprc/control-token（仅属主可读），Web UI 用 igrep serve open 打开的一次性链接登录，其他 HTTP 客户端（VS Code 桥接、Dify）读取该文件。serve status 与 doctor 一样默认只报告；需要门禁语义时追加 --strict。

配置

配置优先级从高到低：

1. 当前进程的 IGREP_* 环境变量
2. <project>/.igrep/.env
3. ~/.igreprc/.env
4. OPENAI_*（只作为 LLM fallback）
5. 代码默认值

连接自管端点的最小示例：

IGREP_EMBEDDING_URL=http://localhost:8000/v1
IGREP_EMBED_MODEL=your-embedding-model

IGREP_LLM_URL=http://localhost:8000/v1
IGREP_LLM_MODEL=your-chat-model

IGREP_RERANK_URL=http://localhost:8000/v1
IGREP_RERANK_MODEL=your-reranker

OPENAI_API_KEY 是启用 LLM fallback 的锚点；OPENAI_BASE_URL 和 OPENAI_MODEL 只随它一起生效。Embedding、rerank 和 OCR 不读取 OPENAI_*。显式设置空的 IGREP_LLM_URL= 可禁用该 fallback 与共享 LLM 路由；igrep ask / chat / Ultra 的 late selector / mem maintain 走 IGREP_ASK_LLM_* 路由，单独配置了 IGREP_ASK_LLM_URL 时不受影响，要全部禁用需同时设 IGREP_ASK_LLM_URL=。Ultra 的 planner 与其他检索 LLM 阶段保留在 shared 路由，最终排序对 ask 模型敏感（同一语料下 R@10 可差 8pp）；当 ask 路由的模型是为其他用途（如 mem maintain）选的，用 IGREP_LLM_FINAL_SORT_MODEL（可配 _URL / _API_KEY / _EXTRA_BODY）只给最终排序换更强的模型。

凭证只放环境变量或 .env，不要写入 profile 或提交到仓库。IGREP_API_KEY 是全局 fallback；能力级 IGREP_LLM_API_KEY、IGREP_EMBEDDING_API_KEY、IGREP_RERANK_API_KEY 和 IGREP_OCR_API_KEY 可单独覆盖。完整配置契约见本地服务协议。

文档

• 文档导航
• 技术架构
• CLI 进程与机器输出契约
• 管理生命周期规范
• HTTP OpenAPI
• Agent 安装指南
• 记忆宿主接入指南

License

MIT