Bootstrap e Memória Persistente

O ChatCLI oferece dois sistemas complementares para personalizar e contextualizar o agente: arquivos bootstrap para definir personalidade e regras, e memória persistente para manter contexto entre sessões.

O sistema de bootstrap e memória está totalmente conectado ao fluxo de system prompt. Os arquivos são carregados automaticamente e injetados em todas as interações — tanto no modo chat quanto nos modos /agent e /coder.

Arquivos Bootstrap

Os arquivos bootstrap são documentos Markdown carregados automaticamente no system prompt do agente. Eles definem quem o assistente e, como ele se comporta e quais regras deve seguir.

Arquivos Suportados

O ChatCLI carrega exatamente 5 arquivos bootstrap, nesta ordem. Todos são opcionais — se não existirem, são simplesmente ignorados:

Arquivo	Proposito	Quando usar
`AGENTS.md`	Definicoes de sub-agentes e seus papeis	Quando você quer instruir o orquestrador sobre quais agents existem e como usa-los
`SOUL.md`	Personalidade, tom e estilo do assistente	Para definir “quem” e o assistente — como ele fala, pensa e se comporta
`USER.md`	Preferencias e contexto do usuário/projeto	Para informar o stack, convencoes, ferramentas preferidas e contexto do projeto
`IDENTITY.md`	Identidade e capacidades do agente	Para definir “o que” o assistente e — nome, capacidades, limitações
`RULES.md`	Regras e restrições explicitas	Para guardrails rígidos — o que ele DEVE e NÃO DEVE fazer

Os nomes dos arquivos são exatos e case-sensitive. O ChatCLI busca apenas AGENTS.md, SOUL.md, USER.md, IDENTITY.md e RULES.md. Outros nomes (como CLAUDE.md, README.md, etc.) não são carregados pelo bootstrap.

Prioridade de Carregamento

Os arquivos são buscados em dois níveis, com o workspace tendo prioridade:

Workspace (raiz do projeto)

Configurações específicas do projeto. Tem prioridade sobre o global. A raiz do projeto e detectada automaticamente (veja abaixo).

Global (~/.chatcli/)

Configurações padrão do usuário. Serve como fallback quando o arquivo não existe no workspace.

Se o mesmo arquivo existe em ambos os níveis, o do workspace prevalece. Arquivos globais servem como fallback.

Detecção Automática do Workspace

O ChatCLI usa detectProjectDir() para encontrar a raiz real do projeto. Em vez de usar simplesmente o diretório atual (CWD), ele sobe na árvore de diretorios procurando marcadores de projeto:

Verifica se o diretório atual contem .git/ ou .agent/
Se não encontrar, sobe para o diretório pai e repete
Continua até encontrar um marcador ou chegar na raiz do filesystem
Se nenhum marcador for encontrado, usa o CWD como fallback

Isso significa que você pode rodar o ChatCLI de qualquer subdiretorio do projeto e os arquivos bootstrap na raiz serão encontrados normalmente.

Marcadores reconhecidos: .git (repositório Git) e .agent (marcador explicito do ChatCLI). Basta um deles existir para definir a raiz do workspace.

Cenarios de Exemplo

CWD ao iniciar	Marcador encontrado	Workspace detectado	Arquivos carregados
`~/project/`	`~/project/.git`	`~/project/`	`~/project/SOUL.md`, etc.
`~/project/src/pkg/`	`~/project/.git`	`~/project/`	`~/project/SOUL.md` (sobe 2 níveis)
`~/project/src/pkg/`	nenhum	`~/project/src/pkg/`	Apenas globais (`~/.chatcli/`)
`~/monorepo/services/api/`	`~/monorepo/.git`	`~/monorepo/`	`~/monorepo/SOUL.md`, etc.
`~/tmp/`	nenhum	`~/tmp/`	Apenas globais (`~/.chatcli/`)

Exemplos Detalhados

SOUL.md
USER.md
IDENTITY.md
RULES.md
AGENTS.md

Define personalidade e tom. Coloque em ~/.chatcli/SOUL.md (global) ou ./SOUL.md (projeto):

# Personalidade

Você e um assistente tecnico especializado em engenharia de software.
Seja conciso e direto. Prefira exemplos praticos a explicações teoricas.
Quando sugerir código, use boas praticas e testes.

# Tom

