Coder Legion - Recent posts tagged opencode

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

Tue, 13 Oct 2026 20:07:36 +0000

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

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

Tue, 13 Oct 2026 19:55:11 +0000

Como migrei 177 sessões de desenvolvimento para uma memória local pesquisável, preservando o histórico original e preparando o ambiente para reutilizar conhecimento entre sessões de IA.

O problema: cada sessão termina, mas o conhecimento precisa continuar

Ferramentas de desenvolvimento com IA aceleram tarefas como investigação de incidentes, alterações de infraestrutura, depuração e implementação de funcionalidades. Porém, existe um problema recorrente: boa parte do contexto fica distribuída em sessões anteriores.

Uma investigação pode envolver dezenas de mensagens, comandos executados, decisões de arquitetura, erros encontrados e soluções validadas. Ao iniciar uma nova sessão, recuperar esse contexto manualmente consome tempo e nem sempre é possível lembrar onde uma decisão foi tomada.

O objetivo da migração foi transformar o histórico de sessões do OpenCode em uma base local de memória que permita recuperar informações de trabalhos anteriores sem depender exclusivamente da busca manual nas conversas.

A solução: AI Memory

O AI Memory é um projeto voltado à persistência e recuperação de contexto para fluxos de trabalho com IA. Nesta implementação, utilizei a versão 2.6.5, com armazenamento local, indexação textual e embeddings gerados por um modelo local.

A migração foi realizada em etapas:

Identificação do banco de dados original do OpenCode.
Backup do histórico antes de qualquer operação.
Inventário das sessões e identificação dos diretórios de projeto associados.
Validação das sessões que ainda correspondiam a diretórios disponíveis.
Importação individual das sessões para o AI Memory.
Verificação da indexação, dos embeddings e do estado do armazenamento.

A decisão de importar cada sessão a partir de seu diretório original foi importante: o processo de backfill utiliza o contexto do projeto atual para identificar as sessões elegíveis.

Preservação e validação do histórico

O banco original do OpenCode foi mantido intacto. O trabalho foi feito a partir de uma cópia de segurança e de comandos de importação direcionados a cada sessão.

Durante o inventário, foram identificadas 197 sessões. Desse total, 177 passaram pela validação e foram selecionadas para importação. As outras 20 estavam associadas a diretórios antigos, removidos ou não disponíveis. Como pertenciam a projetos legados que não precisavam fazer parte desta migração, ficaram fora do escopo.

Antes da importação definitiva, as sessões elegíveis foram submetidas a uma execução de validação em modo dry-run. Isso permitiu confirmar a seleção sem gravar os dados no armazenamento definitivo.

A importação foi então automatizada com processamento individual, registro dos resultados em log e tratamento de falhas por sessão.

Resultado da migração

Ao final do processo, o AI Memory apresentou os seguintes indicadores:

Indicador	Resultado
Sessões importadas	177
Falhas na importação	0
Observações armazenadas	16.610
Versões de páginas indexadas	189
Embeddings gerados	189
Páginas mais recentes sem embedding	0
Eventos pendentes no spool	0
Espaço utilizado	26,8 MiB

A busca textual (FTS) 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 embeddings de 384 dimensões, também estava operacional.

Esses números confirmam que o histórico validado foi importado e indexado. A etapa seguinte é testar a recuperação de informações de sessões específicas e validar o uso da memória durante novos trabalhos.

Por que manter a memória local?

Para este fluxo, manter os dados localmente oferece algumas vantagens práticas:

Controle dos dados: o armazenamento permanece na máquina, sem exigir que o histórico seja enviado a um serviço externo de memória.
Busca contextual: informações de sessões anteriores podem ser recuperadas sem depender apenas da memória da conversa atual.
Baixo consumo de armazenamento: a base importada ocupou aproximadamente 26,8 MiB.
Independência do modelo de linguagem: a indexação vetorial utiliza um modelo local, embora a geração de respostas por um LLM não esteja habilitada nesta configuração.
Rastreabilidade: o processo foi executado com logs, validação prévia e contagem de sessões importadas.

