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.
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