ShadowGraph

ShadowGraph

Memoria de decisiones local-primero para agentes de IA. ShadowGraph recuerda qué decidió un agente, qué rechazó, por qué lo rechazó y cuándo esa decisión debería reconsiderarse.

Estado: Vista previa técnica / Acceso anticipado. Instálalo desde GitHub — no está en npm. Consulta Limitaciones y estado de la vista previa técnica.

Por qué es importante

La memoria del chat recuerda la conversación. Pierde la decisión.

Pregúntale a un agente tres meses después por qué el proyecto usa SQLite y la parte útil ya no está:

• La elección puede sobrevivir en un resumen. La alternativa rechazada y el motivo del rechazo no.
• Un hecho cambia — el despliegue pasa de un solo usuario a múltiples usuarios — y nada reabre la decisión.
• El mismo enfoque vuelve a fallar, porque el intento fallido nunca se registró como intento fallido.

ShadowGraph almacena ese razonamiento como datos estructurados e inspeccionables en lugar de prosa: qué se eligió, qué se rechazó, por qué, las suposiciones y la evidencia detrás de ello, intentos fallidos, resultados, procedencia, historial de confianza y las condiciones que deberían desencadenar un replanteamiento.

La promesa es deliberadamente limitada: las decisiones importantes de IA deberían sobrevivir a las sesiones y seguir siendo explicables, revisables y reconsiderables.

Para quién es: desarrolladores que construyen agentes con MCP, una CLI o una API HTTP local que necesitan que las decisiones consecuentes sobrevivan a una sesión. Es un almacén de decisiones y mantiene su almacén en tu máquina; los datos salen de la máquina solo mediante opciones que tú activas (consulta Local-primero y privacidad).

Inicio rápido — 5 minutos

Requisitos

• Node.js 20+ (el backend SQLite opcional necesita Node 22.5+ para node:sqlite)
• Sin dependencias npm en tiempo de ejecución, sin paso de compilación, sin cuenta, sin llamadas de red

1. Instalación

ShadowGraph no está publicado en npm. Durante la vista previa técnica, instálalo desde este repositorio. Una instalación global coloca shadowgraph en tu PATH, que es lo que los clientes MCP necesitan:

npm install --global github:LiLara-AI/shadowgraph

Esto instala la rama main actual: la compilación de desarrollo 0.42.0-dev.0, más reciente que la 0.41.0 de la vista previa técnica y no es una versión. Para instalar la vista previa técnica en su lugar, usa github:LiLara-AI/shadowgraph#v0.41.0. Antes de mover un almacén entre las dos, lee Moverse entre 0.41.0 y main.

git clone https://github.com/LiLara-AI/shadowgraph.git
cd shadowgraph
npm install
node src/cli.js setup
node src/cli.js doctor

npm install shadowgraph-unified-plugin no funciona y falla con E404. El paquete está private: true y no publicado, y el nombre del registro no está reservado. Este README cambiará si la publicación se aprueba alguna vez.

2. Argumentos JSON y tu shell

Cada comando de ShadowGraph toma un único argumento JSON, por lo que las comillas dependen de tu shell. Elige la fila para el shell que realmente estás usando — esta es la razón más común por la que falla el primer comando:

Los ejemplos a continuación usan la forma de bash. Si un comando falla en tu shell, por favor repórtalo.

3. Inicializa un almacén

mkdir shadowgraph-demo
cd shadowgraph-demo
shadowgraph setup
shadowgraph doctor

setup crea .shadowgraph/data.json en el directorio actual, así que ejecútalo donde quieras que viva el almacén. Nunca reescribe un almacén existente. doctor luego verifica la compatibilidad de Node, la legibilidad y escritura del almacenamiento, la validez del grafo y el punto de entrada MCP.

Ejecuta setup antes de doctor: en un directorio nuevo doctor reporta Storage is not initialized y sale con 1 hasta que exista un almacén. Eso es esperado, no una instalación fallida.

4. Registra una decisión, reinicia y recupérala

