akb_grep
Search document contents for exact text or regex patterns. Returns matching documents and lines, supports count-only and files-with-matches modes, and can perform bounded find-and-replace.
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. |