Agent Memory

Memória do agente do sistema de arquivos funcionando com o daemon de consolidação na sua máquina

GitHub
4
Experimente este MCPPatrocinado

Documentação

Um MCP de Filesystem para Agent Memory

mcp-agent-memory MCP server

Servidor MCP que expõe agent-memory-daemon a qualquer cliente compatível com MCP — Kiro (CLI e IDE), Claude Desktop, Cursor e outros.

O daemon faz o trabalho pesado (consolidação + extração); este servidor é uma ponte leve de filesystem para que agentes possam ler, anexar e buscar memória através do Model Context Protocol.

output

Como tudo se encaixa

 ┌──────────────┐     MCP/stdio     ┌────────────────────┐     filesystem      ┌────────────────────────┐
 │ Kiro / Claude│ ◄───────────────► │ mcp-server-memory  │ ◄─────────────────► │ agent-memory-daemon    │
 │   / Cursor   │                   │  (this package)    │   ~/.agent-memory/   │  (runs in background)  │
 └──────────────┘                   └────────────────────┘                     └────────────────────────┘
  • O servidor MCP lê/grava arquivos em ~/.agent-memory/
  • O daemon monitora o mesmo diretório e executa passadas de consolidação + extração
  • Eles nunca se comunicam diretamente — o filesystem é o contrato

Ferramentas expostas

memory_read

Lê o índice de memória do agente (MEMORY.md) e, opcionalmente, arquivos de tópicos específicos. Chame sem argumentos para carregar apenas o índice leve (barato). Passe topics somente quando precisar do conteúdo completo de um arquivo de tópico específico.

ParâmetroTipoObrigatórioDescrição
topicsstring[]NãoNomes de arquivos de tópico para carregar por completo (ex.: ["preferences", "projects"]). Omita para retornar apenas o índice.

memory_append_session

Anexa um resumo de sessão ao diretório de sessões. O daemon extrairá posteriormente memórias duráveis dele. Chame esta ferramenta ao final de trocas significativas. Mantenha os resumos focados em descobertas e decisões duráveis (alvo de 300–800 tokens), não em relato passo a passo — resumos mais longos custam mais durante a consolidação.

ParâmetroTipoObrigatórioDescrição
contentstringSimResumo de sessão formatado em Markdown. Use cabeçalhos estruturados e marcadores para melhor extração; evite prosa prolixa.
sourcestringNãoTag de origem, ex.: "kiro", "claude-desktop"

memory_search

Busca uma substring nos arquivos de memória. Use esta ferramenta para recuperar fatos específicos sem carregar tudo.

ParâmetroTipoObrigatórioDescrição
querystringSimA substring a ser buscada em todos os arquivos de memória.

Instalação

npm install -g mcp-agent-memory

Início rápido (assistente interativo)

A forma mais rápida de configurar tudo — diretório de memória, daemon, configurações de clientes, logs e LaunchAgent — é o assistente de configuração:

mcp-agent-memory --setup

Ele faz seis perguntas:

  1. Diretório de memória — onde .agent-memory/ fica (padrão ~/.agent-memory)
  2. Instalar o daemon de consolidação? — diga "não" para o modo somente MCP (agentes podem ler/gravar/buscar memória, mas sem consolidação automática)
  3. Backend de LLM — bedrock, openai ou kiro (ignorado se você recusou o daemon)
  4. Configurações de consolidação — min_hours, min_sessions, intervalo de extração, máx. de caracteres
  5. Modo de execução — standalone (iniciar manualmente) ou launchagent (início automático no login, somente macOS)
  6. Diretório de logs + TTL — onde colocar os logs e por quantos dias mantê-los (0 = para sempre)
  7. Registro de clientes — registrar automaticamente o servidor MCP nas configurações do Kiro, Claude Desktop e/ou Cursor (entradas MCP existentes são preservadas)

