Context Atlas

Context Atlas es una capa de memoria local-first y respaldada por evidencia para proyectos de software. Convierte el historial de Git, la estructura del repositorio, los manifiestos, los documentos del proyecto y las explicaciones revisadas por humanos en:

• una visión general del proyecto apta para nuevos integrantes;

• un mapa explorable de componentes y dependencias;

• un registro cronológico de cómo ha cambiado el proyecto;

• explicaciones de componentes y decisiones vinculadas a evidencia; y

• paquetes de contexto acotados que los agentes de codificación pueden leer antes de hacer un cambio;

• documentos seleccionados explícitamente y resúmenes de conversaciones con consentimiento humano; y

• contratos de seguridad versionados para extensiones y salida de proveedores en hosts de confianza.

Este repositorio contiene el código fuente de un candidato de lanzamiento alfa experimental 0.1.0 funcional: un CLI de Node.js, un panel web local, una biblioteca TypeScript, un servidor MCP stdio y un paquete de plugin para Codex. El runtime de plugin generado, las compuertas de comportamiento locales, el último paquete local candidato y la prueba de humo de paquete instalado limpio descritos a continuación se han verificado en el árbol de trabajo actual. Los flujos de trabajo alojados y un lanzamiento de GitHub no; 0.1.0 sigue sin publicarse, y el plan de producción más amplio se rastrea explícitamente en docs/.

Por qué existe

Las sesiones de codificación largas pierden el hilo. Los historiales de chat se comprimen, los agentes cambian, las decisiones no documentadas desaparecen y los resúmenes generados pueden volverse obsoletos o incorrectos silenciosamente. Context Atlas mantiene un mapa de alto nivel duradero fuera de cualquier chat individual, preservando al mismo tiempo un límite estricto entre hechos observados, afirmaciones documentadas, inferencias, propuestas y explicaciones aprobadas por humanos.

flowchart LR
  A["Git history"] --> I["Evidence-first ingestion"]
  B["Repository structure"] --> I
  C["README, ADRs, manifests"] --> I
  I --> D["Local SQLite knowledge graph"]
  I --> L["Hash-chained audit ledger"]
  D --> O["Overview and orientation"]
  D --> M["Mind map and timeline"]
  D --> P["Task-bounded context pack"]
  O --> H["Developer"]
  M --> H
  P --> X["Coding agent through MCP"]
  R["Human review"] --> D

Related MCP server: CodeIntel MCP Server

Inicio rápido

Requisitos: Git y Node.js 24 o más reciente.

git clone https://github.com/moelomda/context-atlas.git
cd context-atlas
npm.cmd ci
npm.cmd run build
node dist/cli.js init C:\path\to\your\git-repository --name "My Project"
node dist/cli.js serve --repo C:\path\to\your\git-repository

Abre http://127.0.0.1:4242. El servidor rechaza deliberadamente hosts no loopback sin autenticación.

Para una primera transferencia, usa esta secuencia:

node dist/cli.js overview --repo C:\path\to\repo
node dist/cli.js health --repo C:\path\to\repo
node dist/cli.js timeline --repo C:\path\to\repo
node dist/cli.js pack "add subscription retry handling" --json --repo C:\path\to\repo
node dist/cli.js proposals pending --repo C:\path\to\repo

Las propuestas narrativas generadas no se aceptan como verdad automáticamente. Revisa su evidencia y luego aprueba o rechaza explícitamente una propuesta específica:

node dist/cli.js approve <proposal-id> --actor human:alice --note "Reviewed against ADR-0001 and current code" --repo C:\path\to\repo
node dist/cli.js reject <proposal-id> --actor human:alice --note "Superseded by the current architecture" --repo C:\path\to\repo

El panel loopback también proporciona un espacio de trabajo de revisión de propuestas humano con preparación de evidencia, agrupación de conflictos, historial de revisión y confirmación explícita de aprobar/rechazar. Las mutaciones del navegador requieren una solicitud exacta del mismo origen y un token de sesión en memoria; no son capacidades de agentes.

Se puede agregar un documento externo de texto/Markdown o un resumen de conversación a través del flujo de trabajo Agregar fuente del panel o del CLI. La vista previa es de solo lectura y vincula los bytes exactos, el origen, el propósito, la autoridad, la sensibilidad y el actor humano atribuido. Aplicar requiere el plan fresco más IMPORT literal; las importaciones sensibles conservan metadatos y procedencia mientras omiten su cuerpo. El material importado sigue siendo evidencia no confiable y nunca aprueba una afirmación ni reescribe la visión general automáticamente.

