# State and Memory Tools

Tools that search chat, error and action history, and record resolved errors.

| Tool | Description |
|---|---|
| `chat_history` | This session's own action log. `mode=list` returns recent runs one row each with their `task_id`; `mode=read` opens one or more runs in full — what each was asked for, every tool it called with what came back, and the reply it ended on (`scope=reference` keeps only the expensive payloads, `scope=full` keeps everything) — since v1.3.11, with a decision model set, a run of 4096 characters or more judged unrelated to the current request (confidence 0.7 or higher, the same check `read_files` uses) is replaced by a one-line withheld note carrying its objective, at most once per run per session, so reading it again returns it in full; `mode=tool_list` flattens the reusable calls across the last 16 runs so an already-paid-for fetch is found before it is re-run, and `mode=tool` returns one such call's raw output by `task_id` + `name`; `mode=search` searches past messages, `match=semantic` matching meaning in recent messages and `match=keyword` matching text across the full archive (SQLite FTS5, trigram tokenizer), bounded by `time_range`. The records live in the daemon's own store, so file tools never reach them |
| `error_history` | Tool failures kept across sessions. `mode=search` looks up past records by keyword — each carries the fix that worked; `mode=read` fetches one record by its 8-char hash (used when a tool returns `no data: {hash}`). Mode is inferred when omitted: `hash` → read, otherwise search. `mode=write` was Removed in v1.3.11; records are written with `write_error`. Search returns 4 records by default and caps `limit` at 16 |
| `write_error` | Added in v1.3.11, replacing `error_history(mode=write)`. Stores a tool failure together with the fix that resolved it, so a later `error_history` search finds it, and returns `recorded`. `tool_name`, `keywords` (an array), `symptom`, `action` and `outcome` (`resolved` / `failed` / `abandoned`) are required, `cause` is optional. Only `outcome=resolved` is stored — `failed` and `abandoned` are accepted but discarded. Called once a non-trivial fix is confirmed working, and when a failed tool result's `next:` hint asks for it |
| `reasoning_guide` | Fetch the full rule sets for every topic a turn needs in one call — since v1.0.26 the argument is `topics` (an array, at least one) instead of a single `topic`, and the result joins each guide under a `## <topic>` heading. Topics: `tool_generate`, `tool_error`, `web_search` (named `rag_web` before v1.2.1), `market_analysis`, `targeted_read`, `ask_user`, `subagent_dispatch`, `write_todo`, `html_render`, `office` (rules for creating or modifying `.docx` / `.xlsx` / `.pptx` so Office and iWork apps accept the file), `figure` (since v1.3.5: chart and diagram examples plus the extended Markdown syntax, read before writing a chart, flowchart, diagram or formula). Since v1.3.8 a session that cannot dispatch (a subagent leg) gets a one-line "run every lookup yourself" note for `subagent_dispatch` instead of the full rules. Replaces the former per-topic guide tools. Since v1.2.1 its full schema rides in the tools array next to `find_tools` and `run_tool`, so it is called directly rather than through `run_tool` |
| `write_result` | Renamed from `write_report` in v1.0.17, which added HTML output. Saves one long-form deliverable as `report-YYYYMMDD-HHMMSS.md` or `.html` in the output directory and returns the write receipt with its path — the research / analysis / comparison body the reply summarises instead of reprinting, or a finished HTML page. `content` is the complete file; `format` is `md` (default) or `html`. The output directory is `output_dir` from `config.json` (set with `/config`), else `~/Downloads` when it exists, else `~/.config/agenvoy/download/`. Since v1.2.1 `format=html` is checked before anything is written: the page must mount QuickUI, its inline `<script>` blocks must parse, and it may not write markup from script, use `{{ }}` expressions or compound `:if` conditions, or point `T.init` at a missing container. A failing page is not written; the error lists every problem (and the `html_render` rules when QuickUI is missing), and the call is repeated after the fix. Any other file, or a change to a file that already exists → `edit_file` |