- Profissional mas acessivel
- Prefira respostas curtas e objetivas
- Use bullet points para listas
- Responda em portugues por padrão

Define contexto do usuário e projeto. Ideal para ./USER.md no diretório do projeto:

# Contexto do Projeto

- Stack: Go 1.25, gRPC, Kubernetes
- Banco: PostgreSQL 16
- CI/CD: GitHub Actions
- Estilo: conventional commits, trunk-based development

# Preferencias

- Sempre usar tabelas para comparações
- Preferir soluces simples e sem over-engineering
- Testes com table-driven tests idiomaticos em Go

Define o que o assistente e. Normalmente global em ~/.chatcli/IDENTITY.md:

# Identidade

Você e o ChatCLI, um assistente de terminal inteligente.

## Capacidades

- Leitura e edicao de código via @coder plugin
- Execução de comandos shell com aprovação do usuário
- Análise de logs e diagnóstico de erros
- Operações Git (status, diff, log, commit)

## Limitações

- Você NÃO tem acesso a internet
- Você NÃO pode instalar pacotes sem aprovação
- Seus patches podem falhar se o contexto mudou

Define regras rigidas e guardrails. Pode ser global ou por projeto:

# Regras Obrigatorias

1. NUNCA execute `rm -rf` sem confirmação explicita
2. NUNCA commite diretamente na branch main
3. SEMPRE rode testes após modificar código
4. SEMPRE use conventional commits (feat:, fix:, chore:)

# Restrições de Segurança

- Não exponha secrets, tokens ou API keys em logs
- Não modifique arquivos fora do diretório do projeto
- Não execute comandos com sudo

Define sub-agentes e seus papeis para o orquestrador:

# Agents Customizados

## @devops
Especialista em infraestrutura, Docker, Kubernetes e CI/CD.
Use para tarefas de deploy, monitoramento e configuração de pipelines.

## @dba
Especialista em banco de dados PostgreSQL.
Use para queries, otimização, migrations e análise de performance.

## @security
Auditor de segurança focado em OWASP Top 10.
Use para revisao de código com foco em vulnerabilidades.

Onde Colocar os Arquivos

“Raiz do projeto” significa o diretório que contem .git/ ou .agent/ — detectado automaticamente pelo detectProjectDir(), não necessariamente o CWD.

# Configuração GLOBAL (vale para todos os projetos)
~/.chatcli/SOUL.md
~/.chatcli/IDENTITY.md
~/.chatcli/RULES.md
~/.chatcli/USER.md
~/.chatcli/AGENTS.md

# Configuração por PROJETO (override do global)
# "Raiz do projeto" = diretório com .git/ ou .agent/
<raiz-do-projeto>/SOUL.md          # Na raiz do projeto
<raiz-do-projeto>/USER.md          # Na raiz do projeto
<raiz-do-projeto>/RULES.md         # Na raiz do projeto (regras do projeto)
<raiz-do-projeto>/IDENTITY.md      # Na raiz do projeto (raro)
<raiz-do-projeto>/AGENTS.md        # Na raiz do projeto (agents do projeto)

CHATCLI_BOOTSTRAP_DIR substitui apenas o diretório global (~/.chatcli/), não a detecção do workspace. Arquivos na raiz do projeto (detectada via .git ou .agent) continuam tendo prioridade sobre os globais, independentemente de CHATCLI_BOOTSTRAP_DIR.

A estratégia recomendada: SOUL.md e IDENTITY.md globais (são sobre o assistente), USER.md e RULES.md por projeto (são sobre o contexto de trabalho).

Cache Inteligente

Os arquivos bootstrap usam cache baseado em mtime (modification time):

Na primeira leitura, o conteúdo e cacheado em memória
Leituras subsequentes verificam se o mtime mudou
Se o arquivo foi modificado, o cache e invalidado automaticamente
IsStale() verifica se algum arquivo mudou desde o ultimo carregamento

Memória Persistente

O sistema de memória mantem contexto entre sessões do ChatCLI usando armazenamento estruturado com múltiplos componentes que aprendem sobre você e seu trabalho ao longo do tempo.

Arquitetura do Sistema

Conversa -> memoryWorker (3min) -> LLM extraction -> ProcessExtraction()
                                                          |
                    +───────────+───────────+──────────────+────────────+
                    v           v           v              v            v
              FactIndex    Profile    TopicTracker  ProjectTracker  DailyNote
              (scored)     (JSON)     (JSON)        (JSON)          (.md)
                    |
                    v
              Compactor (6h check, 24h cycle)
              |-- Level 1: Score-based pruning + archive
              +-- Level 2: LLM consolidation
                    |
                    v
              MEMORY.md (regenerado, nunca source of truth)

