> ## 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.

# Busca em Conversas (@session)

> O agente recupera o que foi discutido em sessões salvas anteriores — busca ranqueada, leitura paginada e salvamento automático.

O tool **`@session`** deixa o agente **recuperar conversas passadas** salvas — "o que decidimos sobre o cache semana passada?". Implementado nativamente sobre o [SessionManager](/pt/context/session-management) existente. Inspirado no `session_search` do hermes-agent.

O fluxo de recall tem duas metades: `search` acha **qual** sessão discutiu algo, `get` lê **aquela parte** dela.

***

## Subcomandos

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

| Subcomando | Função |
| - | - |
| `search {query, limit?}` | busca textual ranqueada nas sessões salvas; retorna sessões que casam + seus trechos mais fortes (`limit` = trechos por sessão, padrão 3) |
| `get {name, offset?, limit?, query?}` | lê uma sessão salva página a página (padrão 20 mensagens, índices absolutos + hint do próximo offset); uma `query` centraliza a página na melhor mensagem |
| `list` | lista os nomes das sessões salvas |

***

## Busca ranqueada (BM25)

A busca é **ranqueada**, não só casada: cada mensagem de cada sessão salva vira um documento BM25 scorado pelo mesmo motor lexical keyless da [base de conhecimento](/pt/context/knowledge-base). Semântica em dois níveis equilibra recall e precisão:

* Uma sessão **qualifica** quando todos os termos da query aparecem em algum lugar da conversa — em *qualquer* mensagem, não necessariamente na mesma. "decisão do refresh oauth" discutida ao longo de vários turnos ainda encontra a sessão.
* Sessões qualificadas **ranqueiam** pelo agregado dos scores das mensagens: a sessão onde os termos são densos e raros vence a que os menciona de passagem. Os trechos vêm das mensagens mais fortes de cada sessão.

## Saída

```text theme={"system"}
Sessões que correspondem a "rate limiter":

• proj-acme (2 ocorrências)
    … usei um token bucket para o rate limiter
    … o limite ficou em 1000 rps por chave
```

***

## Salvamento automático no exit

O REPL interativo **salva a conversa automaticamente ao sair** sob o nome reservado `autosave-YYYYMMDD-HHMMSS`, e o servidor MCP/ACP espelha cada conversa viva num arquivo rolling `mcp-<session>` — toda conversa vira memória recuperável mesmo que ninguém rode `/session save`. Sessões triviais (menos de 2 mensagens não-system) e execuções one-shot `-p` nunca são salvas. Gate `CHATCLI_SESSION_AUTOSAVE` (**on** por padrão; `CHATCLI_MCP_SESSION_AUTOSAVE` sobrescreve para MCP). A retenção é tempo-primeiro: sessões de máquina expiram no TTL de 90 dias com backstop de 600 arquivos, sessões nomeadas nunca expiram, e as camadas destiladas (fatos, episódios, rollups) sobrevivem a qualquer limpeza — veja [Gerenciamento de Sessões › Limpeza Automática](/pt/context/session-management).

***

## Notas

* `search`, `get` e `list` são **read-only** e concurrency-safe.
* **System prompts armazenados são mascarados**: ficam fora do corpus de busca e do ranking, e o `get` os substitui por um marcador de omissão — uma pergunta de recap retorna a conversa, nunca as próprias instruções da sessão ecoadas de volta.
* Busca tanto no histórico de chat quanto no de agente das sessões salvas.
* Pareie com [Gerenciamento de Sessões](/pt/context/session-management) (`/session save`) para checkpoints nomeados — o autosave cobre o resto.

<Tip>
  Use junto com `@memory` (fatos) e `@skill` (procedimentos): `@session` é a memória **episódica** ("o que conversamos"), enquanto memória e skills são o conhecimento destilado.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.