Migrando 177 sessões do OpenCode para o AI Memory: passo a passo com comandos

Migrando 177 sessões do OpenCode para o AI Memory: passo a passo com comandos

●1 ●4 ●25
calendar_today • schedule5 min read

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.

CodeLegion #OpenCode #AIMemory #IA #DevTools #LLM #EngenhariaDeSoftware

DevEx

Part 3 of 3 in Ai-Memory
🔥 Join developers growing publicly
Share your knowledge, build in public, and grow your developer presence with a global community.

More Posts

Do histórico perdido ao contexto reutilizável: migrando sessões do OpenCode para o AI Memory

Marcos Vilela - Oct 13

AI Memory no Debian: como integrar memória persistente ao OpenCode com mise, MCP e systemd

Marcos Vilela - Oct 13

Frameworks Are Institutional Memory

Ken W. Algerverified - Sep 17

Minha Experiência com o uso do SpecKit no desenvolvimento em Infra/Cloud

Marcos Vilela - Jul 2

AI Reliability Gap: Why Large Language Models are not for Safety-Critical Systems

praneeth - Mar 31
chevron_left
411 Points • 30 Badges
Montes Claros/MG • github.com/marcosvile
11Posts
5Comments
11Connections
Sou graduado em Análise e Desenvolvimento de Sistemas, com experiência em Linux, Docker, redes e amb... Show more

Related Jobs

View all jobs →

Commenters (This Week)

2 comments
2 comments
1 comment

Contribute meaningful comments to climb the leaderboard and earn badges!