Bootstrap e Memória Persistente

​

Arquivos Bootstrap

​

Arquivos Suportados

​

Prioridade de Carregamento

​

Detecção Automática do Workspace

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

​

Cenarios de Exemplo

​

Exemplos Detalhados

# 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

# 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

# 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

# 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

# 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

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

​

Cache Inteligente

• 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

​

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

1. 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.
2. 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.
3. 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.

​

Estrutura de Armazenamento

~/.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)
|-- weekly/                # Digests semanais (consolidados de notas diarias)
|   +-- 2026-W27.md
|-- monthly/               # Digests mensais (mantidos para sempre)
|   +-- 2026-06.md
|-- 202603/                # Notas diarias de marco 2026
|   |-- 20260301.md
|   +-- 20260306.md
+-- 202602/
    +-- 20260228.md

​

Componentes

​

Smart Retrieval

1. Extrai keywords das ultimas mensagens da conversa
2. Busca fatos relevantes no FactIndex por keyword match + score temporal
3. Respeita um budget configurável (padrão: 4000 caracteres)
4. Prioriza: Perfil > Projetos > Topicos > Fatos relevantes > Notas recentes > Trajetória (digests) > Padrões de uso

​

Modo de injeção: push vs pull

​

Configuração da Memória

​

Como as Memorias são Criadas

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

​

Processo de Extracao

1. EnhancedExtractionPrompt: Envia o histórico recente da conversa para o LLM com um prompt estruturado solicitando extracao de informações
2. 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
3. ParseEnhancedResponse(): Faz o parse da resposta e extrai cada seção individualmente
4. 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
5. Merge de perfil com ciclo de vida: Atualizações de PROFILE_UPDATE são mescladas com o perfil existente. Campos de lista fazem upsert (reafirmar um item supera o antigo em vez de duplicar), e a extração pode emitir operações de reescrita: goals_done=/goals_remove= removem objetivos concluídos (movendo-os para milestone=/certifications=), goals_replace= substitui a lista inteira — os mesmos sufixos valem para certificações, skills, interesses e diretivas. Instruções suas sobre o perfil (“remove X dos objetivos”) são aplicadas, nunca gravadas como se fossem fatos

​

Compactação Automatica

​

Digests Semanais e Mensais (Trajetória)

• Ao fim de cada semana ISO, as notas diárias daquela semana consolidam em weekly/2026-W27.md (resumo via LLM com fallback determinístico — nunca depende do provider estar de pé).
• Ao fim de cada mês, os digests semanais consolidam em monthly/2026-06.md.
• Retenção: semanais guardam ~26 semanas; mensais ficam para sempre (custo mínimo).
• Uma seção Trajectory limitada entra no contexto de memória com o último mensal + semanais recentes — é assim que “o que você andou fazendo nos últimos meses” sobrevive à limpeza das notas diárias.

​

Migração Automatica

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

​

Comando /memory

​

Edição manual e perfil estendido

> /memory profile set company=ACME Corp
> /memory profile set certifications=CKA, AWS SAA        # upsert, deduplicado
> /memory profile set goals_done=tirar CKA               # objetivo concluído sai da lista
> /memory profile set milestone=Concluiu a CKA           # ...e vira marco datado
> /memory profile set goals_replace=lançar o produto Y   # substitui TODOS os objetivos
> /memory profile set stance=preferir backends keyless :: menos atrito de setup
> /memory profile set directives=[scope:meu-repo] sempre rodar o linter antes do push
> /memory profile set env_shell=zsh
> /memory profile set sensitive_mark=renda_mensal        # marca como privado
> /memory remember [preference] Prefere Go a Python para CLIs
> /memory forget Python                                  # remove FATOS contendo "Python"

​

Tool @memory (agent, coder e chat)

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

​

Grafo de conhecimento (@memory neighbors / map)

• recall → busca por conteúdo (“quais fatos casam com estas palavras?”).
• neighbors <assunto> → grafo local: backlinks + notas conectadas de um assunto (“o que está ligado a isto?”).
• map → visão geral (contagens por tipo + hubs).

​

Qualidade dos fatos (confiança, proveniência, reconciliação)

# 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

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

​

O que e Injetado no 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]

​

Contexto Dinamico (CWD + Desambiguacao)

• 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

​

Path-Specific Rules

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

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

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

​

Configuração

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

# 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

​

Boas Praticas

​

Otimização de Contexto (Cache de Prompt)

​

System Prompt Unificado com Cache

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

​

Compactação Inteligente

​

Visibilidade de Tokens

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

​

Próximos Passos