The @session tool lets the agent recall earlier saved conversations — “what did we decide about the cache last week?”. Implemented natively over the existing SessionManager. Inspired by hermes-agent’s session_search.
The recall flow has two halves: search finds which session discussed something, get reads that part of it.
Subcommands
Ranked search (BM25)
Search is ranked, not just matched: every message of every saved session is scored as a BM25 document by the same keyless lexical engine the knowledge base uses. Two-level semantics balance recall and precision:
- A session qualifies when every query term appears somewhere in the conversation — in any message, not necessarily the same one. “oauth refresh decision” discussed across several turns still finds the session.
- Qualifying sessions rank by their aggregate message scores, so the session where the terms are dense and rare beats one that mentions them in passing. Snippets come from each session’s strongest messages.
Output
Automatic saving on exit
The interactive REPL auto-saves the conversation on exit under a reserved autosave-YYYYMMDD-HHMMSS name, and the MCP/ACP server mirrors each live conversation as a rolling mcp-<session> file — every conversation becomes retrievable memory even when nobody ran /session save. Trivial sessions (fewer than 2 non-system messages) and one-shot -p runs are never saved. Gated by CHATCLI_SESSION_AUTOSAVE (on by default; CHATCLI_MCP_SESSION_AUTOSAVE overrides for MCP). Retention is time-first: machine sessions expire after the 90-day TTL with a 600-file keep backstop, user-named sessions never expire, and the distilled memory layers (facts, episodes, rollups) survive any cleanup — see Session Management › Automatic Cleanup.
Notes
search, get and list are read-only and concurrency-safe.- Searches both the chat and agent history of saved sessions.
- Pair with Session Management (
/session save) for named checkpoints — autosave covers everything else.
Use alongside @memory (facts) and @skill (procedures): @session is episodic memory (“what we talked about”), while memory and skills are distilled knowledge.
