O seu agente de codificação lembra-se de tudo. Chega de voltar a explicar.
Construído sobre o iii engine
Memória persistente para Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode e qualquer cliente MCP.
O gist alarga o padrão LLM Wiki de Karpathy com pontuação de confiança, ciclo de vida, grafos de conhecimento e pesquisa híbrida: o agentmemory é a implementação.
---
## Instalação
Requisitos:
- Node.js 20 ou mais recente, com npm e npx (`node -v`, `npm -v` e `npx -v`).
- A instalação automática do iii-engine no macOS/Linux também precisa de `curl`, de um `sh` POSIX e de `tar`. Imagens minimalistas como `node:20-slim` podem não os incluir.
- O Windows nativo exige que o `iii.exe` do iii-engine fixado na v0.22.1 seja instalado manualmente. O WSL2 ou o Docker Desktop são os outros caminhos suportados.
Comando canónico para uma instalação limpa:
```bash
npx -y @agentmemory/agentmemory@latest
```
A primeira execução é uma configuração interativa: escolha os agentes a ligar (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), escolha um fornecedor de LLM ou fique sem chave, e esta gera a configuração, inicia o servidor de memória e o seu iii engine fixado, e propõe instalar globalmente para que o comando simples `agentmemory` funcione em qualquer lugar depois disso. O `-y` aceita o prompt do pacote do npx e o `@latest` evita uma versão desatualizada em cache. Um fornecedor disponibiliza as funcionalidades de LLM, mas a compressão de observações escrita por LLM só é iniciada quando `AGENTMEMORY_AUTO_COMPRESS=true` também está definida.
O modo sem chave desativa os embeddings vetoriais. O `memory_recall` (o caminho `mem::search`) usa BM25, enquanto o `memory_smart_search` também pode combinar correspondências estruturais do grafo quando já existem dados de grafo. Para obter recall semântico local e gratuito, defina `EMBEDDING_PROVIDER=local` em `~/.agentmemory/.env` e reinicie. O primeiro pedido de embedding faz o download de `Xenova/all-MiniLM-L6-v2`; a inferência corre localmente depois desse download inicial do modelo.
O runtime local usa quatro portas: `3111` para REST/MCP HTTP, `3112` para os streams do iii, `3113` para o visualizador e `49134` para o WebSocket do worker iii. O estado persistente do iii vive em `~/Library/Application Support/agentmemory` no macOS, em `$XDG_DATA_HOME/agentmemory` ou `~/.local/share/agentmemory` no Linux, e em `%APPDATA%\agentmemory` no Windows. Use `--data-dir ` ou `AGENTMEMORY_DATA_DIR` para o substituir, e reutilize o mesmo valor em cada reinício. Por compatibilidade com versões anteriores, um `./data/state_store.db` ou `./data/iii-config.yaml` já existentes têm precedência sobre a predefinição da plataforma para a instância 0; uma flag explícita ou uma variável de ambiente continuam a ganhar.
Depois, prove que o recall funciona e dê ao seu agente as suas skills:
```bash
npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
```
As pesquisas por palavra-chave devem ter resultados no modo sem chave predefinido, através do BM25. A query `database performance optimization` da demo é propositadamente semântica e pode devolver zero resultados até que um fornecedor de embeddings seja configurado.
Prefere deixar um agente de codificação fazer tudo? Dê-lhe uma única instrução:
> Obtenha e siga as instruções em: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
Ligue mais agentes em qualquer momento com `agentmemory connect ` — 20 adaptadores listados em [Funciona com qualquer agente](#works-with-every-agent). Referência completa de comandos em [Início Rápido](#quick-start).
Windows
O caminho mais rápido é o WSL2. A configuração do engine no Windows nativo exige o download manual do ZIP fixado na v0.22.1 e a extração manual do `iii.exe`; o CLI não o extrai automaticamente. O Docker Desktop também é suportado. Veja as [notas de Windows](#windows) para o passo a passo.
Instalação global / EACCES
```bash
npm install -g @agentmemory/agentmemory@latest
```
O comando npx acima continua a ser o caminho canónico para uma instalação limpa e evita problemas de permissões do prefixo global.
O npx está a servir uma versão antiga
O npx faz cache por versão. Force a mais recente com `npx -y @agentmemory/agentmemory@latest`, ou limpe a cache uma vez com `rm -rf ~/.npm/_npx` (macOS/Linux; no Windows elimine `%LOCALAPPDATA%\npm-cache\_npx`).
Já tem o seu próprio iii engine em execução
O agentmemory fixa o iii-engine na v0.22.1 e não se liga a uma versão diferente (o worker não fala o protocolo de outro engine). Pare o outro engine e execute `npx -y @agentmemory/agentmemory@latest`. Este instala e executa a v0.22.1 fixada em `~/.agentmemory/bin`, deixando o seu próprio `iii` intacto.
---
O agentmemory funciona com qualquer agente que suporte hooks, MCP ou REST API. Todos os agentes partilham o mesmo servidor de memória.
Claude Code plugin nativo + 12 hooks + MCP
Codex CLI plugin nativo + 6 hooks + MCP
GitHub Copilot CLI MCP + hooks/skills do plugin
Cursor plugin nativo + 7 hooks + MCP
OpenCode plugin de captura + MCP
Devin 6 hooks + skills + MCP
OpenClaw plugin nativo + MCP
Hermes plugin nativo + MCP
pi plugin nativo + MCP
OpenHuman backend nativo com trait Memory
Gemini CLI servidor MCP
Antigravity MCP + hooks
Claude Desktop servidor MCP
Warp connect + MCP + skills
Zed servidor MCP
Cline servidor MCP
Continue servidor MCP
Droid servidor MCP
Kiro servidor MCP
Qwen Code servidor MCP
DeepSeek Harness servidor MCP
Roo Code servidor MCP
Kilo Code servidor MCP
Goose servidor MCP
Aider REST API
Funciona com qualquer agente que fale MCP ou HTTP. Um servidor, memórias partilhadas entre todos eles.
---
Explica a mesma arquitetura em cada sessão. Redescobre os mesmos bugs. Volta a ensinar as mesmas preferências. A memória incorporada (CLAUDE.md, .cursorrules) tem um limite de 200 linhas e torna-se desatualizada. O agentmemory resolve isto. Captura silenciosamente o que o seu agente faz, comprime-o em memória pesquisável e injeta o contexto certo quando a sessão seguinte começa. Um único comando. Funciona entre agentes.
**O que muda:** Na sessão 1 configura a autenticação JWT. Na sessão 2 pede limitação de taxa (rate limiting). O agente já sabe que a sua autenticação usa o middleware jose em `src/middleware/auth.ts`, que os seus testes cobrem a validação de tokens, e que escolheu jose em vez de jsonwebtoken por compatibilidade com Edge, sem voltar a explicar e sem copiar e colar.
```bash
npx -y @agentmemory/agentmemory@latest
```
Por predefinição, o agentmemory guarda o estado do iii-engine fora do repositório a partir do qual é iniciado: `~/Library/Application Support/agentmemory` no macOS, `$XDG_DATA_HOME/agentmemory` ou `~/.local/share/agentmemory` no Linux, e `%APPDATA%\agentmemory` no Windows. Um `./data/state_store.db` ou `./data/iii-config.yaml` legados já existentes são reutilizados para a instância 0 antes dessa predefinição da plataforma. Para escolher uma localização explicitamente, passe `--data-dir ` ou defina `AGENTMEMORY_DATA_DIR`; qualquer uma destas definições explícitas tem precedência sobre a deteção legada:
```bash
npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
```
As execuções nativas e em Docker usam este mesmo diretório do anfitrião já resolvido; o Docker monta-o com bind em `/data`. O `--instance 1` acrescenta `instance-1` ao diretório resolvido e seleciona o quarteto de portas predefinido separado `3211/3212/3213/49234`.
Notas da versão mais recente: [CHANGELOG.md](../CHANGELOG.md).
---
### Precisão de Recuperação
**coding-agent-life-v1** (corpus interno, reproduzível em sandbox)
| Adaptador | P@5 | R@5 | Taxa de acerto top-5 | latência p50 |
|---|---|---|---|---|
| **agentmemory híbrido** | **0.240** | **1.000** | **15 / 15** | 14 ms |
| grep de referência | 0.227 | 0.967 | 15 / 15 | 0 ms |
Taxa de acerto top-5 de 100% no **teto matemático do P@5** para este corpus (0.240, ver scorecard). O híbrido recupera todas as sessões gold; o grep falha 1 de 2 golds na query temporal multi-sessão. O ganho está no **recall + temporal**, não na precisão agregada. Este benchmark é pequeno e escasso em golds; o LongMemEval-S maior, abaixo, diferencia melhor. Detalhamento completo por tipo + nota de correção: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md).
**LongMemEval-S** (ICLR 2025, 500 perguntas)
| Sistema | R@5 | R@10 | MRR |
|---|---|---|---|
| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
| fallback apenas BM25 | 86.2% | 94.6% | 71.5% |
> Modelo de embedding: `all-MiniLM-L6-v2` (local, gratuito, sem chave de API). Relatórios completos: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Comparação com concorrentes: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) cobrindo agentmemory vs mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
**Reproduzir localmente:** [`eval/README.md`](../eval/README.md), um harness com adaptadores encaixáveis para o LongMemEval `_s` (500 perguntas públicas) + `coding-agent-life-v1` (corpus interno de 15 sessões). Os adaptadores grep / vetor / agentmemory são avaliados lado a lado, com saída NDJSON, e os scorecards publicados ficam em [`docs/benchmarks/`](../docs/benchmarks/).
**Combina-se com [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything) e [Graphify](https://github.com/safishamsi/graphify).** Indexação de grafos de código, pipelines de build multiagente e grafos de conhecimento mais amplos em docs / PDFs / imagens / vídeos. O agentmemory recorda o trabalho; estes três projetos iluminam o resto da camada de contexto. Receitas + tabela de encaminhamento de perguntas: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
---
agentmemory
mem0 (63K ⭐)
Letta / MemGPT (24K ⭐)
Khoj (36K ⭐)
supermemory (29K ⭐)
TencentDB Agent Memory (22K ⭐)
MemPalace (54K ⭐)
oracleagentmemory
Hippo
Incorporado (CLAUDE.md)
Tipo
Motor de memória + servidor MCP
API de camada de memória
Runtime completo de agente
IA pessoal
API de memória + app
Hub de memória de equipa (proxy LLM)
Memória vetorial (OSS)
Motor de memória (Oracle DB)
Sistema de memória
Ficheiro estático
Recuperação R@5
95.2%
68.5% (LoCoMo)
83.2% (LoCoMo)
N/A
Autorreportado
PersonaMem 76% (autorreportado)
~96.6% (autorreportado)
94.4% (autorreportado)
N/A
N/A (grep)
Captura automática
12 hooks (esforço manual zero)
Chamadas manuais a add()
Autoedição pelo agente
Manual
Extração do lado da API
Interceção via proxy (troca de URL base)
Manual
Extração via API
Manual
Edição manual
Pesquisa
BM25 + Vetor + Grafo (fusão RRF)
Vetor + Grafo
Vetor (arquivo)
Semântica
Vetor + RAG
4 tipos de recursos (Chat / Skill / Wiki / CodeGraph)
Apenas vetor
Vetor + semântica
Ponderada por decaimento
Carrega tudo para o contexto
Multiagente
MCP + REST + leases + signals
API (sem coordenação)
Apenas dentro do runtime da Letta
Não
Não
Papéis de equipa + recursos partilhados
Não
Apenas com âmbito definido
Partilhada multiagente
Ficheiros por agente
Dependência de framework
Nenhuma (qualquer cliente MCP)
Nenhuma
Alta (tem de usar Letta)
Autónomo
Nenhuma
O proxy intermedeia todas as chamadas ao modelo
Nenhuma
Oracle Database
Nenhuma
Formato por agente
Dependências externas
Nenhuma (SQLite + iii-engine)
Qdrant / pgvector
Postgres + BD vetorial
Várias
Nuvem gerida
Stack Docker (Core + Hub + Proxy)
Armazenamento vetorial
Oracle AI Database
Nenhuma
Nenhuma
Ciclo de vida da memória
Consolidação em 4 níveis + decaimento + esquecimento automático
Extração passiva
Gerido pelo agente
Manual
Esquecimento automático
Revisão manual; encaminhamento automático em desenvolvimento
Nenhum
Não indicado
Decaimento + consolidação
Limpeza manual
Eficiência de tokens
~1,900 tokens/sessão ($10/ano)
Varia com a integração
Memória principal no contexto
Varia
Preços na nuvem
Não indicado
Sem orçamento de tokens
Suportado por LLM (varia)
Varia
22K+ tokens em 240 observações
Visualizador em tempo real
Sim (porta 3113)
Painel na nuvem
Painel na nuvem
Interface Web
Painel na nuvem
Interface Web do hub
Não
Não
Não
Não
Auto-hospedado
Sim (predefinição)
Opcional
Opcional
Sim
Não (apenas na nuvem)
Sim (Docker)
Sim
Sim (Oracle DB)
Sim
Sim
Nota sobre o benchmark: apenas o R@5 do agentmemory é um resultado medido por nós (LongMemEval-S, reproduzível a partir de benchmark/COMPARISON.md). Os valores de mem0 e Letta são os números LoCoMo publicados por eles (um dataset diferente); os valores de MemPalace, supermemory, TencentDB (PersonaMem) e oracleagentmemory são afirmações autorreportadas pelos fornecedores que não reproduzimos de forma independente (a execução do oracleagentmemory usou o GPT-5.5 contra uma Oracle AI Database). Mostrados lado a lado apenas como estimativa aproximada, não como comparação direta sobre dados idênticos. As contagens de estrelas são aproximadas e variam com o tempo.
**Participantes mais recentes** que vale a pena conhecer, comparados em profundidade em [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
| Sistema | ⭐ | Abordagem |
|--------|---|-------|
| Zep / Graphiti | 30K | Grafo de conhecimento temporal; os resultados publicados mais fortes em queries temporais (LongMemEval 63.8%), mas o grafo é construído de forma assíncrona, por isso os factos recentes podem atrasar |
| Cognee | 30K | Ingestão de documentos para grafo de conhecimento, apenas Python, construído para extração estruturada de entidades em vez de captura de sessões |
Nenhum destes faz captura automática a partir de hooks de agentes de codificação, entrega um visualizador local-first, ou funciona sem chave — a combinação em torno da qual o agentmemory foi construído.
---
Compatibilidade: esta versão visa o `iii-sdk` 0.22.1 e fixa o iii-engine na v0.22.1.
### Experimente em 30 Segundos
```bash
# Terminal 1: start the server
npx -y @agentmemory/agentmemory@latest
# Terminal 2: seed sample data and see recall in action
npx -y @agentmemory/agentmemory@latest demo
```
O `demo` gera 3 sessões realistas (autenticação JWT, correção de uma query N+1, limitação de taxa) e executa pesquisas sobre elas. As instalações sem chave desativam os vetores, por isso as queries por palavra-chave do `mem::search` devem ter resultados através do BM25, enquanto `database performance optimization` pode devolver zero. O `smart-search` pode também devolver correspondências estruturais do grafo quando existem dados de grafo. Para que a query semântica encontre a correção da N+1 através de vetores, defina `EMBEDDING_PROVIDER=local`, reinicie e deixe terminar o primeiro download do modelo.
Abra `http://localhost:3113` para ver a memória a construir-se em direto.
### Validar uma Instalação Limpa e a Persistência ao Reiniciar
Com o servidor em execução, valide o REST, a saúde (health), o visualizador e o estado do runtime suportado pelo iii:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
curl -fsS http://localhost:3111/agentmemory/health
curl -fsS -o /dev/null http://localhost:3113/
npx -y @agentmemory/agentmemory@latest status
```
O painel de arranque pronto (ready) tem em conta as quatro portas: REST/MCP HTTP na 3111, streams do iii na 3112, o visualizador na 3113 e o WebSocket do worker iii na 49134. O `status` confirma a saúde do agentmemory e o modo ativo de fornecedor/embedding. Guarde uma sonda e confirme que é pesquisável:
```bash
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
Depois execute `npx -y @agentmemory/agentmemory@latest stop`, inicie novamente o comando canónico no Terminal 1, espere por `/agentmemory/livez` e repita a pesquisa. A sonda tem de continuar a ser devolvida. Se selecionou um `--data-dir` personalizado, passe o mesmo diretório ao reiniciar.
### Comandos do Dia a Dia
A instalação e a configuração estão em [Instalação](#install) acima (a primeira execução guia-o passo a passo). No dia a dia:
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
agentmemory connect # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
```
### Reprodução de Sessões
Todas as sessões que o agentmemory regista podem ser reproduzidas. Abra o visualizador, escolha o separador **Replay** e percorra a linha do tempo: prompts, chamadas a ferramentas, resultados de ferramentas e respostas são apresentados como eventos discretos, com play/pause, controlo de velocidade (0.5x a 4x) e atalhos de teclado (espaço para alternar, setas para avançar passo a passo).
Para importar transcrições JSONL mais antigas do Claude Code:
```bash
# Import everything under the default ~/.claude/projects
npx -y @agentmemory/agentmemory@latest import-jsonl
# Or import a single file
npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
```
As sessões importadas aparecem no seletor do Replay junto às nativas. Por trás, cada entrada passa pelas funções iii `mem::replay::load`, `mem::replay::sessions` e `mem::replay::import-jsonl`, sem servidores paralelos. Cada transcrição importada é indexada para pesquisa, marcada com o canal de origem `import`, e processada para gerar um crystal de sessão e lessons.
> **Atenção, se depende do `import-jsonl` como o seu caminho principal de captura:** o `cleanupPeriodDays` do Claude Code (em `~/.claude/settings.json`, predefinição **30**) elimina automaticamente as transcrições JSONL mais antigas do que essa janela em `~/.claude/projects/`. Se instalar o agentmemory do zero sobre um histórico do Claude Code com meses, tudo o que tiver mais de 30 dias já desapareceu antes da primeira importação. Execute o `import-jsonl` num cron, aumente o `cleanupPeriodDays` para um valor mais alto, ou ligue os hooks de captura automática (o caminho predefinido de instalação do plugin) para que cada turno chegue ao agentmemory enquanto a sessão está ativa e a limpeza do JSONL deixe de ter importância.
### Atualização / Manutenção
Use o comando de manutenção quando quiser, de forma intencional, atualizar o seu runtime local:
```bash
npx -y @agentmemory/agentmemory@latest upgrade
```
Aviso: este comando altera o workspace/runtime atual. Pode atualizar dependências JavaScript e descarregar a imagem Docker fixada `iiidev/iii:0.22.1`. Nunca instala um iii engine sem fixação de versão ou mais recente.
Os detalhes de implementação estão em `src/cli.ts` (ver `runUpgrade` na zona `src/cli.ts:544-595`).
### Claude Code (um bloco, cole-o)
```text
Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code sem instalar o plugin (caminho MCP standalone)
Se ligar o servidor MCP do agentmemory através de `~/.claude.json` diretamente, em vez de usar `/plugin install`, o Claude Code nunca resolve `${CLAUDE_PLUGIN_ROOT}` e tem de apontar os scripts de hook para caminhos absolutos em `~/.claude/settings.json`. Esses caminhos normalmente incorporam a versão do agentmemory (por exemplo, `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), por isso a atualização seguinte quebra silenciosamente todos os hooks.
Solução alternativa:
```bash
agentmemory connect claude-code --with-hooks
```
Isto combina os mesmos comandos de hook em `~/.claude/settings.json` com caminhos absolutos resolvidos para o diretório `plugin/` empacotado do pacote `@agentmemory/agentmemory` atualmente instalado. Volte a executar o comando depois de atualizar o agentmemory para atualizar os caminhos. As entradas do utilizador no mesmo ficheiro são preservadas; só as entradas anteriores do agentmemory são substituídas. Usar o caminho `/plugin install` continua a ser a abordagem recomendada.
Para implementações remotas ou protegidas, inicie o Claude Code com `AGENTMEMORY_URL` e `AGENTMEMORY_SECRET` definidas. O plugin passa ambos os valores ao seu servidor MCP empacotado; quando `AGENTMEMORY_URL` está vazia, o shim MCP usa `http://localhost:3111`.
### Codex CLI (plataforma de plugins do Codex)
```bash
# 1. start the memory server in a separate terminal
npx -y @agentmemory/agentmemory@latest
# 2. register the agentmemory marketplace and install the plugin
codex plugin marketplace add rohitg00/agentmemory
codex plugin add agentmemory@agentmemory
```
O plugin do Codex é distribuído a partir do mesmo diretório `plugin/` que o plugin do Claude Code. Este regista:
- Uma ponte MCP stdio empacotada para o daemon em execução, sem download via npm nem armazenamento de reserva. Consulte o [guia local do Codex](../docs/plugins/codex-local.md) para testar uma compilação ainda não lançada.
- 6 hooks de ciclo de vida: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
- 9 skills invocáveis: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, mais 8 skills de referência que o agente carrega sob demanda (disciplina de memória, ferramentas MCP, REST API, configuração, agentes, hooks, arquitetura e o guia de criação de skills)
O motor de hooks do Codex injeta `CLAUDE_PLUGIN_ROOT` nos subprocessos de hook (conforme [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), por isso os mesmos scripts de hook funcionam em ambos os anfitriões sem duplicação. Os eventos Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure são exclusivos do Claude Code e não são registados para o Codex.
#### Confiança e compatibilidade dos hooks do Codex
O despacho nativo de hooks de plugin está verificado com o Codex CLI 0.150.1. Confie nos hooks do plugin antes de esperar captura. O comportamento no Desktop depende do seu runtime empacotado; verifique `/hooks` e confirme um evento capturado antes de ativar uma solução alternativa.
Se o seu anfitrião exigir hooks globais, replique os comandos em `~/.codex/hooks.json`. Quando o MCP já está configurado, o conector atual precisa de `--force` para chegar à instalação dos hooks:
```bash
agentmemory connect codex --with-hooks --force
```
Isto combina os hooks globais e reescreve a entrada MCP do agentmemory, preservando as entradas não relacionadas. Reveja quaisquer definições personalizadas do endpoint do agentmemory antes de usar `--force`. Volte a executar depois de atualizar para atualizar os caminhos dos scripts. Ative os hooks nativos do plugin ou as cópias globais para evitar captura duplicada.
### GitHub Copilot CLI
Para o modo de agente do VS Code, utilize o [guia de MCP e captura automática do Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). O conector do CLI não configura o VS Code.
```bash
# MCP-only wiring
agentmemory connect copilot-cli
# Alternatively, full hooks/skills plugin from the GitHub subdir
copilot plugin install rohitg00/agentmemory:plugin
```
`agentmemory connect copilot-cli` combina `mcpServers.agentmemory` em `~/.copilot/mcp-config.json` (ou `$COPILOT_HOME/mcp-config.json` quando `COPILOT_HOME` está definida) e preserva os servidores existentes. No Windows nativo, este é o único adaptador `connect` automatizado; configure manualmente todos os outros agentes nativos do Windows. O `connect` no WSL só é suportado quando o agente de destino também está instalado nesse mesmo ambiente WSL. O Copilot deteta o servidor MCP no próximo arranque ou depois de `/mcp`. Instale também o plugin quando quiser a experiência completa de hooks/skills.
OpenClaw (cole este prompt)
```text
Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "http://localhost:3111"
}
}
}
}
Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
```
Guia completo: [`integrations/openclaw/`](../integrations/openclaw/)
Agente Hermes (cole este prompt)
```text
Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
mcp_servers:
agentmemory:
command: npx
args: ["-y", "@agentmemory/mcp"]
memory:
provider: agentmemory
Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
```
Guia completo: [`integrations/hermes/`](../integrations/hermes/)
### Outros Agentes
Inicie o servidor de memória: `npx -y @agentmemory/agentmemory@latest`
#### Skills nativas via `npx skills add` (50+ agentes)
O agentmemory distribui 17 skills no formato `/SKILL.md`, no estilo do Claude Code: 9 skills de ação invocáveis (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) e 8 skills de referência que o agente carrega sob demanda (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). As skills de referência trazem tabelas de dados geradas a partir do código-fonte, por isso nunca ficam desatualizadas. O CLI [`skills`](https://npmjs.com/package/skills) da vercel-labs instala-as automaticamente no diretório nativo de skills do agente que o invoca, em mais de 50 agentes (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, e outros):
```bash
npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
npx skills add rohitg00/agentmemory -y -a warp # explicit agent
npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
```
Isto é **complementar** a `agentmemory connect `:
- `agentmemory connect ` escreve a configuração do servidor MCP para que as ferramentas fiquem disponíveis.
- `npx skills add rohitg00/agentmemory` instala as skills para que o agente saiba quando as chamar.
Para os poucos agentes que o CLI `skills` ainda não cobre (Zed v1.3.x e anteriores), coloque você mesmo os 17 ficheiros SKILL.md no diretório nativo de skills do agente; o mesmo formato funciona em todo o lado.
#### Bloco MCP Padrão
A entrada do agentmemory é o **mesmo bloco de servidor MCP** em todos os anfitriões que usam o formato `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
```json
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
"AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
}
}
```
**Combine esta entrada com o objeto `mcpServers` existente** no ficheiro de configuração do anfitrião; não substitua o ficheiro. Se o ficheiro já tiver outros servidores, adicione `agentmemory` junto deles como mais uma chave dentro de `mcpServers`. Se `mcpServers` estiver totalmente ausente, cole o bloco dentro de `{ "mcpServers": { ... } }`. Os marcadores `${VAR}` herdam `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` da shell no momento em que o servidor MCP é iniciado; variáveis não definidas passam strings vazias e o shim recua para `http://localhost:3111`. Uma única entrada ligada cobre tanto implementações locais como remotas (k8s / com proxy inverso).
| Agent | Config file | Notes |
|---|---|---|
| **Cursor (apenas MCP)** | `~/.cursor/mcp.json` | Combine com `mcpServers`, ou use `agentmemory connect cursor`. Também está disponível um deeplink de um clique no site. |
| **Cursor (plugin completo)** | `.cursor-plugin/` | Listagem no Cursor Marketplace (submissão em revisão) ou Cursor Settings → Plugins → checkout local. Regista 7 hooks de captura automática (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skills + o servidor MCP, com `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` geridas no painel de plugins do Cursor. Funciona no Cursor IDE e no CLI `cursor-agent`; os prompts do modo print do CLI são preenchidos retroativamente a partir da transcrição da sessão no fim da sessão. |
| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Combine com `mcpServers`. Reinicie o Claude Desktop depois de editar. |
| **Cline / Roo Code / Kilo Code** | Definições MCP do Cline (Settings UI → MCP Servers → Edit) | Mesmo bloco `mcpServers`. |
| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` combina a entrada MCP; `--with-hooks` adiciona seis hooks nativos de captura automática (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) com os correspondentes de ferramentas em minúsculas do Devin. Verifique com `devin mcp list` e `/hooks` dentro do devin. |
| **Devin CLI (plugin completo)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` a partir de um checkout regista as 17 skills como comandos slash `/agentmemory:`, além do servidor MCP. Os hooks de plugin do Devin não conseguem disparar `SessionStart`/`SessionEnd`, por isso combine com `connect devin --with-hooks` para uma captura completa da sessão. |
| **Devin (nuvem)** | Settings → Connections → MCP servers | Adicione um MCP personalizado (STDIO): comando `npx`, argumentos `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` a apontar para uma implementação do agentmemory acessível pela rede, mais `AGENTMEMORY_SECRET` (as sessões na nuvem não conseguem alcançar o localhost — ver [`deploy/`](../deploy/)). Guarde o segredo em Devin Secrets e depois use "Test listing tools" para confirmar que aparecem as 54 ferramentas. |
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (combina automaticamente). |
| **GitHub Copilot CLI (apenas MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` combina `mcpServers.agentmemory`; o Copilot deteta-o no próximo arranque ou com `/mcp`. |
| **GitHub Copilot CLI (plugin completo)** | Instalação de plugin do Copilot | `copilot plugin install rohitg00/agentmemory:plugin` para o plugin a partir do subdiretório do GitHub. |
| **OpenClaw** | Configuração MCP do OpenClaw | Mesmo bloco `mcpServers`. Mais profundo: `openclaw plugins install ./integrations/openclaw` reivindica o slot de memória do OpenClaw (muda automaticamente de `memory-core`); defina `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, ou a captura de turnos é bloqueada silenciosamente. Ver [`integrations/openclaw`](../integrations/openclaw/). |
| **Codex CLI (apenas MCP)** | `.codex/config.toml` | Formato TOML: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, ou adicione `[mcp_servers.agentmemory]` manualmente. |
| **Codex CLI (plugin completo)** | Marketplace de plugins do Codex | `codex plugin marketplace add rohitg00/agentmemory` e depois `codex plugin add agentmemory@agentmemory`. Regista MCP + 6 hooks de ciclo de vida + 17 skills. Confie nos hooks e verifique a captura no seu anfitrião; consulte [configuração e validação do Codex](../docs/plugins/codex-local.md). |
| **OpenCode (apenas MCP)** | `opencode.json` | Formato diferente: chave `mcp` de nível superior, comando como array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
| **OpenCode (plugin completo)** | `plugin/opencode/` | 22 hooks de captura automática, cobrindo o ciclo de vida da sessão, mensagens, ferramentas e erros. A atribuição de projeto é feita por sessão, por isso um único processo do OpenCode que abrange vários repositórios arquiva cada sessão sob o seu próprio projeto. Dois comandos slash (`/recall`, `/remember`). Copie `plugin/opencode/` para o seu workspace do OpenCode e adicione a entrada do plugin a `opencode.json`. Ver [`plugin/opencode/README.md`](../plugin/opencode/README.md) para a tabela completa de hooks + análise de lacunas. |
| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` instala a extensão empacotada no diretório de auto-deteção do pi (recall ao iniciar o agente, captura ao terminar o agente, ferramentas `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). O `/reload` num pi em execução deteta-a. [`integrations/pi`](../integrations/pi/) é também um pacote pi (`pi install ./integrations/pi` a partir de um checkout). |
| **Agente Hermes** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` dá o fornecedor de memória com 6 hooks (prefetch, captura de turno, fim de sessão, pré-compressão, espelhamento de MEMORY.md, bloco de prompt do sistema). Valide com `hermes plugins doctor` e `hermes memory status`. Ver [`integrations/hermes`](../integrations/hermes/). |
| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` escreve o bloco `mcpServers` padrão. O payload dos hooks é compatível a nível de campos com o Claude Code, por isso os scripts dos 12 hooks existentes funcionam sem modificação; ligue-os através da secção `hooks` no mesmo `settings.json`. |
| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` instala o MCP e os hooks de captura no diretório de personalização partilhado. Consulte [configuração e limites do Antigravity](../docs/plugins/antigravity.md). |
| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` usa a mesma configuração de MCP e hooks das versões atuais do IDE. As instalações existentes devem atualizar com `--force`; consulte as [notas de atualização](../docs/plugins/antigravity.md). |
| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` escreve a configuração ao nível do utilizador. As substituições ao nível do workspace vão em `.kiro/settings/mcp.json`, junto ao seu código. |
| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` escreve o bloco `mcpServers` padrão. O Warp também deteta automaticamente skills em `.claude/skills/`; depois de instalado o plugin do Claude Code, as 8 skills do agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) aparecem nativamente na paleta de comandos slash do Warp. |
| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` escreve o bloco `mcpServers` padrão. Utilizadores da extensão VS Code: cole o mesmo bloco através de Cline Settings → MCP Servers → Edit JSON. |
| **Continue.dev** | `~/.continue/config.yaml` (preferido) ou `config.json` (legado) | `agentmemory connect continue` cria `config.yaml` do zero quando nenhum dos dois existe, ou modifica o `config.json` existente. **Se já tiver `config.yaml`**, o adaptador imprime o bloco exato para colar sob `mcpServers:`; não reescreve o seu yaml silenciosamente, porque preservar comentários e anchors em segurança precisa de um parser YAML que o pacote não inclui. O Continue usa a forma de array (não de objeto) para `mcpServers`. |
| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` escreve sob `context_servers` (a chave do Zed, NÃO `mcpServers`). Servidores MCP remotos podem, em alternativa, ser ligados através de `{"url": "..."}`. |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` escreve o bloco `mcpServers` padrão. As substituições ao nível do projeto vão em `/.factory/mcp.json`. Passe `--with-hooks` para captura automática nativa. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` acrescenta uma linha `@deepseek-ai/dsh-mcp-client` à camada de patch ao nível home que todos os perfis do Harness carregam; as ferramentas registam-se como `mcp__agentmemory__*`. Passe `--with-hooks` para também ligar a captura automática: os scripts de hook do Claude Code empacotados correm através da ponte oficial `@deepseek-ai/dsh-hooks-claude-code` do Harness (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop), via um manifesto escrito em `$DSH_HOME/agentmemory.hooks.json`. Usa por predefinição `~/.dsh` quando `DSH_HOME` não está definida. |
| **Goose** | Settings UI de MCP do Goose | Mesmo bloco `mcpServers`; use `goose configure` → Add Extension → MCP. A edição direta do YAML em `~/.config/goose/config.yaml` é suportada, mas o esquema usa `extensions:` + `cmd` (não `mcpServers:` + `command`). |
| **Aider** | n/a | Fale diretamente com a REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
| **Qualquer agente (32+)** | n/a | `npx skillkit install agentmemory` deteta automaticamente o anfitrião e combina a configuração. |
**Clientes MCP em sandbox** (Flatpak / Snap / contentores restritivos) que não conseguem alcançar o `localhost` do anfitrião: defina também `"AGENTMEMORY_FORCE_PROXY": "1"` no bloco `env`, e aponte `AGENTMEMORY_URL` para uma rota que a sandbox consiga efetivamente alcançar (por exemplo, o seu IP de LAN).
### Acesso Programático (Python / Rust / Node)
O agentmemory regista as suas operações principais como funções iii (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Qualquer linguagem com um SDK iii pode chamá-las diretamente através de `ws://localhost:49134`, sem necessidade de um cliente REST separado por linguagem.
```bash
pip install iii-sdk # Python
cargo add iii-sdk # Rust
npm install iii-sdk # Node
```
```python
from iii import register_worker
iii = register_worker("ws://localhost:49134")
iii.connect()
iii.trigger({
"function_id": "mem::smart-search",
"payload": {"project": "demo", "query": "how do tokens refresh"},
})
```
Exemplo prático: [`examples/python/`](../examples/python/) (fluxo de arranque rápido + observação/recall). O REST na `:3111` continua disponível para anfitriões sem um runtime iii.
### A Partir do Código-Fonte
```bash
git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
```
Isto inicia o agentmemory com um `iii-engine` local, se o binário fixado já estiver instalado, ou usa o Docker Compose quando selecionado. O REST, os streams e o visualizador fazem bind em `127.0.0.1` por predefinição. O caminho automático do binário para macOS/Linux exige `curl`, um `sh` POSIX e `tar`.
Instale o `iii-engine` manualmente. **O agentmemory atualmente fixa o `iii-engine` na `v0.22.1`**, o mesmo lançamento da sua dependência `iii-sdk`; o worker fala o protocolo de ligação (wire protocol) desse engine, e a 0.20.0 reorganizou a superfície do SDK, por isso os dois avançam juntos nos lançamentos do agentmemory. Substitua com `AGENTMEMORY_III_VERSION=` se executar o seu próprio engine e souber que corresponde.
- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
- **macOS x64:** troque `aarch64-apple-darwin` por `x86_64-apple-darwin`
- **Linux x64:** troque por `x86_64-unknown-linux-gnu`
- **Linux arm64:** troque por `aarch64-unknown-linux-gnu`
- **Windows:** descarregue `iii-x86_64-pc-windows-msvc.zip` de [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) e extraia `iii.exe` para `%USERPROFILE%\.agentmemory\bin\iii.exe`
Cada arquivo tem um ficheiro `.sha256` correspondente na página de lançamento; quando trocar a plataforma, use o hash desse ficheiro na verificação acima (no Windows: `Get-FileHash`). O instalador automático em `npx @agentmemory/agentmemory` fixa estes hashes e rejeita um arquivo que não corresponda.
Ou use Docker (o `docker-compose.yml` incluído descarrega `iiidev/iii:0.22.1`). Documentação completa: [iii.dev/docs](https://iii.dev/docs).
### Windows
O agentmemory funciona no Windows 10/11, mas o pacote Node.js por si só não basta; também precisa do runtime do iii-engine fixado na v0.22.1 como processo em segundo plano. O CLI não extrai automaticamente o ZIP do Windows, por isso os utilizadores do Windows nativo têm de instalar o `iii.exe` manualmente, usar o WSL2 ou optar pelo Docker Desktop.
A ligação automática de MCP no Windows nativo só suporta `agentmemory connect copilot-cli`. Para o Claude Code, o Codex, o Cursor, e qualquer outro agente nativo do Windows, copie o bloco MCP manual de [Outros agentes](#other-agents) para a configuração do Windows desse agente. Executar o `connect` no WSL só é apropriado quando o agente de destino também está instalado nesse mesmo ambiente WSL; não edita a configuração de um agente que corre no anfitrião Windows.
**Opção A: binário pré-compilado para Windows (recomendado)**
```powershell
# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
# (agentmemory pins the engine to the same release as its iii-sdk;
# v0.22.1 is the current pair)
# 2. Download iii-x86_64-pc-windows-msvc.zip
# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
# 3. Extract iii.exe to agentmemory's private engine directory:
New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
# 4. Verify:
& "$HOME\.agentmemory\bin\iii.exe" --version
# Should print: 0.22.1
# 5. Then run agentmemory as usual:
npx -y @agentmemory/agentmemory@latest
```
**Opção B: Docker Desktop**
```powershell
# 1. Install Docker Desktop for Windows
# 2. Start Docker Desktop and make sure the engine is running
# 3. Select Docker explicitly and run agentmemory:
$env:AGENTMEMORY_USE_DOCKER = "1"
npx -y @agentmemory/agentmemory@latest
```
**Opção C: apenas MCP standalone (sem engine).** Se só precisar das ferramentas MCP para o seu agente e não precisar da REST API, do visualizador ou das tarefas cron, ignore completamente o engine:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
# or via the shim package:
npx -y @agentmemory/mcp
```
**Diagnóstico para Windows:** se `npx -y @agentmemory/agentmemory@latest` falhar, execute-o novamente com `--verbose` para ver o stderr real do engine. Modos de falha comuns:
| Sintoma | Correção |
|---|---|
| `The engine process started but the REST API never responded.` | Confirme que as quatro portas derivadas estão livres, verifique se o `iii.exe` fixado continuou ativo, e depois execute novamente com `--verbose` e inspecione o stderr do engine capturado |
| `Could not start iii-engine` | Nem o `iii.exe` nem o Docker estão instalados. Veja a Opção A ou B acima |
| Conflito de porta | `netstat -ano \| findstr :3111` para ver o que está vinculado, depois termine o processo ou use `--port ` |
| O fallback para Docker é ignorado mesmo com o Docker instalado | Confirme que o Docker Desktop está realmente em execução (ícone na bandeja do sistema) |
> Nota: o **engine** do iii é um binário pré-compilado, não uma cargo crate, por isso não tente fazer `cargo install` dele. (Os **SDKs** do iii são publicados em crates.io, npm e PyPI, mas o agentmemory não precisa deles.) Todos os métodos de instalação do engine suportados estão fixados na v0.22.1: o binário pré-compilado acima, o caminho de auto-instalação do agentmemory para macOS/Linux (exige `curl`, `sh` POSIX e `tar`), e a imagem Docker `iiidev/iii:0.22.1`. Um `install.sh | sh` simples do upstream instala o engine mais recente, que o agentmemory não suporta. Use `npx -y @agentmemory/agentmemory@latest`; no macOS/Linux, este obtém o engine fixado para `~/.agentmemory/bin`.
---
Deploy
Modelos de um clique para anfitriões geridos. Cada um distribui um
Dockerfile autocontido que obtém o `@agentmemory/agentmemory` do npm e copia
o binário do iii engine a partir da imagem oficial `iiidev/iii` no Docker Hub;
não é necessária nenhuma imagem pré-construída do agentmemory. O armazenamento persistente
é montado em `/data`; o entrypoint do primeiro arranque substitui a
configuração do iii incluída no npm (que faz bind em `127.0.0.1`) por uma
ajustada para implementação, que faz bind em `0.0.0.0` e usa caminhos absolutos em `/data`,
gera o segredo HMAC, e depois reduz os privilégios de `root` para `node` através do
`gosu` antes de executar o CLI do agentmemory.
O botão de implementação de um clique do Render exige um `render.yaml` na raiz do repositório, que mantemos deliberadamente limpa. Use o fluxo Render Blueprint documentado em [`deploy/render/`](.././deploy/render/README.md) para apontar manualmente para o blueprint existente no repositório.
Os detalhes completos de configuração (captura de HMAC, túnel SSH do visualizador, rotação, cópia de segurança,
custos mínimos) estão em [`deploy/`](.././deploy/README.md):
- [`deploy/fly`](.././deploy/fly/README.md): máquina única com
`auto_stop_machines = "stop"`; a mais económica em inatividade.
- [`deploy/railway`](.././deploy/railway/README.md): taxa fixa do plano Hobby,
volume no painel.
- [`deploy/render`](.././deploy/render/README.md): fluxo Blueprint,
snapshots automáticos de disco nos planos pagos.
- [`deploy/coolify`](.././deploy/coolify/README.md): auto-hospedado no seu
próprio VPS através do [Coolify](https://coolify.io/self-hosted); a mesma stack
Docker Compose, o anfitrião e os dados são seus.
Apenas a porta `3111` é publicada. O visualizador na `3113` continua
vinculado ao loopback dentro do contentor; o README de cada modelo documenta o
padrão de túnel SSH para o alcançar.
---
Todo o agente de codificação esquece tudo quando a sessão termina, e cada nova sessão começa consigo a voltar a explicar a sua stack. O agentmemory corre em segundo plano e remove esse passo.
```text
Session 1: "Add auth to the API"
Agent writes code, runs tests, fixes bugs
agentmemory silently captures every tool use
Session ends -> observations compressed into structured memory
Session 2: "Now add rate limiting"
Agent already knows:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
Zero re-explaining. Starts working immediately.
```
### vs memória incorporada do agente
Todo o agente de codificação com IA vem com memória incorporada: o Claude Code tem o `MEMORY.md`, o Cursor tem notepads, o Cline tem memory bank. Estas funcionam como notas autocolantes. O agentmemory é a base de dados pesquisável por trás das notas autocolantes.
| | Incorporado (CLAUDE.md) | agentmemory |
|---|---|---|
| Escala | Limite de 200 linhas | Ilimitada |
| Pesquisa | Carrega tudo para o contexto | BM25 + vetor + grafo (apenas top-K) |
| Custo em tokens | 22K+ em 240 observações | ~1,900 tokens (92% menos) |
| Entre agentes | Ficheiros por agente | MCP + REST (qualquer agente) |
| Coordenação | Nenhuma | Leases, signals, actions, routines |
| Observabilidade | Ler ficheiros manualmente | Visualizador em tempo real na :3113 |
---
### Pipeline de Memória
```text
PostToolUse hook fires
-> SHA-256 dedup (5min window)
-> Privacy filter (strip secrets, API keys)
-> Store raw observation
-> Synthetic compression by default
(LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
-> Vector embedding when an embedding provider is active
-> Index in BM25, plus vectors when enabled
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
-> Slot reflection (if SLOT_REFLECT_ENABLED=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
-> Inject into conversation
```
### Consolidação de Memória em 4 Níveis
Modelada em como os cérebros humanos processam a memória, incluindo a consolidação durante o sono.
| Nível | O que é | Analogia |
|------|------|---------|
| **Working** | Observações em bruto do uso de ferramentas | Memória de curto prazo |
| **Episodic** | Resumos comprimidos de sessões | "O que aconteceu" |
| **Semantic** | Factos e padrões extraídos | "O que eu sei" |
| **Procedural** | Workflows e padrões de decisão | "Como fazer" |
As memórias decaem com o tempo (curva de Ebbinghaus). As memórias acedidas frequentemente fortalecem-se. As memórias obsoletas são removidas automaticamente. As contradições são detetadas e resolvidas.
### O Que É Capturado
| Hook | Captura |
|------|----------|
| `SessionStart` | Caminho do projeto, ID da sessão |
| `UserPromptSubmit` | Prompts do utilizador (filtrados por privacidade) |
| `PreToolUse` | Padrões de acesso a ficheiros + contexto enriquecido |
| `PostToolUse` | Nome da ferramenta, entrada, saída |
| `PostToolUseFailure` | Contexto do erro |
| `PreCompact` | Reinjeta memória antes da compactação |
| `SubagentStart/Stop` | Ciclo de vida do subagente |
| `Stop` | Resumo de fim de sessão |
| `SessionEnd` | Marcador de sessão concluída |
### Principais Capacidades
| Capacidade | Descrição |
|---|---|
| **Captura automática** | Todo o uso de ferramentas é registado através de hooks, sem esforço manual |
| **Pesquisa semântica** | BM25 + vetor + grafo de conhecimento com fusão RRF |
| **Evolução da memória** | Versionamento, substituição, grafos de relações |
| **Higiene do recall** | As versões de memória substituídas saem dos índices de pesquisa; a cadeia de versões no KV mantém o histórico completo |
| **Avisos de quase-duplicados** | Ao guardar, é reportada uma correspondência consultiva `similarTo` quando o novo conteúdo se parece muito com uma memória existente |
| **Âmbito por agente** | O `agentId` percorre a gravação e o recall em REST, MCP e no índice de pesquisa, em modo partilhado ou isolado |
| **Proveniência no momento da escrita** | Toda observação e memória transporta um canal de origem imutável (user, agent, tool, import, ou shared) marcado na captura, na gravação e na importação |
| **Esquecimento automático** | Expiração por TTL, deteção de contradições, remoção por importância |
| **Privacidade primeiro** | Chaves de API, segredos e tags `` são removidos antes do armazenamento |
| **Auto-recuperação** | Circuit breaker, cadeia de fallback de fornecedores, monitorização de saúde |
| **Ponte com o Claude** | Sincronização bidirecional com o MEMORY.md |
| **Grafo de conhecimento** | Extração de entidades + travessia BFS |
| **Memória de equipa** | Partilhada e privada, com namespaces, entre os membros da equipa |
| **Proveniência de citações** | Rastreia qualquer memória até às observações de origem |
| **Snapshots Git** | Versiona, reverte e compara (diff) o estado da memória |
---
Recuperação de três fluxos, combinando três sinais:
| Fluxo | O que faz | Quando |
|---|---|---|
| **BM25** | Correspondência de palavras-chave com stemming e expansão de sinónimos | Sempre ativo |
| **Vetor** | Similaridade de cosseno sobre embeddings densos | Fornecedor de embeddings configurado |
| **Grafo** | Travessia do grafo de conhecimento via correspondência de entidades | Entidades detetadas na query |
Combinados com Reciprocal Rank Fusion (RRF, k=60) e diversificados por sessão (máximo de 3 resultados por sessão).
Quando um índice vetorial está preenchido, o `mem::search` (por trás de `memory_recall`) usa o ranker híbrido BM25 + vetor. Sem embeddings, usa o BM25. O `smart-search` pode ainda combinar correspondências estruturais do grafo quando existem dados de grafo, inclusive em modo sem chave. O recall de lessons corre sobre um índice BM25 dedicado em memória, em vez de percorrer todo o corpus a cada query. As versões de memória substituídas são excluídas de todos os caminhos de recall; a cadeia de versões mantém o seu histórico.
Os vetores sobrevivem a um crash ou a uma paragem forçada. O índice vetorial é guardado em blocos no máximo a cada `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minutos). Cada vetor adicionado ou removido entretanto também é escrito imediatamente num pequeno registo pendente no state store, e o arranque seguinte reproduz esse registo sem chamar o fornecedor de embeddings. Cada gravação bem-sucedida esvazia o registo. Os documentos que ainda não têm vetor depois da reprodução são re-embutidos (re-embedded) em segundo plano, em lotes de `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500), até não restar nenhum, e um preenchimento retroativo (backfill) interrompido continua no arranque seguinte. O `/agentmemory/status` e o visualizador mostram o tamanho do registo pendente e o estado do backfill. As instalações sem chave não escrevem nada.
O BM25 tokeniza grego, cirílico, hebraico, árabe e latim acentuado de fábrica. Para memórias em chinês / japonês / coreano, instale os segmentadores opcionais (`npm install @node-rs/jieba tiny-segmenter`) para dividir sequências CJK em tokens ao nível da palavra; sem eles, o agentmemory recua suavemente para a tokenização da sequência completa e imprime uma dica única no stderr.
### Fornecedores de Embeddings
As instalações sem chave desativam os embeddings vetoriais: o `mem::search` usa BM25, enquanto o `smart-search` também pode usar dados estruturais de grafo já existentes. Para optar por embeddings semânticos locais e gratuitos, adicione isto a `~/.agentmemory/.env` e reinicie o agentmemory:
```env
EMBEDDING_PROVIDER=local
```
A instalação normal via npm inclui o runtime opcional `@huggingface/transformers`. O primeiro pedido de embedding faz o download de `Xenova/all-MiniLM-L6-v2`, por isso precisa de acesso à rede e pode demorar mais; a inferência seguinte corre localmente. Os fornecedores remotos são detetados automaticamente a partir das suas chaves, a menos que `EMBEDDING_PROVIDER` os substitua.
| Fornecedor | Modelo | Custo | Notas |
|---|---|---|---|
| **Local (opt-in recomendado)** | `all-MiniLM-L6-v2` | Gratuito | No dispositivo após o primeiro download do modelo, +8pp de recall sobre apenas BM25 |
| Gemini | `gemini-embedding-001` | Nível gratuito | 100+ idiomas, dimensões 768/1536/3072 (MRL), entrada de 2048 tokens. Substitui o `text-embedding-004` ([descontinuado, encerramento a 14 de janeiro de 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
| OpenAI | `text-embedding-3-small` | $0.02/1M | Qualidade mais alta |
| Voyage AI | `voyage-code-3` | Pago | Otimizado para código |
| Cohere | `embed-english-v3.0` | Teste gratuito | Uso geral |
| OpenRouter | Qualquer modelo | Varia | Proxy multimodelo |
---
54 ferramentas, 6 recursos, 3 prompts e 17 skills.
> **Shim MCP vs servidor completo:** o pacote publicado `@agentmemory/mcp` é um shim fino. Expõe a superfície completa de 54 ferramentas **apenas quando consegue alcançar um servidor agentmemory em execução** através de `AGENTMEMORY_URL` (modo proxy). Sem nenhum servidor acessível, o shim recua para um conjunto local de 7 ferramentas (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). A variável de ambiente `AGENTMEMORY_TOOLS=core|all` é uma flag *do lado do servidor*; defini-la no bloco `env` do shim não tem efeito. Se só vir 7 ferramentas no Cursor / OpenCode / Gemini CLI, inicie `npx -y @agentmemory/agentmemory@latest` (ou a stack Docker) e defina `AGENTMEMORY_URL=http://localhost:3111`.
### 54 Ferramentas
Três superfícies de ferramentas, da mais pequena à maior: `AGENTMEMORY_TOOLS=core` reduz a visibilidade a 8 essenciais (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); o conjunto base abaixo são as 14 ferramentas fundamentais do registo; a predefinição (`AGENTMEMORY_TOOLS=all`) expõe todas as 54.
Ferramentas base (14)
| Ferramenta | Descrição |
|------|-------------|
| `memory_recall` | Pesquisar observações passadas |
| `memory_compress_file` | Comprimir ficheiros markdown preservando a estrutura |
| `memory_save` | Guardar uma perceção, decisão ou padrão |
| `memory_file_history` | Observações passadas sobre ficheiros específicos |
| `memory_patterns` | Detetar padrões recorrentes |
| `memory_sessions` | Listar sessões recentes |
| `memory_smart_search` | Pesquisa híbrida semântica + palavra-chave |
| `memory_vision_search` | Pesquisar observações de imagens |
| `memory_timeline` | Observações cronológicas |
| `memory_profile` | Perfil do projeto (conceitos, ficheiros, padrões) |
| `memory_export` | Exportar todos os dados de memória |
| `memory_relations` | Consultar o grafo de relações |
| `memory_commit_lookup` | Sessões por trás de um commit git |
| `memory_commits` | Commits registados para uma sessão |
Ferramentas avançadas (54 no total, a superfície predefinida)
| Ferramenta | Descrição |
|------|-------------|
| `memory_patterns` | Detetar padrões recorrentes |
| `memory_timeline` | Observações cronológicas |
| `memory_relations` | Consultar o grafo de relações |
| `memory_graph_query` | Travessia do grafo de conhecimento |
| `memory_consolidate` | Executar a consolidação em 4 níveis |
| `memory_claude_bridge_sync` | Sincronizar com o MEMORY.md |
| `memory_team_share` | Partilhar com membros da equipa |
| `memory_team_feed` | Itens partilhados recentes |
| `memory_audit` | Registo de auditoria das operações |
| `memory_governance_delete` | Eliminar com registo de auditoria |
| `memory_snapshot_create` | Snapshot versionado em Git |
| `memory_action_create` | Criar itens de trabalho com dependências |
| `memory_action_update` | Atualizar o estado de uma action |
| `memory_frontier` | Actions desbloqueadas, ordenadas por prioridade |
| `memory_next` | A próxima action mais importante |
| `memory_lease` | Leases exclusivos de actions (multiagente) |
| `memory_routine_run` | Instanciar routines de workflow |
| `memory_signal_send` | Mensagens entre agentes |
| `memory_signal_read` | Ler mensagens com confirmações de leitura |
| `memory_checkpoint` | Portões de condição externos |
| `memory_mesh_sync` | Sincronização P2P entre instâncias |
| `memory_sentinel_create` | Vigilantes orientados a eventos |
| `memory_sentinel_trigger` | Disparar sentinels externamente |
| `memory_sketch_create` | Grafos de actions efémeros |
| `memory_sketch_promote` | Promover a permanente |
| `memory_crystallize` | Compactar cadeias de actions |
| `memory_diagnose` | Verificações de saúde |
| `memory_heal` | Corrigir automaticamente estados bloqueados |
| `memory_facet_tag` | Tags dimensão:valor |
| `memory_facet_query` | Consultar por tags de faceta |
| `memory_verify` | Rastrear proveniência |
### 6 Recursos · 3 Prompts · 17 Skills
| Tipo | Nome | Descrição |
|------|------|-------------|
| Recurso | `agentmemory://status` | Saúde, contagem de sessões, contagem de memórias |
| Recurso | `agentmemory://project/{name}/profile` | Inteligência por projeto |
| Recurso | `agentmemory://project/{name}/recent` | Observações recentes de um projeto |
| Recurso | `agentmemory://memories/latest` | As últimas 10 memórias ativas |
| Recurso | `agentmemory://graph/stats` | Estatísticas do grafo de conhecimento |
| Recurso | `agentmemory://team/{id}/profile` | Perfil de equipa partilhado |
| Prompt | `recall_context` | Pesquisar e devolver mensagens de contexto |
| Prompt | `session_handoff` | Dados de handoff entre agentes |
| Prompt | `detect_patterns` | Analisar padrões recorrentes |
| Skill | `/recall` | Pesquisar na memória |
| Skill | `/remember` | Guardar na memória de longo prazo |
| Skill | `/session-history` | Resumos de sessões recentes |
| Skill | `/forget` | Eliminar observações/sessões |
A tabela mostra as quatro skills principais. O conjunto completo é de 9 skills invocáveis mais 8 skills de referência; ver a secção de skills nativas acima.
### MCP Standalone
Execute sem o servidor completo, para qualquer cliente MCP. Qualquer uma destas opções funciona:
```bash
npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
npx -y @agentmemory/mcp # shim package alias
```
Ou adicione à configuração MCP do seu agente:
Na maioria dos agentes (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
```json
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "http://localhost:3111"
}
}
}
}
```
Combine a entrada `agentmemory` com o objeto `mcpServers` já existente do seu anfitrião, em vez de substituir o ficheiro. Para clientes em sandbox que não conseguem alcançar o `localhost` do anfitrião, adicione `"AGENTMEMORY_FORCE_PROXY": "1"` ao bloco env e defina `AGENTMEMORY_URL` para uma rota que a sandbox consiga alcançar.
OpenCode (`opencode.json`):
```json
{
"mcp": {
"agentmemory": {
"type": "local",
"command": ["npx", "-y", "@agentmemory/mcp"],
"enabled": true
}
},
"plugin": ["./plugins/agentmemory-capture.ts"]
}
```
Copie o ficheiro do plugin a partir do repositório:
```bash
mkdir -p ~/.config/opencode/plugins
cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
```
---
Inicia-se automaticamente na porta `3113`. O visualizador carrega um snapshot quando se liga (`GET /agentmemory/viewer/snapshot`) e depois aplica eventos de stream em direto: novas memórias, lessons, observações, entradas de auditoria, alterações no grafo e atualizações de saúde aparecem sem polling ou recarregamentos de página. Os únicos outros pedidos são as ações em que clica, as páginas "carregar mais" e as pesquisas. Quando o stream cai, o visualizador mostra há quanto tempo os seus números estão desatualizados, volta a ligar-se com backoff e volta a sincronizar a partir de um snapshot.
- **12 separadores em quatro grupos**, com contagens em direto, deep links (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), atalhos de teclado e um menu para dispositivos móveis.
- **Memories:** pesquisa do lado do servidor, filtros por projeto, agente e tipo, um painel de detalhe com a cadeia de versões e um diff por palavras, ligações de proveniência, botões para copiar o id, a chamada MCP e um comando curl, edição (uma nova versão), esquecer com confirmação, esquecer em massa e exportação JSON.
- **Sessions:** uma linha do tempo de observações inline, com entrada e saída de ferramentas legíveis, filtros e paginação, e as memórias e lessons que cada sessão produziu.
- **Graph:** pesquisa, detalhe de nó com relações e fontes, uma legenda que não depende apenas da cor, e controlos de zoom.
- **Health:** a versão em direto de `GET /agentmemory/status`. Todos os problemas vêm com a respetiva correção, mais o state backend, o estado de gravação do índice, o progresso da compactação de proveniência do grafo e um explicador de consolidação com os limiares reais.
- Páginas **Audit, Activity, Profile, Replay, Lessons, Actions e Crystals**, cada uma com um estado vazio que explica o que é a secção, porque está vazia e o comando que a preenche, e uma tooltip de glossário `?` em todos os termos e números.
```bash
open http://localhost:3113
```
O servidor do visualizador faz bind em `127.0.0.1` por predefinição e junta o segredo do servidor quando reencaminha pedidos para a REST API, por isso não precisa de nenhuma configuração. O endpoint `/agentmemory/viewer`, servido pelo REST, segue as regras normais de bearer-token e redireciona os browsers sem token para a porta do visualizador. Os cabeçalhos CSP usam um nonce de script por resposta e desativam atributos de handler inline (`script-src-attr 'none'`).
---
O visualizador na `:3113` mostra o que o seu agente **se lembrou**. A [iii console](https://iii.dev/docs/console) mostra o que o seu agente **fez**: cada operação de memória como um trace OpenTelemetry, cada entrada KV editável, cada função invocável, cada stream acessível. Duas janelas sobre a mesma memória: uma moldada como produto, outra moldada como engine.
Veja um `memory_smart_search` a disparar e observe a varredura BM25 → consulta de embedding → fusão RRF → reranker como uma waterfall. Edite um temporizador de consolidação bloqueado no navegador de KV. Reproduza um hook `PostToolUse` com um payload ajustado. Fixe o stream WebSocket e veja as observações a chegar em direto.
O agentmemory oferece isto de graça, porque cada chamada de função e cada trigger disparam através do iii; nada personalizado, nada para instrumentar.
Página Workers: cada worker conectado, incluindo o próprio agentmemory, com PID, contagem de funções, runtime e última atividade (last-seen).
**Já vem instalada.** A console é distribuída com o engine `iii` fixado (0.22+); não há nada separado para instalar. O primeiro arranque faz o download do binário da console junto ao engine.
**Iniciar junto com o agentmemory:**
```bash
agentmemory console
```
Isto executa o `iii console` do engine fixado contra as portas que o agentmemory resolveu (REST, streams, bridge) e serve-a uma porta acima do visualizador, `http://localhost:3114` por predefinição. `--console-port N` escolhe outra porta; `--port` e `--instance` selecionam a instância do agentmemory da mesma forma que fazem para o `stop`; qualquer outra flag é passada adiante, por exemplo `--enable-flow` para a página experimental de grafo de arquitetura.
O mesmo à mão, útil quando o `agentmemory` não está no PATH:
```bash
~/.agentmemory/bin/iii console --port 3114 \
--engine-port 3111 \
--ws-port 3112 \
--bridge-port 49134
```
**O que pode fazer a partir da console:**
| Página | Use-a para |
|------|-----------|
| **Workers** | Ver cada worker conectado e as suas métricas em direto, incluindo o próprio worker do agentmemory. |
| **Functions** | Invocar diretamente qualquer função do agentmemory com um payload JSON; útil para testar `memory.recall`, `memory.consolidate`, `graph.query` sem ligar um cliente. |
| **Triggers** | Reproduzir triggers de HTTP, cron, event e state: disparar manualmente o cron de consolidação, repetir uma rota HTTP, emitir uma alteração de estado. |
| **States** | Navegador de KV com CRUD completo sobre sessões, slots de memória, temporizadores de ciclo de vida e o índice de embeddings; edite valores no próprio local. |
| **Streams** | Monitor de WebSocket em direto para escritas de memória, eventos de hook e atualizações de observações, a fluir pelos streams do iii. |
| **Queues** | Tópicos de fila duráveis + gestão de dead-letter. Reproduza ou descarte jobs falhados de embedding / compressão. |
| **Traces** | Vistas waterfall / flame / por serviço do OpenTelemetry. Filtre por `trace_id` para ver exatamente que funções, chamadas à BD e pedidos de embedding um único `memory.search` produziu. |
| **Logs** | Logs OTEL estruturados, filtrados e correlacionados com IDs de trace/span. |
| **Config** | Configuração de runtime: veja exatamente com que workers, fornecedores e portas o seu engine está a correr. |
| **Flow** | (Opcional, `--enable-flow`) Grafo de arquitetura interativo de cada worker, trigger e stream. |
Traces: waterfall / flame / por serviço para cada operação de memória.
**Os traces já estão ativos:**
O `iii-config.yaml` já vem com o worker `iii-observability` ativado (`exporter: memory`, `sampling_ratio: 0.1`, métricas + logs). Não precisa de configuração extra; no momento em que o agentmemory inicia, toda a operação de memória emite um log estruturado que a console consegue ler, e uma em cada dez (`sampling_ratio: 0.1`) também emite um span de trace.
Se preferir exportar para Jaeger/Honeycomb/Grafana Tempo, mude `exporter: memory` para `exporter: otlp` e defina o endpoint do collector de acordo com a documentação de observabilidade do iii.
> **Atenção:** a console em si não impõe autenticação; mantenha-a vinculada a `127.0.0.1` (a predefinição) e nunca a exponha publicamente.
---
O agentmemory **já é uma instância [iii](https://iii.dev) em execução**. Três primitivos (worker, function, trigger) compõem o runtime; o estado KV, os streams e os traces OTEL vêm dos workers iii-state, iii-stream e iii-observability que acompanham o iii. Não instalou Postgres, Redis, Express, pm2 ou Prometheus, porque o iii os substitui.
Isso significa que mais um comando estende o agentmemory com uma capacidade completamente nova.
### Estender o agentmemory com Mais Workers
Os builtins de que o agentmemory precisa já estão em `iii-config.yaml` e arrancam com ele: `iii-state` (KV), `iii-queue` (retries duráveis para os subscritores de eventos), `iii-pubsub`, `iii-cron`, `iii-stream`, e `iii-observability` (traces, métricas e logs OTEL em cada função). Qualquer outra coisa do [registo de workers do iii](https://workers.iii.dev) encaixa-se no mesmo engine: copie `iii-config.yaml` para `~/.agentmemory/iii-config.yaml` (o CLI prefere esse ficheiro em vez do incluído, e continua a renderizar portas e caminhos de dados nele), adicione a entrada, instale o runtime do worker uma vez com `~/.agentmemory/bin/iii update worker`, e reinicie o agentmemory.
```yaml
workers:
# ...the bundled entries...
- name: database # SQL-backed state adapter when you outgrow the KV defaults
- name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
- name: mcp # extra MCP servers next to agentmemory's, same engine
```
| Worker | O que ganha para além do agentmemory |
|---|---|
| [`database`](https://workers.iii.dev/workers/database) | Um adaptador de estado baseado em SQL, quando ultrapassar as predefinições de KV em memória |
| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | O código que saiu do `memory_recall` corre dentro de uma VM descartável, não na sua shell |
| [`mcp`](https://workers.iii.dev/workers/mcp) | Monte servidores MCP adicionais ao lado do do agentmemory, partilhando o mesmo engine |
No engine 0.22.x mantenha os nomes com o prefixo `iii-` para os builtins acima; as entradas sem prefixo `http`, `state`, `queue`, `pubsub` e `cron` são os workers standalone do registo para os quais o agentmemory migra com a atualização para 0.23.
Registo completo: [workers.iii.dev](https://workers.iii.dev). Todos os workers aí compõem-se através dos mesmos primitivos que o agentmemory usa, e o agentmemory que já tem é um deles.
### Configuração do Engine e Endereço de Bind
O `agentmemory start` lê a configuração do engine a partir do primeiro ficheiro que existir: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` no diretório atual, `~/.agentmemory/iii-config.yaml`, e depois o `iii-config.yaml` incluído. A cada arranque, renderiza esse ficheiro (caminhos de dados, portas, state backend) para `~/.agentmemory/data/iii-config.runtime.yaml` e lança o engine com a cópia renderizada, por isso edite o ficheiro de origem, não o renderizado. Os valores `host:` do ficheiro de origem são mantidos tal como foram escritos.
O `iii-config.yaml` incluído faz bind em `127.0.0.1` de propósito, e essa predefinição também se aplica dentro de um contentor. Um CLI iniciado num contentor escuta no loopback do contentor, por isso as portas publicadas não alcançam nada. Para servir um CLI em contentor através de portas publicadas, defina `AGENTMEMORY_III_CONFIG` para uma configuração que faça bind em `0.0.0.0`. O `iii-config.docker.yaml` empacotado é uma delas: faz bind do `iii-http`, do `iii-stream` e da porta do engine em `0.0.0.0` e guarda o estado em `/data`, por isso monte aí um volume com permissão de escrita. Mantenha `AGENTMEMORY_SECRET` definida, e publique apenas as portas de que precisa, em `127.0.0.1` ou por trás de um proxy de confiança.
O `docker-compose.yml` deste repositório não passa pela procura de configuração do CLI: monta `iii-config.docker.yaml` em `/app/config.yaml`, e o contentor `iii-engine` arranca com `--config /app/config.yaml`. Os [modelos de implementação](../deploy/) de um clique escrevem a sua própria configuração `0.0.0.0` nos respetivos entrypoints.
### Backend de Armazenamento: Ficheiro (predefinição) vs Redis
Por predefinição, o `iii-state` e o `iii-stream` usam o armazenamento KV baseado em ficheiro incluído no iii-engine: um ficheiro JSON por âmbito, mantido na memória do processo do engine e reescrito em disco periodicamente. Essa é a predefinição certa para uma instalação local de um só utilizador; um daemon partilhado com vários escritores concorrentes obtém, em vez disso, escritas reais por chave a partir do Redis, ao custo de uma viagem de rede por operação (cada chamada `state::*` continua a serializar numa única ligação Redis, por isso isto troca o lock do armazenamento de ficheiro por um socket, não por paralelismo).
Defina `AGENTMEMORY_STATE_BACKEND=redis` (mais `AGENTMEMORY_REDIS_URL`) para mudar ambos os workers para o adaptador `redis` incluído no iii-engine, que guarda cada chave como um campo de hash Redis (`HSET`) em vez de reescrever um âmbito inteiro a cada escrita:
```env
# ~/.agentmemory/.env
AGENTMEMORY_STATE_BACKEND=redis
AGENTMEMORY_REDIS_URL=redis://localhost:6379
```
O `AGENTMEMORY_STATE_BACKEND` assume `file` por predefinição; deixá-lo sem definir mantém o comportamento atual inalterado, e um valor não reconhecido (qualquer coisa que não seja `file` ou `redis`) é um erro de arranque, em vez de um fallback silencioso. O `/agentmemory/status` e a página Health do visualizador (a linha State store) reportam qual o backend ativo e se responde, nunca o URL.
**Apenas `redis://` simples.** O engine fixado (0.22.1) constrói o seu cliente Redis sem suporte para TLS, por isso um URL `rediss://` (a maioria das ofertas Redis geridas, como Upstash, Redis Cloud, e ElastiCache com encriptação em trânsito, assumem TLS por predefinição) falha a ligação. A ligação não é encriptada, por isso a password do Redis e cada memória guardada atravessam a rede em texto simples: aponte para um Redis local ou um numa rede privada de confiança. Para qualquer outro Redis, corra um túnel encriptado (stunnel, SSH ou uma VPN) no anfitrião do agentmemory, para que o salto `redis://` simples fique nesse anfitrião e a ligação a montante do túnel seja encriptada e autenticada. Se uma password do Redis contiver um apóstrofo, codifique-o em percentagem (`%27`); o engine expande o URL para dentro da sua configuração YAML antes de o analisar.
**Um servidor Redis por `--instance`.** Os prefixos de chave Redis do engine (`state:`, `stream::`) são fixos, por isso duas instâncias do agentmemory (`--instance 1`, `--instance 2`, ...) a apontar para a mesma base de dados sobrescrevem os dados uma da outra. Um índice de base de dados separado (`redis://localhost:6379/1`) mantém os dados guardados separados, mas o engine retransmite os eventos do visualizador em direto através de um único canal Redis pub/sub (`stream::events`), e o pub/sub do Redis ignora o índice de base de dados, por isso o visualizador de cada instância continuaria a mostrar os eventos em direto da outra. Dê a cada instância o seu próprio servidor Redis (ou porta) quando executar mais do que uma.
**O que fica igual, e o que é diferente.** Todas as funcionalidades do agentmemory funcionam sobre Redis: sessões, observações, memórias (remember, supersede, evolve, forget), pesquisa e os blocos do índice, lessons, o grafo, o registo de auditoria e os seus âmbitos mensais, exportação e importação, governance deletes, estado de consolidação, o snapshot do visualizador e o seu stream em direto, e o monitor de saúde. O engine guarda cada âmbito como um único hash Redis (`HSET`/`HGET`/`HGETALL`) e dispara os mesmos state triggers que o armazenamento de ficheiro. Três diferenças do engine são tratadas dentro do agentmemory:
- O Redis devolve os registos de um âmbito sem ordem fixa. O agentmemory ordena-os do mais antigo para o mais recente (pela data de criação no id do registo, depois pelo seu timestamp), para que listas, paginação e blocos de exportação voltem na mesma ordem que no armazenamento de ficheiro.
- O engine aplica atualizações parciais no Redis através de um script Lua que transforma arrays vazios em objetos vazios. O agentmemory aplica essas atualizações ele próprio (ler, alterar, escrever sob um lock por chave) no Redis, para que campos como `tags: []` permaneçam arrays.
- A verificação do registo de auditoria legado lê o âmbito antigo a partir do Redis, em vez de procurar o ficheiro do armazenamento de ficheiro em disco.
Uma diferença precisa da sua intervenção: **depois de o Redis reiniciar, o engine deixa de retransmitir eventos em direto** para o visualizador até o agentmemory reiniciar. Os dados continuam a ser guardados e lidos normalmente. O monitor de saúde envia um evento de teste através do Redis a cada 30 segundos; quando este não volta, o `/agentmemory/status` e a página Health do visualizador mostram "Live updates are not reaching the viewer", com a correção: reinicie o agentmemory. Se o Redis estiver em baixo, o relatório de estado mostra "The state store is not answering" e como verificá-lo (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Listar um âmbito muito grande lê o hash inteiro num único `HGETALL`, o mesmo custo de o armazenamento de ficheiro o manter em memória.
**Definições Redis recomendadas.** A política de snapshot predefinida `save 3600 1 300 100 60 10000` pode perder minutos de escritas num crash, pior do que a janela de 5s de flush do armazenamento de ficheiro. Defina `appendonly yes` para tudo o que não queira perder. Defina `maxmemory-policy noeviction`; `allkeys-lru` ou semelhante descarta memórias silenciosamente quando o Redis atinge o seu limite de memória.
Um arranque nativo (sem Docker), e todos os [modelos de implementação](../deploy/) de um clique (que sobrescrevem o `iii-config.yaml` incluído e arrancam nativamente), leem `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` e renderizam-nos no `iii-config` lançado. O URL em si nunca é escrito nesse ficheiro renderizado, apenas uma referência `${AGENTMEMORY_REDIS_URL}` que o processo do engine expande a partir do seu próprio ambiente no arranque. Só o caminho de Docker Compose deste repositório (`AGENTMEMORY_USE_DOCKER=1`, ou retomar um engine já iniciado dessa forma) monta `iii-config.docker.yaml` em modo só de leitura e nunca renderiza; o `agentmemory start` avisa quando deteta essa combinação. Troque esse ficheiro à mão, seguindo o mesmo formato `name: redis` / `config: redis_url: ...` mostrado na documentação dos workers [iii-state](https://workers.iii.dev/workers/iii-state) e [iii-stream](https://workers.iii.dev/workers/iii-stream), e aponte `redis_url` para um Redis acessível a partir do contentor. O `docker-compose.yml` passa `AGENTMEMORY_REDIS_URL` para o contentor do engine, por isso `redis_url: '${AGENTMEMORY_REDIS_URL}'` funciona aí e mantém o URL fora do ficheiro montado.
A configuração renderizada mantém o URL fora de `~/.agentmemory/data/iii-config.runtime.yaml`, mas o próprio worker de configuração do engine ainda persiste o valor *expandido* em `~/.agentmemory/config/iii-state.yaml` e `iii-stream.yaml` depois de arrancar (a expansão `${VAR}` do iii-engine acontece antes de esse worker guardar a sua seed, e guarda o valor resolvido, não a referência). Trate esse diretório como contendo uma credencial: `chmod 700 ~/.agentmemory` em qualquer anfitrião partilhado, e prefira um utilizador Redis ACL limitado ao que o agentmemory precisa, em vez das credenciais de administrador da base de dados.
**A migração não é automática.** Mudar `AGENTMEMORY_STATE_BACKEND` parte de um armazenamento vazio em qualquer um dos lados; nada copia os dados existentes de ficheiro para Redis ou vice-versa. Exporte a partir do backend que está a deixar e importe para aquele para o qual está a mudar. Isto corre de forma idêntica em bash e zsh (incluindo `bash -u`). Um array como `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` não corre: o zsh mantém o header como uma única palavra malformada, onde o bash o divide em duas, por isso ambos os pedidos recebem 401 sempre que `AGENTMEMORY_SECRET` está definida:
```bash
# 0. Use the generated secret when none is exported:
AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
# 1. On the old backend, while agentmemory is still running on it:
if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
else
curl -fsS http://localhost:3111/agentmemory/export > backup.json
fi
# 2. Confirm backup.json is a usable export before switching backends:
jq -e '.version and .exportedAt' backup.json > /dev/null || {
echo "backup.json is not a valid export; do not switch backends" >&2
exit 1
}
# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
# restart agentmemory against the new backend, then:
if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
-H 'Content-Type: application/json' -d @-
else
jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
curl -fsS -X POST http://localhost:3111/agentmemory/import \
-H 'Content-Type: application/json' -d @-
fi
```
O `/agentmemory/export` também aceita `?maxSessions=` e `?offset=` para dividir um corpus grande em várias chamadas; o `strategy` na importação é `merge` (seguro por predefinição), `replace`, ou `skip`.
### O Que o iii Substitui
| Stack tradicional | O agentmemory usa |
|---|---|
| Express.js / Fastify | iii HTTP Triggers |
| SQLite / Postgres + pgvector | iii KV State + índice vetorial em memória |
| SSE / Socket.io | iii Streams (WebSocket) |
| pm2 / systemd | supervisão de workers do iii engine |
| Prometheus / Grafana | iii OTEL + monitor de saúde |
| Sistemas de plugins personalizados | `iii worker add ` |
**219 ficheiros de código-fonte · ~52,000 LOC · 2,500+ testes · 311 funções · 60 âmbitos de KV**, tudo sobre três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.
---
### Fornecedores de LLM
O agentmemory deteta automaticamente fornecedores a partir do seu ambiente. Um fornecedor torna disponíveis as operações suportadas por LLM, mas a configuração do fornecedor por si só não ativa a compressão de observações escrita por LLM. Esse caminho exige tanto um fornecedor como `AGENTMEMORY_AUTO_COMPRESS=true`.
| Fornecedor | Configuração | Notas |
|----------|--------|-------|
| **No-op (predefinição)** | Sem configuração necessária | A compressão/resumo suportados por LLM estão desativados. A compressão sintética e o recall por BM25 continuam a funcionar. Ver `AGENTMEMORY_ALLOW_AGENT_SDK` abaixo, se costumava depender do fallback de subscrição Claude. |
| API da Anthropic | `ANTHROPIC_API_KEY` | Faturação por token |
| MiniMax | `MINIMAX_API_KEY` | Compatível com Anthropic |
| Gemini | `GEMINI_API_KEY` | Também ativa embeddings |
| OpenRouter | `OPENROUTER_API_KEY` | Qualquer modelo |
| API da OpenAI | `OPENAI_API_KEY` | Predefinição `gpt-5.6-luna`, substitua com `OPENAI_MODEL` |
| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) ou `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Qualquer coisa compatível com a API da OpenAI. Custo zero, corre no seu hardware. Ver [Modelos locais](#local-models-ollama--lm-studio--vllm) abaixo. |
| Fallback de subscrição Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Apenas opt-in. Cria sessões `@anthropic-ai/claude-agent-sdk`; costumava causar recursão ilimitada no hook Stop, por isso já não é a predefinição. |
### Modelos Locais (Ollama / LM Studio / vLLM)
O agentmemory comunica com qualquer servidor compatível com a API da OpenAI, por isso qualquer coisa que exponha `/v1/chat/completions` funciona sem alterações de código. Sem chaves pagas, sem nuvem, sem limites de taxa; corre inteiramente no seu hardware.
**Ollama** (porta predefinida `11434`):
```bash
ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
ollama serve
```
```env
# ~/.agentmemory/.env
OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen3:8b
```
**LM Studio** (porta predefinida `1234`):
Abra o LM Studio → separador Local Server → Start Server. Escolha qualquer modelo de chat no seletor (Qwen 3, gpt-oss, DeepSeek R1, etc.).
```env
# ~/.agentmemory/.env
OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
```
**vLLM / llama.cpp / Text Generation Inference**: mesmo formato. Aponte `OPENAI_BASE_URL` para o URL que o seu servidor expõe e defina `OPENAI_MODEL` para um nome que o seu servidor aceite.
**Escolhas de modelo para o trabalho de memória**: a compressão e o resumo são tarefas curtas (<2K tokens de entrada, <500 tokens de saída), onde um modelo instruct de 7B já é mais do que suficiente. Recomendações:
| Modelo | Tamanho | Porquê |
|-------|------|-----|
| `qwen3:8b` | ~5.2 GB | Predefinição equilibrada numa máquina de 16 GB; forte em extração e texto no formato de ferramentas |
| `qwen3:4b` | ~2.6 GB | A opção mais pequena ainda razoável; serve bem para compressão, mais fraca para extração de grafo |
| `qwen3-coder:30b` | ~19 GB | A melhor escolha local para sessões no formato de código (30B MoE, 3.3B ativos) em hardware de 24-32 GB |
| `gpt-oss:20b` | ~14 GB | Modelo geral forte que cabe em 16 GB de RAM |
| `deepseek-r1:8b` | ~5.2 GB | Destilação de raciocínio; mais lento, mas com extrações mais limpas |
Os modelos Qwen 3 raciocinam por predefinição e podem gastar todo o orçamento de tokens em raciocínio antes de qualquer saída. Defina `AGENTMEMORY_LLM_NOTHINK=1` para acrescentar `/no_think` aos prompts de extração de grafo, e aumente o `MAX_TOKENS` (16384 funciona) se as extrações voltarem vazias.
Modelos da classe de raciocínio (estilo `o1`, com blocos ``) podem devolver `content` vazio, com um campo `reasoning` que o seu servidor local pode não expor. Se as extrações voltarem em branco, mude primeiro para um modelo sem raciocínio. A variável de ambiente `OPENAI_REASONING_EFFORT=none` também pode desativar o raciocínio em modelos de pensamento do Ollama Cloud que espelham o esquema de raciocínio da OpenAI.
Os embeddings locais são distribuídos como dependência opcional, mas não estão ativados por predefinição. Defina `EMBEDDING_PROVIDER=local` para optar por `Xenova/all-MiniLM-L6-v2` (384 dimensões). O primeiro pedido de embedding faz o download do modelo; a inferência corre localmente a partir daí. Sem essa definição ou uma chave de embedding remota, os vetores ficam desativados, o `mem::search` usa BM25, e o `smart-search` ainda pode adicionar correspondências de grafo já existentes.
### Seleção de Modelo com Consciência de Custo
Quando a compressão em segundo plano escrita por LLM está ativada, com um fornecedor e `AGENTMEMORY_AUTO_COMPRESS=true`, esta corre em cada observação, por isso a escolha do modelo altera significativamente a despesa mensal. Dados de carga de trabalho capturados: 635 pedidos / 888K tokens / 35 horas de uso ativo, executados contra três modelos OpenRouter aos preços de 2026-05-23.
| Nível | Modelo | Entrada / 1M | Saída / 1M | Custo para as 35h capturadas | Notas |
|------|-------|------------|-------------|---------------------------|-------|
| Recomendado | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | O DeepSeek mais recente; a escolha recomendada mais económica para cargas de compressão. |
| Recomendado | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Qualidade sólida de compressão + resumo, a um custo ~10× mais baixo do que o Sonnet. |
| Recomendado | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Raciocínio de código forte, se as suas sessões forem fortemente orientadas a código. |
| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (est.) | Mesmo preço de tabela que a execução medida com o Sonnet 4.6; preço de lançamento de $2/$10 até 2026-08-31. |
| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | Nível topo de gama; caro para trabalho em segundo plano permanente. |
| Evitar | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | Modelo de classe topo de gama; gasto excessivo para compressão. |
As linhas medidas vêm da execução capturada; as linhas (est.) escalam a mesma mistura de tokens pelo preço de tabela de cada modelo.
O agentmemory imprime um aviso em runtime quando `OPENROUTER_MODEL` corresponde a um padrão de nível premium. Defina `AGENTMEMORY_SUPPRESS_COST_WARNING=1` para silenciar depois de fazer uma escolha informada.
Compromisso entre qualidade e custo para o trabalho de memória: a compressão é uma tarefa de resumo com barreiras de qualidade relativamente flexíveis (é o agente que volta a ler o resumo, não o utilizador). O DeepSeek V4 Flash / V4 Pro / Qwen3-Coder ficam dentro da margem de erro do Sonnet nesta tarefa, custando 10-70× menos. Guarde os modelos de nível premium para queries que você próprio lê diretamente.
Fontes: [Preços da OpenRouter para o Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [Notas de preços da DeepSeek](https://api-docs.deepseek.com/quick_start/pricing/).
### Memória Multiagente (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
Em configurações multiagente onde vários papéis partilham um servidor agentmemory (architect / developer / reviewer / researcher / support-agent), o `AGENT_ID` marca cada escrita com o papel que a fez. O `AGENTMEMORY_AGENT_SCOPE` controla se o recall filtra por essa marca.
```env
TEAM_ID=company
USER_ID=engineering-team
AGENT_ID=architect
AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
```
Dois modos:
| Modo | Marca escritas | Filtra o recall | Quando usar |
|------|------------|---------------|-------------|
| `shared` (predefinição) | sim | não | Contexto entre agentes, com registo de auditoria. O architect consegue ver o que o developer anotou, mas cada linha regista quem o disse. |
| `isolated` | sim | sim | Separação estrita. O architect nunca vê as observações / memórias / sessões do developer. |
O que é marcado quando `AGENT_ID` está definida: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. O papel flui de `api::session::start` → `mem::observe` → `mem::compress` → KV.
O que é filtrado no modo isolated: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Cada endpoint aceita `?agentId=` para substituir por pedido, e `?agentId=*` para sair completamente do âmbito do env. O `/memories` também aceita `?includeOrphans=true` para mostrar memórias anteriores ao AGENT_ID, cujo `agentId` está indefinido.
Substituição por chamada, na camada SDK / REST: todo o endpoint que escreve (`/session/start`, `/remember`) aceita um campo `agentId` no corpo do pedido, que vence o env. Útil para runtimes que encaminham muitos papéis através de um único processo de servidor. A ferramenta MCP `memory_save` expõe o mesmo campo `agentId`, o servidor stdio standalone reencaminha tanto `agentId` como `project`, e as memórias guardadas transportam `agentId` para o índice de pesquisa, por isso a pesquisa com âmbito de agente cobre tanto memórias como observações.
Quando `AGENT_ID` não está definida, a memória permanece sem âmbito (comportamento legado, sem marcas, sem filtros).
### Portas
O agentmemory + iii-engine fazem bind em quatro portas por predefinição. Se um reinício falhar com `port in use`, esta tabela diz-lhe que processo procurar.
| Porta | Processo | Finalidade | Substituição por env |
|------|---------|---------|--------------|
| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
| `3112` | iii-engine | Worker interno de streams (consumido pelo agentmemory + visualizador) | `III_STREAM_PORT` (preferido) ou o legado `III_STREAMS_PORT` |
| `3113` | agentmemory | Visualizador em tempo real (`http://localhost:3113`) | `III_VIEWER_PORT` ou `AGENTMEMORY_VIEWER_URL` para o URL reportado |
| `49134` | iii-engine | WebSocket; os workers registam-se aqui, a telemetria OTel flui por aqui | `III_ENGINE_PORT` ou `III_ENGINE_URL` |
`--port ` altera a âncora REST e deriva os streams para `N+1`, o visualizador para `N+2`, e o WebSocket do engine para `N+46023`, apenas onde a porta ou o URL explícitos correspondentes acima não estiverem definidos. Não cria um namespace de ciclo de vida isolado. Use `--instance 1` para um segundo daemon; este usa a âncora 3211, com predefinição `3211/3212/3213/49234`, e recebe um diretório de dados e de ciclo de vida `instance-1` separado. As instâncias 1 a 50 seguem o mesmo padrão.
O engine fixado arranca com `--no-update-check` (sem verificações de atualização ou de avisos de segurança contra o GitHub no arranque) e com a telemetria de uso anónima do iii desativada: o agentmemory define `III_TELEMETRY_ENABLED=false` para o engine que cria, a menos que exporte a variável você mesmo, e o ficheiro compose incluído faz o mesmo.
Limpeza de processos obsoletos, quando as portas continuam vinculadas depois de uma execução que terminou em crash:
```bash
# macOS / Linux — find whatever is on each port and kill it
lsof -i :3111,3112,3113,49134
pkill -f agentmemory || true
pkill -f 'iii ' || true
# Windows
netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID
```
O `agentmemory stop` recolhe de forma limpa tanto o worker como o pidfile do engine, num encerramento nativo gracioso. Em modo Docker, esvazia o worker nativo, para exatamente o contentor do engine validado, e preserva tanto o contentor como o seu mount `/data` para um reinício sem perdas; o arranque seguinte valida e retoma esse mesmo contentor. A desinstalação apoiada em Docker exige `agentmemory remove --keep-data`: remove os ficheiros partilhados geridos pelo agentmemory, preservando o contentor validado, o seu mount de dados, e o registo de ciclo de vida necessário para os recuperar. A eliminação destrutiva de dados do Docker é deixada intencionalmente ao operador, depois de uma cópia de segurança. O CLI também se recusa a adotar ou sinalizar detentores de portas do Docker ou de VM (backend do Docker, vpnkit, colima) como o engine nativo, a menos que `--force` seja passado. A limpeza manual acima é apenas para o caso pós-crash em que nenhum dos dois pidfiles ficou para trás.
### Ficheiro de Configuração
Coloque a configuração de runtime do agentmemory em `~/.agentmemory/.env`, em vez de exportar variáveis em todas as shells. Se o visualizador mostrar uma dica de configuração como `export ANTHROPIC_API_KEY=...`, copie-a para este ficheiro como `ANTHROPIC_API_KEY=...`, sem o prefixo `export`, e depois reinicie o agentmemory.
As variáveis de ambiente do processo continuam a funcionar e têm precedência sobre os valores no ficheiro.
No Windows, o mesmo ficheiro vive em `%USERPROFILE%\.agentmemory\.env`:
```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
notepad $HOME\.agentmemory\.env
```
Para testar com uma subscrição Claude Code Pro/Max em vez de uma chave de API, ative-o explicitamente:
```env
AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
```
A compressão de observações escrita por LLM exige ambas as linhas: acesso a um fornecedor de LLM (incluindo este fallback explícito de subscrição) e `AGENTMEMORY_AUTO_COMPRESS=true`. Um fornecedor, por si só, deixa o caminho predefinido de compressão sintética em vigor.
A consolidação (nós do grafo, lessons, crystals) está ativada por predefinição sempre que um fornecedor de LLM está configurado. Desative explicitamente com `CONSOLIDATION_ENABLED=false` se quiser operação sem LLM. A extração de grafo é uma flag separada:
```env
GRAPH_EXTRACTION_ENABLED=true
# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
```
### Variáveis de Ambiente
Crie `~/.agentmemory/.env`:
```env
# LLM provider (pick one — default is the no-op provider: no LLM calls)
# ANTHROPIC_API_KEY=sk-ant-...
# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
# GEMINI_API_KEY=...
# OPENROUTER_API_KEY=...
# MINIMAX_API_KEY=...
# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
# # OpenAI LLM provider (here) AND the OpenAI
# # embedding provider (further below). Set
# # OPENAI_API_KEY_FOR_LLM=false to scope it
# # to embeddings only.
# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
# # Azure: https://.openai.azure.com/openai/deployments/
# # Auto-detected from `.openai.azure.com` hostname; uses
# # api-key header + api-version query param.
# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
# # for back-compat with v0.9.17. New configs should
# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
# # Honored only by OpenAI's reasoning models (o1, o3,
# # gpt-*-reasoning) and providers that mirror that
# # schema (Ollama Cloud thinking models). Standard
# # chat models reject this field with 400. Set to
# # "none" for thinking models that return reasoning
# # but no content.
# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
# # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
# Embedding provider (BM25-only when unset; local is an explicit opt-in)
# EMBEDDING_PROVIDER=local
# VOYAGE_API_KEY=...
# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
# Outbound LLM / embedding timeout
# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
# raw-fetch provider (Gemini, OpenRouter, MiniMax,
# OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
# embedding). For the OpenAI LLM path, the
# OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
# takes precedence when set, for back-compat
# with v0.9.17.
# Increase for slow networks or large batch calls;
# decrease to fail-fast on rate-limit holds.
# Search tuning
# BM25_WEIGHT=0.4
# VECTOR_WEIGHT=0.6
# TOKEN_BUDGET=2000
# Auth (generated into ~/.agentmemory/secret on first start when unset)
# AGENTMEMORY_SECRET=your-secret
# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
# AGENTMEMORY_IMPORT_ROOT=~/projects
# Ports (defaults: 3111 API, 3113 viewer)
# III_REST_PORT=3111
# Engine usage telemetry (iii). Off unless you set it; true opts in.
# III_TELEMETRY_ENABLED=false
# Features
# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
# provider as well. When both are on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
# token spend on active sessions.
# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
# memory slots — persona,
# user_preferences, tool_guidelines,
# project_context, guidance,
# pending_items, session_patterns,
# self_notes. Size-limited; agent
# edits via memory_slot_* tools.
# Pinned slots addressable for
# SessionStart injection.
# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
# Stop hook fires mem::slot-reflect:
# scans recent observations, auto-
# appends TODOs to pending_items,
# counts patterns in
# session_patterns, records touched
# files in project_context. Fire-
# and-forget; does not block.
# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
# - SessionStart may inject ~1-2K
# chars of project context into
# the first turn of each session
# (this is what actually reaches
# the model — Claude Code treats
# SessionStart stdout as context)
# - PreToolUse fires /agentmemory/enrich
# on every file-touching tool call
# (resource cleanup, not a token
# fix — PreToolUse stdout is debug
# log only per Claude Code docs)
# Observations are still captured via
# PostToolUse regardless of this flag.
# GRAPH_EXTRACTION_ENABLED=false
# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
# model to skip its hidden thinking pass
# during graph extraction. Faster runs;
# relation quality can drop slightly.
# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
# LESSON_DECAY_ENABLED=true
# OBSIDIAN_AUTO_EXPORT=false
# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
# CLAUDE_MEMORY_BRIDGE=false
# SNAPSHOT_ENABLED=false
# Storage and durability
# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
# A hard kill loses at most this window.
# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
# shutdown and deletes still save at once.
# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
# provenance; false skips it
# Sessions
# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
# the threshold as abandoned. Deletes nothing;
# new activity makes the session active again.
# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
# Capture filters (hooks)
# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
# when set, only these tools are captured
# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
# defaults: memory_*, toolsearch,
# listmcpresources, fetchmcpresource
# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
# Audit log
# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
# rows (debugging only)
# Team
# TEAM_ID=
# USER_ID=
# TEAM_MODE=private
# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
# AGENTMEMORY_TOOLS=core
```
---
138 endpoints na porta `3111`. A REST API faz bind em `127.0.0.1` por predefinição. Os endpoints protegidos exigem `Authorization: Bearer `, e os endpoints de sincronização mesh exigem uma `AGENTMEMORY_SECRET` explicitamente definida em ambos os pares.
**A autenticação está ativa por predefinição.** Quando `AGENTMEMORY_SECRET` não está definida (na shell ou em `~/.agentmemory/.env`), o servidor gera um segredo aleatório no primeiro arranque e guarda-o em `~/.agentmemory/secret` com o modo `0600`. Todo o cliente incluído lê-o a partir daí quando fala com um servidor local: o CLI, o visualizador, os hooks em `plugin/scripts`, o servidor MCP e o shim `@agentmemory/mcp`, as configurações escritas por `agentmemory connect`, e as integrações incluídas do OpenCode, Pi, OpenClaw, Hermes e do filesystem-watcher. O segredo guardado só é enviado para URLs de loopback (`localhost`, `127.0.0.0/8`, `::1`). Uma `AGENTMEMORY_SECRET` explícita vence sempre, e os clientes remotos continuam a precisar de a ter definida. O Docker e os entrypoints de `deploy/` já geram e exportam o seu próprio segredo. Para chamar a API manualmente:
```bash
curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
```
**Regras de pedidos para escritas.** Os pedidos `POST`, `PUT`, `PATCH` e `DELETE` para a REST API e o visualizador têm de enviar `Content-Type: application/json` (um parâmetro `charset` é aceitável) sempre que transportem um corpo, e um cabeçalho `Origin`, quando presente, tem de ser uma origem de loopback para a porta REST ou do visualizador configurada, ou estar listado em `VIEWER_ALLOWED_ORIGINS` (separado por vírgulas, por exemplo `https://memory.example.com`). Os clientes que não enviam nenhum cabeçalho `Origin` (CLI, hooks, MCP, curl, servidor-a-servidor) não são afetados. O visualizador também aceita a sua própria origem.
**Caminhos de ficheiros.** Os endpoints que leem ou escrevem ficheiros (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) só aceitam caminhos dentro de `~/.agentmemory`, do diretório de dados da instância, ou de um diretório listado em `AGENTMEMORY_IMPORT_ROOT` (separe vários com `:`, ou `;` no Windows). O `/replay/import-jsonl` também aceita o seu predefinido `~/.claude/projects`. O `/obsidian/export` mantém-se dentro de `AGENTMEMORY_EXPORT_ROOT` e o `/migrate` dentro de `~/.agentmemory`. Os symlinks são resolvidos antes de cada verificação.
**Remoção de segredos.** As chaves de API, os bearer tokens, os blocos de chave privada PEM e as credenciais incorporadas em URLs (`scheme://user:password@host`) são ocultados antes de o texto ser guardado, em todos os caminhos de escrita: observations, remember, evolve, slots, lessons, actions, sketches, signals, checkpoints, imports, jsonl replay, mesh sync, team shares, saída de compressão e de resumo, crystals e nós do grafo.
Endpoints principais
| Método | Caminho | Descrição |
|--------|------|-------------|
| `GET` | `/agentmemory/health` | Verificação de saúde (sempre pública) |
| `GET` | `/agentmemory/status` | O que está errado e como corrigir (HTML para browsers, JSON de resto) |
| `GET` | `/agentmemory/viewer/snapshot` | Tudo o que o visualizador mostra, numa única resposta |
| `POST` | `/agentmemory/session/start` | Iniciar sessão + obter contexto |
| `POST` | `/agentmemory/session/end` | Terminar sessão |
| `POST` | `/agentmemory/observe` | Capturar observação (ver a entrega de captura abaixo) |
| `GET` | `/agentmemory/capture` | Caixa de entrada de captura, dead letters e spool offline |
| `POST` | `/agentmemory/capture/retry` | Repetir capturas em dead-letter |
| `POST` | `/agentmemory/capture/drain` | Enviar agora o spool offline local |
| `POST` | `/agentmemory/smart-search` | Pesquisa híbrida |
| `POST` | `/agentmemory/context` | Gerar contexto |
| `POST` | `/agentmemory/remember` | Guardar na memória de longo prazo |
| `POST` | `/agentmemory/forget` | Eliminar observações |
| `POST` | `/agentmemory/enrich` | Contexto de ficheiro + memórias + bugs |
| `GET` | `/agentmemory/profile` | Perfil do projeto |
| `GET` | `/agentmemory/export` | Exportar todos os dados |
| `POST` | `/agentmemory/import` | Importar a partir de JSON |
| `POST` | `/agentmemory/graph/query` | Consulta ao grafo de conhecimento |
| `POST` | `/agentmemory/graph/compact` | Reduzir a proveniência de grafo sobredimensionada |
| `POST` | `/agentmemory/team/share` | Partilhar com a equipa |
| `GET` | `/agentmemory/audit` | Registo de auditoria |
Lista completa de endpoints: [`src/triggers/api.ts`](../src/triggers/api.ts)
**Entrega de captura.** Os hooks enviam cada observação uma vez para `POST /agentmemory/observe`, com um `eventId`. Este é o próprio id do anfitrião para a chamada, quando o payload tem um (por exemplo, o `tool_use_id` do Claude Code), caso contrário é um hash da sessão, do tipo de hook, do nome da ferramenta, da entrada, da saída e do timestamp do anfitrião. O servidor escreve o evento numa caixa de entrada de captura no state store, guarda a observação, e depois remove a entrada da caixa de entrada. O código de estado diz o que aconteceu:
| Estado | Campo `status` | Significado |
|---|---|---|
| `201` | `accepted` | Guardado. `observationId` é a nova observação. |
| `202` | `accepted` (`state: "retrying"`) | Aceite, mas a gravação falhou. O servidor volta a tentar, também depois de um reinício. |
| `200` | `duplicate` | Este `eventId` já tinha sido aceite. `observationId` é a observação existente; nada de novo é guardado. |
| `400` / `422` | `rejected` | Payload inválido, ou a gravação falhou definitivamente (o evento fica guardado como dead letter). |
| `503` | `rejected` (`retryable: true`) | A caixa de entrada está cheia (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Os hooks colocam o evento em spool e enviam-no mais tarde. |
Os eventos falhados são repetidos a cada `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s), com backoff que duplica, até `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Os eventos que continuam a falhar ficam na caixa de entrada como dead letters, são listados em `/agentmemory/status` e na página Health do visualizador, e podem ser repetidos com `POST /agentmemory/capture/retry` (`{"eventId": "..."}` ou `{"all": true}`). Os ids de eventos aceites são lembrados durante `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 horas, no máximo `AGENTMEMORY_CAPTURE_EVENTS_MAX` ids), por isso um hook reproduzido depois de um timeout ou de um reinício é guardado uma vez, enquanto duas chamadas de ferramenta separadas, com os seus próprios ids de anfitrião, são guardadas duas vezes, mesmo quando o seu conteúdo é idêntico. Quando uma observação é eliminada (forget, eliminação de sessão, remoção, esquecimento automático ou uma importação que substitui o armazenamento), o seu evento é marcado como eliminado antes de a observação ser removida, por isso uma reprodução desse evento dentro da mesma janela é respondida como duplicada e não guarda nada. O state store escreve em disco a cada 2 segundos, por isso um evento respondido ainda pode estar apenas em memória por um momento. Para cobrir isso, toda resposta `2xx` também transporta o `bootId` do servidor (novo a cada arranque), `acceptedAt` e `durableAfterMs` (o intervalo de gravação mais 1.5 s no armazenamento de ficheiro, 1.5 s no redis, onde a persistência é uma definição do operador). Os hooks mantêm o evento no spool local até essa janela ter passado, e eliminam-no numa chamada posterior, sem outro pedido. Se o `bootId` tiver mudado nessa altura, o servidor reiniciou, por isso o hook envia o evento novamente com o mesmo `eventId`; um evento que já tinha chegado ao disco não é guardado duas vezes. O servidor também envia esses eventos a si próprio no arranque e em cada intervalo de repetição, por isso um reinício não perde nada, mesmo quando nenhum hook corre depois. Os hooks mais antigos ignoram os campos extra, e hooks novos contra um servidor mais antigo descartam o evento no `2xx`, como antes.
Quando o servidor está em baixo, não responde a tempo ou devolve um 5xx, o hook acrescenta a observação a um ficheiro de spool local, `/capture-spool/-.jsonl` (substitua a pasta com `AGENTMEMORY_CAPTURE_SPOOL_DIR`). O ficheiro é privado ao seu utilizador (modo 600), os segredos são ocultados da mesma forma que o servidor os oculta, aguenta no máximo `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) e descarta entradas mais antigas do que `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Quando está cheio, as novas entradas são descartadas e contadas, e o `/agentmemory/status` reporta isso. O hook continua a terminar com 0 dentro do seu limite de tempo e não acrescenta nenhum pedido quando o servidor está saudável. O spool é enviado no arranque seguinte e pelo primeiro hook que voltar a alcançar o servidor, num processo em segundo plano, para que o agente não espere. Os ids de evento tornam isto seguro: uma observação que já tinha chegado antes de um timeout não é guardada duas vezes. O `npx @agentmemory/agentmemory capture` mostra o spool e a caixa de entrada do servidor, `--drain` envia o spool imediatamente, e `GET /agentmemory/capture` devolve o mesmo em JSON. Defina `AGENTMEMORY_CAPTURE_SPOOL=false` para desligar o spool.
**Compactação da proveniência do grafo.** Cada nó e aresta do grafo de conhecimento mantém os ids das 32 observações mais recentes de onde veio. Armazenamentos escritos antes desse limite podem ter milhares de ids por nó quente, o que torna a pesquisa no grafo e o visualizador lentos, ou derruba o worker. O agentmemory corrige isto por si só: no primeiro arranque depois de uma atualização, reduz cada nó, aresta, aresta substituída (o histórico temporal do grafo) e o snapshot em cache até ao limite, em segundo plano, em pequenas fatias com uma pausa entre elas, para que a pesquisa, a captura e o visualizador continuem a funcionar. Guarda o seu progresso, retoma depois de um reinício e nunca volta a correr depois de terminar. O `/agentmemory/status` e a página Health do visualizador mostram-no como pendente, em execução (com o âmbito e a posição atuais), concluído ou falhado. Defina `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` para o desligar.
Para o executar à mão, chame `POST /agentmemory/graph/compact`. Percorre os índices de nome e de chave de aresta, em vez de listar cada nó e aresta, e é seguro voltar a executar. Quando reduz ids, escreve uma entrada de auditoria `graph_compact`.
```bash
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
```
Num armazenamento grande, ou quando a chamada devolve 504, execute-o em fatias. Envie `scope` (`nodes`, `edges` ou `history`), `offset` e `limit`, e depois chame novamente com o `nextOffset` devolvido, até este ser `null`. Faça isto para `nodes`, `edges` e `history`, e termine com uma chamada `{"scope":"snapshot"}`, porque uma execução em fatias não toca no snapshot em cache.
```bash
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
```bash
npm run dev # Hot reload
npm run build # Production build
npm test # 2,500+ tests
npm run test:integration # API tests (requires running services)
```
**Pré-requisitos:** Node.js >= 20 com npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 ou Docker. A instalação automática do engine no macOS/Linux também exige `curl`, um `sh` POSIX e `tar`; o Windows nativo usa o `iii.exe` fixado manualmente, o WSL2, ou o Docker Desktop.