shadowgraph decision '{"project":"checkout-service","title":"Choose the datastore","chosen":"SQLite","confidence":0.8,"alternatives":[{"label":"PostgreSQL","reasonRejected":"Single-user local deployment does not justify running a server","reopenWhen":[{"key":"deployment","operator":"equals","value":"multi-user"}]}]}'

shadowgraph fact '{"project":"checkout-service","key":"deployment","value":"single-user","sourceClass":"human_confirmed","confidence":1}'

shadowgraph search '{"query":"datastore","project":"checkout-service"}'

Cada comando se ejecuta en un proceso nuevo y reabre el almacén desde el disco, por lo que el resultado de search vuelve a través de un reinicio real, no desde el estado en memoria. Ahora tienes una decisión que lleva su alternativa rechazada, el motivo del rechazo y la condición que debería reabrirla.

La demostración: una decisión que se reabre sola

Este es el punto central de ShadowGraph, en tres comandos. Continúa en el mismo directorio.

La decisión está resuelta, así que no hay nada que reconsiderar todavía:

shadowgraph review '{"project":"checkout-service"}'

{
  "items": [],
  "completeness": {
    "returned": 0,
    "total": 0,
    "omitted": 0,
    "complete": true,
    "losslessItems": true,
    "scope": {
      "project": "checkout-service",
      "requestState": "project_selected",
      "originPresented": false,
      "grant": null
    }
  }
}

Ahora el mundo cambia. El despliegue se vuelve multiusuario:

shadowgraph fact '{"project":"checkout-service","key":"deployment","value":"multi-user","sourceClass":"human_confirmed","confidence":1}'

Reinicia y pregunta de nuevo — pasando solo el proyecto, nunca el hecho desencadenante:

shadowgraph review '{"project":"checkout-service"}'

El resultado, abreviado a los primeros campos de su único elemento:

{
  "items": [
    {
      "decisionId": "decision_1788079304730_yjawcg",
      "title": "Choose the datastore",
      "reason": "deployment",
      "alternativesToReconsider": [
        "PostgreSQL"
      ]
    }
  ]
}

ShadowGraph leyó el hecho almacenado, lo comparó con la regla guardada con la decisión y sacó a la superficie la alternativa que había sido rechazada por una razón que ya no se sostiene. El elemento completo también lleva violatedConditions (cada uno nombra el hecho almacenado que coincidió como evidencia) y la señal de revisión que registró, y el resultado termina con un bloque completeness como el primero. Tus IDs y tiempos serán diferentes.

Eso es memoria de decisiones: no "de qué hablamos", sino "qué decidimos, qué descartamos y ¿eso sigue siendo válido?"

Para la misma historia a través de MCP, la API HTTP y la API de JavaScript — además de registrar intentos fallidos y resultados — consulta la demostración de memoria de decisiones.

Capacidades clave

Memoria de decisiones. Las decisiones llevan el enfoque elegido, alternativas rechazadas con sus motivos, suposiciones, evidencia y reglas estructuradas de reopenWhen. Los resultados (exitosos, mixtos, fallidos, desconocidos) retroalimentan la confianza.

Reconsideración. review() evalúa reglas de reapertura contra hechos almacenados, por lo que funciona después de un reinicio sin que el llamador vuelva a proporcionar lo que cambió. Las señales de revisión se persisten y pueden reconocerse.

Memoria de intentos fallidos. Los intentos registran el enfoque, el resultado, el entorno y la lección, para que un agente pueda descubrir que algo ya se intentó y por qué no funcionó.

Procedencia auditable. Cada afirmación lleva un sourceClass — agent_claimed, tool_observed, human_confirmed o production_verified — que registra lo que se afirmó sobre el origen de una observación, nunca prueba de ello. La entrada ordinaria de herramientas no puede crear verified; eso requiere un verificador Ed25519 configurado por separado.

