| 1 | # History Search Catalog |
| 2 | |
| 3 | Reasonix stores the history search projection at |
| 4 | `<cache root>/history-search/v1.sqlite`. Session JSONL, event logs, metadata, |
| 5 | sub-agent transcripts, and archives remain authoritative. Removing or |
| 6 | rebuilding the database never removes conversation data, and older Reasonix |
| 7 | versions continue to read the same authoritative files. |
| 8 | |
| 9 | The catalog stores normalized retrieval tokens in FTS5, not complete message |
| 10 | text. English tokens retain the existing lowercase/code-symbol semantics and |
| 11 | CJK text retains overlapping bigrams. Snippets and `around` context are loaded |
| 12 | from the authoritative source only after SQLite has selected the final |
| 13 | candidates. User, assistant, tool input, tool error, and tool output parts are |
| 14 | indexed; ordinary tool output remains excluded by the default search kinds. |
| 15 | |
| 16 | Successful session persistence sends a non-blocking, path-coalesced hint after |
| 17 | the authoritative commit and after file locks have been released. Continuous |
| 18 | appends read only the new display-index range. Rewrites, missed notifications, |
| 19 | external writers, or fingerprint mismatches rebuild that source in the |
| 20 | background. Only one full transcript decoder runs at once, checkpoints are |
| 21 | persisted per source, and one corrupt source cannot stop other histories. A |
| 22 | format-2 session log is indexed through the derived transcript of its selected |
| 23 | head; switching heads rewrites that transcript, which the projection treats |
| 24 | like any other rewrite and rebuilds in the background. Other heads are not |
| 25 | searchable until they are made current. |
| 26 | |
| 27 | The Agent `history` tool and Desktop history manager share the projection. |
| 28 | Search never starts a synchronous directory scan. While indexing is incomplete, |
| 29 | existing results return immediately with explicit progress. Runtime open, |
| 30 | running, and current state is overlaid from memory; SQLite cannot restore stale |
| 31 | runtime ownership. Provider-visible tool name, description, schema, defaults, |
| 32 | and ordering are unchanged. |
| 33 | |
| 34 | The database uses the common disposable projection policy: local disks use WAL, |
| 35 | `synchronous=NORMAL`, foreign keys, private permissions, and a short busy |
| 36 | timeout. Remote or unavailable cache directories fall back to memory. Integrity |
| 37 | or migration failures quarantine and rebuild the cache; future schema versions |
| 38 | are preserved in degraded read mode. |
| 39 | |
| 40 | Diagnostics and safe rebuild commands: |
| 41 | |
| 42 | ```sh |
| 43 | reasonix doctor catalogs [--json] |
| 44 | reasonix catalogs reindex history [--dir PATH ...] [--json] |
| 45 | ``` |
| 46 | |
| 47 | Diagnostics never print queries, tokens, snippets, messages, tool arguments, or |
| 48 | provider content. A rebuild replaces only this disposable projection. |
| 49 |