ShadowGraph

ShadowGraph

Memória de decisão local-first para agentes de IA. O ShadowGraph lembra o que um agente decidiu, o que rejeitou, por que rejeitou e quando essa decisão deve ser reconsiderada.

Status: Prévia Técnica / Acesso Antecipado. Instale pelo GitHub — não está no npm. Veja Limitações e status da Prévia Técnica.

Por que isso importa

A memória de chat lembra da conversa. Ela perde a decisão.

Pergunte a um agente três meses depois por que o projeto usa SQLite e a parte útil já se foi:

• A escolha pode sobreviver em um resumo. A alternativa rejeitada e o motivo da rejeição não sobrevivem.
• Um fato muda — a implantação passa de usuário único para multi-usuário — e nada reabre a decisão.
• A mesma abordagem falha de novo, porque a tentativa fracassada nunca foi registrada como uma tentativa fracassada.

O ShadowGraph armazena esse raciocínio como dados estruturados e inspecionáveis, em vez de prosa: o que foi escolhido, o que foi rejeitado, o porquê, as premissas e evidências por trás disso, tentativas fracassadas, resultados, procedência, histórico de confiança e as condições que devem acionar um repensar.

A promessa é deliberadamente estreita: decisões importantes de IA devem sobreviver às sessões e permanecer explicáveis, revisáveis e reconsideráveis.

Para quem é: desenvolvedores que constroem agentes em MCP, uma CLI ou uma API HTTP local que precisam que decisões consequentes sobrevivam a uma sessão. É um armazenamento de decisões, e ele mantém o armazenamento na sua máquina; os dados saem da máquina apenas por meio de opt-ins que você ativa (veja Local-first e privacidade).

Início Rápido — 5 minutos

Requisitos

• Node.js 20+ (o backend SQLite opcional precisa do Node 22.5+ para node:sqlite)
• Sem dependências npm em tempo de execução, sem etapa de build, sem conta, sem chamadas de rede

1. Instalar

O ShadowGraph não é publicado no npm. Durante a Prévia Técnica, instale-o a partir deste repositório. Uma instalação global coloca shadowgraph no seu PATH, que é o que os clientes MCP precisam:

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

Isso instala o branch main atual: o build de desenvolvimento 0.42.0-dev.0, mais novo que o 0.41.0 da Prévia Técnica e não é um release. Para instalar a Prévia Técnica, use github:LiLara-AI/shadowgraph#v0.41.0. Antes de mover um armazenamento entre os dois, leia Movendo entre 0.41.0 e 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 não funciona e falha com E404. O pacote é private: true e não publicado, e o nome no registro não está reservado. Este README mudará se a publicação for algum dia aprovada.

2. Argumentos JSON e seu shell

Todo comando do ShadowGraph recebe um único argumento JSON, então as aspas dependem do seu shell. Escolha a linha do shell que você está realmente usando — este é o motivo mais comum de um primeiro comando falhar:

Os exemplos abaixo usam a forma do bash. Se um comando falhar no seu shell, por favor, reporte.

3. Inicializar um armazenamento

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

setup cria .shadowgraph/data.json no diretório atual, então execute-o onde você quer que o armazenamento fique. Ele nunca reescreve um armazenamento existente. doctor então verifica a compatibilidade do Node, a legibilidade e gravação do armazenamento, a validade do grafo e o ponto de entrada do MCP.

Execute setup antes de doctor: em um diretório novo, doctor reporta Storage is not initialized e sai com 1 até que um armazenamento exista. Isso é esperado, não uma instalação falha.

4. Registre uma decisão, reinicie e recupere-a

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 é executado em um novo processo e reabre o armazenamento do disco, então o resultado de search volta através de uma reinicialização real, não de um estado em memória. Agora você tem uma decisão que carrega sua alternativa rejeitada, o motivo da rejeição e a condição que deve reabri-la.

A demonstração: uma decisão que se reabre

Este é o ponto central do ShadowGraph, em três comandos. Continue no mesmo diretório.

A decisão está resolvida, então não há nada para reconsiderar ainda:

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

Agora o mundo muda. A implantação se torna multi-usuário:

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

Reinicie e pergunte novamente — passando apenas o projeto, nunca o fato que acionou:

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

O resultado, resumido aos primeiros campos do seu único item:

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

