{"id":1457,"date":"2026-09-08T16:40:55","date_gmt":"2026-09-08T19:40:55","guid":{"rendered":"https:\/\/www.linuxpro.com.br\/2026\/09\/engram-memoria-persistente-para-agentes-no-linux\/"},"modified":"2026-09-08T17:05:11","modified_gmt":"2026-09-08T20:05:11","slug":"engram-memoria-persistente-para-agentes-no-linux","status":"publish","type":"post","link":"https:\/\/www.linuxpro.com.br\/en\/2026\/09\/engram-memoria-persistente-para-agentes-no-linux\/","title":{"rendered":"Engram: persistent memory for agents on Linux"},"content":{"rendered":"

\"Mascote<\/p>\n

O agente de terminal \u00e9 \u00f3timo at\u00e9 a sess\u00e3o acabar. Na seguinte, ele redescobre o mesmo bug, rel\u00ea o mesmo README e pergunta de novo se a API usa JWT. O Engram<\/a> \u00e9 um c\u00e9rebro local para isso: um bin\u00e1rio em Go<\/a>, um SQLite com FTS5 em ~\/.engram\/engram.db<\/code>, e o mesmo banco para Claude Code, Codex, Cursor, Grok e qualquer outro cliente MCP.<\/p>\n

<\/p>\n

N\u00e3o \u00e9 lixeira de transcript. O agente decide o que vale a pena lembrar \u2014 decis\u00e3o, bug, conven\u00e7\u00e3o \u2014 e grava com mem_save<\/code>. Na sess\u00e3o seguinte, mem_search<\/code> e mem_context<\/code> devolvem o peda\u00e7o certo. O mapa das alternativas (mnemo, Leteo, Subcog\u2026) est\u00e1 em Alternativas ao Claude-Mem em Go, Rust e C<\/a>; o mapa dos agentes no terminal, em Assistentes de IA no terminal Linux<\/a>. Este post \u00e9 o passo a passo do Engram no Linux: instalar, ligar nos agentes, acertar o nome do projeto e deixar o daemon no boot.<\/p>\n

O que \u00e9 \u2014 e o que n\u00e3o \u00e9<\/h2>\n

Engram (\/\u02c8en.\u0261r\u00e6m\/<\/code>, o tra\u00e7o f\u00edsico de uma mem\u00f3ria no c\u00e9rebro) \u00e9 um bin\u00e1rio Go com SQLite embutido via modernc.org\/sqlite<\/code> \u2014 puro Go, sem CGO, sem Node, sem Python, sem Docker para o uso di\u00e1rio. Licen\u00e7a MIT. A linha est\u00e1vel em julho de 2026 \u00e9 a v1.20.0<\/strong>.<\/p>\n

Quatro portas para o mesmo banco:<\/p>\n\n\n\n\n\n\n\n\n
Porta<\/th>\nComando<\/th>\nPara qu\u00ea<\/th>\n<\/tr>\n<\/thead>\n
MCP stdio<\/td>\nengram mcp --tools=agent<\/code><\/td>\nO agente fala com a mem\u00f3ria (Claude, Grok, Codex\u2026)<\/td>\n<\/tr>\n
CLI<\/td>\nengram search<\/code>, save<\/code>, context<\/code><\/td>\nVoc\u00ea consulta e grava na m\u00e3o<\/td>\n<\/tr>\n
TUI<\/td>\nengram tui<\/code><\/td>\nNavegar sess\u00f5es e observa\u00e7\u00f5es no terminal<\/td>\n<\/tr>\n
HTTP local<\/td>\nengram serve<\/code> (porta 7437)<\/td>\nAPI JSON. N\u00e3o<\/strong> \u00e9 p\u00e1gina de navegador<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

O dashboard HTML (\/dashboard<\/code>) \u00e9 o Engram Cloud<\/strong> \u2014 outro processo, Postgres, opcional. Sem Cloud, o visualizador local \u00e9 o TUI.<\/p>\n

A filosofia, expl\u00edcita no README: o agente j\u00e1 tem o LLM e o contexto. Em vez de capturar cada tool call e comprimir depois (o modelo do claude-mem), o Engram pede que o agente grave s\u00f3 o que dura. Resultado: busca FTS5 limpa, zero chamada extra de API, um arquivo que voc\u00ea controla.<\/p>\n

Instalar no Ubuntu\/Linux<\/h2>\n

N\u00e3o existe pacote apt<\/code> nem .deb<\/code> nas releases<\/a>. O que a documenta\u00e7\u00e3o de produ\u00e7\u00e3o pede \u00e9 o bin\u00e1rio. Um arquivo, zero runtime: sem Node, sem Python, sem Docker. A linha est\u00e1vel em julho de 2026 \u00e9 a v1.20.0<\/strong>.<\/p>\n

Os releases oferecem bin\u00e1rios Linux prontos para amd64<\/code> e arm64<\/code>. O execut\u00e1vel oficial \u00e9 estaticamente ligado, sem depend\u00eancias de runtime; escolha apenas o arquivo da arquitetura da m\u00e1quina. Para compilar do c\u00f3digo-fonte, o requisito \u00e9 Go 1.24+.<\/p>\n

Ubuntu amd64 e arm64<\/h3>\n
sudo apt-get update\nsudo apt-get install -y curl ca-certificates\n\nVER=1.20.0\ncase \"$(dpkg --print-architecture)\" in\n  amd64) FILE=engram_${VER}_linux_amd64.tar.gz ;;\n  arm64) FILE=engram_${VER}_linux_arm64.tar.gz ;;\n  *) echo \"sem bin\u00e1rio pronto para $(dpkg --print-architecture)\"; exit 1 ;;\nesac\n\ncd \/tmp\ncurl -fsSL -O \"https:\/\/github.com\/Gentleman-Programming\/engram\/releases\/download\/v${VER}\/${FILE}\"\ncurl -fsSL -O \"https:\/\/github.com\/Gentleman-Programming\/engram\/releases\/download\/v${VER}\/checksums.txt\"\nsha256sum -c checksums.txt --ignore-missing\n\nmkdir -p ~\/.local\/bin\ntar -xzf \"$FILE\" engram\ninstall -m 755 engram ~\/.local\/bin\/engram\n\n# o ~\/.profile do Ubuntu s\u00f3 acrescenta ~\/.local\/bin no pr\u00f3ximo login,\n# e s\u00f3 se o diret\u00f3rio j\u00e1 existir\nexport PATH=\"$HOME\/.local\/bin:$PATH\"\nhash -r\nengram version<\/code><\/pre>\n
A sa\u00edda esperada \u00e9 engram 1.20.0<\/code>. O tarball traz o execut\u00e1vel na raiz, mais README, LICENSE e CHANGELOG. Banco padr\u00e3o: ~\/.engram\/engram.db<\/code>.<\/p>\n
Para o PATH ficar permanente, abra um terminal novo depois da instala\u00e7\u00e3o. O ~\/.profile<\/code> padr\u00e3o do Ubuntu j\u00e1 tem o bloco if [ -d \"$HOME\/.local\/bin\" ]<\/code> \u2014 por isso o mkdir<\/code> vem antes do install<\/code>.<\/p>\n
go install<\/h3>\n
Se voc\u00ea j\u00e1 tem Go 1.24+ (o da documenta\u00e7\u00e3o). O pacote golang-go<\/code> do Ubuntu 24.04 \u00e9 1.22 e o do 22.04 \u00e9 1.18 \u2014 n\u00e3o d\u00e1 para go install<\/code> por a\u00ed; use o bin\u00e1rio da release ou instale o Go pelo site:<\/p>\n
go install github.com\/Gentleman-Programming\/engram\/cmd\/engram@latest\n# cai em $(go env GOPATH)\/bin \u2014 em geral ~\/go\/bin\/<\/code><\/pre>\n
go install<\/code> carimba a vers\u00e3o como dev<\/code>. Se quiser o git-describe no engram version<\/code>, clone e passe -ldflags<\/code> \u2014 um go install<\/code> e um go build<\/code> no mesmo PATH deixam dois bin\u00e1rios e a vers\u00e3o \u201cdev\u201d ganha. H\u00e1 uma linha v2 (github.com\/Gentleman-Programming\/engram\/v2\/cmd\/engram<\/code>) para release candidates; produ\u00e7\u00e3o continua na v1.<\/p>\n
Homebrew no Linux<\/h3>\n
brew install gentleman-programming\/tap\/engram<\/code><\/pre>\n
O tap cobre a linha est\u00e1vel v1.20.0. Upgrade: brew update && brew upgrade engram<\/code>. Trocar o bin\u00e1rio mata um engram serve<\/code> solto \u2014 por isso o servi\u00e7o systemd, mais abaixo.<\/p>\n
Primeiro contato<\/h2>\n
engram version\nengram stats\nengram projects list\nengram tui<\/code><\/pre>\n
Banco padr\u00e3o: ~\/.engram\/engram.db<\/code>. Override: ENGRAM_DATA_DIR<\/code>. No TUI, j<\/code>\/k<\/code> navega, Enter<\/code> abre, \/<\/code> busca, Esc<\/code> volta. Tema Catppuccin Mocha.<\/p>\n
A API local, se voc\u00ea subir o daemon:<\/p>\n
engram serve          # 127.0.0.1:7437\ncurl -s http:\/\/127.0.0.1:7437\/health\n# {\"service\":\"engram\",\"status\":\"ok\",\"version\":\"0.1.0\"}<\/code><\/pre>\n
\/<\/code> e \/dashboard<\/code> nessa porta devolvem 404. \u00c9 JSON, n\u00e3o site. GET \/project\/current<\/code> usa o cwd do processo do serve<\/strong> \u2014 no systemd com WorkingDirectory=%h<\/code>, isso vira o basename da home, n\u00e3o o repo em que voc\u00ea est\u00e1 editando.<\/p>\n
Ligar nos agentes<\/h2>\n
engram setup <agente><\/code> escreve o MCP no formato de cada cliente. N\u00e3o configura Cloud. Reinicie o agente depois.<\/p>\n\n\n\n\n\n\n\n\n\n\n\n
Agente<\/th>\nComando<\/th>\n<\/tr>\n<\/thead>\n
Claude Code<\/td>\nclaude plugin marketplace add Gentleman-Programming\/engram<\/code> e claude plugin install engram<\/code> \u2014 ou engram setup claude-code<\/code><\/td>\n<\/tr>\n
Codex<\/td>\nengram setup codex<\/code><\/td>\n<\/tr>\n
OpenCode<\/td>\nengram setup opencode<\/code><\/td>\n<\/tr>\n
Cursor<\/td>\nengram setup cursor<\/code><\/td>\n<\/tr>\n
Gemini CLI<\/td>\nengram setup gemini-cli<\/code><\/td>\n<\/tr>\n
VS Code Copilot<\/td>\nengram setup vscode-copilot<\/code><\/td>\n<\/tr>\n
Windsurf, Qwen, Kiro, Kilo, Pi, Antigravity<\/td>\nengram setup <nome><\/code> \u2014 lista em engram --help<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Perfis MCP: agent<\/code> (o conjunto que o agente usa no dia a dia), admin<\/code>, ou all<\/code>. O default do engram mcp<\/code> sem flag \u00e9 all<\/code>. Para o agente, use --tools=agent<\/code>.<\/p>\n
Grok Build (manual)<\/h3>\n
N\u00e3o h\u00e1 engram setup grok<\/code>. Em ~\/.grok\/config.toml<\/code>:<\/p>\n
[mcp_servers.engram]\ncommand = \"\/home\/SEU_USER\/.local\/bin\/engram\"\nargs = [\"mcp\", \"--tools=agent\"]\nenabled = true<\/code><\/pre>\n
Confira com grok mcp doctor engram<\/code> \u2014 handshake ok e as tools do perfil agent<\/code>. Recarregue a sess\u00e3o do Grok: o MCP s\u00f3 entra na que sobe depois<\/em> da config. O banco \u00e9 o mesmo do Claude. O nome do projeto<\/em>, n\u00e3o: cada processo detecta pelo pr\u00f3prio cwd.<\/p>\n
Qualquer cliente MCP<\/h3>\n
{\n  \"mcpServers\": {\n    \"engram\": {\n      \"command\": \"engram\",\n      \"args\": [\"mcp\", \"--tools=agent\"]\n    }\n  }\n}<\/code><\/pre>\n
O cliente dispara um processo stdio por sess\u00e3o. Isso n\u00e3o<\/em> substitui o engram serve<\/code> do systemd \u2014 s\u00e3o coisas diferentes. MCP l\u00ea e grava o SQLite direto; o serve \u00e9 a API HTTP (e o autosync Cloud, se voc\u00ea ligar).<\/p>\n
Como o Engram escolhe o projeto<\/h2>\n
Ele n\u00e3o indexa o path. Resolve um nome<\/strong> e filtra o SQLite por esse nome. Preced\u00eancia:<\/p>\n
    \n
  1. argumento expl\u00edcito (mem_context<\/code> com project<\/code>, engram context teste<\/code>);<\/li>\n
  2. override de processo (engram mcp --project \u2026<\/code> ou ENGRAM_PROJECT<\/code>);<\/li>\n
  3. detec\u00e7\u00e3o pelo cwd.<\/li>\n<\/ol>\n
    A detec\u00e7\u00e3o do diret\u00f3rio, em ordem:<\/p>\n\n\n\n\n\n\n\n\n\n\n
    #<\/th>\nsource<\/th>\nO que usa<\/th>\n<\/tr>\n<\/thead>\n
    0<\/td>\nconfig<\/code><\/td>\n.engram\/config.json<\/code> com project_name<\/code><\/td>\n<\/tr>\n
    1<\/td>\ngit_remote<\/code><\/td>\nrepo com origin<\/code> \u2014 nome do remote, gravado num binding privado do clone<\/td>\n<\/tr>\n
    2<\/td>\ngit_root<\/code><\/td>\ngit sem origin \u2014 basename da raiz<\/td>\n<\/tr>\n
    3<\/td>\ngit_child<\/code><\/td>\ncwd tem exatamente um filho git \u2014 promove esse<\/td>\n<\/tr>\n
    4<\/td>\nambiguous<\/code><\/td>\nv\u00e1rios filhos git \u2014 n\u00e3o escolhe sozinho<\/td>\n<\/tr>\n
    5<\/td>\ndir_basename<\/code><\/td>\n\u00faltimo recurso: filepath.Base(cwd)<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Pasta sem git vira o basename. Claude gravando em \/home\/voc\u00ea\/teste<\/code> e Grok em \u2026\/site-linuxpro<\/code> s\u00e3o dois projetos. A mem\u00f3ria n\u00e3o aparece \u201cdo outro lado\u201d at\u00e9 voc\u00ea buscar com o nome certo ou all_projects=true<\/code>.<\/p>\n
    Lock est\u00e1vel na raiz do repo:<\/p>\n
    {\n  \"project_name\": \"site-linuxpro\"\n}<\/code><\/pre>\n
    O Engram usa o config mais pr\u00f3ximo<\/strong> abaixo da raiz git \u2014 d\u00e1 para ter backend\/.engram\/config.json<\/code> e frontend\/.engram\/config.json<\/code> no monorepo. Fora de git, s\u00f3 vale o config do diret\u00f3rio atual: ~\/.engram\/config.json<\/code> n\u00e3o<\/em> vaza para os filhos. Primeira chamada \u00fatil de qualquer sess\u00e3o: mem_current_project<\/code> \u2014 devolve project<\/code>, project_source<\/code> e, se for o caso, available_projects<\/code>.<\/p>\n
    Se a escrita voltar ambiguous_project<\/code>, o agente n\u00e3o pode chutar. Voc\u00ea escolhe um nome da lista e a tool retenta com project_choice_reason=user_selected_after_ambiguous_project<\/code>.<\/p>\n
    Subir o serve no boot<\/h2>\n
    Esta se\u00e7\u00e3o \u00e9 opcional. Claude Code, Codex e os demais clientes MCP via stdio usam engram mcp<\/code> e n\u00e3o precisam de engram serve<\/code>. Suba o servi\u00e7o se precisar da API HTTP local, do autosync do Cloud ou de integra\u00e7\u00f5es HTTP, como OpenCode e Pi.<\/p>\n
    Quando ele for necess\u00e1rio, um supervisor evita que engram serve<\/code> morra no reboot ou durante a troca do bin\u00e1rio.<\/p>\n
    Unit de usu\u00e1rio, no template oficial:<\/p>\n
    # ~\/.config\/systemd\/user\/engram.service\n[Unit]\nDescription=Engram Memory Server\nAfter=network.target\n\n[Service]\nWorkingDirectory=%h\nExecStart=%h\/.local\/bin\/engram serve\nRestart=always\nRestartSec=3\nEnvironment=ENGRAM_DATA_DIR=%h\/.engram\nStandardOutput=journal\nStandardError=journal\n\n[Install]\nWantedBy=default.target<\/code><\/pre>\n
    mkdir -p ~\/.engram ~\/.config\/systemd\/user\nsystemctl --user daemon-reload\nsystemctl --user enable --now engram.service\ncurl -s http:\/\/127.0.0.1:7437\/health\njournalctl --user -u engram -f<\/code><\/pre>\n
    enable<\/code> amarra no login. Para subir no boot sem<\/em> sess\u00e3o gr\u00e1fica, o usu\u00e1rio precisa de linger:<\/p>\n
    loginctl enable-linger \"$USER\"\nloginctl show-user \"$USER\" -p Linger<\/code><\/pre>\n
    Se a 7437 j\u00e1 estiver ocupada por um serve \u00f3rf\u00e3o, a unit falha no bind. Mate o processo antigo (ss -tlnp | grep 7437<\/code>) e systemctl --user restart engram<\/code>.<\/p>\n
    O contrato de mem\u00f3ria<\/h2>\n
    O README trata o Engram como mem\u00f3ria curada, n\u00e3o como dump. O ciclo:<\/p>\n
      \n
    1. Orientar<\/strong> \u2014 mem_current_project<\/code>, depois mem_context<\/code> \/ mem_search<\/code>.<\/li>\n
    2. Buscar antes de repetir<\/strong> \u2014 decis\u00e3o, bug, conven\u00e7\u00e3o que j\u00e1 podem estar no banco.<\/li>\n
    3. Revelar por camadas<\/strong> \u2014 mem_search<\/code> devolve preview (~300 caracteres); mem_get_observation<\/code> traz o texto inteiro; mem_timeline<\/code> mostra o antes\/depois na sess\u00e3o.<\/li>\n
    4. Gravar o que dura<\/strong> \u2014 mem_save<\/code> com t\u00edtulo curto, tipo (decision<\/code>, bugfix<\/code>, config<\/code>, architecture<\/code>\u2026) e corpo What \/ Why \/ Where \/ Learned. N\u00e3o grave sa\u00edda crua de ferramenta.<\/li>\n
    5. Assunto que evolui<\/strong> \u2014 topic_key<\/code> est\u00e1vel (architecture\/auth-model<\/code>). Mesmo projeto + scope + topic vira upsert, n\u00e3o uma linha nova.<\/li>\n
    6. Fechar a sess\u00e3o<\/strong> \u2014 mem_session_summary<\/code> com Goal, Discoveries, Accomplished, Next Steps, Files.<\/li>\n<\/ol>\n
      Scope: project<\/code> (default), personal<\/code> ou global<\/code>. Um personal<\/code> no mesmo topic_key<\/code> n\u00e3o sobrescreve o de projeto.<\/p>\n
      O que n\u00e3o<\/em> vai para o SQLite: senha, token, dump de journalctl<\/code>. O git continua sendo o registro \u2014 a hist\u00f3ria est\u00e1 em A hist\u00f3ria do Git<\/a>. Tags <private><\/code> s\u00e3o removidas em duas camadas no Engram; mesmo assim, n\u00e3o grave o que n\u00e3o pode vazar.<\/p>\n
      Cloud e dashboard no navegador<\/h2>\n
      O Cloud \u00e9 replica\u00e7\u00e3o opcional + UI. SQLite local continua autoritativo. Caminho smoke com Docker, no clone do reposit\u00f3rio:<\/p>\n
      docker compose -f docker-compose.cloud.yml up -d\nengram cloud config --server http:\/\/127.0.0.1:18080\nengram cloud enroll meu-projeto\nengram sync --cloud --project meu-projeto<\/code><\/pre>\n
      Dashboard local: http:\/\/127.0.0.1:18080\/dashboard<\/code>. No compose smoke, \/dashboard\/login<\/code> redireciona sem pedir token. Rotas \u00fateis: \/dashboard\/browser<\/code>, \/dashboard\/projects<\/code>, \/dashboard\/activity<\/code>.<\/p>\n
      Para o dia a dia num laptop, Cloud \u00e9 extra. TUI + MCP bastam.<\/p>\n
      Dicas que evitam dor<\/h2>\n