rohitg00--agentmemory/READMEs/README.pt-BR.md at be89b222b0b4cd9b019e21b6ead002c15d840199

Files

T

Rohit Ghumare be89b222b0 feat: devin support (cli adapter, plugin, cloud mcp) (#1214 )

* feat: devin support replacing windsurf

* feat: devin cli adapter, plugin manifest, and hook payload compat

* fix: stale tool counts in translations and cwd validation

2026-08-16 14:44:10 +01:00

93 KiB

Raw Blame History

Seu agente de codificação lembra de tudo. Chega de re-explicar. Built on iii engine
Memória persistente para Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode e qualquer cliente MCP.

O gist estende o padrão LLM Wiki do Karpathy com pontuação de confiança, ciclo de vida, grafos de conhecimento e busca híbrida: agentmemory é a implementação.

Instalação • Início rápido • Benchmarks • Comparativo • Agentes • Como funciona • MCP • Viewer • Powered by iii • Configuração • API

Install

Um único comando:

npx @agentmemory/agentmemory

A primeira execução é um setup interativo: escolha os agentes a conectar (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), escolha um provider de LLM ou fique sem chave, e ele semeia a configuração, inicia o servidor de memória em :3111 e se oferece para instalar globalmente, de modo que o comando agentmemory simples funcione em qualquer lugar depois.

Depois prove que o recall funciona e dê ao seu agente as skills dele:

agentmemory demo --serve                 # seed sample sessions + watch recall find them
npx skills add rohitg00/agentmemory -y   # 17 native skills so your agent knows when to reach for memory

Prefere deixar um agente de codificação fazer tudo? Entregue a ele uma única instrução:

Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md

Conecte mais agentes a qualquer momento com agentmemory connect <agent> — 20 adaptadores listados em Funciona com qualquer agente. Referência completa de comandos em Início rápido.

Windows

O caminho rápido é o WSL2. O setup nativo do engine no Windows é manual (cerca de 10 a 20 minutos) e agentmemory connect atualmente não é suportado lá. Veja as notas de Windows para o passo a passo.

Instalação global / EACCES

npm install -g @agentmemory/agentmemory
# If you hit EACCES on macOS/Linux system Node installs:
sudo npm install -g @agentmemory/agentmemory

npx serve uma versão antiga

O npx faz cache por versão. Force a mais recente com npx -y @agentmemory/agentmemory@latest, ou limpe o cache uma vez com rm -rf ~/.npm/_npx (macOS/Linux; no Windows apague %LOCALAPPDATA%\npm-cache\_npx).

Já roda seu próprio engine iii

agentmemory fixa o iii-engine em v0.11.2 e não se conecta a uma versão diferente (o worker não fala o protocolo de outro engine). Pare o outro engine e rode npx -y @agentmemory/agentmemory@latest. Ele instala e executa a v0.11.2 fixada em ~/.agentmemory/bin, deixando o seu próprio iii intocado.

agentmemory funciona com qualquer agente que suporte hooks, MCP ou REST API. Todos os agentes compartilham o mesmo servidor de memória.

Claude Code _{native plugin + 12 hooks + MCP}	Codex CLI _{native plugin + 6 hooks + MCP}	OpenClaw _{native plugin + MCP}	Hermes _{native plugin + MCP}	pi _{native plugin + MCP}	OpenHuman _{native Memory trait backend}	Cursor _{MCP server}	Gemini CLI _{MCP server}
OpenCode _{22 hooks + MCP + plugin}	Cline _{MCP server}	Goose _{MCP server}	Kilo Code _{MCP server}	Aider _{REST API}	Claude Desktop _{MCP server}	Devin _{6 hooks + MCP}	Roo Code _{MCP server}

_{Funciona com qualquer agente que fale MCP ou HTTP. Um servidor, memórias compartilhadas entre todos eles.}

Você explica a mesma arquitetura toda sessão. Você redescobre os mesmos bugs. Você reensina as mesmas preferências. A memória integrada (CLAUDE.md, .cursorrules) bate no teto das 200 linhas e fica desatualizada. agentmemory resolve isso. Ele captura silenciosamente o que seu agente faz, comprime em memória pesquisável e injeta o contexto certo quando a próxima sessão começa. Um comando. Funciona em todos os agentes.

O que muda: Na sessão 1 você configura autenticação JWT. Na sessão 2 você pede rate limiting. O agente já sabe que sua autenticação usa o middleware jose em src/middleware/auth.ts, que seus testes cobrem a validação de tokens e que você escolheu jose em vez de jsonwebtoken por compatibilidade com Edge, sem re-explicar e sem copiar e colar.

npx @agentmemory/agentmemory

Novidade na v0.9.0 — Landing em agent-memory.dev, conector de filesystem (@agentmemory/fs-watcher), MCP standalone agora faz proxy para o servidor em execução, então hooks e viewer combinam, política de auditoria codificada em cada caminho de deleção, e health para de marcar memory_critical em processos Node pequenos. Notas completas em CHANGELOG.md.

Precisão de recuperação

coding-agent-life-v1 (corpus interno, reproduzível em sandbox)

Adaptador	P@5	R@5	Taxa de acerto top-5	Latência p50
agentmemory hybrid	0.240	1.000	15 / 15	14 ms
grep baseline	0.227	0.967	15 / 15	0 ms

Taxa de acerto top-5 de 100% no teto matemático de P@5 deste corpus (0.240, veja a scorecard). O híbrido recupera todas as sessões gold; o grep perde 1 de 2 golds na query temporal multi-sessão. O ganho é recall + temporal, não precisão agregada. Este benchmark é pequeno e esparso em golds; o LongMemEval-S maior abaixo diferencia melhor. Detalhamento completo por tipo + nota de correção: docs/benchmarks/2026-05-20-coding-agent-life-v1.md.

LongMemEval-S (ICLR 2025, 500 perguntas)

Sistema	R@5	R@10	MRR
agentmemory	95.2%	98.6%	88.2%
BM25-only fallback	86.2%	94.6%	71.5%

Economia de tokens

Abordagem	Tokens/ano	Custo/ano
Colar contexto completo	19.5M+	Impossível (excede a janela)
Resumido por LLM	~650K	~$500
agentmemory	~170K	~$10
agentmemory + embeddings locais	~170K	$0

Modelo de embedding: all-MiniLM-L6-v2 (local, gratuito, sem API key). Relatórios completos: benchmark/LONGMEMEVAL.md, benchmark/QUALITY.md, benchmark/SCALE.md. Comparativo com concorrentes: benchmark/COMPARISON.md cobrindo agentmemory vs mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.

Reproduza localmente: eval/README.md, um harness com adaptadores plugáveis para LongMemEval _s (500-Q públicas) e coding-agent-life-v1 (corpus interno de 15 sessões). Adaptadores grep / vector / agentmemory são pontuados lado a lado, saída em NDJSON, e as scorecards publicadas ficam em docs/benchmarks/.

Combina com codegraph, Understand Anything e Graphify. Indexação de grafos de código, pipelines de build multiagente e grafos de conhecimento mais amplos sobre docs / PDFs / imagens / vídeos. agentmemory lembra do trabalho; esses três projetos iluminam o resto da camada de contexto. Recipes e tabela de roteamento por pergunta: docs/recipes/pairings.md.

	agentmemory	mem0 (63K ⭐)	Letta / MemGPT (24K ⭐)	Khoj (36K ⭐)	supermemory (29K ⭐)	TencentDB Agent Memory (22K ⭐)	MemPalace (54K ⭐)	oracleagentmemory	Hippo	Built-in (CLAUDE.md)
Tipo	Engine de memória + servidor MCP	API de camada de memória	Runtime de agente completo	IA pessoal	API de memória + app	Hub de memória de time (proxy de LLM)	Memória vetorial (OSS)	Engine de memória (Oracle DB)	Sistema de memória	Arquivo estático
Retrieval R@5	95.2%	68.5% (LoCoMo)	83.2% (LoCoMo)	N/A	Autorreportado	PersonaMem 76% (autorreportado)	~96.6% (autorreportado)	94.4% (autorreportado)	N/A	N/A (grep)
Captura automática	12 hooks (esforço manual zero)	Chamadas manuais a `add()`	O agente se autoedita	Manual	Extração no lado da API	Interceptação por proxy (troca de base-URL)	Manual	Extração via API	Manual	Edição manual
Busca	BM25 + Vector + Graph (fusão RRF)	Vector + Graph	Vector (archival)	Semântica	Vector + RAG	4 tipos de asset (Chat / Skill / Wiki / CodeGraph)	Somente vector	Vector + semântica	Ponderada por decaimento	Carrega tudo no contexto
Multiagente	MCP + REST + leases + signals	API (sem coordenação)	Somente dentro do runtime do Letta	Não	Não	Papéis de time + assets compartilhados	Não	Somente com escopo	Compartilhado multiagente	Arquivos por agente
Dependência de framework	Nenhuma (qualquer cliente MCP)	Nenhuma	Alta (precisa usar Letta)	Standalone	Nenhuma	Proxy na frente de toda chamada de modelo	Nenhuma	Oracle Database	Nenhuma	Formato por agente
Dependências externas	Nenhuma (SQLite + iii-engine)	Qdrant / pgvector	Postgres + BD vetorial	Várias	Nuvem gerenciada	Stack Docker (Core + Hub + Proxy)	Vector store	Oracle AI Database	Nenhuma	Nenhuma
Ciclo de vida da memória	Consolidação de 4 níveis + decaimento + auto-esquecimento	Extração passiva	Gerenciado pelo agente	Manual	Auto-esquecimento	Revisão manual; roteamento automático em desenvolvimento	Nenhum	Não informado	Decaimento + consolidação	Poda manual
Eficiência de tokens	~1.900 tokens/sessão ($10/ano)	Varia conforme a integração	Memória principal no contexto	Varia	Preços de nuvem	Não informado	Sem token budget	Com LLM (varia)	Varia	22K+ tokens com 240 obs
Viewer em tempo real	Sim (port 3113)	Dashboard na nuvem	Dashboard na nuvem	Web UI	Dashboard na nuvem	Web UI do Hub	Não	Não	Não	Não
Self-hosted	Sim (padrão)	Opcional	Opcional	Sim	Não (somente nuvem)	Sim (Docker)	Sim	Sim (Oracle DB)	Sim	Sim

_{Nota de benchmark: apenas o R@5 do agentmemory é resultado medido por nós mesmos (LongMemEval-S, reproduzível a partir de benchmark/COMPARISON.md). Os números de mem0 e Letta são os números LoCoMo publicados por eles (um dataset diferente); os números de MemPalace, supermemory, TencentDB (PersonaMem) e oracleagentmemory são alegações autorreportadas dos fornecedores que não reproduzimos de forma independente (a execução do oracleagentmemory usou GPT-5.5 contra um Oracle AI Database). Mostrados lado a lado apenas como ordem de grandeza, não como comparação direta sobre dados idênticos. As contagens de stars são aproximadas e mudam com o tempo.}

Novos entrantes que vale conhecer, comparados em profundidade em benchmark/COMPARISON.md:

Sistema	⭐	Ângulo
Zep / Graphiti	30K	Grafo de conhecimento temporal; resultados publicados mais fortes em queries temporais (LongMemEval 63.8%), mas o grafo é construído de forma assíncrona, então fatos recentes podem atrasar
Cognee	30K	Ingestão de documento para grafo de conhecimento, somente Python, feito para extração estruturada de entidades em vez de captura de sessões

Nenhum deles faz captura automática a partir de hooks de agentes de codificação, entrega um viewer local-first ou roda sem chave — a combinação em torno da qual o agentmemory foi construído.

Compatibilidade: este release tem como alvo o iii-sdk estável ^0.11.0 e o iii-engine v0.11.x.

Experimente em 30 segundos

# Terminal 1: start the server
npx @agentmemory/agentmemory

# Terminal 2: seed sample data and see recall in action
npx @agentmemory/agentmemory demo

demo semeia 3 sessões realistas (autenticação JWT, correção de N+1 queries, rate limiting) e roda buscas semânticas sobre elas. Você verá que ele encontra "N+1 query fix" ao buscar "database performance optimization", algo que matching por palavra-chave não consegue fazer.

Abra http://localhost:3113 para acompanhar a memória sendo construída ao vivo.

Comandos do dia a dia

Instalação e setup ficam em Install acima (a primeira execução guia você pelo processo). No dia a dia:

agentmemory                    # start the server
agentmemory stop               # tear it down
agentmemory connect <agent>    # wire another agent
agentmemory doctor             # interactive diagnostics + fix prompts
agentmemory remove             # uninstall everything we created

Session Replay

Toda sessão que o agentmemory grava é reproduzível. Abra o viewer, escolha a aba Replay e arraste pela timeline: prompts, chamadas a tools, resultados e respostas renderizam como eventos discretos com play/pause, controle de velocidade (0,5x a 4x) e atalhos de teclado (espaço para alternar, setas para avançar passo a passo).

Para trazer transcripts JSONL antigos do Claude Code:

# Import everything under the default ~/.claude/projects
npx @agentmemory/agentmemory import-jsonl

# Or import a single file
npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl

As sessões importadas aparecem no seletor de Replay ao lado das nativas. Sob o capô, cada entrada passa pelas funções iii mem::replay::load, mem::replay::sessions e mem::replay::import-jsonl, sem servidores paralelos. Cada transcript importado é indexado para busca, carimbado com o canal de origem import e minerado para gerar um crystal de sessão e lessons.

Atenção se você depende do import-jsonl como caminho primário de captura: o cleanupPeriodDays do Claude Code (em ~/.claude/settings.json, padrão 30) apaga automaticamente de ~/.claude/projects/ os transcripts JSONL mais antigos que essa janela. Se você instalar o agentmemory do zero sobre um histórico de Claude Code com meses de idade, tudo com mais de 30 dias já se foi antes do primeiro import. Rode import-jsonl em um cron, aumente cleanupPeriodDays para algo maior, ou conecte os hooks de captura automática (o caminho padrão de instalação do plugin) para que cada turno chegue ao agentmemory enquanto a sessão está viva e a limpeza dos JSONL deixe de importar.

Atualização / Manutenção

Use o comando de manutenção quando você intencionalmente quiser atualizar seu runtime local:

npx @agentmemory/agentmemory upgrade

Aviso: este comando muta o workspace/runtime atual. Pode atualizar dependências JavaScript e puxar a imagem Docker fixada iiidev/iii:0.11.2. Nunca instala um engine iii sem fixação ou mais recente.

Detalhes de implementação estão em src/cli.ts (veja runUpgrade na região src/cli.ts:544-595).

Claude Code (um bloco, cole)

Install agentmemory: run `npx @agentmemory/agentmemory` 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.

Claude Code sem instalar o plugin (caminho MCP standalone)

Se você cabear o servidor MCP do agentmemory via ~/.claude.json diretamente em vez de usar /plugin install, o Claude Code nunca resolve ${CLAUDE_PLUGIN_ROOT} e você tem que apontar os scripts de hook para caminhos absolutos em ~/.claude/settings.json. Esses caminhos tipicamente embutem a versão do agentmemory (ex: ~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…), então a próxima atualização quebra silenciosamente todos os hooks.

Contorno:

agentmemory connect claude-code --with-hooks

Isso mescla os mesmos comandos de hook em ~/.claude/settings.json com caminhos absolutos resolvidos para o diretório plugin/ empacotado do pacote @agentmemory/agentmemory atualmente instalado. Rode o comando novamente após atualizar o agentmemory para atualizar os caminhos. Entradas de usuário no mesmo arquivo são preservadas; apenas entradas anteriores do agentmemory são substituídas. Usar o caminho /plugin install continua sendo a abordagem recomendada. Para deploys remotos ou protegidos, inicie o Claude Code com AGENTMEMORY_URL e AGENTMEMORY_SECRET definidos. O plugin repassa ambos os valores para seu servidor MCP empacotado; quando AGENTMEMORY_URL está vazio, o shim MCP usa http://localhost:3111.

Codex CLI (plataforma de plugins do Codex)

# 1. start the memory server in a separate terminal
npx @agentmemory/agentmemory

# 2. register the agentmemory marketplace and install the plugin
codex plugin marketplace add rohitg00/agentmemory
codex plugin add agentmemory@agentmemory

O plugin do Codex é servido a partir do mesmo diretório plugin/ do plugin do Claude Code. Ele registra:

@agentmemory/mcp como servidor MCP (faz proxy de todas as 54 tools quando AGENTMEMORY_URL aponta para um servidor agentmemory em execução; cai para 7 tools localmente quando não há servidor acessível)
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 (memory discipline, tools MCP, REST API, config, agentes, hooks, arquitetura e o guia de autoria de skills)

A engine de hooks do Codex injeta CLAUDE_PLUGIN_ROOT nos subprocessos de hook (conforme codex-rs/hooks/src/engine/discovery.rs), então os mesmos scripts de hook funcionam nos dois hosts sem duplicação. Os eventos Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure são exclusivos do Claude Code e não são registrados para o Codex.

Codex Desktop: hooks do plugin atualmente silenciosos (com contorno)

CodexHooks e PluginHooks são estáveis e habilitados por padrão em codex-rs/features/src/lib.rs, mas as builds atuais do Codex Desktop não despacham hooks.json local de plugin (openai/codex#16430). As tools MCP continuam funcionando; só as observações de ciclo de vida estão faltando.

Até que o upstream corrija, espelhe os mesmos comandos de hook no ~/.codex/hooks.json global:

agentmemory connect codex --with-hooks

Isso adiciona um bloco idempotente em ~/.codex/hooks.json referenciando caminhos absolutos para os scripts empacotados (sem necessidade de expansão de ${CLAUDE_PLUGIN_ROOT} no escopo de usuário). Rode o mesmo comando novamente após atualizar o agentmemory para atualizar os caminhos. Entradas de usuário no mesmo arquivo são preservadas; só entradas anteriores do agentmemory são substituídas.

OpenClaw (cole este prompt)

Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` 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/

Hermes Agent (cole este prompt)

Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:

mcp_servers:
  agentmemory:
    command: npx
    args: ["-y", "@agentmemory/mcp"]

memory:
  provider: agentmemory

Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.

Guia completo: integrations/hermes/

Outros agentes

Inicie o servidor de memória: npx @agentmemory/agentmemory

Skills nativas via `npx skills add` (50+ agentes)

agentmemory entrega 17 skills no formato <dir>/SKILL.md estilo 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 carregam tabelas de dados geradas a partir do código-fonte, então nunca ficam defasadas. O CLI skills da vercel-labs as instala automaticamente no diretório nativo de skills do agente chamador em 50+ agentes (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf e mais):

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

Isso é complementar a agentmemory connect <agent>:

agentmemory connect <agent> escreve a configuração do servidor MCP para que as tools fiquem disponíveis.
npx skills add rohitg00/agentmemory instala as skills para que o agente saiba quando chamá-las.

Para os poucos agentes que o CLI de skills ainda não cobre (Zed v1.3.x e anteriores), coloque você mesmo os 17 arquivos SKILL.md no diretório nativo de skills do agente; o mesmo formato funciona em todo lugar.

Bloco MCP padrão

A entrada do agentmemory é o mesmo bloco de servidor MCP em todo host que usa o formato mcpServers (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI, OpenClaw):

"agentmemory": {
  "command": "npx",
  "args": ["-y", "@agentmemory/mcp"],
  "env": {
    "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
    "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
  }
}

Mescle esta entrada no objeto mcpServers existente no arquivo de configuração do host; não substitua o arquivo. Se o arquivo já tem outros servidores, adicione agentmemory ao lado deles como outra chave dentro de mcpServers. Se mcpServers não existe, cole o bloco dentro de { "mcpServers": { ... } }. Os placeholders ${VAR} herdam AGENTMEMORY_URL / AGENTMEMORY_SECRET do shell no momento em que o servidor MCP sobe; variáveis não definidas passam string vazia e o shim cai para http://localhost:3111. Uma entrada cabeada cobre deploys tanto locais quanto remotos (k8s / com reverse-proxy).

Agente	Arquivo de configuração	Notas
Cursor	`~/.cursor/mcp.json`	Mescle em `mcpServers`. Deeplink de um clique também disponível no site.
Claude Desktop	`claude_desktop_config.json` (Application Support)	Mescle em `mcpServers`. Reinicie o Claude Desktop após editar.
Cline / Roo Code / Kilo Code	Configurações MCP do Cline (Settings UI → MCP Servers → Edit)	Mesmo bloco `mcpServers`.
Devin CLI	`~/.config/devin/config.json`	`agentmemory connect devin` mescla a entrada MCP; `--with-hooks` adiciona seis hooks nativos de captura automática (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) com os matchers de ferramentas em minúsculas do Devin. Verifique com `devin mcp list` e `/hooks` dentro do devin.
Devin (nuvem)	Settings → Connections → MCP servers	Adicione um MCP personalizado (STDIO): command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` apontando para um deployment de agentmemory acessível pela rede mais `AGENTMEMORY_SECRET` (sessões na nuvem não alcançam localhost — veja `deploy/`).
Gemini CLI	`~/.gemini/settings.json`	`gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (mescla automaticamente).
GitHub Copilot CLI (somente MCP)	`~/.copilot/mcp-config.json`	`agentmemory connect copilot-cli` mescla `mcpServers.agentmemory`; o Copilot o reconhece no próximo launch ou via `/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 (alterna automaticamente de `memory-core`); defina `plugins.entries.agentmemory.hooks.allowConversationAccess=true` ou a captura de turnos fica bloqueada silenciosamente. Veja `integrations/openclaw`.
Codex CLI (somente 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`. Registra MCP + 6 hooks de ciclo de vida (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) + 17 skills. No Codex Desktop, rode também `agentmemory connect codex --with-hooks` até que openai/codex#16430 seja mergeado; os hooks de plugin estão silenciosos lá.
OpenCode (somente MCP)	`opencode.json`	Formato diferente: chave `mcp` no topo, 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 ciclo de vida de sessão, mensagens, tools e erros. A atribuição de projeto é por sessão, então um único processo do OpenCode abrangendo vários repositórios arquiva cada sessão sob o próprio projeto. Dois comandos slash (`/recall`, `/remember`). Copie `plugin/opencode/` para seu workspace do OpenCode e adicione a entrada do plugin em `opencode.json`. Tabela completa de hooks + análise de gaps em `plugin/opencode/README.md`.
pi	`~/.pi/agent/extensions/agentmemory`	`agentmemory connect pi` instala a extensão empacotada no diretório de auto-descoberta do pi (recall no início do agente, captura no fim do agente, tools `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` em um pi em execução a reconhece. `integrations/pi` também é um pacote pi (`pi install ./integrations/pi` a partir de um checkout).
Hermes Agent	`~/.hermes/config.yaml`	`cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` ativa o memory provider de 6 hooks (prefetch, captura de turnos, fim de sessão, pré-compressão, espelhamento do MEMORY.md, bloco de system prompt). Valide com `hermes plugins doctor` e `hermes memory status`. Veja `integrations/hermes`.
Qwen Code	`~/.qwen/settings.json`	`agentmemory connect qwen` escreve o bloco `mcpServers` padrão. O payload dos hooks é compatível em nível de campo com o Claude Code, então os scripts dos 12 hooks existentes funcionam sem modificação; conecte-os via a seção `hooks` do mesmo `settings.json`.
Antigravity (substitui o Gemini CLI)	`mcp_config.json` (no diretório User do Antigravity)	`agentmemory connect antigravity` escreve o bloco `mcpServers` padrão. macOS: `~/Library/Application Support/Antigravity/User/`. Linux: `~/.config/Antigravity/User/`. Use após o sunset do Gemini CLI em 2026-06-18.
Antigravity CLI (`agy`)	`~/.gemini/config/mcp_config.json`	`agentmemory connect antigravity-cli`. O CLI `agy` mantém a própria configuração em `~/.gemini/`, separada do Antigravity IDE acima. Passe `--with-hooks` para captura automática nativa via `~/.gemini/config/hooks.json`.
Kiro	`~/.kiro/settings/mcp.json`	`agentmemory connect kiro` escreve a configuração no nível do usuário. Overrides por workspace vão em `.kiro/settings/mcp.json` ao lado do seu código.
Warp	`~/.warp/.mcp.json`	`agentmemory connect warp` escreve o bloco `mcpServers` padrão. O Warp também auto-descobre skills de `.claude/skills/`; instalado o plugin do Claude Code, as 8 skills do agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) aparecem nativamente na paleta de comandos slash do Warp.
Cline (CLI)	`~/.cline/mcp.json`	`agentmemory connect cline` escreve o bloco `mcpServers` padrão. Usuários da extensão do VS Code: cole o mesmo bloco via Cline Settings → MCP Servers → Edit JSON.
Continue.dev	`~/.continue/config.yaml` (preferido) ou `config.json` (legado)	`agentmemory connect continue` cria `config.yaml` do zero quando nenhum dos dois existe, ou modifica um `config.json` existente. Se você já tem `config.yaml`, o adaptador imprime o bloco exato para colar sob `mcpServers:`; ele não reescreve seu yaml silenciosamente porque preservar comentários e âncoras com segurança exige um parser YAML que o pacote não empacota. Continue usa a forma de array (não objeto) para `mcpServers`.
Zed	`~/.config/zed/settings.json`	`agentmemory connect zed` escreve sob `context_servers` (a chave do Zed, NÃO `mcpServers`). Servidores MCP remotos podem ser conectados via `{"url": "..."}` em vez disso.
Droid (Factory.ai)	`~/.factory/mcp.json`	`agentmemory connect droid` escreve o bloco `mcpServers` padrão. Overrides com escopo de projeto vão em `<repo>/.factory/mcp.json`. Passe `--with-hooks` para captura automática nativa.
DeepSeek Harness	`$DSH_HOME/cordis.patch.yml`	`agentmemory connect dsh` acrescenta uma linha `@deepseek-ai/dsh-mcp-client` à camada de patch no nível do home que todo perfil do Harness carrega; as tools se registram como `mcp__agentmemory__*`. Passe `--with-hooks` para também conectar a captura automática: os scripts de hook do Claude Code empacotados rodam pela bridge first-party `@deepseek-ai/dsh-hooks-claude-code` do Harness (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) via um manifesto escrito em `$DSH_HOME/agentmemory.hooks.json`. O padrão é `~/.dsh` quando `DSH_HOME` não está definido.
Goose	UI de configurações MCP do Goose	Mesmo bloco `mcpServers`; use `goose configure` → Add Extension → MCP. Edição direta do YAML em `~/.config/goose/config.yaml` é suportada, mas o schema usa `extensions:` + `cmd` (não `mcpServers:` + `command`).
Aider	n/a	Fale diretamente com a REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`.
Qualquer agente (32+)	n/a	`npx skillkit install agentmemory` autodetecta o host e mescla.

Clientes MCP em sandbox (Flatpak / Snap / contêineres restritivos) que não conseguem alcançar o localhost do host: também defina "AGENTMEMORY_FORCE_PROXY": "1" no bloco env, e aponte AGENTMEMORY_URL para uma rota que o sandbox realmente alcance (ex: seu IP de LAN).

Acesso programático (Python / Rust / Node)

agentmemory registra suas operações principais como funções iii (mem::remember, mem::observe, mem::context, mem::smart-search, mem::forget). Qualquer linguagem com um SDK iii pode chamá-las diretamente via ws://localhost:49134, sem um cliente REST separado por linguagem.

pip install iii-sdk         # Python
cargo add iii-sdk           # Rust
npm  install iii-sdk        # Node

from iii import register_worker

iii = register_worker("ws://localhost:49134")
iii.connect()

iii.trigger({
    "function_id": "mem::smart-search",
    "payload": {"project": "demo", "query": "how do tokens refresh"},
})

Exemplo prático: examples/python/ (quickstart + fluxo de observação/recall). A REST em :3111 continua disponível para hosts sem runtime iii.

A partir do código-fonte

git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start

Isso inicia o agentmemory com um iii-engine local se iii já estiver instalado, ou cai para Docker Compose se o Docker estiver disponível. REST, streams e o viewer fazem bind em 127.0.0.1 por padrão.

Instale o iii-engine manualmente. O agentmemory atualmente fixa o iii-engine em v0.11.2. A v0.11.6 introduz um novo modelo que faz sandbox de tudo via iii worker add que o agentmemory ainda não foi refatorado para usar. O pin sai assim que o refactor cair. Sobrescreva com AGENTMEMORY_III_VERSION=<version> se você migrou manualmente para o modelo de sandbox.

macOS arm64: mkdir -p ~/.local/bin && curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii
macOS x64: troque aarch64-apple-darwin por x86_64-apple-darwin
Linux x64: troque por x86_64-unknown-linux-gnu
Linux arm64: troque por aarch64-unknown-linux-gnu
Windows: baixe iii-x86_64-pc-windows-msvc.zip de iii-hq/iii releases v0.11.2, extraia iii.exe, adicione ao PATH

Ou use Docker (o docker-compose.yml empacotado puxa iiidev/iii:0.11.2). Docs completas: iii.dev/docs.

Windows

agentmemory roda em Windows 10/11, mas só o pacote Node.js não é suficiente; você também precisa do runtime iii-engine (um binário nativo separado) como processo em segundo plano. O instalador oficial upstream é um script sh e hoje não há instalador PowerShell nem pacote scoop/winget, então usuários de Windows têm dois caminhos:

Opção A: binário Windows pré-compilado (recomendado)

# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2 in your browser
#    (we pin to v0.11.2 until agentmemory refactors for the new sandbox
#     model that engine v0.11.6+ requires)
# 2. Download iii-x86_64-pc-windows-msvc.zip
#    (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
# 3. Extract iii.exe somewhere on PATH, or place it at:
#    %USERPROFILE%\.local\bin\iii.exe
#    (agentmemory checks that location automatically)
# 4. Verify:
iii --version
# Should print: 0.11.2

# 5. Then run agentmemory as usual:
npx -y @agentmemory/agentmemory

Opção B: Docker Desktop

# 1. Install Docker Desktop for Windows
# 2. Start Docker Desktop and make sure the engine is running
# 3. Run agentmemory — it will auto-start the bundled compose file:
npx -y @agentmemory/agentmemory

Opção C: apenas MCP standalone (sem engine). Se você só precisa das tools MCP para seu agente e não precisa da REST API, viewer ou cron jobs, pule o engine completamente:

npx -y @agentmemory/agentmemory mcp
# or via the shim package:
npx -y @agentmemory/mcp

Diagnóstico para Windows: se npx @agentmemory/agentmemory falhar, rode novamente com --verbose para ver o stderr real do engine. Modos de falha comuns:

Sintoma	Correção
`iii-engine process started` seguido de `did not become ready within 15s`	Engine crashou na inicialização; rode novamente com `--verbose`, verifique stderr
`Could not start iii-engine`	Nem `iii.exe` nem Docker estão instalados. Veja Opção A ou B acima
Conflito de porta	`netstat -ano \| findstr :3111` para ver o que está em bind, mate o processo ou use `--port <N>`
Fallback do Docker é pulado mesmo com Docker instalado	Confira se o Docker Desktop está de fato rodando (ícone na bandeja do sistema)

Nota: o engine iii é um binário pré-compilado, não um crate do cargo, então não tente instalá-lo com cargo install. (Os SDKs do iii são publicados no crates.io, npm e PyPI, mas o agentmemory não precisa deles.) Métodos de instalação do engine suportados, todos fixados em v0.11.2: o binário pré-compilado v0.11.2 acima, o script de instalação sh upstream com a fixação de versão curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh (macOS/Linux) e a imagem Docker iiidev/iii:0.11.2. Um simples install.sh | sh instala o engine mais recente, que o agentmemory não suporta; sempre passe VERSION=0.11.2. O mais fácil de tudo: basta rodar npx @agentmemory/agentmemory, que busca o engine fixado em ~/.agentmemory/bin para você.

Deploy

Templates de um clique para hosts gerenciados. Cada um inclui um Dockerfile autocontido que puxa @agentmemory/agentmemory do npm e copia o binário do iii engine da imagem oficial iiidev/iii no Docker Hub; sem necessidade de imagem pré-compilada do agentmemory. Armazenamento persistente monta em /data; o entrypoint de primeiro boot sobrescreve a configuração iii empacotada pelo npm (que faz bind em 127.0.0.1) por uma ajustada para deploy que faz bind em 0.0.0.0 e usa caminhos absolutos /data, gera o segredo HMAC e depois reduz privilégios de root para node via gosu antes de fazer exec do CLI do agentmemory.

O botão de deploy de um clique do Render exige um render.yaml na raiz do repositório, que mantemos limpo de propósito. Use o fluxo Render Blueprint documentado em deploy/render/ para apontar para o blueprint do repo manualmente.

Detalhes completos de setup (captura de HMAC, túnel SSH do viewer, rotação, backup, mínimos de custo) ficam em deploy/:

deploy/fly: máquina única com auto_stop_machines = "stop"; mais barato em idle.
deploy/railway: taxa plana do plano Hobby, volume no dashboard.
deploy/render: fluxo Blueprint, snapshots automáticos de disco nos planos pagos.
deploy/coolify: self-hosted no seu próprio VPS via Coolify; mesma stack Docker Compose, você possui o host e os dados.

Somente a porta 3111 é publicada. O viewer em 3113 fica em bind no loopback dentro do contêiner; o README de cada template documenta o padrão de túnel SSH para alcançá-lo.

Todo agente de codificação esquece tudo quando a sessão termina, e cada nova sessão começa com você re-explicando sua stack. agentmemory roda em segundo plano e remove essa etapa.

Session 1: "Add auth to the API"
  Agent writes code, runs tests, fixes bugs
  agentmemory silently captures every tool use
  Session ends -> observations compressed into structured memory

Session 2: "Now add rate limiting"
  Agent already knows:
    - Auth uses JWT middleware in src/middleware/auth.ts
    - Tests in test/auth.test.ts cover token validation
    - You chose jose over jsonwebtoken for Edge compatibility
  Zero re-explaining. Starts working immediately.

vs memória integrada do agente

Todo agente de codificação com IA vem com memória integrada: Claude Code tem MEMORY.md, Cursor tem notepads, Cline tem memory bank. Funcionam como post-its. agentmemory é o banco de dados pesquisável por trás dos post-its.

	Integrada (CLAUDE.md)	agentmemory
Escala	teto de 200 linhas	Ilimitado
Busca	Carrega tudo no contexto	BM25 + vector + graph (só top-K)
Custo em tokens	22K+ com 240 observações	~1.900 tokens (92% menos)
Cross-agent	Arquivos por agente	MCP + REST (qualquer agente)
Coordenação	Nenhuma	Leases, signals, actions, routines
Observabilidade	Leitura manual de arquivos	Viewer em tempo real em :3113

Pipeline de memória

PostToolUse hook fires
  -> SHA-256 dedup (5min window)
  -> Privacy filter (strip secrets, API keys)
  -> Store raw observation
  -> LLM compress -> structured facts + concepts + narrative
  -> Vector embedding (6 providers + local)
  -> Index in BM25 + vector

Stop / SessionEnd hook fires
  -> Summarize session
  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)

SessionStart hook fires
  -> Load project profile (top concepts, files, patterns)
  -> Hybrid search (BM25 + vector + graph)
  -> Token budget (default: 2000 tokens)
  -> Inject into conversation

Consolidação de memória em 4 níveis

Modelada em como o cérebro humano processa memória, incluindo a consolidação do sono.

Nível	O quê	Analogia
Working	Observações brutas a partir do uso de tools	Memória de curto prazo
Episodic	Resumos de sessão comprimidos	"O que aconteceu"
Semantic	Fatos 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). Memórias acessadas com frequência se reforçam. Memórias velhas são evictadas automaticamente. Contradições são detectadas e resolvidas.

O que é capturado

Hook	Captura
`SessionStart`	Caminho do projeto, ID da sessão
`UserPromptSubmit`	Prompts do usuário (filtrados por privacidade)
`PreToolUse`	Padrões de acesso a arquivos + contexto enriquecido
`PostToolUse`	Nome da tool, entrada, saída
`PostToolUseFailure`	Contexto do erro
`PreCompact`	Reinjeta memória antes da compactação
`SubagentStart/Stop`	Ciclo de vida de sub-agentes
`Stop`	Resumo de fim de sessão
`SessionEnd`	Marcador de sessão completa

Principais capacidades

Capacidade	Descrição
Captura automática	Todo uso de tool registrado via hooks, sem esforço manual
Busca semântica	BM25 + vector + grafo de conhecimento com fusão RRF
Evolução de memória	Versionamento, supersessão, grafos de relacionamento
Higiene de recall	Versões supersedidas de memória saem dos índices de busca; a cadeia de versões no KV mantém o histórico completo
Dicas de quase-duplicata	Saves reportam um match consultivo `similarTo` quando o novo conteúdo se parece muito com uma memória existente
Escopo por agente	`agentId` atravessa save e recall em REST, MCP e no índice de busca, em modo shared ou isolated
Provenance em tempo de escrita	Toda observação e memória carrega um canal de origem imutável (user, agent, tool, import ou shared) carimbado na captura, no save e no import
Auto-esquecimento	Expiração por TTL, detecção de contradição, evicção por importância
Privacy first	API keys, segredos e tags `<private>` são removidos antes do armazenamento
Self-healing	Circuit breaker, cadeia de fallback de providers, monitoramento de saúde
Ponte Claude	Sincronização bidirecional com MEMORY.md
Grafo de conhecimento	Extração de entidades + travessia BFS
Memória de time	Compartilhado namespaced + privado entre membros do time
Provenance de citação	Rastreia qualquer memória de volta às observações originais
Snapshots Git	Versiona, faz rollback e diff do estado de memória

Recuperação triple-stream combinando três sinais:

Stream	O que faz	Quando
BM25	Matching de palavra-chave com stemming + expansão de sinônimos	Sempre ativo
Vector	Similaridade de cosseno sobre embeddings densos	Provider de embedding configurado
Graph	Travessia do grafo de conhecimento via matching de entidades	Entidades detectadas na query

Fundidos com Reciprocal Rank Fusion (RRF, k=60) e diversificados por sessão (máximo de 3 resultados por sessão).

O ranqueamento híbrido se aplica ao caminho primário de recall, não só ao smart-search: mem::search (por trás de memory_recall) ranqueia pela mesma fusão BM25 + vector + graph assim que o índice vetorial está populado. O recall de lessons roda em um índice BM25 in-memory dedicado em vez de varrer o corpus inteiro a cada query. Versões supersedidas de memória são excluídas de todo caminho de recall; a cadeia de versões mantém o histórico delas.

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 quebrar runs CJK em tokens em nível de palavra; sem eles, o agentmemory faz soft-fallback para tokenização por run inteiro e imprime uma dica única no stderr.

Providers de embedding

agentmemory autodetecta seu provider. Para melhores resultados, instale embeddings locais (gratuito):

npm install @huggingface/transformers

Provider	Modelo	Custo	Notas
Local (recomendado)	`all-MiniLM-L6-v2`	Gratuito	Offline, +8pp de recall sobre BM25-only
Gemini	`gemini-embedding-001`	Free tier	100+ idiomas, 768/1536/3072 dims (MRL), entrada de 2048 tokens. Substitui `text-embedding-004` (deprecado, encerramento em 14 de janeiro de 2026)
OpenAI	`text-embedding-3-small`	$0.02/1M	Maior qualidade
Voyage AI	`voyage-code-3`	Pago	Otimizado para código
Cohere	`embed-english-v3.0`	Trial gratuito	Uso geral
OpenRouter	Qualquer modelo	Varia	Proxy multi-modelo

54 tools, 6 resources, 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 tools apenas quando consegue alcançar um servidor agentmemory em execução via AGENTMEMORY_URL (modo proxy). Sem servidor acessível, o shim cai para um set local de 7 tools (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 você vê só 7 tools no Cursor / OpenCode / Gemini CLI, inicie npx @agentmemory/agentmemory (ou a stack Docker) e defina AGENTMEMORY_URL=http://localhost:3111.

54 Tools

Três superfícies de tools, da menor para a 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 tools fundamentais do registry; o padrão (AGENTMEMORY_TOOLS=all) expõe todas as 54.

Tools base (14)

Tool	Descrição
`memory_recall`	Busca observações passadas
`memory_compress_file`	Comprime arquivos markdown preservando a estrutura
`memory_save`	Salva um insight, decisão ou padrão
`memory_file_history`	Observações passadas sobre arquivos específicos
`memory_patterns`	Detecta padrões recorrentes
`memory_sessions`	Lista sessões recentes
`memory_smart_search`	Busca híbrida semântica + por palavras
`memory_vision_search`	Busca observações de imagem
`memory_timeline`	Observações cronológicas
`memory_profile`	Perfil de projeto (conceitos, arquivos, padrões)
`memory_export`	Exporta todos os dados de memória
`memory_relations`	Consulta o grafo de relacionamentos
`memory_commit_lookup`	Sessões por trás de um commit git
`memory_commits`	Commits registrados para uma sessão

Tools estendidas (54 no total, a superfície padrão)

Tool	Descrição
`memory_patterns`	Detecta padrões recorrentes
`memory_timeline`	Observações cronológicas
`memory_relations`	Consulta o grafo de relacionamentos
`memory_graph_query`	Travessia do grafo de conhecimento
`memory_consolidate`	Executa a consolidação de 4 níveis
`memory_claude_bridge_sync`	Sincroniza com MEMORY.md
`memory_team_share`	Compartilha com membros do time
`memory_team_feed`	Itens compartilhados recentes
`memory_audit`	Trilha de auditoria de operações
`memory_governance_delete`	Deleção com trilha de auditoria
`memory_snapshot_create`	Snapshot versionado no Git
`memory_action_create`	Cria itens de trabalho com dependências
`memory_action_update`	Atualiza status de action
`memory_frontier`	Actions desbloqueadas ranqueadas por prioridade
`memory_next`	A única action mais importante a seguir
`memory_lease`	Leases exclusivos de actions (multiagente)
`memory_routine_run`	Instancia rotinas de workflow
`memory_signal_send`	Mensageria entre agentes
`memory_signal_read`	Lê mensagens com confirmação de recebimento
`memory_checkpoint`	Portões de condições externas
`memory_mesh_sync`	Sincronização P2P entre instâncias
`memory_sentinel_create`	Watchers dirigidos por eventos
`memory_sentinel_trigger`	Dispara sentinels externamente
`memory_sketch_create`	Grafos de actions efêmeros
`memory_sketch_promote`	Promove para permanente
`memory_crystallize`	Compacta cadeias de actions
`memory_diagnose`	Health checks
`memory_heal`	Corrige automaticamente estado travado
`memory_facet_tag`	Tags dimension:value
`memory_facet_query`	Consulta por tags de facet
`memory_verify`	Rastreia provenance

6 Resources · 3 Prompts · 17 Skills

Tipo	Nome	Descrição
Resource	`agentmemory://status`	Saúde, contagem de sessões, contagem de memórias
Resource	`agentmemory://project/{name}/profile`	Inteligência por projeto
Resource	`agentmemory://project/{name}/recent`	Observações recentes de um projeto
Resource	`agentmemory://memories/latest`	As 10 memórias ativas mais recentes
Resource	`agentmemory://graph/stats`	Estatísticas do grafo de conhecimento
Resource	`agentmemory://team/{id}/profile`	Perfil de time compartilhado
Prompt	`recall_context`	Busca + retorna mensagens de contexto
Prompt	`session_handoff`	Dados de handoff entre agentes
Prompt	`detect_patterns`	Analisa padrões recorrentes
Skill	`/recall`	Busca na memória
Skill	`/remember`	Salva na memória de longo prazo
Skill	`/session-history`	Resumos recentes de sessões
Skill	`/forget`	Deleta observações/sessões

A tabela mostra as quatro skills principais. O conjunto completo são 8 skills invocáveis mais 7 skills de referência; veja a seção de skills nativas acima.

MCP standalone

Rode sem o servidor completo, para qualquer cliente MCP. Qualquer um destes funciona:

npx -y @agentmemory/agentmemory mcp   # canonical (always available)
npx -y @agentmemory/mcp                # shim package alias

Ou adicione à configuração MCP do seu agente:

A maioria dos agentes (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI):

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      }
    }
  }
}