Memoria con alcance y recuerdo temporal. remember() / recall() almacenan preferencias, perfiles, metas, instrucciones, procedimientos, episodios y notas bajo un proyecto más userId / agentId / runId opcionales. Los hechos, recuerdos y relaciones son bi-temporales, por lo que puedes preguntar qué era verdad asOf un momento pasado. La recuperación fusiona señales léxicas, vectoriales, de distancia en el grafo y temporales, y declara qué señales no estaban disponibles en lugar de degradarse silenciosamente.

Aislamiento de proyectos y alcance. Cada escritura necesita un proyecto, un enlace de espacio de trabajo (shadowgraph bind) o un id de origen de captura: una escritura sin ninguno de ellos es rechazada (write_scope_unresolved) en lugar de aterrizar en un bucket default compartido, y default es un nombre de proyecto ordinario. search, retrieve, recall, context y traverse leen solo los registros del proyecto seleccionado, y la expansión del grafo que hacen permanece en ese proyecto; sin proyecto seleccionado no devuelven nada, nunca todos los proyectos y nunca un bucket default compartido. Un id fuera del proyecto seleccionado — o uno que no existe — recibe la misma respuesta: sin registro. Una nueva relación une dos registros de un proyecto (link necesita ese proyecto), y una entre proyectos es rechazada como un punto final faltante; las relaciones almacenadas entre proyectos antes se conservan, y ninguna lectura las sigue. El diario, stats, la salida de redact y la exportación pública (GET /records, list) leen de la misma manera. Un cambio por id — un resultado, un estado, evidencia de confianza, una sustitución, una verificación de hecho, un reconocimiento de revisión — cambia solo lo que su propio proyecto u origen posee, y responde al id de otro proyecto exactamente como a uno faltante. Guardar, respaldar y restaurar aún cubren todo el almacén; la exportación pública y una redacción son lecturas de un proyecto y son rechazadas como un almacén. Los registros escritos antes del esquema 6 en default, o sin proyecto, no pertenecen a ningún proyecto que un llamador pueda nombrar, por lo que ninguna lectura de proyecto los devuelve; el legacyAttributionReview() del núcleo los lista para inspección, cada uno con su estado heredado y registro canónico, y no infiere ningún proyecto para ellos. Una lectura sin proyecto reporta su resultado vacío como incompleto (completeness.complete: false, con una limitación de scoped_coverage), nunca como completo. Las herramientas MCP, las rutas HTTP y los verbos CLI pasan el project del llamador (o originId) al mismo límite: un resultado, un cambio de estado o un reconocimiento de revisión enviado con uno cambia solo lo que posee, y la misma llamada sin uno es rechazada (write_scope_unresolved) igual para cada id; stats sobre HTTP (GET /stats?project=...) y la CLI cuenta solo el contenido del proyecto nombrado, y nada sin uno. El acceso más amplio es explícito y revocable: una concesión de acceso que el propietario emite en una terminal (issue-access) abre los proyectos u orígenes que nombra a lecturas explícitas que la presentan, hasta que expira o es revocada. No es un intercambio solo de lecciones, y la entrega automática de hooks nunca usa una. Un nombre de proyecto, como un id de origen presentado, es un selector, no un control de acceso: cualquier llamador de la CLI, MCP o API HTTP que nombre uno explícitamente lo lee. Los registros heredados son lo que solo una concesión abre. Consulta el contrato de transporte de acceso. El alcance omitido significa alcance todo-nulo. La purga es previsualizable, lógica por defecto y explícitamente irreversible en modo duro.

Recuperación explicable. Los resultados exponen puntuaciones brutas, rangos y razones, y cada respuesta limitada declara su total, páginas y alcance omitido. Nada se resume silenciosamente.

Local-primero y privacidad

Todo es un archivo local. El servidor HTTP se vincula a 127.0.0.1 y rechaza orígenes de navegador no locales. No hay servicio en la nube, ni cuenta, ni telemetría, ni analíticas — ShadowGraph no hace ninguna solicitud de red saliente a menos que configures una explícitamente.

Las opciones que pueden enviar datos fuera de la máquina están todas desactivadas por defecto:

