ShadowGraph

ShadowGraph

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

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 multiusuario — 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 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, no un almacén de transcripciones, y mantiene todo en tu máquina.

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

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 es private: true y no está publicado, y el nombre del registro no está reservado. Este README cambiará si se aprueba la publicación.

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. Las tres están probadas en cada comando de este README.

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 de MCP.

Ejecuta setup antes de doctor: en un directorio nuevo, doctor informa Storage is not initialized y sale con 1 hasta que exista un almacén. Eso es lo 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"}'

[]

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"}'

[
  {
    "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. Tus IDs de decisión serán diferentes; nada más lo es.

Eso es memoria de decisiones: no "de qué hablamos", sino "qué decidimos, qué descartamos y ¿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, objetivos, 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 en 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 proyecto y alcance. Proyecto y alcance omitidos significan el proyecto default y alcance todo-nulo — nunca todos los proyectos o todos los usuarios. La purga es previsualizable, lógica por defecto y explícitamente irreversible en modo estricto.

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

Local-first 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 realiza ninguna solicitud de red saliente a menos que configures una explícitamente.

Las dos opciones que pueden enviar datos fuera de la máquina están 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.
• 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, copia de seguridad y eliminación.

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 12 herramientas de flujo de trabajo mientras el grafo completo, recuerdos, hechos, alternativas y resultados permanecen almacenados con fidelidad total. El modo compacto es una elección de anuncio de herramientas, no un almacenamiento con pérdida.

SHADOWGRAPH_MCP_COMPACT=1 shadowgraph mcp

Las 12 herramientas compactas son shadowgraph_context, shadowgraph_remember, shadowgraph_recall, shadowgraph_record_decision, shadowgraph_record_attempt, shadowgraph_record_fact, shadowgraph_record_outcome, shadowgraph_retrieve, shadowgraph_search, shadowgraph_review, shadowgraph_validate y shadowgraph_maintain. El modo completo anuncia 27 — consulta la guía de compatibilidad MCP para el inventario completo, ambas revisiones de protocolo y el comportamiento verificado del cliente.

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 (alcance 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 verificados para los cuatro viven en integrations/. 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 '{"solution":"Rewrite everything","result":"Regression"}'
shadowgraph outcome '{"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 control 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 con 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, copia 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. Las exportaciones actuales usan el esquema 5; los esquemas 1 a 4 siguen siendo importables.

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 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 opción predeterminada) elimina el contenido del proyecto de la proyección en vivo y conserva un esqueleto de purga auditable y sin carga útil. La purga física elimina definitivamente 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. Elimínelas por separado.

Limitaciones y estado de Vista Previa Técnica

ShadowGraph 0.40.0 es una versión de Vista Previa Técnica / Acceso Anticipado. No es Beta ni estable.

• Las interfaces y el esquema de almacenamiento pueden cambiar. No lo use para datos que no pueda reproducir.
• No está en npm. El paquete está deliberadamente en private: true. No se ha creado ninguna publicación en npm, etiqueta de Git ni versión de GitHub, y ninguna está autorizada.
• No se ha medido ningún benchmark comparativo. Se ejecutó la infraestructura de benchmark comparativo, pero no se midió ningún brazo porque no había un endpoint común de LLM y embeddings local/gratuito 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 menos tokens, más preciso o mejor que cualquier otro sistema de memoria. Consulte el informe de benchmark.
• Estado de 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 de APROBADO y sin hallazgos sin resolver. No se ha realizado ninguna auditoría de seguridad humana de terceros. Consulte SECURITY.md.
• Sin extractor predeterminado, vigilante en segundo plano ni sincronización alojada. ShadowGraph registra lo que usted le indica que registre.
• Mantenimiento de una sola persona. Sin soporte de pago, sin SLA de parches y sin programa de recompensas por errores.

Comentarios y soporte

Los comentarios de la Vista Previa Técnica son el propósito de esta versión. Por favor, avísenos 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 recuperado realmente cambió lo que hizo su agente?
• Flujos de trabajo confusos — dónde la documentación o una forma de comando lo desviaron.
• Casos de uso faltantes de memoria de decisiones — decisiones que quería almacenar y no pudo.
• Rendimiento — dónde se sintió lento y aproximadamente qué tan grande era el almacén.

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

Documentación

Verificaciones

npm run check
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. Las compuertas de SQLite se ejecutan solo donde existe node:sqlite. El Inspector MCP oficial estricto ejecuta compuertas completas y compactas, y la prueba de humo del paquete se ejecuta desde una instalación limpia real en cada celda de la matriz.

Licencia

MIT. Consulte LICENSE.