Extração resiliente — nada se perde em silêncio

A extração depende de uma chamada de LLM em background — e um provider fora do ar não pode custar a memória da conversa. Três defesas em camadas:

Cadeia de fallback: a extração tenta o client ativo da sessão e, em falha, percorre CHATCLI_MEMORY_FALLBACK_PROVIDERS (ou CHATCLI_FALLBACK_PROVIDERS), com timeout próprio por tentativa.
Fila durável em disco: um segmento que falhar em todos os providers é gravado em ~/.chatcli/memory/pending/ (escrita atômica) e reprocessado nas próximas execuções, do mais antigo para o mais novo — sobrevive a restart. A fila tem teto (100 segmentos) e arquivos corrompidos são descartados sem travar o restante.
Aviso visível: duas falhas consecutivas mostram uma linha no terminal (memória: extração falhando…) — perda silenciosa de fatos por dias não acontece mais.

O gateway também consulta esta memória: a persona do daemon chama @memory recall antes de responder “não sei” a perguntas pessoais. Veja Chat Gateway.

Estrutura de Armazenamento

Toda a memória fica em ~/.chatcli/memory/:

~/.chatcli/memory/
|-- MEMORY.md              # Resumo legivel (regenerado do FactIndex)
|-- memory_index.json      # Fatos com scores de relevancia
|-- user_profile.json      # Perfil do usuário (nome, role, expertise)
|-- topics.json            # Topicos recorrentes com frequência
|-- projects.json          # Projetos ativos com contexto
|-- usage_stats.json       # Padroes de uso e estatisticas
|-- memory_archive.json    # Fatos arquivados (baixo score)
|-- 202603/                # Notas diarias de marco 2026
|   |-- 20260301.md
|   +-- 20260306.md
+-- 202602/
    +-- 20260228.md

Componentes

FactIndex -- Memória de Longo Prazo

Substitui o antigo MEMORY.md append-only. Cada fato tem:

ID unico por hash SHA-256 do conteúdo (deduplicação automatica)
Categoria: architecture, pattern, preference, gotcha, project, personal
Score temporal: (1 + log(accessCount)) * exp(-days * ln2 / halfLife)
Tags para busca por keywords

Fatos mais acessados e recentes tem scores maiores. Fatos antigos e nunca acessados decaem naturalmente.

UserProfile -- Perfil do Usuário

Detectado automaticamente pela IA durante a extracao:

Nome, role, nível de expertise
Idioma preferido e estilo de comunicação
Comandos mais usados (top 10)
Preferencias gerais

Veja com /memory profile.

TopicTracker -- Topicos Recorrentes

Rastreia topicos tecnicos discutidos:

Frequência de mencoes
Recencia (topicos recentes pesam mais)
Links com fatos relacionados

Veja com /memory topics.

ProjectTracker -- Projetos

Rastreia projetos em que você trabalha:

Nome, path, descrição
Tecnologias usadas
Status (active, paused, completed)
Ultima atividade

Veja com /memory projects.

PatternDetector -- Padroes de Uso

Analisa como você usa o ChatCLI:

Sessões totais e duracao media
Horas de pico de atividade
Features preferidas (chat, agent, coder)
Erros comuns e resolucoes

Veja com /memory stats.

Smart Retrieval

Em vez de injetar toda a memória no system prompt, o ChatCLI usa retrieval inteligente:

Extrai keywords das ultimas mensagens da conversa
Busca fatos relevantes no FactIndex por keyword match + score temporal
Respeita um budget configurável (padrão: 4000 caracteres)
Prioriza: Perfil > Projetos > Topicos > Fatos relevantes > Notas recentes

Fatos acessados pelo retriever tem seu score incrementado automaticamente, criando um ciclo virtuoso: quanto mais um fato e util, mais ele aparece.

Modo de injeção: push vs pull

Como a memória chega ao modelo nos modos /agent e /coder é controlado por CHATCLI_MEMORY_MODE:

