KuzuMem-MCP

Una herramienta MCP de banco de memoria distribuida que almacena recuerdos en una base de datos gráfica KùzuDB, con capacidades de filtrado por repositorio y rama.

GitHub
24
Prueba este MCPPatrocinado

Documentación

KuzuMem-MCP

Una implementación en TypeScript de un banco de memoria distribuido como herramienta MCP (Model Context Protocol), que almacena memorias en una base de datos de grafos KùzuDB con capacidades de filtrado por repositorio y rama. El aislamiento de ramas se logra mediante el uso de un identificador único de grafo para las entidades, lo que permite un banco de memoria centralizado mientras se ofrecen vistas específicas por repositorio y por rama. Totalmente compatible con la especificación MCP para una integración perfecta con IDEs y agentes de IA.

Características principales

  • 🧠 Optimización de memoria impulsada por IA - Modelos de razonamiento avanzado (OpenAI o3/o4-mini, Claude 4) con muestreo MCP para una gestión inteligente de la memoria
  • 🛡️ Seguridad lista para producción - Sistema de instantáneas automáticas con capacidades de reversión garantizadas
  • 🎯 Inteligencia consciente del contexto - El muestreo MCP analiza el estado real de la memoria para estrategias de optimización adaptativas
  • 🔧 Arquitectura de herramientas unificada - 12 herramientas consolidadas que cubren todas las operaciones del banco de memoria
  • 🧵 Patrón singleton seguro para subprocesos - Garantiza que cada recurso se instancie solo una vez, con la seguridad adecuada para subprocesos
  • 📊 Estructura de grafo distribuida - Sigue la especificación avanzada del banco de memoria utilizando un grafo KùzuDB
  • 🌿 Conocimiento de repositorio y rama - Todas las operaciones se contextualizan por nombre de repositorio y rama
  • ⚡ Operaciones asíncronas - Utiliza async/await para un mejor rendimiento
  • 🔌 Múltiples interfaces de acceso - Acceso mediante CLI y múltiples implementaciones de servidor MCP
  • 💾 Backend KùzuDB - Utiliza KùzuDB para el almacenamiento y consulta de memoria basada en grafos
  • ✅ Totalmente compatible con MCP - Todas las herramientas siguen el Model Context Protocol para la integración con clientes
  • 📡 Transmisión progresiva de resultados - Admite transmisión para operaciones de grafo de larga duración
  • 🏠 Aislamiento de la raíz del proyecto del cliente - Cada proyecto de cliente obtiene su propia instancia de base de datos aislada
  • 🧠 Análisis de alto razonamiento - Aprovecha el razonamiento HIGH de OpenAI y el pensamiento extendido de Anthropic para la optimización de la memoria
  • 🗑️ Operaciones masivas seguras - Eliminación masiva avanzada con validación de dependencias y capacidades de ejecución en seco

Herramientas unificadas

El sistema transmite actualmente 12 herramientas unificadas que consolidan todas las operaciones del banco de memoria:

  1. memory-bank - Inicializar y gestionar los metadatos del banco de memoria
  2. entity - Crear, actualizar, eliminar y recuperar todos los tipos de entidades (componentes, decisiones, reglas, archivos, etiquetas)
  3. introspect - Explorar el esquema del grafo y los metadatos
  4. context - Gestionar el contexto de la sesión de trabajo
  5. query - Búsqueda unificada en contextos, entidades, relaciones, dependencias, gobernanza, historial y etiquetas
  6. associate - Crear relaciones entre entidades
  7. analyze - Ejecutar algoritmos de grafo (PageRank, K-Core, Louvain, ruta más corta)
  8. detect - Detectar patrones (componentes fuertemente/débilmente conectados)
  9. bulk-import - Importación masiva eficiente de entidades
  10. search - Búsqueda de texto completo en todos los tipos de entidades con integración FTS de KuzuDB
  11. delete - Eliminación segura de entidades con validación de dependencias y operaciones masivas
  12. memory-optimizer - 🧠 Optimización central de memoria impulsada por IA con muestreo MCP, instantáneas y reversión

Para obtener documentación detallada de las herramientas, consulte Documentación de herramientas unificadas.

Documentación

Instalación

