> ## 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. # Bootstrap e Memória Persistente > Personalize a identidade do agente com arquivos bootstrap e mantenha contexto entre sessões com memória de longo prazo e notas diarias. 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: Configurações específicas do projeto. Tem **prioridade** sobre o global. A raiz do projeto e detectada automaticamente (veja abaixo). 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: 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 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 Define **personalidade e tom**. Coloque em `~/.chatcli/SOUL.md` (global) ou `./SOUL.md` (projeto): ```markdown theme={"system"} # 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: ```markdown theme={"system"} # 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`: ```markdown theme={"system"} # 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: ```markdown theme={"system"} # 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: ```markdown theme={"system"} # 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. ```text theme={"system"} # 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/ /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) ``` `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 ```text theme={"system"} 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: 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. 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](/pt/features/chat-gateway). ### Estrutura de Armazenamento Toda a memória fica em `~/.chatcli/memory/`: ```text theme={"system"} ~/.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 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. Detectado automaticamente pela IA durante a extracao e editável por você/pelo modelo em qualquer modo: * Nome, role, nível de expertise, empresa, localização * Idioma preferido e estilo de comunicação * Listas com ciclo de vida: **certificações, skills, objetivos, interesses e diretivas** (reafirmar um item **supera** o antigo em vez de duplicar; sufixos `_replace`/`_done`/`_remove` reescrevem) * **Diretivas** com severidade (regras duras vs preferências) e **escopo por projeto** (`[scope:] regra` só é injetada quando aquele workspace está ativo) * **Posições** (`stance`) — opiniões técnicas gravadas **com o porquê** (`"posição :: razão"`) * **Marcos** (`milestone`) — linha do tempo datada do que aconteceu * **Ambiente** estruturado (`env_os`, `env_shell`, ...) — migrado automaticamente das preferences legadas * **Proveniência e frescor por campo**: cada atributo sabe se veio de você ou da extração e quando foi confirmado; campos sem reconfirmação há 120+ dias são sinalizados como possivelmente desatualizados no prompt * **Camada de privacidade**: chaves de finanças/saúde/família/documentos são auto-marcadas `[sensitive]` — personalizam respostas, mas nunca entram em código, exemplos ou artefatos gerados (`sensitive_mark`/`sensitive_unmark` para controle manual) * Comandos mais usados (top 10) e preferencias gerais Veja com `/memory profile`. Perfis antigos poluídos por versões append-only se **auto-curam no próximo load** (fragmentos, duplicatas de progresso e objetivos concluídos saem sozinhos). Rastreia topicos tecnicos discutidos: * Frequência de mencoes * Recencia (topicos recentes pesam mais) * Links com fatos relacionados Veja com `/memory topics`. Rastreia projetos em que você trabalha: * Nome, path, descrição * Tecnologias usadas * Status (active, paused, completed) * Ultima atividade Veja com `/memory projects`. 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**: 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 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](/pt/features/token-efficiency) 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): 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 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: 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 O sistema executa compactação periodica para evitar crescimento descontrolado: Checa se o número de fatos ultrapassa 80% do limite ou se passaram 24h desde a ultima compactação. Envia todos os fatos para a IA com instruções para: merge duplicatas, remover obsoletos, consolidar relacionados. Se a chamada LLM falhar, arquiva fatos com score abaixo de 0.1 em `memory_archive.json`. Remove notas mais antigas que o periodo de retencao (padrão: 30 dias). Reescreve MEMORY.md a partir do FactIndex -- sempre atualizado, nunca source of truth. ### Digests Semanais e Mensais (Trajetória) Notas diárias expiram em \~30 dias — os **rollups** preservam a narrativa de longo prazo antes disso: * 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. O processo é idempotente e roda sozinho no worker de memória (checagem no startup e a cada 12h). ### 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: 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` | 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 ` | Carrega notas de um dia no contexto da conversa | | `/memory profile` | Mostra o perfil do usuário detectado | | `/memory profile set =` | Define/atualiza um campo do perfil manualmente | | `/memory remember ` | Adiciona um fato de longo prazo explicitamente (aceita prefixo `[categoria]`) | | `/memory forget ` | 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**. Além de nome/role/expertise/empresa/localização, o perfil cobre **certificações, skills, objetivos, interesses, diretivas, posições (stance), marcos (milestone) e ambiente (env\_\*)**. Campos de lista têm **ciclo de vida**, não são append-only: novos itens entram, um item reafirmado (mesmo texto fora do status/parêntese) **supera** o antigo no lugar, e sufixos de operação reescrevem — `_replace` substitui a lista inteira (valor vazio limpa), `_done`/`_remove` removem itens que casem. Vírgulas dentro de parênteses são seguras (`"Quiz X (Provider, 60 questões)"` fica inteiro). ```text theme={"system"} > /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" ``` `forget` atua só em **fatos**; para remover itens do perfil use os sufixos (`goals_remove=...`). Diretivas com `[scope:]` só são injetadas quando aquele workspace está ativo; sem a tag, valem globalmente. #### Tool `@memory` (agent, coder e chat) Dentro do `/agent` e `/coder`, o modelo pode persistir e explorar memória sozinho via a tool **`@memory`** (cmds `remember`, `profile`, `forget`, `recall`, `neighbors`, `map`): ```text theme={"system"} ``` 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 subcomando `profile` aceita todas as operações de ciclo de vida (`goals_done`, `goals_replace`, `stance`, `milestone`, `env_*`, `sensitive_mark`, ...). **No chat também**: atualização de memória/perfil é a **quarta exceção sancionada** do chat tool-less (junto de `ask_user`, knowledge read-only e `@graphview`). Quando você revela ou corrige um fato durável sobre si, o modelo persiste **no mesmo turno** — nada de "vou considerar daqui pra frente" sem gravar. Controlada por `CHATCLI_CHAT_MEMORY` (**ligada por padrão**) e alternável com `/config chat memory on|off`. #### Grafo de conhecimento (`@memory neighbors` / `map`) O que o ChatCLI sabe sobre você não é uma lista plana: facts, tópicos, projetos, skills e tags formam um **grafo derivado on-demand** (estilo Obsidian, no core) a partir das relações que os stores já guardam (tópico↔fato, fato→projeto, tags, triggers de skill) mais `[[wikilinks]]` no texto. Acesso pelo próprio `@memory`: * `recall` → busca por **conteúdo** ("quais fatos casam com estas palavras?"). * `neighbors ` → **grafo local**: backlinks + notas conectadas de um assunto ("o que está ligado a isto?"). * `map` → visão geral (contagens por tipo + hubs). Disciplina de contexto: por turno entra só um *index card* minúsculo e determinístico (cache-friendly); a profundidade é puxada sob demanda. Para visualizar, use [`/graph`](#) (renderiza o grafo em imagem via go-graphviz embarcado). #### Qualidade dos fatos (confiança, proveniência, reconciliação) Cada fato carrega **confiança** e **proveniência**: o que você afirma diretamente vale mais que um palpite da extração de fundo, e um fato re-observado sobe de confiança — a confiança pondera o score (ranking e sobrevivência ao decay/poda). Ao gravar, o ChatCLI **reconcilia**: uma reformulação reforça o fato existente em vez de duplicar, e uma atualização do mesmo assunto com confiança igual ou maior **substitui** o fato obsoleto (conservador — um palpite fraco nunca apaga um fato forte). Tópicos ganham um **resumo rolante** do que foi discutido, virando nós de conhecimento de verdade. Índices de memória legados são enriquecidos uma vez no startup, sem perder nada. * **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 Sim! Todos os arquivos são JSON ou Markdown puro: ```bash theme={"system"} # 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. 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: ```text theme={"system"} ## 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/`: ```text theme={"system"} .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: ```markdown theme={"system"} --- 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](/pt/features/path-rules) para documentação completa. *** ## Configuração ```bash theme={"system"} 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. ```yaml theme={"system"} # 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 Mantenha sua personalidade preferida globalmente e contexto tecnico por projeto. Mantenha apenas fatos estaveis e confirmados — não sessão-específicos. Use para registrar decisoes, problemas resolvidos e contexto temporal. 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: 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) 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. *** ## Próximos Passos Use /compact e /rewind para gerenciar o tamanho e estado da conversa. Salve e reutilize conversas entre projetos.