Cursor-Cortex: Memoria Estructurada para Asistentes de IA

Funciona con Cursor, Claude Code y cualquier asistente de IA compatible con MCP.

Resuelve la pérdida de memoria y la confusión de contexto de los asistentes de IA. Cursor-Cortex le da a tu IA el pensamiento estructurado y la memoria a largo plazo que necesita para ayudarte realmente a crear software.

🧠 El problema con los asistentes de IA

Los asistentes de IA basados en LLM son increíbles generando código y explicando conceptos, pero tienen dificultades con:

• ❌ Pérdida de memoria: «¿En qué estábamos trabajando ayer?»

• ❌ Cambio de contexto: «Espera, ¿de qué trata este proyecto otra vez?»

• ❌ Fallos del agente: Perderse, alucinar, perder el rastro de los objetivos

• ❌ Sin estructura: Saltar entre ideas sin pensamiento sistemático

• ❌ Lagunas de conocimiento: Sin acceso a conocimientos específicos de la empresa o del proyecto

Resultado: Pasas más tiempo explicando el contexto que resolviendo problemas de verdad.

Related MCP server: BuildAutomata Memory MCP Server

🎯 La solución de Cursor-Cortex

Cursor-Cortex proporciona a tu IA memoria externa estructurada:

📋 Archivos de contexto → «¿De qué trata este proyecto?»

Tu IA siempre conoce los objetivos del proyecto, las decisiones de arquitectura y el enfoque actual.

📝 Notas de rama → «¿En qué hemos estado trabajando?»

Registro de desarrollo continuo para que tu IA pueda retomar exactamente donde lo dejaste.

🧠 Conocimiento tácito → «¿Cómo resolvemos este tipo de problema?»

Soluciones específicas de la empresa, patrones y conocimientos ganados con esfuerzo que los LLM no conocen.

✅ Listas de verificación → «¿Cuál es nuestro enfoque sistemático?»

Marcos de pensamiento estructurado que mantienen a la IA (y a ti) organizados y minuciosos.

💡 Antes vs Después

❌ Sin Cursor-Cortex:

You: "Help me continue the authentication work"
AI: "I need more context. What authentication system? What issues were you facing?"
You: "Ugh, let me explain everything again..."

✅ Con Cursor-Cortex:

You: "Help me continue the authentication work"  
AI: *reads context + branch notes + knowledge base*
"I see you're implementing JWT refresh tokens and hit CORS issues yesterday. 
Based on our company knowledge doc about API security, let's check the middleware..."

🚀 Beneficio principal

Convierte tu IA de un becario inteligente en un compañero experimentado que recuerda todo, sigue un pensamiento estructurado y tiene acceso al conocimiento institucional.

⚡ Guía de configuración completa

1. Instalar dependencias

npm install --legacy-peer-deps

Nota: La opción --legacy-peer-deps es necesaria debido a conflictos de dependencias entre pares de TensorFlow.js entre las versiones v3.x y v4.x.

2. Obtener la ruta completa

pwd
# Copy the output - you'll need it for configuration

3. Configuración de la búsqueda vectorial (opcional)

Para capacidades de búsqueda semántica impulsadas por IA:

Requisitos del sistema:

• Node.js 18+

• 2GB de RAM para modelos vectoriales

• 500MB de espacio en disco

Pasos de configuración:

# Step 1: Generate embeddings for all knowledge files
node generate-all-embeddings-cpu.js

# This creates vector embeddings for:
# - All tacit knowledge documents
# - All branch notes
# - All context files
# Duration varies by document count and system specs

# Step 2 (Optional): Force regenerate if content changes
node generate-all-embeddings-cpu.js --force

# Step 3 (Optional): View progress during generation
node generate-all-embeddings-cpu.js --verbose

Por qué es importante:

• Sin embeddings, la búsqueda semántica recurre a la búsqueda de texto

• Los embeddings precalculados hacen las búsquedas 100 veces más rápidas

• Genéralos una vez y úsalos para todas las consultas semánticas

• Los embeddings se almacenan en ~/.cursor-cortex/embeddings/

4. Configurar Cursor MCP

Crea o edita ~/.cursor/mcp.json:

"cursor-cortex": {
      "command": "node",
      "args": ["/YOUR/FULL/PATH/TO/cursor-cortex/index.js"],
      "tools": [
        "update_branch_note", 
        "add_commit_separator",
        "read_branch_notes",
        "update_context_file", 
        "read_project_context",
        "read_branch_context", 
        "list_context_files", 
        "generate_commit_message", 
        "generate_jira_comment", 
        "create_tacit_knowledge",
        "read_tacit_knowledge", 
        "search_branch_notes",
        "generate_embeddings",
        "create_completion_checklist",
        "read_checklist",
        "update_checklist",
        "sign_off_checklist",
        "archive_branch_note",
        "clear_branch_note",
        "list_all_branch_notes",
        "enhanced_branch_survey",
        "comprehensive_knowledge_search",
        "construct_project_narrative",
        "timeline_reconstruction",
        "context_sync_guidance",
        "analyze_documentation_gaps",
        "migrate_context_files",
        "request_critical_thinking_space",
        "check_critical_thinking_status",
        "request_thinking_guidance",
        "add_perspective",
        "request_synthesis_space",
        "request_synthesis_step_guidance",
        "complete_synthesis_step",
        "generate_context_zip",
        "unpack_context"
      ],
      "stdio": true,
      "env": {
        "DEBUG": "true"
      }
    },

