amem

Memória de Agente Local Sem Docker: amem + MCP (fatos permanecem em ~/.amem)

Documentação

amem

Memória pessoal do agente que fica na sua máquina.

Agentes de codificação esquecem entre sessões. Eles pesquisam novamente a mesma árvore, reaprendem as mesmas restrições e gastam tokens redescobrindo decisões pelas quais você já pagou uma vez.

amem dá ao Cursor, Claude Code e outros hosts locais uma memória privada e pesquisável de fatos duráveis sobre seus repositórios — o que é dono do quê, quais arquivos importam, o que quebrou da última vez — para que a próxima sessão comece orientada em vez de fria.

amem context "sync auth startup"

# Agent Memory Context

## Best Claims
### claim.sync_auth_mode_startup
Kind: `constraint`
Why: `keyword+8`, `fts+18.0`, `embed+6.3`, `kind:constraint`, `fresh`

The sync service checks auth mode during startup before enabling Drive sync.
Anchors: `src/background/sync-service.ts`

Nada é enviado. Nada é escrito no histórico git do seu produto. A memória vive sob ~/.amem/ apenas no seu laptop.

Por que o amem existe

Sem amem	Com amem
O agente explora amplamente a cada sessão	O agente consulta a memória primeiro, depois verifica os arquivos certos
Decisões vivem no histórico do chat	Decisões se tornam afirmações estruturadas com âncoras de arquivo
Pressão de compartilhamento de equipe em documentos de "contexto de IA"	Explicitamente pessoal — seus prompts e aprendizados ficam locais
`AGENTS.md` plano que fica desatualizado	Grafo pequeno: componentes → fluxos → afirmações, atualizado via propostas

amem não é uma wiki corporativa compartilhada e não é um produto de RAG em nuvem. É uma ferramenta local para desenvolvedores individuais que querem agentes que lembram do seu trabalho.

Privacidade (innegociável)

Peça	Localização	Compartilhado?
A ferramenta amem (este repositório)	GitHub / npm	Sim — instalável
Seu banco de dados de memória	`~/.amem/graph.db` (ou `.enc` quando bloqueado)	Não
Regra de projeto do Cursor	`.cursor/rules/amem.mdc` no repositório do produto	Seguro para commitar — apenas orientação, sem conteúdo de memória
Exportações / backups que você cria	Onde você os escrever	Mantenha privado — não commite

Garantias:

~/.amem é criado com modo 0700
UI local vincula-se apenas a 127.0.0.1
A memória nunca sai da máquina — sem sincronização gerenciada, sem modo "compartilhar com a organização"
Ping anônimo de instalação opcional apenas (veja Telemetria); desative a qualquer momento
Agentes são instruídos a armazenar fatos do repositório, não estratégia proprietária de prompting
Bloqueio AES-256-GCM opcional e backups locais criptografados — ainda sem nuvem

Requisitos

Node.js 20+ (better-sqlite3 nativo)
git (identidade do repositório usa URL remota / caminho raiz)

Instale a ferramenta

npx @iamem/amem setup   # Node 20+ — installs the `amem` CLI
# or
npm i -g @iamem/amem && amem setup

De um clone durante o desenvolvimento:

git clone https://github.com/sslugic/amem.git
cd amem
npm install
npm link
amem setup

Veja docs/npm-release.md. CI executa npm test e npm run pack:check. better-sqlite3 usa seus próprios prebuilds — sem etapa nativa extra em macOS/Linux comuns + Node 20/22.

Se npm install falhar ao compilar código nativo, instale Xcode CLT (macOS) ou build-essential (Linux) e tente novamente, ou use um binário oficial Node 20/22 que corresponda à matriz de prebuilds.

Telemetria

Em npm install / npx (fora de CI e testes), o amem pode enviar um único POST anônimo para https://getamem.com/api/beacon/npm-install com:

nome e versão do pacote
versão do Node.js
plataforma do SO e arquitetura da CPU

Nenhum código, caminhos, nomes de usuário, e-mails, IPs ou conteúdo de memória são incluídos. Desative:

AMEM_TELEMETRY_DISABLED=1 npm i -g @iamem/amem

A memória sob ~/.amem ainda nunca sai da sua máquina.

Caminhos rápidos

# Cursor or Claude Code in a git repo
amem init --platform cursor    # or: claude

