ai-memory: instale memória persistente para agentes no Linux

Trocar de Claude Code para Codex, OpenCode, Cursor ou Grok no meio de uma tarefa normalmente custa contexto: é preciso explicar de novo a arquitetura, as tentativas que falharam e o próximo passo. O ai-memory resolve esse problema com memória persistente compartilhada entre agentes. Este guia instala a versão nativa no Linux, cria um serviço systemd --user, liga MCP e hooks nos clientes suportados e mostra onde os dados ficam. A versão 2.0 também tornou a memória mais portátil e preparada para uso concorrente.

O que o ai-memory guarda — e o que não guarda

O ai-memory é um servidor de memória de longo prazo para agentes de programação. Os hooks registram eventos da sessão; o servidor consolida esse material em páginas Markdown e permite recuperar contexto e handoffs pelo MCP. A fonte de verdade é uma wiki em arquivos .md; o SQLite é um índice derivado. Isso torna a memória inspecionável, versionável e recuperável sem depender de um banco vetorial opaco.

O caminho padrão não exige chave de API nem chamadas a LLM: captura, busca textual e handoff continuam disponíveis. Na primeira execução do servidor, o ai-memory baixa o modelo local all-MiniLM-L6-v2 para embeddings; ele não precisa de chave de API. Uma LLM é opcional para recursos de consolidação e recuperação. Para desligar embeddings locais, defina embedding_provider = "none" na configuração. Antes de ativar hooks, avalie o que pode entrar no histórico do projeto. Para áreas sensíveis, use uma política de captura e mantenha a instância apenas no loopback.

O que mudou na linha 2.x

O anúncio da ai-memory 2.0 ajuda a entender por que este não é apenas um gerenciador de resumos. A wiki passou a usar o Open Knowledge Format (OKF): páginas Markdown com metadados padronizados. Em outras palavras, a memória continua legível fora do servidor — você pode inspecioná-la, versioná-la no Git ou levá-la para outra ferramenta compatível.

Ao migrar uma instalação 1.x, a 2.0 cria e verifica um backup do diretório de dados antes de alterar o formato. Não descarte esse backup até conferir a wiki e as consultas após a atualização. Os embeddings locais continuam sendo o caminho padrão: não exigem chave de API nem enviam o conteúdo da memória a um provedor externo.

A outra mudança prática é a concorrência. Claude Code, Codex, OpenCode e outros harnesses podem trabalhar no mesmo checkout sem compartilhar um ponteiro global de “projeto atual”. As escritas passam por uma fila única e páginas recebem versões, para que uma atualização posterior não apague silenciosamente a anterior. Em uma instalação compartilhada, as páginas podem servir ao time inteiro; handoffs, porém, continuam pessoais e só podem ser aceitos uma vez pelo dono da sessão.

Isso não significa que uma conversa já aberta seja interrompida para receber uma anotação nova: ela a verá na próxima consulta ou numa sessão seguinte. Para equipes, mantenha autenticação e HTTPS antes de expor o serviço fora da máquina local.

Pré-requisitos e escolha da instalação

O projeto oferece binários Linux para x86_64 e aarch64. A alternativa recomendada pelo próprio projeto para instalações nativas é mise use -g github:akitaonrails/ai-memory; abaixo usaremos o tarball da release para deixar versão, checksum, binário e hooks explícitos.

Não use cargo install ai-memory: esse nome já pertence a outro crate no crates.io. Para compilar, use o workspace do repositório; para operar normalmente, prefira um binário da release v2.1.1.

command -v curl sha256sum tar systemctl
uname -m
mkdir -p ~/.local/bin ~/.config/ai-memory ~/.local/share/ai-memory

Baixando e verificando o binário nativo

Baixe sempre o arquivo .sha256 publicado junto ao tarball e interrompa a instalação se a soma não conferir. O bloco abaixo seleciona a arquitetura, usa a release v2.1.1 e preserva os hooks que vêm no pacote.

set -euo pipefail

VER=2.1.1
case "$(uname -m)" in
  x86_64)  ARQ=ai-memory-linux-x86_64.tar.gz ;;
  aarch64|arm64) ARQ=ai-memory-linux-aarch64.tar.gz ;;
  *) echo "Arquitetura sem binário publicado: $(uname -m)" >&2; exit 1 ;;