Quando você seleciona o backend kiro, o assistente também copia um agente enxuto para ~/.kiro/agents/memconsolidate.json que reduz o uso de tokens em ~7× (veja backend Kiro).

Quando você seleciona launchagent, o assistente verifica se agent-memory-daemon está instalado (e oferece npm install -g caso não esteja) e então registra e inicia o plist.

Referência da CLI

mcp-agent-memory                       # run as an MCP server (normal mode — clients spawn it)
mcp-agent-memory --setup               # first-time interactive setup
mcp-agent-memory --configure           # re-run most steps; can add/remove the daemon later
mcp-agent-memory --remove              # interactive uninstall (backup memory, clean configs)

# macOS LaunchAgent control:
mcp-agent-memory --daemon status       # is the daemon running?
mcp-agent-memory --daemon start        # load and start
mcp-agent-memory --daemon stop         # unload (keeps the plist)
mcp-agent-memory --daemon restart      # stop + start
mcp-agent-memory --daemon remove       # unload and delete the plist

--remove preserva outras entradas nas configurações MCP dos clientes — apenas a chave memory é excluída. Por padrão, ele faz backup de ~/.agent-memory/ em um diretório .bak-* com timestamp para que você possa restaurar suas memórias consolidadas.

Instalação manual

Se você preferir pular o assistente, veja como fazer manualmente.

Instalar o daemon (opcional)

O servidor MCP funciona de forma autônoma — ele apenas lê e grava arquivos em ~/.agent-memory/. As memórias persistem, mas não serão consolidadas nem extraídas das sessões até que você adicione o daemon.

npm install -g agent-memory-daemon

# copy the example config
mkdir -p ~/.agent-memory
cp examples/memconsolidate.toml ~/.agent-memory/memconsolidate.toml

# start the daemon
agent-memory-daemon start ~/.agent-memory/memconsolidate.toml

Consulte examples/memconsolidate.toml para obter uma configuração pronta para uso que corresponde ao layout de diretório que este servidor MCP espera.

Executar o daemon no login (macOS)

Em vez de iniciar o daemon manualmente, registre-o como um LaunchAgent:

./scripts/daemon.sh start          # install plist, load it, start at login
./scripts/daemon.sh status         # check if it's running
./scripts/daemon.sh stop           # unload (keeps the plist)
./scripts/daemon.sh remove         # unload and delete the plist

Passe um caminho de configuração personalizado como segundo argumento: ./scripts/daemon.sh start /path/to/config.toml. Os logs vão para ~/.agent-memory/logs/daemon.{out,err}.log. remove deixa seus arquivos de configuração e memória intactos.

Usar o Kiro como backend de LLM

Se você tem créditos no Kiro, pode executar o daemon por meio de kiro-cli em vez de pagar por chamadas de API da Bedrock ou da OpenAI. Isso requer agent-memory-daemon ≥ 2.7 (branch feat/kiro-backend), que adiciona um backend kiro.

[llm_backend]
name = "kiro"
# optional overrides:
# binary = "/custom/path/to/kiro-cli"
# agent = "memconsolidate"          # set to "" to use Kiro's default session context (not recommended)
# model = "claude-sonnet-4-20250514"
# timeoutMs = 300000

Use um agente enxuto para reduzir o uso de tokens em ~7×. Por padrão, toda chamada kiro-cli chat carrega o system prompt completo do Kiro mais todos os schemas de ferramentas MCP da sua configuração global — cerca de 12–18K tokens extras de entrada por chamada. Crie um agente mínimo que ignore tudo isso:

cp examples/kiro-agent-memconsolidate.json ~/.kiro/agents/memconsolidate.json

O backend do Kiro passa --agent memconsolidate automaticamente, então nenhuma configuração adicional é necessária. Medido em um prompt trivial: 0,01 créditos com o agente enxuto vs. 0,07 créditos com o padrão (mesma qualidade de saída).