• Embeddings. No hay ningún endpoint configurado. Un servidor compatible con OpenAI en localhost funciona una vez configurado; un endpoint remoto además requiere SHADOWGRAPH_ALLOW_REMOTE_EMBEDDINGS=1, porque eso significa que la memoria y el texto de las consultas salen de tu máquina.
• Extracción. La extracción aprobada por separado envía capturas redactadas elegibles a través de la ruta de suscripción de Claude de primera parte compatible. Este ejecutor no admite claves de API, proveedores alternativos, proxies ni alternativas de pago; el propietario debe deshabilitar el exceso de suscripción. La redacción por patrones no puede garantizar que se elimine cada secreto. La extracción solo se ejecuta en Windows, con Claude Code 2.1.288, o con el binario perfilado de Claude Code 2.1.292 y la recepción de una validación de host real superada (ShadowGraph verifica la identidad del recibo, no la validación en sí); en cualquier otra plataforma, versión o binario se rechaza. Consulta extracción y sus límites de host.
• Exportación Markdown. markdown-sync escribe copias en texto plano que tú controlas. ShadowGraph no puede encontrar ni eliminar esas copias más tarde; consulta Almacenamiento, copias de seguridad y eliminación.
• Entrega al host. Inerte a menos que instales los hooks y actives la entrega para un almacén. Una vez activa, los registros que entrega (valores con forma de credencial redactados primero) pasan a formar parte de la transcripción de la sesión de Claude Code y de lo que el modelo recibe, como cualquier contexto; ShadowGraph no puede eliminarlos de la transcripción. Consulta la guía de integraciones.

La captura, la extracción y la entrega requieren sus procedimientos de activación por separado. Una vez activa, la captura registra tus prompts, las llamadas a herramientas con su entrada y salida, y el texto del asistente de las sesiones de Claude Code, redactado por patrones, en un almacén local privado. La captura utiliza el almacén externo inscrito; los almacenes manuales existentes no se migran automáticamente, y la entrega lee el único almacén que fija su activación. Los datos sin procesar elegibles no citados caducan según la política configurada incluso cuando están en cuarentena, mientras que la experiencia aceptada y la evidencia citada requerida están protegidas. Los datos sin procesar caducados pueden no volver a extraerse.

Consulta el mapa del ciclo de vida de los datos para conocer el alcance de la eliminación, las copias retenidas, la poda explícita de Markdown y los mínimos de recuperación, y el ciclo de vida de la experiencia integrada para conocer los límites de corrección, reprocesamiento, reinicio y apagado.

Para uso local compartido, establece un token Bearer:

SHADOWGRAPH_API_TOKEN="use-a-random-token-at-least-16-characters" shadowgraph serve

Luego envía Authorization: Bearer use-a-random-token-at-least-16-characters con cada solicitud. Esto es defensa en profundidad para un despliegue local, no un modelo de seguridad para internet público. Consulta SECURITY.md.

Interfaces

MCP

shadowgraph mcp

Se recomienda el modo compacto: anuncia 16 herramientas de flujo de trabajo mientras que el grafo completo, los recuerdos, los hechos, las alternativas y los resultados se almacenan con fidelidad total. El modo compacto es una elección de anuncio de herramientas, no un almacenamiento con pérdidas.

SHADOWGRAPH_MCP_COMPACT=1 shadowgraph mcp

Los metadatos de las herramientas siguen la revisión que negocia initialize: una sesión negociada en 2025-03-26 también recibe anotaciones de comportamiento, y una en 2025-06-18 o 2025-11-25 también recibe esquemas de salida y resultados estructurados, mientras que una sesión en 2024-11-05 mantiene los miembros de herramientas y los resultados serializados que siempre tuvo. Una solicitud de una revisión que este servidor no implementa se responde con 2025-11-25, la más reciente que sí implementa. Consulta la guía de compatibilidad MCP para la tabla completa.