# Other hosts (thin installers, same local DB)
amem init --platform windsurf|continue|aider|zed|claude-desktop

# Any other MCP client — binds the repo and prints the endpoint to paste
amem init --platform codex|copilot|gemini|cline|roo|jetbrains|opencode|goose|…
amem platforms                  # every id amem accepts (aliases included)

# Cross-repo “how I work” prefs (blended into project context)
amem init --personal
# or: amem setup --personal

Criptografia em repouso + backups locais

amem lock --passphrase '…'       # or AMEM_PASSPHRASE
amem unlock --passphrase '…'
amem backup --passphrase '…'     # ~/.amem/backups by default
amem backup schedule             # daily local timer (no cloud)
amem backup unschedule

Enquanto bloqueado, defina AMEM_PASSPHRASE (ou desbloqueie) antes de qualquer comando que abra o banco de dados.

Embeddings e o resto do kit de ferramentas

Tudo é gratuito. Não há níveis e nada é retido — embeddings locais, higiene de memória e sua programação, sincronização de regras e o pacote de atestação estão todos incluídos.

amem embed use ngram                     # local n-gram model, or `external` for your own command
amem embed reindex
amem restore --file ~/.amem/backups/amem-….db.enc
amem hygiene
amem rules sync
amem it-pack --out ~/.amem/it-pack
amem doctor --attest

O embedder vem como um modelo de hash por padrão (sem download); ngram e external (texto stdin → vetor JSON) também são locais. Ainda sem API de embed em nuvem, e nada é enviado.

Checkout + entrega por e-mail é um processo de vendedor separado (npm run shop) que não é publicado com o CLI. Ele pode colocar na lista de permissões nomes do Mailtrap e Stripe de outro projeto .env — veja shop/README.md.

Ensinando cada cliente a usar o amem

Conectar um host ao endpoint MCP diz a ele que o amem existe; não diz a ele para verificar o quadro de tarefas ou consultar a memória antes de explorar. amem init e amem setup agora escrevem instruções em qualquer arquivo que o host realmente lê, e um comando cobre todo o resto:

amem instructions                 # the client(s) bound to this repo
amem instructions --all           # every supported client
amem instructions --check         # CI-friendly: exits 1 if missing or stale
amem instructions --platform roo  # just one

Um texto canônico (src/instructions.ts) é renderizado por host, para que a orientação não se desvie entre clientes:

Arquivo	Clientes
`.cursor/rules/amem.mdc`	Cursor
`CLAUDE.md`	Claude Code
`AGENTS.md`	Codex, Grok, OpenCode, Crush, Amp, Qwen, Droid, OpenHands, Warp, Zed, Cody, Antigravity, Neovim, Claude Desktop, Devin, Jules
`GEMINI.md`	Gemini CLI
`.github/copilot-instructions.md`	GitHub Copilot
`.windsurf/rules/amem.md` · `.continue/rules/amem.md` · `.clinerules/amem.md` · `.roo/rules/amem.md` · `.kilocode/rules/amem.md` · `.augment/rules/amem.md` · `.kiro/steering/amem.md` · `.trae/rules/amem.md` · `.amazonq/rules/amem.md`	Windsurf, Continue, Cline, Roo, Kilo, Augment, Kiro, Trae, Amazon Q
`.junie/guidelines.md` · `.goosehints` · `.aider.amem.md`	Junie, Goose, Aider

Hosts que compartilham um arquivo são escritos uma vez, então --all produz 17 arquivos, não 30. Arquivos compartilhados (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md) recebem um bloco marcado que é substituído no lugar — qualquer coisa que você escreveu ao redor sobrevive:

# My Project
Use pnpm, not npm.

<!-- BEGIN amem (generated) -->
…
<!-- END amem -->

Aider não tem MCP, então recebe comandos CLI em vez de nomes de ferramentas. Cada arquivo é apenas orientação — sem conteúdo de memória — e seguro para commitar. amem doctor avisa quando as instruções de um cliente vinculado estão ausentes ou desatualizadas.

Memória que se auto-cuida

A memória apodrece se nada a aposenta. O amem limpa em uma programação em vez de esperar ser solicitado:

amem hygiene schedule          # daily; amem doctor warns when it is not installed

Cada execução faz um backup de segurança e, então, por repositório:

