🏷️ Donos da informação
Fato, preferência, hipótese, decisão. Quando você tem três versões da mesma informação espalhadas em memória, CLAUDE.md e sessões antigas, qual vale? Este módulo dá a resposta: cada tipo de informação tem um dono, uma origem, uma data e uma regra de atualização. É isso que faz o "cérebro" sobreviver à troca de modelo sem virar bagunça.
🧩 Os quatro tipos e por que misturá-los quebra
Toda informação que vive no seu workspace é de um de quatro tipos: um fato (algo verificado, com fonte), uma preferência (como você gosta que as coisas sejam feitas), uma hipótese (algo que parece verdade, mas ninguém confirmou) ou uma decisão (uma escolha aceita, com contexto e consequências). O erro mais comum de quem usa agentes é jogar tudo no mesmo saco: a memória automática do Claude grava "o usuário prefere X" ao lado de "a porta do servidor é 8000" ao lado de "acho que o build quebrou por causa do cache". Três tipos diferentes, tratados como iguais.
Leia cada caixa de cima pra baixo: o tipo, um exemplo real deste curso, quem é o dono, a regra que muda a informação, e onde ela mora. Só o fato tem glow porque é o único que exige fonte; a hipótese tem borda tracejada porque é provisória por definição.
Novo aqui? "Fonte" é de onde a informação veio: um arquivo, um comando que você rodou, uma página. Um fato sem fonte é só uma frase que alguém escreveu um dia. "Provenance" (proveniência) é a palavra técnica pra isso: a trilha de origem de um dado. Vamos usar bastante neste módulo.
✓ Separado por tipo
- ✓Um agente novo sabe o que pode confiar e o que precisa checar.
- ✓Uma preferência não vira "verdade sobre o mundo".
- ✓Hipótese envelhece e é descartada sem dó.
- ✓Decisão tem contexto: dá pra revogar sabendo o porquê.
✗ Tudo no mesmo saco
- ✗"Acho que" de três meses atrás vira instrução obrigatória.
- ✗O agente cita um chute como se fosse fato verificado.
- ✗Ninguém sabe quem pode mudar o quê.
- ✗Ao trocar de modelo, o ruído migra junto com o sinal.
Conceitos-chave
Verificado, com fonte e data. Muda só com nova fonte.
Como o dono quer. Só o dono altera.
Provisória. Ou vira fato ou é descartada.
Escolha aceita com contexto e consequências.
📇 Origem, escopo, data, estado, regra de atualização
O Prompt B (o mega-prompt de workspace portátil) pede que toda nota durável registre cinco coisas: um ID, o escopo (vale pra este projeto? pra este cliente? pra tudo?), a fonte, a data de observação e o estado (rascunho, aceito, revogado), mais uma regra de quando revisar ou expirar. Parece burocracia. Não é: é o mínimo pra que um agente que nunca viu o projeto consiga responder "de onde veio isso e ainda vale?".
Nota durável de exemplo — o cabeçalho que o template context/overview.md do kit já traz
# Overview — agente-claude-codex
- ID: overview | Escopo: este repo | Fonte: docs/ (3 textos + PDF) e auditoria local
- Data de observação: 2026-09-13 | Status: aceito | Revisar em: ao mudar versão do Codex ou do Claude Code
## Fatos verificados (2026-09-13)
- Codex CLI 0.154.0 não tem comando `import`; o import "um clique" é do app desktop.
- polyskill 0.1.0 instalado globalmente.
## Preferências do dono
- Audit primeiro, sem cópia em massa, segredos fora.
## Hipóteses (não verificadas)
- A classificação heurística de 71 skills como "reutilizável" está correta na maioria; precisa amostragem.Repare que o mesmo arquivo tem três seções separadas: fatos (com data), preferências e hipóteses. Um agente que lê isso sabe exatamente com que peso tratar cada linha. E o campo "Revisar em" diz quando o fato pode ter envelhecido: quando o Codex mudar de versão, a linha sobre o import precisa ser conferida de novo.
ID e escopo
Um nome estável pra ser citado por outros arquivos, e a resposta a "vale onde?". Um fato de cliente nunca tem escopo global.
Fonte e data de observação
De onde veio e quando foi visto. "Data de observação" não é "data de escrita": é quando a realidade foi checada.
Estado e regra de revisão
Rascunho, aceito ou revogado. E o gatilho de revisão: uma data, ou um evento ("quando o Codex atualizar").
Novo aqui? "Escopo" é o alcance de uma informação: global (vale pra você em qualquer projeto), de projeto (vale só aqui) ou de cliente (vale só pra aquele cliente). Confundir escopo é como colocar a senha de um cliente no arquivo de regras gerais: a informação certa, no lugar errado, vira problema.
Conceitos-chave
Informação que sobrevive à sessão e precisa de metadados.
Quando a realidade foi checada, não quando o texto foi digitado.
Rascunho, aceito, revogado. Diz se pode confiar.
O gatilho que obriga reconferir o fato.
⚖️ Provenance vence timestamp
Quando duas versões de uma informação se contradizem, o instinto é ficar com a mais recente. O Prompt B proíbe exatamente isso: resolva conflitos por proveniência e decisão aceita, não por "qual timestamp é mais novo". Por quê? Porque a versão mais nova pode ser um chute de uma sessão apressada, e a antiga pode ser um fato verificado com fonte. Data de escrita não mede confiabilidade.
A versão da esquerda é mais antiga e vence porque tem fonte e status aceito. A da direita é mais nova e perde: sem fonte, é hipótese. Ela recebe superseded_by (substituída por) e fica tracejada, mas não é apagada.
🔬 Como o openpcbotv3 faz isso de verdade
O bot v3 desta máquina tem uma consolidação noturna de memória. Ela funde duplicatas e, quando detecta contradição entre duas memórias, a antiga recebe superseded_by apontando pra nova, e nunca é apagada. O mesmo mecanismo serve pro caminho inverso: se a "nova" for a que perde, é ela que recebe a marca. O ponto é que nada some; só muda o que está em vigor.
- •Apagar destrói a trilha. Você perde o "por que achávamos isso".
- •Esconder preserva a trilha e mantém só uma versão ativa.
- •Backup antes de cada rodada de consolidação, porque errar aqui apaga contexto.
Novo aqui? "Timestamp" é o carimbo de data e hora de quando algo foi gravado. "Superseded" (substituído) é o estado de uma informação que foi trocada por outra mais confiável. Guardar a substituída com um ponteiro pra vencedora é o que permite reconstruir a história depois.
Conceitos-chave
A trilha de origem. Decide quem vence um conflito.
Vence qualquer versão sem aceite, nova ou velha.
Marca a versão que perdeu, sem apagar.
Recente não significa correto.
⬆️ Promover fato: de memória bruta a overview aprovado
O Claude Code grava memória sozinho: nesta máquina são 869 arquivos em 227 pastas. Nenhum passou por aprovação. Isso não é fonte de verdade; é matéria-prima. O Prompt B diz "promova fatos verificados deliberadamente da memória nativa ou das conversas". Promover é o ato consciente de pegar uma linha da memória bruta, verificar, dar fonte e data, e só então gravar no context/overview.md como fato aceito.
Memória bruta gravada
O agente escreveu "o usuário usa flux2-klein por padrão" numa sessão qualquer. Sem fonte, sem data.
Proposta
Ao tocar no projeto, o agente propõe: "isto parece uma preferência estável; promover pro overview?"
Verificação e aprovação humana
Você confirma (ou corrige: "é preferência, não fato"). Ganha fonte ("regra global do CLAUDE.md"), data e status aceito.
Gravado no lugar certo
Vai pra seção correta do overview. A memória bruta continua existindo como evidência, separada.
🗃️ O vault do openpcbotv3: "o bot propõe, você aprova"
O bot v3 mantém dois arquivos curados, ~/vault/MEMORY.md e USER.md. O bot propõe entradas; nada é escrito sem você aprovar. O USER.md entra em todo prompt. É a mesma ideia de promoção, já rodando: a memória automática do banco é matéria-prima; o vault é o overview aprovado. O plano de migração desta máquina usa esse vault como overview global de fatos pessoais.
Na Trilha 3, Projeto 3, você liga Claude, Codex e o dsh pra lerem o mesmo USER.md.
✓ Promover
- ✓Um fato por vez, ao tocar no projeto.
- ✓Com verificação e aprovação humana.
- ✓Ganha ID, escopo, fonte, data, status.
- ✓Evidência bruta preservada à parte.
✗ Copiar em massa
- ✗Despejar os 869 arquivos de memória no
context/. - ✗Transportar chutes, duplicatas e fatos mortos junto.
- ✗Sem fonte: o agente novo não sabe em que confiar.
- ✗O ruído do Claude vira ruído do Codex.
Conceitos-chave
Memória nativa e sessões: evidência, não fonte.
Ato deliberado de verificar e gravar com metadados.
O agente sugere, o humano decide. Nada automático.
MEMORY.md e USER.md: o overview aprovado do openpcbotv3.
🔁 Índices rebuildáveis a partir das fontes
Busca semântica, embeddings, banco de vetores, cache de resumo: tudo isso é índice, e índice é derivado. O Prompt B fecha a seção de propriedade com uma regra simples: "torne os índices de busca reconstruíveis a partir dos registros-fonte que você possui". Se o índice corromper, mudar de ferramenta ou de modelo de embedding, você roda o build de novo e ele volta. Se a única cópia da informação estiver dentro do índice, você perdeu.
📊 Exemplos reais desta máquina
- •openpcbotv3: vetores
bge-m3são reindexados por cron a cada 15 min a partir da tabela de memórias. Apagar o índice não perde nada. - •Catálogo INEMA:
courses.data.json,cursos.json,base.jsonsão todos gerados. A fonte é ocourses.tse oPortal.tsx. Editar o gerado na mão é o erro que a skill do portal proíbe. - •Kit de migração:
relatorios/auditoria-*.mdé gerado peloaudit.sh. Rodou de novo, refez.
Novo aqui? "Embedding" é um jeito de transformar texto em números pra que um programa ache textos parecidos. "Índice" é qualquer estrutura montada pra achar coisas mais rápido. Ambos são cópias transformadas do original. Regra prática: se você não consegue apagar e regenerar, não é índice, é fonte disfarçada.
⚠️ O erro a evitar
Deixar a memória do agente viver só num banco vetorial proprietário. Trocou de modelo, o embedding antigo não serve mais. Trocou de ferramenta, o banco não abre. Sem a fonte em Markdown, o "cérebro" some junto com o modelo. É o oposto do que este curso ensina.
Conceitos-chave
Fonte é o que você edita; derivado é o que o build gera.
Apagar e regenerar sem perda. O teste definitivo.
Busca, vetores, cache. Sempre derivado.
Abre em qualquer lugar, com qualquer modelo.
🔐 Segredos e material bruto ficam fora
Dois tipos de conteúdo nunca entram no núcleo portátil: segredos (chaves de API, tokens, senhas) e estado bruto nativo (sessões JSONL, banco de memória do Claude, exports de chat inteiros). Os mega-prompts repetem isso em quase toda seção: "mantenha segredos e memória privada bruta fora de relatórios e repositórios", "preserve evidência bruta separadamente". O núcleo portátil é o que você publicaria; o resto fica no lugar dele, referenciado, nunca copiado.
✓ Entra no núcleo
- ✓A regra "keys ficam em
~/projetos/openpcbotv2/.env" (a referência). - ✓Fatos promovidos, decisões, tarefas, handoffs.
- ✓O nome do MCP registrado (magnific, metricool).
- ✓Um snapshot curado e datado de contexto.
✗ Fica fora
- ✗O valor da chave (nunca impresso, nunca copiado).
- ✗Os 2,3 GB de sessões JSONL do Claude.
- ✗A pasta
~/.claudeou~/.codexcopiada inteira. - ✗Material de terceiros sem licença (o
docs/do kit ficou fora do git por isso).
🧭 O caso do dsh-sandbox
A pasta ~/projetos desta máquina tem 269 arquivos de segredo. Por isso o dsh-sandbox amarra montagem e provedor: modo local monta os projetos mas só fala com o Ollama; modo remoto fala com a OpenRouter mas não vê os projetos. Juntar os dois exige digitar "CONFIRMO". É a regra deste tópico virando mecanismo: o segredo pode existir na máquina, mas o executor que fala com fora não pode enxergá-lo.
Novo aqui? "Evidência bruta" é o material original sem tratamento: a transcrição inteira, o log completo, o export do chat. Ela é valiosa pra auditar depois, mas não é pra ser lida em toda sessão. Fica arquivada, com um ponteiro no context/sources.md dizendo onde está e de quando é.
Conceitos-chave
O núcleo diz onde a chave está, nunca qual é.
Sessões e memória automática ficam onde nasceram.
Recorte aprovado, com fonte e data, em vez do bruto.
Se não pode ir pra um repo, não está no núcleo.
Auto-checagem (opcional): duas anotações se contradizem. A de agosto diz "porta 8000" com fonte; a de setembro diz "acho que é 8080" sem fonte. Qual vale?
🎯 Resumo do módulo
Próximo módulo:
1.6 — Audit antes de implement: analisar → planejar → simular