Reemplaza /YOUR/FULL/PATH/TO/cursor-cortex/ con el resultado del paso 2

Nota: Esta configuración es para Cursor-Cortex v1.2.0+. Si usas una versión anterior, es posible que algunas herramientas no estén disponibles. Comprueba la versión de tu package.json y considera actualizarla.

5. Reiniciar Cursor

Cierra y vuelve a abrir Cursor por completo.

Instalación con Claude Code

Crea o edita .claude/settings.json en la raíz de tu proyecto (o ~/.claude/settings.json globalmente):

{
  "mcpServers": {
    "cursor-cortex": {
      "command": "node",
      "args": ["/YOUR/FULL/PATH/TO/cursor-cortex/index.js"]
    }
  }
}

Reemplaza /YOUR/FULL/PATH/TO/cursor-cortex/ con el resultado del paso 2 y reinicia Claude Code.

6. Habilitar el servidor MCP

1. Ve a Configuración de Cursor (Cmd/Ctrl + ,)

2. Navega a Funciones → Model Context Protocol

3. Busca cursor-cortex y actívalo ON

4. Deberías ver: Storage directory created at /Users/yourname/.cursor-cortex

7. Probarlo

En cualquier chat de Cursor, prueba:

"Update my branch notes: Testing Cursor-Cortex setup"

Si funciona, verás: Successfully updated branch note with: "Testing Cursor-Cortex setup"

8. Explorador de conocimiento (grafo visual)

Una vez que todo esté configurado, explora tu base de conocimiento como un grafo de red interactivo:

npm run explorer

Luego abre http://localhost:4000 en tu navegador.

Características:

• Visualización de tres niveles: Proyectos, notas de rama y conocimiento tácito como nodos interconectados

• Diseño basado en similitud: Los proyectos semánticamente similares se agrupan mediante la similitud coseno de los embeddings

• Animación de pulso neuronal: Observa cómo las señales se propagan por tu red de conocimiento en tiempo real

• Colores según actividad: Nodos más brillantes = proyectos actualizados más recientemente

• Haz clic para explorar: Haz clic en cualquier nodo para ver detalles, proyectos similares y etiquetas

• Alternancia de profundidad: Cambia entre las vistas Compacta (solo proyectos), Ramas y Completa

🔧 Solución de problemas

Problemas comunes:

❌ Error «Tool not found»

• Reinicia Cursor por completo después de la configuración

• Verifica que el servidor MCP esté habilitado en la configuración

• Comprueba que la ruta del archivo en mcp.json sea correcta (sin errores tipográficos)

❌ La configuración de MCP no funciona

• Valida la sintaxis JSON en jsonlint.com

• Asegúrate de que las comas y las comillas sean correctas

• Comprueba los permisos de archivo en mcp.json

❌ La búsqueda vectorial no funciona

• Ejecuta npm install para asegurarte de que TensorFlow.js esté instalado

• Comprueba que el sistema tenga 2GB+ de RAM disponible

• Prueba el modo de búsqueda de texto si falla la búsqueda vectorial

¿Necesitas ayuda? Crea un issue con tu mensaje de error para recibir soporte rápido.

9. Empezar a usarlo

• «Muéstrame mi trabajo sin confirmar» - Ve en qué has estado trabajando

• «Genera un mensaje de commit» - Crea commits a partir de tus notas

• «Crea un documento de conocimiento tácito» - Guarda soluciones para más adelante

📖 Uso básico

Captura tus pensamientos

Mientras programas, dile a tu asistente de IA:

"Update branch notes: Fixed the login validation bug by adding proper error handling 
for expired tokens. Had to modify the JWT middleware."

Mantente orientado

Cuando vuelvas al trabajo:

"Show me my uncommitted work"

Commits inteligentes

Cuando estés listo para hacer commit:

"Generate a commit message"

La IA lee todas tus notas y crea: «Corrige la validación del token JWT y el manejo de errores»

🏗️ Estructura del proyecto

Cursor-Cortex organiza tu conocimiento en:

• 📝 Notas de rama: En qué estás trabajando ahora mismo

• 📋 Archivos de contexto: Documentación y decisiones del proyecto

• 🧠 Base de conocimiento: Soluciones y conocimientos para referencia futura

• ✅ Listas de verificación: Realiza un seguimiento de la finalización del proyecto

Todo se almacena en ~/.cursor-cortex/ y es accesible a través de la IA.

🎓 Funciones para usuarios avanzados

