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. O roteiro abaixo está atualizado para a versão 2.6.3.
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 observações sanitizadas e limitadas de prompts e ferramentas — não uma transcrição completa. O servidor produz resumos e pode consolidar o material em páginas Markdown; consulta e handoffs ficam disponíveis por MCP. A wiki em arquivos .md é a fonte de verdade das páginas. O SQLite mantém índices derivados e também estado operacional, como sessões, observações e handoffs. 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.
O que muda para quem instala a 2.6.3
A série 2.6 acrescentou perfil de preferências entre projetos, backup das configurações dos agentes, controles de handoff e o exportador opcional ai-memory-wikisync. Os patches seguintes corrigiram problemas de captura, privacidade e roteamento. Para este tutorial, estes são os pontos práticos:
- Escopo MCP explícito: em clientes estáticos, informe
workspaceeproject; não presuma que os hooks também identificam a sessão nas chamadas MCP. - Reaplique os hooks: as integrações TypeScript geradas receberam correções de retenção de eventos quando o servidor responde com falhas temporárias.
- Revise o perfil antigo: correções na identificação de preferências não apagam automaticamente entradas já admitidas.
- Servidor e clientes são processos distintos: substituir o binário não reinicia o serviço nem recarrega plugins de agentes já abertos.
Consulte o changelog fixado na 2.6.3. O ai-memory-wikisync é uma exportação unidirecional de famílias de páginas permitidas; não é sincronização bidirecional e não é necessário para esta instalação.
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.6.3. No Fedora, a release também publica RPMs para x86_64 e aarch64, instaláveis com sudo dnf install ./ai-memory-2.6.3-1.<arq>.rpm; o pacote traz os arquivos de serviço systemd do projeto. Este guia segue com o tarball Linux; confira a arquitetura suportada e valide o executável na sua distribuição.
command -v curl sha256sum tar systemctl
uname -m
mkdir -p ~/.local/bin ~/.config/ai-memory ~/.local/share/ai-memory ~/.config/systemd/userBaixando 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.6.3 e preserva os hooks que vêm no pacote.
set -euo pipefail
VER=2.6.3
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.new"
mv -f "$HOME/.local/bin/ai-memory.new" "$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 --versionSe 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 ou ~/.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" \
initApó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 backup do próprio ai-memory depois de iniciar o servidor, como mostrado na próxima seção.
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 --enable-web
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-pagerEm 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 statusCom o servidor ativo, crie um backup completo da memória. Este comando depende da API do serviço; não funciona antes de iniciá-lo:
mkdir -p "$HOME/backups/ai-memory"
ai-memory backup --to "$HOME/backups/ai-memory/ai-memory-$(date +%Y%m%d-%H%M).tar.gz"LLM opcional: configure e teste separadamente
Captura, busca textual e handoff não dependem de uma LLM generativa. A consolidação com provedor externo envia conteúdo selecionado para fora da máquina: avalie privacidade, disponibilidade e limites antes de habilitá-la.
O provedor openai-oauth do ai-memory usa login próprio e armazena o token em <data_dir>/auth.json. Não é o mesmo que codex, que reutiliza o acesso administrado pelo Codex CLI. A documentação da release indica gpt-5.5 como padrão de openai-oauth; disponibilidade depende da conta e do serviço. Não confunda esse exemplo com a configuração histórica deste laboratório, que utilizava gpt-6-luna com effort high.
ai-memory auth login openai-oauth
ai-memory auth status
ai-memory llm-test \
--provider openai-oauth \
--model gpt-5.5 \
--prompt 'Responda somente: OK'Faça o login no mesmo usuário e diretório de dados do serviço. Não publique tokens nem o arquivo auth.json. Só prossiga se o teste funcionar com a sua conta. Depois, para uma instalação nova, crie o drop-in:
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.5
Environment=AI_MEMORY_CONSOLIDATE_ON_SESSION_END=true
EOF
systemctl --user daemon-reload
systemctl --user restart ai-memory.service
ai-memory statusEm um serviço já configurado, edite o drop-in existente em vez de sobrescrevê-lo. Variáveis do systemd não são exportadas para o seu terminal. Se escolher outro modelo ou AI_MEMORY_LLM_REASONING_EFFORT, valide a combinação com llm-test; mais raciocínio não garante uma consolidação melhor. O teste desta revisão conferiu o binário e os comandos, não refez a autenticação nem uma chamada paga ao provedor.
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.6.3/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-rootReinicie 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 de SessionStart continua descartado; desde a 2.5.0, o handoff pendente é entregue como contexto no primeiro uso de ferramenta da sessão. Se a sessão não chamar nenhuma ferramenta, peça ao agente para chamar memory_handoff_accept. No Codex CLI 0.145.0 ou mais novo, o evento SessionEnd finaliza a sessão e, se a criação automática estiver habilitada, cria o handoff para a próxima sessão. 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, a partir da 2.5.0 o projeto de um checkout com remote Git é identificado pelo repositório (remote upstream, senão origin), não pelo nome da pasta: dois clones do mesmo repositório em pastas diferentes caem no mesmo projeto, e dois repositórios distintos com a mesma pasta não se misturam. Projetos existentes compatíveis podem ser reaproveitados. Na linha 2.6, os clientes atuais enviam por padrão identity_style = "path": o nome deriva do caminho completo do remote, sem o host. Uma captura ou escrita autorizada pode promover um nome compatível, preservando o UUID; consultas não renomeiam projetos e ambiguidades são recusadas. Confira o resultado com ai-memory doctor e ai-memory list-projects. Sem remote, vale o nome do diretório. 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. Um project declarado no marcador continua tendo prioridade sobre o remote Git. 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 allowlistHooks não garantem escopo nas chamadas MCP
Um cliente só é session-aware quando encaminha o ID real da sessão de lifecycle em cada chamada MCP. Ter hooks instalados, por si só, não faz isso. No cliente estático, o agente deve ler os nomes exatos do .ai-memory.toml e passar os dois argumentos em toda operação de projeto:
{"workspace": "pessoal", "project": "site-linuxpro"}Esses nomes são apenas os do exemplo acima. Não deduza o escopo pelo nome da pasta nem pelo último projeto ativo do servidor. Na 2.6.3, memory_message_send, memory_message_pop e memory_message_cancel recusam escopo inferido sem vínculo à sessão; memory_message_list informa como o escopo foi resolvido. A recusa evita atuar na caixa de outro projeto.
Para Claude Code, existe a ponte opcional ai-memory install-mcp --client claude-code --session-aware --apply. Confira seu funcionamento antes de depender de seleção automática. Para consultas globais, use global=true sem misturá-lo com workspace, project ou scopes.
Perfil compartilhado: confira o que atravessa projetos
Desde a 2.6.0, o perfil pode aprender preferências a partir das suas solicitações e de páginas curadas. Não confunda esse recurso com isolamento absoluto entre projetos: em uma instalação de um único operador, ele compartilha padrões de trabalho entre workspaces. Inspecione o conteúdo antes de adotá-lo em trabalhos de clientes:
ai-memory profile status
ai-memory profile list
ai-memory profile reviewPara impedir que um projeto contribua ou receba esse perfil, acrescente ao seu .ai-memory.toml, sem apagar as configurações existentes:
[profile]
contribute = false
consume = falseAo atualizar da 2.6.0: profile rebuild relê a base, mas não remove entradas antigas nem reclassifica todos os candidatos já registrados. Revise as evidências com profile review e remova individualmente uma preferência incorreta com ai-memory profile forget CAMINHO_DA_ENTRADA, usando o caminho exibido na listagem. Não execute exclusões em lote sem revisar. Memória recuperada nunca autoriza comandos nem substitui suas instruções atuais.
Essas opções controlam o perfil; não desligam os hooks nem substituem [capture]. Consulte a documentação do perfil para revisar, remover preferências e configurar o comportamento do servidor.
Handoff sem consumo automático
Se abrir uma sessão não deve consumir o contexto reservado para outra tarefa, ajuste a seção abaixo no arquivo de configuração usado pelo servidor. Preserve as demais seções e reinicie o serviço:
[handoff]
claim_on_session_start = false
create_on_session_end = falseCom a primeira opção, a abertura mostra um aviso com o ID do handoff, sem reivindicá-lo. O agente pode listar os pendentes com memory_handoff_list e aceitar o escolhido por ID. A segunda desliga a criação automática no encerramento de sessões não gerenciadas; resumos e consolidação continuam. Handoffs explícitos e execuções gerenciadas não são desativados. Ambas são opções globais do servidor e permanecem true por padrão.
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 doctor
ai-memory lintDentro 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
Antes de substituir o executável, faça backup. A instalação manual acima também serve para atualizar; não precisa recriar a base, o serviço ou as credenciais.
mkdir -p "$HOME/backups/ai-memory"
ai-memory backup --to "$HOME/backups/ai-memory/ai-memory-$(date +%Y%m%d-%H%M%S).tar.gz"Saindo da 2.4.x ou 2.5.x: prefira o bloco manual deste guia, com VER=2.6.3. A 2.4.x não tinha upgrade; o atualizador da 2.5.x podia recusar arquivos auxiliares do pacote oficial. A correção desse segundo problema chegou na 2.6.0 — não está no binário antigo que tenta atualizar.
Instalação nativa por release, já na 2.6.0 ou posterior: use o atualizador com versão explícita. Instalações AUR, RPM, Homebrew ou outros gerenciadores devem seguir o método de atualização correspondente, não este comando.
ai-memory upgrade --version 2.6.3
systemctl --user restart ai-memory.service
systemctl --user is-active ai-memory.service
ai-memory --version
ai-memory statusA CLI e o servidor devem indicar a versão esperada. Se o serviço ainda estiver iniciando, consulte journalctl --user -u ai-memory.service -n 80 --no-pager e repita a consulta. O upgrade reaplica hooks registrados, mas clientes abertos precisam ser reiniciados.
Na atualização manual, reaplique os hooks usando os arquivos da nova release. Faça isso somente para agentes que você utiliza. As integrações geradas, como OpenCode, também precisam ser regeneradas para receber as correções de entrega da 2.6.3:
HOOKS_DIR="$HOME/.local/share/ai-memory/release-2.6.3/hooks"
# Exemplo após download manual:
ai-memory install-hooks --agent codex --hooks-dir "$HOOKS_DIR" --apply
# Se utiliza OpenCode:
# ai-memory install-hooks --agent open-code --apply
# Na raiz de cada projeto, renove instruções e skills gerenciadas:
ai-memory install-instructions --target AGENTS.md --skills-agent agents
# Claude Code: --target CLAUDE.md --skills-agent claude-code
systemctl --user restart ai-memory.service
ai-memory doctorO instalador de instruções preserva texto fora do bloco gerenciado. Reaplicar hooks sem --project-strategy mantém a estratégia já registrada. Reinicie os clientes MCP, abra uma sessão de teste e confira se captura e consulta usam o projeto correto. Não basta verificar apenas ai-memory --version.
Validação desta revisão: em 10/10/2026, o tarball Linux x86_64 da 2.6.3 passou no sha256sum -c e o executável extraído informou ai-memory 2.6.3. A sintaxe dos principais subcomandos foi conferida pelo --help. Não houve atualização do serviço desta estação nem teste ponta a ponta de todos os clientes nesta revisão editorial.
Backup da memória não é backup dos agentes
ai-memory backup preserva a wiki e o estado SQLite, incluindo sessões, observações e handoffs. O comando abaixo cobre outro conjunto: configurações, skills, plugins e instruções dos agentes. Veja primeiro o plano e depois gere o arquivo:
ai-memory backup-agents --dry-run --to "$HOME/backups/ai-memory/agentes.tar.gz"
ai-memory backup-agents --to "$HOME/backups/ai-memory/agentes-$(date +%Y%m%d-%H%M%S).tar.gz"A sanitização padrão cobre texto de configuração MCP, não todo arquivo: outros conteúdos são copiados integralmente e podem conter segredos. Proteja o arquivo e não o publique no Git. Antes de recuperar dados, consulte ai-memory restore --help ou ai-memory restore-agents --help, conforme o tipo de backup. Em migrações, guarde também a versão anterior do binário; não tente fazer downgrade contra um banco já migrado sem um plano de restauração.
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.