Bootstrap e Memoria Persistente

O ChatCLI oferece dois sistemas complementares para personalizar e contextualizar o agente: arquivos bootstrap para definir personalidade e regras, e memoria persistente para manter contexto entre sessoes.

O sistema de bootstrap e memoria esta totalmente conectado ao fluxo de system prompt. Os arquivos sao carregados automaticamente e injetados em todas as interacoes — tanto no modo chat quanto nos modos /agent e /coder.

Arquivos Bootstrap

Os arquivos bootstrap sao 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 sao opcionais — se nao existirem, sao simplesmente ignorados:

Arquivo	Proposito	Quando usar
`AGENTS.md`	Definicoes de sub-agentes e seus papeis	Quando voce 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 usuario/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, limitacoes
`RULES.md`	Regras e restricoes explicitas	Para guardrails rigidos — o que ele DEVE e NAO DEVE fazer

Os nomes dos arquivos sao 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.) nao sao carregados pelo bootstrap.

Prioridade de Carregamento

Os arquivos sao buscados em dois niveis, com o workspace tendo prioridade:

Workspace (./)

Configuracoes especificas do projeto. Tem prioridade sobre o global.

Global (~/.chatcli/)

Configuracoes padrao do usuario. Serve como fallback quando o arquivo nao existe no workspace.

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

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

Voce e um assistente tecnico especializado em engenharia de software.
Seja conciso e direto. Prefira exemplos praticos a explicacoes teoricas.
Quando sugerir codigo, use boas praticas e testes.

# Tom

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

Define contexto do usuario e projeto. Ideal para ./USER.md no diretorio 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 comparacoes
- 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

Voce e o ChatCLI, um assistente de terminal inteligente.

## Capacidades

- Leitura e edicao de codigo via @coder plugin
- Execucao de comandos shell com aprovacao do usuario
- Analise de logs e diagnostico de erros
- Operacoes Git (status, diff, log, commit)

## Limitacoes

- Voce NAO tem acesso a internet
- Voce NAO pode instalar pacotes sem aprovacao
- 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 confirmacao explicita
2. NUNCA commite diretamente na branch main
3. SEMPRE rode testes apos modificar codigo
4. SEMPRE use conventional commits (feat:, fix:, chore:)

# Restricoes de Seguranca

- Nao exponha secrets, tokens ou API keys em logs
- Nao modifique arquivos fora do diretorio do projeto
- Nao 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 configuracao de pipelines.

## @dba
Especialista em banco de dados PostgreSQL.
Use para queries, otimizacao, migrations e analise de performance.

## @security
Auditor de seguranca focado em OWASP Top 10.
Use para revisao de codigo com foco em vulnerabilidades.

Onde Colocar os Arquivos

# Configuracao GLOBAL (vale para todos os projetos)
~/.chatcli/SOUL.md
~/.chatcli/IDENTITY.md
~/.chatcli/RULES.md
~/.chatcli/USER.md
~/.chatcli/AGENTS.md

# Configuracao por PROJETO (override do global)
./SOUL.md          # Na raiz do projeto
./USER.md          # Na raiz do projeto
./RULES.md         # Na raiz do projeto (regras do projeto)
./IDENTITY.md      # Na raiz do projeto (raro)
./AGENTS.md        # Na raiz do projeto (agents do projeto)

A estrategia recomendada: SOUL.md e IDENTITY.md globais (sao sobre o assistente), USER.md e RULES.md por projeto (sao sobre o contexto de trabalho).

Cache Inteligente

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

Na primeira leitura, o conteudo e cacheado em memoria
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

Memoria Persistente

O sistema de memoria mantem contexto entre sessoes do ChatCLI, permitindo que o agente “lembre” de fatos, decisoes e padroes ao longo do tempo.

Estrutura de Armazenamento

Toda a memoria fica em ~/.chatcli/memory/:

~/.chatcli/memory/
|-- MEMORY.md              # Memoria de longo prazo (fatos persistentes)
|-- 202603/                # Notas diarias de marco 2026
|   |-- 20260301.md        # Notas de 1 de marco
|   |-- 20260302.md        # Notas de 2 de marco
|   +-- 20260306.md        # Notas de hoje
+-- 202602/                # Notas diarias de fevereiro 2026
    +-- 20260228.md        # Notas de 28 de fevereiro

As notas diarias ficam diretamente em subdiretorios YYYYMM/ dentro de ~/.chatcli/memory/, nomeadas como YYYYMMDD.md. Nao existe subdiretorio daily/.