O ShadowGraph leu o fato armazenado, comparou-o com a regra salva com a decisão e trouxe à tona a alternativa que havia sido rejeitada por um motivo que não se sustenta mais. O item completo também carrega violatedConditions (cada um nomeia o fato armazenado que correspondeu como evidência) e o sinal de revisão que registrou, e o resultado termina com um bloco completeness como o primeiro. Seus IDs e horários serão diferentes.

Isso é memória de decisão: não "sobre o que conversamos", mas "o que decidimos, o que descartamos, e isso ainda se sustenta?"

Para a mesma história via MCP, a API HTTP e a API JavaScript — além de registrar tentativas fracassadas e resultados — veja a demonstração de memória de decisão.

Capacidades principais

Memória de decisão. As decisões carregam a abordagem escolhida, alternativas rejeitadas com seus motivos, premissas, evidências e regras estruturadas de reopenWhen. Os resultados (bem-sucedido, misto, fracassado, desconhecido) alimentam a confiança.

Reconsideração. review() avalia regras de reabertura contra fatos armazenados, então funciona após uma reinicialização sem que o chamador reenvie o que mudou. Os sinais de revisão são persistidos e podem ser reconhecidos.

Memória de tentativas fracassadas. As tentativas registram a abordagem, o resultado, o ambiente e a lição, para que um agente possa descobrir que algo já foi tentado e por que não funcionou.

Procedência auditável. Cada afirmação carrega um sourceClass — agent_claimed, tool_observed, human_confirmed ou production_verified — que registra o que foi afirmado sobre a origem de uma observação, nunca prova disso. Entrada comum de ferramenta não pode criar verified; isso exige um verificador Ed25519 configurado separadamente.

Memória com escopo e recordação temporal. remember() / recall() armazenam preferências, perfis, metas, instruções, procedimentos, episódios e notas sob um projeto, mais userId / agentId / runId opcionais. Fatos, memórias e relações são bi-temporais, então você pode perguntar o que era verdade asOf um momento passado. A recuperação funde sinais lexicais, vetoriais, de distância no grafo e temporais, e declara quais sinais estavam indisponíveis em vez de degradar silenciosamente.

Isolamento de projeto e escopo. Toda gravação precisa de um projeto, uma vinculação de espaço de trabalho (shadowgraph bind), ou um id de origem de captura: uma gravação sem nenhum deles é recusada (write_scope_unresolved) em vez de cair em um bucket default compartilhado, e default é um nome de projeto comum. search, retrieve, recall, context e traverse leem apenas os registros do projeto selecionado, e a expansão do grafo que fazem permanece nesse projeto; sem projeto selecionado, retornam nada, nunca todos os projetos e nunca um bucket default compartilhado. Um id fora do projeto selecionado — ou um que não existe — recebe a mesma resposta: nenhum registro. Uma nova relação une dois registros de um projeto (link precisa desse projeto), e uma entre projetos é recusada como um endpoint ausente; relações armazenadas entre projetos antes são mantidas, e nenhuma leitura as segue. O diário, stats, a saída de redact e a exportação pública (GET /records, list) leem da mesma forma. Uma mudança por id — um resultado, um status, evidência de confiança, uma substituição, uma verificação de fato, um reconhecimento de revisão — muda apenas o que seu próprio projeto ou origem possui, e responde ao id de outro projeto exatamente como a um ausente. Salvar, backup e restauração ainda cobrem todo o armazenamento; a exportação pública e uma redação são leituras de um projeto e são recusadas como um armazenamento. Registros escritos antes do esquema 6 em default, ou sem projeto, não pertencem a nenhum projeto que um chamador possa nomear, então nenhuma leitura de projeto os retorna; o legacyAttributionReview() do kernel os lista para inspeção, cada um com seu estado legado e registro canônico, e não infere projeto para eles. Uma leitura sem projeto relata seu resultado vazio como incompleto (completeness.complete: false, com uma limitação de scoped_coverage), nunca como completo. As ferramentas MCP, rotas HTTP e verbos CLI passam o project do chamador (ou originId) para a mesma fronteira: um resultado, uma mudança de status ou um reconhecimento de revisão enviado com um muda apenas o que ele possui, e a mesma chamada sem um é recusada (write_scope_unresolved) igualmente para todo id; stats via HTTP (GET /stats?project=...) e a CLI contam apenas o conteúdo do projeto nomeado, e nada sem um. Acesso mais amplo é explícito e revogável: uma concessão de acesso que o proprietário emite em um terminal (issue-access) abre os projetos ou origens que nomeia para leituras explícitas que a apresentam, até que expire ou seja revogada. Não é compartilhamento apenas de lições, e a entrega automática de hooks nunca usa uma. Um nome de projeto, como um id de origem apresentado, é um seletor, não controle de acesso: qualquer chamador da CLI, MCP ou API HTTP que nomeie um explicitamente o lê. Registros legados são o que apenas uma concessão abre. Veja o contrato de transporte de acesso. Escopo omitido significa escopo todo-nulo. A purga é pré-visualizável, lógica por padrão e explicitamente irreversível no modo difícil.

