Embgrep

embgrep

韩文文档 · llms.txt

本地语义搜索——为文件提供由嵌入向量驱动的 grep，无需外部服务。

按含义而非仅按关键词搜索代码库和文档。embgrep 会将文件索引为本地嵌入向量，并支持语义查询——无需 API 密钥、云服务或向量数据库服务。

功能

• 本地嵌入向量 — 使用 fastembed（ONNX Runtime），无需 API 密钥
• SQLite 存储 — 单文件索引，无需外部向量数据库
• 增量索引 — 仅重新索引已更改的文件（通过 SHA-256 哈希值比较）
• 智能分块 — 代码按函数级别拆分，文档按标题级别拆分
• 原生支持 MCP — 提供 4 个工具的 FastMCP 服务，可集成 LLM Agent
• 支持 15 种以上文件类型 — .py、.js、.ts、.java、.go、.rs、.md、.txt、.yaml、.json、.toml 等

安装

pip install embgrep              # core (fastembed + numpy)
pip install embgrep[cli]         # + click/rich CLI
pip install embgrep[mcp]         # + FastMCP server
pip install embgrep[all]         # everything

快速开始

Python API

from embgrep import EmbGrep

eg = EmbGrep()

# Index a directory
eg.index("./my-project", patterns=["*.py", "*.md"])

# Semantic search
results = eg.search("database connection pooling", top_k=5)
for r in results:
    print(f"{r.file_path}:{r.line_start}-{r.line_end} (score: {r.score:.4f})")
    print(f"  {r.chunk_text[:80]}...")

# Incremental update (only changed files)
eg.update()

# Index statistics
status = eg.status()
print(f"{status.total_files} files, {status.total_chunks} chunks, {status.index_size_mb} MB")

eg.close()

CLI

# Index a project
embgrep index ./my-project --patterns "*.py,*.md"

# Search
embgrep search "error handling patterns"

# Filter by file type
embgrep search "async database query" --path-filter "%.py"

# Check status
embgrep status

# Update changed files
embgrep update

便捷函数

import embgrep

embgrep.index("./src")
results = embgrep.search("authentication middleware")
status = embgrep.status()
embgrep.update()

MCP 服务

将其添加到 Claude Desktop / MCP 客户端配置中：

{
  "mcpServers": {
    "embgrep": {
      "command": "embgrep-mcp"
    }
  }
}

也可以使用 uvx：

{
  "mcpServers": {
    "embgrep": {
      "command": "uvx",
      "args": ["--from", "embgrep[mcp]", "embgrep-mcp"]
    }
  }
}

MCP 工具

工具	描述
index_directory	为目录中的文件建立索引，以便进行语义搜索
semantic_search	使用自然语言搜索已建立索引的文件
index_status	获取当前索引统计信息
update_index	增量更新——仅重新索引已更改的文件

工作原理

flowchart TD
    A["📁 Files"] --> B["Smart Chunking\ncode: function-level\ndocs: heading-level"]
    B --> C["fastembed\nlocal embeddings"]
    C --> D["SQLite\nvector index"]
    D --> E["🔍 Query"]
    E --> F["Cosine Similarity\nranked results"]
    F --> G["✅ Matches\nwith context"]

1. 分块 — 将文件拆分为语义上有意义的块：

   • 代码文件（.py、.js、.ts 等）：按函数／类边界拆分
   • 文档（.md、.txt）：按标题或段落分隔符拆分
   • 配置文件：按固定大小分块

2. 嵌入 — 通过 ONNX Runtime 使用 BGE-small-en-v1.5 将每个块转换为 384 维向量（无需 PyTorch）

3. 存储 — 将嵌入向量作为 BLOB 存储在本地 SQLite 数据库中

4. 搜索 — 将查询文本转换为嵌入向量，并使用余弦相似度与所有块进行比较

配置

参数	默认值	描述
db_path	~/.local/share/embgrep/embgrep.db	SQLite 数据库位置
model	BAAI/bge-small-en-v1.5	fastembed 模型名称
max_chunk_size	1000 chars	固定大小拆分时的最大块大小
top_k	5	搜索结果数量

QuartzUnit 生态系统

软件包	描述
markgrab	将 HTML/YouTube/PDF/DOCX 转换为适用于 LLM 的 Markdown
snapgrab	将 URL 转换为截图和元数据
docpick	OCR + LLM 文档结构提取
browsegrab	本地 LLM 浏览器 Agent
feedkit	RSS 源收集 + MCP
embgrep	针对文件的本地语义搜索

使用于

• newswatch — RSS 新闻监控工作流（feedkit → markgrab → embgrep → diffgrab）

许可证

MIT

---

_{属于 QuartzUnit 生态系统——一系列可组合的 Python 库，用于数据收集、提取、搜索和 AI Agent 安全。}