igrep-tme 0.1.17

Agent-first semantic grep — filesystem-native retrieval

igrep

面向 Agent 时代的 semantic grep：像 grep 一样直接搜本地代码和文档，不预建索引；像 RAG 一样支持自然语言强召回和可引用证据。

产品主线：filesystem-native search-first retrieval。 Local-first，兼容云端 API；ask / chat / Web / VS Code / Obsidian 都复用同一检索内核。

特性

• Agent-first grep：零配置直接搜索，支持 glob / 文件类型 / git diff 过滤
• 强召回证据：自然语言查询先定位源码和文档证据，再交给 ask / chat 总结
• 本地多格式：Markdown、代码、PDF、Excel、PPT、图片 OCR 都进入同一搜索路径
• 单一检索内核：CLI、Web、MCP、VS Code、Obsidian、OpenClaw 只是不同 host，不分叉产品语义

产品边界

igrep 不是通用 RAG 平台。igrep search 是主入口；igrep ask / igrep chat 是搜索后的带引用总结；igrep serve 和各类编辑器插件是管理与 host 层，不改变检索语义。

召回性能

公开 benchmark 测试集的 Recall@10 召回率：

Benchmark	任务类型	召回率
HotpotQA	多跳问答	99%
MuSiQue	深层多跳问答（2-4 跳）	73.4%
SWE-bench Verified	代码文件定位	91.5%

安装

安装 igrep

curl -fsSL https://cnb.tmeoa.com/chatops/igrep-setup/-/git/raw/master/setup.sh | bash

macOS（Apple Silicon）

igrep setup

Linux

编辑 ~/.igreprc/.env 配置 AI 端点：

IGREP_EMBEDDING_URL=http://your-embed-server/v1   # 必需
IGREP_EMBED_MODEL=your-embed-model
IGREP_LLM_URL=http://your-llm-server/v1           # 推荐
IGREP_RERANK_URL=http://your-rerank-server/v1     # 推荐

快速开始

# 搜当前目录
igrep search "部署流程"

# 搜指定目录
igrep search "query" ~/my-repo

# 只搜 Python 文件
igrep search "query" . -g 'src/**/*.py'

# 只搜 git 变更文件
igrep search "query" --diff

# 搜索 + LLM 总结（带引用）
igrep ask "部署流程是怎样的" ~/my-repo

# 纯 web 搜索（独立于本地搜索）
igrep web-search "OAuth best practices"
igrep isearch "OAuth best practices" -s web  # 兼容入口，同 web-search

# 内部 MCP 搜索（iWiki / KM / TAPD / Gongfeng）
export IGREP_TAI_PAT_TOKEN='tai_pat_xxx'
# 可选：写入 ~/.igreprc/.env 或 <project>/.igrep/.env，逗号分隔多个默认范围
# IGREP_IWIKI_SPACES=4011148431,1188855927
# IGREP_TAPD_WORKSPACES=10088931
igrep isearch "缓存一致性" --source km
igrep isearch "支付失败 重试" --source tapd --workspace 755
igrep isearch "vector search" --source gongfeng

# 本地管理台（项目 / 搜索 / 聊天）
igrep serve run

Tip: igrep "多词查询" 省略 search 也行，但单词查询可能与子命令冲突（如 index）， 建议始终写 igrep search "query" 或 igrep -- "query"。

常用命令

# 搜索
igrep search "query" [path...]       # 默认搜当前目录
igrep search "query" -g 'src/**/*.py' # 按 glob 过滤（支持 !pattern 排除）
igrep search "query" --type md       # 只搜某类文件
igrep search "query" --diff [REF]    # 只搜 git 变更文件
igrep search "query" -C 5           # 上下文行数
igrep search "query" -m 50          # 最大结果数
igrep search "query" --format json  # JSON 输出

# 搜索 + LLM 总结
igrep ask "query" ~/my-repo          # 自然语言回答，带引用
igrep ask "query" --json             # JSON 输出

# Web 搜索（独立子命令，与本地搜索完全分离）
igrep web-search "query"              # 纯 web 搜索
igrep web-search "query" --mode normal  # 复用 fast/normal/ultra 质量档
igrep isearch "query" -s web          # 兼容入口，同 web-search

# 内部搜索（内建 iWiki / KM / TAPD story / Gongfeng project source）
export IGREP_TAI_PAT_TOKEN='tai_pat_xxx'
# 可选默认范围：IGREP_IWIKI_SPACES=4011148431,1188855927
# 可选默认范围：IGREP_TAPD_WORKSPACES=10088931
igrep isearch "query" --source iwiki --space KgMesh
igrep isearch "query" --source tapd  # 使用 IGREP_TAPD_WORKSPACES 默认范围
igrep isearch "query" --source km --filter tag=AI
igrep isearch "query" --source tapd --workspace 755
igrep isearch "query" --source gongfeng --filter type=GIT

# 诊断
igrep doctor

配合 Codex 使用

让 Codex CLI 把 igrep 当成一等检索工具，两步搞定：

# 1) 安装 Skill（教 Codex 什么时候该用 igrep）
#    写入 ~/.codex/skills/igrep/SKILL.md
igrep skill install --target codex

# 2) 安装 MCP Server（把 search 作为工具暴露给 Codex）
#    写入 ~/.codex/config.toml 的 [mcp_servers.igrep]
igrep mcp install --target codex