Sinal	O que significa	Ação
Não-fato	Enchimento de chat armazenado como afirmação	Excluído (retido se exceder 25% do repositório — uma heurística que corresponde à maior parte de um corpus é uma heurística quebrada)
Âncora podre	Todo arquivo para o qual a afirmação aponta sumiu	Decaído. Âncoras de tag e workspaces sem fonte são isentos
Inútil	Atestado 3+ vezes e nunca respondeu à pergunta	Decaído
Não usado	Não retornado e não tocado dentro da janela	Decaído
Quase-duplicado	Mesmo conteúdo, âncoras sobrepostas	Mesclado

Uma afirmação só é aposentada com evidência positiva. Atestação ausente nunca conta contra ela — caso contrário, enviar isso decairia tudo de uma vez. Afirmações fixadas nunca decaem.

Economia que você pode verificar

amem context registra o que entregou; o agente (ou o hook de parada, do transcript do host) registra o que ainda precisou abrir. A economia é então calculada a partir do tamanho real dos arquivos que foram evitados:

saved = Σ(measured tokens of anchors returned but not opened) − packet_tokens

Nada pede a um modelo para estimar seu próprio valor, e um pacote que não evitou nada relata uma perda. O painel diz modelled até 30 eventos serem atestados, então muda para measured e corrige o total pela proporção observada.

amem usage attest --opened "src/db.ts"   # or let the stop hook do it
amem usage recompute --scope all --apply # re-measure historical events

Configuração inicial (recomendada)

amem ui

Isso abre http://127.0.0.1:7843 na aba Configuração. Ele escaneia sua pasta pessoal em busca de repositórios git (pula Library, node_modules, Downloads e ruído similar). Marque os que você quer, escolha clientes (Cursor, Claude Code, Windsurf, Continue, Aider, Zed, …), então Começar a rastrear selecionados. Cada escolha é vinculada em ~/.amem e recebe o instalador correspondente quando disponível.

Prefere uma janela de desktop em vez de uma aba do navegador (mesmo servidor localhost, mesma privacidade):

# once per machine/checkout (downloads Electron — not included in npm i -g)
npm run app:setup

amem app

amem ui continua abrindo o navegador; amem app abre Electron. Ambos falam apenas com 127.0.0.1. Se o servidor de UI já estiver em execução, amem app se anexa a ele. Instalações globais: execute npm run app:setup do diretório do pacote (ou clone), então amem app.

O cabeçalho tem um alternador Pessoal (preferências entre repositórios) e cromo Bloquear / backup — status de bloqueio, último backup e uma programação local diária. A memória mostra os mesmos chips de bloqueio/backup. A aba Configuração inclui um contrato de lembrete copiável para qualquer host MCP (amem recipe).

Opcional: marque Iniciar amem ui quando este computador fizer login para que o servidor localhost volte após uma reinicialização:

amem service install    # macOS LaunchAgent, Linux systemd --user, or Windows Startup
amem service status
amem service uninstall

Abas após a configuração:

Configuração — escanear/selecionar repositórios, plataformas, auto-início no login, proposta de bootstrap
Memória — fatos por arquivo, rascunhos pontuados (aprovar / substituir mais antigo / dispensar / rejeitar ruído), editar/fixar/excluir, pesquisar, acertos/erros recentes
Tarefas — Kanban por projeto para trabalho adiado do agente (Backlog → Próximo → Fazendo → Bloqueado → Concluído). MCP: amem_task_add / amem_task_update / amem_task_complete. Tarefas abertas aparecem em amem_context. Use Memória para fatos duráveis; Tarefas para "fazer depois".
Estatísticas — tokens estimados economizados por LLM, além de exportação JSON / markdown / PDF (proxies, não uma conta)

Somente servidor (sem navegador aberto):

amem ui --port 7843 --no-open

Para escanear pastas extras (ou apenas um subconjunto), defina AMEM_SCAN_ROOTS para uma lista de diretórios separada por dois-pontos.

Alternativa CLI (sem UI)

cd ~/path/to/your-real-project
amem init --platform cursor    # or: --platform claude
amem doctor
amem status

Para conectar ambos os agentes à mesma memória local, execute init uma vez por plataforma (ou selecione ambos na UI).

Loop do dia a dia

1. Consultar antes de explorar

amem context "billing webhook retry"