Modo	Comportamento
`index` (default)	Injeta apenas um índice compacto e estável (perfil resumido + nomes dos top topics/projects + contagem de fatos por categoria) e deixa o agente puxar o detalhe sob demanda via `@memory recall`. Custo por turno limitado e cacheável.
`full`	Injeta o Smart Retrieval completo (acima) a cada turno — o comportamento clássico de “push”.
`off`	Não injeta memória; os arquivos bootstrap continuam valendo.

O modo pull (index) reduz o bloco de memória por turno em ~88% num store de 500 fatos sem perder acesso ao detalhe — veja Eficiência de Tokens › Memória pull-first para a medição completa. O chat é tool-less e não puxa sob demanda: lá index cai em full. A ferramenta @memory recall usa HyDE + busca vetorial, então o detalhe puxado tem a mesma qualidade do push. Veja o estado atual em /config memory.

Configuração da Memória

O sistema de memória possui parâmetros configuraveis via variáveis de ambiente:

Variável	Padrão	Descrição
`CHATCLI_MEMORY_MODE`	`index`	Modo de injeção em agent/coder: `index` (pull), `full` (push) ou `off`
`CHATCLI_MEMORY_MAX_SIZE`	`32768` (32KB)	Tamanho máximo do MEMORY.md renderizado
`CHATCLI_MEMORY_RETENTION_DAYS`	`30`	Dias de retencao de notas diarias antes da limpeza
`CHATCLI_MEMORY_MAX_FACTS`	`500`	Número máximo de fatos no FactIndex
`CHATCLI_MEMORY_RETRIEVAL_BUDGET`	`4000`	Máximo de caracteres de memória injetados no system prompt (modo `full`)

Alem das variáveis de ambiente, o struct Config interno define valores padrão adicionais:

Parâmetro	Valor Padrão	Descrição
`CompactionInterval`	24 horas	Intervalo mínimo entre compactações completas
`DecayHalfLifeDays`	30.0	Meia-vida do decay temporal dos scores de fatos
Intervalo de verificação	6 horas	Frequência com que o sistema checa se precisa compactar

Como as Memorias são Criadas

O worker em background agora extrai 5 tipos de informação (antes eram apenas 2):

DAILY — O que foi feito (arquivos, comandos, erros, tarefas)
LONGTERM — Fatos novos para lembrar permanentemente
PROFILE_UPDATE — Informações sobre o usuário (nome, role, expertise)
TOPICS — Topicos tecnicos discutidos
PROJECTS — Projetos em que se trabalhou

O worker dispara após 4+ mensagens novas com cooldown de 2 minutos, e também a cada 3 minutos em sessões longas.

Processo de Extracao

O Memory Worker segue este fluxo interno:

EnhancedExtractionPrompt: Envia o histórico recente da conversa para o LLM com um prompt estruturado solicitando extracao de informações
Resposta esperada: O LLM retorna texto com headers de seção bem definidos:
- ## DAILY — Resumo do que foi feito na sessão
- ## LONGTERM — Fatos novos para memória de longo prazo
- ## PROFILE_UPDATE — Atualizações de perfil do usuário
- ## TOPICS — Topicos tecnicos identificados
- ## PROJECTS — Projetos mencionados ou trabalhados
ParseEnhancedResponse(): Faz o parse da resposta e extrai cada seção individualmente
Deduplicação: Cada fato recebe um ID único via hash SHA-256 do conteúdo. Fatos com hash identico a um já existente são descartados automaticamente
Merge de perfil: Atualizações de PROFILE_UPDATE são mescladas (merged) com o perfil existente, nunca substituidas por completo

Compactação Automatica

O sistema executa compactação periodica para evitar crescimento descontrolado:

Verificação (a cada 6 horas)

Checa se o número de fatos ultrapassa 80% do limite ou se passaram 24h desde a ultima compactação.

Compactação LLM (preferida)

Envia todos os fatos para a IA com instruções para: merge duplicatas, remover obsoletos, consolidar relacionados.

Fallback Score-based

Se a chamada LLM falhar, arquiva fatos com score abaixo de 0.1 em memory_archive.json.

Limpeza de Notas Diarias

Remove notas mais antigas que o periodo de retencao (padrão: 30 dias).

Regeneracao do MEMORY.md

Reescreve MEMORY.md a partir do FactIndex — sempre atualizado, nunca source of truth.

Migração Automatica

Ao iniciar pela primeira vez com o novo sistema, o ChatCLI detecta se existe um MEMORY.md legado (sem memory_index.json) e migra automaticamente:

Cada linha/bullet e convertida em um fato individual
Categorias são detectadas pelos headers do markdown
Tags são extraidas por keywords tecnicas
O arquivo original e salvo como MEMORY.md.bak

Comando `/memory`

Subcomando	Descrição
`/memory` ou `/memory today`	Mostra as notas de hoje
`/memory yesterday`	Mostra as notas de ontem
`/memory 2026-03-04`	Mostra notas de uma data específica
`/memory week`	Mostra notas dos ultimos 7 dias
`/memory longterm`	Mostra o conteúdo do MEMORY.md
`/memory list`	Lista todos os arquivos de memória (inclui JSONs estruturados)
`/memory load <data>`	Carrega notas de um dia no contexto da conversa
`/memory profile`	Mostra o perfil do usuário detectado
`/memory profile set <campo>=<valor>`	Define/atualiza um campo do perfil manualmente
`/memory remember <fato>`	Adiciona um fato de longo prazo explicitamente (aceita prefixo `[categoria]`)
`/memory forget <trecho>`	Remove fatos de longo prazo que contenham o trecho
`/memory topics`	Mostra topicos rastreados com frequência
`/memory projects`	Mostra projetos rastreados com status
`/memory stats`	Estatisticas completas (sessões, horas de pico, erros, features)
`/memory facts [categoria]`	Lista fatos com scores (filtro por categoria)
`/memory compact`	Forca compactação imediata (LLM + cleanup de notas)

Edição manual e perfil estendido

A detecção automática nem sempre captura tudo, então você pode editar a memória explicitamente. O perfil do usuário agora cobre, além de nome/role/expertise: empresa, localização, skills, certificações e metas. Campos de lista (skills, certificações, metas) acumulam e deduplicam.

> /memory profile set company=ACME Corp
> /memory profile set location=São Paulo, BR
> /memory profile set certifications=CKA, AWS SAA   # vira lista, deduplicada
> /memory remember [preference] Prefere Go a Python para CLIs
> /memory forget Python                              # remove fatos contendo "Python"

Tool `@memory` (no modo agente)

Dentro do /agent e /coder, o modelo pode persistir memória sozinho via a tool @memory (cmds remember, profile, forget, recall):

<tool_call name="@memory" args='{"cmd":"remember","args":{"content":"User earned the AWS Solutions Architect certification","category":"personal"}}' />

Assim, quando você conta uma novidade ao agente (ex.: uma certificação nova), ele a grava no seu perfil/fatos de longo prazo sem você precisar rodar /memory manualmente.

O que vai em cada componente?

FactIndex: Fatos estaveis e duradouros — decisoes, padroes, gotchas, preferencias
UserProfile: Quem você e — nome, role, expertise, idioma
TopicTracker: Sobre o que você fala — Go, Docker, K8s, etc.
ProjectTracker: Em que você trabalha — chatcli, meu-app, etc.
PatternDetector: Como você trabalha — horarios, features, erros comuns
Notas diarias: O que aconteceu hoje — temporal e específico

Posso editar as memorias manualmente?

Sim! Todos os arquivos são JSON ou Markdown puro:

# Ver perfil
cat ~/.chatcli/memory/user_profile.json | jq .

# Ver fatos com scores
cat ~/.chatcli/memory/memory_index.json | jq '.[0:5]'

# Editar nota de hoje
vim ~/.chatcli/memory/$(date +%Y%m)/$(date +%Y%m%d).md

Alterações em JSONs são carregadas na proxima inicializacao. O MEMORY.md e regenerado e não deve ser editado diretamente.

Como funciona o scoring de fatos?

Cada fato tem um score calculado por:

score = (1 + log(1 + accessCount)) * exp(-daysSinceAccess * ln(2) / halfLifeDays)

accessCount: Quantas vezes o fato foi usado pelo retriever
daysSinceAccess: Dias desde o ultimo acesso
halfLifeDays: Meia-vida do decay (padrão: 30 dias)

Fatos acessados frequentemente e recentemente tem score alto. Fatos nunca acessados decaem para ~0 após 3-4 meias-vidas.

O que e Injetado no Prompt

O ContextBuilder monta o seguinte bloco e injeta como prefixo do system prompt:

## AGENTS.md

[conteúdo do AGENTS.md]

---

## SOUL.md

[conteúdo do SOUL.md]

---

## USER.md