只想针对单个仓库启用（写到 ./.codex/config.toml）：

igrep mcp install --target codex --scope project

预览配置不落盘：

igrep mcp install --target codex --dry-run
igrep skill install --target codex --dry-run

安装完成后，在 Codex CLI 里直接提问即可：

• "在当前仓库里找一下鉴权流程的实现"
• "搜一下 retry 相关的逻辑"
• "看看这份 PDF 里关于部署的部分"

Codex 会自动调用 mcp_servers.igrep 的 search 工具，而不是退化成 grep/rg 的字面匹配。

需要先完成上面的「安装 igrep」步骤，确保 igrep 和 igrep-mcp 在 PATH 中。

配合 Claude Code 使用

一键安装（MCP + 两个 skill + PreToolUse 钩子 + 项目级 CLAUDE.md 注入）：

igrep setup claude-code                         # 全套（推荐）
igrep setup claude-code --no-hooks              # 跳过 settings.json 里的 PreToolUse 钩子
igrep setup claude-code --no-memory-md          # 跳过 ./CLAUDE.md 注入
igrep setup claude-code --uninstall-hooks       # 只移除钩子
igrep setup claude-code --uninstall-memory-md   # 只移除 ./CLAUDE.md 里的 igrep 块

五样产物（都幂等，重跑只刷新）：

• ~/.claude.json 的 mcpServers.igrep
• ~/.claude/skills/igrep/SKILL.md（CLI 路径 skill）
• ~/.claude/skills/igrep-search/SKILL.md（MCP 路由 skill — pre-loaded 绕开 deferred-tool 瓶颈）
• ~/.claude/settings.json 里的 PreToolUse 钩子（Bash|Grep 匹配器，gated on .igrep/ 索引）
• ./CLAUDE.md 里 <!-- igrep:memory-md:start --> … <!-- igrep:memory-md:end --> 之间的路由块（marker-bounded，块外字节原样保留）

分步写法仍然可用：

igrep skill install --target claude   # ~/.claude/skills/igrep/SKILL.md
igrep mcp install --target claude     # ~/.claude.json 的 mcpServers.igrep
igrep mcp install --target claude --scope project   # 项目级 ./.mcp.json

详细说明 + 对比：integrations/claude-code/README.md。

多 agent 平台 — 一键 setup

每个平台都有自己的 igrep setup <platform> 聚合命令，默认装全套（MCP + skill + 适用时的 hook + 项目级 memory-md 注入），--no-<step> 按需跳过，--uninstall-<step> 单独回滚：

igrep setup codex       # MCP + skill + Codex PreToolUse hook + AGENTS.md
igrep setup codebuddy   # MCP + skill + AGENTS.md
igrep setup opencode    # MCP + OpenCode system-context 插件 + AGENTS.md
igrep setup cursor      # MCP + .cursor/rules/igrep-search.mdc
igrep setup gemini      # MCP + GEMINI.md
igrep setup copilot     # 仅 MCP（Copilot CLI 无 skill / memory-md 通道）

各平台能力矩阵：

平台	MCP 配置	Skill / 规则	项目 memory-md	Hook / 插件
Claude Code	~/.claude.json / .mcp.json	~/.claude/skills/igrep{,-search}/SKILL.md	CLAUDE.md	✅ (Bash|Grep)
Codex CLI	~/.codex/config.toml	~/.codex/skills/igrep/SKILL.md	AGENTS.md	✅ (Bash)
CodeBuddy	~/.codebuddy/.mcp.json / .mcp.json	~/.codebuddy/skills/igrep/SKILL.md	AGENTS.md	❌
OpenCode	~/.config/opencode/opencode.json (mcp.igrep)	—（使用插件）	AGENTS.md	✅ (experimental.chat.system.transform)
Cursor	~/.cursor/mcp.json / .cursor/mcp.json	.cursor/rules/igrep-search.mdc (项目级)	—	❌
Gemini CLI	~/.gemini/settings.json	—	GEMINI.md	❌
Copilot CLI	~/.copilot/mcp-config.json / .mcp.json	—	—	❌

memory-md 注入用 HTML-comment sentinels（<!-- igrep:memory-md:start/end -->），再次 setup 仅刷新块内容，块外字节原样保留；--uninstall-memory-md 线性扫描 sentinel 精确移除，既不误删用户内容也不留孤块。

MCP 路由指令的 SSoT 在 skills/igrep-search/SKILL.md；如果手工嵌入也可以：

igrep skill render --format agents-md >> AGENTS.md              # Codex / OpenCode / CodeBuddy
igrep skill render --format cursor-rule -o .cursor/rules/igrep-search.mdc
igrep skill render --format gemini >> GEMINI.md
igrep skill render --format raw                                 # 纯 body，自行嵌入
igrep skill render --format claude                              # 完整 SKILL.md

其他集成

• Web Control Plane：igrep serve run（项目 / 搜索 / 聊天）
• Obsidian：igrep setup obsidian
• VS Code：igrep setup vscode
• OpenClaw：igrep setup openclaw
• 通用 AgentSkills 导出：igrep skill install --target agentskills 或 igrep skill export -o igrep-skill.zip
• Aider：无 MCP 通道，手工追加 igrep skill render --format agents-md >> AGENTS.md 即可（未提供专用 setup aider）

License

MIT