{"id":37345983,"url":"https://github.com/tomohiro-owada/devrag","last_synced_at":"2026-04-05T01:02:40.248Z","repository":{"id":320638725,"uuid":"1082455641","full_name":"tomohiro-owada/devrag","owner":"tomohiro-owada","description":"Markdown vector search MCP server for Claude Code. Natural language search for markdown files using multilingual-e5-small embeddings.","archived":false,"fork":false,"pushed_at":"2026-03-27T03:13:43.000Z","size":11431,"stargazers_count":42,"open_issues_count":2,"forks_count":10,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-27T04:59:10.353Z","etag":null,"topics":["claude-code","developer-tools","documentation","embeddings","golang","local-ai","markdown","mcp","onnx","rag","semantic-search","sqlite","vector-search"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tomohiro-owada.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-24T09:10:57.000Z","updated_at":"2026-03-27T03:13:40.000Z","dependencies_parsed_at":"2025-10-25T00:36:31.749Z","dependency_job_id":null,"html_url":"https://github.com/tomohiro-owada/devrag","commit_stats":null,"previous_names":["tomohiro-owada/markdown-vector-mcp"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/tomohiro-owada/devrag","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomohiro-owada%2Fdevrag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomohiro-owada%2Fdevrag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomohiro-owada%2Fdevrag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomohiro-owada%2Fdevrag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomohiro-owada","download_url":"https://codeload.github.com/tomohiro-owada/devrag/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomohiro-owada%2Fdevrag/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31307466,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","developer-tools","documentation","embeddings","golang","local-ai","markdown","mcp","onnx","rag","semantic-search","sqlite","vector-search"],"created_at":"2026-01-16T03:58:38.827Z","updated_at":"2026-04-02T14:03:39.908Z","avatar_url":"https://github.com/tomohiro-owada.png","language":"Go","readme":"# DevRag\n\n**Free Local RAG for Claude Code - Save Tokens \u0026 Time**\n\n[日本語版はこちら](#日本語版) | [Japanese Version](#日本語版)\n\nDevRag is a lightweight RAG (Retrieval-Augmented Generation) system designed specifically for developers using Claude Code. Stop wasting tokens by reading entire documents - let vector search find exactly what you need.\n\n## Why DevRag?\n\nWhen using Claude Code, reading documents with the Read tool consumes massive amounts of tokens:\n\n- ❌ **Wasting Context**: Reading entire docs every time (3,000+ tokens per file)\n- ❌ **Poor Searchability**: Claude doesn't know which file contains what\n- ❌ **Repetitive**: Same documents read multiple times across sessions\n\n**With DevRag:**\n\n- ✅ **40x Less Tokens**: Vector search retrieves only relevant chunks (~200 tokens)\n- ✅ **15x Faster**: Search in 100ms vs 30 seconds of reading\n- ✅ **Auto-Discovery**: Claude Code finds documents without knowing file names\n\n## Features\n\n- 🤖 **Simple RAG** - Retrieval-Augmented Generation for Claude Code\n- 📝 **Markdown Support** - Auto-indexes .md files\n- 🔍 **Semantic Search** - Natural language queries like \"JWT authentication method\"\n- 🚀 **Single Binary** - No Python, models auto-download on first run\n- 💻 **CLI \u0026 MCP** - Use as MCP server or standalone CLI commands\n- 🖥️ **Cross-Platform** - macOS / Linux / Windows\n- ⚡ **Fast** - Auto GPU/CPU detection, incremental sync\n- 🌐 **Multilingual** - Supports 100+ languages including Japanese \u0026 English\n\n## Quick Start\n\n### 1. Download Binary\n\nGet the appropriate binary from [Releases](https://github.com/tomohiro-owada/devrag/releases):\n\n| Platform | File |\n|----------|------|\n| macOS (Apple Silicon) | `devrag-macos-apple-silicon.tar.gz` |\n| macOS (Intel) | `devrag-macos-intel.tar.gz` |\n| Linux (x64) | `devrag-linux-x64.tar.gz` |\n| Linux (ARM64) | `devrag-linux-arm64.tar.gz` |\n| Windows (x64) | `devrag-windows-x64.zip` |\n\n**macOS/Linux:**\n```bash\ntar -xzf devrag-*.tar.gz\nchmod +x devrag-*\nsudo mv devrag-* /usr/local/bin/\n```\n\n\u003e **Note**: macOS releases include `libonnxruntime.dylib` for CoreML GPU acceleration. Keep it in the same directory as the `devrag` binary.\n\n**Windows:**\n- Extract the zip file\n- Place in your preferred location (e.g., `C:\\Program Files\\devrag\\`)\n\n### 2. Configure Claude Code\n\nAdd to `~/.claude.json` or `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"devrag\": {\n      \"type\": \"stdio\",\n      \"command\": \"/usr/local/bin/devrag\"\n    }\n  }\n}\n```\n\n**Using a custom config file:**\n```json\n{\n  \"mcpServers\": {\n    \"devrag\": {\n      \"type\": \"stdio\",\n      \"command\": \"/usr/local/bin/devrag\",\n      \"args\": [\"--config\", \"/path/to/custom-config.json\"]\n    }\n  }\n}\n```\n\n### 3. Add Your Documents\n\n```bash\nmkdir documents\ncp your-notes.md documents/\n```\n\nThat's it! Documents are automatically indexed on startup.\n\n### 4. Search with Claude Code\n\nIn Claude Code:\n```\n\"Search for JWT authentication methods\"\n```\n\n## Configuration\n\nCreate `config.json`:\n\n```json\n{\n  \"document_patterns\": [\n    \"./documents\",\n    \"./notes/**/*.md\",\n    \"./projects/backend/**/*.md\"\n  ],\n  \"db_path\": \"./vectors.db\",\n  \"chunk_size\": 500,\n  \"search_top_k\": 5,\n  \"compute\": {\n    \"device\": \"auto\",\n    \"fallback_to_cpu\": true\n  },\n  \"model\": {\n    \"name\": \"multilingual-e5-small\",\n    \"dimensions\": 384\n  }\n}\n```\n\n### Configuration Options\n\n- `document_patterns`: Array of document paths and glob patterns\n  - Supports directory paths: `\"./documents\"`\n  - Supports glob patterns: `\"./docs/**/*.md\"` (recursive)\n  - Multiple patterns: Index files from different locations\n  - **Note**: Old `documents_dir` field is still supported (automatically migrated)\n- `db_path`: Vector database file path\n- `chunk_size`: Document chunk size in characters\n- `search_top_k`: Number of search results to return\n- `compute.device`: Compute device (`auto`, `cpu`, `gpu`)\n- `compute.fallback_to_cpu`: Fallback to CPU if GPU unavailable\n- `model.name`: Embedding model name\n- `model.dimensions`: Vector dimensions\n\n### Command-Line Options\n\n- `--config \u003cpath\u003e`: Specify a custom configuration file path (default: `config.json`)\n\n**Example:**\n```bash\ndevrag --config /path/to/custom-config.json\n```\n\nThis is useful for:\n- Running multiple instances with different configurations\n- Testing different models or chunk sizes\n- Maintaining separate dev/test/prod configurations\n\n### Pattern Examples\n\n```json\n{\n  \"document_patterns\": [\n    \"./documents\",                    // All .md files in documents/\n    \"./notes/**/*.md\",                // Recursive search in notes/\n    \"./projects/*/docs/*.md\",         // docs/ in each project\n    \"/path/to/external/docs\"          // Absolute path\n  ]\n}\n```\n\n## MCP Tools\n\nDevRag provides the following tools via Model Context Protocol:\n\n### search\nPerform semantic vector search with optional filtering\n\n**Parameters:**\n- `query` (string, required): Search query in natural language\n- `top_k` (number, optional): Maximum number of results (default: 5)\n- `directory` (string, optional): Filter to specific directory (e.g., \"docs/api\")\n- `file_pattern` (string, optional): Glob pattern for filename (e.g., \"api-*.md\", \"*.md\")\n\n**Returns:**\nArray of search results with filename, chunk content, and similarity score\n\n**Examples:**\n```\n// Basic search\nsearch(query: \"JWT authentication\")\n\n// Search only in docs/api directory\nsearch(query: \"user endpoints\", directory: \"docs/api\")\n\n// Search only files matching pattern\nsearch(query: \"deployment\", file_pattern: \"guide-*.md\")\n\n// Combined filters\nsearch(query: \"authentication\", directory: \"docs/api\", file_pattern: \"auth*.md\")\n```\n\n### index_markdown\nIndex a markdown file\n\n**Parameters:**\n- `filepath` (string): Path to the file to index\n\n### list_documents\nList all indexed documents\n\n**Returns:**\nDocument list with filenames and timestamps\n\n### delete_document\nRemove a document from the index\n\n**Parameters:**\n- `filepath` (string): Path to the file to delete\n\n### reindex_document\nRe-index a document\n\n**Parameters:**\n- `filepath` (string): Path to the file to re-index\n\n## CLI Usage\n\nDevRag can also be used as a standalone CLI tool. All MCP tools are available as CLI commands.\n\n```bash\n# Start MCP server (default)\ndevrag\ndevrag serve\n\n# Search documents\ndevrag search \"JWT authentication\"\ndevrag search \"deployment\" --top-k 10 --directory docs/api\n\n# Index files\ndevrag index ./docs/api-spec.md\ndevrag index-code --directory ./src\n\n# List indexed documents\ndevrag list\ndevrag list --fields filename\n\n# Delete / Reindex\ndevrag delete ./docs/old-spec.md --dry-run\ndevrag reindex ./docs/updated-spec.md\n\n# Code symbol relations\ndevrag search-relations handleAuth --type calls\n\n# Build dictionary (Japanese-English mapping)\ndevrag build-dictionary\n\n# Show CLI schema (machine-readable)\ndevrag schema\n```\n\n### Output Format\n\nAll commands output JSON by default. Use `--output text` for human-readable output.\n\n```bash\n# JSON (default, suitable for scripts and AI agents)\ndevrag search \"authentication\"\n\n# Text (human-readable)\ndevrag search \"authentication\" --output text\n```\n\n### MCP Tool Name Compatibility\n\nCLI commands also accept MCP tool names with underscores:\n\n```bash\ndevrag index_markdown ./docs/api.md    # same as: devrag index\ndevrag list_documents                  # same as: devrag list\ndevrag delete_document ./docs/old.md   # same as: devrag delete\ndevrag reindex_document ./docs/api.md  # same as: devrag reindex\n```\n\n### Flag Syntax\n\nFlags must be placed **before** positional arguments:\n\n```bash\n# Correct\ndevrag delete --dry-run file.md\n\n# Incorrect (--dry-run is ignored)\ndevrag delete file.md --dry-run\n```\n\n## Team Development\n\nPerfect for teams with large documentation repositories:\n\n1. **Manage docs in Git**: Normal Git workflow\n2. **Each developer runs DevRag**: Local setup on each machine\n3. **Search via Claude Code**: Everyone can search all docs\n4. **Auto-sync**: `git pull` automatically updates the index\n\nConfigure for your project's docs directory:\n\n```json\n{\n  \"document_patterns\": [\n    \"./docs\",\n    \"./api-docs/**/*.md\",\n    \"./wiki/**/*.md\"\n  ],\n  \"db_path\": \"./.devrag/vectors.db\"\n}\n```\n\n## Performance\n\nEnvironment: MacBook Pro M2, 100 files (1MB total)\n\n| Operation | Time | Tokens |\n|-----------|------|--------|\n| Startup | 2.3s | - |\n| Indexing | 8.5s | - |\n| Search (1 query) | 95ms | ~300 |\n| Traditional Read | 25s | ~12,000 |\n\n**260x faster search, 40x fewer tokens**\n\n## Development\n\n### Run Tests\n\n```bash\n# All tests\ngo test ./...\n\n# Specific packages\ngo test ./internal/config -v\ngo test ./internal/indexer -v\ngo test ./internal/embedder -v\ngo test ./internal/vectordb -v\n\n# Integration tests\ngo test . -v -run TestEndToEnd\n```\n\n### Build\n\n```bash\n# Using build script\n./build.sh\n\n# Direct build\ngo build -o devrag cmd/main.go\n\n# Cross-platform release build\n./scripts/build-release.sh\n```\n\n### Creating a Release\n\n```bash\n# Create version tag\ngit tag v1.0.1\n\n# Push tag\ngit push origin v1.0.1\n```\n\nGitHub Actions automatically:\n1. Builds for all platforms\n2. Creates GitHub Release\n3. Uploads binaries\n4. Generates checksums\n\n## Project Structure\n\n```\ndevrag/\n├── cmd/\n│   └── main.go              # Entry point\n├── internal/\n│   ├── cli/                 # CLI commands\n│   ├── config/              # Configuration\n│   ├── embedder/            # Vector embeddings\n│   ├── indexer/             # Indexing logic\n│   ├── mcp/                 # MCP server\n│   └── vectordb/            # Vector database\n├── models/                  # ONNX models\n├── build.sh                 # Build script\n└── integration_test.go      # Integration tests\n```\n\n## Troubleshooting\n\n### Model Download Fails\n\n**Cause**: Internet connection or Hugging Face server issues\n\n**Solutions**:\n1. Check internet connection\n2. For proxy environments:\n   ```bash\n   export HTTP_PROXY=http://your-proxy:port\n   export HTTPS_PROXY=http://your-proxy:port\n   ```\n3. Manual download (see `models/DOWNLOAD.md`)\n4. Retry (incomplete files are auto-removed)\n\n### GPU / CoreML Not Working\n\nOn macOS, DevRag uses Apple CoreML for GPU/Neural Engine acceleration. Requirements:\n- `libonnxruntime.dylib` must be in the same directory as the `devrag` binary\n- macOS releases from GitHub include this file automatically\n\nIf CoreML is not available, DevRag falls back to CPU automatically. To tune performance:\n```bash\n# Adjust CPU thread count (default: 4)\nDEVRAG_THREADS=4 devrag\n```\n\nTo explicitly force CPU mode:\n```json\n{\n  \"compute\": {\n    \"device\": \"cpu\",\n    \"fallback_to_cpu\": true\n  }\n}\n```\n\n### Won't Start\n\n- Ensure Go 1.21+ is installed (for building)\n- Check CGO is enabled: `go env CGO_ENABLED`\n- Verify dependencies are installed\n- Internet required for first run (model download)\n\n### Unexpected Search Results\n\n- Adjust `chunk_size` (default: 500)\n- Rebuild index (delete vectors.db and restart)\n\n### High Memory Usage\n\n- GPU mode loads model into VRAM\n- Switch to CPU mode for lower memory usage\n\n## Requirements\n\n- Go 1.21+ (for building from source)\n- CGO enabled (for sqlite-vec)\n- macOS, Linux, or Windows\n\n## License\n\nMIT License\n\n## Credits\n\n- Embedding Model: [intfloat/multilingual-e5-small](https://huggingface.co/intfloat/multilingual-e5-small)\n- Vector Database: [sqlite-vec](https://github.com/asg017/sqlite-vec)\n- MCP Protocol: [Model Context Protocol](https://modelcontextprotocol.io/)\n- ONNX Runtime: [onnxruntime-go](https://github.com/yalue/onnxruntime_go)\n\n## Contributing\n\nIssues and Pull Requests are welcome!\n\n## Contributors\n\nSpecial thanks to all contributors who helped improve DevRag:\n\n- **[@badri](https://github.com/badri)** - Multiple document paths with glob patterns ([#2](https://github.com/tomohiro-owada/devrag/pull/2)), `--config` CLI flag ([#3](https://github.com/tomohiro-owada/devrag/pull/3))\n- **[@io41](https://github.com/io41)** - Project cleanup and documentation improvements ([#4](https://github.com/tomohiro-owada/devrag/pull/4))\n\nYour contributions make DevRag better for everyone!\n\n## Author\n\n[towada](https://github.com/tomohiro-owada)\n\n---\n\n# 日本語版\n\n**Claude Code用の無料ローカルRAG - トークン＆時間を節約**\n\nDevRagは、Claude Codeを使う開発者のための軽量RAG（Retrieval-Augmented Generation）システムです。ドキュメント全体を読み込んでトークンを無駄にするのをやめて、ベクトル検索で必要な情報だけを取得しましょう。\n\n## なぜDevRagが必要か？\n\nClaude Codeでドキュメントを読み込むと、大量のトークンを消費します：\n\n- ❌ **コンテキストの浪費**: 毎回ドキュメント全体を読み込み（1ファイル3,000トークン以上）\n- ❌ **検索性の欠如**: Claudeはどのファイルに何が書いてあるか知らない\n- ❌ **繰り返し**: セッションをまたいで同じドキュメントを何度も読む\n\n**DevRagを使えば:**\n\n- ✅ **トークン消費1/40**: ベクトル検索で必要な部分だけ取得（約200トークン）\n- ✅ **15倍高速**: 検索100ms vs 読み込み30秒\n- ✅ **自動発見**: ファイル名を知らなくてもClaude Codeが見つける\n\n## 特徴\n\n- 🤖 **簡易RAG** - Claude Code用の検索拡張生成\n- 📝 **マークダウン対応** - .mdファイルを自動インデックス化\n- 🔍 **意味検索** - 「JWTの認証方法」のような自然言語クエリ\n- 🚀 **ワンバイナリー** - Python不要、モデルは初回起動時に自動ダウンロード\n- 💻 **CLI \u0026 MCP** - MCPサーバーとしても、CLIコマンドとしても使える\n- 🖥️ **クロスプラットフォーム** - macOS / Linux / Windows\n- ⚡ **高速** - GPU/CPU自動検出、差分同期\n- 🌐 **多言語** - 日本語・英語を含む100以上の言語対応\n\n## クイックスタート\n\n### 1. バイナリダウンロード\n\n[Releases](https://github.com/tomohiro-owada/devrag/releases)から環境に合ったファイルをダウンロード：\n\n| プラットフォーム | ファイル |\n|----------|------|\n| macOS (Apple Silicon) | `devrag-macos-apple-silicon.tar.gz` |\n| macOS (Intel) | `devrag-macos-intel.tar.gz` |\n| Linux (x64) | `devrag-linux-x64.tar.gz` |\n| Linux (ARM64) | `devrag-linux-arm64.tar.gz` |\n| Windows (x64) | `devrag-windows-x64.zip` |\n\n**macOS/Linux:**\n```bash\ntar -xzf devrag-*.tar.gz\nchmod +x devrag-*\nsudo mv devrag-* /usr/local/bin/\n```\n\n\u003e **注意**: macOS版リリースにはCoreML GPU高速化用の`libonnxruntime.dylib`が含まれています。`devrag`バイナリと同じディレクトリに配置してください。\n\n**Windows:**\n- zipファイルを解凍\n- 任意の場所に配置（例: `C:\\Program Files\\devrag\\`）\n\n### 2. Claude Code設定\n\n`~/.claude.json` または `.mcp.json` に追加：\n\n```json\n{\n  \"mcpServers\": {\n    \"devrag\": {\n      \"type\": \"stdio\",\n      \"command\": \"/usr/local/bin/devrag\"\n    }\n  }\n}\n```\n\n**カスタム設定ファイルを使用する場合:**\n```json\n{\n  \"mcpServers\": {\n    \"devrag\": {\n      \"type\": \"stdio\",\n      \"command\": \"/usr/local/bin/devrag\",\n      \"args\": [\"--config\", \"/path/to/custom-config.json\"]\n    }\n  }\n}\n```\n\n### 3. ドキュメントを配置\n\n```bash\nmkdir documents\ncp your-notes.md documents/\n```\n\nこれで完了！起動時に自動的にインデックス化されます。\n\n### 4. Claude Codeで検索\n\nClaude Codeで：\n```\n「JWTの認証方法について検索して」\n```\n\n## 設定\n\n`config.json`を作成：\n\n```json\n{\n  \"document_patterns\": [\n    \"./documents\",\n    \"./notes/**/*.md\",\n    \"./projects/backend/**/*.md\"\n  ],\n  \"db_path\": \"./vectors.db\",\n  \"chunk_size\": 500,\n  \"search_top_k\": 5,\n  \"compute\": {\n    \"device\": \"auto\",\n    \"fallback_to_cpu\": true\n  },\n  \"model\": {\n    \"name\": \"multilingual-e5-small\",\n    \"dimensions\": 384\n  }\n}\n```\n\n### 設定項目\n\n- `document_patterns`: ドキュメントのパスとglobパターンの配列\n  - ディレクトリパス対応: `\"./documents\"`\n  - globパターン対応: `\"./docs/**/*.md\"` (再帰的)\n  - 複数パターン: 異なる場所からファイルをインデックス化\n  - **注意**: 旧形式の`documents_dir`もサポート（自動的に移行）\n- `db_path`: ベクトルデータベースのパス\n- `chunk_size`: ドキュメントのチャンクサイズ（文字数）\n- `search_top_k`: 検索結果の返却件数\n- `compute.device`: 計算デバイス（`auto`, `cpu`, `gpu`）\n- `compute.fallback_to_cpu`: GPU利用不可時にCPUにフォールバック\n- `model.name`: 埋め込みモデル名\n- `model.dimensions`: ベクトル次元数\n\n### コマンドラインオプション\n\n- `--config \u003cpath\u003e`: カスタム設定ファイルのパスを指定（デフォルト: `config.json`）\n\n**使用例:**\n```bash\ndevrag --config /path/to/custom-config.json\n```\n\nこれは以下の用途で便利です：\n- 異なる設定で複数のインスタンスを実行\n- 異なるモデルやチャンクサイズをテスト\n- 開発/テスト/本番環境の設定を分離\n\n### パターン例\n\n```json\n{\n  \"document_patterns\": [\n    \"./documents\",                    // documents/内の全.mdファイル\n    \"./notes/**/*.md\",                // notes/内を再帰的に検索\n    \"./projects/*/docs/*.md\",         // 各プロジェクトのdocs/\n    \"/path/to/external/docs\"          // 絶対パス\n  ]\n}\n```\n\n## MCPツール\n\nModel Context Protocolを通じて以下のツールを提供：\n\n### search\nフィルター機能付き意味ベクトル検索を実行\n\n**パラメータ:**\n- `query` (string, 必須): 自然言語の検索クエリ\n- `top_k` (number, 任意): 最大結果数（デフォルト: 5）\n- `directory` (string, 任意): 特定ディレクトリに絞り込み（例: \"docs/api\"）\n- `file_pattern` (string, 任意): ファイル名のglobパターン（例: \"api-*.md\", \"*.md\"）\n\n**戻り値:**\nファイル名、チャンク内容、類似度スコアを含む検索結果の配列\n\n**使用例:**\n```\n// 基本検索\nsearch(query: \"JWT認証\")\n\n// docs/apiディレクトリ内のみ検索\nsearch(query: \"ユーザーエンドポイント\", directory: \"docs/api\")\n\n// パターンに一致するファイルのみ検索\nsearch(query: \"デプロイ\", file_pattern: \"guide-*.md\")\n\n// フィルターの組み合わせ\nsearch(query: \"認証\", directory: \"docs/api\", file_pattern: \"auth*.md\")\n```\n\n### index_markdown\nマークダウンファイルをインデックス化\n\n**パラメータ:**\n- `filepath` (string): インデックス化するファイルのパス\n\n### list_documents\nインデックス化されたドキュメントの一覧を取得\n\n**戻り値:**\nファイル名とタイムスタンプを含むドキュメントリスト\n\n### delete_document\nドキュメントをインデックスから削除\n\n**パラメータ:**\n- `filepath` (string): 削除するファイルのパス\n\n### reindex_document\nドキュメントを再インデックス化\n\n**パラメータ:**\n- `filepath` (string): 再インデックス化するファイルのパス\n\n## CLI使用方法\n\nDevRagはスタンドアロンのCLIツールとしても使用できます。すべてのMCPツールがCLIコマンドとして利用可能です。\n\n```bash\n# MCPサーバーを起動（デフォルト）\ndevrag\ndevrag serve\n\n# ドキュメントを検索\ndevrag search \"JWT認証\"\ndevrag search \"デプロイ\" --top-k 10 --directory docs/api\n\n# ファイルをインデックス化\ndevrag index ./docs/api-spec.md\ndevrag index-code --directory ./src\n\n# インデックス済みドキュメント一覧\ndevrag list\ndevrag list --fields filename\n\n# 削除 / 再インデックス\ndevrag delete ./docs/old-spec.md --dry-run\ndevrag reindex ./docs/updated-spec.md\n\n# コードシンボル関係検索\ndevrag search-relations handleAuth --type calls\n\n# 辞書ビルド（日本語→英語マッピング）\ndevrag build-dictionary\n\n# CLIスキーマ表示（機械可読）\ndevrag schema\n```\n\n### 出力形式\n\n全コマンドはデフォルトでJSONを出力します。`--output text`で人間が読みやすい形式になります。\n\n```bash\n# JSON（デフォルト、スクリプトやAIエージェント向け）\ndevrag search \"認証\"\n\n# テキスト（人間向け）\ndevrag search \"認証\" --output text\n```\n\n### MCPツール名との互換性\n\nCLIコマンドはアンダースコア形式のMCPツール名でも動作します：\n\n```bash\ndevrag index_markdown ./docs/api.md    # devrag index と同じ\ndevrag list_documents                  # devrag list と同じ\ndevrag delete_document ./docs/old.md   # devrag delete と同じ\ndevrag reindex_document ./docs/api.md  # devrag reindex と同じ\n```\n\n### フラグの構文\n\nフラグは位置引数の**前**に置く必要があります：\n\n```bash\n# 正しい\ndevrag delete --dry-run file.md\n\n# 誤り（--dry-runが無視される）\ndevrag delete file.md --dry-run\n```\n\n## チーム開発\n\n大量のドキュメントがあるチームに最適：\n\n1. **Gitでドキュメント管理**: 通常のGitワークフロー\n2. **各開発者がDevRagを起動**: 各マシンでローカルセットアップ\n3. **Claude Codeで検索**: 全員が全ドキュメントを検索可能\n4. **自動同期**: `git pull`でインデックスを自動更新\n\nプロジェクトのdocsディレクトリ用に設定：\n\n```json\n{\n  \"document_patterns\": [\n    \"./docs\",\n    \"./api-docs/**/*.md\",\n    \"./wiki/**/*.md\"\n  ],\n  \"db_path\": \"./.devrag/vectors.db\"\n}\n```\n\n## パフォーマンス\n\n環境: MacBook Pro M2, 100ファイル (合計1MB)\n\n| 操作 | 時間 | トークン |\n|------|------|----------|\n| 起動 | 2.3秒 | - |\n| インデックス化 | 8.5秒 | - |\n| 検索 (1クエリ) | 95ms | ~300 |\n| 従来のRead | 25秒 | ~12,000 |\n\n**検索は260倍速、トークンは40分の1**\n\n## 開発\n\n### テスト実行\n\n```bash\n# すべてのテスト\ngo test ./...\n\n# 特定のパッケージ\ngo test ./internal/config -v\ngo test ./internal/indexer -v\ngo test ./internal/embedder -v\ngo test ./internal/vectordb -v\n\n# 統合テスト\ngo test . -v -run TestEndToEnd\n```\n\n### ビルド\n\n```bash\n# ビルドスクリプト使用\n./build.sh\n\n# 直接ビルド\ngo build -o devrag cmd/main.go\n\n# クロスプラットフォームリリースビルド\n./scripts/build-release.sh\n```\n\n### リリース作成\n\n```bash\n# バージョンタグを作成\ngit tag v1.0.1\n\n# タグをプッシュ\ngit push origin v1.0.1\n```\n\nGitHub Actionsが自動的に：\n1. 全プラットフォーム向けにビルド\n2. GitHub Releaseを作成\n3. バイナリをアップロード\n4. チェックサムを生成\n\n## プロジェクト構造\n\n```\ndevrag/\n├── cmd/\n│   └── main.go              # エントリーポイント\n├── internal/\n│   ├── cli/                 # CLIコマンド\n│   ├── config/              # 設定管理\n│   ├── embedder/            # ベクトル埋め込み\n│   ├── indexer/             # インデックス処理\n│   ├── mcp/                 # MCPサーバー\n│   └── vectordb/            # ベクトルDB\n├── models/                  # ONNXモデル\n├── build.sh                 # ビルドスクリプト\n└── integration_test.go      # 統合テスト\n```\n\n## トラブルシューティング\n\n### モデルのダウンロードに失敗\n\n**原因**: インターネット接続またはHugging Faceサーバーの問題\n\n**解決方法**:\n1. インターネット接続を確認\n2. プロキシ環境の場合：\n   ```bash\n   export HTTP_PROXY=http://your-proxy:port\n   export HTTPS_PROXY=http://your-proxy:port\n   ```\n3. 手動ダウンロード（`models/DOWNLOAD.md`参照）\n4. 再試行（不完全なファイルは自動削除）\n\n### GPU / CoreMLが動作しない\n\nmacOSではApple CoreMLによるGPU/Neural Engine高速化を使用します。条件：\n- `libonnxruntime.dylib`が`devrag`バイナリと同じディレクトリにあること\n- GitHubのmacOS版リリースにはこのファイルが含まれています\n\nCoreMLが利用できない場合は自動的にCPUにフォールバックします。パフォーマンス調整：\n```bash\n# CPUスレッド数の変更（デフォルト: 4）\nDEVRAG_THREADS=4 devrag\n```\n\n明示的にCPUモードを指定する場合：\n```json\n{\n  \"compute\": {\n    \"device\": \"cpu\",\n    \"fallback_to_cpu\": true\n  }\n}\n```\n\n### 起動しない\n\n- Go 1.21+がインストールされているか確認（ソースからビルドする場合）\n- CGOが有効か確認: `go env CGO_ENABLED`\n- 依存関係がインストールされているか確認\n- 初回起動時はインターネット接続が必要（モデルダウンロード）\n\n### 検索結果が期待と異なる\n\n- `chunk_size`を調整（デフォルト: 500）\n- インデックスを再構築（vectors.dbを削除して再起動）\n\n### メモリ使用量が多い\n\n- GPUモードではモデルがVRAMにロード\n- CPUモードに切り替えるとメモリ使用量が減少\n\n## 必要要件\n\n- Go 1.21+（ソースからビルドする場合）\n- CGO有効（sqlite-vecのため）\n- macOS, Linux, または Windows\n\n## ライセンス\n\nMIT License\n\n## クレジット\n\n- 埋め込みモデル: [intfloat/multilingual-e5-small](https://huggingface.co/intfloat/multilingual-e5-small)\n- ベクトルデータベース: [sqlite-vec](https://github.com/asg017/sqlite-vec)\n- MCPプロトコル: [Model Context Protocol](https://modelcontextprotocol.io/)\n- ONNX Runtime: [onnxruntime-go](https://github.com/yalue/onnxruntime_go)\n\n## コントリビューション\n\nIssuesとPull Requestsを歓迎します！\n\n## コントリビューター\n\nDevRagの改善に貢献してくださった皆様に感謝します：\n\n- **[@badri](https://github.com/badri)** - 複数ドキュメントパスとglobパターン対応 ([#2](https://github.com/tomohiro-owada/devrag/pull/2))、`--config` CLIフラグ ([#3](https://github.com/tomohiro-owada/devrag/pull/3))\n- **[@io41](https://github.com/io41)** - プロジェクトのクリーンアップとドキュメント改善 ([#4](https://github.com/tomohiro-owada/devrag/pull/4))\n\n皆様の貢献がDevRagをより良くしています！\n\n## 作者\n\n[towada](https://github.com/tomohiro-owada)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomohiro-owada%2Fdevrag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomohiro-owada%2Fdevrag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomohiro-owada%2Fdevrag/lists"}