Memento-cmp

Uma arquitetura de memória de três camadas para LLMs (Redis + Postgres + Vector) MCP

GitHub

171

Documentação

AnchorMind Logo

Português

AnchorMind

O que é isso | Como funciona | Como instalar | Perguntas frequentes

O que é isso

É um servidor MCP que dá aos agentes de IA (Claude Code, Cursor, Codex etc.) memória de longo prazo que persiste após o fim da sessão. Você mesmo hospeda, e as memórias são armazenadas em PostgreSQL.

Quando a sessão termina, o agente esquece a conversa anterior. Em resumo, você precisa explicar tudo de novo. Configurações de projeto, bugs resolvidos ontem, preferências de estilo de trabalho — coisas que são chatas de repetir toda vez — o AnchorMind guarda em unidades curtas (fragmentos) e, na próxima sessão, entrega apenas o que for necessário.

Quando usar

Você usa agentes de IA diariamente e repete as mesmas explicações a cada sessão.
Quer compartilhar as mesmas memórias entre vários agentes (Claude Code, Cursor, Codex etc.) e vários dispositivos.
Quer separar memórias por projeto ou cliente.
Quer manter as memórias no seu próprio servidor e no seu próprio banco de dados.

Como funciona

Execute o servidor AnchorMind.
Registre-o como servidor MCP no agente.
Quando a sessão começa, o agente recebe as memórias principais do servidor. Durante a conversa, ele busca memórias quando necessário e salva o que deve ser mantido.
O agente responde com base nessas memórias.

Na visão do usuário, é mais ou menos assim.

[세션 1]
사용자: 우리 프로젝트는 PostgreSQL 15를 쓰고 테스트는 Vitest로 돌려.
에이전트: (remember 호출, 파편 2개 저장)

[다음 날, 새 세션]
에이전트: (시작하며 context 호출, 저장해 둔 파편 2개를 받음)
사용자: 테스트 어떻게 돌리더라?
에이전트: (recall 호출) 이 프로젝트는 Vitest를 쓴다. npx vitest로 실행하면 된다.

Você não precisa repetir as mesmas explicações a cada nova sessão. O fluxo completo está no diagrama abaixo.

sequenceDiagram
    participant U as 사용자
    participant A as 에이전트
    participant M as AnchorMind 서버
    participant D as PostgreSQL

    U->>A: 세션 시작
    A->>M: context
    M->>D: 선호, 에러, 절차, 결정 조회
    M-->>A: 핵심 기억
    U->>A: 질문
    A->>M: recall
    M-->>A: 관련 기억
    A-->>U: 기억을 참고한 답변
    A->>M: remember (새 결정, 해결한 에러)
    U->>A: 세션 종료
    A->>M: reflect (세션 요약)

As chamadas de ferramenta são feitas pelo agente. O servidor não inicia conversa. Para garantir que o agente chame as ferramentas sem esquecer, é preciso configurar hooks ou arquivos de instrução (Como fazer o agente usar automaticamente).

Como instalar

Instalação do servidor

Pré-requisitos: Node.js 22+, Docker. Se você já tiver PostgreSQL com pgvector instalado, o Docker não é necessário.

1. Banco de dados (pule se já tiver)

docker run -d --name anchormind-db -p 5432:5432 \
  -e POSTGRES_PASSWORD=change-me -e POSTGRES_DB=memento \
  -v anchormind-pgdata:/var/lib/postgresql/data pgvector/pgvector:pg15

docker exec anchormind-db psql -U postgres -d memento \
  -c "CREATE EXTENSION IF NOT EXISTS vector"

2. Servidor

git clone https://github.com/JinHo-von-Choi/anchormind.git
cd anchormind
npm install

cp .env.example.minimal .env

Abra o .env e altere apenas duas coisas.

Mude o MEMENTO_ACCESS_KEY para um valor diferente de change-me. Esse valor é a chave mestra e é usado como token Authorization: Bearer.
Adicione as três linhas abaixo. É a configuração de embeddings locais para usar busca em linguagem natural sem chaves de API externas.

EMBEDDING_PROVIDER=transformers
EMBEDDING_MODEL=Xenova/multilingual-e5-small
EMBEDDING_DIMENSIONS=384

As configurações de banco de dados já estão alinhadas com o valor de docker run acima, então deixe como está. Agora execute.

npm run migrate
node scripts/post-migrate-flexible-embedding-dims.js
node server.js

Na primeira execução, o modelo de embeddings será baixado. O tamanho é de aproximadamente 120MB.