Las 16 herramientas compactas son shadowgraph_context, shadowgraph_review_context, shadowgraph_expand, shadowgraph_remember, shadowgraph_recall, shadowgraph_record_decision, shadowgraph_record_attempt, shadowgraph_record_fact, shadowgraph_record_outcome, shadowgraph_retrieve, shadowgraph_search, shadowgraph_review, shadowgraph_validate, shadowgraph_maintain, shadowgraph_ack_review — para que un cliente compacto pueda despejar una revisión que ya puede ver, en lugar de acumular señales sin forma de reconocerlas — y shadowgraph_reconsider, que lee la misma evaluación como un veredicto: revisión recomendada, sin cambios, o un humano debería mirar. shadowgraph_context es una lectura que no persiste nada; shadowgraph_review_context persiste las señales de revisión que encuentra debidas, y shadowgraph_expand expande una línea de afirmación a su registro completo. El modo completo anuncia 35 — consulta la guía de compatibilidad MCP para el inventario completo, cada revisión de protocolo y el comportamiento verificado del cliente. El modo completo incluye herramientas del propietario: copia de seguridad a una ruta que el llamador nombra, restauración desde una y purga. Sus shadowgraph_bind y shadowgraph_attribute solo proponen: no cambian nada y devuelven la entrada shadowgraph bind o attribute que el propietario ejecuta y confirma en una terminal. Dale a un agente el modo compacto a menos que quieras que tenga las herramientas del propietario (consulta SECURITY.md).

Configuración de herramientas de IA

Instala globalmente primero para que el cliente pueda encontrar shadowgraph en su PATH:

npm install --global github:LiLara-AI/shadowgraph
shadowgraph setup
shadowgraph doctor

Claude Code (ámbito de usuario):

claude mcp add --scope user --env SHADOWGRAPH_MCP_COMPACT=1 --transport stdio shadowgraph -- shadowgraph mcp

Cursor (.cursor/mcp.json o ~/.cursor/mcp.json):

{"mcpServers":{"shadowgraph":{"type":"stdio","command":"shadowgraph","args":["mcp"],"env":{"SHADOWGRAPH_MCP_COMPACT":"1"}}}}

Codex:

codex mcp add shadowgraph --env SHADOWGRAPH_MCP_COMPACT=1 -- shadowgraph mcp

Hermes Agent:

hermes mcp add shadowgraph --command shadowgraph --connect-timeout 30 --env SHADOWGRAPH_MCP_COMPACT=1 --args mcp

Los formularios de archivo para los cuatro viven en integrations/; npm run check:integrations los valida como archivos, lo que no es una ejecución en vivo de cada cliente. Establece un SHADOWGRAPH_FILE absoluto en el entorno del cliente cuando un almacén debe compartirse entre directorios de trabajo.

CLI

Los comandos que realmente usarás:

shadowgraph setup
shadowgraph doctor
shadowgraph context '{"project":"my-app"}'
shadowgraph decision '{"project":"my-app","title":"Choose the datastore","chosen":"SQLite"}'
shadowgraph fact '{"project":"my-app","key":"deployment","value":"local","sourceClass":"human_confirmed"}'
shadowgraph attempt '{"project":"my-app","solution":"Rewrite everything","result":"Regression"}'
shadowgraph outcome '{"project":"my-app","decisionId":"DECISION_ID","outcome":{"status":"failed","lessons":["Assumption was wrong"]}}'
shadowgraph review '{"project":"my-app"}'
shadowgraph search '{"query":"database","project":"my-app"}'
shadowgraph remember '{"project":"my-app","memoryType":"preference","key":"editor","text":"Prefers VS Code"}'
shadowgraph recall '{"project":"my-app","query":"development environment"}'

API HTTP

shadowgraph serve
curl http://127.0.0.1:8787/health

Un panel de solo lectura se sirve en http://127.0.0.1:8787/dashboard. Solo habla con el mismo origen local, y un token ingresado allí se mantiene solo en la memoria de la página — nunca en cookies, almacenamiento local o datos de ShadowGraph.

GET  /health                 GET  /stats               GET  /records
GET  /search?q=&project=     GET  /review-signals      GET  /validate
GET  /journal