$plan = node dist/cli.js source-import-preview C:\path\to\notes.md --type document --origin "Architecture workshop" --authority documented --sensitivity normal --purpose "Preserve retry decisions" --actor human:alice --repo C:\path\to\repo | ConvertFrom-Json
node dist/cli.js source-import C:\path\to\notes.md --plan $plan.planId --confirm IMPORT --type document --origin "Architecture workshop" --authority documented --sensitivity normal --purpose "Preserve retry decisions" --actor human:alice --repo C:\path\to\repo

Ejecuta sync después de confirmaciones significativas. Los informes de salud advierten claramente cuando el repositorio ha avanzado más allá del último commit indexado.

Los repositorios nuevos comienzan con un presupuesto de paquete de contexto de 8,000 tokens. Los repositorios existentes conservan el valor ya almacenado en .context-atlas/config.json—incluido el valor predeterminado heredado de 4,000 tokens—hasta que un operador lo cambie. pack --budget N aún anula el valor predeterminado del repositorio para una solicitud.

La sincronización también es necesaria después de un cambio de configuración que afecte la extracción o de una política de .atlasignore. Context Atlas registra una marca de agua de dependencia de guía cuando el contenido se sincroniza y revisa; cambiar ese límite hace que las afirmaciones revisadas previamente queden sin resolver. Las afirmaciones creadas antes del seguimiento de la marca de agua fallan de forma segura y requieren sincronización más una nueva revisión humana en lugar de ser heredadas silenciosamente.

Plugin de Codex y MCP

El paquete fuente del plugin está en plugin/context-atlas/. Compila y verifica este proyecto antes de empaquetarlo o instalarlo: la compilación incorpora un runtime MCP autocontenido en plugin/context-atlas/runtime/server.mjs, por lo que una instalación de marketplace copiada y verificada no depende de este árbol fuente. El envoltorio conserva un respaldo dist/mcp/server.js para el desarrollo local de fuentes.

El servidor MCP expone 13 herramientas de solo lectura:

• Navegación actual: atlas_overview, atlas_context_pack, atlas_explain, atlas_history, atlas_health, atlas_search y atlas_evidence.

• Conocimiento temporal: atlas_assertions, atlas_assertion_history y atlas_assertion_evolution.

• Inspección de paquetes guardados: atlas_pack_history, atlas_pack_snapshot y atlas_pack_diff.

• La sincronización, la creación de propuestas, las decisiones de propuestas, el guardado/actualización de paquetes y la aplicación de retención no están disponibles intencionalmente a través de MCP. Las decisiones de propuestas requieren un humano explícito a través del CLI o del panel loopback protegido; las otras mutaciones siguen siendo flujos de trabajo CLI operados por humanos.

• atlas_context_pack puede consumir el ID de una anulación CLI existente creada por humanos. No puede crear ni alterar una anulación, y los hallazgos críticos anulados siguen siendo prominentes tanto en el resultado estructurado como en su disposición de texto.

Cada herramienta acepta una ruta repo absoluta. Un cliente MCP directo también puede ejecutar node <ruta-absoluta-del-proyecto>/dist/mcp/server.js y establecer CONTEXT_ATLAS_REPO en un repositorio inicializado.

Las lecturas HTTP y MCP versionadas comparan la base de conocimiento, el Git/árbol de trabajo en vivo, el libro mayor, la sincronización y los límites de la política de guía antes y después de ensamblar una respuesta; un cambio concurrente se rechaza con un error de instantánea reintentable en lugar de adjuntar una marca de agua más nueva a datos más antiguos. El historial de paquetes guardados y las herramientas de diff devuelven un payload estructurado compacto con un puntero de texto corto, y cada resultado de herramienta MCP tiene un límite máximo de 2,500,000 caracteres con fallo cerrado.

Las extensiones confiables en proceso pueden usar la exportación pública context-atlas/extensions. Sus seis puertos versionados cubren extractores, analizadores, proveedores, redactores, exportadores y validadores; los manifiestos y las entradas/salidas se verifican con esquemas, las salidas inseguras fallan atómicamente y el código de extensión instalado se trata explícitamente como código ejecutable confiable. La biblioteca central también expone una pasarela de vista previa/consentimiento/autorización de salida de bytes exactos con listas de permitidos de proveedores, política de redacción/bloqueo, presupuestos de tokens/costos, indirección de credenciales, recibos de intento duraderos, revocación y sin reintentos automáticos. Ningún proveedor remoto está habilitado por el CLI, el panel web o el servidor MCP en este alfa.

