memory-lean

Memória de longo prazo para agentes de codificação de IA que não consome a janela de contexto. Um substituto direto para o servidor de memória de referência, com respostas cerca de 40 vezes menores. Um único arquivo, zero dependências.

GitHub

Documentação

memory-lean

Memória de longo prazo para agentes de codificação de IA que não queima a janela de contexto.

Início rápido · O que o agente vê · Por que ele permanece enxuto · Ferramentas · Protocolo do agente · Configurações · Contribuindo

memory-lean é um servidor MCP que dá ao Claude Code, Claude Desktop, Cursor e qualquer outro cliente MCP um grafo de conhecimento que persiste entre sessões. Ele é um substituto direto para o servidor de memória de referência (@modelcontextprotocol/server-memory): mesmo arquivo memory.jsonl, mesmos nove nomes de ferramentas, mais dois extras. O que muda é o quanto as ferramentas enviam de volta.

Chamada, em um grafo real de 237 entidades	Servidor de referência	memory-lean
`read_graph`	~77.800 tokens	~2.000 tokens	40× menor
`search_nodes` (média de 5 palavras comuns)	~31.000 tokens	~770 tokens	40× menor

Um arquivo. Sem dependências. Nada para compilar.

Início rápido

Claude Code: instale o plugin. Ele adiciona o servidor, uma skill com as instruções do agente e um lembrete curto no início de cada sessão.

/plugin marketplace add zamansheikh/memory-lean
/plugin install memory-lean@memory-lean

Qualquer outro agente: adicione o servidor à configuração MCP do agente e dê a ele as instruções.

{
  "mcpServers": {
    "memory": { "command": "npx", "args": ["-y", "memory-lean"] }
  }
}

npx -y memory-lean --protocol >> AGENTS.md   # into the rules file your agent reads

O arquivo de configuração e seu formato exato variam conforme o agente.

A configuração copiar-e-colar para cada agente está em docs/SETUP.md:

Agente	Configuração do servidor	Instruções
Claude Code	plugin	incluídas no plugin
Xiaomi MiMo Code	`mimocode.jsonc`	skill ou `AGENTS.md`
opencode	`opencode.json`	`AGENTS.md`
OpenAI Codex CLI	`codex mcp add`	`AGENTS.md`
Cursor	`.cursor/mcp.json`	`AGENTS.md` ou uma regra
VS Code (Copilot)	`.vscode/mcp.json`	`copilot-instructions.md`
Gemini CLI	`settings.json`	`GEMINI.md`
Windsurf	`mcp_config.json`	uma regra
Cline	`cline_mcp_settings.json`	`.clinerules/`
Zed	`settings.json`	`AGENTS.md` ou `.rules`
IDEs JetBrains	configurações do AI Assistant	uma regra ou diretrizes
Claude Desktop	`claude_desktop_config.json`	instruções do projeto

O grafo é criado na primeira gravação em ~/.claude/memory-graph/memory.jsonl, independentemente de qual agente grava nele, para que vários agentes possam compartilhar uma única memória. Defina MEMORY_FILE_PATH para mantê-lo em outro lugar.

Executar a partir de um clone em vez de npm

git clone https://github.com/zamansheikh/memory-lean.git
claude mcp add --scope user memory -- node /absolute/path/to/memory-lean/server/memory-lean.mjs

Nenhum npm install é necessário.

O que o agente vê

O servidor de referência responde a uma busca com cada entidade correspondente por completo, como JSON formatado. memory-lean responde com uma lista classificada de nomes e as linhas que corresponderam:

> search_nodes { "query": "deploy" }

57 match "deploy", top 10 shown (narrow the query or raise limit). open_nodes for full entities.
- shop-backend [service] 12 obs, 6 rel
    › 2026-03-02: deployed 2.4.0 to production
    › deploy with scripts/release.sh, never by hand
- PENDING shop-backend 2.4.0 [pending] 2 obs, 3 rel
    › …mobile apps still call the old endpoint until the deploy of 2.4.0 reaches them

O agente então abre apenas o que precisa:

> open_nodes { "names": ["shop-backend"] }

## shop-backend [service]
- NestJS API behind api.example.com
- 2026-03-02: deployed 2.4.0 to production

## relations
shop-app -talks_to-> shop-backend
PENDING shop-backend 2.4.0 -blocks-> shop-app

Esse é o padrão completo: buscar, depois abrir.

Por que ele permanece enxuto

Um grafo de conhecimento só é útil se o agente puder se dar ao luxo de olhá-lo, e um grafo ao qual cada sessão adiciona cresce sem limite. memory-lean limita tanto o que retorna quanto o que armazena.

Limite	O que significa
Respostas pequenas	`search_nodes` retorna no máximo 10 nomes com trechos, `read_graph` retorna um índice de nomes, e apenas `open_nodes` retorna entidades completas.
Fatos curtos	Uma observação com mais de 300 caracteres é rejeitada, com uma mensagem dizendo ao agente para dividi-la ou colocar o detalhe no repositório.
Um teto por entidade	Uma entidade mantém 15 observações. Além disso, as mais antigas com data são movidas para `archive/<entity>.md` ao lado do grafo. Nada é excluído: o agente pode listar e restaurá-las, e observações sem data (os fatos de identidade) sempre permanecem.
Busca multipalavra que funciona	Cada palavra deve corresponder em algum lugar da entidade, então adicionar uma palavra restringe o resultado. O servidor de referência procura a consulta como uma frase exata única.

E ele é cuidadoso com o arquivo:

Salvaguarda	O que significa
Seguro para compartilhar	Os gravadores usam um arquivo de bloqueio, para que várias sessões de agente possam usar um grafo sem sobrescrever umas às outras. Cada gravação substitui o arquivo atomicamente.
Backups diários	Uma cópia vai para `backups/` uma vez por dia; os últimos 7 são mantidos.
Linhas danificadas são mantidas	Uma linha que não pode ser lida é movida para `memory.jsonl.unreadable` na próxima gravação e relatada, nunca descartada silenciosamente.
Arquivos simples	O grafo é JSON lines, os arquivos são Markdown, os backups são cópias. Você pode ler, usar grep e editar tudo manualmente.

Meça no seu próprio grafo

A partir de um clone deste repositório:

node tools/bench.mjs                  # read_graph + your five most common words
node tools/bench.mjs deploy "api v2"  # your own queries

É somente leitura e imprime tamanhos, nunca conteúdo. Tokens são estimados como caracteres ÷ 4. Uma busca estreita que corresponde a uma ou duas entidades economiza muito menos, porque havia pouco para aparar.

Ferramentas

Ferramenta	O que retorna
`search_nodes`	Lista classificada de nomes de entidades com contagens e até dois trechos correspondentes cada. Cada palavra deve corresponder ao nome, tipo, uma observação ou o tipo de uma relação que toca a entidade.
`open_nodes`	As entidades completas que você nomeia, como texto compacto, com todas as relações que as tocam. Nomes desconhecidos retornam com sugestões "você quis dizer".
`read_graph`	Um índice: nomes de entidades agrupados por tipo, com contagens de observações. Nunca as observações.
`create_entities`	Cria entidades; nomes existentes são ignorados.
`create_relations`	Cria relações entre entidades existentes; duplicatas são ignoradas.
`add_observations`	Adiciona fatos a uma entidade, aplicando o limite de comprimento e o teto por entidade.
`rename_entity`	Renomeia uma entidade, mantendo suas observações, relações e arquivo. Não está no servidor de referência.
`archived_observations`	Lista o que foi arquivado para uma entidade, opcionalmente filtrado, e pode restaurar observações escolhidas. Não está no servidor de referência.
`delete_observations`	Remove observações por texto exato.
`delete_relations`	Remove relações específicas.
`delete_entities`	Remove entidades e todas as relações que as tocam.

As três ferramentas de leitura são marcadas como somente leitura, para que clientes que suportam isso possam executá-las sem perguntar.

Ensine seu agente a usá-lo

Um servidor de memória só ajuda se o agente o lê antes de trabalhar e grava nele quando algo muda. docs/AGENT-PROTOCOL.md é um conjunto pronto de instruções: o que consultar no início de uma tarefa, o que registrar, como nomear coisas e o que nunca armazenar. O plugin do Claude Code o inclui. Para todos os outros agentes, um comando o instala:

npx -y memory-lean --protocol >> AGENTS.md     # into a rules file: always on
npx -y memory-lean --skill .agents/skills      # as an Agent Skill: loaded when relevant

Ajuste os tipos de entidade e nomes nele para o seu próprio trabalho.

Vindo do servidor de memória de referência

Aponte MEMORY_FILE_PATH para seu memory.jsonl existente e troque o comando. O formato do arquivo é idêntico, então você pode voltar a qualquer momento. Observações existentes com mais de 300 caracteres são mantidas como estão; apenas novas gravações são verificadas.

Para ver o que em um grafo existente está acima do orçamento e, opcionalmente, corrigir:

npx -y memory-lean --lint      # report only
npx -y memory-lean --compact   # back up, then move overflow to archive/

Configurações

Todas opcionais, definidas como variáveis de ambiente no servidor:

Variável	Padrão	Significado
`MEMORY_FILE_PATH`	`~/.claude/memory-graph/memory.jsonl`	Onde o grafo vive
`MEMORY_OBS_MAX_CHARS`	`300`	Observação mais longa aceita
`MEMORY_OBS_MAX`	`15`	Observações por entidade antes que as mais antigas com data sejam arquivadas
`MEMORY_SEARCH_LIMIT`	`10`	Número padrão de resultados de busca
`MEMORY_BACKUPS_KEPT`	`7`	Backups diários mantidos

Bom saber

Seu grafo é privado. Ele guarda o que seu agente aprendeu sobre seus projetos. Mantenha-o fora do git e nunca armazene senhas, chaves ou tokens nele: registre onde um segredo vive, não seu valor.
A busca é correspondência de texto simples, não embeddings. Nomes de entidades bons importam mais do que consultas inteligentes.

Roadmap

Um plugin do Claude Code que instala o servidor e o protocolo do agente juntos
Configuração pronta para MiMo Code, Codex, Cursor e outros agentes
Guias de configuração para Cline, Zed e IDEs JetBrains
Windows na matriz de CI
rename_entity, mantendo relações intactas
Uma maneira de listar e restaurar observações arquivadas
Listagens no registro MCP e no diretório de plugins do Claude Code
Busca em observações arquivadas de todas as entidades

Contribuindo

Ideias, relatórios de bugs e pull requests são bem-vindos. O servidor inteiro é um arquivo sem dependências, e npm test roda em cerca de um segundo, então uma primeira mudança é rápida de fazer. CONTRIBUTING.md tem o layout, as regras básicas e uma lista de boas primeiras contribuições.

Se você experimentar memory-lean no seu próprio grafo, a saída de tools/bench.mjs é um post de issue útil. E se ele economizar tokens para você, uma ⭐ ajuda outras pessoas a encontrá-lo.