# Clone the repository
git clone git@github.com:Jakedismo/KuzuMem-MCP.git
cd kuzumem-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuración

Cree un archivo .env en el directorio raíz (cópielo de .env.example):

# Database Configuration
DB_FILENAME="memory-bank.kuzu"

# Server Configuration
HTTP_STREAM_PORT=3001
HOST=localhost

# Debug Logging (0=Error, 1=Warn, 2=Info, 3=Debug, 4=Trace)
DEBUG=1

# Core Memory Optimization Agent - AI Provider Configuration
# Required for memory optimization features
OPENAI_API_KEY=sk-your-openai-api-key-here
ANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key-here

# Optional: Custom API endpoints
# OPENAI_BASE_URL=https://api.openai.com/v1
# ANTHROPIC_BASE_URL=https://api.anthropic.com

Configuración de la optimización central de memoria

El agente de optimización central de memoria requiere claves de API para modelos de alto razonamiento:

Modelos compatibles:

  • OpenAI: o3, o4-mini (con razonamiento HIGH, 32 768 tokens)
  • Anthropic: claude-4 (con pensamiento extendido, 2 048 tokens)

Para obtener instrucciones de configuración detalladas, consulte Guía de configuración de la optimización central de memoria.

Añada a la configuración MCP de su IDE:

{
  "mcpServers": {
    "KuzuMem-MCP": {
      "command": "npx",
      "args": ["-y", "ts-node", "/absolute/path/to/kuzumem-mcp/src/mcp-stdio-server.ts"],
      "env": {
        "PORT": "3000",
        "HOST": "localhost",
        "DB_FILENAME": "memory-bank.kuzu",
        "HTTP_STREAM_PORT": "3001"
      }
    }
  }
}

Inicio rápido

1. Inicializar el banco de memoria

{
  "tool": "memory-bank",
  "operation": "init",
  "clientProjectRoot": "/path/to/your/project",
  "repository": "my-app",
  "branch": "main"
}

2. Crear entidades

{
  "tool": "entity",
  "operation": "create",
  "entityType": "component",
  "repository": "my-app",
  "branch": "main",
  "data": {
    "id": "comp-auth-service",
    "name": "Authentication Service",
    "kind": "service",
    "depends_on": ["comp-user-service"]
  }
}

3. Consultar dependencias

{
  "tool": "query",
  "type": "dependencies",
  "repository": "my-app",
  "branch": "main",
  "componentId": "comp-auth-service",
  "direction": "dependencies"
}

4. Ejecutar análisis

{
  "tool": "analyze",
  "type": "pagerank",
  "repository": "my-app",
  "branch": "main",
  "projectedGraphName": "component-importance",
  "nodeTableNames": ["Component"],
  "relationshipTableNames": ["DEPENDS_ON"]
}

🧠 Agente de optimización central de memoria

El agente de optimización central de memoria proporciona optimización del grafo de memoria impulsada por IA con capacidades de razonamiento avanzado y funciones de seguridad listas para producción:

Características

  • 🧠 Análisis de alto razonamiento: Utiliza OpenAI o3/o4-mini (razonamiento HIGH) o Claude (pensamiento extendido) para un análisis inteligente de la memoria
  • 🎯 Muestreo MCP: Prompts conscientes del contexto que se adaptan al estado real de la memoria y a las características del proyecto
  • 🛡️ Instantáneas automáticas: Seguridad lista para producción con copia de seguridad automática antes de la optimización
  • 🔄 Reversión garantizada: Restauración completa del estado con seguridad transaccional
  • ⚖️ Optimización segura: Estrategias conservadoras, equilibradas y agresivas con validación de seguridad
  • 🔍 Detección de entidades obsoletas: Identifica entidades desactualizadas según la antigüedad y los patrones de uso
  • 🔗 Eliminación de redundancias: Encuentra y consolida entidades duplicadas o redundantes
  • 📊 Optimización de dependencias: Optimiza las cadenas de relaciones preservando la integridad
  • 👀 Modo de ejecución en seco: Previsualiza las optimizaciones sin realizar cambios
  • 📈 Inteligencia de proyecto: Análisis automático de madurez, actividad y complejidad del proyecto

Inicio rápido

