akb_grep
Search documents for exact string or regex matches, returning URIs and matched lines—ideal for specific terms, URLs, code snippets, or version numbers.
Instructions
Search for exact text or regex patterns across document content. On a native Document backend, optionally include admitted searchable text Files with measurement_include_text_files=true; binary Files remain excluded. 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; the call writes nothing if the scope exceeds max_replacements. 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. When response safety bounds truncate snippets, the truncation object names the applied resource, match, and byte limits; use count_only for exact counts without snippets.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max documents to return; does not limit replacement writes | |
| 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 | Non-empty 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 and the full scope fits max_replacements, replaces all matches in EVERY matching document (git commit + re-index per doc); otherwise writes nothing. Treated literally when regex=false; supports regex backreferences (\1, \2) only 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) | |
| _vault_skill_ack | No | Opaque acknowledgement returned as vault_skill.ack_token. After applying that guide, retry the unchanged operation with this value. The bundled proxy supplies it automatically. | |
| max_replacements | No | Maximum documents a replace call may rewrite, independent of the response limit. If the full scope matches more documents, the call fails before writing anything. Preview with count_only or files_with_matches, then set this budget to cover the intended scope. | |
| 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. | |
| measurement_include_text_files | No | Native mode: include admitted searchable text Files as well as Documents. File results include resource_type=file, their canonical akb:// URI, revision, and content_hash; native results also report payload_placement, the body placement their bytes were read from. Binary Files are never searchable. Rejected unless postgres_native or the exact guarded native measurement backend is active. |