Memória persistente entre sessões e agentes de programação.
Memória persistente para Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, 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.
---
O AgentMemory captura sessões de programação e permite pesquisar decisões, correções e aprendizagens. Partilhe um único armazenamento entre agentes, inspecione o conteúdo guardado e escolha quanto contexto chega ao modelo.
## Instalação
Requisitos:
- Node.js 20 ou mais recente, com npm e npx (`node -v`, `npm -v` e `npx -v`).
- No macOS/Linux, a configuração automática também precisa de `curl`, um `sh` POSIX e `tar`.
- No Windows, use WSL2 ou siga a [configuração nativa](#windows).
Comando canónico para uma instalação limpa:
```bash
npx -y @agentmemory/agentmemory@latest
```
Escolha os seus agentes e um fornecedor, ou o modo sem chave. O assistente grava a configuração, inicia o servidor de memória e oferece uma instalação global do comando `agentmemory`. `-y` aceita a confirmação do npm; `@latest` seleciona a versão atual. A compressão por LLM é opcional e exige um fornecedor e `AGENTMEMORY_AUTO_COMPRESS=true`.
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.
A API fica em `http://localhost:3111` e o visualizador em `http://localhost:3113`. Ambos escutam em loopback por predefinição. A configuração fica em `~/.agentmemory/.env`; consulte [armazenamento de dados](#data-storage) para os caminhos e instâncias separadas.
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
Conecte outro agente com `agentmemory connect `. Consulte as [integrações](#works-with-every-agent) e os [comandos cotidianos](#everyday-commands).
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`).
---
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 + hooks do ciclo de vida + MCP
OpenCode plugin de captura + MCP
Devin 6 hooks + skills + MCP
OpenClaw plugin nativo + MCP
Hermes plugin nativo + MCP
pi pesquisa nativa + captura + skills
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 captura nativa + MCP
Roo Code servidor MCP
Kilo Code servidor MCP
Goose servidor MCP
Aider REST API
Oh My Pi pesquisa nativa + captura + skills + MCP opcional
Funciona com qualquer agente que fale MCP ou HTTP. Um servidor, memórias partilhadas entre todos eles.
---
### Armazenamento de dados
Por predefinição, as memórias ficam fora do repositório:
| Plataforma | Diretório de dados |
|---|---|
| macOS | `~/Library/Application Support/agentmemory` |
| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
| Windows | `%APPDATA%\agentmemory` |
A instância 0 reutiliza um `./data/state_store.db` existente. Escolha outro caminho com `--data-dir ` ou `AGENTMEMORY_DATA_DIR` e mantenha-o ao reiniciar ou atualizar. `--instance 1` usa o subdiretório `instance-1`, a porta da API `3211` e o visualizador `3213`. Consulte [armazenamento e cópias de segurança](../docs/reliability/state-storage.md) para Redis e migrações.
```bash
agentmemory --data-dir ~/.agentmemory-projects/main
agentmemory --instance 1
```
Notas da versão mais recente: [CHANGELOG.md](../CHANGELOG.md).
---
Resultados atuais de recuperação, definições das métricas e passos de reprodução:
[0.9.31 · 2026-10-28 · strict recall-all@5](../docs/benchmarks/2026-10-28-retrieval-evaluation.md) · [eval/README.md](../eval/README.md).
---
Comparação atualizada de produtos e opções de implementação, com fontes:
[AgentMemory / Mem0 / Supermemory / Zep / Letta / Cognee / claude-mem](../benchmark/COMPARISON.md) · 2026-10-28.
---
### 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, verifique o funcionamento, o visualizador e o estado:
```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
```
`status` mostra a saúde do servidor e os fornecedores e embeddings ativos. Guarde uma memória de teste e confirme a pesquisa:
```bash
# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
-H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-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 "Authorization: Bearer $AGENTMEMORY_SECRET" \
-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. 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
```
O comando atualiza o ambiente local e pode atualizar dependências JavaScript no workspace atual. Faça uma cópia de segurança e leia o [guia de atualização](../docs/upgrades/iii-0.25.md) antes de continuar.
### Claude Code (um bloco, cole-o)
```text
Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. 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` (caminho predefinido) 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` (caminho predefinido). 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
```
Este comando configura o servidor MCP e funde os hooks incluídos com a configuração de utilizador do Claude Code. Se `CLAUDE_CONFIG_DIR` não estiver definida, estiver vazia ou contiver apenas espaços em branco, usa `~/.claude.json` para MCP e `~/.claude/settings.json` para os hooks. Os restantes valores de diretório são usados exatamente como fornecidos, incluindo espaços em branco no início e no fim. Para usar um diretório personalizado, defina `CLAUDE_CONFIG_DIR` com o mesmo valor não vazio para este comando e para o Claude Code; os ficheiros serão então `$CLAUDE_CONFIG_DIR/.claude.json` e `$CLAUDE_CONFIG_DIR/settings.json`, respetivamente. O Claude Code tem de receber este valor no seu ambiente de arranque, mesmo que o conector o leia do ficheiro `.env` do AgentMemory. Crie o diretório personalizado antes de executar este comando; caso contrário, o conector ignora o Claude Code por não o detetar. Se o valor na shell contiver apenas espaços em branco, remova `CLAUDE_CONFIG_DIR` do ambiente antes de iniciar o Claude Code para que também use o perfil predefinido. Utilize um caminho absoluto. Os caminhos relativos são resolvidos a partir do diretório de trabalho, pelo que ambos os comandos têm de ser executados no mesmo diretório.
Os comandos dos hooks usam caminhos absolutos para o diretório `plugin/` incluído no pacote instalado. Volte a executar o comando depois de atualizar o agentmemory para atualizar esses caminhos. As entradas do utilizador nos ficheiros de configuração são preservadas; só as entradas anteriores do agentmemory são substituídas. O uso de `/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.
### Cursor
```bash
agentmemory connect cursor
```
Depois adicione o plugin nativo de um checkout do AgentMemory em **Settings → Plugins → Add marketplace** e recarregue a janela. O plugin oferece captura do ciclo de vida, atribuição ao projeto, skills e MCP. Ative os hooks do plugin ou os manuais em `~/.cursor/hooks.json` para evitar captura duplicada. [Guia do Cursor](../integrations/cursor/).
### Pi, Oh My Pi, DeepSeek Harness
```bash
agentmemory connect pi --with-mcp
agentmemory connect omp --with-mcp
agentmemory connect dsh --with-hooks
```
Escolha o comando para o seu host. Pi e OMP instalam pesquisa, captura, reenvio offline e 17 skills; `--with-mcp` adiciona todas as ferramentas. Execute `/reload` no Pi ou reinicie o OMP e verifique `/agentmemory-status`. O DSH instala MCP e o plugin de captura incluído; reinicie o DSH depois.
O Pi também oferece o pacote instalável `@agentmemory/pi`. O [guia do Pi](../integrations/pi/) explica a instalação local e a disponibilidade no npm. Use apenas um método de instalação por host.
[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
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 https://github.com/rohitg00/agentmemory 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`
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 ` normalmente grava a configuração MCP. Hermes, OpenClaw, Pi e Oh My Pi instalam a integração nativa e as skills incluídas por predefinição; MCP é opcional com `--with-mcp`.
- `npx skills add rohitg00/agentmemory` instala skills para agentes que não as incluem nativamente. Ignore este passo para Hermes, OpenClaw, Pi e Oh My Pi: os respetivos conectores já instalam as skills.
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/` | Depois adicione o plugin nativo de um checkout do AgentMemory em **Settings → Plugins → Add marketplace** e recarregue a janela. O plugin oferece captura do ciclo de vida, atribuição ao projeto, skills e MCP. Ative os hooks do plugin ou os manuais em `~/.cursor/hooks.json` para evitar captura duplicada. [Guia do Cursor](../integrations/cursor/). |
| **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 / Oh My Pi** | `~/.pi/agent/` / `~/.omp/agent/` | pesquisa nativa + captura + skills. [Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/). |
| **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 9 skills do agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) aparecem nativamente na paleta de comandos slash do Warp. |
| **Cline (CLI)** | `~/.cline/data/settings/cline_mcp_settings.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` se estiver ausente ou modifica o `config.json` existente. Se o YAML já existir, mostra o bloco para adicionar em `mcpServers:` e preservar comentários e âncoras. O Continue usa um array, não um objeto. |
| **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` ativa as ferramentas MCP. Adicione `--with-hooks` para carregar o plugin nativo de captura incluído no AgentMemory. Não é necessário um pacote adicional. [DSH](../docs/dsh.md). |
| **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 | Use os [exemplos REST autenticados](#validate-a-fresh-install-and-restart-persistence) para gravar e pesquisar memórias em scripts. |
| **Agentes suportados** | Apenas skills | `npx skills add rohitg00/agentmemory`; escolha as skills e os agentes onde pretende instalá-las. |
**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)
Use a [API REST](#api) em qualquer linguagem ou as [ferramentas MCP](#mcp-server) em um agente. REST usa JSON e autenticação bearer; consulte o [exemplo de gravação e pesquisa](#validate-a-fresh-install-and-restart-persistence). Os [exemplos Python](../examples/python/) cobrem a integração direta com o runtime.
### A Partir do Código-Fonte
```bash
git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
```
`npm start` inicia o mesmo servidor local da CLI instalada. Os requisitos estão em [Install](#install); a API e o visualizador escutam em `127.0.0.1`.
### Windows
O agentmemory funciona no Windows 10/11. O WSL2 segue o caminho Linux e pode instalar automaticamente o engine fixado. O Windows nativo exige que o binário iii-engine v0.25.1 fixado seja instalado manualmente; descarregue o ficheiro correspondente na [página de lançamento iii v0.25.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.1), verifique o checksum e coloque `iii.exe` no `PATH` (por exemplo, `%USERPROFILE%\.local\bin\iii.exe`). O CLI não extrai automaticamente o ZIP do Windows.
A ligação MCP automatizada no Windows nativo só suporta `agentmemory connect copilot-cli`. Para os restantes agentes nativos do Windows, use o bloco MCP manual de [Outros agentes](#other-agents). Execute `connect` no WSL apenas quando o agente de destino também estiver instalado nesse mesmo ambiente WSL.
**Apenas MCP standalone (sem engine).** Se só precisar das ferramentas MCP e não precisar da REST API, do visualizador ou dos serviços de runtime:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
# or
npx -y @agentmemory/mcp
```
Execute `agentmemory doctor` ou reinicie com `--verbose`. Use `--port ` ou `--instance ` se as portas estiverem ocupadas. Consulte compatibilidade e recuperação no [guia de atualização](../docs/upgrades/iii-0.25.md).
---
Deploy
Hospede o serviço com Docker Compose ou os modelos abaixo. Memórias e credenciais ficam no volume `/data`. Faça uma cópia de segurança e reutilize esse volume nas atualizações. O [guia de implantação](../deploy/README.md) cobre autenticação, rede, cópias de segurança e migração.
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.
REST usa a porta `3111`; o visualizador, `3113`. Mantenha ambos privados ou proteja-os com autenticação e TLS. O guia de implantação explica a exposição de rede e a [migração de instalações Docker antigas](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode).
---
O conhecimento do projeto dispersa-se por conversas e ficheiros de instruções. O AgentMemory permite pesquisar decisões, correções e aprendizagens no agente que estiver a utilizar.
```text
Session 1: "Add auth to the API"
Agent writes code, runs tests, fixes bugs
Connected hooks capture supported tool events
Observations become searchable project history
Session 2: "Now add rate limiting"
Agent recalls:
- 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
Continues with the earlier decisions in context.
```
### 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 |
|---|---|---|
| Manutenção | Instruções mantidas manualmente | Histórico de sessões e memórias indexadas |
| Pesquisa | Carrega tudo para o contexto | BM25 + vetor + grafo (apenas top-K) |
| 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
-> Stable event ID / durable capture inbox / offline spool
-> 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 AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
-> Inject context when enabled by the integration
```
### 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
Esta tabela descreve os hooks do Claude Code. Outras integrações capturam os eventos fornecidos pelo host; consulte os respectivos guias. A injeção automática de contexto pelos hooks partilhados exige `AGENTMEMORY_INJECT_CONTEXT=true`.
| 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** | Integrações nativas registram os eventos de sessão e ferramentas compatíveis |
| **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.
[0.9.31: `AGENTMEMORY_VECTOR_BACKFILL=all` / `AGENTMEMORY_VECTOR_BACKFILL_MAX`](../docs/reliability/source-and-vector-recovery.md).
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 | [`EMBEDDING_PROVIDER=local`](../README.md#embedding-providers) |
| 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` | [OpenAI](https://openai.com/api/pricing/) | [text-embedding-3-small](https://platform.openai.com/docs/models/text-embedding-3-small) |
| 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 ligue-se a um servidor self-hosted) 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 em direto por SSE em `/agentmemory/viewer/events` no worker REST: 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. Num bind que não seja loopback, a shell HTML continua pública, mas cada pedido proxy exige bearer; o visualizador pede-o e guarda-o no session storage. Configure allowlists explícitas de anfitriões/origens e TLS antes de expor um visualizador. 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'`).
---
### 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
Comece sem chave para captura e pesquisa por palavras-chave. `EMBEDDING_PROVIDER=local` ativa a pesquisa semântica local após o primeiro download do modelo. A compressão por LLM exige um fornecedor e `AGENTMEMORY_AUTO_COMPRESS=true`; pode gerar uma pedido por observação. Consulte os preços atuais antes de ativá-la. O visualizador e `agentmemory status` mostram os fornecedores ativos.
### 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
| Porta | Uso | Configuração |
|---|---|---|
| `3111` | REST API, MCP HTTP, SSE | `III_REST_PORT` |
| `3113` | Viewer UI | `III_VIEWER_PORT` |
`--port ` define a porta da API e, por predefinição, o visualizador em `N+2`. Use `--instance N` para uma instância separada. Mantenha as portas internas privadas e consulte o [guia de implantação](../deploy/README.md) antes de permitir acesso remoto.
### Backend de armazenamento: ficheiro (predefinição) vs Redis
O armazenamento em ficheiros predefinido não precisa de um serviço de base de dados separado. Redis é opcional com `AGENTMEMORY_STATE_BACKEND=redis` e `AGENTMEMORY_REDIS_URL`. Trocar o backend não copia as memórias. O [guia de armazenamento e cópias de segurança](../docs/reliability/state-storage.md) cobre persistência, limitações do Redis e exportação/importação autenticada.
### 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 como `export ANTHROPIC_API_KEY=...`, copie-a para este ficheiro como `ANTHROPIC_API_KEY=...`, sem o prefixo `export`, e reinicie o agentmemory. Defina `AGENTMEMORY_ENV_FILE` para usar outro caminho de ficheiro env.
As variáveis de ambiente do processo têm prioridade sobre o ficheiro. Reinicie o servidor após alterar a configuração.
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
Opções comuns para `~/.agentmemory/.env`:
```env
EMBEDDING_PROVIDER=local
# AGENTMEMORY_INJECT_CONTEXT=true
# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
# AUTO_FORGET_ENABLED=false
# LESSON_DECAY_ENABLED=false
# INSIGHT_DECAY_ENABLED=false
```
A referência completa está em [`.env.example`](../.env.example): credenciais, filtros de captura, retenção, armazenamento, âmbito de equipa e opções. `AGENTMEMORY_ENV_FILE` seleciona outro ficheiro. Nunca inclua um `.env` preenchido ou um segredo bearer no git.
---
147 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 nem em `~/.agentmemory/.env`, o CLI gera um segredo aleatório no primeiro arranque em `~/.agentmemory/secret` e guarda uma cópia chamada `secret` no diretório de dados selecionado, com permissões `0600`. Todos os clientes incluídos o leem daí quando comunicam 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 de OpenCode, Pi, OpenClaw, Hermes e filesystem-watcher. O segredo guardado só é enviado para URLs de loopback (`localhost`, `127.0.0.0/8`, `::1`). Uma `AGENTMEMORY_SECRET` explícita prevalece sempre, e os clientes remotos precisam de ter o segredo definido no seu ambiente. As implementações Docker self-host a partir do repositório e os entrypoints de `deploy/` geram e exportam o seu próprio segredo. Para chamar a API manualmente:
```bash
curl -H "Authorization: Bearer " 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: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
**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.** A compactação da proveniência antiga é adiada no arranque porque lê os scopes antigos completos. `/agentmemory/status` indica `deferred`, ou `off` com `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Execute a compactação manual abaixo durante a manutenção. A migração do índice de pesquisa é separada: use `agentmemory graph-index migrate --allow-legacy-scan` conforme o [guia de manutenção](../docs/reliability/graph-index-migration.md).
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 "Authorization: Bearer " -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 "Authorization: Bearer " -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
```bash
npm run dev # Hot reload
npm run build # Production build
npm test # 5,000+ tests
npm run test:integration # API tests (requires running services)
```
[Install](#install) · [CONTRIBUTING.md](../CONTRIBUTING.md)