Memlord

Servidor de memória MCP auto-hospedado para uso pessoal e equipes

Início Rápido • Como Funciona • Ferramentas MCP • Configuração • Requisitos • Licença

---

✨ Funcionalidades

• 🔍 Busca híbrida — BM25 (texto completo) + KNN vetorial (pgvector) fundidos via Reciprocal Rank Fusion
• 📂 Multiusuário — cada usuário vê apenas suas próprias memórias; espaços de trabalho para conhecimento compartilhado da equipe
• 🛠️ 10 ferramentas MCP — armazenar, recuperar, recordar, listar, buscar por tag, obter, atualizar, excluir, mover, listar espaços de trabalho
• 🌐 Interface Web — navegue, busque, edite e exclua memórias no navegador; exportar/importar JSON
• 🔒 OAuth 2.1 — servidor de autorização completo em processo, sempre ativo
• 🐘 PostgreSQL — pgvector para embeddings, tsvector para busca de texto completo
• 📊 Divulgação progressiva — a busca retorna trechos compactos por padrão; chame get_memory(name) apenas para o que você precisa, reduzindo o uso de tokens
• 🔁 Deduplicação — detecta automaticamente memórias quase idênticas antes de salvar, prevenindo acúmulo de ruído

---

🆚 Como o Memlord se compara

	Memlord	OpenMemory	mcp-memory-service	basic-memory
Busca	BM25 + vetorial + RRF	Apenas vetorial (Qdrant)	BM25 + vetorial + RRF	BM25 + vetorial
Embeddings	ONNX local, configuração zero	OpenAI padrão; Ollama opcional	ONNX local, configuração zero	FastEmbed local
Armazenamento	PostgreSQL + pgvector	PostgreSQL + Qdrant	SQLite-vec / Cloudflare Vectorize	SQLite + arquivos Markdown
Multiusuário	✅	❌ usuário único na prática	⚠️ escopo por agent-ID, sem isolamento	❌
Espaços de trabalho	✅ compartilhado + pessoal, links de convite	⚠️ Namespace "Apps"	⚠️ tags + conversation_id	✅ flag por projeto
Autenticação	✅ OAuth 2.1	❌ nenhuma (auto-hospedado)	✅ OAuth 2.0 + PKCE	❌
Interface Web	✅ navegar, editar, exportar	✅ painel Next.js	✅ interface rica, visualização de grafo, pontuações de qualidade	❌ local; apenas nuvem
Ferramentas MCP	10	5	15+	~20
Auto-hospedado	✅ processo único	✅ Docker (3 contêineres)	✅	✅
Entrada de memória	Manual (armazenamento explícito)	Extração automática por LLM	Manual	Manual (notas Markdown)
Tipos de memória	fato / preferência / instrução / feedback	fatos extraídos automaticamente	—	observações + links wiki
Busca temporal	✅ datas em linguagem natural	⚠️ apenas REST, não nas ferramentas MCP	—	✅ recent_activity
Eficiência de tokens	✅ divulgação progressiva	❌	—	✅ build_context traversal
Importar / Exportar	✅ JSON	✅ ZIP (JSON + JSONL)	—	✅ Markdown (legível por humanos)
Licença	AGPL-3.0 / Comercial	Apache 2.0	Apache 2.0	AGPL-3.0

Onde os concorrentes têm uma vantagem real:

• OpenMemory — extrai memórias automaticamente de texto de conversa bruto; sem necessidade de decidir o que armazenar manualmente; boa importação/exportação
• mcp-memory-service — interface web mais rica (visualização de grafo, pontuação de qualidade, 8 abas); licença mais permissiva (Apache 2.0); múltiplas opções de transporte (stdio, SSE, HTTP)
• basic-memory — memórias são arquivos Markdown legíveis por humanos que você pode editar, versionar e ler sem nenhum servidor; links de entidade estilo wiki formam um grafo de conhecimento local; ~20 ferramentas MCP

Quando escolher o Memlord:

• Você quer embeddings locais com configuração zero — o modelo ONNX vem com o servidor, sem necessidade de Ollama ou API externa
• Você executa um servidor de equipe multiusuário com autenticação OAuth 2.1 adequada e espaços de trabalho baseados em convite
• Você quer um banco de dados de nível de produção (PostgreSQL) que escala além do SQLite de uma única máquina
• Você gerencia memórias explicitamente — armazena exatamente o que importa, tipado e etiquetado, não tudo o que o LLM decide extrair
• Você quer uma Interface Web auto-hospedada com CRUD completo e exportação JSON, sem assinatura na nuvem

---

🚀 Início Rápido

🐳 Docker

cp .env.example .env
docker compose up

Servidor HTTP (multiusuário, Interface Web, OAuth)

# Install dependencies
uv sync --dev

# Download ONNX model (~23 MB)
uv run python scripts/download_model.py

# Run migrations
alembic upgrade head

# Start the server
memlord

Abra http://localhost:8000 para a Interface Web. O endpoint MCP está em /mcp.

---

🔍 Como Funciona

Cada solicitação de busca executa BM25 e KNN vetorial em paralelo, depois mescla os resultados via Reciprocal Rank Fusion:

flowchart TD
    Q([query]) --> BM25["BM25\nsearch_vector @@ websearch_to_tsquery"]
    Q --> EMB["ONNX embed\nall-MiniLM-L6-v2 · 384d · local"]
    EMB --> KNN["KNN\nembedding <=> query_vector\ncosine distance"]
    BM25 --> RRF["RRF fusion\nscore = 1/(k+rank_bm25) + 1/(k+rank_vec)\nk=60"]
    KNN --> RRF
    RRF --> R([top-N results])

---

⚙️ Configuração

Todas as configurações usam o prefixo MEMLORD_. Veja .env.example para a lista completa.

Variável	Padrão	Descrição
MEMLORD_DB_URL	postgresql+asyncpg://postgres:postgres@localhost/memlord	URL de conexão PostgreSQL
MEMLORD_PORT	8000	Porta do servidor
MEMLORD_BASE_URL	http://localhost:8000	URL pública para OAuth (modo HTTP)
MEMLORD_OAUTH_JWT_SECRET	memlord-dev-secret-please-change	Segredo de assinatura JWT (modo HTTP)

Defina MEMLORD_BASE_URL para sua URL pública e altere MEMLORD_OAUTH_JWT_SECRET antes de implantar.

---

🛠️ Ferramentas MCP

Ferramenta	Descrição
store_memory	Salvar uma memória (idempotente por conteúdo); gera erro em quase duplicatas; expires_at opcional
retrieve_memory	Busca híbrida semântica + texto completo; retorna trechos por padrão
recall_memory	Buscar por expressão de tempo em linguagem natural; retorna trechos por padrão
list_memories	Lista paginada com filtros de tipo/tag
search_by_tag	Busca de tags E/OU
get_memory	Obter uma única memória por nome com conteúdo completo
update_memory	Atualizar conteúdo, tipo, tags, metadados ou expiração por nome (e opcionalmente renomear)
delete_memory	Excluir por nome
move_memory	Mover uma memória para um espaço de trabalho diferente
list_workspaces	Listar espaços de trabalho dos quais você é membro (incluindo pessoal)

O gerenciamento de espaços de trabalho (criar, convidar, entrar, sair) é feito via Interface Web.

---

💻 Requisitos do Sistema

• Python 3.12
• PostgreSQL ≥ 15 com extensão pgvector
• uv — Gerenciador de pacotes Python

---

👨‍💻 Desenvolvimento

pyright src/           # type check
ruff format .          # format
pytest                 # run tests
alembic-autogen-check  # verify migrations are up to date

---

📄 Licença

Memlord é licenciado duplamente:

• AGPL-3.0 — gratuito para uso em código aberto. Se você executar uma versão modificada como um serviço de rede, você deve publicar seu código fonte.
• Licença Comercial — para implantações proprietárias ou de código fechado. Contate sergey@memlord.com ou dmitry@memlord.com para adquirir.