Ou deixe o agente fazer isso — Cursor recebe uma regra de projeto sempre ativa; Claude recebe orientação de hook. Ambos instalam as skills:

amem-bootstrap — semear memória de linha de base
amem-update-working-memory — salvar aprendizados duráveis após uma sessão

Hooks também injetam contexto no início da sessão / envio de prompt, armazenam notas de conversa, enfileiram rascunhos de fim de sessão e podem enfileirar rascunhos erro→aprendizado após buscas de contexto vazio quando o agente cita arquivos reais depois. Aprove rascunhos em Memória (ou permita tipos de baixo risco via política auto_apply_kinds).

2. Trabalhe normalmente

Trate a memória como um mapa, não como fonte da verdade. Leia os arquivos ancorados antes de alterá-los. Prefira afirmações marcadas como frescas; verifique as desatualizadas (arquivos ancorados alterados após a afirmação).

3. Salve o que deve sobreviver

Peça ao agente para executar amem-update-working-memory, aprove rascunhos de Memória ou aplique uma proposta você mesmo:

amem propose validate /tmp/memory.json
amem propose diff /tmp/memory.json
amem propose apply /tmp/memory.json

4. Instalação opcional de uma vez pelo agente

De dentro do repositório do produto, cole docs/agent-install-prompt.md no Cursor ou Claude Code e deixe-o executar a configuração para você.

O que é armazenado

A memória é um pequeno grafo local em SQLite:

Objeto	Significado
Componente	Um subsistema / módulo (`component.api`)
Fluxo	Como o trabalho se move (`flow.checkout`)
Afirmação	Um fato durável com âncoras de arquivo (pode ser `active` ou `superseded`; fixação opcional)
Borda	Links (afirmação → fluxo → componente); `kind: "supersedes"` arquiva a afirmação alvo
Rascunho	Propostas pendentes de sessão / erro→aprendizado aguardando aprovação em Memória
Tarefa	Trabalho adiado no Kanban do projeto (Backlog / Próximo / Fazendo / Bloqueado / Concluído) — não é um fato durável
Skill	Um procedimento reutilizável de várias etapas, armazenado como um arquivo `SKILL.md` (veja abaixo)
Evento de uso	Cada acerto de `amem context` + estimativa de tokens

Afirmações são a unidade de recuperação. A classificação combina:

SQLite FTS5 (stemming de Porter) + pontuação de palavras-chave
Embeddings de hash no dispositivo (sem download de modelo)
Impulso de fixação, pesos de tipo (constraint / gotcha > session), frescor
Afirmações de preferências pessoais opcionais misturadas ao contexto do projeto

Cada afirmação injetada inclui uma linha Porquê:. Afirmações desatualizadas (âncoras alteradas após updated_at) são rebaixadas.

Exemplo de afirmação:

{
  "id": "claim.webhook_idempotency",
  "kind": "constraint",
  "text": "Stripe webhooks must be idempotent on event.id before mutating invoices.",
  "code_anchors": ["src/webhooks/stripe.ts"],
  "supersedes": ["claim.webhook_old_rule"]
}

supersedes (ou uma borda com kind: "supersedes") marca ids de afirmações mais antigas como arquivados para que saiam da recuperação.

Skills (memória procedural)

Claims respondem o que é verdade. Skills respondem como fazemos isso aqui — uma sequência de deploy, uma dança de migração, um caminho de depuração que alguém já percorreu. Elas são longas demais para ficarem em todo prompt, então são carregadas sob demanda.

Skills vivem como arquivos SKILL.md em ~/.amem/skills/, indexados em SQLite para ranqueamento:

~/.amem/skills/deploy-staging/SKILL.md
~/.amem/skills/deploy-staging/references/runbook.md

Divulgação progressiva. Um pacote de contexto carrega apenas nomes e descrições. O agente chama amem_skill_view para puxar o corpo assim que decide que o procedimento se aplica, então uma biblioteca de skills não utilizada custa quase zero tokens.

O ciclo de aprendizado. O amem não acompanha modelo, então nunca escreve uma skill por conta própria. Ao final da sessão, ele procura o formato de um procedimento conquistado com esforço — etapas enumeradas ou comandos reais, além de um erro do qual se recuperou ou uma correção que você deu. Quando vários sinais se alinham, ele enfileira uma sugestão, que chega ao seu agente como um lembrete no próximo pacote de contexto. O agente escreve a skill; você aprova. Se uma skill foi carregada durante uma sessão que ainda assim deu errado, o amem enfileira uma revisão em vez de uma duplicata.