[conteúdo do USER.md]

---

## IDENTITY.md

[conteúdo do IDENTITY.md]

---

## RULES.md

[conteúdo do RULES.md]

## Path-Specific Rules

[regras condicionais por path — veja abaixo]

---

# Memory

## Long-term Memory

[conteúdo do MEMORY.md]

## Recent Daily Notes

### 2026-03-04

[conteúdo da nota do dia 4]

### 2026-03-05

[conteúdo da nota do dia 5]

### 2026-03-06

[conteúdo da nota de hoje]

Secoes vazias (arquivos inexistentes) são omitidas automaticamente — apenas o que existe e injetado.

Contexto Dinamico (CWD + Desambiguacao)

O ChatCLI injeta automaticamente no system prompt:

Data e hora atuais
Diretório de trabalho atual (CWD do processo)
Instrução de desambiguacao: o modelo e instruido a SEMPRE resolver “aqui”, “este projeto”, paths relativos contra o CWD atual — nunca contra paths da memória de longo prazo

Isso resolve o problema comum onde a memória de longo prazo contem paths de projetos anteriores e o modelo confunde “o projeto atual” com um projeto que estava na memória. Fatos de outros projetos são anotados com (from: /outro/projeto) para deixar claro de onde vieram.

Path-Specific Rules

Alem do RULES.md global, você pode criar regras condicionais por path em .chatcli/rules/:

.chatcli/rules/
├── go-style.md          # Regras para arquivos Go
├── api-conventions.md   # Regras para APIs
└── testing.md           # Regras para testes

Cada arquivo pode ter um frontmatter paths: que define para quais arquivos a regra se aplica:

---
paths: ["*.go", "src/**"]
---

Sempre use error wrapping com fmt.Errorf("%w", err) em Go.
Nunca ignore erros retornados.

Regras sem frontmatter paths: se aplicam globalmente. Regras do workspace (.chatcli/rules/) tem prioridade sobre regras globais (~/.chatcli/rules/) com o mesmo nome.

Veja Path-Specific Rules para documentação completa.

Configuração

Variáveis de Ambiente
Via Helm Chart

CHATCLI_BOOTSTRAP_ENABLED=true
CHATCLI_BOOTSTRAP_DIR=/path/to/bootstrap/files
CHATCLI_MEMORY_ENABLED=true

Variável	Padrão	Descrição
`CHATCLI_BOOTSTRAP_ENABLED`	`true`	Ativa/desativa o carregamento dos arquivos bootstrap
`CHATCLI_BOOTSTRAP_DIR`	`~/.chatcli/`	Diretório alternativo para os arquivos bootstrap globais. Use quando quiser manter seus arquivos (SOUL.md, RULES.md, etc.) em outro local, por exemplo um repositório versionado ou diretório compartilhado entre máquinas
`CHATCLI_MEMORY_ENABLED`	`true`	Ativa/desativa o sistema de memória persistente

CHATCLI_BOOTSTRAP_DIR substitui apenas o diretório global (~/.chatcli/). Arquivos na raiz do projeto (detectada via .git ou .agent) continuam tendo prioridade sobre os globais.

# values.yaml
bootstrap:
  enabled: true
  definitions:
    SOUL.md: |
      Você e um assistente DevOps...
    USER.md: |
      O usuário prefere Go...

memory:
  enabled: true
  # Usa o PVC de persistencia por padrão

O Helm chart cria ConfigMaps para os arquivos bootstrap e monta em /home/chatcli/.chatcli/bootstrap/. A memória usa o PVC de sessões para persistencia.

Boas Praticas

SOUL.md global, USER.md por projeto

Mantenha sua personalidade preferida globalmente e contexto tecnico por projeto.

MEMORY.md conciso

Mantenha apenas fatos estaveis e confirmados — não sessão-específicos.

Notas diarias para journaling

Use para registrar decisoes, problemas resolvidos e contexto temporal.

Não duplique CLAUDE.md

Se você já usa CLAUDE.md ou instruções do projeto, evite duplicar no bootstrap.

Revise periodicamente suas memorias e remova as desatualizadas para manter o contexto relevante.

Otimização de Contexto (Cache de Prompt)

O ChatCLI otimiza o custo de tokens quando contextos estão attached usando tres estrategias complementares:

System Prompt Unificado com Cache

Contextos attached via /context attach são injetados como system prompt, não como mensagens de usuário. Isso permite que providers apliquem cache automático:

