agentmemory: memória persistente para agentes de codificação de IA

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.

🇬🇧 English • 🇨🇳 简体中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇰🇷 한국어 • 🇵🇹 Português • 🇧🇷 Português (Brasil) • 🇪🇸 Español • 🇩🇪 Deutsch • 🇫🇷 Français • 🇮🇹 Italiano • 🇳🇱 Nederlands • 🇵🇱 Polski • 🇨🇿 Čeština • 🇷🇴 Română • 🇭🇺 Magyar • 🇬🇷 Ελληνικά • 🇸🇪 Svenska • 🇩🇰 Dansk • 🇳🇴 Norsk • 🇫🇮 Suomi • 🇷🇺 Русский • 🇺🇦 Українська • 🇹🇷 Türkçe • 🇮🇱 עברית • 🇸🇦 العربية • 🇮🇳 हिन्दी • 🇧🇩 বাংলা • 🇵🇰 اردو • 🇹🇭 ไทย • 🇻🇳 Tiếng Việt • 🇮🇩 Bahasa Indonesia • 🇵🇭 Tagalog

rohitg00/agentmemory | Trendshift

Documento de design: 1.7k estrelas / 240 forks no gist

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.

versão no npm CI Licença Estrelas skills.sh installs

54 ferramentas MCP 12 hooks automáticos 0 bases de dados externas 5,000+ testes aprovados

demonstração do agentmemory

Instalação • Início Rápido • Benchmarks • vs Concorrentes • Agentes • Como Funciona • MCP • Visualizador • Configuração • API

--- 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`).
---

Funciona com qualquer agente

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
Claude Code
plugin nativo + 12 hooks + MCP
Codex CLI
Codex CLI
plugin nativo + 6 hooks + MCP
GitHub Copilot CLI
GitHub Copilot CLI
MCP + hooks/skills do plugin
Cursor
Cursor
plugin nativo + hooks do ciclo de vida + MCP
OpenCode
OpenCode
plugin de captura + MCP
Devin
Devin
6 hooks + skills + MCP
OpenClaw
OpenClaw
plugin nativo + MCP
Hermes
Hermes
plugin nativo + MCP
pi
pi
pesquisa nativa + captura + skills
OpenHuman
OpenHuman
backend nativo com trait Memory
Gemini CLI
Gemini CLI
servidor MCP
Antigravity
Antigravity
MCP + hooks
Claude Desktop
Claude Desktop
servidor MCP
Warp
Warp
connect + MCP + skills
Zed
Zed
servidor MCP
Cline
Cline
servidor MCP
Continue
Continue
servidor MCP
Droid
Droid
servidor MCP
Kiro
Kiro
servidor MCP
Qwen Code
Qwen Code
servidor MCP
DeepSeek Harness
DeepSeek Harness
captura nativa + MCP
Roo Code
Roo Code
servidor MCP
Kilo Code
Kilo Code
servidor MCP
Goose
Goose
servidor MCP
Aider
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). ---

Benchmarks

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). ---

vs Concorrentes

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. ---

Início Rápido

### 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). ---

Porque usar o agentmemory

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 | ---

Como Funciona

### 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 | ---

Servidor MCP

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/ ``` ---

Visualizador em Tempo Real

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'`). ---

Configuração

### 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. ---

API

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"}' ``` ---

Desenvolvimento

```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)

Licença

[Apache-2.0](../LICENSE)