![\"Mascote](\"\/wp-content\/uploads\/2026\/09\/ai-memory-programador-cli-v2.webp\")
<\/p>\n<\/p>\n
Trocar de Claude Code para Codex, OpenCode, Cursor ou Grok no meio de uma tarefa normalmente custa contexto: \u00e9 preciso explicar de novo a arquitetura, as tentativas que falharam e o pr\u00f3ximo passo. O ai-memory<\/a> resolve esse problema com mem\u00f3ria persistente compartilhada entre agentes. Este guia instala a vers\u00e3o nativa no Linux, cria um servi\u00e7o O ai-memory \u00e9 um servidor de mem\u00f3ria de longo prazo para agentes de programa\u00e7\u00e3o. Os hooks registram observa\u00e7\u00f5es sanitizadas e limitadas de prompts e ferramentas \u2014 n\u00e3o uma transcri\u00e7\u00e3o completa. O servidor produz resumos e pode consolidar o material em p\u00e1ginas Markdown; consulta e handoffs ficam dispon\u00edveis por MCP. A wiki em arquivos O caminho padr\u00e3o n\u00e3o exige chave de API nem chamadas a LLM: captura, busca textual e handoff continuam dispon\u00edveis. Na primeira execu\u00e7\u00e3o do servidor, o ai-memory baixa o modelo local O an\u00fancio da ai-memory 2.0<\/a> ajuda a entender por que este n\u00e3o \u00e9 apenas um gerenciador de resumos. A wiki passou a usar o Open Knowledge Format (OKF): p\u00e1ginas Markdown com metadados padronizados. Em outras palavras, a mem\u00f3ria continua leg\u00edvel fora do servidor \u2014 voc\u00ea pode inspecion\u00e1-la, version\u00e1-la no Git ou lev\u00e1-la para outra ferramenta compat\u00edvel.<\/p>\n Ao migrar uma instala\u00e7\u00e3o 1.x, a 2.0 cria e verifica um backup do diret\u00f3rio de dados antes de alterar o formato. N\u00e3o descarte esse backup at\u00e9 conferir a wiki e as consultas ap\u00f3s a atualiza\u00e7\u00e3o. Os embeddings locais continuam sendo o caminho padr\u00e3o: n\u00e3o exigem chave de API nem enviam o conte\u00fado da mem\u00f3ria a um provedor externo.<\/p>\n A outra mudan\u00e7a pr\u00e1tica \u00e9 a concorr\u00eancia. Claude Code, Codex, OpenCode e outros harnesses podem trabalhar no mesmo checkout sem compartilhar um ponteiro global de \u201cprojeto atual\u201d. As escritas passam por uma fila \u00fanica e p\u00e1ginas recebem vers\u00f5es, para que uma atualiza\u00e7\u00e3o posterior n\u00e3o apague silenciosamente a anterior. Em uma instala\u00e7\u00e3o compartilhada, as p\u00e1ginas podem servir ao time inteiro; handoffs, por\u00e9m, continuam pessoais e s\u00f3 podem ser aceitos uma vez pelo dono da sess\u00e3o.<\/p>\n Isso n\u00e3o significa que uma conversa j\u00e1 aberta seja interrompida para receber uma anota\u00e7\u00e3o nova: ela a ver\u00e1 na pr\u00f3xima consulta ou numa sess\u00e3o seguinte. Para equipes, mantenha autentica\u00e7\u00e3o e HTTPS antes de expor o servi\u00e7o fora da m\u00e1quina local.<\/p>\n A s\u00e9rie 2.6 acrescentou perfil de prefer\u00eancias entre projetos, backup das configura\u00e7\u00f5es dos agentes, controles de handoff e o exportador opcional Consulte o changelog fixado na 2.6.3<\/a>. O O projeto oferece bin\u00e1rios Linux para N\u00e3o use Baixe sempre o arquivo Se Vamos manter a configura\u00e7\u00e3o em Ap\u00f3s o primeiro uso, a wiki fica em O servidor MCP precisa ficar rodando para que os CLIs e hooks falem com ele. Este servi\u00e7o de usu\u00e1rio escuta somente em Em uma m\u00e1quina que deve manter o servi\u00e7o ativo mesmo sem login gr\u00e1fico, habilite linger uma \u00fanica vez:<\/p>\n Confira o processo e os logs quando algo n\u00e3o responder:<\/p>\n Com o servidor ativo, crie um backup completo da mem\u00f3ria. Este comando depende da API do servi\u00e7o; n\u00e3o funciona antes de inici\u00e1-lo:<\/p>\n Captura, busca textual e handoff n\u00e3o dependem de uma LLM generativa. A consolida\u00e7\u00e3o com provedor externo envia conte\u00fado selecionado para fora da m\u00e1quina: avalie privacidade, disponibilidade e limites antes de habilit\u00e1-la.<\/p>\n O provedor Fa\u00e7a o login no mesmo usu\u00e1rio e diret\u00f3rio de dados do servi\u00e7o. N\u00e3o publique tokens nem o arquivo Em um servi\u00e7o j\u00e1 configurado, edite o drop-in existente em vez de sobrescrev\u00ea-lo. Vari\u00e1veis do systemd n\u00e3o s\u00e3o exportadas para o seu terminal. Se escolher outro modelo ou O MCP d\u00e1 ao agente ferramentas como consulta de mem\u00f3ria e aceita\u00e7\u00e3o de handoff. Os hooks fazem a captura autom\u00e1tica do ciclo de vida. Os dois s\u00e3o necess\u00e1rios para a experi\u00eancia completa. Os comandos abaixo fazem merge das entradas pertencentes ao ai-memory, sem exigir edi\u00e7\u00e3o manual dos JSON e TOML dos clientes.<\/p>\n Defina o diret\u00f3rio de hooks extra\u00eddo na instala\u00e7\u00e3o e execute a dupla de comandos para cada cliente instalado:<\/p>\n Reinicie os clientes depois do merge. No Codex, aprove os hooks quando o cliente pedir confirma\u00e7\u00e3o. O OpenCode carrega os hooks como um plugin TypeScript em Sem configura\u00e7\u00e3o, a partir da 2.5.0 o projeto de um checkout com remote Git \u00e9 identificado pelo reposit\u00f3rio (remote Os valores de Um cliente s\u00f3 \u00e9 session-aware<\/em> quando encaminha o ID real da sess\u00e3o de lifecycle em cada chamada MCP. Ter hooks instalados, por si s\u00f3, n\u00e3o faz isso. No cliente est\u00e1tico, o agente deve ler os nomes exatos do Esses nomes s\u00e3o apenas os do exemplo acima. N\u00e3o deduza o escopo pelo nome da pasta nem pelo \u00faltimo projeto ativo do servidor. Na 2.6.3, Para Claude Code, existe a ponte opcional Desde a 2.6.0, o perfil pode aprender prefer\u00eancias a partir das suas solicita\u00e7\u00f5es e de p\u00e1ginas curadas. N\u00e3o confunda esse recurso com isolamento absoluto entre projetos: em uma instala\u00e7\u00e3o de um \u00fanico operador, ele compartilha padr\u00f5es de trabalho entre workspaces. Inspecione o conte\u00fado antes de adot\u00e1-lo em trabalhos de clientes:<\/p>\n Para impedir que um projeto contribua ou receba esse perfil, acrescente ao seu Ao atualizar da 2.6.0:<\/strong> Essas op\u00e7\u00f5es controlam o perfil; n\u00e3o desligam os hooks nem substituem Se abrir uma sess\u00e3o n\u00e3o deve consumir o contexto reservado para outra tarefa, ajuste a se\u00e7\u00e3o abaixo no arquivo de configura\u00e7\u00e3o usado pelo servidor. Preserve as demais se\u00e7\u00f5es e reinicie o servi\u00e7o:<\/p>\n Com a primeira op\u00e7\u00e3o, a abertura mostra um aviso com o ID do handoff, sem reivindic\u00e1-lo. O agente pode listar os pendentes com Depois de trabalhar normalmente pelo agente, use o MCP para pedir uma busca sobre decis\u00f5es, arquivos ou tentativas anteriores. Ao encerrar, finalize a sess\u00e3o quando necess\u00e1rio; o pr\u00f3ximo agente deve aceitar o handoff pendente em vez de come\u00e7ar do zero.<\/p>\n Dentro de Claude, Codex, OpenCode, Cursor Agent CLI ou Grok, uma instru\u00e7\u00e3o simples basta: \u201cbusque na mem\u00f3ria decis\u00f5es sobre autentica\u00e7\u00e3o deste projeto\u201d ou \u201caceite o handoff pendente\u201d. O agente usa as ferramentas MCP registradas; n\u00e3o \u00e9 preciso copiar a wiki para a conversa.<\/p>\n O exemplo deste artigo \u00e9 local e n\u00e3o usa autentica\u00e7\u00e3o porque o bind \u00e9 exclusivo de loopback. Para atender outra m\u00e1quina, configure token bearer, Antes de substituir o execut\u00e1vel, fa\u00e7a backup.<\/strong> A instala\u00e7\u00e3o manual acima tamb\u00e9m serve para atualizar; n\u00e3o precisa recriar a base, o servi\u00e7o ou as credenciais.<\/p>\n Saindo da 2.4.x ou 2.5.x:<\/strong> prefira o bloco manual deste guia, com Instala\u00e7\u00e3o nativa por release, j\u00e1 na 2.6.0 ou posterior:<\/strong> use o atualizador com vers\u00e3o expl\u00edcita. Instala\u00e7\u00f5es AUR, RPM, Homebrew ou outros gerenciadores devem seguir o m\u00e9todo de atualiza\u00e7\u00e3o correspondente, n\u00e3o este comando.<\/p>\n A CLI e o servidor devem indicar a vers\u00e3o esperada. Se o servi\u00e7o ainda estiver iniciando, consulte Na atualiza\u00e7\u00e3o manual, reaplique os hooks usando os arquivos da nova release. Fa\u00e7a isso somente para agentes que voc\u00ea utiliza. As integra\u00e7\u00f5es geradas, como OpenCode, tamb\u00e9m precisam ser regeneradas para receber as corre\u00e7\u00f5es de entrega da 2.6.3:<\/p>\n O instalador de instru\u00e7\u00f5es preserva texto fora do bloco gerenciado. Reaplicar hooks sem Valida\u00e7\u00e3o desta revis\u00e3o:<\/strong> em 10\/10\/2026, o tarball Linux x86_64 da 2.6.3 passou no A sanitiza\u00e7\u00e3o padr\u00e3o cobre texto de configura\u00e7\u00e3o MCP, n\u00e3o todo arquivo: outros conte\u00fados s\u00e3o copiados integralmente e podem conter segredos. Proteja o arquivo e n\u00e3o o publique no Git. Antes de recuperar dados, consulte O ai-memory \u00e9 criado e mantido por F\u00e1bio Akita<\/a>, autor do reposit\u00f3rio akitaonrails\/ai-memory<\/a>. O arquivo LICENSE<\/a> da release identifica \u201cCopyright (c) 2026 Fabio Akita\u201d e disponibiliza o projeto sob a licen\u00e7a MIT. Obrigado ao F\u00e1bio por disponibilizar uma alternativa aberta, local e interoper\u00e1vel para mem\u00f3ria de agentes.<\/p>\n Com o servi\u00e7o local, MCP e hooks instalados, voc\u00ea pode alternar de agente sem abandonar o hist\u00f3rico t\u00e9cnico do projeto. Para comparar outras op\u00e7\u00f5es, veja tamb\u00e9m as alternativas ao Claude-Mem em Go, Rust e C<\/a> e o artigo sobre mem\u00f3ria persistente para agentes no Linux<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":" Install ai-memory 2.6.3 on Linux with systemd, MCP, and hooks. Check out the update, backup, per-project scope, and shared profile review.<\/p>","protected":false},"author":0,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[115,2],"tags":[394,426,116,311,427,158],"class_list":["post-1464","post","type-post","status-publish","format-standard","hentry","category-ia","category-linux","tag-agentes","tag-ai-memory","tag-ia","tag-mcp","tag-memoria-persistente","tag-rust"],"_links":{"self":[{"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/posts\/1464","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/comments?post=1464"}],"version-history":[{"count":16,"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/posts\/1464\/revisions"}],"predecessor-version":[{"id":1837,"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/posts\/1464\/revisions\/1837"}],"wp:attachment":[{"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/media?parent=1464"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/categories?post=1464"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/tags?post=1464"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}systemd --user<\/code>, liga MCP e hooks nos clientes suportados e mostra onde os dados ficam. O roteiro abaixo est\u00e1 atualizado para a vers\u00e3o 2.6.3.<\/p>\nRevis\u00e3o (10\/10\/2026):<\/strong> vers\u00e3o est\u00e1vel mais recente consultada: v2.6.3<\/a>. O changelog a data em 09\/10; os artefatos foram publicados em 10\/10, \u00e0s 03:34 UTC. Esta revis\u00e3o atualiza instala\u00e7\u00e3o, hooks e cuidados com o perfil compartilhado. O checksum e o execut\u00e1vel Linux x86_64 foram conferidos isoladamente; isso n\u00e3o equivale a testar todos os agentes ou provedores.<\/div>\nO que o ai-memory guarda \u2014 e o que n\u00e3o guarda<\/h2>\n
.md<\/code> \u00e9 a fonte de verdade das p\u00e1ginas. O SQLite mant\u00e9m \u00edndices derivados e tamb\u00e9m estado operacional, como sess\u00f5es, observa\u00e7\u00f5es e handoffs. Isso torna a mem\u00f3ria inspecion\u00e1vel, version\u00e1vel e recuper\u00e1vel sem depender de um banco vetorial opaco.<\/p>\nall-MiniLM-L6-v2<\/code> para embeddings; ele n\u00e3o precisa de chave de API. Uma LLM \u00e9 opcional para recursos de consolida\u00e7\u00e3o e recupera\u00e7\u00e3o. Para desligar embeddings locais, defina embedding_provider = \"none\"<\/code> na configura\u00e7\u00e3o. Antes de ativar hooks, avalie o que pode entrar no hist\u00f3rico do projeto. Para \u00e1reas sens\u00edveis, use uma pol\u00edtica de captura e mantenha a inst\u00e2ncia apenas no loopback.<\/p>\n![\"Agentes](\"\/wp-content\/uploads\/2026\/10\/ai-memory-flow-2-6-3.webp\")
O que mudou na linha 2.x<\/h2>\n
O que muda para quem instala a 2.6.3<\/h2>\n
ai-memory-wikisync<\/code>. Os patches seguintes corrigiram problemas de captura, privacidade e roteamento. Para este tutorial, estes s\u00e3o os pontos pr\u00e1ticos:<\/p>\n\n
workspace<\/code> e project<\/code>; n\u00e3o presuma que os hooks tamb\u00e9m identificam a sess\u00e3o nas chamadas MCP.<\/li>\nai-memory-wikisync<\/code> \u00e9 uma exporta\u00e7\u00e3o unidirecional de fam\u00edlias de p\u00e1ginas permitidas; n\u00e3o \u00e9 sincroniza\u00e7\u00e3o bidirecional e n\u00e3o \u00e9 necess\u00e1rio para esta instala\u00e7\u00e3o.<\/p>\nPr\u00e9-requisitos e escolha da instala\u00e7\u00e3o<\/h2>\n
x86_64<\/code> e aarch64<\/code>. A alternativa recomendada pelo pr\u00f3prio projeto para instala\u00e7\u00f5es nativas \u00e9 mise use -g github:akitaonrails\/ai-memory<\/code>; abaixo usaremos o tarball da release para deixar vers\u00e3o, checksum, bin\u00e1rio e hooks expl\u00edcitos.<\/p>\ncargo install ai-memory<\/code>: esse nome j\u00e1 pertence a outro crate no crates.io. Para compilar, use o workspace do reposit\u00f3rio; para operar normalmente, prefira um bin\u00e1rio da release v2.6.3<\/a>. No Fedora, a release tamb\u00e9m publica RPMs para x86_64<\/code> e aarch64<\/code>, instal\u00e1veis com sudo dnf install .\/ai-memory-2.6.3-1.<arq>.rpm<\/code>; o pacote traz os arquivos de servi\u00e7o systemd do projeto. Este guia segue com o tarball Linux; confira a arquitetura suportada e valide o execut\u00e1vel na sua distribui\u00e7\u00e3o.<\/p>\ncommand -v curl sha256sum tar systemctl\nuname -m\nmkdir -p ~\/.local\/bin ~\/.config\/ai-memory ~\/.local\/share\/ai-memory ~\/.config\/systemd\/user<\/code><\/pre>\nBaixando e verificando o bin\u00e1rio nativo<\/h2>\n
.sha256<\/code> publicado junto ao tarball e interrompa a instala\u00e7\u00e3o se a soma n\u00e3o conferir. O bloco abaixo seleciona a arquitetura, usa a release v2.6.3 e preserva os hooks que v\u00eam no pacote.<\/p>\nset -euo pipefail\n\nVER=2.6.3\ncase \"$(uname -m)\" in\n x86_64) ARQ=ai-memory-linux-x86_64.tar.gz ;;\n aarch64|arm64) ARQ=ai-memory-linux-aarch64.tar.gz ;;\n *) echo \"Arquitetura sem bin\u00e1rio publicado: $(uname -m)\" >&2; exit 1 ;;\nesac\n\nBASE=\"https:\/\/github.com\/akitaonrails\/ai-memory\/releases\/download\/v${VER}\"\nTMP=$(mktemp -d)\ntrap 'rm -rf \"$TMP\"' EXIT\n\ncurl -fL \"$BASE\/$ARQ\" -o \"$TMP\/$ARQ\"\ncurl -fL \"$BASE\/$ARQ.sha256\" -o \"$TMP\/$ARQ.sha256\"\n(\n cd \"$TMP\"\n sha256sum -c \"$ARQ.sha256\"\n mkdir release\n tar -xzf \"$ARQ\" -C release\n)\n\ninstall -m 0755 \"$TMP\/release\/ai-memory\" \"$HOME\/.local\/bin\/ai-memory.new\"\nmv -f \"$HOME\/.local\/bin\/ai-memory.new\" \"$HOME\/.local\/bin\/ai-memory\"\ninstall -d \"$HOME\/.local\/share\/ai-memory\/release-$VER\"\ncp -a \"$TMP\/release\/hooks\" \"$HOME\/.local\/share\/ai-memory\/release-$VER\/\"\n\nexport PATH=\"$HOME\/.local\/bin:$PATH\"\nai-memory --version<\/code><\/pre>\nai-memory<\/code> n\u00e3o aparecer em um terminal novo, acrescente export PATH=\"$HOME\/.local\/bin:$PATH\"<\/code> ao arquivo de inicializa\u00e7\u00e3o do shell, como ~\/.bashrc<\/code> ou ~\/.zshrc<\/code>.<\/p>\nInicializando a base local<\/h2>\n
~\/.config\/ai-memory\/config.toml<\/code> e os dados em ~\/.local\/share\/ai-memory<\/code>, o padr\u00e3o esperado em uma instala\u00e7\u00e3o de usu\u00e1rio no Linux.<\/p>\nai-memory \\\n --data-dir \"$HOME\/.local\/share\/ai-memory\" \\\n --config \"$HOME\/.config\/ai-memory\/config.toml\" \\\n init<\/code><\/pre>\n~\/.local\/share\/ai-memory\/wiki\/<\/code>, o \u00edndice SQLite em ~\/.local\/share\/ai-memory\/db\/memory.sqlite<\/code> e os modelos locais em ~\/.local\/share\/ai-memory\/models\/<\/code>. A wiki \u00e9 a fonte de verdade das p\u00e1ginas, mas sess\u00f5es, observa\u00e7\u00f5es, handoffs e auditoria tamb\u00e9m vivem no banco. Para uma c\u00f3pia completa, use o backup do pr\u00f3prio ai-memory depois de iniciar o servidor, como mostrado na pr\u00f3xima se\u00e7\u00e3o.<\/p>\nSubindo o servidor com systemd do usu\u00e1rio<\/h2>\n
127.0.0.1:49374<\/code>: n\u00e3o publique essa porta na rede.<\/p>\ncat > ~\/.config\/systemd\/user\/ai-memory.service <<'UNIT'\n[Unit]\nDescription=ai-memory local MCP and lifecycle server\nAfter=network.target\n\n[Service]\nType=simple\nWorkingDirectory=%h\nExecStart=%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\nRestart=on-failure\nRestartSec=5\nNoNewPrivileges=true\nPrivateTmp=true\n\n[Install]\nWantedBy=default.target\nUNIT\n\nsystemctl --user daemon-reload\nsystemctl --user enable --now ai-memory.service\nsystemctl --user status ai-memory.service --no-pager<\/code><\/pre>\nloginctl enable-linger \"$USER\"<\/code><\/pre>\nsystemctl --user is-active ai-memory.service\njournalctl --user -u ai-memory.service -n 80 --no-pager\nai-memory status<\/code><\/pre>\nmkdir -p \"$HOME\/backups\/ai-memory\"\nai-memory backup --to \"$HOME\/backups\/ai-memory\/ai-memory-$(date +%Y%m%d-%H%M).tar.gz\"<\/code><\/pre>\nLLM opcional: configure e teste separadamente<\/h2>\n
openai-oauth<\/code> do ai-memory usa login pr\u00f3prio e armazena o token em <data_dir>\/auth.json<\/code>. N\u00e3o \u00e9 o mesmo que codex<\/code>, que reutiliza o acesso administrado pelo Codex CLI. A documenta\u00e7\u00e3o da release<\/a> indica gpt-5.5<\/code> como padr\u00e3o de openai-oauth<\/code>; disponibilidade depende da conta e do servi\u00e7o. N\u00e3o confunda esse exemplo com a configura\u00e7\u00e3o hist\u00f3rica deste laborat\u00f3rio, que utilizava gpt-6-luna<\/code> com effort high<\/code>.<\/p>\nai-memory auth login openai-oauth\nai-memory auth status\nai-memory llm-test \\\n --provider openai-oauth \\\n --model gpt-5.5 \\\n --prompt 'Responda somente: OK'<\/code><\/pre>\nauth.json<\/code>. S\u00f3 prossiga se o teste funcionar com a sua conta. Depois, para uma instala\u00e7\u00e3o nova, crie o drop-in:<\/p>\nmkdir -p ~\/.config\/systemd\/user\/ai-memory.service.d\ncat > ~\/.config\/systemd\/user\/ai-memory.service.d\/llm-openai-oauth.conf <<'EOF'\n[Service]\nEnvironment=AI_MEMORY_LLM_PROVIDER=openai-oauth\nEnvironment=AI_MEMORY_LLM_MODEL=gpt-5.5\nEnvironment=AI_MEMORY_CONSOLIDATE_ON_SESSION_END=true\nEOF\nsystemctl --user daemon-reload\nsystemctl --user restart ai-memory.service\nai-memory status<\/code><\/pre>\nAI_MEMORY_LLM_REASONING_EFFORT<\/code>, valide a combina\u00e7\u00e3o com llm-test<\/code>; mais racioc\u00ednio n\u00e3o garante uma consolida\u00e7\u00e3o melhor. O teste desta revis\u00e3o conferiu o bin\u00e1rio e os comandos, n\u00e3o refez a autentica\u00e7\u00e3o nem uma chamada paga ao provedor.<\/p>\nRegistrando MCP e hooks nos agentes<\/h2>\n
export PATH=\"$HOME\/.local\/bin:$PATH\"\nHOOKS_DIR=\"$HOME\/.local\/share\/ai-memory\/release-2.6.3\/hooks\"\n\n# Claude Code\nai-memory install-mcp --client claude-code --apply\nai-memory install-hooks --agent claude-code --hooks-dir \"$HOOKS_DIR\" --apply --project-strategy repo-root\n\n# OpenAI Codex\nai-memory install-mcp --client codex --apply\nai-memory install-hooks --agent codex --hooks-dir \"$HOOKS_DIR\" --apply --project-strategy repo-root\n\n# OpenCode\nai-memory install-mcp --client open-code --apply\nai-memory install-hooks --agent open-code --apply --project-strategy repo-root\n\n# Cursor Agent CLI\nai-memory install-mcp --client cursor --apply\nai-memory install-hooks --agent cursor --hooks-dir \"$HOOKS_DIR\" --apply --project-strategy repo-root\n\n# Grok Build CLI\nai-memory install-mcp --client grok --apply\nai-memory install-hooks --agent grok --hooks-dir \"$HOOKS_DIR\" --apply --project-strategy repo-root<\/code><\/pre>\n~\/.config\/opencode\/plugins\/<\/code>, por isso tamb\u00e9m precisa ser reiniciado. No Grok, o stdout de SessionStart<\/code> continua descartado; desde a 2.5.0, o handoff pendente \u00e9 entregue como contexto no primeiro uso de ferramenta da sess\u00e3o. Se a sess\u00e3o n\u00e3o chamar nenhuma ferramenta, pe\u00e7a ao agente para chamar memory_handoff_accept<\/code>. No Codex CLI 0.145.0 ou mais novo, o evento SessionEnd<\/code> finaliza a sess\u00e3o e, se a cria\u00e7\u00e3o autom\u00e1tica estiver habilitada, cria o handoff para a pr\u00f3xima sess\u00e3o. Em vers\u00f5es antigas \u2014 ou quando esse evento n\u00e3o estiver dispon\u00edvel \u2014 o evento Stop n\u00e3o encerra a sess\u00e3o: execute ai-memory finalize-session --agent codex<\/code> ao concluir uma tarefa importante.<\/p>\nEscopo por reposit\u00f3rio e regras de privacidade<\/h2>\n
upstream<\/code>, sen\u00e3o origin<\/code>), n\u00e3o pelo nome da pasta: dois clones do mesmo reposit\u00f3rio em pastas diferentes caem no mesmo projeto, e dois reposit\u00f3rios distintos com a mesma pasta n\u00e3o se misturam. Projetos existentes compat\u00edveis podem ser reaproveitados. Na linha 2.6, os clientes atuais enviam por padr\u00e3o identity_style = \"path\"<\/code>: o nome deriva do caminho completo do remote, sem o host. Uma captura ou escrita autorizada pode promover um nome compat\u00edvel, preservando o UUID; consultas n\u00e3o renomeiam projetos e ambiguidades s\u00e3o recusadas. Confira o resultado com ai-memory doctor<\/code> e ai-memory list-projects<\/code>. Sem remote, vale o nome do diret\u00f3rio. O par\u00e2metro --project-strategy repo-root<\/code> usado acima evita que um cd<\/code> para um subdiret\u00f3rio crie uma mem\u00f3ria separada. Para declarar o escopo no pr\u00f3prio reposit\u00f3rio, crie .ai-memory.toml<\/code> na raiz:<\/p>\nworkspace = \"pessoal\"\nproject = \"site-linuxpro\"\n\n[briefing]\ninject_on_session_start = \"true\"\nmax_chars = 4000\n\n[capture]\nignore_paths = [\"private\/**\", \"~\/.ssh\/**\"]<\/code><\/pre>\nworkspace<\/code> e project<\/code> aceitam letras min\u00fasculas ASCII, d\u00edgitos, ponto, h\u00edfen e sublinhado. Um project<\/code> declarado no marcador continua tendo prioridade sobre o remote Git. A se\u00e7\u00e3o capture<\/code> evita registrar eventos reconhecidos de ferramentas de arquivo sob os caminhos indicados; n\u00e3o \u00e9 uma solu\u00e7\u00e3o completa de DLP para comandos de shell ou conte\u00fado que voc\u00ea mesmo escrever no prompt. Para m\u00e1xima cautela, instale os hooks em modo allowlist e coloque o marcador somente nos reposit\u00f3rios que devem ser capturados:<\/p>\nai-memory install-hooks --agent claude-code --hooks-dir \"$HOOKS_DIR\" --apply --capture-mode allowlist<\/code><\/pre>\nHooks n\u00e3o garantem escopo nas chamadas MCP<\/h3>\n
.ai-memory.toml<\/code> e passar os dois argumentos em toda opera\u00e7\u00e3o de projeto:<\/p>\n{\"workspace\": \"pessoal\", \"project\": \"site-linuxpro\"}<\/code><\/pre>\nmemory_message_send<\/code>, memory_message_pop<\/code> e memory_message_cancel<\/code> recusam escopo inferido sem v\u00ednculo \u00e0 sess\u00e3o; memory_message_list<\/code> informa como o escopo foi resolvido. A recusa evita atuar na caixa de outro projeto.<\/p>\nai-memory install-mcp --client claude-code --session-aware --apply<\/code>. Confira seu funcionamento antes de depender de sele\u00e7\u00e3o autom\u00e1tica. Para consultas globais, use global=true<\/code> sem mistur\u00e1-lo com workspace<\/code>, project<\/code> ou scopes<\/code>.<\/p>\nPerfil compartilhado: confira o que atravessa projetos<\/h3>\n
ai-memory profile status\nai-memory profile list\nai-memory profile review<\/code><\/pre>\n.ai-memory.toml<\/code>, sem apagar as configura\u00e7\u00f5es existentes:<\/p>\n[profile]\ncontribute = false\nconsume = false<\/code><\/pre>\nprofile rebuild<\/code> rel\u00ea a base, mas n\u00e3o remove entradas antigas nem reclassifica todos os candidatos j\u00e1 registrados. Revise as evid\u00eancias com profile review<\/code> e remova individualmente uma prefer\u00eancia incorreta com ai-memory profile forget CAMINHO_DA_ENTRADA<\/code>, usando o caminho exibido na listagem. N\u00e3o execute exclus\u00f5es em lote sem revisar. Mem\u00f3ria recuperada nunca autoriza comandos nem substitui suas instru\u00e7\u00f5es atuais.<\/p>\n[capture]<\/code>. Consulte a documenta\u00e7\u00e3o do perfil<\/a> para revisar, remover prefer\u00eancias e configurar o comportamento do servidor.<\/p>\nHandoff sem consumo autom\u00e1tico<\/h3>\n
[handoff]\nclaim_on_session_start = false\ncreate_on_session_end = false<\/code><\/pre>\nmemory_handoff_list<\/code> e aceitar o escolhido por ID. A segunda desliga a cria\u00e7\u00e3o autom\u00e1tica no encerramento de sess\u00f5es n\u00e3o gerenciadas; resumos e consolida\u00e7\u00e3o continuam. Handoffs expl\u00edcitos e execu\u00e7\u00f5es gerenciadas n\u00e3o s\u00e3o desativados. Ambas s\u00e3o op\u00e7\u00f5es globais do servidor e permanecem true<\/code> por padr\u00e3o.<\/p>\nConsultando a mem\u00f3ria e entregando contexto<\/h2>\n
# \u00datil principalmente ap\u00f3s uma sess\u00e3o do Codex:\nai-memory finalize-session\n\n# Diagn\u00f3stico e manuten\u00e7\u00e3o local\nai-memory status\nai-memory doctor\nai-memory lint<\/code><\/pre>\nAcesso remoto: n\u00e3o exponha a porta crua<\/h2>\n
allowed_hosts<\/code> e HTTPS por um proxy reverso antes de alterar o bind. Autentica\u00e7\u00e3o n\u00e3o cifra o tr\u00e1fego. O projeto mant\u00e9m um guia de proxy HTTPS<\/a> com exemplos para Caddy e Cloudflare Tunnel.<\/p>\nAtualiza\u00e7\u00f5es e recupera\u00e7\u00e3o<\/h2>\n
mkdir -p \"$HOME\/backups\/ai-memory\"\nai-memory backup --to \"$HOME\/backups\/ai-memory\/ai-memory-$(date +%Y%m%d-%H%M%S).tar.gz\"<\/code><\/pre>\nVER=2.6.3<\/code>. A 2.4.x n\u00e3o tinha upgrade<\/code>; o atualizador da 2.5.x podia recusar arquivos auxiliares do pacote oficial. A corre\u00e7\u00e3o desse segundo problema chegou na 2.6.0 \u2014 n\u00e3o est\u00e1 no bin\u00e1rio antigo que tenta atualizar.<\/p>\nai-memory upgrade --version 2.6.3\nsystemctl --user restart ai-memory.service\nsystemctl --user is-active ai-memory.service\nai-memory --version\nai-memory status<\/code><\/pre>\njournalctl --user -u ai-memory.service -n 80 --no-pager<\/code> e repita a consulta. O upgrade reaplica hooks registrados, mas clientes abertos precisam ser reiniciados.<\/p>\nHOOKS_DIR=\"$HOME\/.local\/share\/ai-memory\/release-2.6.3\/hooks\"\n# Exemplo ap\u00f3s download manual:\nai-memory install-hooks --agent codex --hooks-dir \"$HOOKS_DIR\" --apply\n# Se utiliza OpenCode:\n# ai-memory install-hooks --agent open-code --apply\n\n# Na raiz de cada projeto, renove instru\u00e7\u00f5es e skills gerenciadas:\nai-memory install-instructions --target AGENTS.md --skills-agent agents\n# Claude Code: --target CLAUDE.md --skills-agent claude-code\n\nsystemctl --user restart ai-memory.service\nai-memory doctor<\/code><\/pre>\n--project-strategy<\/code> mant\u00e9m a estrat\u00e9gia j\u00e1 registrada. Reinicie os clientes MCP, abra uma sess\u00e3o de teste e confira se captura e consulta usam o projeto correto. N\u00e3o basta verificar apenas ai-memory --version<\/code>.<\/p>\nsha256sum -c<\/code> e o execut\u00e1vel extra\u00eddo informou ai-memory 2.6.3<\/code>. A sintaxe dos principais subcomandos foi conferida pelo --help<\/code>. N\u00e3o houve atualiza\u00e7\u00e3o do servi\u00e7o desta esta\u00e7\u00e3o nem teste ponta a ponta de todos os clientes nesta revis\u00e3o editorial.<\/p>\nBackup da mem\u00f3ria n\u00e3o \u00e9 backup dos agentes<\/h3>\n
ai-memory backup<\/code> preserva a wiki e o estado SQLite, incluindo sess\u00f5es, observa\u00e7\u00f5es e handoffs. O comando abaixo cobre outro conjunto: configura\u00e7\u00f5es, skills, plugins e instru\u00e7\u00f5es dos agentes. Veja primeiro o plano e depois gere o arquivo:<\/p>\nai-memory backup-agents --dry-run --to \"$HOME\/backups\/ai-memory\/agentes.tar.gz\"\nai-memory backup-agents --to \"$HOME\/backups\/ai-memory\/agentes-$(date +%Y%m%d-%H%M%S).tar.gz\"<\/code><\/pre>\nai-memory restore --help<\/code> ou ai-memory restore-agents --help<\/code>, conforme o tipo de backup. Em migra\u00e7\u00f5es, guarde tamb\u00e9m a vers\u00e3o anterior do bin\u00e1rio; n\u00e3o tente fazer downgrade contra um banco j\u00e1 migrado sem um plano de restaura\u00e7\u00e3o.<\/p>\nCr\u00e9dito ao autor e licen\u00e7a<\/h2>\n