Mescle a entrada agentmemory no objeto mcpServers existente do seu host em vez de substituir o arquivo. Para clientes em sandbox que não conseguem alcançar o localhost do host, adicione "AGENTMEMORY_FORCE_PROXY": "1" ao bloco env e defina AGENTMEMORY_URL para uma rota que o sandbox alcance.

OpenCode (opencode.json):

{
  "mcp": {
    "agentmemory": {
      "type": "local",
      "command": ["npx", "-y", "@agentmemory/mcp"],
      "enabled": true
    }
  },
  "plugin": ["./plugins/agentmemory-capture.ts"]
}

Copie o arquivo do plugin do repo:

mkdir -p ~/.config/opencode/plugins
cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
cp plugin/opencode/commands/*.md ~/.config/opencode/commands/

Sobe automaticamente na porta 3113. Stream ao vivo de observações com um indicador de status do stream, um explorador de sessões em dois painéis (lista ao lado de um painel de detalhes fixo em telas largas), linhas de memórias e lessons que expandem para o registro completo armazenado incluindo JSON bruto e provenance de origem, um grafo de conhecimento que agrupa nós por tipo enquanto as relações são esparsas, replay de sessão e um dashboard de saúde.

open http://localhost:3113

O servidor do viewer faz bind em 127.0.0.1 por padrão. O endpoint servido por REST /agentmemory/viewer segue as regras normais de bearer-token AGENTMEMORY_SECRET. Os headers CSP usam um nonce de script por resposta e desabilitam atributos de handler inline (script-src-attr 'none').

O viewer em :3113 mostra o que seu agente lembrou. O iii console mostra o que seu agente fez: cada operação de memória como uma trace do OpenTelemetry, cada entrada KV editável, cada função invocável, cada stream observável. Duas janelas sobre a mesma memória: uma em formato de produto, outra em formato de engine.

Veja um memory_smart_search disparar e enxergue o scan BM25 → busca de embedding → fusão RRF → reranker como um waterfall. Edite um timer de consolidação travado no navegador KV. Reproduza um hook PostToolUse com payload ajustado. Fixe o stream WebSocket e veja as observações chegando ao vivo.

agentmemory oferece isso de graça porque toda chamada de função e trigger dispara através do iii; nada custom, nada para instrumentar.

Página Workers: todo worker conectado, incluindo o próprio agentmemory, com PID, contagem de funções, runtime e last-seen.

Já instalado. O console vem junto com iii; sem instalador separado.

Suba junto com o agentmemory:

# agentmemory viewer holds port 3113, so run the console on 3114.
# Engine REST (3111), WebSocket (3112), and bridge (49134) defaults match agentmemory.
iii console --port 3114

Depois abra http://localhost:3114. Adicione --enable-flow para a página experimental de grafo de arquitetura.

Sobrescreva endpoints do engine apenas se você os tiver movido:

iii console --port 3114 \
  --engine-port 3111 \
  --ws-port 3112 \
  --bridge-port 49134

O que você pode fazer pelo console:

Página	Use para
Workers	Ver todo worker conectado e suas métricas ao vivo, incluindo o próprio worker do agentmemory.
Functions	Invocar qualquer função do agentmemory diretamente com um payload JSON; útil para testar `memory.recall`, `memory.consolidate`, `graph.query` sem cabear um cliente.
Triggers	Reproduzir triggers HTTP, cron, event e state: disparar o cron de consolidação manualmente, reexecutar uma rota HTTP, emitir uma mudança de estado.
States	Navegador KV com CRUD completo sobre sessões, slots de memória, timers de ciclo de vida e o índice de embeddings; edite valores no lugar.
Streams	Monitor WebSocket ao vivo para escritas de memória, eventos de hook e atualizações de observação à medida que fluem pelos streams iii.
Queues	Tópicos de fila duráveis + gestão de dead-letter. Reproduza ou descarte jobs de embedding / compressão que falharam.
Traces	Vistas waterfall / flame / breakdown por serviço do OpenTelemetry. Filtre por `trace_id` para ver exatamente quais funções, chamadas a DB e requisições de embedding um único `memory.search` produziu.
Logs	Logs OTEL estruturados filtrados e correlacionados a trace/span IDs.
Config	Configuração de runtime: veja exatamente com quais workers, providers e portas seu engine está rodando.
Flow	(Opcional, `--enable-flow`) Grafo de arquitetura interativo de todo worker, trigger e stream.

Traces: waterfall / flame / breakdown por serviço para toda operação de memória.

Traces já estão ativos:

iii-config.yaml vem com o worker iii-observability habilitado (exporter: memory, sampling_ratio: 1.0, métricas + logs). Sem configuração extra; no momento em que o agentmemory inicia, toda operação de memória emite um trace span e um log estruturado que o console consegue ler.

Se você quiser exportar para Jaeger/Honeycomb/Grafana Tempo, troque exporter: memory por exporter: otlp e configure o endpoint do collector conforme a documentação de observabilidade do iii.

Aviso: nenhum auth é aplicado no console em si; mantenha-o em bind em 127.0.0.1 (o padrão) e nunca o exponha publicamente.

agentmemory já é uma instância iii em execução. Três primitivos (worker, function, trigger) compõem o runtime; estado KV, streams e traces OTEL vêm dos workers iii-state, iii-stream e iii-observability que acompanham o iii. Você não instalou Postgres, Redis, Express, pm2 ou Prometheus, porque o iii os substitui.

Isso significa que mais um comando estende o agentmemory com uma capacidade totalmente nova.

Estenda o agentmemory com um comando

iii worker add iii-pubsub          # fan memory writes out to every connected instance
iii worker add iii-cron            # scheduled consolidation, decay sweeps, snapshot rotation
iii worker add iii-queue           # durable retries for embedding + compression jobs
iii worker add iii-observability   # OTEL traces on every memory op (default on)
iii worker add iii-sandbox         # run recalled code inside an isolated microVM
iii worker add iii-database        # swap in a SQL-backed state adapter
iii worker add mcp                 # generic MCP host alongside the agentmemory MCP

Cada iii worker add registra novas funções e triggers no mesmo engine onde o agentmemory já está rodando. O viewer e o console os reconhecem na hora: sem reload, sem nova integração, sem novo contêiner.

`iii worker add`	O que você ganha em cima do agentmemory
`iii-pubsub`	Memória multi-instância: todo `remember` faz fanout, todo `search` lê a união
`iii-cron`	Ciclo de vida agendado: consolidação noturna, snapshots semanais, decaimento em relógio fixo
`iii-queue`	Retries duráveis: jobs falhos de embedding + compressão sobrevivem a restart, sem observações perdidas
`iii-observability`	Traces OTEL, métricas, logs em toda função, cabeado em `iii-config.yaml` desde o primeiro dia
`iii-sandbox`	Código que veio do `memory_recall` roda dentro de uma VM descartável, não no seu shell
`iii-database`	Adaptador de estado baseado em SQL quando você ultrapassa o KV in-memory padrão
`mcp`	Suba servidores MCP adicionais ao lado do MCP do agentmemory, compartilhando o mesmo engine

Registry completo: workers.iii.dev. Todo worker lá se compõe pelos mesmos primitivos que o agentmemory usa, e o agentmemory que você já tem é um deles.

O que o iii substitui

Stack tradicional	agentmemory usa
Express.js / Fastify	iii HTTP Triggers
SQLite / Postgres + pgvector	iii KV State + índice vetorial in-memory
SSE / Socket.io	iii Streams (WebSocket)
pm2 / systemd	Supervisão de workers do iii engine
Prometheus / Grafana	iii OTEL + monitor de saúde
Sistemas de plugin customizados	`iii worker add <name>`

182 arquivos de código · ~41.600 LOC · 1.619 tests · 264 funções · 50 escopos KV, tudo em cima de três primitivos. Sem agentmemory plugin install. O sistema de plugins é o próprio iii.

Providers de LLM

agentmemory autodetecta a partir do seu ambiente. Por padrão, nenhuma chamada LLM é feita a menos que você configure um provider ou opte explicitamente pelo fallback de assinatura do Claude.

Provider	Config	Notas
No-op (padrão)	Sem configuração	Compress/summarize via LLM DESATIVADO. Compressão sintética BM25 + recall ainda funcionam. Veja `AGENTMEMORY_ALLOW_AGENT_SDK` abaixo se você dependia do fallback de assinatura do Claude.
Anthropic API	`ANTHROPIC_API_KEY`	Cobrança por token
MiniMax	`MINIMAX_API_KEY`	Compatível com Anthropic
Gemini	`GEMINI_API_KEY`	Também habilita embeddings
OpenRouter	`OPENROUTER_API_KEY`	Qualquer modelo
OpenAI API	`OPENAI_API_KEY`	Padrão `gpt-5.6-luna`, sobrescreva 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=<your model>`	Qualquer coisa compatível com a API da OpenAI. Custo zero, roda no seu hardware. Veja Modelos locais abaixo.
Claude subscription fallback	`AGENTMEMORY_ALLOW_AGENT_SDK=true`	Apenas opt-in. Cria sessões de `@anthropic-ai/claude-agent-sdk`; costumava causar recursão sem limite no Stop-hook, por isso não é mais o padrão.

Modelos locais (Ollama / LM Studio / vLLM)

agentmemory conversa com qualquer servidor compatível com a API da OpenAI, então qualquer coisa que exponha /v1/chat/completions funciona sem mudanças de código. Sem chaves pagas, sem nuvem, sem rate limits; roda inteiramente no seu hardware.

Ollama (porta padrão 11434):

ollama pull qwen3:8b   # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
ollama serve

# ~/.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 padrão 1234):

Abra o LM Studio → aba Local Server → Start Server. Escolha qualquer modelo de chat no seletor (Qwen 3, gpt-oss, DeepSeek R1, etc.).

# ~/.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 a URL que seu servidor expõe e defina OPENAI_MODEL para um nome que seu servidor aceite.

Escolhas de modelo para trabalho de memória: compressão e sumarização são tarefas curtas (<2K tokens de entrada, <500 tokens de saída) em que um modelo instruct de 7B é mais que suficiente. Recomendações:

Modelo	Tamanho	Por quê
`qwen3:8b`	~5.2 GB	Padrão equilibrado numa máquina de 16 GB; forte em extração e texto em formato de tools
`qwen3:4b`	~2.6 GB	A menor opção sensata; OK para compressão, mais fraco para extração de grafo
`qwen3-coder:30b`	~19 GB	Melhor escolha local para sessões orientadas a 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	Distill de reasoning; mais lento, mas extrações mais limpas

Modelos Qwen 3 pensam por padrão e podem queimar todo o token budget em raciocínio antes de qualquer saída. Defina AGENTMEMORY_LLM_NOTHINK=1 para anexar /no_think aos prompts de extração de grafo, e aumente MAX_TOKENS (16384 funciona) se as extrações voltarem vazias.

Modelos classe reasoning (estilo o1 com blocos <think>) podem retornar content vazio com um campo reasoning que seu servidor local pode não expor. Se as extrações voltarem em branco, troque primeiro para um modelo sem reasoning. A env OPENAI_REASONING_EFFORT=none também pode desabilitar o thinking em modelos thinking do Ollama Cloud que espelham o schema de reasoning da OpenAI.

Embeddings locais vêm de fábrica via @huggingface/transformers: EMBEDDING_PROVIDER=local (padrão) te dá Xenova/all-MiniLM-L6-v2 (384 dims) inteiramente no dispositivo. Sem configuração extra.

Seleção de modelo com consciência de custo

A compressão em background roda em toda observação, então a escolha de modelo muda o gasto mensal de forma significativa. Dados de workload capturados: 635 requisições / 888K tokens / 35 horas de uso ativo, executados contra três modelos OpenRouter a preços de 2026-05-23.

Tier	Modelo	Input / 1M	Output / 1M	Custo para as 35h capturadas	Notas
Recomendado	`deepseek/deepseek-v4-flash-0731`	$0.07	$0.14	~$0.07 (est.)	DeepSeek mais recente; a escolha recomendada mais barata para workloads de compressão.
Recomendado	`deepseek/deepseek-v4-pro`	$0.435	$0.87	~$0.46	Qualidade sólida de compressão + sumarização a um custo ~10× menor que o Sonnet.
Recomendado	`qwen/qwen3-coder`	$0.45	$1.80	~$0.55	Bom raciocínio de código se suas sessões forem muito orientadas a código.
Premium	`anthropic/claude-sonnet-5`	$3.00	$15.00	~$5.02 (est.)	Mesmo preço de lista da execução medida com o Sonnet 4.6; preço introdutório de $2/$10 até 2026-08-31.
Premium	`openai/gpt-5.6-sol`	$5.00	$30.00	~$9 (est.)	Tier flagship; caro para trabalho de background sempre ativo.
Evitar	`anthropic/claude-opus-5`	$5.00	$25.00	~$8.40 (est.)	Modelo classe flagship; gasto desproporcional para compressão.

As linhas medidas vêm da execução capturada; as linhas (est.) escalam o mesmo mix de tokens pelo preço de lista de cada modelo.

agentmemory imprime um aviso em runtime quando OPENROUTER_MODEL casa com um padrão de tier premium. Defina AGENTMEMORY_SUPPRESS_COST_WARNING=1 para silenciar depois que você tiver tomado uma decisão informada.

Trade-off qualidade vs custo para trabalho de memória: compressão é uma tarefa de sumarização com critério de qualidade relativamente frouxo (quem relê o resumo é o agente, não o usuário). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder ficam dentro do erro de arredondamento do Sonnet nessa tarefa, custando 10-70× menos. Reserve os modelos tier premium para as queries que você lê diretamente.

Fontes: OpenRouter pricing for Claude Sonnet 5, DeepSeek V4 Flash, DeepSeek pricing notes.

Memória multiagente (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)

Em setups multiagente onde vários papéis compartilham um servidor agentmemory (architect / developer / reviewer / researcher / support-agent), AGENT_ID etiqueta cada escrita com o papel que a fez. AGENTMEMORY_AGENT_SCOPE controla se o recall filtra por essa tag.

TEAM_ID=company
USER_ID=engineering-team
AGENT_ID=architect
AGENTMEMORY_AGENT_SCOPE=isolated  # optional; default "shared"

Dois modos:

Modo	Etiqueta escritas	Filtra recall	Quando usar
`shared` (padrão)	sim	não	Contexto cross-agent com trilha de auditoria. O architect pode ver o que o developer anotou, mas toda linha registra quem disse.
`isolated`	sim	sim	Separação estrita. O architect nunca vê observações / memórias / sessões do developer.

O que é etiquetado quando AGENT_ID está definido: Session.agentId, RawObservation.agentId, CompressedObservation.agentId, Memory.agentId. O papel flui 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=<role> para sobrescrever por requisição, e ?agentId=* para sair do escopo do env por completo. /memories também aceita ?includeOrphans=true para mostrar memórias pré-AGENT_ID cujo agentId é undefined.

Override por chamada na camada SDK / REST: todo endpoint mutador (/session/start, /remember) aceita um campo agentId no body da requisição que vence o env. Útil para runtimes que roteiam muitos papéis por um único processo de servidor. A tool MCP memory_save expõe o mesmo campo agentId, o servidor stdio standalone repassa tanto agentId quanto project, e memórias salvas carregam agentId para o índice de busca, então a busca com escopo de agente cobre memórias além de observações.

Quando AGENT_ID não está definido, a memória permanece sem escopo (comportamento legado, sem tags, sem filtros).

Portas

agentmemory + iii-engine fazem bind em quatro portas por padrão. Se um restart falhar com port in use, esta tabela diz qual processo procurar.

Porta	Processo	Propósito	Override por env
`3111`	agentmemory	REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez`	`III_REST_PORT`
`3112`	iii-engine	Worker de streams interno (consumido por agentmemory + viewer)	`III_STREAMS_PORT`
`3113`	agentmemory	Viewer em tempo real (`http://localhost:3113`)	`AGENTMEMORY_VIEWER_PORT`
`49134`	iii-engine	WebSocket; workers se registram aqui, telemetria OTel flui por cima	`III_ENGINE_URL` (URL completa, padrão `ws://localhost:49134`)

Limpeza de processo travado quando as portas ficam ocupadas após uma execução crashada:

# macOS / Linux — find whatever is on each port and kill it
lsof -i :3111,3112,3113,49134
pkill -f agentmemory || true
pkill -f 'iii ' || true

# Windows
netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID <pid>

agentmemory stop recolhe tanto o worker quanto o pidfile do engine de forma limpa no shutdown graceful. No modo Docker ele derruba apenas os serviços compose do próprio agentmemory e recolhe o worker nativo antes do teardown do Docker; o CLI também se recusa a adotar ou sinalizar processos Docker ou de VM segurando portas (Docker backend, vpnkit, colima) como se fossem o engine nativo, a menos que --force seja passado. A limpeza manual acima só serve para o caso pós-crash em que nenhum pidfile foi deixado para trás.

Arquivo de configuração

Coloque a configuração de runtime do agentmemory em ~/.agentmemory/.env em vez de exportar variáveis em cada shell. Se o viewer mostrar uma dica de setup como export ANTHROPIC_API_KEY=..., copie para este arquivo como ANTHROPIC_API_KEY=... sem o prefixo export, depois reinicie o agentmemory.

Variáveis de ambiente do processo continuam funcionando e têm precedência sobre os valores no arquivo.

No Windows, o mesmo arquivo fica em %USERPROFILE%\.agentmemory\.env:

New-Item -ItemType Directory -Force $HOME\.agentmemory
notepad $HOME\.agentmemory\.env

Para testar com uma assinatura Claude Code Pro/Max em vez de uma API key, faça opt-in explícito:

AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true

Ligue features de graph ou consolidation no mesmo arquivo se quiser:

GRAPH_EXTRACTION_ENABLED=true
CONSOLIDATION_ENABLED=true

Variáveis de ambiente

Crie ~/.agentmemory/.env:

# LLM provider (pick one — default is the no-op provider: no LLM calls)
# ANTHROPIC_API_KEY=sk-ant-...
# ANTHROPIC_BASE_URL=...              # Optional: Anthropic-compatible proxy / Azure
# GEMINI_API_KEY=...
# OPENROUTER_API_KEY=...
# MINIMAX_API_KEY=...
# OPENAI_API_KEY=***                       # NOTE: this same key auto-activates BOTH the
#                                          # OpenAI LLM provider (here) AND the OpenAI
#                                          # embedding provider (further below). Set
#                                          # OPENAI_API_KEY_FOR_LLM=false to scope it
#                                          # to embeddings only.
# OPENAI_BASE_URL=https://api.openai.com   # Optional: override for Azure / vLLM / LM Studio / proxies
#                                          # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
#                                          # Auto-detected from `.openai.azure.com` hostname; uses
#                                          # api-key header + api-version query param.
# OPENAI_API_VERSION=2024-08-01-preview    # Optional: Azure api-version query param
# OPENAI_MODEL=gpt-5.6-luna                # Optional: default model
# OPENAI_TIMEOUT_MS=60000                  # Optional: OpenAI-scoped alias for the outbound fetch
#                                          # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
#                                          # for back-compat with v0.9.17. New configs should
#                                          # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
# OPENAI_REASONING_EFFORT=none             # Optional: "low" | "medium" | "high" | "none"
#                                          # Honored only by OpenAI's reasoning models (o1, o3,
#                                          # gpt-*-reasoning) and providers that mirror that
#                                          # schema (Ollama Cloud thinking models). Standard
#                                          # chat models reject this field with 400. Set to
#                                          # "none" for thinking models that return reasoning
#                                          # but no content.
# OPENAI_API_KEY_FOR_LLM=false             # Optional: set to false to skip OpenAI auto-detection
#                                          # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true

# Embedding provider (auto-detected, or override)
# EMBEDDING_PROVIDER=local
# VOYAGE_API_KEY=...
# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://api.openai.com   # Override for Azure / vLLM / LM Studio / proxies
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# OPENAI_EMBEDDING_DIMENSIONS=1536        # Required when the model is not in the known-models table

# Outbound LLM / embedding timeout
# AGENTMEMORY_LLM_TIMEOUT_MS=60000       # Default: 60 000 ms (60 s). Applies to every
                                          # raw-fetch provider (Gemini, OpenRouter, MiniMax,
                                          # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
                                          # embedding). For the OpenAI LLM path, the
                                          # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
                                          # takes precedence when set, for back-compat
                                          # with v0.9.17.
                                          # Increase for slow networks or large batch calls;
                                          # decrease to fail-fast on rate-limit holds.

# Search tuning
# BM25_WEIGHT=0.4
# VECTOR_WEIGHT=0.6
# TOKEN_BUDGET=2000

# Auth
# AGENTMEMORY_SECRET=your-secret

# Ports (defaults: 3111 API, 3113 viewer)
# III_REST_PORT=3111

# Features
# AGENTMEMORY_AUTO_COMPRESS=false  # OFF by default. When on,
                                   # every PostToolUse hook calls your
                                   # LLM provider to compress the
                                   # observation — expect significant
                                   # token spend on active sessions.
# AGENTMEMORY_SLOTS=false          # OFF by default. Editable pinned
                                   # memory slots — persona,
                                   # user_preferences, tool_guidelines,
                                   # project_context, guidance,
                                   # pending_items, session_patterns,
                                   # self_notes. Size-limited; agent
                                   # edits via memory_slot_* tools.
                                   # Pinned slots addressable for
                                   # SessionStart injection.
# AGENTMEMORY_REFLECT=false        # OFF by default. Requires SLOTS=on.
                                   # Stop hook fires mem::slot-reflect:
                                   # scans recent observations, auto-
                                   # appends TODOs to pending_items,
                                   # counts patterns in
                                   # session_patterns, records touched
                                   # files in project_context. Fire-
                                   # and-forget; does not block.
# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
                                   # - SessionStart may inject ~1-2K
                                   #   chars of project context into
                                   #   the first turn of each session
                                   #   (this is what actually reaches
                                   #   the model — Claude Code treats
                                   #   SessionStart stdout as context)
                                   # - PreToolUse fires /agentmemory/enrich
                                   #   on every file-touching tool call
                                   #   (resource cleanup, not a token
                                   #   fix — PreToolUse stdout is debug
                                   #   log only per Claude Code docs)
                                   # Observations are still captured via
                                   # PostToolUse regardless of this flag.
# GRAPH_EXTRACTION_ENABLED=false
# AGENTMEMORY_LLM_NOTHINK=1        # Local reasoning models only: ask the
                                   # model to skip its hidden thinking pass
                                   # during graph extraction. Faster runs;
                                   # relation quality can drop slightly.
# CONSOLIDATION_ENABLED=true
# LESSON_DECAY_ENABLED=true
# OBSIDIAN_AUTO_EXPORT=false
# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
# CLAUDE_MEMORY_BRIDGE=false
# SNAPSHOT_ENABLED=false

# Team
# TEAM_ID=
# USER_ID=
# TEAM_MODE=private

# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
# AGENTMEMORY_TOOLS=core

124 endpoints na porta 3111. A REST API faz bind em 127.0.0.1 por padrão. Endpoints protegidos exigem Authorization: Bearer <secret> quando AGENTMEMORY_SECRET está definido, e endpoints de mesh sync exigem AGENTMEMORY_SECRET em ambos os peers.

Endpoints principais

Method	Path	Descrição
`GET`	`/agentmemory/health`	Health check (sempre público)
`POST`	`/agentmemory/session/start`	Inicia sessão + obtém contexto
`POST`	`/agentmemory/session/end`	Encerra sessão
`POST`	`/agentmemory/observe`	Captura observação
`POST`	`/agentmemory/smart-search`	Busca híbrida
`POST`	`/agentmemory/context`	Gera contexto
`POST`	`/agentmemory/remember`	Salva na memória de longo prazo
`POST`	`/agentmemory/forget`	Deleta observações
`POST`	`/agentmemory/enrich`	Contexto de arquivo + memórias + bugs
`GET`	`/agentmemory/profile`	Perfil de projeto
`GET`	`/agentmemory/export`	Exporta todos os dados
`POST`	`/agentmemory/import`	Importa de JSON
`POST`	`/agentmemory/graph/query`	Query do grafo de conhecimento
`POST`	`/agentmemory/team/share`	Compartilha com o time
`GET`	`/agentmemory/audit`	Trilha de auditoria

Lista completa de endpoints: src/triggers/api.ts

npm run dev               # Hot reload
npm run build             # Production build
npm test                  # 1,619 tests
npm run test:integration  # API tests (requires running services)

Pré-requisitos: Node.js >= 20, iii-engine ou Docker

Apache-2.0

93 KiB Raw Blame History Unescape Escape