akb_grep
Find exact text or regex patterns across documents, returning matching URIs and lines. Use for specific terms, links, code, or version numbers—unlike semantic search.
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 |
|---|---|---|---|
| limit | No | Max documents to return | |
| 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. | |
| vault | No | Limit to a specific vault | |
| 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). | |
| 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. | |
| collection | No | Limit to a specific collection | |
| 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. | |
| case_sensitive | No | Case-sensitive matching (default: case-insensitive) | |
| 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. |