A barra é deliberadamente alta, e uma sessão pode enfileirar no máximo uma sugestão.

amem skills list                # index of what is stored
amem skills show deploy-staging # full body
amem skills new deploy-staging --desc "Deploy staging and verify health"
amem skills import ./some-skill # bring in an agentskills.io skill
amem skills drafts              # pending suggestions and staged writes
amem skills approve <draft-id>

Skills também aparecem em uma aba Skills em amem ui.

Segurança. Skills são instruções que um agente seguirá, então o conteúdo é verificado em busca de credenciais e padrões de injeção de prompt antes de qualquer gravação. Três chaves de política controlam isso:

Chave	Padrão	Efeito
`skills_enabled`	`true`	Interruptor mestre para armazenamento, ranqueamento e injeção
`skill_write_approval`	`false`	Coloca gravações do agente em revisão em vez de gravar em disco
`skill_capture`	`true`	Permite sugestões de skills ao final da sessão

Um policy.toml ilegível força skill_write_approval a ficar ativo. amem doctor --attest relata cada skill instalada com um hash de conteúdo, para que você possa comparar o que os agentes estão sendo instruídos a fazer.

Os backups atualmente copiam apenas o banco de dados — ~/.amem/skills/ ainda não está incluído. Mantenha skills importantes sob controle de versão até que isso seja implementado.

Economia de tokens (estimativas)

Cada amem context registra um evento de uso. A aba Stats da interface divide isso por plataforma (cursor, claude, …).

Estimativa automática:

estimated_avoided = max(0, anchors×4000 + claims×200 − packet_tokens)

Isso é um proxy para exploração evitada — não sua fatura da Cursor/Anthropic. Dinheiro usa o mesmo proxy de tokens a US$ 3 por 1M de tokens de entrada (entrada classe Sonnet). O uso incluído da Cursor e tokens de saída não são cobrados dessa forma, então trate $ como uma estimativa de ordem de grandeza.

Tempo economizado é um proxy separado: cada âncora de arquivo retornada é tratada como ~1,2s de ida e volta de ferramenta que o agente não precisou fazer. O tempo de consulta local é medido (SQLite em localhost). Taxa de acerto é correspondência de palavras-chave em amem context — não chamadas de API da Cursor/modelo (essas ainda acontecem). Um erro significa que nenhum fato armazenado correspondeu à consulta; fatos mais recentes ainda podem ser injetados como um fallback fraco, e o agente ainda fala com o modelo.

As estatísticas também mostram uma projeção mensal: últimos 7 dias de chamadas (ou menos se você acabou de começar), escalados para 30 dias. Ainda é um proxy, não uma fatura.

Se você souber depois um número melhor:

amem usage report --platform cursor --saved 12000
# or attach to a specific event:
amem usage report --event-id usage_… --saved 12000

Clientes de LLM (além de repositórios git)

O amem pode vincular um workspace nomeado que não é um checkout git — para Luna Client ou qualquer ferramenta que fale com Cursor/Claude/outros modelos.

amem init --workspace my-app
# seeds starter facts and runs a context check automatically

Anexe qualquer cliente de LLM você mesmo (HTTP ou MCP). Mantenha amem ui em execução para HTTP. No cliente, antes de cada chamada de modelo:

const res = await fetch("http://127.0.0.1:7843/api/context", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    workspace: "my-app",
    query: userMessage,
    platform: "app",
    sessionId,
  }),
});
const { markdown } = await res.json();
// prepend markdown to the prompt / tool result so the model skips a large retrieve

Após um resultado durável:

await fetch("http://127.0.0.1:7843/api/remember", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    workspace: "my-app",
    text: takeaway,
    kind: "session",
    anchors: ["my-app"],
  }),
});

Configuração MCP (qualquer host MCP):

Mantenha amem ui em execução (ou amem service install para que inicie no login). Aplicativos GUI muitas vezes não conseguem encontrar amem em PATH, o que aparece como "live tool discovery failed" / MCP error — não um prompt de login. Prefira HTTP:

{
  "mcpServers": {
    "amem": {
      "url": "http://127.0.0.1:7843/mcp?workspace=my-app"
    }
  }
}