Memória local não elimina a necessidade de segurança. Bancos de conversas podem conter comandos, caminhos, informações de infraestrutura e outros dados sensíveis. Por isso, backups, permissões de arquivos e políticas de retenção continuam importantes.

O que ainda precisa ser validado?

A importação é apenas uma parte da solução. Para considerar o fluxo pronto para uso contínuo, ainda é necessário:

Testar buscas com assuntos conhecidos, comparando os resultados com as sessões originais.
Verificar a resolução de um link de memória que permaneceu pendente.
Avaliar os eventos descartados pela política de captura.
Confirmar que o serviço inicia automaticamente após reinicializações.
Validar a integração de captura e recuperação com novas sessões do OpenCode.

Esses testes distinguem uma base importada e indexada de um sistema de memória efetivamente integrado ao fluxo diário de desenvolvimento.

Conclusão

A migração transformou um histórico de conversas de desenvolvimento em uma base local com 177 sessões importadas, 16.610 observações armazenadas e indexação textual e vetorial operacional.

O ganho esperado não está apenas em guardar conversas antigas, mas em reduzir o esforço necessário para recuperar decisões, diagnósticos e soluções de trabalhos anteriores. O próximo passo é validar essa recuperação na prática e integrar o AI Memory ao fluxo contínuo de desenvolvimento assistido por IA.

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

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

Tue, 13 Oct 2026 19:09:39 +0000

Quem utiliza agentes de IA para desenvolver software já percebeu um problema recorrente: a cada nova sessão, parte do contexto se perde. Decisões de arquitetura, particularidades do projeto, comandos utilizados e soluções de problemas anteriores nem sempre estão disponíveis para a próxima conversa.

Uma alternativa é o AI Memory, projeto open source de Akita que oferece memória persistente para agentes de IA.

Neste artigo, vamos configurar o AI Memory no Debian e integrá-lo ao OpenCode 2, utilizando mise para gerenciar a instalação, MCP para comunicação entre os componentes e systemd para manter o serviço ativo.

1. Instalando o mise no Debian

O mise é um gerenciador de ferramentas e versões que permite instalar e controlar executáveis sem depender exclusivamente dos pacotes da distribuição.

Instale-o utilizando um dos métodos disponíveis na documentação oficial: https://mise.jdx.dev/installing-mise.html

Caso o pacote esteja disponível nos repositórios configurados:

sudo apt update
sudo apt install mise

Depois, configure a integração com o Bash:

echo 'eval "$(mise activate bash)"' >> ~/.bashrc
source ~/.bashrc

Verifique se a instalação está funcionando:

mise --version
mise doctor

2. Instalando o AI Memory

Com o mise configurado, instale o AI Memory diretamente do GitHub:

mise use -g github:akitaonrails/ai-memory@2.6.5

Inicialize a ferramenta:

ai-memory init

Confirme a versão e o caminho do executável:

ai-memory --version
mise which ai-memory

No meu ambiente, o executável ficou disponível em:

~/.local/share/mise/installs/github-akitaonrails-ai-memory/latest/ai-memory

A vantagem dessa abordagem é manter a instalação gerenciada pelo mise, facilitando o controle de versões e futuras atualizações.

Repositório: https://github.com/akitaonrails/ai-memory

3. Executando o servidor MCP

O AI Memory pode disponibilizar suas ferramentas por meio de um servidor HTTP compatível com MCP (Model Context Protocol).

Para testar o serviço manualmente:

ai-memory serve \
  --transport http \
  --bind 127.0.0.1:49375

Utilizei a porta 49375 porque a 49374 já estava ocupada pelo serviço do OpenCode no meu ambiente.

Em outro terminal, confira a porta:

ss -lntp | grep 49375

E teste o endpoint:

curl -i http://127.0.0.1:49375/mcp

Uma observação importante: uma resposta HTTP isolada não garante que o protocolo MCP esteja funcionando corretamente. Verifique se a porta pertence ao processo ai-memory e, posteriormente, valide a conexão pelo cliente MCP.

4. Mantendo o AI Memory ativo com systemd

Executar o servidor manualmente funciona para testes, mas não é uma solução adequada para uso contínuo. Se o terminal for fechado, o processo pode ser encerrado.

Para resolver isso, vamos criar um serviço systemd de usuário.

Crie o diretório:

mkdir -p ~/.config/systemd/user

Crie o arquivo ~/.config/systemd/user/ai-memory.service:

[Unit]
Description=AI Memory MCP Server
After=default.target

[Service]
Type=simple
ExecStart=/home/marcos/.local/share/mise/installs/github-akitaonrails-ai-memory/latest/ai-memory serve --transport http --bind 127.0.0.1:49375
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

O caminho em ExecStart deve corresponder ao resultado de mise which ai-memory. Isso evita depender das variáveis de ambiente do Bash, que podem não estar disponíveis nos serviços systemd.

Agora, carregue e habilite o serviço:

systemctl --user daemon-reload
systemctl --user enable --now ai-memory.service

Para permitir que os serviços do usuário iniciem no boot mesmo sem uma sessão interativa aberta:

sudo loginctl enable-linger "$USER"

Confira o estado:

systemctl --user status ai-memory.service

E consulte os logs:

journalctl --user -u ai-memory.service -n 50 --no-pager

Com isso, o systemd passa a gerenciar o processo e tenta reiniciá-lo quando ocorre uma falha. Aqui incluímos um ponto importante que sempre terá um serviço em execução no seu SO, no entanto, uma vez que gerenciamos via serviço, podemos fazer 'enable' e 'disable' quando necessário, por isso o caminho de gerenciar via serviço é um bom caminho a não ter de ficar iniciando o serviço manualmente.

5. Integrando o AI Memory ao OpenCode 2

Com o servidor ativo, precisamos registrar o endpoint MCP no OpenCode.

No meu ambiente, utilizei:

OpenCode v2.0.28
AI Memory 2.6.5
Endpoint local http://127.0.0.1:49375/mcp

Como a estrutura de configuração varia entre versões do OpenCode, utilizei o instalador específico para a versão 2:

ai-memory install-mcp \
  --client opencode2 \
  --server-url http://127.0.0.1:49375/mcp \
  --apply

O instalador informa qual arquivo foi atualizado. No meu ambiente, a configuração fica em:

~/.config/opencode/opencode.json

É importante preservar os outros servidores MCP já configurados e evitar cadastrar o mesmo servidor duas vezes.

6. Configurando os hooks

Disponibilizar ferramentas MCP não significa necessariamente que o agente salvará e recuperará informações automaticamente em todas as sessões.

Para investigar a integração de ciclo de vida, consulte as opções suportadas pela versão instalada:

ai-memory install-hooks --help

Se a versão instalada oferecer suporte ao OpenCode 2, utilize os argumentos documentados pelo próprio comando para instalar os hooks. Não presuma que os parâmetros ou o formato de plugins de versões anteriores sejam compatíveis.

O objetivo é aproximar duas funcionalidades diferentes: disponibilizar memória para consulta e permitir que o agente utilize essa memória durante o fluxo de trabalho.

7. Diagnóstico de problemas

Durante a configuração, encontrei um conflito importante: a porta 49374 pertencia ao processo opencode serve --service, e não ao AI Memory.

O comando abaixo ajudou a identificar o responsável pela porta:

ss -lntp | grep -E '49374|49375'

Também é útil conferir os processos:

ps aux | grep -E '[a]i-memory|[o]pencode'

Se o serviço systemd falhar, consulte:

systemctl --user status ai-memory.service --no-pager -l
journalctl --user -u ai-memory.service -n 50 --no-pager

Um erro ExecMainStatus=203 indica que o systemd não conseguiu executar o processo. Nesse caso, confira o caminho configurado em ExecStart e compare-o com:

mise which ai-memory

Por fim, valide que o endpoint não está retornando a interface web do OpenCode:

curl -i http://127.0.0.1:49375/mcp

8. Comandos úteis para o dia a dia

# Iniciar
systemctl --user start ai-memory

# Reiniciar
systemctl --user restart ai-memory

# Parar
systemctl --user stop ai-memory

# Consultar o status
systemctl --user status ai-memory

# Acompanhar os logs
journalctl --user -u ai-memory -f

# Verificar a porta
ss -lntp | grep 49375

Conclusão

Integrar o AI Memory ao OpenCode envolve mais do que cadastrar um endpoint MCP. É necessário gerenciar a instalação, manter o servidor ativo, configurar corretamente o cliente e validar o comportamento real da integração.

A combinação de mise, systemd e MCP fornece uma base organizada para executar a ferramenta localmente no Debian. O próximo passo é validar o uso efetivo da memória nas sessões e ajustar os hooks de acordo com as capacidades da versão instalada.

Referências

AI Memory: https://github.com/akitaonrails/ai-memory
mise: https://mise.jdx.dev/
OpenCode: https://opencode.ai/docs/

OpenCode Not Working in Windows 11: CLI + Desktop Both Fail on ConfigInvalidError — Cause and Fix

Fri, 18 Sep 2026 14:09:54 +0000

Environment: Windows 11 Pro Insider Preview (build 10.0.26300), OpenCode CLI v1.18.23, OpenCode Desktop v1.18.25, Node.js v26.7.0.

Symptom: OpenCode Not Working — both the CLI and the separately-installed Desktop app fail to start a session, immediately, on every launch attempt.

Reproduction

$ opencode --version
1.18.23
$ opencode
Configuration is invalid at C:\Users\istiqur\.config\opencode\agents\blog-writer.md
↳ Expected object | undefined, got ["Read","Write","Edit","Grep","Glob"] tools

The CLI's validator names the exact file and field. Compare against the Desktop app's renderer.log:

[error]  Failed to load sessions Error: ConfigInvalidError
[error]  Failed to load sessions Error: ConfigInvalidError
[error]  Failed to finish bootstrap instance Error: ConfigInvalidError

No file path, no field name — same failure class, far less actionable output.

Root Cause

Five custom subagent .md files under ~/.config/opencode/agents/ declared tools: as a YAML sequence:

tools:
  - Read
  - Write
  - Edit

OpenCode's config schema requires tools as a mapping (tool name → boolean):

tools:
  read: true
  write: true
  edit: true

