> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversation Search (@session)

> The agent recalls what was discussed in earlier saved sessions — ranked search, paginated reading and automatic saving.

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](/features/session-management). 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

```text theme={"system"}
<tool_call name="@session" args='{"cmd":"search","args":{"query":"rate limiter design"}}' />
<tool_call name="@session" args='{"cmd":"get","args":{"name":"proj-acme","query":"token bucket"}}' />
<tool_call name="@session" args='{"cmd":"list"}' />
```

| Subcommand                            | Purpose                                                                                                                                                 |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search {query, limit?}`              | ranked full-text search across saved sessions; returns matching sessions + their strongest snippets (`limit` = snippets per session, default 3)         |
| `get {name, offset?, limit?, query?}` | read one saved session page by page (default 20 messages, absolute indices + next-offset hint); a `query` centers the page on the best-matching message |
| `list`                                | list saved session names                                                                                                                                |

***

## 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](/features/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

```text theme={"system"}
Sessions matching "rate limiter":

• proj-acme (2 matches)
    … used a token bucket for the rate limiter
    … capped it at 1000 rps per key
```

***

## 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](/features/session-management).

***

## 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](/features/session-management) (`/session save`) for named checkpoints — autosave covers everything else.

<Tip>
  Use alongside `@memory` (facts) and `@skill` (procedures): `@session` is **episodic** memory ("what we talked about"), while memory and skills are distilled knowledge.
</Tip>