🗃️ Projeto 3: memória curada
O agente propõe, você aprova. Neste projeto você para de tratar a memória bruta do Claude como fonte de verdade e monta uma camada de fatos aprovados que Claude, Codex e qualquer outro executor leem do mesmo lugar — reaproveitando o vault que o openpcbotv3 já opera nesta máquina.
🎯 O projeto em uma tela
Ter UM lugar de fatos verificados sobre você e seus projetos, aprovado por você, lido por todos os executores.
3 fatos promovidos da memória do Claude pro context/overview.md de um projeto, com fonte e data; AGENTS.md e CLAUDE.md mandando ler o USER.md do vault.
Sessão nova no Claude E no Codex cita um fato pessoal apontando o USER.md como fonte. Nada da memória bruta foi copiado em massa.
🧱 A memória do Claude é matéria-prima, não fonte
O diagnóstico desta máquina encontrou 227 pastas de memória e 869 arquivos em ~/.claude/projects/*/memory. Cada arquivo é uma observação que o Claude achou útil guardar: uma preferência, um caminho, um fato de projeto. Nada disso passou por aprovação sua. Boa parte está desatualizada, duplicada ou contradiz outro arquivo escrito semanas depois. E só o Claude lê essa pasta.
Por isso o plano trata essa memória como matéria-prima: uma mina de fatos candidatos, não a verdade. A verdade é o que você aprovou, com fonte e data, num arquivo que qualquer runtime consegue abrir.
✗ Copiar a memória em massa
- ✗869 arquivos viram 869 arquivos em outro lugar, com as mesmas contradições.
- ✗O Codex passa a acreditar em fatos que o Claude gravou errado em maio.
- ✗Nenhuma fonte, nenhuma data: impossível saber qual versão vale.
- ✗Segredos e caminhos privados podem ir junto.
✓ Promover fato a fato
- ✓Você lê a memória do projeto que está tocando e escolhe o que ainda é verdade.
- ✓Cada fato promovido ganha fonte, data e escopo.
- ✓O resto fica onde está, como histórico.
- ✓O resultado cabe numa tela e qualquer modelo lê.
Novo aqui? "Memória" do Claude Code é uma pasta de arquivos Markdown que o próprio agente escreve entre sessões para se lembrar de coisas. "Promover" um fato é copiá-lo, revisado, para um arquivo que você controla. A diferença entre os dois é uma só: aprovação humana.
Conceitos-chave
Observações não aprovadas, candidatas a fato.
O que você aprovou, com origem e data.
Levar um fato da memória bruta pro overview, revisado.
O erro a evitar: transporta ruído e contradição.
🗄️ O vault do openpcbotv3 como overview global
Você não precisa inventar a camada de fatos aprovados: ela já existe nesta máquina. O bot openpcbotv3 mantém um vault curado em ~/vault/MEMORY.md e ~/vault/USER.md. O bot propõe entradas; nada é escrito sem você aprovar com /memoria aprovar <id>. E o USER.md entra no prompt de toda conversa do bot. É exatamente o "overview global" que o plano pede.
Leia de baixo pra cima: cada degrau filtra o anterior. Só o último degrau, aprovado por você, é lido pelos executores. A memória bruta nunca sobe direto.
📊 O que o v3 já faz (do README, seção Cérebro)
- •Toda mensagem sua vira memória classificada em semantic (durável: "prefiro", "sempre", "moro em") ou episodic. Pergunta nunca vira fato.
- •Busca por palavra-chave (FTS5) mais vetor
bge-m3; contexto no prompt limitado a 600 tokens. - •Vault curado: o bot propõe, você aprova.
USER.mdentra em todo prompt. - •Consolidação noturna às 4h, no Ollama, custo zero: funde duplicatas e marca contradições.
💡 Por que reaproveitar em vez de criar
O plano de migração diz: não reinventar. O vault já tem o mecanismo de aprovação, já roda como serviço e já é lido por um executor (o bot). Falta só apontar Claude, Codex e dsh pro mesmo arquivo. Criar um segundo "overview global" seria criar a segunda fonte de verdade que o curso inteiro tenta evitar.
Conceitos-chave
MEMORY.md + USER.md, só entra o que foi aprovado.
Fatos sobre você; entra em todo prompt do bot.
Durável vs "aconteceu uma vez".
O arquivo de fatos pessoais que todo executor lê.
✅ Fluxo propõe → aprova, aplicado a um projeto
Agora a mão na massa. Escolha um projeto que você já migrou (Projeto 1) e promova 3 fatos da memória bruta do Claude pro context/overview.md dele. Três, não trinta: o objetivo é treinar o gesto, não esvaziar a pasta.
Listar a memória bruta do projeto
Objetivo: ver o que o Claude guardou sobre este projeto, com data. Troque o caminho pelo seu.
MEM=~/.claude/projects/-home-nmaldaner-projetos-<meu-projeto>/memory
ls -lt "$MEM" | head -20
# ler só o índice, que resume cada arquivo em uma linha
cat "$MEM/MEMORY.md"Como verificar: o índice lista os arquivos com um gancho por linha. Se estiver vazio, este projeto não tem memória e você pula pro passo 3 com fatos do próprio CLAUDE.md.
Pedir ao agente que PROPONHA, sem escrever
Objetivo: o agente lê a memória e devolve candidatos classificados. Cole no Claude Code ou no Codex, dentro do projeto.
Leia os arquivos em <caminho do memory/ acima>. Não edite nada.
Devolva uma tabela com no máximo 8 candidatos a fato durável sobre este projeto.
Colunas: fato (uma frase), tipo (fato | preferência | hipótese | decisão),
arquivo de origem, data do arquivo, e "ainda parece válido?" (sim / não / não sei).
Descarte perguntas, tarefas passadas e qualquer segredo ou chave.Como verificar: a tabela cita o arquivo de origem em cada linha. Sem origem, a linha não vale.
Aprovar 3 e gravar no overview com fonte e data
Objetivo: você escolhe; o agente escreve só o que você aprovou, no formato do template.
Aprovo os candidatos 2, 5 e 7. Acrescente-os em context/overview.md,
na seção "Fatos verificados", um por linha, no formato:
- <fato> (fonte: memory/<arquivo>, observado em <AAAA-MM-DD>, promovido em 2026-09-14)
Os demais candidatos NÃO entram. Não altere mais nada no arquivo.Como verificar: git diff context/overview.md mostra exatamente 3 linhas novas, todas com fonte e duas datas.
💡 A mesma coisa no bot
No openpcbotv3 o gesto é idêntico, só que pelo Telegram: o bot manda uma proposta com id, você responde /memoria aprovar <id>, e só então a linha entra em ~/vault/MEMORY.md ou USER.md. O que você acabou de fazer à mão no projeto é a versão manual do mesmo protocolo.
Conceitos-chave
Candidato com origem, tipo e data; ainda não vale.
Você nomeia quais entram; o resto não entra.
Quando foi observado e quando foi promovido.
Três linhas. Se o diff é grande, algo saiu do protocolo.
🕰️ Consolidação com superseded_by: nunca apaga, esconde
O que acontece quando um fato aprovado deixa de ser verdade? O v3 responde com a consolidação noturna: quando detecta duas memórias que se contradizem, a mais antiga recebe o campo superseded_by apontando pra nova. Ela não é apagada, só deixa de entrar no prompt. Você pode voltar e ver o que se acreditava antes.
O fato antigo continua existindo, mas tracejado e fora do prompt. O executor só vê o fato atual. Se a decisão nova estava errada, você desfaz sem perder nada.
✓ Como resolver conflito
- ✓Origem e decisão aceita vencem. Timestamp desempata só entre iguais.
- ✓A versão vencida ganha
superseded_bye sai do prompt. - ✓Backup antes de cada rodada de consolidação.
✗ O que quebra a memória
- ✗"O mais novo sempre vence": um arquivo escrito por engano apaga uma decisão sua.
- ✗Deletar a versão antiga: some a trilha de por que você mudou.
- ✗Manter os dois ativos: o executor escolhe um ao acaso.
No overview em Markdown, sem banco: use a mesma ideia à mão. Em vez de apagar a linha antiga, mova-a pra uma seção "Superado" no fim do arquivo com a nota superado por: <linha nova>, em <data>. O agente lê só "Fatos verificados"; o histórico fica pra você.
Conceitos-chave
Ponteiro do fato vencido pro fato que o substituiu.
Sai do prompt, fica no histórico.
De onde veio e quem decidiu; vence data.
Rodada periódica que funde e marca; sempre com backup.
🔗 Claude, Codex e dsh lendo o mesmo USER.md
O bot já injeta o USER.md em todo prompt porque o código dele faz isso. Claude Code e Codex não têm esse código, e nenhum arquivo é carregado sozinho além do CLAUDE.md e do AGENTS.md. A solução é a mesma do curso inteiro: uma instrução explícita de leitura nesses dois arquivos.
Acrescentar a instrução no AGENTS.md global e do projeto
Objetivo: todo executor que lê AGENTS.md aprende onde estão os fatos pessoais aprovados. O CLAUDE.md herda via @AGENTS.md.
cat >> ~/.codex/AGENTS.md <<'EOF'
## Fatos pessoais aprovados
- Antes de assumir qualquer preferência minha (voz, modelo de imagem, conta git, caminhos),
leia `~/vault/USER.md`. É a única fonte aprovada. Cite o arquivo quando usar um fato dele.
- Não proponha gravar nada lá por conta própria: proponha em texto e eu aprovo.
EOF
# o CLAUDE.md global começa com "@AGENTS.md"? Se não, acrescente essa linha no topo dele.
head -1 ~/.claude/CLAUDE.mdComo verificar: grep -n USER.md ~/.codex/AGENTS.md devolve a linha; head -1 ~/.claude/CLAUDE.md devolve @AGENTS.md.
Provar nos dois runtimes
Objetivo: sessão nova cita o USER.md como fonte de um fato pessoal. Sem citar a fonte, não passou.
P='Qual é a voz padrão de narração que eu uso? Responda em uma frase e diga em que arquivo você leu isso. Não edite nada.'
claude -p "$P"
codex exec --skip-git-repo-check "$P"Como verificar: as duas respostas nomeiam ~/vault/USER.md. Se uma citar a memória do Claude ou "não sei", a instrução não chegou; confira se o AGENTS.md certo está sendo lido.
🐳 E o dsh?
O dsh-sandbox não lê ~/vault porque o container só enxerga o que foi montado. No modo local, ~/projetos está montado; o vault não. Duas saídas: montar ~/vault somente leitura no docker-compose.projetos.yml, ou copiar o USER.md aprovado pro projeto como context/user.md com a data do snapshot. O Projeto 4 trata o dsh em detalhe.
Conceitos-chave
O jeito de "injetar" sem código: mandar ler.
Bot, Claude, Codex e dsh apontam pro mesmo arquivo.
O critério de aceite: resposta certa sem fonte não vale.
Quando não dá pra ler ao vivo, copia com data e regra de refresh.
📦 Arquivar sessões antigas, só depois que o ciclo roda
Nesta máquina há 6.859 sessões JSONL do Claude (2,3 GB) e 209 do Codex. Elas são o histórico bruto de cada conversa. Enquanto seu contexto vivia só lá, apagar era perder memória. Depois que handoff e prime (módulo 2.6) estão rodando, o que importa de cada sessão já foi pra handoffs/latest.md e pro overview. Aí, e só aí, arquivar vira uma faxina segura.
Semana 1: ciclo rodando
Toda sessão termina com handoff. Nova sessão começa pelo prime. Nenhuma sessão é apagada ainda.
Semana 2: promoção de fatos
Nos projetos tocados, 3 a 5 fatos promovidos pro overview (tópico 3). O que era memória bruta relevante já está aprovado.
Semana 3: arquivar, não apagar
Sessões com mais de 90 dias vão pra um arquivo compactado fora de ~/.claude. Se algo faltar, está lá.
Depois: rotina mensal
Um comando por mês. O disco (88% cheio hoje) agradece.
Passo 6: arquivar sessões com mais de 90 dias (reversível)
Objetivo: tirar do caminho sem perder. Primeiro conta e lista; só o segundo bloco move.
# 1) só olhar: quantas e quanto pesam
find ~/.claude/projects -name '*.jsonl' -mtime +90 | wc -l
find ~/.claude/projects -name '*.jsonl' -mtime +90 -print0 | du -ch --files0-from=- | tail -1
# 2) arquivar (move pra um tar.gz datado fora de ~/.claude; nada é apagado)
ARQ=~/projetos/output/arquivo-sessoes-claude-$(date +%Y-%m-%d).tar.gz
find ~/.claude/projects -name '*.jsonl' -mtime +90 -print0 \
| tar --null -T - -czf "$ARQ" --remove-files
ls -lh "$ARQ"Como verificar: o primeiro find rodado de novo devolve 0; o tar.gz existe e abre com tar -tzf "$ARQ" | head. Rollback: tar -xzf "$ARQ" -C /.
⚠️ Riscos e rollback do projeto
- •Promover fato errado: o diff é de 3 linhas;
git checkout context/overview.mddesfaz. - •Arquivar cedo demais: não arquive antes de ter pelo menos duas semanas de handoffs. O tar.gz é reversível, mas o hábito de ir buscar lá não.
- •Duas fontes de fatos pessoais: se você criar um
context/user.mdglobal além do vault, escolha um e aponte o outro pra ele. - •Segredo no overview: chaves ficam em
.env; o overview cita o caminho, nunca o valor.
Conceitos-chave
Compacta e tira do caminho; volta com um comando.
Handoff/prime rodando antes de qualquer faxina.
Bruto, útil pra auditoria; não é fonte de contexto.
Uma vez por mês, o mesmo comando.
Auto-checagem (opcional): o Claude gravou em maio que "o modelo de imagem padrão é flux2-dev" e em agosto que "é flux2-klein". O que fazer no overview?
🎯 Resumo do projeto
Próximo projeto:
3.4 — Projeto 4: terceiro executor (dsh-sandbox e modelo local)