GroundMemory

Identidade e memória persistentes entre ferramentas de IA - nativo MCP, local-first, independente de framework, pronto para produção.

GitHub

Documentação

GroundMemory

Identidade e memória persistentes entre ferramentas de IA - nativo para MCP, local-first, agnóstico de framework, pronto para produção.

GitHub repo size GitHub language count GitHub top language

Início Rápido

Opção 1 - Docker (Recomendado)

git clone https://github.com/huss-mo/GroundMemory && cd GroundMemory
docker compose up -d
# -> listening on http://127.0.0.1:4242/mcp

Opção 2 - pip

pip install groundmemory && groundmemory-mcp
# -> listening on http://127.0.0.1:4242/mcp

Conecte seu cliente ao servidor MCP

{
  "mcpServers": {
    "GroundMemory": {
      "url": "http://127.0.0.1:4242/mcp"
    }
  }
}

Você pode habilitar o acesso à rede e substituir 127.0.0.1 pelo IP da LAN do seu servidor - veja DOCS.md - Acesso à Rede.
Você também pode usar o servidor MCP pelo transporte stdio - veja DOCS.md - Configuração do Cliente.

Seu agente agora tem memória estruturada e pesquisável que persiste em todas as sessões - fatos de longo prazo, um perfil de usuário, instruções do agente, um grafo de entidades e registros diários - tudo gerenciado automaticamente. Nenhuma alteração no código do seu agente é necessária.

Esta configuração funciona com qualquer cliente compatível com MCP, incluindo assistentes de codificação de IA (Cursor, Cline, Windsurf, Claude Code, Codex CLI), clientes desktop de IA (Claude Desktop, Open WebUI) e frameworks e plataformas de agentes (LangChain, CrewAI, AutoGen, Google ADK, LiteLLM, n8n).

Para opções de instalação, provedores de embedding, múltiplos workspaces e a API Python, veja DOCS.md.

O Que Se Torna Possível

Sem memória, cada sessão em cada ferramenta de IA começa do zero. Com o GroundMemory, os agentes podem manter continuidade ao longo do tempo, acumular conhecimento e se comportar como se realmente conhecessem a pessoa com quem estão trabalhando. Isso torna as conversas stateful, fluidas e naturais.

O diálogo abaixo é um exemplo de como isso funciona. A primeira sessão acontece no Open WebUI. A segunda sessão acontece no Cline (VS Code) - uma ferramenta completamente diferente, sem histórico compartilhado além do workspace do GroundMemory ao qual ambas estão conectadas.

Sessão 1 - Open WebUI (primeira sessão)

Usuário

Olá

Agente

Olá! Bem-vindo - este é o começo de algo bom. Tenho memória persistente, então tudo o que conversarmos eu levarei comigo em todas as sessões futuras. Não precisará se repetir mais adiante.

Algumas coisas rápidas para começarmos:

Como devo te chamar?

Algo que você sempre queira que eu tenha em mente - como você gosta de trabalhar, coisas a evitar, preferências?

Sem pressa. Só quero te conhecer.

Usuário

Sou a Alice, engenheira backend trabalhando em um produto SaaS. Estamos construindo uma API de gerenciamento de tarefas - Node.js, PostgreSQL, Redis para cache, e planejamos usar BullMQ para filas de jobs.

Agente

Entendido, Alice. Engenheira backend, API de gerenciamento de tarefas - Node.js, PostgreSQL, Redis, BullMQ para filas. Vou manter isso como base para tudo o que trabalharmos juntos.

Mais alguma coisa antes de começarmos? Ou está pronta para entrar no assunto?

O agente grava o que aprendeu na memória.

Sessão 2 - Cline no VS Code (ferramenta diferente, mesmo workspace do GroundMemory)

Usuário

Ei. Qual stack de tecnologia combinamos de usar para a API de gerenciamento de tarefas?

Agente

Você está construindo uma API de gerenciamento de tarefas com Node.js, PostgreSQL, Redis para cache e BullMQ para filas de jobs. Foi o que decidimos.

Sem introdução. Sem configuração. O agente já sabe.

Uma identidade única em todas as ferramentas de IA que você usa. Seu workspace de memória não está vinculado a um único assistente. Conecte Claude Desktop, Cursor, Cline e qualquer outra ferramenta compatível com MCP ao mesmo servidor GroundMemory e todas compartilharão a mesma memória - suas preferências, sua stack, seu trabalho em andamento. Você deixa de ser um estranho toda vez que abre uma ferramenta diferente. Há algo genuinamente diferente em ser conhecido em vez de apenas receber respostas - isso muda o relacionamento de transacional para colaborativo e remove o custo silencioso de restabelecer contexto que a maioria das pessoas só percebe quando ele desaparece.

Um assistente de codificação/pessoal que constrói um perfil ao longo do tempo. Após algumas conversas, ele conhece sua agenda, suas prioridades, como você gosta de se comunicar, sua stack de tecnologia, seus padrões preferidos e as decisões arquiteturais que você já tomou. Ele não precisa perguntar.

