🗺️ ContextMap

El problema: cada chat empieza de cero

Si programas con Cursor, Claude Code, Copilot, ChatGPT, Antigravity, Windsurf o Hermes, esto te resulta familiar:

La solución: un disco duro de memoria viva para tus IAs

ContextMap escanea tu proyecto, entiende su estructura y su propósito, y produce dos artefactos portables que cualquier agente puede leer:

1. 🗺️ Una bóveda de Obsidian — el mapa mental del proyecto: ideas, decisiones, riesgos y su historia, navegable como un grafo.
2. 📄 Un brief ejecutivo (CONTEXT.md) — un resumen de alta densidad. La capa mínima pesa ~700 tokens e incluye identidad, estado, riesgos y pendientes.

Principio de diseño: el script propone, el agente dispone. ContextMap no "adivina" tu proyecto: genera el borrador, y el agente lo revisa y lo humaniza. El contexto solo se da por bueno cuando alguien lo ha verificado.

                    TU PROYECTO
                         │
                 ctxmap refresh .
                         │
        ┌────────────────┴────────────────┐
        ▼                                 ▼
 🗺️ Bóveda Obsidian              📄 Brief (CONTEXT.md)
 (grafo navegable +             (~700 tk con la capa
  memoria manual)                mínima; cacheable)
        └────────────────┬────────────────┘
                         ▼
      🤖 Cualquier agente: Cursor · Claude · Copilot ·
         Antigravity · Windsurf · Hermes · pi (MCP)

Cómo funciona (4 etapas)

Todo en un paso:

ctxmap refresh .     # = scan + build (preservando tus notas) + check + revisión de reglas

Inicio rápido

1. Instalar

pip install context-map-ai            # o: uv tool install context-map-ai

Con el servidor MCP para agentes:

pip install "context-map-ai[mcp]"

2. Inicializar el proyecto

ctxmap auto .

[auto] Proyecto: Mi-Tienda-Online
[auto] Stack detectado: Python 3.12 · FastAPI · pytest
[auto] Ecosistema: Cursor, Claude Code, GitHub Copilot
[auto]         + AGENTS.md · .cursor/rules/contextmap.mdc · .github/copilot-instructions.md
[auto] Vault: .context-map/vault-Mi-Tienda-Online/  (312 notas)
[auto] Brief: .context-map/CONTEXT.md  (1.852 tk → 695 tk con la capa mínima)
[auto] Readiness: 100/100 — ready

3. Mantenerlo al día

Cada vez que avances:

ctxmap refresh .

Ejemplos reales

🧠 Ejemplo 1 — La IA recuerda la decisión de ayer

Anoche acordaste: «usamos SQLite + FTS5, no embeddings, para la búsqueda personal». Lo dejaste en tu diario (.context-map/vault-*/7.0-MANUAL/Diario/), que el build nunca borra.

Hoy, en un chat nuevo, la IA pide el brief y ya lo sabe:

ctxmap search "por qué no usamos embeddings"

[search] 3 pasaje(s) para: por qué no usamos embeddings

1. [NOTA] Diario — 2026-10-07
   cita: .context-map/vault-MiApp/7.0-MANUAL/Diario/2026-10-07.md
   …se descartaron embeddings pesados; SQLite+FTS5 ya cubre la búsqueda personal y no añade dependencias…

2. [NOTA] Plan de Revisión (mediciones)
   cita: .context-map/vault-MiApp/7.0-MANUAL/MEJORAS/PLAN-REVISION.md
   …el peso estaba en copias de texto sin retención, no en el almacenamiento…

El resultado trae citas al archivo real: la IA puede profundizar solo en lo que necesita, en vez de leer carpetas enteras.

🔎 Ejemplo 2 — Recuperar contexto sin leer 100 archivos

ctxmap search "retención de snapshots"

Devuelve los 5 fragmentos más afines con su cita, en lugar de volcar el repositorio. Ese es el ahorro: el agente pide un pasaje, no un proyecto.

🌐 Ejemplo 3 — Todos tus proyectos, de un vistazo

ctxmap personal panorama

============================================================================
🌐 PANORAMA MULTI-PROYECTO
============================================================================
Proyecto               Semáforo   Inactivo   Eventos  Lecc/Dec   Sesiones
----------------------------------------------------------------------------
Mi-Tienda-Online       🟢 Activo   1d         582      4/2        3
App-Finanzas           🟢 Activo   5d         336      4/0        1
Bot-Automatizacion     🟡 Tibio    21d        32       2/1        0
----------------------------------------------------------------------------