Stdio também funciona se o host puder iniciar o binário. Imprima uma configuração com caminhos absolutos:

amem mcp --print-config --workspace my-app

Mesmo banco de dados localhost da memória de repositório git. O alternador da interface agrupa Git repos e Workspaces. Renomeie o nome de exibição de um workspace a qualquer momento — o slug MCP (workspace=luna-ai) e as claims armazenadas permanecem no mesmo id.

amem rename "Luna Client" --workspace luna-ai

Ferramentas MCP (stdio ou HTTP):

Ferramenta	Quando usar
`amem_context`	Pacote de memória ranqueado para a pergunta atual
`amem_remember`	Armazena um fato durável após um resultado
`amem_recipe`	Contrato genérico de leitura-gravação (qualquer host MCP)
`amem_skill_list`	Índice barato de procedimentos armazenados (apenas nomes + descrições)
`amem_skill_view`	Carrega o corpo de uma skill, depois que o índice diz que ela se aplica
`amem_skill_save`	Armazena um procedimento de várias etapas que você acabou de descobrir
`amem_repos`	O que é monitorado (repositórios git + workspaces nomeados)
`amem_stats`	Tempo de consulta, tokens/ms estimados economizados, taxa de acerto
`amem_graph`	Claims / componentes / fluxos armazenados para um workspace ou repositório
`amem_status`	Vinculação + contagens; omita workspace para uma visão geral da máquina

Referência de comandos

amem setup [--personal] [--platform <host>]
amem init --platform <client>      # amem platforms lists every id
amem platforms [--json]
amem init --workspace <name> [--path <dir>] [--platform …]
amem init --personal
amem rename "<display name>" --workspace <slug>
amem status [--workspace <name>]
amem doctor [--attest] [--json]
amem context "<query>" [--workspace <name>] [--platform …]
amem remember "<text>" [--workspace <name>] [--kind …] [--anchor <path>]
amem recipe [--json]
amem skills list|show <name>|new <name> [--desc <text>]|rm <name>|sync|import <path>
amem skills drafts|approve <draft-id>|dismiss <draft-id>
amem mcp [--print-config] [--workspace <name>]
amem propose validate|diff|apply <file.json>
amem export [--out <file.json>]
amem wipe --yes
amem wipe --all --yes
amem lock|unlock --passphrase <secret>
amem backup [--out <dir>] [--passphrase <secret>] [--label <name>]
amem backup schedule [--out <dir>] [--hour <0-23>]
amem backup unschedule
amem session touch --platform cursor|claude [--session-id <id>]
amem hook
amem usage report --saved <n> [--platform …] [--event-id …]
amem usage export [--format json|md|pdf] [--days 30] [--scope current|all] [--out <file>]
amem license status|apply|activate|clear|issue|keys
amem embed status|use hash|use ngram|reindex
amem ui [--port 7843] [--no-open]
amem app [--port 7843]
amem service install|uninstall|status

Comando	Finalidade
`setup`	Workspace pessoal único + instalação opcional de host
`init`	Vincula um repositório git, workspace nomeado, preferências pessoais ou host
`rename`	Altera o nome de exibição de um workspace; slug MCP e memória permanecem vinculados
`context`	Recupera um pacote Markdown; registra uso
`remember`	Armazena um fato local
`mcp`	Ferramentas MCP stdio; MCP HTTP em `http://127.0.0.1:7843/mcp` enquanto a interface está em execução
`skills`	Gerencia memória procedural (`list`, `show`, `new`, `import`, `drafts`, `approve`)
`propose diff`	Pré-visualiza alterações de claim/componente/fluxo antes de aplicar
`propose apply`	Faz upsert de memória estruturada localmente
`lock` / `unlock`	Criptografia opcional em repouso AES-256-GCM para `graph.db`
`backup`	Snapshot local (opcionalmente criptografado); `schedule` para timer diário
`ui`	Assistente de configuração + Memory + Stats no navegador (localhost)
`app`	Mesma interface em uma janela Electron (`npm run app:setup` uma vez)
`service`	Item de login para que `amem ui` inicie após reinicialização
`doctor --attest`	Atestado de privacidade/política para chamados de TI
`export` / `wipe`	Backup pessoal ou exclusão (ainda local)
`wipe --all --yes`	Desligamento: apaga todos os repositórios e remove `~/.amem`

