> ## 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 Hub — continuidade de conversa entre canais

> Uma conversa que atravessa canais: o assunto começado no Telegram/Slack/WhatsApp continua no chatcli do notebook, e vice-versa, até você iniciar uma nova sessão.

O **Conversation Hub** faz a conversa **atravessar canais**. Um assunto começado no Telegram continua quando você abre o chatcli no notebook; o que você responde no notebook vira contexto no Telegram/Slack/WhatsApp. Os dois lados se entendem — sem você repetir nada.

<Note>
  O hub é uma **ponte do momento**, não memória de longo prazo. Ele mantém a conversa **atual** sincronizada entre canais, com banco **limitado** (poda automática). Memória persistente entre projetos/sessões continua sendo o [sistema de memória](/pt/context/bootstrap-memory) (`/memory`) e o [`/session save`](/pt/context/session-management).
</Note>

## Como funciona

* **Principal**: a identidade compartilhada da conversa. No modo single-user (padrão), o CLI local e o gateway colapsam no mesmo principal (`default` se você não definir nada), então tudo compartilha **sem configuração**.
* **`hub.db`**: um log append-only em SQLite (`~/.chatcli/hub.db`). O CLI e o daemon do gateway abrem o **mesmo arquivo** — é por isso que se entendem entre processos.
* **Efêmero por sessão**: ao abrir o chatcli, começa uma conversa **nova** e a anterior é **podada** — o banco não cresce e você não carrega um histórico gigante. Conversas ociosas além do TTL (`CHATCLI_HUB_TTL_HOURS`, padrão 24h) são varridas.
* **Silencioso**: mensagens de outros canais entram no contexto do modelo **sem serem impressas** no seu prompt (nada de poluição, nada de "apertar Enter pra continuar").
* **`/newsession`** zera a conversa compartilhada para todos os canais.

Funciona em **chat**, **`/agent`** e **`/coder`**: o pedido e a resposta final atravessam os canais (o detalhe de execução das tools fica local em cada máquina).

## Modos

<Tabs>
  <Tab title="Local (mesma máquina)">
    O caso mais simples — chatcli + gateway no mesmo notebook, **zero configuração** (basta o principal padrão):

    ```bash theme={"system"}
    export CHATCLI_TELEGRAM_BOT_TOKEN=123:abc
    chatcli                 # abre o REPL (entra em modo hub local)
    # dentro dele:
    /gateway start          # sobe o daemon, herdando o ambiente
    ```

    Converse no notebook, depois puxe o assunto no Telegram → tem o contexto. Mande no Telegram com o prompt aberto → entra no contexto do próximo turno do notebook.

    <Note>Cross-process, o notebook pega o contexto **no próximo turno** (não há push ao vivo no prompt já aberto). Para tempo real, use o modo co-locado abaixo.</Note>
  </Tab>

  <Tab title="Co-locado no servidor (tempo real)">
    Roda o gateway **dentro do processo do servidor**, compartilhando o broker em memória — assim uma mensagem do Telegram chega ao CLI conectado em tempo real:

    ```bash theme={"system"}
    CHATCLI_TELEGRAM_BOT_TOKEN=123:abc \
    CHATCLI_GATEWAY_IN_SERVER=true \
    chatcli server --port 50051

    # no notebook (mesma ou outra máquina):
    chatcli connect localhost:50051
    ```
  </Tab>

  <Tab title="Multi-usuário / bot público">
    Para um bot que atende várias pessoas, **isole** cada identidade e mapeie quem é quem:

    ```bash theme={"system"}
    export CHATCLI_HUB_ISOLATE=true
    export CHATCLI_HUB_BINDINGS="telegram:111=alice;telegram:222=bob"
    ```

    Com `isolate`, remetentes não-vinculados ficam cada um na sua própria conversa (um usuário nunca vê o thread de outro). Bindings explícitos colapsam identidades específicas num principal nomeado.
  </Tab>
</Tabs>

## Comandos

```text theme={"system"}
/hub whoami                         # seu principal e a conversa ativa
/hub bind telegram 123 alice        # vincula uma identidade de canal a um principal
/hub bindings [principal]           # lista os vínculos canal→principal
```

As **settings** do hub são mutáveis em runtime e persistem no `hub.db` (lidas ao vivo pelo gateway, sem restart):

```text theme={"system"}
/config hub                         # painel: valor efetivo + fonte (setting/env/default)
/config hub set principal alice
/config hub set isolate on
/config hub set ttl_hours 72
/config hub reset principal         # volta a env/default
```

Precedência de resolução: **setting (db) > variável de ambiente > default**.

## Identidade compartilhada (single-user vs multi-user)