POST /decisions              POST /attempts            POST /memories
POST /recall                 POST /facts               POST /outcomes
POST /review                 POST /context             POST /status
POST /relationships          POST /traverse            POST /redact
POST /supersede              POST /maintain            POST /retrieve
POST /review-signals/ack     POST /repair-plan         POST /backup
POST /restore                POST /rebuild             POST /confidence-evidence
POST /projects/purge-preview

DELETE /projects

JavaScript

import { createShadowGraph } from 'shadowgraph-unified-plugin';

const graph = createShadowGraph();
graph.addDecision({
  project: 'checkout-service',
  title: 'Choose the datastore',
  chosen: 'SQLite',
  confidence: 0.8,
  alternatives: [{
    label: 'PostgreSQL',
    reasonRejected: 'Single-user local deployment does not justify running a server',
    reopenWhen: [{ key: 'deployment', operator: 'equals', value: 'multi-user' }]
  }]
});
graph.addFact({
  project: 'checkout-service',
  key: 'deployment',
  value: 'multi-user',
  sourceClass: 'human_confirmed',
  confidence: 1
});

// review() reads stored facts, so this also works in a fresh process after an
// export/save and load. Do not pass the triggering fact again.
console.log(graph.review({ project: 'checkout-service' }));

La importación de especificador desnudo se resuelve cuando ShadowGraph es una dependencia de tu proyecto (npm install github:LiLara-AI/shadowgraph). Con una instalación --global, usa las superficies CLI, HTTP o MCP en su lugar, o importa desde la ruta instalada.

Almacenamiento, copias de seguridad y eliminación

JSON es el valor predeterminado sin dependencias y almacena un grafo versionado en .shadowgraph/data.json. Establece SHADOWGRAPH_FILE para reubicarlo. Establece SHADOWGRAPH_STORAGE=sqlite en Node 22.5+ para el adaptador relacional respaldado por WAL. Los almacenes se escriben en el esquema 7; los esquemas 1 a 6 siguen siendo legibles, y downgrade hace una copia en el esquema 5 (el predeterminado, que 0.41.0 lee) o el esquema 6 (que solo las compilaciones intermedias no publicadas leen), sin cambiar el almacén.

El estado y el diario se escriben en una sola operación atómica, cada guardado y restauración para un destino comparte una valla de bloqueo entre procesos, y una escritura obsoleta se rechaza con un conflicto de revisión en lugar de perderse silenciosamente. backup toma una instantánea consistente; restore valida la consistencia del dominio y del diario antes de reemplazar el estado en vivo, y revierte en caso de fallo. Esto es seguridad de reversión a nivel de proceso, no una afirmación de durabilidad ante fallos o pérdida de energía. Las garantías completas — tiempos de espera de bloqueo, recuperación de bloqueos obsoletos, aritmética de revisiones e informes de artefactos de restauración — están en la referencia de la API y en el contrato de restauración SQLite.

La eliminación es explícita y previsualizable:

shadowgraph purge-preview '{"project":"release-demo"}'
shadowgraph purge '{"project":"release-demo"}'
shadowgraph purge '{"project":"another-project","mode":"hard"}'

La purga lógica (la predeterminada) elimina el contenido del proyecto de la proyección en vivo y mantiene un esqueleto de purga auditable y sin carga útil. La purga dura elimina físicamente las entradas del diario, crea una brecha declarada y no se puede deshacer.

La purga no puede eliminar exportaciones Markdown externas. ShadowGraph no tiene forma de encontrar copias en texto plano en espacios de trabajo arbitrarios, historial de Git, sincronización en la nube, copias de seguridad o medios extraíbles. Elimina esas por separado. Las copias de seguridad, las copias de preservación y degradadas que migrate y downgrade escriben, y los archivos de recuperación que deja una restauración interrumpida también pueden contener material purgado o caducado más tarde; una purga no los alcanza (consulta el mapa del ciclo de vida de los datos).

Limitaciones y estado de Vista Previa Técnica

La última versión es la 0.41.0 Vista Previa Técnica / Acceso Anticipado (etiqueta v0.41.0). No es Beta ni estable. main lleva 0.42.0-dev.0, una compilación de desarrollo: no publicada, no estable, y sus criterios de aceptación no han sido evaluados.