Contrato de paquete de contexto

El esquema de paquete de contexto v2 siempre representa las mismas 15 secciones requeridas: identidad/autoridad, advertencias, objetivos, componentes, interfaces, convenciones, decisiones, restricciones, riesgos, cambios recientes, pruebas, conflictos, incógnitas, evidencia y exclusiones. Una sección puede ser explícitamente presente, ninguna o desconocida; un área de conocimiento vacía no se omite silenciosamente.

La selección es de elemento completo. Cada entidad material, relación activa, afirmación o evento admitido en el universo selector acotado se muestra completo con su cierre de evidencia o se enumera como exclusión material con una razón exacta; los registros no materiales ambientales se informan como recuentos agregados. Las relaciones llevan estado de uso actual, razón, autoridad, confianza y metadatos de validación de evidencia, y la topología no verificada no se presenta como guía establecida. El presupuesto duro se aplica a todo el objeto JSON compacto—no solo al cuerpo Markdown—y el adaptador MCP también reserva espacio para su envoltorio de resultado de herramienta. La estimación actual es una aproximación divulgada de caracteres divididos por cuatro, no un tokenizador de proveedor. Se aceptan solicitudes tan bajas como 500 tokens como entradas, pero la generación se niega con el mínimo calculado cuando el envoltorio obligatorio no cabe.

pack-save almacena un paquete verificado como una instantánea inmutable direccionada por contenido. pack-history, pack-diff y pack-refresh proporcionan historial acotado, comparación estructural y flujos de trabajo de reconstrucción contra el estado actual. Las instantáneas viven bajo .context-atlas/packs/; el almacén rechaza una 257.ª instantánea distinta en lugar de eliminar silenciosamente el historial. La actualización conserva la tarea original y el presupuesto de tokens, no hereda una anulación de seguridad anterior y rechaza cambios de identidad de repositorio o de repositorio/política inestables. Las lecturas de historial verifican el conjunto retenido antes de aplicar el límite de visualización solicitado, por lo que el límite de 256 elementos es un techo de seguridad, no una calificación de rendimiento para historial grande.

Antes de presentar o empaquetar la guía actual, los localizadores de archivos locales, commits de Git alcanzables, instantáneas de repositorio y instantáneas de componentes se revalidan contra rutas canónicas, política y resúmenes SHA-256. Los tipos de localizadores externos desconocidos se informan como no validados; no se actualizan a evidencia verificada. Las rutas de visión general, gráfico, búsqueda, explicación, afirmación, API, MCP, paquete y panel llevan metadatos de estado de uso actual/razón/autoridad/evidencia o retienen prosa revisada no resuelta.

Qué se registra

Context Atlas almacena su estado local bajo <repositorio>/.context-atlas/:

• config.json: política de escaneo y frescura;

• atlas.db: evidencia, entidades, versiones, relaciones, eventos y propuestas;

• ledger.ndjson: una cadena hash de solo anexión que cubre las acciones registradas;

• backups/: copias de seguridad SQLite verificadas y instantáneas de conocimiento portátiles;

• exports/: exportaciones JSON portátiles con suma de verificación; y

• packs/: instantáneas de paquete de contexto inmutables ignoradas con una capacidad dura de 256 elementos.

No se conservan diffs crudos completos ni cuerpos de archivos completos. Context Atlas sí conserva extractos de documentos acotados y saneados y metadatos de repositorio necesarios para la navegación. Los valores similares a secretos y las rutas sensibles como .env, credenciales, claves privadas y certificados se omiten. Agrega exclusiones específicas del repositorio a .atlasignore; sus reglas glob ordenadas admiten la negación con !.

La inicialización crea .context-atlas/.gitignore para que la base de datos, las exportaciones, las copias de seguridad, los paquetes y las instantáneas de migración completas previas a la actualización no se confirmen accidentalmente. Antes de que el almacenamiento heredado escriba una instantánea de migración o un paquete, Context Atlas agrega de forma segura la regla de datos derivados faltante sin reemplazar las reglas del operador. Confirma .context-atlas/config.json, .context-atlas/ledger.ndjson y .context-atlas/.gitignore cuando quieras memoria de proyecto compartida y revisable; mantén el material de base de datos ignorado local o transfiérelo solo a través del flujo de trabajo de copia de seguridad verificado.

