Como importar o histórico de desenvolvimento para uma memória local pesquisável, validar os dados e organizar o processo de migração no Debian.
O histórico de uma ferramenta de desenvolvimento com IA pode acumular meses de decisões técnicas, diagnósticos, comandos e soluções. O desafio é tornar esse conhecimento reutilizável em novas sessões, sem depender de buscas manuais em conversas antigas.
Neste artigo, compartilho o processo que utilizei para migrar sessões do OpenCode para o AI Memory, incluindo os comandos, as validações e os resultados obtidos.
1. Preparando o ambiente
O ambiente utilizado foi Debian Linux, com OpenCode 2.0.28 e AI Memory 2.6.5 durante a importação inicial. Posteriormente, atualizei o AI Memory para a versão 2.6.6 para corrigir um problema no comando list-projects.
O banco de dados original do OpenCode estava em:
~/.local/share/opencode/opencode.db
Antes de iniciar, preservei o histórico original e mantive backups em ~/backups/opencode/.
Para conferir os arquivos de backup:
ls -lh ~/backups/opencode/
Importante: não remova nem sobrescreva o banco original do OpenCode. A importação deve ocorrer para o armazenamento do AI Memory, mantendo uma cópia de segurança do histórico de origem.
2. Iniciando e validando o servidor
O AI Memory estava configurado para executar como serviço do usuário, na porta 49375.
Verifiquei o serviço:
systemctl --user is-active ai-memory
systemctl --user status ai-memory --no-pager
Caso seja necessário reiniciá-lo:
systemctl --user restart ai-memory
Em seguida, defini a URL correta para o CLI:
export AI_MEMORY_SERVER_URL=http://127.0.0.1:49375
Para persistir essa configuração no Bash:
grep -q 'AI_MEMORY_SERVER_URL=http://127.0.0.1:49375' ~/.bashrc || \
echo 'export AI_MEMORY_SERVER_URL=http://127.0.0.1:49375' >> ~/.bashrc
source ~/.bashrc
A variável é importante porque o CLI utilizava por padrão a porta 49374, enquanto o servidor estava escutando na 49375.
Validei a conexão:
ai-memory status
Esse comando apresenta informações sobre o armazenamento, as sessões, as observações, a indexação textual e os embeddings.
3. Identificando as sessões que poderiam ser migradas
O histórico estava distribuído entre vários projetos. Como o backfill depende do diretório de trabalho para identificar o projeto e selecionar sessões, não bastava executar a importação a partir de qualquer pasta.
Primeiro, inventariei as sessões no banco original e gerei um relatório de validação chamado:
~/backups/opencode/session-validation.log
O relatório continha entradas com o status OK para sessões validadas e MISSING para sessões cujos diretórios originais não estavam disponíveis.
O inventário identificou 197 sessões. Dessas, 177 estavam associadas a diretórios disponíveis e passaram pela validação. Outras 20 pertenciam a projetos legados ou diretórios removidos e foram deixadas de fora deliberadamente.
O relatório foi usado como fonte para automatizar a importação sem tentar processar as sessões excluídas.
4. Validando antes de importar
Antes da gravação definitiva, executei o backfill em modo dry-run, selecionando uma sessão por vez.
Exemplo:
cd "$HOME/Documentos/github/meu-projeto"
export AI_MEMORY_SERVER_URL=http://127.0.0.1:49375
ai-memory backfill \
--session ses_047652742ffeDkF5OI6oK3Ewpd \
--max-sessions 1 \
--dry-run \
--json
O parâmetro --session restringe a execução a uma sessão específica. --max-sessions 1 limita o processamento a uma sessão por chamada, enquanto --dry-run permite verificar a seleção sem efetivar a importação.
A validação confirmou que a sessão era elegível e que o comando não registrava falhas.
Esse cuidado foi importante porque a seleção dependia do projeto atual. Quando executei o comando a partir de ~, o CLI identificou o projeto como marcos e não selecionou a sessão desejada.
5. Testando uma importação real
Depois de validar a seleção, importei uma sessão de teste:
cd "$HOME/Documentos/github/meu-projeto"
AI_MEMORY_SERVER_URL=http://127.0.0.1:49375 \
ai-memory backfill \
--session ses_047652742ffeDkF5OI6oK3Ewpd \
--max-sessions 1 \
--json
O resultado confirmou:
- Uma sessão importada.
- 542 eventos importados.
- Zero falhas.
Como o armazenamento deixa de estar vazio após a primeira importação, utilizei --force nas chamadas seguintes. Esse parâmetro permite executar o backfill mesmo quando já existem sessões no armazenamento.
O uso de --force deve ser combinado com a seleção explícita da sessão e a validação dos resultados, para evitar processar mais histórico do que o pretendido.
6. Automatizando as 176 sessões restantes
Com o teste concluído, automatizei a importação das demais sessões elegíveis. O script abaixo utiliza o relatório de validação criado anteriormente, pula a primeira sessão já importada e registra os resultados em um log.
Salve como ~/backups/opencode/import-restantes.sh:
cat > "$HOME/backups/opencode/import-restantes.sh" <<'EOF'
#!/usr/bin/env bash
set -uo pipefail
REPORT="$HOME/backups/opencode/session-validation.log"
LOG="$HOME/backups/opencode/import-restantes.log"
export AI_MEMORY_SERVER_URL="http://127.0.0.1:49375"
JA_IMPORTADA="ses_047652742ffeDkF5OI6oK3Ewpd"
if [[ ! -f "$REPORT" ]]; then
echo "Relatório não encontrado: $REPORT"
exit 1
fi
total=0
sucesso=0
falha=0
ignorada=0
while IFS=$'\t' read -r status id dir; do
[[ "$status" == "OK" ]] || continue
[[ -n "$id" && -n "$dir" ]] || continue
if [[ "$id" == "$JA_IMPORTADA" ]]; then
ignorada=$((ignorada + 1))
continue
fi
if [[ ! -d "$dir" ]]; then
echo "ERRO: diretório ausente: $id — $dir" | tee -a "$LOG"
falha=$((falha + 1))
continue
fi
total=$((total + 1))
echo "[$total] Importando $id — $dir" | tee -a "$LOG"
if (
cd "$dir" &&
ai-memory backfill \
--session "$id" \
--max-sessions 1 \
--force \
--json
) >> "$LOG" 2>&1; then
sucesso=$((sucesso + 1))
echo "OK: $id" | tee -a "$LOG"
else
falha=$((falha + 1))
echo "FALHA: $id — verificar $LOG" | tee -a "$LOG"
fi
done < "$REPORT"
echo
echo "Importação concluída."
echo "Processadas: $total | Sucesso: $sucesso | Falhas: $falha | Já importada: $ignorada"
echo "Log: $LOG"
ai-memory status
EOF
chmod +x "$HOME/backups/opencode/import-restantes.sh"
Para executar:
"$HOME/backups/opencode/import-restantes.sh"
O script percorre somente as entradas OK, muda para o diretório original de cada sessão e executa uma importação por chamada. As sessões ausentes são registradas como falhas, e o processamento continua para as seguintes.
O resultado foi de 176 sessões importadas pelo script, sem falhas, além da sessão de teste já importada.
7. Conferindo os resultados
Ao final, executei:
AI_MEMORY_SERVER_URL=http://127.0.0.1:49375 ai-memory status
O armazenamento apresentou os seguintes indicadores:
| Indicador | Resultado |
|---|
| Sessões importadas | 177 |
| Falhas de importação | 0 |
| Observações armazenadas | 16.610 |
| Páginas, incluindo versões anteriores | 189 |
| Embeddings | 189 |
| Páginas mais recentes sem embedding | 0 |
| Eventos pendentes no spool | 0 |
| Espaço utilizado | 26,8 MiB |
A busca textual estava indexada para todas as 189 versões de páginas e para as 16.610 observações. O modelo local all-MiniLM-L6-v2, com vetores de 384 dimensões, estava operacional.
Para consultar os projetos disponíveis, utilizei:
ai-memory list-projects
Inicialmente, esse comando retornou 404 Not Found com a versão 2.6.5. Após atualizar o CLI para a versão 2.6.6, o comando passou a listar corretamente os projetos.
8. Problemas encontrados e como foram resolvidos
O CLI tentava acessar a porta errada.
A variável AI_MEMORY_SERVER_URL não estava definida no ambiente. A solução foi exportar a URL do servidor na porta 49375 e persistir a configuração no ~/.bashrc.
O backfill não encontrava a sessão.
A execução ocorria fora do diretório original do projeto. A solução foi entrar no diretório correto antes de executar o comando.
O armazenamento já não estava vazio.
Após a importação inicial, as chamadas seguintes precisaram de --force para executar o backfill. Para limitar o escopo, mantive --session e --max-sessions 1.
O comando list-projects retornava 404.
A atualização para o AI Memory 2.6.6 resolveu o problema observado, sem necessidade de reimportar as sessões.
Conclusão
O processo transformou 177 sessões do OpenCode em uma base local pesquisável, com 16.610 observações e embeddings gerados sem falhas de importação.
O ponto mais importante não foi apenas executar o backfill, mas validar as sessões, preservar o histórico original, respeitar o contexto dos projetos e registrar os resultados de cada etapa.
O AI Memory passa a oferecer uma base para recuperar decisões e investigações anteriores. A próxima etapa é validar essa recuperação em situações reais de desenvolvimento e manter a integração funcionando continuamente.