3. Verificação

curl http://localhost:57332/health

Se aparecer {"status":"healthy", ...}, está funcionando. Para verificar salvamento e consulta de uma vez, siga o First Memory Flow.

Se precisar de mais:

Criar .env enquanto responde perguntas, usar API de embeddings externa: INSTALL.md
Delegar a instalação a um assistente de IA: INSTALL.md
Operar continuamente com Docker: Production Docker
Windows: Guia WSL2
Se travar: Solução de problemas

Conectar ao agente

Claude Code:

claude mcp add anchormind http://localhost:57332/mcp \
  --transport http \
  --scope user \
  --header "Authorization: Bearer YOUR_ACCESS_KEY"

Se Connected aparecer em claude mcp list, está conectado. O Claude Code não reconhece servidores MCP HTTP escritos diretamente em settings.json, então use o comando acima ou .mcp.json.

Para conectar a outros clientes, como Cursor, Codex, Windsurf, Claude.ai Web, ChatGPT etc., veja Conexão por cliente.

Depois de conectar, para que o agente use as ferramentas de memória automaticamente, veja a FAQ abaixo.

Perguntas frequentes

Uma resposta por pergunta. Se não encontrar o que procura, consulte Solução de problemas ou Issues.

É a ferramenta certa?

Qual é a diferença para anotações em arquivos como CLAUDE.md ou MEMORY.md?

Anotações em arquivos precisam ser lidas por completo a cada sessão. Conforme o conteúdo cresce, os tokens aumentam e é fácil haver conflito entre informações antigas e novas. O AnchorMind busca apenas os fragmentos necessários e os retorna dentro de tokenBudget.

Qual é a diferença para RAG?

RAG indexa documentos existentes para encontrá-los. O AnchorMind é memória que o agente escreve e relê diretamente durante a conversa. As memórias salvas são organizadas pelo servidor com técnicas como mesclagem de duplicatas, detecção de contradições e decaimento de importância.

Posso usar como base de conhecimento?

Sim. Basta inserir fatos como fragmentos de uma ou duas frases e buscá-los com recall. Não é para indexar documentos longos inteiros.

Posso usar junto com outras ferramentas de memória que já uso?

Sim. Como é um servidor MCP, pode ser registrado no mesmo agente. O nome do servidor aparece antes do nome da ferramenta, então dá para diferenciar (exemplo: mcp__anchormind__recall).

Como saber se vale a pena migrar da ferramenta que já uso?

Se pelo menos um dos três itens abaixo se aplicar, vale a pena tentar. Se nenhum se aplicar, a ferramenta atual já é suficiente.

Você precisa manter os dados no seu próprio servidor.
Você precisa usar as mesmas memórias em vários agentes e dispositivos.
Você quer que o servidor organize duplicatas e contradições.

Em quais casos não é adequada?

Se o que precisa memorizar cabe em uma página de CLAUDE.md, um arquivo é mais simples.
Você precisa operar PostgreSQL (pgvector).
A busca é orientada a fatos. É fraca para perguntas que exigem síntese de raciocínio longo (benchmark).

Instalação e requisitos

Preciso de modelo de embeddings ou chave OpenAI?

Não é obrigatório. Com apenas PostgreSQL, salvamento, recall por palavras-chave, links e funções de gerenciamento funcionam. Porém, sem embeddings, perguntas em linguagem natural (consultas text) retornam 0 resultados. Por isso, o procedimento de instalação acima inclui embeddings locais.

Devo usar modelo local ou API externa para embeddings?

Modelo local: coloque EMBEDDING_PROVIDER=transformers em .env. Não precisa de chave de API e o conteúdo não sai do seu ambiente.
API externa: use uma chave de API de embeddings, como OpenAI.

Não é possível misturar os dois modos no mesmo banco de dados, pois as dimensões dos vetores são diferentes. Veja mais em Guia de embeddings locais.

Preciso de Redis?

Não. Se você adicionar Redis, ativa cache de busca e rastreamento de atividade de sessão.

O que muda se eu usar sem Redis?

Fragmentos recém-salvos podem levar até 5 minutos para aparecer na busca em linguagem natural, pois o servidor gera embeddings a cada 5 minutos. A busca por palavras-chave é imediata.

Quanta memória o modelo local usa?

Modelo	Memória adicional	Uso
Embeddings locais (`multilingual-e5-small`)	~150MB	Busca em linguagem natural
NLI para detecção de contradições (mDeBERTa)	~250–280MB	Determina se um novo fragmento contradiz um existente

