Sessions & Agents

Last updated 2026-10-31

Session

A session is the core unit in Agenvoy. Each session has its own conversation context, memory, agent persona, and tool configuration.
Storage path: ~/.config/agenvoy/sessions/<sid>/

File	Purpose
`history.json`	Recent conversation, delta-appended
`summary.json` / `.summary_cursor`	Rolling summary and its incremental cursor
`action.log`	Tool call audit log. One line per event, `[timestamp][window_hash][kind][task_hash] body` (`window_hash` is the writing window's hash, the same value events carry as `window_hash`); the trailing `task_hash` bracket was added in v1.0.2 so every line can be traced back to the run that wrote it, and the replay parser treats it as optional so pre-v1.0.2 lines still load
`.cmd_history`	TUI input history for this session
`.claude_code/<model>_<hash>.json`	Since v1.1.3, one per `claude-code` model and system prompt hash used in the session (`_plain` appended for calls without tools): its Claude Code session id, message fingerprints and last answer, so a restarted daemon can `--resume` instead of replaying history (`@`, `/` and `\|` become `_`). v1.1.1 to v1.1.2 wrote one `claude_code_<model>.json` per model in the session directory
`pending/`	Pending `ask_user` / confirm metadata, one JSON per task hash

Everything else moved into ~/.config/agenvoy/.store/history.db:

SQLite table	Content
`session`	Display name, `self_id`, persona (`role`), model, reasoning level. Since v1.1.0 the persona is written to both the `role` column and the legacy `rule` column, and read from `role` first
`note` + `note_fts5`	Removed in v1.0.23 along with operator notes; tables left in an older database are no longer read
`messages` + `messages_fts5`	Full message archive and its full-text index
`action_history`	Finished runs and their tool results
`file_history`	Recorded versions of every file the tools changed. Since v1.0.14 the unique index is `(dir, name, task_id, session_id)` for rows that carry a task, so one task records a given file once — the first version it saw — instead of one row per save; the migration deletes the duplicates already stored. Rows with an empty `task_id` are unaffected
`usage`	Per-model token spend, 28-day retention. Carries `elapsed_ms` per send since v1.0.11, which the summaries turn into `output_tps`. Since v1.0.26 each row also records the ids of the tool calls in that reply (`tool_calls`); since v1.1.0 `input` for `claude` and `claude-code` includes cache writes, matching how other providers report uncached input

Vectors, tool cache, error memory, and running-task presence live in ToriiDB (.store/db_0 ... db_3). Up to v1.1.1 the daemon migrated legacy per-session bot.json, bot.md, config.json, status.json, usage.log, summary.meta.json and the history/ task directory into SQLite at startup; v1.1.2 removed those migrations, so such files left by an older install are no longer read — upgrade through v1.1.1 first to carry them over. The state table was dropped in v0.35.3: a running task is now an action:<session_id>:<task_hash> key in ToriiDB, refreshed every 55 s with a 60 s TTL, so a killed process stops being online on its own rather than needing a PID liveness check.

Session prefixes and lifetime

Prefix	Lifetime
`cli-*`	Permanent — local CLI / TUI work (TUI `/new`, or `POST /v1/session`)
`chat-*`	Permanent — web / API work (`POST /v1/send` with `persist=true`)
`dc-*`	Permanent (Discord channels)
`tg-*`	Permanent (Telegram chats — per-chat, shared across users in that chat)
`temp-*`	Reaped after 30 min idle (default for `POST /v1/send` and subagent sessions)

Cleanup runs every 30 minutes via cron (and once on startup) against the temp-* prefix only — cli-*, chat-*, dc-*, and tg-* are never auto-reaped.
The prefix also decides where a confirmation goes back to (since v1.2.0 a run started from the TUI asks only the TUI window that started it), and it is what the TUI session picker groups by: with at least two groups present the picker shows an all tab plus one tab per prefix, current session first. A daemon-side fsnotify watcher logs the ID and configured name of every newly created session directory.