1. Analizar el grafo de memoria (con muestreo MCP)

{
  "tool": "memory-optimizer",
  "operation": "analyze",
  "repository": "my-app",
  "branch": "main",
  "llmProvider": "openai",
  "model": "o4-mini",
  "strategy": "conservative",
  "enableMCPSampling": true,
  "samplingStrategy": "representative"
}

2. Previsualizar la optimización (ejecución en seco)

{
  "tool": "memory-optimizer",
  "operation": "optimize",
  "repository": "my-app",
  "branch": "main",
  "dryRun": true,
  "strategy": "conservative"
}

3. Ejecutar la optimización (con instantánea automática)

{
  "tool": "memory-optimizer",
  "operation": "optimize",
  "repository": "my-app",
  "branch": "main",
  "dryRun": false,
  "confirm": true,
  "strategy": "conservative"
}

4. Listar instantáneas disponibles

{
  "tool": "memory-optimizer",
  "operation": "list-snapshots",
  "repository": "my-app",
  "branch": "main"
}

5. Revertir al estado anterior

{
  "tool": "memory-optimizer",
  "operation": "rollback",
  "repository": "my-app",
  "branch": "main",
  "snapshotId": "snapshot-1703123456789-xyz789"
}

Estrategias de optimización

  • Conservadora: Máximo 5 eliminaciones, umbral de obsolescencia de 6 meses (recomendada para producción)
  • Equilibrada: Máximo 20 eliminaciones, umbral de obsolescencia de 3 meses (recomendada para desarrollo)
  • Agresiva: Máximo 50 eliminaciones, umbral de obsolescencia de 1 mes (usar con precaución)

Estrategias de muestreo MCP

  • Representativa: Muestra equilibrada en todos los tipos de entidades (predeterminada)
  • Problemática: Se centra en entidades obsoletas, desconectadas o en desuso
  • Reciente: Muestrea entidades recién creadas (< 30 días) para el análisis de seguridad
  • Diversa: Garantiza la representación de todos los tipos de entidades para sistemas complejos

Funciones de seguridad

  • 🛡️ Instantáneas automáticas: Se crean antes de cada optimización (a menos que sea en seco)
  • 🔄 Reversión transaccional: Restauración completa del estado con consistencia de la base de datos
  • ✅ Sistema de validación: Comprobaciones de integridad de las instantáneas antes de las operaciones de reversión
  • 📊 Seguridad consciente del contexto: Medidas de seguridad basadas en el nivel de actividad y la complejidad

Para obtener instrucciones completas de configuración y uso, consulte:

Pruebas

# Run unit tests
npm test

# Run E2E tests (requires API keys)
npm run test:e2e

# Run specific E2E tests
npm run test:e2e:stdio
npm run test:e2e:httpstream

# Run memory optimizer E2E tests
npm run test:e2e -- --testNamePattern="Memory Optimizer E2E Tests"

# Run all tests
npm run test:all

Requisitos de las pruebas E2E

Para las pruebas E2E del optimizador de memoria, establezca las variables de entorno:

export OPENAI_API_KEY="your-actual-openai-api-key"
export ANTHROPIC_API_KEY="your-actual-anthropic-api-key"

Nota: Toda la funcionalidad principal está operativa con una cobertura completa de pruebas E2E para los protocolos stdio y HTTP stream.

Arquitectura

KuzuMem-MCP sigue los patrones oficiales del SDK TypeScript de MCP con una arquitectura limpia:

┌─────────────────────────────────────────────────────────────┐
│                    MCP Protocol Layer                       │
├─────────────────────────────────────────────────────────────┤
│     HTTP Stream Server     │      Stdio Server             │
│   (StreamableHTTPTransport) │   (StdioTransport)            │
├─────────────────────────────────────────────────────────────┤
│                    Tool Handlers                            │
├─────────────────────────────────────────────────────────────┤
│                   Memory Service                            │
├─────────────────────────────────────────────────────────────┤
│                   Repository Layer                          │
├─────────────────────────────────────────────────────────────┤
│                    KuzuDB Client                            │
└─────────────────────────────────────────────────────────────┘