O que a instalação coloca onde

Cursor

Artefato	Caminho
Skills	`~/.cursor/skills/amem-*`
Regra de projeto	`.cursor/rules/amem.mdc` (no repositório do produto)
Hooks	`~/.cursor/hooks.json`

Recarregue o Cursor se skills/regras não aparecerem imediatamente.

Claude Code

Artefato	Caminho
Skills	`~/.claude/skills/amem-*`
Hooks	`~/.claude/settings.json` (`UserPromptSubmit` / `Stop` / relacionados → `amem hook` completo)

Outros hosts

Host	O que o amem grava
Windsurf	Entrada MCP `~/.codeium/windsurf/mcp_config.json`
Continue	Servidores MCP `~/.continue/config.json`
Aider	Dicas de CLI `.aider.amem.md` no repositório
Zed	Dica `settings.json` `context_servers` / HTTP
Claude Desktop	Entrada MCP stdio `claude_desktop_config.json`

Todos os outros clientes em amem platforms — Codex, Copilot, Gemini CLI, Grok, Cline, Roo, Kilo, Cody, Augment, JetBrains, Kiro, Trae, Antigravity, Neovim, OpenCode, Goose, Crush, Amp, Qwen Code, Factory Droid, OpenHands, Amazon Q, Warp, Devin, Jules — não têm instalador local: amem init --platform <id> vincula o repositório e imprime o endpoint MCP para colar (amem recipe para a configuração completa).

Os ids de clientes são dobrados por alias, então claude-code, vscode, pycharm e chatgpt resolvem para claude, copilot, jetbrains e codex em vez de disparar policy.allowed_platforms.

FAQ de Segurança e Arquitetura

Como o amem evita envenenamento de ferramentas e injeção de prompt?

Ferramentas de memória sem restrições que gravam cegamente transcrições de chat são vulneráveis a armazenar resíduos conversacionais, instruções adversárias ou contexto envenenado. O amem aplica múltiplas barreiras defensivas:

Filtragem de sintaxe Fato vs. Ruído (isFactLike): Frases de transcrição, perguntas, gentilezas de chat e fragmentos de prompt do usuário são rejeitados automaticamente antes de se tornarem claims, mesmo que mencionem caminhos de arquivo reais.
Listas de negação de segredos integradas e personalizadas (BUILTIN_DENY_CLAIM_PATTERNS): Regex integrados descartam senhas, chaves de API, tokens e chaves privadas. Administradores podem impor padrões de negação regex adicionais via política do sistema.
Pontuação de qualidade e especificidade (scoreProposal): Propostas são pontuadas com base na presença de âncoras, vocabulário durável (constraint, gotcha, must) e especificidade. Entradas finas ou de baixa pontuação abaixo do limite de rejeição são descartadas.
Fila de ingestão em etapas por padrão (ProposalDraft): Capturas em segundo plano e deduções de fim de sessão são colocadas em etapas como propostas em SQLite para revisão humana na interface. A aplicação automática está desativada por padrão (auto_apply_kinds = []).
Rastreamento de conflito e substituição: Quando novas claims compartilham âncoras com fatos existentes, o amem calcula similaridade e levanta avisos de conflito, exigindo substituição explícita em vez de permitir sobrescritas silenciosas.

Como o amem evita inchaço de contexto e vazamento de memória entre projetos?

Particionamento por repositório: Cada claim de memória, tarefa, componente e nota é chaveado por repo_id (derivado da URL remota do git / caminho do workspace). Consultas em um projeto não podem recuperar ou vazar memória de outro repositório.
Recuperação híbrida e limites estritos: Em vez de despejar o grafo, amem_context usa pesquisa híbrida de texto completo BM25, embeddings no dispositivo, correspondência de palavras-chave e multiplicadores de frescor para ranquear e selecionar apenas os fatos relevantes de topo (limite padrão: 12).
Limites rígidos de caracteres: Injeções automáticas de hooks são limitadas a 2.400 caracteres para evitar inchaço de prompt e ataques de exaustão de tokens.
Divulgação progressiva para Skills: Pacotes de contexto injetam apenas um índice de Nível 0 (nomes de skills e descrições de uma linha). Corpos procedurais completos nunca são injetados a menos que o modelo os solicite explicitamente via amem_skill_view.