Somando os dois modelos, o processo do servidor usa cerca de 0,4GB adicionais. O modelo de reordenação (reranker) está desligado por padrão. Se usar API externa de embeddings, a memória dos embeddings locais é liberada. Os valores por configuração estão em Requisitos de sistema.

Posso fazer o modelo NLI não usar memória?

Com NLI_SERVICE_URL, você pode delegar o NLI a um serviço separado, e o modelo não carrega no processo do servidor. MEMENTO_CONSOLIDATE_DETECT_CONTRADICT=false é a configuração que desliga apenas a detecção de contradições. O modelo ainda é carregado na inicialização do servidor.

Integração com agentes

Como fazer o agente usar as ferramentas de memória automaticamente?

Há duas maneiras, que podem ser combinadas.

Hooks ou plugins: chame context no início da sessão e configure um resumo automático no fim da sessão. Crie um plugin para Claude Code com anchormind init --target claude --write (Instalação de plugin, Configuração de hooks).
Instruções: depois de conectar o MCP, peça ao agente para ler o guia da ferramenta get_skill_guide e configurar o uso ativo das ferramentas de memória. O guia é fornecido pelo servidor.

E se a memória conflitar com as regras do CLAUDE.md?

A memória injetada tem prioridade menor que o prompt do sistema e arquivos de instrução. Fatos como "usamos PostgreSQL 15" funcionam bem, mas regras de comportamento como "escreva testes no formato Given-When-Then" podem ser ignoradas em caso de conflito. Em resumo, regras de comportamento devem ficar em CLAUDE.md, AGENTS.md, hooks ou skills.

O agente consegue saber quando não há resposta na memória?

Basta ver o campo _meta.evidence.status da resposta de recall. Se for no_evidence, não há memória encontrada; se for partial, parte das palavras-chave centrais da pergunta não está nos resultados (as palavras ausentes estão em uncovered_terms). O agente pode buscar novamente com as palavras ausentes ou responder "não está na memória". Para perguntas como "quantas vezes" ou "quando", a resposta inclui uma tabela com evidências em ordem cronológica e um resumo da linha do tempo por tópico.

Dados e segurança

Onde minhas memórias são armazenadas?

No PostgreSQL que você opera.

Minhas memórias saem do meu ambiente?

Só saem pelos caminhos que você configurar.

Se usar API externa de embeddings, o texto salvo é enviado para essa API. Com embeddings locais, nada sai.
Recursos de LLM, como avaliação de qualidade e reflect automático, exigem um provedor de LLM. O padrão é gemini-cli, e o provedor pode ser alterado.
Com chaves e egress_policy por workspace, você pode restringir provedores externos de LLM, mascarar o texto enviado e manter registros de transmissão (Checklist de segurança e operação).

Posso memorizar senhas ou tokens?

Não recomendamos. O sistema mascara padrões de informações sensíveis ao salvar, mas não cobre todos os formatos. Coloque valores secretos em variáveis de ambiente ou em um cofre de segredos, e registre apenas a localização na memória.

Qualidade da memória

Dá para impedir que informações erradas entrem na memória?

Não é possível impedir completamente. Até humanos alteram levemente as memórias ao relembrá-las. Por isso, em vez de tentar bloquear tudo desde o início, o design foca em reduzir a propagação de erros e permitir encontrar e corrigir problemas quando surgirem. Os métodos estão divididos nos quatro itens abaixo.

Como corrijo uma memória errada?

Como o armazenamento é por fragmento, basta corrigir o fragmento errado com amend ou excluí-lo com forget. Não há um resumo único que quebre por inteiro.

E se um conteúdo novo contradizer um existente?

O servidor detecta a contradição e expira o fragmento antigo (exceto âncoras). Ele não apaga simplesmente. O histórico é mantido com valid_to e superseded_by; os detalhes estão em Internals. Qual é o mais recente é determinado pelo horário em que a afirmação foi feita (mentionTime, ou o horário de salvamento se não houver).

Se precisar do valor antigo, forneça includeHistory: true em recall. O valor anterior aparece logo após o valor atual. Contradições ainda não resolvidas aparecem nos resultados com conflicts_with.

Você também lembra quando algo aconteceu?

O horário da afirmação e o horário do evento são tratados separadamente. Você pode fornecer mentionTime e eventTime em remember; se não fornecer eventTime, o sistema tenta extrair de expressões no texto, como "ontem", "2026-03-14" ou "semana passada". Se precisar da ordem dos eventos, use order: "chronological" em recall; para filtrar por período com base no horário do evento, use timeRange: { from, to, basis: "event" }.