Um agente de pesquisa que constrói um grafo de conhecimento. À medida que lê artigos e fontes em muitas sessões, ele registra entidades, relacionamentos e descobertas.

Um agente voltado ao cliente com memória por usuário. Em configurações multiusuário, cada usuário tem seu próprio workspace - preferências, histórico, contexto em andamento - dando a cada interação uma sensação personalizada e stateful, sem qualquer infraestrutura personalizada.

Um agente autônomo de longa duração que sobrevive aos limites de contexto. Cada nova sessão chama memory_bootstrap para recarregar os fatos persistidos, então o agente retoma exatamente de onde a última sessão parou.

Backup e restauração automáticos quando a memória cresce. Quando o contexto de memória excede um limite de tokens configurável, o GroundMemory faz backup automático do workspace em um arquivo zip com timestamp antes de pedir ao agente para compactá-lo. Você também pode acionar um backup manualmente a qualquer momento com groundmemory --backup. Se algo der errado, um único comando restaura o estado anterior: groundmemory --restore -1.

O Que o GroundMemory Faz

A maioria dos agentes é stateless. Eles fazem as mesmas perguntas repetidamente, repetem os mesmos erros e perdem o rastro das preferências do usuário e do trabalho em andamento. Isso não é uma limitação do modelo - é infraestrutura ausente.

O GroundMemory fornece essa infraestrutura. Ele dá ao seu agente uma memória estruturada e pesquisável que persiste entre sessões, organizada em camadas distintas com responsabilidade clara:

Arquivo	Finalidade
`MEMORY.md`	Fatos de longo prazo curados - preferências, decisões, conhecimento persistente. Escrito pelo agente usando `memory_write(tier="long_term")`. Sobrevive para sempre.
`USER.md`	Perfil de usuário estável - nome, função, estilo de trabalho. Editado manualmente ou pelo agente. Injetado no início de cada sessão.
`AGENTS.md`	Instruções operacionais do agente - como este agente deve se comportar, quais ferramentas usar e quando. Inicializado com padrões sensatos.
`RELATIONS.md`	Grafo de relacionamento de entidades - triplas tipadas (`Alice → works_at → Acme Corp`). Escrito por `memory_relate`, espelho legível por humanos do grafo SQLite.
`daily/YYYY-MM-DD.md`	Registros diários somente anexação - progresso de tarefas, notas contínuas, contexto da sessão. Escrito por `memory_write(tier="daily")`.

No início da sessão, todos esses arquivos são montados em um bloco compacto de system prompt que seu agente recebe como contexto - chamado injeção de bootstrap. No momento da busca, todas as camadas são consultadas juntas ou individualmente.

Capacidades adicionais:

Busca híbrida - a pontuação por palavras-chave BM25 e a similaridade de cosseno vetorial são combinadas e reordenadas em uma única consulta, para que a recuperação seja precisa mesmo quando a formulação difere do que foi armazenado.
Modo zero-configuração - com provider: none, o GroundMemory roda inteiramente em SQLite com FTS5. Sem chave de API, sem GPU, sem dependências extras.
Provedores de embedding plugáveis - alterne entre um modelo local sentence-transformers, qualquer endpoint compatível com OpenAI (OpenAI, Ollama, LM Studio, LiteLLM) ou somente BM25 sem tocar no código do seu agente.
Isolamento de workspace - cada projeto, usuário ou agente tem seu próprio workspace baseado em diretório, com memória, relações e registros diários independentes.
Grafo de relações com deduplicação semântica - o grafo suprime automaticamente triplas quase duplicadas usando limiar de similaridade de cosseno configurável.

Como o GroundMemory se Compara

A comparação reflete recursos documentados publicamente em MAR-2026. Envie um PR se algo estiver impreciso.

Recurso	GroundMemory	Mem0	Letta	memsearch	Zep
Zero-configuração (sem chave de API, sem GPU)	✅	-	-	-	-
Local-first / offline	✅	-	-	Parcial¹	-
Memória Markdown legível por humanos	✅	-	-	✅	-
Camadas de memória estruturadas	✅	✅²	✅³	-	-
Busca híbrida BM25 + vetorial	✅	-	-	✅	✅
Grafo de relações de entidades	✅	✅	-	-	✅
Servidor nativo MCP	✅	Parcial⁴	Parcial⁵	-	-
Grafo de conhecimento temporal	-⁶	-	-	-	✅
Framework completo de agentes	-	-	✅	-	-
Serviço gerenciado em nuvem	-	✅	✅	-	✅

¹ memsearch suporta embeddings ONNX locais + Milvus Lite, mas requer download inicial do modelo
² O Mem0 organiza a memória em camadas de Conversa, Sessão, Usuário e Organizacional
³ O Letta usa blocos de Core Memory (em contexto) + Archival Memory (banco vetorial) + Conversation Search
⁴ O Mem0 oferece uma integração MCP, mas a interface principal é o SDK Python/Node
⁵ Os agentes do Letta podem consumir servidores MCP externos como ferramentas; o próprio Letta não é um servidor MCP
⁶ O GroundMemory registra timestamps em todas as relações, mas não suporta consultas por intervalo de datas.