Both shapes are valid YAML in isolation — per the YAML 1.2.2 spec, a sequence and a mapping are distinct node types, so the file parses fine and only fails when a stricter schema inspects the field. All five files carried the identical defect (list format, apparently ported from a different AI coding assistant's subagent convention), confirming a batch-import mismatch rather than an isolated typo.

Affected files:

File	Declared tools
`blog-writer.md`	Read, Write, Edit, Grep, Glob
`blog-seo.md`	Read, Grep, Glob
`blog-reviewer.md`	Read, Grep, Glob
`blog-researcher.md`	WebSearch, WebFetch, Read, Grep, Glob
`blog-translator.md`	Read, Write, Edit, Glob, Grep

Why It Broke Both Applications

OpenCode CLI and OpenCode Desktop are separate installers (AppData\Roaming\npm\opencode vs AppData\Local\Programs\@opencode-aidesktop\OpenCode.exe) with independent version numbers and log directories. They share the same config root, ~/.config/opencode/, and both boot the same local sidecar server at startup:

[info]  spawning sidecar { url: 'http://127.0.0.1:11956' }
[info]  server ready { url: 'http://127.0.0.1:11956' }

The sidecar itself starts cleanly in both cases (main.log shows no errors) — the failure occurs specifically when the app asks the running server to enumerate the agents directory and receives the validation error back. Config errors introduced through either surface (CLI, direct file edit, another tool) will therefore surface identically on both — they are not independent configuration domains.

Watch the full breakdown on video

Fix

Frontmatter-only change, one line per file:

 tools:
-  - Read
-  - Write
-  - Edit
+  Read: true
+  Write: true
+  Edit: true

Apply to all five affected files, preserving tool names and case. No reinstall, no cache invalidation, no plugin reset required.

Verification

$ opencode
# TUI launches cleanly, 0 matches for "invalid"/"error" in captured output

For Desktop: confirm no stale opencode-named process is running, force-relaunch, and check the newest log session — not the first one alphabetically or chronologically listed. The pre-fix log session will still show the old errors and can easily be mistaken for a failed fix if you don't check its own start timestamp against the fix's file-mtime.

Check	Before	After
CLI startup	Fatal `ConfigInvalidError`	Clean launch
Desktop `renderer.log`	6 error entries	0
Desktop `main.log`	No errors (sidecar itself was fine)	No errors
Bootstrap	Failed	Succeeded

opencode.json was found to store MCP service API keys in plaintext. Unrelated to this failure, but worth an audit pass on any OpenCode install — keep such config files out of version control, source keys from environment variables where possible.

Takeaways for Anyone Running Multiple AI Coding Assistants

Subagent/plugin config schemas are not interchangeable between vendors, even with near-identical file conventions (Markdown + YAML frontmatter, tools: field present in both).
Eager, whole-config, fail-closed validation means a single malformed file can abort every entry point, not just the misconfigured agent.
A CLI and a GUI application sharing one config root will share failure modes, regardless of separate installers/versions.
Reproduce GUI failures at the CLI first when a CLI equivalent exists — error verbosity is often not consistent across surfaces of the same product.
Timestamp-check any log before trusting its contents during verification.

Full writeup (complete diffs, appendix, environment fingerprint): https://istiquritconsultant.com/workflow-optimization-blogs/opencode-not-working-windows-11/ — more postmortems: https://istiquritconsultant.com/workflow-optimization-blogs/

This topic was picked by newsletter vote (69% vs. 13% and 18% for two other incidents). Suggestions for future postmortems welcome — comment below or join the newsletter.

Coder Legion - Recent posts tagged opencode

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

1. Preparando o ambiente

2. Iniciando e validando o servidor

3. Inventariando e validando as sessões

3.1. Criar o script de validação

3.2. Executar a validação

3.3. Consultar o relatório

4. Validando uma sessão antes de importar

5. Testando uma importação real

6. Automatizando as 176 sessões restantes

7. Conferindo os resultados

8. Problemas encontrados e soluções

Conclusão

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

DevEx

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

O problema: cada sessão termina, mas o conhecimento precisa continuar

A solução: AI Memory

Preservação e validação do histórico

Resultado da migração

Por que manter a memória local?

O que ainda precisa ser validado?

Conclusão

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

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

1. Instalando o mise no Debian

2. Instalando o AI Memory

3. Executando o servidor MCP

4. Mantendo o AI Memory ativo com systemd

5. Integrando o AI Memory ao OpenCode 2

6. Configurando os hooks

7. Diagnóstico de problemas

8. Comandos úteis para o dia a dia

Conclusão

OpenCode Not Working in Windows 11: CLI + Desktop Both Fail on ConfigInvalidError — Cause and Fix

Reproduction

Root Cause

Why It Broke Both Applications

Fix

Verification

Related Finding (Not the Root Cause)

Takeaways for Anyone Running Multiple AI Coding Assistants

Find Me Elsewhere