esac

BASE="https://github.com/akitaonrails/ai-memory/releases/download/v${VER}"
TMP=$(mktemp -d)
trap 'rm -rf "$TMP"' EXIT

curl -fL "$BASE/$ARQ" -o "$TMP/$ARQ"
curl -fL "$BASE/$ARQ.sha256" -o "$TMP/$ARQ.sha256"
(
  cd "$TMP"
  sha256sum -c "$ARQ.sha256"
  mkdir release
  tar -xzf "$ARQ" -C release
)

install -m 0755 "$TMP/release/ai-memory" "$HOME/.local/bin/ai-memory"
install -d "$HOME/.local/share/ai-memory/release-$VER"
cp -a "$TMP/release/hooks" "$HOME/.local/share/ai-memory/release-$VER/"

export PATH="$HOME/.local/bin:$PATH"
ai-memory --version

Se ai-memory não aparecer em um terminal novo, acrescente export PATH="$HOME/.local/bin:$PATH" ao arquivo de inicialização do shell, como ~/.bashrc o ~/.zshrc.

Inicializando a base local

Vamos manter a configuração em ~/.config/ai-memory/config.toml e os dados em ~/.local/share/ai-memory, o padrão esperado em uma instalação de usuário no Linux.

ai-memory 
  --data-dir "$HOME/.local/share/ai-memory" 
  --config "$HOME/.config/ai-memory/config.toml" 
  init

Após o primeiro uso, a wiki fica em ~/.local/share/ai-memory/wiki/, o índice SQLite em ~/.local/share/ai-memory/db/memory.sqlite e os modelos locais em ~/.local/share/ai-memory/models/. A wiki é a fonte de verdade das páginas, mas sessões, observações, handoffs e auditoria também vivem no banco. Para uma cópia completa, use o comando de backup do próprio ai-memory:

mkdir -p "$HOME/backups/ai-memory"
ai-memory backup --to "$HOME/backups/ai-memory/ai-memory-$(date +%Y%m%d-%H%M).tar.gz"

Subindo o servidor com systemd do usuário

O servidor MCP precisa ficar rodando para que os CLIs e hooks falem com ele. Este serviço de usuário escuta somente em 127.0.0.1:49374: não publique essa porta na rede.

cat > ~/.config/systemd/user/ai-memory.service <<'UNIT'
[Unit]
Description=ai-memory local MCP and lifecycle server
After=network.target

[Service]
Type=simple
WorkingDirectory=%h
ExecStart=%h/.local/bin/ai-memory --data-dir %h/.local/share/ai-memory --config %h/.config/ai-memory/config.toml serve --transport http --bind 127.0.0.1:49374
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=default.target
UNIT

systemctl --user daemon-reload
systemctl --user enable --now ai-memory.service
systemctl --user status ai-memory.service --no-pager

Em uma máquina que deve manter o serviço ativo mesmo sem login gráfico, habilite linger uma única vez:

loginctl enable-linger "$USER"

Confira o processo e os logs quando algo não responder:

systemctl --user is-active ai-memory.service
journalctl --user -u ai-memory.service -n 80 --no-pager
ai-memory status

Usando ChatGPT/Codex como provedor LLM

Sem provedor, o ai-memory continua capturando sessões, buscando na wiki e criando resumos determinísticos. Um LLM acrescenta consolidação mais rica, lint e melhorias em segundo plano. Para usar a assinatura ChatGPT Plus, Pro ou Codex, selecione openai-oauth: ele usa o backend ChatGPT/Codex por OAuth, não precisa de OPENAI_API_KEY e guarda o token renovável em ~/.local/share/ai-memory/auth.json.

Para consolidação, um modelo econômico é suficiente. O exemplo fixa gpt-5.6-luna com medium: é o ponto de partida mais equilibrado quando as sessões envolvem decisões técnicas, tentativas que falharam e próximos passos. Crie um drop-in do systemd, em vez de editar a unidade principal:

mkdir -p ~/.config/systemd/user/ai-memory.service.d