Componentes clave

  • Servidores MCP: Implementaciones oficiales del SDK que utilizan McpServer con transportes HTTP Stream y Stdio
  • Manejadores de herramientas: Lógica de negocio para cada herramienta MCP con manejo simplificado del contexto
  • Servicio de memoria: Orquestación central y gestión de repositorios
  • Capa de repositorio: Singletons seguros para subprocesos para cada tipo de entidad
  • Capa de base de datos: Base de datos de grafos integrada KùzuDB

Cumplimiento del SDK oficial

✅ Gestión de sesiones: Utiliza el manejo de sesiones integrado del SDK ✅ Registro de herramientas: Utiliza el método oficial tool() con validación Zod ✅ Manejo de transportes: Aprovecha las implementaciones de transporte del SDK ✅ Manejo de errores: Sigue los patrones de error y las mejores prácticas del SDK

Para obtener información detallada sobre la arquitectura, consulte Documentación ampliada.

Bucle de desarrollo del agente (con reglas aplicadas)

Cuando las "Reglas de espacio de trabajo siempre aplicadas" a nivel de repositorio (project_config_updated.md) y las reglas de flujo de trabajo a corto plazo (workflow_state_updated.mdc) están activas, todo IDE o agente de IA que se comunique con KuzuMem-MCP debe seguir el bucle de estados finitos de cinco fases que se describe a continuación. Cada transición es observable mediante la herramienta unificada context y está respaldada por llamadas MCP obligatorias que mantienen la base de datos de grafos sincronizada y las reglas de gobernanza aplicadas.

  1. ANALIZAR – Obtener el contexto más reciente, inspeccionar el vecindario de 1 salto y, opcionalmente, ejecutar un análisis PageRank. Producir una declaración del problema de alto nivel.
  2. PLANIFICAR – Redactar un plan de implementación numerado y persistirlo como entidad Decision (status: proposed, etiqueta architecture). Esperar la aprobación explícita del usuario.
  3. CONSTRUIR – Ejecutar los pasos del plan, aplicar las ediciones de código y reflejar inmediatamente los cambios mediante llamadas a las herramientas entity, associate y context, respetando las reglas de dependencias y etiquetado.
  4. VALIDAR – Ejecutar el conjunto completo de pruebas y linters. Si es correcto, actualizar Decision a implemented; si falla, registrar el contexto y volver a CONSTRUIR.
  5. REVERTIR – Se activa automáticamente ante errores irrecuperables, revirtiendo el trabajo parcial antes de volver a ANALIZAR.

Diagrama de fases

stateDiagram-v2
    [*] --> ANALYZE
    ANALYZE --> BLUEPRINT: blueprint drafted
    BLUEPRINT --> CONSTRUCT: approved
    CONSTRUCT --> VALIDATE: steps complete
    VALIDATE --> DONE: tests pass
    VALIDATE --> CONSTRUCT: tests fail
    CONSTRUCT --> ROLLBACK: unrecoverable error
    ROLLBACK --> ANALYZE

Licencia

Apache-2.0

Contribuciones

¡Las contribuciones son bienvenidas! Asegúrese de que:

  • Todas las pruebas pasen (o cree problemas para las pruebas que fallen)
  • El código siga el estilo existente
  • Las nuevas funciones incluyan pruebas
  • La documentación esté actualizada

Mejoras futuras

  • Vectores de incrustación - Búsqueda de similitud semántica (pendiente de las actualizaciones de columnas vectoriales de KuzuDB)
  • Algoritmos de grafo avanzados - Capacidades de análisis adicionales
  • Actualizaciones del esquema del grafo - Según el buen funcionamiento del bucle de desarrollo automatizado, es posible que el esquema del grafo deba actualizarse para admitir nuevas funciones
  • Búsqueda semántica completa - Implementación de la herramienta de búsqueda semántica (actualmente es un marcador de posición: los índices vectoriales de KuzuDB son inmutables y dificultarían el desarrollo de esta función, ya que la actualización de las memorias no actualizaría los índices vectoriales)

Revisión MCP

Este MCP está verificado por MCP Review

https://mcpreview.com/mcp-servers/Jakedismo/KuzuMem-MCP

Revisiones de código automáticas con Codrabbit

CodeRabbit Pull Request Reviews