Consulte examples/kiro-agent-memconsolidate.json — o agente tem mcpServers: {}, tools: [] e useLegacyMcpJson: false para não herdar nada da sua configuração global do Kiro.

Configurar clientes manualmente

Os assistentes --setup e --configure cuidam disso para você. Esta seção é para usuários que querem configurar tudo manualmente.

Kiro (CLI e IDE)

Edite ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "mcp-agent-memory"],
      "env": {
        "MEMORY_DIRECTORY": "~/.agent-memory/memory",
        "SESSION_DIRECTORY": "~/.agent-memory/sessions"
      },
      "disabled": false,
      "timeout": 30000,
      "autoApprove": ["memory_read", "memory_search", "memory_append_session", "memory_daemon_status"]
    }
  }
}

Por que autoApprove? Todas as ferramentas de memória são operações de filesystem apenas locais — elas leem/gravam arquivos markdown em ~/.agent-memory/ e nunca fazem chamadas de rede. Adicioná-las a autoApprove permite que o Kiro as chame sem pedir confirmação a cada vez, o que é essencial para a experiência perfeita de "ler memória no início da sessão".

Em seguida, peça ao Kiro: "Leia meu índice de memória." ou "Lembre disto: prefiro pnpm a npm."

Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "mcp-agent-memory"],
      "env": {
        "MEMORY_DIRECTORY": "~/.agent-memory/memory",
        "SESSION_DIRECTORY": "~/.agent-memory/sessions"
      },
      "autoApprove": ["memory_read", "memory_search", "memory_append_session", "memory_daemon_status"]
    }
  }
}

Reinicie o Claude Desktop. As ferramentas memory_* aparecerão.

Cursor

Adicione a ~/.cursor/mcp.json com o mesmo bloco de servidor (incluindo autoApprove).

Variáveis de ambiente

VariávelPadrãoDescrição
MEMORY_DIRECTORY~/.agent-memory/memoryOnde o daemon armazena os arquivos de memória consolidados
SESSION_DIRECTORY~/.agent-memory/sessionsOnde os resumos de sessão escritos por agentes são salvos

Ambos os caminhos devem corresponder ao que sua configuração agent-memory-daemon usa.

Prompt recomendado para o agente

Instrua seu agente a chamar memory_read no início de uma conversa e memory_append_session no final. Exemplo de regra de direcionamento para o Kiro (~/.kiro/steering/memory.md):

At the start of every session, call memory_read (no arguments) to load my memory
index. Only pass `topics` when the task genuinely needs the full content of a
specific topic file.

When you learn something durable about me, my projects, or my preferences, call
memory_append_session with a concise markdown summary. Target 300-800 tokens,
use structured headers and bullets (not prose), and focus on durable findings
and decisions — not play-by-play. Verbose summaries cost more during the
daemon's consolidation pass.

Dicas de uso de tokens

Cada uma das três ferramentas tem um perfil de custo diferente. Algumas práticas mantêm as contas de inferência + consolidação baixas:

  • memory_read sem argumentos retorna apenas o índice MEMORY.md (normalmente <1 KB). Prefira esta opção a topics a menos que precise do conteúdo completo.
  • memory_search é baseada em substring e retorna ≤3 linhas correspondentes por arquivo — mais barata do que carregar arquivos de tópico inteiros.
  • memory_append_session não custa nada no momento da chamada, mas toda sessão é processada pelo LLM do daemon durante a consolidação. Mantenha os resumos concisos e estruturados.
  • Consolide ou remova arquivos de tópicos antigos ocasionalmente. Execute mcp-agent-memory --configure — ele agora avisa se o seu diretório de memória exceder 25 arquivos ou 200 KB.
  • A poda de sessões após a extração é tratada pelo daemon, não pelo servidor MCP. Consulte a configuração de agent-memory-daemon para opções que arquivam ou excluem sessões após o processamento (evita que o daemon reexamine sessões antigas para sempre).

Licença

MIT