Modelo de seguridad

Context Atlas es una ayuda de navegación, no una prueba de que el software sea correcto. El código y las pruebas actuales siguen siendo autoritativos para el comportamiento en tiempo de ejecución. Si un paquete de contexto está bloqueado, resuelva las comprobaciones de salud críticas enumeradas. El flujo de trabajo excepcional pack-override requiere un actor humano explícito, una justificación y una caducidad corta, y el paquete resultante permanece marcado visiblemente.

Comandos

Ejecute node dist/cli.js help para obtener la lista completa de comandos. Los flujos de trabajo principales son:

• Explorar: overview, map, timeline, search, explain, evidence, assertions, assertion-history, assertion-evolution.

• Preparar un agente: pack <task> [--budget N] [--json], pack-save <task>, pack-history, pack-diff <left> <right>, pack-refresh <snapshot>.

• Mantener memoria: sync, proposals, propose, approve, reject; approve/reject también están disponibles para un humano en el panel de control protegido de loopback.

• Añadir evidencia seleccionada: source-import-preview <file> seguido de source-import <file> --plan <id> --confirm IMPORT; el panel de control proporciona el mismo límite de vista previa/consentimiento para un archivo seleccionado en el navegador o un resumen pegado.

• Auditoría: health, validate, recover-ledger, privacy, retention-preview, retention-apply confirmado y retention-history (validate sale con código 2 en hallazgos críticos). La eliminación de retención se limita a archivos de exportación/copia de seguridad elegibles y requiere el ID exacto del plan de vista previa, actor human:, justificación y --confirm APPLY.

• Portabilidad: export, verify-export, import-preview, import de todo o nada, rebuild-verify, backup, verify-backup, restore --confirm RESTORE.

• Visualizar: serve en loopback.

Desarrollo y verificación

npm.cmd run build
npm.cmd test

El árbol de trabajo local actual ha pasado la suite de comportamiento normal (122/122 pruebas en 693 394 ms) y la ejecución de cobertura (122/122 pruebas en 901 735 ms; 95,40% líneas, 96,07% funciones y 76,81% ramas). También pasaron la compilación estricta de TypeScript de fuente/pruebas, la sintaxis de JavaScript, el análisis de JSON/YAML, la validación de identidad de versión y una auditoría npm audit en línea con cero vulnerabilidades reportadas. Estos son resultados locales de Windows, no resultados multiplataforma ni alojados.

La pasada final de rendimiento local también eliminó el trabajo duplicado de repositorio/evidencia del contrato de descripción general: en un fixture de nueve entidades, una solicitud real /api/v1/overview cayó de aproximadamente 8–12 segundos y 58 subprocesos de Git a 1,48–1,61 segundos y 12 subprocesos de Git, preservando las comprobaciones de instantáneas antes/después. Este es un resultado de regresión enfocado en un fixture pequeño, no una calificación de latencia para repositorios grandes.

El plugin se regeneró a partir de esta fuente: la fuente y el runtime empaquetado exponen cada uno las mismas 13 herramientas de solo lectura, los validadores de plugin y habilidad pasan, la regeneración independiente del runtime y de los avisos de terceros produjo hashes deterministas, y el runtime regenerado real pasó su regresión MCP (1/1). La inspección de flujos de trabajo con Actionlint 1.7.12 fijado pasó los cuatro flujos de trabajo; las 17 referencias uses de flujos de trabajo están fijadas por SHA completo, cubriendo siete commits únicos que se resolvieron y verificaron. Estas comprobaciones no sustituyen a CI alojado en GitHub, CodeQL, revisión de dependencias, SBOM o trabajos de procedencia.

La QA de navegador en la aplicación renderizada el 2026-08-23 cubrió el viewport de escritorio más los diseños de 390×844 y 320×720, incluyendo la descripción general y el flujo completo de vista previa/consentimiento de fuentes externas. Verificó que la confirmación permanece oculta hasta la vista previa, completó una importación local, comprobó el reflujo responsivo y el desbordamiento de ancho mínimo, y terminó con cero advertencias o errores de consola. La ejecución encontró y corrigió la visibilidad prematura de la confirmación y el desbordamiento horizontal de 320px; la suite web actualizada pasó 6/6. La cobertura anterior de navegación, mapa, línea de tiempo, salud, revisión, búsqueda, briefing, teclado, Escape y retorno de foco sigue siendo parte del contrato de pruebas de la fuente, pero esto no es un resultado de lector de pantalla, una afirmación de conformidad WCAG, una matriz de navegadores cruzados ni una prueba en otro sistema operativo.