cat > ~/.config/systemd/user/ai-memory.service.d/llm-openai-oauth.conf <<'EOF'
[Service]
Environment=AI_MEMORY_LLM_PROVIDER=openai-oauth
Environment=AI_MEMORY_LLM_MODEL=gpt-5.6-luna
Environment=AI_MEMORY_LLM_REASONING_EFFORT=medium
Environment=AI_MEMORY_CONSOLIDATE_ON_SESSION_END=true
EOF

systemctl --user daemon-reload

O último parâmetro agenda a consolidação com LLM depois de um encerramento de sessão; a captura e o handoff não ficam bloqueados esperando a resposta do modelo. O GPT-5.6 Luna é voltado a cargas de alto volume e sensíveis a custo e aceita none, low, medium, high, xhigh e max. Portanto, none é uma configuração válida — mas não é a única opção, nem a melhor escolha padrão para consolidar sessões técnicas.

Qual effort escolher para o ai-memory?

Comece com medium se o objetivo é preservar decisões, causas de falhas e pendências de uma sessão. Ele tende a produzir uma consolidação mais útil que um simples resumo, sem elevar o custo e a latência tanto quanto os níveis mais altos.

Effort	Quando usar no ai-memory
none	Extração ou resumo muito simples, quando a menor latência é prioridade.
low	Boa opção para equilibrar velocidade e qualidade em sessões rotineiras.
medium	Recomendado como ponto de partida para consolidação de sessões técnicas e handoffs.
high	Teste apenas para sessões excepcionalmente complexas, se medium estiver deixando decisões importantes de fora.
xhigh e max	Raramente necessários para a consolidação automática; aumente somente após avaliar ganho real de qualidade.

Em outras palavras: use low quando quiser privilegiar velocidade; use medium para o uso diário de projetos com código, infraestrutura e troubleshooting. Só suba para high se os handoffs e páginas consolidadas comprovadamente ainda estiverem superficiais.

Login OAuth e teste

Faça o login interativo no mesmo usuário que executa o serviço. O comando mostra uma URL e um código temporário: abra a URL, entre na sua conta ChatGPT/Codex e informe o código. Não copie o arquivo auth.json, nem cole tokens em arquivos de configuração.

ai-memory auth login openai-oauth

# depois de autorizar no navegador:
systemctl --user restart ai-memory.service
ai-memory auth status
ai-memory llm-test 
  --provider openai-oauth 
  --model gpt-5.6-luna 
  --prompt 'Responda somente: OK'

O teste deve devolver OK. Se o login expirar ou for revogado, repita ai-memory auth login openai-oauth; para trocar de conta, execute antes ai-memory auth logout openai-oauth. Consulte a documentação de provedores do ai-memory para Anthropic, OpenAI por API, Gemini, Copilot e endpoints compatíveis com OpenAI.

Registrando MCP e hooks nos agentes

O MCP dá ao agente ferramentas como consulta de memória e aceitação de handoff. Os hooks fazem a captura automática do ciclo de vida. Os dois são necessários para a experiência completa. Os comandos abaixo fazem merge das entradas pertencentes ao ai-memory, sem exigir edição manual dos JSON e TOML dos clientes.

Defina o diretório de hooks extraído na instalação e execute a dupla de comandos para cada cliente instalado:

export PATH="$HOME/.local/bin:$PATH"
HOOKS_DIR="$HOME/.local/share/ai-memory/release-2.1.1/hooks"

# Claude Code
ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --hooks-dir "$HOOKS_DIR" --apply --project-strategy repo-root

# OpenAI Codex
ai-memory install-mcp --client codex --apply
ai-memory install-hooks --agent codex --hooks-dir "$HOOKS_DIR" --apply --project-strategy repo-root

# OpenCode
ai-memory install-mcp --client open-code --apply
ai-memory install-hooks --agent open-code --apply --project-strategy repo-root

# Cursor Agent CLI
ai-memory install-mcp --client cursor --apply
ai-memory install-hooks --agent cursor --hooks-dir "$HOOKS_DIR" --apply --project-strategy repo-root

# Grok Build CLI
ai-memory install-mcp --client grok --apply
ai-memory install-hooks --agent grok --hooks-dir "$HOOKS_DIR" --apply --project-strategy repo-root

