Como importar o histórico de desenvolvimento para uma memória local
pesquisável, validar os dados e organizar a 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 preparação do ambiente, validação prévia, importação
automatizada e conferência dos resultados.
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 observado 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:
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.
systemctl --user is-active ai-memory
systemctl --user status ai-memory --no-pager
Caso seja necessário reiniciá-lo:
systemctl --user restart ai-memory
Defina a URL correta para o CLI:
export AI_MEMORY_SERVER_URL=http://127.0.0.1:49375
Para persistir a configuração no Bash:
grep -qF 'export 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
Essa variável é importante porque o CLI utilizava por padrão a porta
49374, enquanto o servidor estava escutando na 49375.
Valide 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. Inventariando e validando as sessões
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.
Antes de importar, inventariei as sessões do banco original e executei
uma simulação para identificar quais ainda tinham diretórios de projeto
disponíveis.
3.1. Criar o script de validação
O script consulta o banco SQLite original do OpenCode, executa
ai-memory backfill em modo de simulação para cada sessão e registra o
resultado em ~/backups/opencode/session-validation.log.
mkdir -p ~/backups/opencode
cat > "$HOME/backups/opencode/validate-sessions.sh" <<'BASH'
#!/usr/bin/env bash
set -uo pipefail
DB="$HOME/.local/share/opencode/opencode.db"
REPORT="$HOME/backups/opencode/session-validation.log"
for cmd in sqlite3 jq ai-memory; do
if ! command -v "$cmd" >/dev/null 2>&1; then
echo "ERRO: comando obrigatório não encontrado: $cmd" >&2
exit 1
fi
done
if [[ ! -f "$DB" ]]; then
echo "ERRO: banco do OpenCode não encontrado: $DB" >&2
exit 1
fi
mkdir -p "$(dirname "$REPORT")"
: > "$REPORT"
total=0
ok=0
missing=0
failed=0
printf 'Validação de sessões do OpenCode\n'
printf 'Banco: %s\n' "$DB"
printf 'Relatório: %s\n\n' "$REPORT"
while IFS=$'\t' read -r id directory; do
[[ -n "$id" ]] || continue
((total += 1))
if [[ -z "$directory" || ! -d "$directory" ]]; then
printf 'MISSING\t%s\t%s\n' "$id" "$directory" | tee -a "$REPORT"
((missing += 1))
continue
fi
output="$(
cd "$directory" &&
ai-memory backfill \
--session "$id" \
--max-sessions 1 \
--dry-run \
--json 2>&1
)"
rc=$?
if [[ $rc -eq 0 ]] &&
jq -e '
.selected == 1 and
.failed_sessions == 0 and
.dry_run == true
' >/dev/null 2>&1 <<<"$output"; then
printf 'OK\t%s\t%s\n' "$id" "$directory" | tee -a "$REPORT"
((ok += 1))
else
printf 'FAIL\t%s\t%s\n' "$id" "$directory" | tee -a "$REPORT"
printf '%s\n' "$output" >> "$REPORT"
printf '%s\n' '---' >> "$REPORT"
((failed += 1))
fi
done < <(
sqlite3 -separator $'\t' "$DB" \
'SELECT id, directory
FROM session_v2
ORDER BY time_created, id;'
)
{
printf '\nResumo da validação\n'
printf 'Total: %d | OK: %d | MISSING: %d | Falhas: %d\n' \
"$total" "$ok" "$missing" "$failed"
} | tee -a "$REPORT"
printf '\nRelatório salvo em: %s\n' "$REPORT"
BASH
chmod +x "$HOME/backups/opencode/validate-sessions.sh"
3.2. Executar a validação
"$HOME/backups/opencode/validate-sessions.sh"
O script classifica cada sessão em três categorias:
OK: diretório disponível e simulação do AI Memory concluída com o
resultado esperado.
MISSING: diretório original da sessão não existe mais.
FAIL: erro durante a simulação ou resultado diferente do esperado.
A validação usa --dry-run, portanto não executa a importação efetiva
das sessões.
3.3. Consultar o relatório
cat ~/backups/opencode/session-validation.log
Para filtrar os registros e o resumo:
grep -E '^(OK|MISSING|FAIL)|^Total:' \
~/backups/opencode/session-validation.log
Na execução original, o inventário apresentou:
Total: 197 | OK: 177 | MISSING: 20 | Falhas: 0
As 177 sessões aprovadas foram consideradas aptas para a etapa seguinte.
As 20 classificadas como MISSING estavam associadas a diretórios de
projetos que não estavam mais disponíveis.
Importante: OK indica que a sessão passou pela simulação, não que
já foi importada. A importação efetiva deve ser executada
posteriormente, após revisar o relatório e confirmar os projetos de
origem.
O relatório foi usado como entrada para automatizar a importação sem
tentar processar as sessões excluídas.
4. Validando uma sessão antes de importar
Antes da gravação definitiva, executei o backfill em modo dry-run,
selecionando uma sessão por vez.
O exemplo abaixo usa um diretório e um identificador ilustrativos.
Substitua-os pelos valores reais da sua instalação:
cd "$HOME/Documentos/github/meu-projeto"
export AI_MEMORY_SERVER_URL=http://127.0.0.1:49375
ai-memory backfill \
--session ses_ID_DA_SESSAO \
--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.
Esse cuidado é importante porque a seleção depende do projeto atual. Na
minha execução, quando rodei o comando a partir de ~, o CLI
identificou o projeto como marcos e não selecionou a sessão desejada.
Executar a partir do diretório original evitou esse problema.
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_ID_DA_SESSAO \
--max-sessions 1 \
--json
O resultado da sessão de teste foi:
- Uma sessão importada.
- 542 eventos importados.
- Zero falhas.
Como o armazenamento deixou 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.
Use --force com cuidado, mantendo a seleção explícita da sessão e
conferindo os resultados para não 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 lê o relatório de validação, pula a sessão de
teste já importada e registra os resultados em um log.
Salve como ~/backups/opencode/import-restantes.sh:
cat > "$HOME/backups/opencode/import-restantes.sh" <<'BASH'
#!/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_ID_DA_SESSAO_DE_TESTE"
if [[ ! -f "$REPORT" ]]; then
echo "Relatório não encontrado: $REPORT" >&2
exit 1
fi
: > "$LOG"
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
BASH
chmod +x "$HOME/backups/opencode/import-restantes.sh"
Antes de executar: substitua ses_ID_DA_SESSAO_DE_TESTE pelo ID
real da sessão importada no teste. Confira também se o relatório contém
apenas registros de validação no formato esperado e se os diretórios
continuam disponíveis.
Execute:
"$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. Se uma
sessão falhar, registra a ocorrência e continua com as seguintes.
Na execução realizada, o script importou 176 sessões sem falhas, além da
sessão de teste importada anteriormente. O resultado total foi de 177
sessões.
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:
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 soluções
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.\
O comando estava sendo executado fora do diretório original do projeto.
A solução foi entrar no diretório correto antes de executar a
importação.
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 do AI Memory para a versão 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. Não houve
falhas de importação na execução registrada.
O ponto principal 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 passou 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.
DevEx