{
  "markdown": "# embgrep\n\n> [한국어 문서](README.ko.md) · [llms.txt](llms.txt)\n\n**Local semantic search — embedding-powered grep for files, zero external services.**\n\n[![PyPI](https://img.shields.io/pypi/v/embgrep)](https://pypi.org/project/embgrep/)\n[![Python](https://img.shields.io/pypi/pyversions/embgrep)](https://pypi.org/project/embgrep/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nSearch your codebase and documentation by *meaning*, not just keywords. embgrep indexes files into local embeddings and lets you run semantic queries — no API keys, no cloud services, no vector database servers.\n\n## Features\n\n- **Local embeddings** — Uses [fastembed](https://github.com/qdrant/fastembed) (ONNX Runtime), no API keys needed\n- **SQLite storage** — Single-file index, no external vector DB\n- **Incremental indexing** — Only re-indexes changed files (SHA-256 hash comparison)\n- **Smart chunking** — Function-level splitting for code, heading-level for docs\n- **MCP native** — 4-tool FastMCP server for LLM agent integration\n- **15+ file types** — `.py`, `.js`, `.ts`, `.java`, `.go`, `.rs`, `.md`, `.txt`, `.yaml`, `.json`, `.toml`, and more\n\n## Install\n\n```bash\npip install embgrep              # core (fastembed + numpy)\npip install embgrep[cli]         # + click/rich CLI\npip install embgrep[mcp]         # + FastMCP server\npip install embgrep[all]         # everything\n```\n\n## Quick Start\n\n### Python API\n\n```python\nfrom embgrep import EmbGrep\n\neg = EmbGrep()\n\n# Index a directory\neg.index(\"./my-project\", patterns=[\"*.py\", \"*.md\"])\n\n# Semantic search\nresults = eg.search(\"database connection pooling\", top_k=5)\nfor r in results:\n    print(f\"{r.file_path}:{r.line_start}-{r.line_end} (score: {r.score:.4f})\")\n    print(f\"  {r.chunk_text[:80]}...\")\n\n# Incremental update (only changed files)\neg.update()\n\n# Index statistics\nstatus = eg.status()\nprint(f\"{status.total_files} files, {status.total_chunks} chunks, {status.index_size_mb} MB\")\n\neg.close()\n```\n\n### CLI\n\n```bash\n# Index a project\nembgrep index ./my-project --patterns \"*.py,*.md\"\n\n# Search\nembgrep search \"error handling patterns\"\n\n# Filter by file type\nembgrep search \"async database query\" --path-filter \"%.py\"\n\n# Check status\nembgrep status\n\n# Update changed files\nembgrep update\n```\n\n### Convenience functions\n\n```python\nimport embgrep\n\nembgrep.index(\"./src\")\nresults = embgrep.search(\"authentication middleware\")\nstatus = embgrep.status()\nembgrep.update()\n```\n\n## MCP Server\n\nAdd to your Claude Desktop / MCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"embgrep\": {\n      \"command\": \"embgrep-mcp\"\n    }\n  }\n}\n```\n\nOr with uvx:\n\n```json\n{\n  \"mcpServers\": {\n    \"embgrep\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"embgrep[mcp]\", \"embgrep-mcp\"]\n    }\n  }\n}\n```\n\n### MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `index_directory` | Index files in a directory for semantic search |\n| `semantic_search` | Search indexed files using natural language |\n| `index_status` | Get current index statistics |\n| `update_index` | Incremental update — re-index changed files only |\n\n## How It Works\n\n```mermaid\nflowchart TD\n    A[\"📁 Files\"] --> B[\"Smart Chunking\\ncode: function-level\\ndocs: heading-level\"]\n    B --> C[\"fastembed\\nlocal embeddings\"]\n    C --> D[\"SQLite\\nvector index\"]\n    D --> E[\"🔍 Query\"]\n    E --> F[\"Cosine Similarity\\nranked results\"]\n    F --> G[\"✅ Matches\\nwith context\"]\n```\n\n1. **Chunking** — Files are split into semantically meaningful chunks:\n   - Code files (`.py`, `.js`, `.ts`, etc.): split by function/class boundaries\n   - Documents (`.md`, `.txt`): split by headings or paragraph breaks\n   - Config files: fixed-size chunking\n\n2. **Embedding** — Each chunk is converted to a 384-dimensional vector using [BGE-small-en-v1.5](https://huggingface.co/BAAI/bge-small-en-v1.5) via ONNX Runtime (no PyTorch needed)\n\n3. **Storage** — Embeddings are stored as BLOBs in a local SQLite database\n\n4. **Search** — Query text is embedded and compared against all chunks using cosine similarity\n\n## Configuration\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `db_path` | `~/.local/share/embgrep/embgrep.db` | SQLite database location |\n| `model` | `BAAI/bge-small-en-v1.5` | fastembed model name |\n| `max_chunk_size` | 1000 chars | Maximum chunk size for fixed-size splitting |\n| `top_k` | 5 | Number of search results |\n\n## QuartzUnit Ecosystem\n\n| Package | Description |\n|---------|-------------|\n| [markgrab](https://github.com/QuartzUnit/markgrab) | HTML/YouTube/PDF/DOCX to LLM-ready markdown |\n| [snapgrab](https://github.com/QuartzUnit/snapgrab) | URL to screenshot + metadata |\n| [docpick](https://github.com/QuartzUnit/docpick) | OCR + LLM document structure extraction |\n| [browsegrab](https://github.com/QuartzUnit/browsegrab) | Local LLM browser agent |\n| [feedkit](https://github.com/QuartzUnit/feedkit) | RSS feed collection + MCP |\n| **embgrep** | **Local semantic search for files** |\n\n## Used in\n\n- [newswatch](https://github.com/QuartzUnit/newswatch) — RSS news monitoring pipeline (feedkit → markgrab → embgrep → diffgrab)\n\n## License\n\nMIT\n\n<!-- mcp-name: io.github.QuartzUnit/embgrep -->\n\n\n---\n\n<sub>Part of the [QuartzUnit](https://github.com/QuartzUnit) ecosystem — composable Python libraries for data collection, extraction, search, and AI agent safety.</sub>\n",
  "bytes": 5377,
  "sha": "11c23cbb754f961065152373fba6ed28edb99d39afceab0786ca23a274668556",
  "repo_slug": "quartzunit/embgrep",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_arknill_embgrep_7043b92c/readme"
}