Una vez que te sientas cómodo con lo básico, explora estas capacidades avanzadas:

Búsqueda de conocimiento entre proyectos

"Search all my projects for JWT authentication solutions"

Seguimiento automático de commits

node setup-hooks.js  # Auto-separates pre/post commit work

Listas de verificación de proyectos

Realiza un seguimiento de requisitos, pruebas y aprobaciones:

"Create a completion checklist for the user auth feature"

Intercambio de conocimiento en equipo

Crea documentos de soluciones reutilizables:

"Create tacit knowledge document about our JWT implementation approach"

Arqueología del conocimiento e inteligencia de proyectos

Analiza y sintetiza el conocimiento del proyecto:

"Survey all my branch documentation and show completeness scores"
"Construct a project narrative for the user authentication system"
"Show me a timeline of all development across projects"
"Analyze this folder structure for documentation gaps"

🛠️ Todas las herramientas disponibles

• update_branch_note - Añade entradas a tu registro de desarrollo

• read_branch_notes - El valor predeterminado es el archivo completo (incluidos los separadores COMMIT); mode=uncommitted o uncommittedOnly=true para el trabajo desde el último commit; beforeDate, afterDate o commitHash opcionales para filtrar

• add_commit_separator - Marca los límites de commit (automático mediante git hooks)

• generate_commit_message - La IA crea commits a partir de tus notas

• update_context_file - Documenta los objetivos y decisiones del proyecto

• read_project_context - Lee solo el contexto del proyecto independiente de la rama

• read_branch_context - Lee solo el contexto específico de la rama

• list_context_files - Navega por todos los documentos del proyecto con advertencias entre proyectos

• create_tacit_knowledge - Documenta soluciones para referencia futura

• read_tacit_knowledge - Busca conocimiento en todos los proyectos con búsqueda por etiquetas y contenido

• search_branch_notes - Busca notas de rama entre proyectos con búsqueda semántica

• generate_embeddings - Genera o regenera embeddings vectoriales para la búsqueda semántica

• comprehensive_knowledge_search - Búsqueda semántica global en TODO el conocimiento de Cursor-Cortex

• create_completion_checklist - Realiza un seguimiento de requisitos y entregables

• read_checklist - Ver el progreso

• update_checklist - Marca elementos como completados (manual o detección automática)

• sign_off_checklist - Aprobación formal con firmas

• archive_branch_note - Archiva el trabajo completado

• clear_branch_note - Restablece la documentación de la rama

• migrate_context_files - Migra los archivos de contexto existentes al Smart Hybrid Context System

• list_all_branch_notes - Ver todas las notas de rama de todos los proyectos con orden de prioridad

• enhanced_branch_survey - Análisis exhaustivo de la documentación con puntuación de completitud y mapeo de relaciones

• construct_project_narrative - Teje detalles técnicos dispersos en historias de producción coherentes

• timeline_reconstruction - Extrae datos cronológicos de las notas de rama y los separadores de commit

• context_sync_guidance - Obtén orientación contextual para sincronizar contextos de proyecto según los datos de la línea de tiempo

• analyze_documentation_gaps - Analiza la estructura de carpetas para identificar necesidades de documentación y crear listas de verificación automáticamente

• request_critical_thinking_space - Crea un espacio de trabajo de análisis sistemático utilizando la metodología Six Thinking Hats

• check_critical_thinking_status - Comprueba el estado de finalización del análisis de pensamiento crítico

• request_thinking_guidance - Obtén orientación para perspectivas específicas de Six Thinking Hats

• add_perspective - Añade el análisis de una perspectiva específica al espacio de trabajo de pensamiento crítico

• request_synthesis_space - Carga perspectivas en el espacio de trabajo de síntesis para su integración

• request_synthesis_step_guidance - Obtén orientación detallada para los pasos de síntesis

• complete_synthesis_step - Completa un paso de síntesis específico y actualiza el proceso

• generate_context_zip - Empaqueta el conocimiento en un archivo ZIP portátil para compartirlo entre usuarios/entornos

• unpack_context - Importa un paquete de contexto compartido con resolución segura de conflictos

🎛️ Configuración avanzada

Integración con Git

Los separadores automáticos de commit requieren que el servidor MCP esté en ejecución:

node setup-hooks.js  # Install git hooks

Interfaz CLI

Acceso directo sin IA:

node cursor-cortex-cli.js  # Interactive menu

🤝 Contribuciones

¿Encontraste un error o tienes una idea? Abre un issue o envía un pull request — ¡las contribuciones son bienvenidas!

Autor: Manuel Flores-Ramirez

📄 Licencia

Este proyecto está licenciado bajo la Parachute Public License (PPL) v1.0.

La PPL es una licencia ética que incluye restricciones contra el uso por parte de gobiernos, militares, vigilancia y otras entidades perjudiciales. Para más detalles y fundamentos, consulta parachute.pub.

© 2025 Manuel Flores-Ramirez.