Las lecciones y decisiones se consolidan en una base SQLite + FTS5 común a todos tus proyectos.

🛡️ Ejemplo 4 — Las reglas del equipo que la IA respeta

ctxmap adapt escribe tus normas una sola vez y las traduce al formato nativo de cada herramienta:

En cada refresh/arranque, ContextMap revisa esas reglas: si están al día no las toca; si tu plantilla cambió (versión nueva) las actualiza; y si las editaste a mano, las respeta.

🪙 Presupuesto de contexto (medido, no prometido)

El ahorro no es magia: es quitar del prompt lo que no aporta.

Frente a "pegar el repositorio entero", un brief de ~700 tokens es un ahorro superior al 99%. Además, el brief separa un prefijo invariante (cacheable por el proveedor) de la parte que cambia, para maximizar el prompt caching.

✨ Características

• 🧠 Memoria permanente — tu diario y tus notas manuales (7.0-MANUAL/) sobreviven a cada build (preserve: true). La historia no se borra: lo tosco se redacta.
• 🌐 Multi-proyecto — base SQLite + FTS5 con lecciones, decisiones y sesiones de todos tus proyectos.
• 🔌 Servidor MCP nativo — 30 herramientas (context, context_diff, context_search, personal_*, knowledge_*, refresh, check…) para agentes locales.
• 🧩 Paquete de pi — pi install npm:@kudawa/pi-contextmap (MCP + skill + prompts). Ver docs/PI_PACKAGE.md.
• 🛡️ Adaptación por IDE — reglas nativas para 10+ editores (ver Ejemplo 4).
• 📚 Second Brain — captura la web, artículos y vídeos; sintetiza respuestas con citas sobre tu propia wiki (ctxmap wiki ask).
• 🧩 Opcional, no obligatorio — OCR de PDF, embeddings y síntesis con LLM se activan solo si los necesitas; la base no añade dependencias pesadas.

⚖️ ContextMap frente a otras soluciones

💻 Comandos principales

ctxmap auto .                            # inicializar: detecta el ecosistema y crea todo
ctxmap refresh .                         # día a día: scan + build + check + revisión de reglas
ctxmap check .                           # salud y readiness (0-100)
ctxmap search "tema"                     # pasajes con citas (sin leer ficheros enteros)

ctxmap personal panorama                 # semáforo de todos tus proyectos
ctxmap personal timeline --dias 7        # qué se trabajó esta semana
ctxmap personal query "autenticación jwt"  # busca en lecciones y decisiones

ctxmap adapt                             # genera/actualiza reglas nativas por IDE
ctxmap mcp                               # servidor MCP (stdio) para agentes

ctxmap secret init                      # crea el baúl cifrado (frase maestra)
ctxmap secret set token_api --nota "apunte"   # guarda SIN mostrar el valor
ctxmap secret list                      # solo nombres/metadatos
ctxmap secret exec --ids token_api --autorizado "curl ..."   # usa sin ver (salida saneada)
ctxmap secret receta descargar_cartola --ids cl_banca --autorizado   # guion aprobado
ctxmap secret audit                     # registro de usos (nunca valores)
ctxmap secret backup pendrive/baul.json # respaldo cifrado portable

🔐 Baúl de secretos: valores cifrados con AES-256-GCM y clave derivada de tu frase maestra (nunca almacenada). El agente nunca ve los valores: secret_list solo nombres; secret exec/secret receta los inyecta en el proceso y sanea la salida (***), con autorización explícita y log de auditoría. El archivo cifrado viaja contigo (commit o pendrive). Requiere el extra opcional: pip install "context-map-ai[secure]".

🔌 Integración con agentes (MCP)

pip install "context-map-ai[mcp]"

Configura el servidor en tu agente (ejemplo, Hermes):

mcp_servers:
  ctxmap:
    command: "ctxmap"
    args: ["mcp"]

El agente gana herramientas como:

• context(minimo=True) — leer el brief sin gastar tokens de más.
• context_diff(since="<digest>") — al volver a una sesión, recibir solo lo que cambió.
• context_search("tema") — pasajes de la memoria con cita.
• personal_query("tema") — el historial de todos tus proyectos.

📚 Más documentación

• 🏛️ Documentación técnica y de arquitectura — AST, complejidad ciclomática, MCP stdio, topología del grafo.
• 🧩 Paquete de pi · 🖥️ Web Clipper · 🤖 LLM opcional
• 📜 Historial de versiones

📄 Licencia

MIT. Úsalo, modifícalo e intégralo en proyectos personales o comerciales.