mindcore-memory-mcp

Servidor de Memória MCP Endurecido para Produção — Busca Híbrida + Resiliência para Agentes de IA

O único servidor de memória MCP com circuit breaker, monitoramento de SLO e busca híbrida BM25+FAISS. Agentes de IA esquecem tudo entre sessões. O MindCore Memory dá a eles memória persistente, pesquisável e de nível de produção — com 118/118 testes passando e CI/CD completo.

⭐ Se este projeto ajuda sua IA a lembrar, uma estrela significa o mundo para nós.

Início Rápido

# 1. Install
pip install mindcore-memory

# 2. Launch (stdio mode — works with any MCP client)
mindcore-memory

# 3. Your AI agent remembers across sessions

{
  "mcpServers": {
    "mindcore-memory": {
      "command": "python",
      "args": ["-m", "mindcore_memory.server"],
      "env": { "MINDCORE_MEMORY_PATH": "~/.mindcore/memory" }
    }
  }
}

pip install mindcore-memory[semantic]
# Enables FAISS embeddings for hybrid BM25+semantic search

Por que o MindCore — vs a Concorrência

O MindCore é o único servidor de memória MCP projetado para cargas de trabalho de produção desde o primeiro dia. O circuit breaker protege contra falhas do serviço de embeddings. A repetição com backoff exponencial lida com erros transitórios. O monitoramento de SLO alerta você antes que os usuários percebam. Exportação de métricas para sua stack de monitoramento. Todos os outros servidores assumem que nada falha — o MindCore não.

Exclusivo: Algoritmo de Equilíbrio de Fronteira 3D

O MindCore não é apenas um armazenamento de memória — é um mecanismo de fronteira cognitiva. Cada memória armazenada é automaticamente avaliada por um sistema de pontuação 4-dimensional baseado na 正反公式 (Fórmula Direta/Reversa):

BND_score = 0.28·TRJ(Trajectory) + 0.28·EVO(Evolution) + 0.28·COG(Cognition) + 0.16·BALANCE

• Ciclo direto: TRJ → BND → EVO → COG → BND (cada etapa traça uma fronteira, cada fronteira é crescimento)
• Cadeia reversa: Caos → Desconhecido → Risco → Dano → Morte (2+ gatilhos vinculados → penalidade automática de 50% na pontuação)
• Equilíbrio 3D: A variância entre TRJ/EVO/COG penaliza memórias desequilibradas (despejos de dados puros sem percepção)
• Sem chamadas de LLM: Avaliação puramente algorítmica usando padrões de palavras-chave, regex e variância estatística

from mindcore_memory import BNDManager
bnd = BNDManager()
result = bnd.evaluate("基于之前修复, 理解到根因, 改进后提升30%", importance=4)
# → TRJ:0.63  EVO:0.54  COG:0.61  BALANCE:0.98  BND:0.75  ACCEPTED

📖 Documentação completa do algoritmo

Nenhum outro servidor de memória MCP faz isso. O BND transforma o armazenamento de memória de um despejo de dados passivo em um filtro cognitivo ativo — rejeitando ruído, sinalizando cadeias de risco e garantindo que apenas conhecimento estruturado e orientado ao crescimento entre na cadeia de versões.

Recursos de Produção

Camada de Resiliência

• Circuit Breaker: Máquina de estados CLOSED → OPEN → HALF_OPEN. Protege operações FAISS/embeddings contra falhas em cascata.
• Retry: Backoff exponencial com jitter. Erros transitórios são repetidos automaticamente, erros permanentes falham rapidamente.
• Validação de Entrada: Saneamento em nível de servidor contra ataques de injeção.

Camada de Observabilidade

• Monitoramento de SLO: Metas de latência P95/P99 para todas as 6 operações. Violações registradas e exportadas.
• Prometheus /metrics: Coletor compatível com Prometheus sem dependências. Plug-and-play para qualquer stack de monitoramento.

Camada de Dados

• Criptografia: Criptografia Fernet opcional em repouso (mindcore-memory[encrypt]).
• Deduplicação: Mesclagem por correspondência exata — memórias idênticas atualizam importância/confiança em vez de armazenar duplicatas.
• Despejo Inteligente: Poda de memórias de baixa importância com sincronização atômica de disco. Sem memórias zumbis.

Ferramentas Principais

Memória (6 ferramentas)

Fronteira e Dedução (3 ferramentas) 🆕

Fórmula de busca: score = BM25(40%) + FAISS(50%) + importance(5%) + recency(5%)

Quando os embeddings FAISS não estão disponíveis, faz fallback automaticamente para busca por palavras-chave somente com BM25.

Arquitetura

┌───────────────────┐     MCP JSON-RPC      ┌────────────────────────────┐
│  AI Client         │ ◄──────────────────► │  MindCore Memory           │
│  (Claude/Cursor)   │     stdio / HTTP     │  MCP Server                │
└───────────────────┘                       └──────────┬─────────────────┘
                                                       │
                                            ┌──────────▼─────────────────┐
                                            │  Memory Engine             │
                                            │  ┌──────────────────────┐  │
                                            │  │ Hybrid Search        │  │
                                            │  │  BM25 (keyword) 40%  │  │
                                            │  │  FAISS (semantic)50%│  │
                                            │  │  importance        5%│  │
                                            │  │  recency           5%│  │
                                            │  └──────────────────────┘  │
                                            │  ┌──────────────────────┐  │
                                            │  │ Resilience           │  │
                                            │  │  Circuit Breaker     │  │
                                            │  │  Retry + Backoff     │  │
                                            │  │  SLO Tracking        │  │
                                            │  └──────────────────────┘  │
                                            └──────────┬─────────────────┘
                                                       │
                                            ┌──────────▼─────────────────┐
                                            │  Storage                   │
                                            │  JSONL (append)            │
                                            │  + FAISS index (IVF > 500) │
                                            │  + Fernet encrypt (opt)    │
                                            └────────────────────────────┘

• Embutido: Sem necessidade de PostgreSQL, Redis ou serviços externos. Um único binário, JSONL local + FAISS.
• Índice IVF: O índice de arquivo invertido FAISS é ativado com 500+ memórias para busca O(√N).
• MCP Nativo: Protocolo MCP completo sobre transportes stdio e HTTP.

Disponível Em

Comparação Completa

Consulte docs/comparison.md para uma comparação detalhada de 5 servidores cobrindo arquitetura, qualidade de busca, latência e guias de migração.

Contribuindo

Consulte CONTRIBUTING.md para o guia completo. Caminho rápido:

git clone https://github.com/woshilaohei/mindcore-memory-mcp.git
cd mindcore-memory-mcp
pip install -e ".[dev]"
pytest -v              # 118 tests
ruff check .           # linter
mypy mindcore_memory/  # type checker

Licença

Licença MIT — Copyright (c) 2025 Lao Hei