| Cenário | Configuração | Resultado |
| - | - | - |
| Só você (notebook + bot pessoal) | nada (ou `CHATCLI_HUB_PRINCIPAL=eu`) | tudo colapsa num principal → uma conversa compartilhada |
| Bot multi-usuário/público | `CHATCLI_HUB_ISOLATE=true` (+ bindings) | cada identidade isolada; bindings mesclam quem você quiser |

Com o isolamento ligado, o gateway também dá a cada principal seu **próprio conjunto de stores** — sessões salvas, memória de longo prazo, contextos de conhecimento, arquivo CCR, snapshots de custo, journal de transcript e a conversa viva — na raiz `~/.chatcli/tenants/<principal>/`. O conjunto é instalado para o turno daquele remetente e o compartilhado é restaurado depois, então um `/session list` num chat nunca mostra as sessões de outro usuário e os fatos de um usuário nunca aparecem no turno de outro. `CHATCLI_GATEWAY_MAX_TENANTS` (16) limita quantos conjuntos ficam residentes; os menos usados recentemente são liberados e reconstruídos do disco no próximo turno. Execuções parkeadas (`/park`, `/resume`) e execuções de task-graph também seguem a raiz do tenant, e `CHATCLI_DAILY_BUDGET_USD` limita o gasto de cada tenant por dia-calendário separadamente. Tudo que deriva de uma conversa troca junto com o conjunto: o cartão de memória do início de sessão, a pilha de undo do `/rewind compact`, o último trace de auto-recall, a marca d'água de encaminhamento do provedor de memória externo, imagens recebidas pendentes e a última resposta do agente; o memory worker base continua lendo o histórico base enquanto o turno de um tenant roda, e as chamadas MCP `memory_recall` / `memory_store` de um provedor externo carregam um argumento `tenant`. O que fica global ao processo está listado em "Compartilhado entre tenants" no `/config security`: hooks, o MCP manager (servidores e OAuth), o reflexion runner, o arquivo de histórico do REPL, o banco do hub e o scheduler — além do board do squad e do cache de vocabulário do tokenizer (dados públicos).

## Relação com memória e sessões

| Mecanismo | Para quê | Persistência |
| - | - | - |
| **Conversation Hub** | contexto cross-channel da conversa **atual** | efêmero/limitado (poda + TTL) |
| [Memória](/pt/context/bootstrap-memory) (`/memory`) | fatos/aprendizados de longo prazo | permanente |
| [Sessões](/pt/context/session-management) (`/session save` / `attach`) | snapshot explícito de uma conversa — ou, enquanto vinculada, o **registro durável cross-surface** que todas as superfícies gravam via write-through | arquivo JSON |

O hub é um **trilho paralelo aditivo**: o histórico local, o `/session save` e a memória continuam funcionando exatamente como antes. Para continuidade durável de uma conversa nomeada entre REPL, IDE, MCP e gateway, veja [Continuidade cross-surface](/pt/context/session-management#continuidade-cross-surface) — o hub segue sendo a ponte em tempo real do turno *atual*.

## Observabilidade — o hub nunca morre em silêncio

A continuidade depende do hub estar de pé, então todo estado dele é **explícito no log**:

* **Hub ativo**: o daemon loga `gateway: conversation hub active (principal=…, isolate=…, idle_ttl=…)` no boot; o CLI loga `local hub mode enabled`.
* **Hub desligado**: um `Warn` nomeia **a fonte exata da decisão** — `db setting enabled=false`, `env CHATCLI_HUB_ENABLED=false` ou `default` — em vez de simplesmente sumir com a continuidade.
* **Daemon servindo sem hub** (banco inacessível): um aviso único por execução deixa claro que as respostas estão sem contexto cross-channel.

<Warning>
  O daemon herda o ambiente da shell que rodou `/gateway start`, e o `.env` **não** sobrescreve variáveis já exportadas. Um `CHATCLI_HUB_ENABLED=false` esquecido na shell desliga a continuidade mesmo com o `.env` correto — o log de proveniência acima existe exatamente para flagrar isso (`ps eww <pid>` confirma o ambiente real do processo).
</Warning>

## Veja também

* [Agent Squad](/pt/agents/agent-squad) — o squad mail e o registry de runs viajam por este mesmo hub: o `/agents` enxerga (e cancela) runs em outros processos, e o `/mail send` alcança agents rodando no gateway daemon
* [Chat Gateway](/pt/gateway/chat-gateway) — expõe o ChatCLI nos canais de mensagem
* [Servidor Remoto (/connect)](/pt/server/remote-connect) — conectar o CLI a um hub remoto
* [Variáveis de Ambiente](/pt/reference/environment-variables#conversation-hub-continuidade-cross-channel)
* [Referência de Comandos](/pt/reference/command-reference)


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