mindcore-memory-mcp

Servidor de Memoria MCP Endurecido para Producción — Búsqueda Híbrida + Resiliencia para Agentes de IA

El único servidor de memoria MCP con interruptor de circuito, seguimiento de SLO y búsqueda híbrida BM25+FAISS. Los agentes de IA olvidan todo entre sesiones. MindCore Memory les brinda memoria persistente, buscable y de grado de producción — con 118/118 pruebas aprobadas y CI/CD completo.

⭐ Si este proyecto ayuda a tu IA a recordar, una estrella significa mucho para nosotros.

Inicio 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 Qué MindCore — vs la Competencia

MindCore es el único servidor de memoria MCP diseñado para cargas de trabajo de producción desde el primer día. El interruptor de circuito protege contra fallas del servicio de incrustación. Los reintentos con retroceso exponencial manejan errores transitorios. El seguimiento de SLO te alerta antes de que los usuarios lo noten. Métricas exportadas para tu stack de monitoreo. Todos los demás servidores asumen que nada falla — MindCore no.

Único: Algoritmo de Equilibrio de Límites 3D

MindCore no es solo un almacén de memoria — es un motor de límites cognitivos. Cada memoria almacenada se evalúa automáticamente mediante un sistema de puntuación de 4 dimensiones basado en la 正反公式 (Fórmula Adelante/Reversa):

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

• Ciclo hacia adelante: TRJ → BND → EVO → COG → BND (cada paso dibuja un límite, cada límite es crecimiento)
• Cadena inversa: Caos → Desconocido → Riesgo → Daño → Muerte (2+ disparadores vinculados → penalización automática del 50% en la puntuación)
• Equilibrio 3D: La varianza entre TRJ/EVO/COG penaliza memorias desequilibradas (volcados de datos puros sin conocimiento)
• Sin llamadas LLM: Evaluación puramente algorítmica usando patrones de palabras clave, expresiones regulares y varianza estadí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

📖 Documentación completa del algoritmo

Ningún otro servidor de memoria MCP hace esto. BND transforma el almacenamiento de memoria de un volcado de datos pasivo a un filtro cognitivo activo — rechazando ruido, marcando cadenas de riesgo y asegurando que solo el conocimiento estructurado y orientado al crecimiento entre en la cadena de versiones.

Características de Producción

Capa de Resiliencia

• Interruptor de Circuito: Máquina de estados CERRADO → ABIERTO → MEDIO_ABIERTO. Protege las operaciones FAISS/incrustación de fallas en cascada.
• Reintentos: Retroceso exponencial con fluctuación. Los errores transitorios se reintentan automáticamente, los errores permanentes fallan rápidamente.
• Validación de Entrada: Saneamiento a nivel de servidor contra ataques de inyección.

Capa de Observabilidad

• Seguimiento de SLO: Objetivos de latencia P95/P99 para las 6 operaciones. Las violaciones se registran y exportan.
• Prometheus /metrics: Colector compatible con Prometheus sin dependencias. Listo para cualquier stack de monitoreo.

Capa de Datos

• Cifrado: Cifrado opcional Fernet en reposo (mindcore-memory[encrypt]).
• Deduplicación: Fusión por coincidencia exacta — las memorias idénticas actualizan importancia/confianza en lugar de almacenar duplicados.
• Expulsión Inteligente: Poda de memorias de baja importancia con sincronización atómica de disco. Sin memorias zombis.

Herramientas Principales

Memoria (6 herramientas)

Límites y Deducción (3 herramientas) 🆕

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

Cuando las incrustaciones FAISS no están disponibles, automáticamente se recurre a búsqueda de palabras clave solo con BM25.

Arquitectura

┌───────────────────┐     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)    │
                                            └────────────────────────────┘

• Integrado: Sin necesidad de PostgreSQL, Redis o servicios externos. Un solo binario, JSONL local + FAISS.
• Índice IVF: El índice de archivo invertido FAISS se activa con 500+ memorias para búsqueda O(√N).
• MCP Nativo: Protocolo MCP completo sobre transportes stdio y HTTP.

Disponible En

Comparación Completa

Consulta docs/comparison.md para una comparación detallada de 5 servidores que cubre arquitectura, calidad de búsqueda, latencia y guías de migración.

Contribuciones

Consulta CONTRIBUTING.md para la guía completa. Ruta rápida:

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

Licencia

Licencia MIT — Copyright (c) 2025 Lao Hei