Embgrep

embgrep

韓国語ドキュメント · llms.txt

ローカルセマンティック検索 — ファイル向けの埋め込みベースの grep。外部サービスは不要です。

キーワードだけでなく、意味に基づいてコードベースやドキュメントを検索できます。embgrep はファイルをローカルの埋め込みベクトルとしてインデックス化し、セマンティック検索を実行できます。API キーもクラウドサービスもベクトルデータベースサーバーも必要ありません。

機能

• ローカル埋め込み — fastembed（ONNX Runtime）を使用するため、API キーは不要です
• SQLite ストレージ — 単一ファイルのインデックスで、外部のベクトルデータベースは不要です
• 差分インデックス作成 — 変更されたファイルのみを再インデックス化します（SHA-256 ハッシュ比較）
• スマートなチャンク分割 — コードは関数単位、ドキュメントは見出し単位で分割します
• MCP ネイティブ — LLM エージェントと連携する 4 ツール対応の FastMCP サーバー
• 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. 保存 — 埋め込みベクトルはローカルの SQLite データベースに BLOB として保存されます

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 のブラウザーエージェント
feedkit	RSS フィードの収集と MCP
embgrep	ファイル向けのローカルセマンティック検索

使用例

• newswatch — RSS ニュース監視パイプライン（feedkit → markgrab → embgrep → diffgrab）

ライセンス

MIT

---

_{QuartzUnit エコシステムの一部です。データ収集、抽出、検索、AI エージェントの安全性に対応する、組み合わせ可能な Python ライブラリを提供します。}