Recuperação explicável. Os resultados expõem pontuações brutas, classificações e motivos, e toda resposta limitada declara seu total, páginas e escopo omitido. Nada é resumido silenciosamente.

Local-first e privacidade

Tudo é um arquivo local. O servidor HTTP vincula-se a 127.0.0.1 e rejeita origens de navegador não locais. Não há serviço em nuvem, conta, telemetria ou análise — o ShadowGraph não faz nenhuma solicitação de rede de saída, a menos que você configure uma explicitamente.

Os opt-ins que podem enviar dados para fora da máquina estão todos desativados por padrão:

• Embeddings. Nenhum endpoint está configurado. Um servidor compatível com OpenAI em localhost funciona uma vez configurado; um endpoint remoto adicionalmente requer SHADOWGRAPH_ALLOW_REMOTE_EMBEDDINGS=1, porque isso significa que memória e texto de consulta saem da sua máquina.
• Extração. A extração aprovada separadamente envia capturas redigidas elegíveis através da rota de assinatura de primeira parte do Claude suportada. Nenhuma chave de API, provedor alternativo, proxy ou fallback pago é suportado por este executor; o proprietário deve desativar o excesso de assinatura. A redação por padrão não pode garantir que todos os segredos sejam removidos. A extração é executada apenas no Windows, com Claude Code 2.1.288, ou com o binário perfilado Claude Code 2.1.292 e o recebimento de uma validação de host real aprovada dele (ShadowGraph verifica a identidade do recibo, não a validação em si); em qualquer outra plataforma, versão ou binário, é recusada. Veja extração e seus limites de host.
• Exportação Markdown. markdown-sync grava cópias em texto simples que você controla. ShadowGraph não pode encontrar ou excluir essas cópias posteriormente — veja Armazenamento, backup e exclusão.
• Entrega ao host. Inerte a menos que você instale os hooks e ative a entrega para um armazenamento. Uma vez ativo, os registros que ele entrega (valores em formato de credencial redigidos primeiro) tornam-se parte da transcrição da sessão do Claude Code e do que o modelo recebe, como qualquer contexto; ShadowGraph não pode removê-los da transcrição. Veja o guia de integrações.

Captura, extração e entrega exigem seus procedimentos de ativação separados. Uma vez ativos, a captura registra seus prompts, chamadas de ferramentas com sua entrada e saída, e o texto do assistente de sessões do Claude Code, redigido por padrão, em um armazenamento local privado. A captura usa o armazenamento externo inscrito; armazenamentos manuais existentes não são migrados automaticamente, e a entrega lê o único armazenamento que sua ativação fixa. Dados brutos elegíveis não citados expiram sob a política configurada mesmo quando em quarentena, enquanto experiência aceita e evidência citada necessária são protegidas. Dados brutos expirados podem não ser mais reextraídos.

Veja o mapa do ciclo de vida dos dados para alcance de exclusão, cópias retidas, poda explícita de Markdown e pisos de recuperação, e o ciclo de vida da experiência integrada para limites de correção, reprocessamento, reinício e desligamento.

Para uso local compartilhado, defina um token Bearer:

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

Em seguida, envie Authorization: Bearer use-a-random-token-at-least-16-characters com cada solicitação. Isso é defesa em profundidade para uma implantação local, não um modelo de segurança para internet pública. Veja SECURITY.md.

Interfaces

MCP

shadowgraph mcp

O modo compacto é recomendado: ele anuncia 16 ferramentas de fluxo de trabalho enquanto o grafo completo, memórias, fatos, alternativas e resultados permanecem armazenados com fidelidade total. O modo compacto é uma escolha de anúncio de ferramentas, não armazenamento com perdas.