MEMORY.md — Memoria de Longo Prazo

O ~/.chatcli/memory/MEMORY.md armazena fatos persistentes que o agente recebe em toda interacao:

# Decisoes Arquiteturais

- Usamos go-prompt v0.2.6 para TUI interativa
- Charmbracelet (glamour, lipgloss) apenas para styling, nao para TUI
- Message bus desacoplado via cli/bus para I/O do agente

# Padroes do Projeto

- json.Compact recebe *bytes.Buffer, nao *strings.Builder
- embed.FS sempre usa / nos caminhos, nunca filepath.Join
- Parsers stateful > regex para XML com atributos especiais

Notas Diarias — Journaling Temporal

As notas diarias registram o que aconteceu em cada dia. O ChatCLI carrega automaticamente as ultimas 3 notas no prompt. Cada entrada recebe um timestamp automatico (hora:minuto):

## 14:32

Implementado fallback chain para provedores LLM.
Adicionado suporte a MCP via stdio/SSE.
47 arquivos alterados, +4920 linhas.

## 16:15

Decisao: usar init() auto-registration para provedores no registry.
Decisao: cache_control:ephemeral para otimizacao de KV cache na Anthropic.

Como as Memorias sao Criadas

As memorias sao gravadas automaticamente por um worker em background. O usuario nao precisa fazer nada.

Anotacao Automatica (Background Memory Worker)

O ChatCLI roda um worker em background que analisa periodicamente o historico da conversa e usa a IA para extrair anotacoes:

Apos cada resposta da IA (em qualquer modo: chat, agent, coder), o worker e “cutucado”
Se houver 4+ novas mensagens desde a ultima extracao e pelo menos 2 minutos desde a ultima execucao, o worker dispara
O worker envia as mensagens novas para a IA com um prompt de extracao estruturada
A IA retorna dois blocos: DAILY (o que foi feito) e LONGTERM (fatos novos para lembrar)
Os resultados sao gravados automaticamente em MEMORY.md e na nota diaria
Um indicador sutil ⟳ updating memory... aparece brevemente (apenas quando o prompt esta ocioso)

O worker tambem roda periodicamente a cada 3 minutos, capturando anotacoes mesmo em sessoes longas de agent/coder.

O processo e totalmente transparente — voce nao precisa intervir. A IA decide sozinha o que e importante anotar. Fatos ja existentes no MEMORY.md nao sao duplicados.

Comando `/memory` — Consultar e Carregar Notas

Use /memory para ver e carregar anotacoes:

