akb_grep
Search documents for exact text or regex patterns. Get matching documents and lines, or use count_only/files_with_matches for summaries. Optionally replace matches across all documents.
Instructions
Search for exact text or regex patterns across document content. Unlike akb_search (semantic/meaning-based), this finds exact string matches — use it for specific terms, URLs, code snippets, version numbers, etc. Returns matching documents (each with its uri) and matched lines. Optionally pass replace to find-and-replace across all matching documents. Three response shapes (mutually exclusive): default lines, count_only=true (grep -c — per-doc counts + total, no snippets), files_with_matches=true (grep -l — just the URIs that contain the pattern). The default shape always reports BOTH returned_* (what fit under limit) and total_* (full corpus matches) plus a truncated flag — if truncated, switch to count_only/files_with_matches for the full picture instead of bumping limit.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pattern | Yes | Search pattern. By default matched as literal text (ILIKE) — metacharacters like |, ., *, (), [], +, ? are treated as literal characters. Set regex=true to enable PostgreSQL regex (required for alternation and wildcards). | |
| vault | No | Limit to a specific vault | |
| collection | No | Limit to a specific collection | |
| regex | No | Treat pattern as PostgreSQL regex. REQUIRED to use alternation (|), wildcards (.*), character classes, anchors, etc. When false (default), the entire pattern including any metacharacters is matched literally. | |
| case_sensitive | No | Case-sensitive matching (default: case-insensitive) | |
| replace | No | Replacement string. If provided, replaces all matches in EVERY matching document across the search scope (git commit + re-index per doc). Supports regex backreferences (\1, \2) when regex=true. For precise edits to a single known document, prefer akb_edit instead. | |
| limit | No | Max documents to return | |
| count_only | No | Return counts only (grep -c semantics). Response: {pattern, total_matches, total_docs, by_doc:{uri:count,...}}. Use for 'how many X are there?' questions — much cheaper than fetching every line. | |
| files_with_matches | No | Return only the URIs that contain matches (grep -l semantics). Response: {pattern, n_files, files:[uri,...]}. Use for 'which documents mention X?' questions. |