SHADOWGRAPH_MCP_COMPACT=1 shadowgraph mcp

Os metadados das ferramentas seguem a revisão que initialize negocia: uma sessão negociada em 2025-03-26 também recebe anotações comportamentais, e uma em 2025-06-18 ou 2025-11-25 também recebe esquemas de saída e resultados estruturados, enquanto uma sessão em 2024-11-05 mantém os membros de ferramenta e resultados serializados que sempre teve. Uma solicitação para uma revisão que este servidor não implementa é respondida com 2025-11-25, a mais recente que ele implementa. Veja o guia de compatibilidade MCP para a tabela completa.

As 16 ferramentas compactas são 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 um cliente compacto possa limpar uma revisão que já pode ver, em vez de acumular sinais sem forma de reconhecê-los — e shadowgraph_reconsider, que lê a mesma avaliação como um veredito: revisão recomendada, inalterada, ou um humano deve olhar. shadowgraph_context é uma leitura que não persiste nada; shadowgraph_review_context persiste os sinais de revisão que considera devidos, e shadowgraph_expand expande uma linha de reivindicação para seu registro completo. O modo completo anuncia 35 — veja o guia de compatibilidade MCP para o inventário completo, cada revisão de protocolo e comportamento de cliente verificado. O modo completo inclui ferramentas do proprietário: backup para um caminho nomeado pelo chamador, restauração de um e purga. Seus shadowgraph_bind e shadowgraph_attribute apenas propõem: eles não mudam nada e retornam a entrada shadowgraph bind ou attribute que o proprietário executa e confirma em um terminal. Dê a um agente o modo compacto, a menos que você queira que ele tenha as ferramentas do proprietário (veja SECURITY.md).

Configuração de ferramentas de IA

Instale globalmente primeiro para que o cliente possa encontrar shadowgraph em seu PATH:

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

Claude Code (escopo do usuário):

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