Subcomando	Descricao
`/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 especifica
`/memory week`	Mostra notas dos ultimos 7 dias
`/memory longterm`	Mostra o conteudo do MEMORY.md
`/memory list`	Lista todos os arquivos de memoria
`/memory load <data>`	Carrega notas de um dia no contexto da conversa atual

O /memory load e especialmente util para retomar trabalho de dias anteriores:

/memory load yesterday

Isso injeta as notas de ontem na conversa, permitindo que a IA continue de onde parou.

O que vai no MEMORY.md vs notas diarias?

MEMORY.md: Fatos estaveis e duradouros — decisoes arquiteturais, padroes do projeto, convencoes de equipe, preferencias confirmadas. Acumulativo ao longo de muitas sessoes.
Notas diarias (YYYYMM/YYYYMMDD.md): Registros temporais e especificos — o que foi feito naquele dia, erros encontrados, arquivos modificados, tarefas em progresso.

Posso editar as memorias manualmente?

Sim! Os arquivos sao Markdown puro — edite com qualquer editor:

# Editar memoria de longo prazo
vim ~/.chatcli/memory/MEMORY.md

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

# Ver todas as notas
find ~/.chatcli/memory/ -name "*.md" -type f | sort

As alteracoes sao captadas automaticamente na proxima interacao (cache invalida por mtime).

Quais informacoes a IA extrai automaticamente?

O worker de extracao pede para a IA identificar:Notas diarias (DAILY):

Arquivos lidos, modificados ou criados (com paths)
Comandos executados e seus resultados
Erros encontrados e como foram resolvidos
Tarefas completas ou em progresso

Memoria de longo prazo (LONGTERM):

Decisoes arquiteturais tomadas
Padroes ou convencoes descobertos/estabelecidos
Preferencias expressas pelo usuario
Insights sobre estrutura do projeto
Gotchas e restricoes tecnicas

Se nao houver nada novo para anotar, a IA simplesmente pula.

O que e Injetado no Prompt

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

## AGENTS.md

[conteudo do AGENTS.md]

---

## SOUL.md

[conteudo do SOUL.md]

---

## USER.md

[conteudo do USER.md]

---

## IDENTITY.md

[conteudo do IDENTITY.md]

---

## RULES.md

[conteudo do RULES.md]

---

# Memory

## Long-term Memory

[conteudo do MEMORY.md]

## Recent Daily Notes

### 2026-03-04

[conteudo da nota do dia 4]

### 2026-03-05

[conteudo da nota do dia 5]

### 2026-03-06

[conteudo da nota de hoje]

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

Configuracao

Variaveis de Ambiente
Via Helm Chart

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

# values.yaml
bootstrap:
  enabled: true
  definitions:
    SOUL.md: |
      Voce e um assistente DevOps...
    USER.md: |
      O usuario prefere Go...

memory:
  enabled: true
  # Usa o PVC de persistencia por padrao

O Helm chart cria ConfigMaps para os arquivos bootstrap e monta em /home/chatcli/.chatcli/bootstrap/. A memoria usa o PVC de sessoes 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 — nao sessao-especificos.

Notas diarias para journaling

Use para registrar decisoes, problemas resolvidos e contexto temporal.

Nao duplique CLAUDE.md

Se voce ja usa CLAUDE.md ou instrucoes do projeto, evite duplicar no bootstrap.

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

Otimizacao de Contexto (Cache de Prompt)

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

System Prompt Unificado com Cache

Contextos attached via /context attach sao injetados como system prompt, nao como mensagens de usuario. Isso permite que providers apliquem cache automatico:

Provider	Mecanismo	Desconto
Anthropic	`cache_control: ephemeral`	~90%
OpenAI	Prompt caching automatico	~50%
Google	Context caching API	Variavel

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.

Compactacao Inteligente

Mensagens de contexto injetado (/memory load, contextos summarizados) sao automaticamente truncadas durante a compactacao (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.

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Suporte

Bootstrap e Memoria Persistente

Arquivos Bootstrap

Arquivos Suportados

Prioridade de Carregamento

Exemplos Detalhados

Onde Colocar os Arquivos

Cache Inteligente

Memoria Persistente

Estrutura de Armazenamento

MEMORY.md — Memoria de Longo Prazo

Notas Diarias — Journaling Temporal

Como as Memorias sao Criadas

Anotacao Automatica (Background Memory Worker)

Comando `/memory` — Consultar e Carregar Notas

O que e Injetado no Prompt

Configuracao

Boas Praticas

SOUL.md global, USER.md por projeto

MEMORY.md conciso

Notas diarias para journaling

Nao duplique CLAUDE.md

Otimizacao de Contexto (Cache de Prompt)

System Prompt Unificado com Cache

Compactacao Inteligente

Visibilidade de Tokens

Proximos Passos

Controle de Conversa

Sessoes

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Suporte

​Arquivos Bootstrap

​Arquivos Suportados

​Prioridade de Carregamento

​Exemplos Detalhados

​Onde Colocar os Arquivos

​Cache Inteligente

​Memoria Persistente

​Estrutura de Armazenamento

​MEMORY.md — Memoria de Longo Prazo

​Notas Diarias — Journaling Temporal

​Como as Memorias sao Criadas

​Anotacao Automatica (Background Memory Worker)

​Comando /memory — Consultar e Carregar Notas

​O que e Injetado no Prompt

​Configuracao

​Boas Praticas

SOUL.md global, USER.md por projeto

MEMORY.md conciso

Notas diarias para journaling

Nao duplique CLAUDE.md

​Otimizacao de Contexto (Cache de Prompt)

​System Prompt Unificado com Cache

​Compactacao Inteligente

​Visibilidade de Tokens

​Proximos Passos

Controle de Conversa

Sessoes

Arquivos Bootstrap

Arquivos Suportados

Prioridade de Carregamento

Exemplos Detalhados

Onde Colocar os Arquivos

Cache Inteligente

Memoria Persistente

Estrutura de Armazenamento

MEMORY.md — Memoria de Longo Prazo

Notas Diarias — Journaling Temporal

Como as Memorias sao Criadas

Anotacao Automatica (Background Memory Worker)

Comando `/memory` — Consultar e Carregar Notas

O que e Injetado no Prompt

Configuracao

Boas Praticas

Otimizacao de Contexto (Cache de Prompt)

System Prompt Unificado com Cache

Compactacao Inteligente

Visibilidade de Tokens

Proximos Passos