Ferramentas

No modo normal, o GroundMemory expõe quatro ferramentas: memory_bootstrap, memory_read, memory_write e memory_relate. Uma ferramenta opcional memory_list pode ser habilitada via configuração. No modo dispatcher, todas as ações são roteadas por uma única chamada memory_tool - útil para clientes que têm melhor desempenho com menos ferramentas em escopo.

Ao usar o servidor MCP, instrua seu agente a chamar memory_bootstrap no início de cada sessão antes de fazer qualquer outra coisa, se você descobrir que ele não faz isso por padrão. Isso carrega o contexto completo da memória (MEMORY.md, USER.md, AGENTS.md, RELATIONS.md, registros diários) na conversa. Clientes que suportam a primitiva MCP Prompts (Cline, Claude Desktop) podem, em vez disso, usar o prompt memory_bootstrap_prompt no painel de Prompts.

Ao usar a API Python, chame session.bootstrap() e passe o resultado como seu system prompt - nenhuma chamada de ferramenta é necessária.

Para a referência completa das ferramentas, incluindo parâmetros, camadas e filtros de origem, veja DOCS.md - Referência de Ferramentas.

Arquitetura

┌─────────────────────────────────────────────────────┐
│                    AI Agent / LLM                   │
│         (OpenAI, Anthropic, or any framework)       │
└────────────────────┬────────────────────────────────┘
                     │  tool calls + bootstrap prompt
                     ▼
┌─────────────────────────────────────────────────────┐
│                  MemorySession                      │
│   workspace  ·  index  ·  provider  ·  config       │
└───────┬──────────────┬──────────────────────────────┘
        │              │
        ▼              ▼
┌───────────┐  ┌───────────────────────────────────┐
│ Workspace │  │          MemoryIndex              │
│           │  │  SQLite + FTS5 (BM25 keyword)     │
│ MEMORY.md │  │  + optional vector store          │
│ USER.md   │  │  hybrid re-ranking + MMR          │
│ AGENTS.md │  └──────────────┬────────────────────┘
│ RELATIONS │                 │
│ daily/    │                 ▼
└───────────┘  ┌───────────────────────────────────┐
               │       EmbeddingProvider           │
               │  NullProvider  (BM25-only)        │
               │  SentenceTransformer  (local)     │
               │  OpenAICompatible  (HTTP API)     │
               └───────────────────────────────────┘

Para um detalhamento de cada camada, o fluxo completo de dados e a stack de tecnologia, veja DOCS.md - Arquitetura.

Contribuindo

Filosofia

O GroundMemory é projetado em torno de três valores:

Simplicidade acima de recursos. Cada adição deve justificar sua complexidade. Um modo somente BM25 sem dependências deve sempre funcionar.
Offline-first. A configuração padrão não deve exigir chave de API, conexão de rede ou GPU.
Orientado a testes. Novo comportamento é entregue com testes. A suíte completa deve passar antes que qualquer PR seja mesclado.

Configuração de Desenvolvimento

git clone https://github.com/huss-mo/GroundMemory.git
cd GroundMemory

# Install with all dev dependencies
pip install -e ".[dev,local]"

# Or with uv
uv sync --extra dev --extra local

Executando a Suíte de Testes

# Core tests - no extra deps or config required (fast, always passes)
pytest

# Local model tests - sentence-transformers + cross-encoder
# Requires: pip install groundmemory[local]
pytest -m local

# API embedding tests - OpenAI-compatible HTTP endpoint
# Requires: endpoint configured via .env (see below)
pytest -m api_embeddings

# All marked tests together
pytest -m "local or api_embeddings"

# With coverage
pytest --cov=groundmemory --cov-report=term-missing

Testes local baixam modelos reais sentence-transformers e cross-encoder na primeira execução. Os nomes dos modelos são lidos da configuração (embedding.local_model, search.rerank_model). Eles são pulados automaticamente quando sentence-transformers não está instalado.

Testes api_embeddings exigem um endpoint de embedding compatível com OpenAI configurado. Todas as configurações são lidas de .env (raiz do projeto ou ~/.groundmemory/). Os testes são pulados automaticamente quando embedding.provider não é openai ou o endpoint está inacessível.

.env mínimo para api_embeddings:

GROUNDMEMORY_EMBEDDING__PROVIDER=openai
GROUNDMEMORY_EMBEDDING__BASE_URL=http://localhost:11434/v1
GROUNDMEMORY_EMBEDDING__API_KEY=ollama
GROUNDMEMORY_EMBEDDING__MODEL=nomic-embed-text

Qualquer endpoint compatível com OpenAI funciona: OpenAI, Ollama, LM Studio, LiteLLM, etc. Executar pytest sem a flag -m roda tudo - os testes marcados são pulados graciosamente quando seus requisitos não são atendidos.

Enviando um PR

Faça um fork do repositório e crie uma branch: git checkout -b feature/your-feature-name
Faça suas alterações com testes correspondentes.
Execute os testes - todos os testes unitários devem passar.
Abra um pull request com uma descrição clara do que muda e por quê.

Licença

Este projeto é licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.