🗺️ ContextMap

🇬🇧 English Speaker? Click the Read in English 🇬🇧 badge above or read the full English documentation at 👉 README_EN.md.

💡 ¿Qué es ContextMap y por qué existe?

Cuando trabajas con Agentes de IA en tu IDE (Antigravity, Cursor, Claude Code, Copilot, etc.), la IA suele olvidar las decisiones del pasado, desconocer las reglas inamovibles o proponer refactorizaciones a ciegas que rompen la arquitectura.

ContextMap resuelve esto creando una memoria viva del proyecto: Construye una bóveda interconectada en Obsidian (Graph View en Árbol Estricto) y un Brief Ejecutivo (CONTEXT.md) que le enseñan a cualquier Agente de IA:

• ¿Por qué existe el proyecto? (Propósito, negocio e identidad).
• ¿Qué riesgos afronta? (Complejidad estática, alertas y zonas sensibles).
• ¿Qué está implementado vs. pendiente? (Grafo desduplicado de ideas, bases y cambios).
• ¿Qué decisiones de arquitectura se han tomado? (Memoria viva de conversaciones pasadas e historias de commit).

🚫 No es un simple generador de documentación pasiva. Es un sistema vivo de Gobernanza Agéntica, Memoria Permanente, Readiness y Auto-Mantenimiento Autónomo.

⚡ Inicio Rápido en 10 Segundos

1. Instalación Global (con pip o uv)

# Opción 1: Desde PyPI oficial (recomendado con pip)
pip install context-map-ai

# Opción 2: Instalación aislada global con uv (ultra-rápido)
uv tool install context-map-ai

# Opción 3: Desde el repositorio en GitHub
uv tool install git+https://github.com/kudawasama/ContextMap.git

2. Poner en Contexto un Proyecto

En cualquier chat con tu Agente de IA dentro de tu IDE, dile:

💬 "Inicializa ContextMap para este proyecto"

O ejecútalo directamente en la consola de tu repositorio:

# Inicialización automática completa en 1 paso:
ctxmap auto .

# Día a día: mantén el contexto al día tras hacer cambios:
ctxmap refresh .

✨ Características Clave

🧠 1. Contexto Narrativo con Alma

Cada nota del vault se enriquece automáticamente con una estructura narrativa según su rol semántico:

• 💡 IDEAS: Por qué surgió, lógica, propuesta de mejora y matriz de Pros & Contras.
• ⚠️ RIESGOS: Ubicación, nivel de gravedad, impacto de ignorarlo y Estrategia de Mitigación.
• 🔧 CAMBIOS Y CORRECCIONES: Razón del cambio, componentes afectados y Verificación de No-Regresión.
• 📦 BASE: Rol estructural en la arquitectura e integraciones clave.
• 🧪 PRUEBAS: Funcionalidad validada, criterios de aceptación y comando pytest.
• 📄 DOCUMENTOS: Ingesta extractiva de PDFs, Markdown y textos con citas referenciadas.

🤖 2. Auto-Mantenimiento Autónomo (v1.9.0)

• 🏥 Self-Healing (ctxmap doctor --fix): Diagnostica y auto-repara inconsistencias de vaults, fragmentación de nombres de proyecto y metadatos sin perder notas manuales.
• 👀 Watcher Daemon (ctxmap watch .): Proceso en segundo plano que escucha cambios en el código (.py, .md, .json, etc.) y aplica parches incrementales desbouncheados (500ms).
• ⚓ Git Hooks Transparentes (ctxmap hook install): Inyecta scripts pre-commit y post-commit para sincronizar el mapa y el brief en cada commit.

🔌 3. Servidor MCP Nativo (11 Tools stdio)

Expone 11 herramientas MCP nativas vía stdio (ctxmap mcp) para que agentes compatibles como Hermes Agent, Claude Desktop o Cursor ejecuten refresh, scan, build, check, doctor o install_hooks directamente sin shell:

# Conectar a Hermes Agent:
hermes mcp add ctxmap --command ctxmap --args mcp

🛡️ 4. Zona Protegida y Memoria Viva (7.0-MANUAL/ & 8.0-KNOWLEDGE/)

• 7.0-MANUAL/: Alberga notas de sesión, diarios (Diario/YYYY-MM-DD.md) y acuerdos sostenidos con el usuario. El motor de build jamás las borra (preserve: true).
• 8.0-KNOWLEDGE/: Aprendizajes accionables reutilizables documentados por la IA: Lección · Cómo se resolvió · Prompt específico · Instrucción previa · Conexiones.

📦 5. Base de Datos Personal Consolidada Multi-Proyecto (ctxmap personal)