Como o amem lida com mudanças de código sem servir memória obsoleta?

Cada claim é fundamentada com âncoras de arquivo (code_anchors). Durante a geração de contexto, amem verifica a existência do arquivo e compara os timestamps de modificação do arquivo com os tempos de criação da claim:

Se os arquivos ancorados mudaram, a claim é marcada como obsoleta e penalizada no ranqueamento.
Pacotes de contexto injetam explicitamente um aviso no prompt do agente: "_X claim(s) marked stale — anchored files changed after the claim was written. Verify before trusting._"

O amem expõe um servidor de rede não autenticado ou envia código?

Vinculação estrita a loopback: A interface HTTP local / daemon MCP vincula exclusivamente a 127.0.0.1. Vinculações não-loopback são bloqueadas por regras de política codificadas.
Zero egresso externo: Telemetria está codificada como desativada (telemetry: false). Todos os bancos de dados SQLite (graph.db), vetores e logs permanecem em ~/.amem com permissões de sistema de arquivos locais 0700.
Criptografia opcional em repouso: O banco de dados local pode ser criptografado usando AES-256-GCM (amem lock --passphrase '...').

Desenvolva o próprio amem

cd amem
npm install
npm run build
npm run test          # unit + integration + CLI e2e (node:test)
npm run smoke         # end-to-end CLI/API smoke
npm run test:all      # both
npm link

Layout:

src/           CLI, SQLite, policy, attest, installers, localhost API
ui-static/     Setup / Memory / Stats UI
skills/        Agent skill markdown
templates/     Cursor rule + example enterprise policy
docs/          Agent install prompt + IT endpoint runbook + backlog
test/          Comprehensive node:test suite
scripts/       Smoke tests + MDM offboard helper

Substitua o diretório de memória para testes:

AMEM_HOME=/tmp/amem-test amem status

Endpoint empresarial (gerenciado por TI)

O amem ainda é memória pessoal no laptop — não um wiki compartilhado ou RAG em nuvem.
TI / DevEx pode governar a frota: instalação aprovada, política, atestado, desligamento.

Controle	Mecanismo
Política	`/etc/amem/policy.toml` (sistema) substitui `~/.amem/policy.toml`; ou `AMEM_POLICY_PATH`
Atestação	`amem doctor --attest` / `--json` (também `GET /api/attest` na interface local)
Higiene de segredos	Padrões de negação integrados + política `deny_claim_patterns` na proposta
Bloqueio de exportação	`allow_export = false`
Listas de permissão de plataforma/repositório	`allowed_platforms`, `allowed_remote_hosts`
Rascunhos de aplicação automática	`auto_apply_kinds` (vazio = nunca; ainda local)
Desligamento	`amem wipe --all --yes` ou scripts/mdm-offboard.sh

Garantias rígidas (não podem ser desativadas por configuração):

Sem telemetria de memória ou upload de reivindicações — ~/.amem permanece local
Apenas ping opcional e anônimo de instalação via npm (exclusão: AMEM_TELEMETRY_DISABLED=1)
A interface vincula-se apenas ao loopback (127.0.0.1)
A memória permanece abaixo de ~/.amem (modo 0700)

Início rápido de TI

# 1) Pin / install amem on the endpoint (internal npm, pkg, or npm link)
# 2) Deploy policy (root-owned on managed machines)
sudo mkdir -p /etc/amem
sudo cp templates/policy.example.toml /etc/amem/policy.toml

# 3) Verify for security review
amem doctor --attest --json

# 4) On offboard / laptop return
amem wipe --all --yes
# or: scripts/mdm-offboard.sh

Exemplo de política: templates/policy.example.toml
Manual completo de TI: docs/enterprise-endpoint.md

Roteiro sugerido: piloto pequeno de DevEx → pacote MDM + política → builds assinados/SBOM se a aquisição solicitar. Memória organizacional compartilhada está intencionalmente fora do escopo.

Não objetivos

Memória compartilhada ou sincronizada pela empresa
"Cérebro de equipe" hospedado na nuvem
Integração exata de faturamento do provedor
APIs de incorporação em nuvem/remota (apenas FTS5 local + embeddings de hash no dispositivo)
Gravar conteúdos de memória no histórico do git do produto

Ideias futuras (não agendadas): veja docs/backlog.md.

Licença

MIT — veja LICENSE.