• Las interfaces y el esquema de almacenamiento pueden cambiar aún. No lo uses para datos que no puedas reproducir.
• No está en npm. El paquete está deliberadamente private: true. La etiqueta Git v0.41.0 y el lanzamiento de GitHub están autorizados por el mantenedor para esta Vista Previa Técnica; la publicación en npm no está autorizada y no ha ocurrido.
• No se ha medido ningún benchmark comparativo. Se ejecutó la infraestructura de benchmarks comparativos, pero no se midió ningún brazo porque no había un endpoint común local/gratuito de LLM y embeddings disponible. No se respalda ninguna afirmación comparativa de rendimiento, calidad, tokens, costo o "mejor". ShadowGraph no afirma ser más rápido, más barato, de menor consumo de tokens, más preciso o mejor que cualquier otro sistema de memoria. Consulta el informe de benchmark.
• Estado de la revisión de seguridad. Una revisión de seguridad independiente asistida por IA del commit 4a5e076 (árbol 62c1918e) se completó el 2026-08-30 por Antigravity Assistant (Gemini 3.7 Flash), con un resultado APROBADO y sin hallazgos sin resolver. No se ha realizado ninguna auditoría de seguridad humana de terceros. Consulta SECURITY.md. Esa revisión cubrió el commit 4a5e076, antes de la etiqueta v0.41.0. Nada agregado desde entonces ha tenido una revisión de seguridad independiente, incluidos el alcance del proyecto, las concesiones de acceso, los registros de eliminación y la restauración consciente de purgas, la migración de esquemas 6 y 7 y downgrade, los hooks de Claude Code, la captura automática, la lectura y extracción de transcripciones.
• Nada se captura ni se extrae a menos que lo actives, y no hay sincronización alojada. Sin la integración opcional de Claude Code, ShadowGraph registra lo que le indicas que registre. Con ella, la captura automática de sesiones de Claude Code y la extracción basada en modelos permanecen inactivas hasta que el propietario las active por separado; la captura cubre solo eventos declarados, con redacción basada en patrones (consulta la guía de integraciones y extracción).
• La captura y la entrega cubren una sola tienda inscrita. La entrega lee la única tienda que su activación fija, y la captura escribe en la tienda con la que se inscribió; otras tiendas que uses manualmente no se entregan ni se capturan, y no se migran.
• Mantenedor único. Sin soporte de pago, sin SLA de parches y sin programa de recompensas por errores.

Moverse entre 0.41.0 y main

• Haz una copia de seguridad antes de actualizar. shadowgraph backup [<file>] copia la tienda: una tienda JSON byte por byte, una tienda SQLite tabla por tabla. Una copia de seguridad tomada antes de que esta compilación guarde por primera vez la tienda sigue siendo una tienda de esquema 5 que 0.41.0 abre. (Al abrir una tienda SQLite, esta compilación agrega una tabla propia; 0.41.0 aún lee la tienda). Una vez que esta compilación ha guardado la tienda, sus copias de seguridad son tiendas de esquema 7; para usar una con 0.41.0, restáurala en una ruta nueva con esta compilación y crea una copia de esquema 5 como se indica a continuación.
• Actualización. Esta compilación lee cada tienda que 0.41.0 escribió (esquemas 1 a 5) y escribe el esquema 7 en su siguiente guardado. Lo que cambia para ti:
  • Una escritura que no nombra un proyecto es rechazada (write_scope_unresolved). Pasa project, o vincula el espacio de trabajo a un proyecto con shadowgraph bind.
  • Los registros que 0.41.0 almacenó en default — escritos sin un proyecto, que 0.41.0 puso allí, o nombrando default — son material heredado cuyo propietario esta compilación trata como incierto: ninguna lectura los devuelve, ni siquiera con "project":"default". No se eliminan. El legacyAttributionReview() de la API de JavaScript los lista, y shadowgraph attribute '{"ids":["<id>"],"targetProject":"<project>","reason":"<why>"}', que confirmas en una terminal, mueve registros nombrados a un proyecto. Para anotar sus IDs antes de actualizar, ejecuta el shadowgraph list de 0.41.0, que imprime cada registro, y conserva los IDs de aquellos con "project": "default". Si dependes de tales registros y no quieres moverlos, quédate en 0.41.0.
  • Algunos resultados cambiaron de forma; por ejemplo, review devuelve {"items": [...], "completeness": {...}} en lugar de un arreglo. El registro de cambios lista cada cambio incompatible.