Reinicie os clientes depois do merge. No Codex, aprove os hooks quando o cliente pedir confirmação. O OpenCode carrega os hooks como um plugin TypeScript em ~/.config/opencode/plugins/, por isso também precisa ser reiniciado. No Grok, o stdout do evento SessionStart não é inserido no contexto; ao retomar trabalho, peça ao agente para chamar memory_handoff_accept. No Codex CLI 0.145.0 ou mais novo, o evento SessionEnd entrega o handoff automaticamente. Em versões antigas — ou quando esse evento não estiver disponível — o evento Stop não encerra a sessão: execute ai-memory finalize-session --agent codex ao concluir uma tarefa importante.

Escopo por repositório e regras de privacidade

Sem configuração, o projeto é identificado pelo nome do diretório corrente. O parâmetro --project-strategy repo-root usado acima evita que um cd para um subdiretório crie uma memória separada. Para declarar o escopo no próprio repositório, crie .ai-memory.toml na raiz:

workspace = "pessoal"
project = "site-linuxpro"

[briefing]
inject_on_session_start = "true"
max_chars = 4000

[capture]
ignore_paths = ["private/**", "~/.ssh/**"]

Os valores de workspace e project aceitam letras minúsculas ASCII, dígitos, ponto, hífen e sublinhado. A seção capture evita registrar eventos reconhecidos de ferramentas de arquivo sob os caminhos indicados; não é uma solução completa de DLP para comandos de shell ou conteúdo que você mesmo escrever no prompt. Para máxima cautela, instale os hooks em modo allowlist e coloque o marcador somente nos repositórios que devem ser capturados:

ai-memory install-hooks --agent claude-code --hooks-dir "$HOOKS_DIR" --apply --capture-mode allowlist

Consultando a memória e entregando contexto

Depois de trabalhar normalmente pelo agente, use o MCP para pedir uma busca sobre decisões, arquivos ou tentativas anteriores. Ao encerrar, finalize a sessão quando necessário; o próximo agente deve aceitar o handoff pendente em vez de começar do zero.

# Útil principalmente após uma sessão do Codex:
ai-memory finalize-session

# Diagnóstico e manutenção local
ai-memory status
ai-memory lint

Dentro de Claude, Codex, OpenCode, Cursor Agent CLI ou Grok, uma instrução simples basta: “busque na memória decisões sobre autenticação deste projeto” ou “aceite o handoff pendente”. O agente usa as ferramentas MCP registradas; não é preciso copiar a wiki para a conversa.

Acesso remoto: não exponha a porta crua

O exemplo deste artigo é local e não usa autenticação porque o bind é exclusivo de loopback. Para atender outra máquina, configure token bearer, allowed_hosts e HTTPS por um proxy reverso antes de alterar o bind. Autenticação não cifra o tráfego. O projeto mantém um guia de proxy HTTPS com exemplos para Caddy e Cloudflare Tunnel.

Atualizações e recuperação

Para atualizar uma instalação por tarball, baixe a nova release, valide o checksum, substitua o binário, atualize o diretório de hooks e reinicie o serviço. Depois, rode novamente install-hooks --apply para cada agente. Ao cruzar a fronteira para a linha 2.x, deixe a migração criar e verificar seu backup antes de tocar nos dados. Não apague wiki/ nem db/ durante esse processo.

systemctl --user restart ai-memory.service
systemctl --user status ai-memory.service --no-pager

Se houver problema após uma atualização, restaure o arquivo gerado por ai-memory backup e examine journalctl --user -u ai-memory.service. Esse backup inclui a wiki e o estado SQLite necessário para preservar também sessões, observações e handoffs.

Crédito ao autor e licença

O ai-memory é criado e mantido por Fábio Akita, autor do repositório akitaonrails/ai-memory. O arquivo LICENSE da release identifica “Copyright (c) 2026 Fabio Akita” e disponibiliza o projeto sob a licença MIT. Obrigado ao Fábio por disponibilizar uma alternativa aberta, local e interoperável para memória de agentes.

Com o serviço local, MCP e hooks instalados, você pode alternar de agente sem abandonar o histórico técnico do projeto. Para comparar outras opções, veja também as alternativas ao Claude-Mem em Go, Rust e C e o artigo sobre memória persistente para agentes no Linux.