Como são marcadas informações incertas?

Salve com assertionStatus=inferred. Depois, se confirmado, mude para verified; se estiver errado, mude para rejected.

Conteúdo salvo errado desde o início é detectado automaticamente?

Não. O servidor detecta apenas quando fragmentos contraditórios entram. Memórias importantes devem ser marcadas como âncoras e revisadas por humanos. Fragmentos com baixo nível de confiança, como conteúdo vindo de documentos externos, não entram em ANCHOR e CORE injetados no início da sessão, e textos que tentam sobrescrever instruções do agente vão para a fila de revisão.

E se a memória continuar crescendo?

Mesclagem de duplicatas, detecção de contradições, decaimento de importância e expiração por TTL rodam periodicamente. Fragmentos pouco usados descem de camada até desaparecerem. Fragmentos que devem ser mantidos podem ser marcados como âncoras, ficando fora do decaimento e da expiração. Marcar âncoras exige a permissão anchor.

Solução de problemas

Salvei, mas não aparece no recall

Se aparecer pending_review: true, está aguardando revisão (Problema 17 na solução de problemas).
Se o workspace for diferente, não aparece. Use o mesmo workspace para salvar e consultar.
Se apenas a consulta em linguagem natural estiver vazia, verifique se os embeddings estão ativados. Sem Redis, logo após salvar, pode levar até 5 minutos para aparecer na busca em linguagem natural. A busca por palavras-chave é imediata.

Outros sintomas estão organizados em 17 itens na Solução de problemas.

Não era memento-mcp?

É o mesmo projeto. Havia muitos projetos com nomes iguais ou parecidos, então o nome mudou para AnchorMind. Os comandos aceitam anchormind e memento-mcp, e algumas variáveis de ambiente ainda usam o prefixo MEMENTO_.

Unidades de memória

A memória é armazenada em fragmentos de uma ou duas frases. Cada fragmento é de um dos 7 tipos.

Tipo	Conteúdo
`fact`	Fatos como valores de configuração, caminhos, versões
`decision`	Escolhas técnicas e suas justificativas
`error`	Erros ocorridos, causas e soluções
`preference`	Estilo e modo de trabalho do usuário
`procedure`	Procedimentos repetitivos como deploy, build, testes
`relation`	Relações e dependências entre entidades
`episode`	Narrativas com contexto (1000 caracteres; as demais, 300)

As principais ferramentas são context (restaura memórias principais no início da sessão), recall (busca), remember (salvamento) e reflect (salva resumo no fim da sessão). A lista completa de ferramentas e regras de uso está em SKILL.md; a lista completa de recursos está em Detalhes de recursos.

Benchmark

Com base em 500 perguntas do LongMemEval-S (medido em 2026-10-10, líder deepseek-flash, avaliador GPT-4o em configuração oficial, MiniMax, Claude Sonnet 5.5):

Métrica	Pontuação	Condição
Proporção de turnos de evidência inteiros no top-10	91,2%	bge-m3, busca por trechos ativada
Recall de busca recall_any@5	98,4%	Por sessão
Taxa de acerto em QA (avaliador oficial GPT-4o)	84,0%	IC 95% 80,5–87,0%
Taxa de acerto em QA (avaliação MiniMax)	84,0%	IC 95% 80,5–87,0%
Taxa de acerto em QA (avaliação Claude)	78,0%	IC 95% 74,2–81,4%

A busca encontra a maior parte das evidências. Os erros restantes concentram-se em perguntas que exigem somar valores de várias sessões ou calcular datas (multi-session, temporal-reasoning). Condições de medição e análise: Benchmark Report.

Documentação

Tarefa	Documento
Instalação inicial e verificação	Requisitos de sistema, Quick Start, First Memory Flow, INSTALL.md
Conexão de clientes	Conexão por cliente, Claude Code, Plugin, Hooks
Solução de problemas	Troubleshooting
Atualizações	Notas de atualização
Operação	Checklist de segurança e operação, Backup e recuperação, Monitoramento, Console do administrador
Configurações	Configuration
Recursos completos	Detalhes de recursos, Features
Interfaces	API Reference, CLI, SKILL.md
Estrutura interna	Architecture, Internals
Histórico de alterações	CHANGELOG

Licença

Apache 2.0

Feito por Jinho Choi | Me pague um café