Provider	Mecanismo	Desconto
Anthropic	`cache_control: ephemeral`	~90%
OpenAI	Prompt caching automático	~50%
Google	Context caching API	Variável

O bloco de system prompt contem:

Bootstrap (SOUL.md, USER.md, etc.)
Memory (MEMORY.md + notas diarias)
Contextos Attached (novo — antes era user message)
K8s Watcher (se ativo)

Como o system prompt e identico entre turnos, o provider cacheia e cobra tokens com desconto.

Compactação Inteligente

Mensagens de contexto injetado (/memory load, contextos summarizados) são automaticamente truncadas durante a compactação (Level 1 — trimming). Isso evita que contexto referencial antigo consuma budget precioso.

Visibilidade de Tokens

O comando /context attached agora mostra:

Estimativa de tokens por contexto
Total de tokens por turno
Dicas de cache por provider
Alertas para contextos muito grandes

Ao executar /context attach, o feedback inclui a estimativa de custo por turno.

Bootstrap e Memória Persistente

Arquivos Bootstrap

Arquivos Suportados

Prioridade de Carregamento

Detecção Automática do Workspace

Cenarios de Exemplo

Exemplos Detalhados

Onde Colocar os Arquivos

Cache Inteligente

Memória Persistente

Arquitetura do Sistema

Extração resiliente — nada se perde em silêncio

Estrutura de Armazenamento

Componentes

Smart Retrieval

Modo de injeção: push vs pull

Configuração da Memória

Como as Memorias são Criadas

Processo de Extracao

Compactação Automatica

Migração Automatica

Comando `/memory`

Edição manual e perfil estendido

Tool `@memory` (no modo agente)

O que e Injetado no Prompt

Contexto Dinamico (CWD + Desambiguacao)

Path-Specific Rules

Configuração

Boas Praticas

SOUL.md global, USER.md por projeto

MEMORY.md conciso

Notas diarias para journaling

Não duplique CLAUDE.md

Otimização de Contexto (Cache de Prompt)

System Prompt Unificado com Cache

Compactação Inteligente

Visibilidade de Tokens

Próximos Passos

Controle de Conversa

Sessões

​Arquivos Bootstrap

​Arquivos Suportados

​Prioridade de Carregamento

​Detecção Automática do Workspace

​Cenarios de Exemplo

​Exemplos Detalhados

​Onde Colocar os Arquivos

​Cache Inteligente

​Memória Persistente

​Arquitetura do Sistema

​Extração resiliente — nada se perde em silêncio

​Estrutura de Armazenamento

​Componentes

​Smart Retrieval

​Modo de injeção: push vs pull

​Configuração da Memória

​Como as Memorias são Criadas

​Processo de Extracao

​Compactação Automatica

​Migração Automatica

​Comando /memory

​Edição manual e perfil estendido

​Tool @memory (no modo agente)

​O que e Injetado no Prompt

​Contexto Dinamico (CWD + Desambiguacao)

​Path-Specific Rules

​Configuração

​Boas Praticas

SOUL.md global, USER.md por projeto

MEMORY.md conciso

Notas diarias para journaling

Não duplique CLAUDE.md

​Otimização de Contexto (Cache de Prompt)

​System Prompt Unificado com Cache

​Compactação Inteligente

​Visibilidade de Tokens

​Próximos Passos

Controle de Conversa

Sessões

Arquivos Bootstrap

Arquivos Suportados

Prioridade de Carregamento

Detecção Automática do Workspace

Cenarios de Exemplo

Exemplos Detalhados

Onde Colocar os Arquivos

Cache Inteligente

Memória Persistente

Arquitetura do Sistema

Extração resiliente — nada se perde em silêncio

Estrutura de Armazenamento

Componentes

Smart Retrieval

Modo de injeção: push vs pull

Configuração da Memória

Como as Memorias são Criadas

Processo de Extracao

Compactação Automatica

Migração Automatica

Comando `/memory`

Edição manual e perfil estendido

Tool `@memory` (no modo agente)

O que e Injetado no Prompt

Contexto Dinamico (CWD + Desambiguacao)

Path-Specific Rules

Configuração

Boas Praticas

Otimização de Contexto (Cache de Prompt)

System Prompt Unificado com Cache

Compactação Inteligente

Visibilidade de Tokens

Próximos Passos