Después de las correcciones de funciones y de la UI renderizada, se reconstruyó un candidato de paquete local de 124 archivos y pasó la verificación de inventario, archivos prohibidos, tamaño, SHA-1 y SHA-512. Un proyecto temporal limpio instaló ese archivo y sus dependencias, importó una fuente externa seleccionada, cargó el panel/API y la API de revisión protegida, importó la subruta de extensión pública y pasó las pruebas de humo de privacidad, anulación y MCP; la prueba de humo verificó el inventario completo de 13 herramientas de solo lectura y ejerció lecturas representativas de navegación, historial de paquetes, evidencia y anulación. Las ediciones de documentación crean un nuevo candidato de archivo, por lo que la entrega final registra solo la recualificación posterior a la documentación más reciente. Los resúmenes y tamaños exactos del archivo permanecen en el informe de paquete local en lugar de en este documento autorreferencial. Esto sigue siendo evidencia de artefacto local, no un repositorio remoto, una comprobación alojada, un artefacto firmado/atestiguado por SBOM ni una versión preliminar publicada.

La compilación copia la licencia del proyecto en el plugin, genera avisos de terceros a partir de las dependencias realmente incluidas en el runtime autocontenido, y los flujos de trabajo de lanzamiento están definidos para rechazar la deriva de runtime/licencia/avisos. Las comprobaciones locales de deriva de runtime/avisos y de identidad de lanzamiento pasan, incluida la paridad entre la entrada de etiqueta candidata, el paquete, el archivo de bloqueo, el manifiesto del plugin, la versión anunciada por MCP y el changelog fechado. La última prueba de humo del paquete local también pasa, pero estos controles no prueban la ejecución o publicación alojada; las mismas puertas aún deben pasar en el commit inmutable seleccionado para una versión preliminar real de GitHub.

La implementación actualmente usa la API SQLite integrada de Node, que Node 24 aún etiqueta como experimental. Este alfa está diseñado para un único repositorio local y un único escritor; la colaboración alojada, los paneles nativos de IDE, la observación incremental del sistema de archivos, la integración de proveedor/almacenamiento/UI, el análisis semántico de lenguaje más rico y el trabajo de rendimiento para repositorios grandes siguen siendo elementos de la hoja de ruta. La detección de rutas privadas de paquetes guardados bloquea la raíz del repositorio actual y un amplio conjunto de raíces reconocibles del sistema de archivos del host, pero el texto libre no puede distinguir perfectamente cada ruta absoluta POSIX personalizada de una ruta de API. La retención reduce las carreras de rutas con comprobaciones de descriptor e identidad, pero no afirma una eliminación libre de carreras contra un intercambio malicioso de componentes de directorio del mismo usuario.

Plan detallado y evidencia

• docs/PRODUCT_PLAN.md — usuarios, trabajos, alcance, requisitos funcionales y no funcionales.

• docs/ARCHITECTURE.md — modelo de datos temporal, límites de confianza, ingesta, recuperación y diseño de despliegue.

• docs/RISK_REGISTER.md — modos de fallo, controles, pruebas y riesgo residual.

• docs/IMPLEMENTATION_ROADMAP.md — hitos desde el prototipo hasta el endurecimiento de producción.

• docs/REQUIREMENTS_TRACEABILITY.md — registro de requisito a control/prueba.

• docs/IMPLEMENTATION_STATUS.md — evidencia honesta de lo que implementa esta versión alfa y lo que queda planificado.

Contribuciones, soporte y versiones

• Lee CONTRIBUTING.md antes de proponer o implementar un cambio. Documenta los invariantes del límite de confianza y el estándar de verificación.

• Usa los formularios estructurados de incidencias de GitHub para errores reproducibles, solicitudes de producto y problemas de documentación.

• Reporta vulnerabilidades de forma privada usando SECURITY.md; nunca pongas credenciales, código fuente propietario o un directorio real .context-atlas/ en una incidencia pública.

• La participación en el proyecto sigue CODE_OF_CONDUCT.md.

• Los cambios de versión y el procedimiento del mantenedor se encuentran en CHANGELOG.md y docs/RELEASING.md.

Licencia

MIT