Consolida en un único archivo SQLite + FTS5 (~/.context-map/personal/personal.db) todos los eventos, lecciones y decisiones de todos tus proyectos, transportable en pendrive o Google Drive:

ctxmap personal sync --todos      # Sincroniza todos tus repositorios
ctxmap personal query "términos"  # Búsqueda ultra-rápida full-text (pocos tokens)

🏛️ Gobernanza Multi-IDE

ContextMap genera e inyecta reglas contextuales específicas para el stack de tu proyecto adaptadas a más de 10 herramientas de IA:

⚖️ Comparativa Funcional: ContextMap vs Herramientas Top del Mercado

En el ecosistema de herramientas de contexto para IA (2026), existen 4 soluciones populares. A continuación se compara ContextMap frente a las alternativas web y CLI más utilizadas:

🔍 ¿Por qué ContextMap es superior a la competencia?

• Repomix & Gitingest: Útiles para volcar un archivo plano de texto o copiar un repo de GitHub a un chat web, pero consumen presupuestos masivos de tokens y carecen de memoria de decisiones pasadas.
• Aider Repo Map: Excelente para el CLI de Aider extrayendo firmas sintácticas, pero no genera documentación visual para humanos ni guarda el trasfondo de decisiones conversadas.
• Indexadores de Cursor / Windsurf: Indizan vectores en su propio entorno cerrado, perdiendo todo el contexto si cambias de agente o IDE.
• ContextMap: Unifica la Gobernanza Agéntica Universal, la Memoria Viva Indestructible, el Auto-Mantenimiento Autónomo y una Bóveda Obsidian Interconectada, garantizando que tu proyecto mantenga su historia e identidad en cualquier IDE o modelo.

📜 Historial de Versiones (Releases)

Para consultar el historial completo de versiones, cambios, notas de release y novedades desde la v1.0.0 hasta la v1.9.0, por favor revisa el archivo CHANGELOG.md.

💻 Lista Completa de Comandos CLI

# 🚀 Día a día (recomendado): mantén el contexto al día en 1 solo paso
ctxmap refresh .                      # scan + build (preservando manuales) + check

# 👀 Monitoreo en segundo plano
ctxmap watch .                        # Daemon escuchador de cambios en tiempo real

# 🏥 Diagnóstico y Self-Healing
ctxmap doctor . --fix                 # Diagnostica y auto-repara el proyecto y el vault

# ⚓ Instalación de Git Hooks
ctxmap hook install                   # Inyecta pre-commit y post-commit transparentes

# 🔄 Cierre de sesión de trabajo
ctxmap wrap                           # refresh + resumen de memoria viva registrada

# 📦 Empaquetado y Transporte Offline Portátil
ctxmap pack . --output mi_proyecto.ctxpack  # Comprime la memoria viva en un paquete único
ctxmap unpack mi_proyecto.ctxpack ./destino # Restaura el contexto completo 100% offline

# 📦 Exportación de Contexto Portable (Repomix compatible)
ctxmap export . --format xml          # Exporta contexto plano en XML, JSON o Markdown

# 🤖 Servidor MCP
ctxmap mcp                            # Arranca el servidor MCP stdio

# 📦 Base de datos personal multi-proyecto
ctxmap personal sync --todos          # Sincroniza todos los repositorios locales
ctxmap personal query "términos"      # Búsqueda full-text en tu histórico

# 🛠️ Construcción y Escaneo
ctxmap auto .                         # Escaneo completo + ingesta git + build
ctxmap build                          # Reconstruye el Vault Obsidian
ctxmap build --brief                  # Genera CONTEXT.md y AGENTS.md
ctxmap check .                        # Audita el Readiness Score (0-100)

# 📥 Importadores de Historia
ctxmap import-git .                   # Importa commits de Git
ctxmap import-sessions                # Importa sesiones de Hermes Agent
ctxmap import-antigravity             # Importa conversaciones de Antigravity IDE
ctxmap import-chat export.jsonl       # Importa chats de Telegram, Discord o Slack
ctxmap ingest documento.pdf           # Ingiere PDFs/Markdown al vault

# 🧰 Adaptación Agéntica
ctxmap adapt .                        # Genera reglas agénticas respetando existentes
ctxmap adapt . --merge               # Anexa el bloque ContextMap preservando reglas del usuario

🛡️ Insignia para tu Proyecto

Si utilizas ContextMap para la gobernanza de contexto en tu repositorio, puedes añadir nuestra insignia oficial a tu README.md:

[![ContextMap Verified](https://img.shields.io/badge/ContextMap-100%2F100_Ready-blue?style=for-the-badge&logo=obsidian)](https://github.com/kudawasama/ContextMap)

📄 Licencia

MIT © kudawasama