Cursor (.cursor/mcp.json ou ~/.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

Formulários de arquivo para todos os quatro vivem em integrations/; npm run check:integrations os valida como arquivos, o que não é uma execução ao vivo de cada cliente. Defina um SHADOWGRAPH_FILE absoluto no ambiente do cliente quando um armazenamento deve ser compartilhado entre diretórios de trabalho.

CLI

Os comandos que você realmente usará:

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

Um painel somente leitura é servido em http://127.0.0.1:8787/dashboard. Ele fala apenas com a mesma origem local, e um token inserido lá é mantido apenas na memória da página — nunca em cookies, armazenamento local ou dados do 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' }));

A importação de especificador nu resolve quando ShadowGraph é uma dependência do seu projeto (npm install github:LiLara-AI/shadowgraph). Com uma instalação --global, use as superfícies CLI, HTTP ou MCP em vez disso, ou importe do caminho instalado.

Armazenamento, backup e exclusão

JSON é o padrão sem dependências e armazena um grafo versionado em .shadowgraph/data.json. Defina SHADOWGRAPH_FILE para realocá-lo. Defina SHADOWGRAPH_STORAGE=sqlite no Node 22.5+ para o adaptador relacional com suporte a WAL. Os armazenamentos são gravados no esquema 7; esquemas 1 a 6 permanecem legíveis, e downgrade bifurca uma cópia no esquema 5 (o padrão, que 0.41.0 lê) ou esquema 6 (que apenas builds intermediários não lançados leem), sem alterar o armazenamento.

Estado e diário são gravados em uma única operação atômica, cada salvamento e restauração para um destino compartilha uma cerca de bloqueio entre processos, e uma gravação obsoleta é rejeitada com um conflito de revisão em vez de ser silenciosamente perdida. backup tira um instantâneo consistente; restore valida a consistência do domínio e do diário antes de substituir o estado ativo, e reverte em caso de falha. Isso é segurança de reversão em nível de processo, não uma alegação de durabilidade contra falhas ou perda de energia. As garantias completas — tempos limite de bloqueio, recuperação de bloqueio obsoleto, aritmética de revisão e relatórios de artefatos de restauração — estão na referência da API e no contrato de restauração SQLite.

A exclusão é explícita e pré-visualizável:

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

A purga lógica (o padrão) remove o conteúdo do projeto da projeção ativa e mantém um esqueleto de purga auditável, sem payload. A purga física exclui entradas do diário, cria uma lacuna declarada e não pode ser desfeita.

A purga não pode excluir exportações Markdown externas. ShadowGraph não tem como encontrar cópias em texto simples em espaços de trabalho arbitrários, histórico do Git, sincronização em nuvem, backups ou mídia removível. Exclua-as separadamente. Backups, as cópias de preservação e downgrade que migrate e downgrade gravam, e os arquivos de recuperação que uma restauração interrompida deixa também podem reter material purgado ou expirado posteriormente; uma purga não os alcança (veja o mapa do ciclo de vida dos dados).

Limitações e status de Pré-visualização Técnica

A versão mais recente é a 0.41.0 Pré-visualização Técnica / Acesso Antecipado (tag v0.41.0). Não é Beta e não é estável. main carrega 0.42.0-dev.0, um build de desenvolvimento: não lançado, não estável, e seus critérios de aceitação não foram avaliados.

• As interfaces e o esquema de armazenamento ainda podem mudar. Não use para dados que você não possa reproduzir.
• Não está no npm. O pacote é deliberadamente private: true. A tag Git v0.41.0 e o Release do GitHub são autorizados pelo mantenedor para esta Prévia Técnica; a publicação no npm não é autorizada e não ocorreu.
• Nenhum benchmark comparativo foi medido. A infraestrutura de benchmark comparativo foi executada, mas nenhum braço foi medido porque nenhum endpoint comum local/gratuito de LLM e embedding estava disponível. Nenhuma alegação comparativa de desempenho, qualidade, tokens, custo ou "melhor" é suportada. O ShadowGraph não faz nenhuma alegação de ser mais rápido, mais barato, com menos tokens, mais preciso ou melhor do que qualquer outro sistema de memória. Consulte o relatório de benchmark.
• Status da revisão de segurança. Uma revisão de segurança independente assistida por IA do commit 4a5e076 (árvore 62c1918e) foi concluída em 30/08/2026 pelo Antigravity Assistant (Gemini 3.7 Flash), com resultado APROVADO e nenhuma descoberta não resolvida. Nenhuma auditoria de segurança de terceiros humana foi realizada. Consulte SECURITY.md. Essa revisão cobriu o commit 4a5e076, antes da tag v0.41.0. Nada adicionado desde então passou por revisão de segurança independente, incluindo escopo de projeto, concessões de acesso, registros de exclusão e restauração ciente de purga, migração de esquema 6 e 7 e downgrade, os hooks do Claude Code, captura automática, leitura e extração de transcrições.
• Nada é capturado ou extraído a menos que você ative, e não há sincronização hospedada. Sem a integração opcional do Claude Code, o ShadowGraph registra o que você diz para ele registrar. Com ela, a captura automática de sessões do Claude Code e a extração baseada em modelo permanecem inertes até que o proprietário as ative separadamente; a captura cobre apenas eventos declarados, com redação baseada em padrões (consulte o guia de integrações e extração).
• Captura e entrega cobrem um único armazenamento inscrito. A entrega lê o único armazenamento que sua ativação fixa, e a captura grava no armazenamento com o qual foi inscrita; outros armazenamentos que você usa manualmente não são entregues nem capturados, e não são migrados.
• Mantenedor único. Sem suporte pago, sem SLA de correção e sem programa de recompensas por bugs.

Movendo entre 0.41.0 e main

• Faça um backup antes de atualizar. shadowgraph backup [<file>] copia o armazenamento: um armazenamento JSON byte por byte, um armazenamento SQLite tabela por tabela. Um backup feito antes de esta versão salvar o armazenamento pela primeira vez ainda é um armazenamento de esquema 5 que a 0.41.0 abre. (Ao abrir um armazenamento SQLite, esta versão adiciona uma tabela própria a ele; a 0.41.0 ainda lê o armazenamento.) Uma vez que esta versão salvou o armazenamento, seus backups são armazenamentos de esquema 7; para usar um com a 0.41.0, restaure-o em um caminho novo com esta versão e crie uma cópia de esquema 5 como abaixo.
• Atualizando. Esta versão lê todos os armazenamentos que a 0.41.0 gravou (esquemas 1 a 5) e grava o esquema 7 no próximo salvamento. O que muda para você:
  • Uma gravação que não nomeia um projeto é recusada (write_scope_unresolved). Passe project, ou vincule o espaço de trabalho a um projeto com shadowgraph bind.
  • Registros que a 0.41.0 armazenou em default — gravados sem um projeto, que a 0.41.0 colocou lá, ou nomeando default — são material legado cujo proprietário esta versão trata como incerto: nenhuma leitura os retorna, nem mesmo com "project":"default". Eles não são excluídos. O legacyAttributionReview() da API JavaScript os lista, e shadowgraph attribute '{"ids":["<id>"],"targetProject":"<project>","reason":"<why>"}', que você confirma em um terminal, move registros nomeados para um projeto. Para anotar seus IDs antes de atualizar, execute o shadowgraph list da 0.41.0, que imprime todos os registros, e guarde os IDs daqueles com "project": "default". Se você depende de tais registros e não quer movê-los, permaneça na 0.41.0.
  • Alguns resultados mudaram de forma; por exemplo, review retorna {"items": [...], "completeness": {...}} em vez de um array. O changelog lista todas as mudanças que quebram compatibilidade.
• Voltando para a 0.41.0. A 0.41.0 lê apenas os esquemas 1 a 5 e recusa um armazenamento que esta versão salvou. Crie uma cópia de esquema 5 com shadowgraph downgrade '{"output":"<new file>"}'. Ela primeiro grava uma cópia de preservação verificada ao lado do armazenamento (<store>.preservation-<time>), depois a cópia, e nunca altera o armazenamento. <output>.report.json nomeia o que o esquema 5 não pode conter, como atribuição de registros, tokens de apagamento, evidência de reivindicação e estado de captura, e o histórico de diário da cópia é substituído por uma entrada de linha de base. Aponte a 0.41.0 apenas para a cópia: dado um armazenamento SQLite de esquema 7, a 0.41.0 pode definir o modo de diário do arquivo antes de recusá-lo.
• O que a 0.41.0 não tem. A 0.41.0 não tem nenhum dos isolamentos de projeto ou registros de exclusão desta versão: lá, uma leitura que não nomeia um projeto retorna os registros de todos os projetos, e restaurar um backup feito antes de uma purga traz o material purgado de volta.
• Hooks, captura, entrega e extração. A 0.41.0 não tem comandos de hook, captura, entrega ou extração. Antes de mudar para ela, execute com esta versão shadowgraph deactivate extraction, shadowgraph deactivate capture, shadowgraph deactivate delivery, shadowgraph uninstall-hooks --capture e shadowgraph uninstall-hooks, e verifique se a limpeza da extração não relatou deferred (consulte desativar, desinstalar e recuperar).

Feedback e suporte

O feedback da Prévia Técnica é o objetivo desta versão. Por favor, nos avise quando algo quebrar.

Durante a prévia, estes relatórios são os mais valiosos:

• Problemas de instalação — qualquer coisa entre npm install --global e um doctor verde.
• Compatibilidade com clientes MCP — qual cliente, qual modo, e o que ele descobriu ou não.
• Utilidade da memória — o contexto recuperado realmente mudou o que seu agente fez?
• Fluxos de trabalho confusos — onde a documentação ou um formato de comando te enviou pelo caminho errado.
• Casos de uso de memória de decisão ausentes — decisões que você queria armazenar e não conseguiu.
• Desempenho — onde pareceu lento, e aproximadamente quão grande era o armazenamento.

O ShadowGraph não tem telemetria e não coleta nada automaticamente, então um relatório seu é o único sinal que existe. Ao colar saída, redija qualquer coisa privada: o conteúdo de decisões e memórias é seu dado, e a saída de shadowgraph doctor geralmente é suficiente.

Documentação

Verificações

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

O GitHub Actions cobre Ubuntu e Windows no Node 20, 22 e 24. Em cada trabalho, os casos de desempenho de orçamento de entrega são executados em sua própria etapa obrigatória antes da suíte. As portas SQLite são executadas apenas onde node:sqlite existe. O inspetor MCP oficial estrito executa portas completas e compactas, a porta fixada do Glama mcp-proxy@6.4.3 prova a revisão que este servidor negocia com ele e que a lista de ferramentas alcança um scanner HTTP inalterada, e o teste de fumaça do pacote é executado a partir de uma instalação limpa real em cada célula da matriz.

Licença

MIT. Consulte LICENSE.