• Volver a 0.41.0. 0.41.0 lee solo los esquemas 1 a 5 y rechaza una tienda que esta compilación ha guardado. Crea una copia de esquema 5 con shadowgraph downgrade '{"output":"<new file>"}'. Primero escribe una copia de preservación verificada junto a la tienda (<store>.preservation-<time>), luego la copia, y nunca cambia la tienda. <output>.report.json nombra lo que el esquema 5 no puede contener, como la atribución de registros, los tokens de borrado, la evidencia de reclamaciones y el estado de captura, y el historial de diario de la copia se reemplaza por una entrada de línea base. Apunta 0.41.0 solo a la copia: dado una tienda SQLite de esquema 7, 0.41.0 puede establecer el modo de diario del archivo antes de rechazarla.
• Lo que 0.41.0 no tiene. 0.41.0 no tiene ninguna de las funciones de aislamiento de proyectos o registros de eliminación de esta compilación: allí, una lectura que no nombra un proyecto devuelve los registros de cada proyecto, y restaurar una copia de seguridad tomada antes de una purga trae de vuelta el material purgado.
• Hooks, captura, entrega y extracción. 0.41.0 no tiene comandos de hook, captura, entrega o extracción. Antes de cambiar a él, ejecuta con esta compilación shadowgraph deactivate extraction, shadowgraph deactivate capture, shadowgraph deactivate delivery, shadowgraph uninstall-hooks --capture y shadowgraph uninstall-hooks, y verifica que la limpieza de extracción no informó deferred (consulta desactivar, desinstalar y recuperar).

Comentarios y soporte

Los comentarios sobre la Vista Previa Técnica son el punto de este lanzamiento. Por favor, cuéntanos cuando algo falle.

Durante la vista previa, estos informes son los más valiosos:

• Problemas de instalación — cualquier cosa entre npm install --global y un doctor verde.
• Compatibilidad con clientes MCP — qué cliente, qué modo y qué descubrió o no.
• Utilidad de la memoria — ¿el contexto recordado realmente cambió lo que hizo tu agente?
• Flujos de trabajo confusos — donde la documentación o una forma de comando te enviaron por el camino equivocado.
• Casos de uso de memoria de decisiones faltantes — decisiones que querías almacenar y no pudiste.
• Rendimiento — donde se sintió lento, y aproximadamente qué tan grande era la tienda.

ShadowGraph no tiene telemetría y no recopila nada automáticamente, así que un informe tuyo es la única señal que existe. Al pegar salida, redacta cualquier cosa privada: el contenido de decisiones y memoria son tus datos, y la salida de shadowgraph doctor suele ser suficiente.

Documentación

Verificaciones

npm run check
npm run test:performance
npm test
npm run check:integrations
npm run check:mcp
npm audit --omit=dev
npm run check:package
npm run smoke:package

GitHub Actions cubre Ubuntu y Windows en Node 20, 22 y 24. En cada trabajo, los casos de rendimiento del presupuesto de entrega se ejecutan en su propio paso obligatorio antes de la suite. Las compuertas de SQLite se ejecutan solo donde node:sqlite existe. El estricto Inspector MCP oficial ejecuta compuertas completas y compactas, la compuerta fijada de Glama mcp-proxy@6.4.3 prueba la revisión que este servidor negocia con él y que la lista de herramientas llega a un escáner HTTP sin cambios, y la prueba de humo del paquete se ejecuta desde una instalación limpia real en cada celda de la matriz.

Licencia

MIT. Consulta LICENSE.