Rekindle

npx rekindle init

Rekindle é um mecanismo de continuidade MCP que resolve orientação de sessão, não apenas armazenamento. Oriente no início da sessão, capture no final da sessão, sobreviva à compactação no meio da sessão. Tudo local, tudo SQLite, zero chaves de API.

v0.3.3 — metadados MCP consistentes com a versão e documentação do pacote, sobre o instalador de entrega de início de sessão com um comando do v0.3.2. Notas de versão

Início Rápido

Requer Node.js 20 ou mais recente.

npx rekindle init

Isso cria .rekindle/ no seu projeto com um banco de dados SQLite, modelo de identidade, diretório de capturas e diretório de transcrições. Em seguida, adicione a configuração do servidor MCP para o seu cliente:

{
  "mcpServers": {
    "rekindle": {
      "command": "npx",
      "args": ["-y", "rekindle"]
    }
  }
}

npx rekindle setup-hooks

npx rekindle setup-delivery

{
  "mcpServers": {
    "rekindle": {
      "command": "npx",
      "args": ["-y", "rekindle"]
    }
  }
}

{
  "mcpServers": {
    "rekindle": {
      "command": "npx",
      "args": ["-y", "rekindle"]
    }
  }
}

Em seguida, preencha .rekindle/identity.md e cole as instruções de inicialização no CLAUDE.md do seu projeto.

A sessão 1 armazena. A sessão 2 lembra. A sessão 10 antecipa.

O Problema (43 Sessões de Dados)

Ao longo de 43 sessões, medimos o que um assistente de IA falhou em carregar no início da sessão:

As ferramentas de memória existentes (Mem0, Letta, Zep) otimizam a precisão da recuperação: a IA consegue encontrar o que armazenou? Isso é necessário, mas não suficiente. Nenhuma delas aborda se a IA carregou o contexto certo para esta sessão, ou se ela consegue detectar o que perdeu.

Rekindle resolve a orientação de sessão: carregar identidade, contexto recente, saúde da memória e avisos de contexto ausente antes de o assistente começar a trabalhar.

Veja docs/gap-analysis.md para o conjunto completo de dados da pesquisa.

O Que Ele Faz

Inicialização: oriente no início da sessão

boot_report executa um pipeline de orientação antes de qualquer trabalho começar:

boot_report
  +-- Read identity document (who am I working with?)
  +-- Scan memory stats (what do I know?)
  +-- Find latest checkpoint (where did we leave off?)
  +-- Read last transcript (what actually happened?)
  +-- Surface open loops (what needs follow-up?)
  +-- Surface PreCompact captures (what survived compaction?)
  +-- Detect gaps (what am I missing?)
  +-- Calculate orientation score (how oriented am I?)
  --> "Carrying forward: [context loaded, gaps identified, score: 80/100]"

Sobreviva ao Meio Longo: captura PreCompact (v0.3)

A compactação no meio da sessão destrói cadeias de raciocínio, abordagens falhas, textura relacional e tom. O hook PreCompact dispara automaticamente antes da compactação e salva o que de outra forma seria perdido:

PreCompact hook fires
  +-- Parse JSONL transcript (last N messages)
  +-- Write raw Markdown capture (.rekindle/captures/)
  +-- Write structured JSON snapshot (decisions, open loops, files)
  +-- Update manifest for cheap listing
  --> boot_report surfaces captures on next session start
  --> end_session warns if captures exist but weren't reviewed

Três modos de leitura controlam o custo de tokens:

• summary — um parágrafo, barato
• structured — decisões/loops/avisos, moderado
• raw — trecho completo da transcrição, caro (somente quando necessário)

Captura: feche o ciclo no final da sessão

end_session armazena registros estruturados de continuidade — não apenas um resumo:

Todos os registros são armazenados com metadados type, source e session_id. A próxima boot_report carrega o checkpoint automaticamente.

Entre sessões: pesquise e gerencie

Categorias: preference lesson context relationship general

Por que não apenas CLAUDE.md?

Um arquivo estático é passivo. Sua IA o lê, mas não pode pesquisá-lo, classificá-lo, rastrear o que foi recuperado ou dizer o que está faltando. Rekindle adiciona:

• Pesquisa — texto completo com classificação ponderada por importância
• Estrutura — escopo por categoria e projeto entre memórias
• Orientação — carregamento proativo de contexto na inicialização, não apenas recuperação sob demanda
• Detecção de lacunas — sinaliza identidade ausente, categorias vazias, dados desatualizados
• Pontuação — checklist transparente para você saber quão orientada a IA está
• Captura de sessão — fechamento estruturado com checkpoints, decisões e loops abertos
• Sobrevivência à compactação — capturas PreCompact preservam o que os resumos achatam

Destaques das Versões

v0.3.3

• Metadados de protocolo consistentes com a versão — a resposta de inicialização do MCP deriva sua versão dos metadados do pacote enviado, evitando desvio de versão de lançamento
• Precisão da página do pacote — o README enviado ao npm identifica a versão atual antes de a tag e o pacote serem criados
• 148 testes automatizados, além de uma verificação de artefato empacotado que compara os metadados do MCP com a versão do pacote instalado

v0.3.2

• Instalação de entrega com um comando — npx rekindle setup-delivery (ou init --with-delivery) configura a adesão ao hook SessionStart: idempotente, preserva os hooks de outras ferramentas, recusa arquivos de configuração corrompidos
• 147 testes automatizados

v0.3.1 — "Five Measured Gates"

• Entrega no início da sessão — rekindle session-start emite um pacote de orientação orçado via hook SessionStart na inicialização, retomada, /clear e /compact
• Pacotes orçados, recibos verdadeiros — pacotes limitam-se a 8.000 bytes UTF-8 válidos com um marcador de truncamento dentro do pacote; recibos atestam apenas a emissão e nunca afirmam visibilidade do modelo
• Armazenamento seguro para desktop — a raiz de armazenamento nunca deriva do ponto de spawn (Claude Desktop inicia servidores MCP em /); ordem de resolução explícita, falha ruidosa
• Orientação de canal duplo — a orientação do fluxo de trabalho viaja tanto nas descrições de ferramentas quanto nas instruções do MCP, deriva estruturalmente impossível
• Adaptador Cursor — session-start --client cursor com análise de stdin na lista de permissões; e-mail e caminhos de workspace nunca chegam aos recibos
• Medido, não presumido — cada afirmação acima é respaldada por uma medição publicada (evidência, resultados de spike)

v0.3.0 — "Survive the Long Middle" adicionou o sistema de captura PreCompact, loops abertos e rastreamento de revisão — notas de versão v0.3.0

Comandos CLI

Instalar a partir do Código Fonte

git clone https://github.com/Skitchy/rekindle.git
cd rekindle
npm install
npm run build
node dist/init/cli.js init

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "auto",
        "hooks": [
          {
            "type": "command",
            "command": "npx rekindle precompact-capture",
            "timeout": 60
          }
        ]
      },
      {
        "matcher": "manual",
        "hooks": [
          {
            "type": "command",
            "command": "npx rekindle precompact-capture",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Compatibilidade

"Entrega completa" significa que o pacote de orientação chega automaticamente nos limites da sessão e o modelo demonstravelmente o vê — medido com sondas canário tanto na camada de recebimento quanto na camada do modelo, não presumido. Detalhes e evidências: resultados de spike de compatibilidade.

Claude Code: orientação no início da sessão (opcional)

npx rekindle setup-delivery

escreve isto em .claude/settings.local.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          { "type": "command", "command": "npx rekindle session-start", "timeout": 60 }
        ]
      }
    ]
  }
}

O pacote é limitado a 8.000 bytes UTF-8 válidos — medido: quando a saída do hook excede o limite do host, o modelo vê apenas a porção inicial, sem nenhum erro exibido. Se seções forem descartadas para caber no orçamento, um marcador dentro do pacote indica isso, e o recibo em .rekindle/receipts/session-start.jsonl registra exatamente o que foi emitido, sem nunca afirmar que o modelo viu.

Cursor: orientação de início de sessão (opt-in)

O sistema de hooks do Cursor pode entregar o pacote de orientação orçado no início da sessão, medido no spike de compatibilidade v0.3.1. A configuração é manual e opt-in — o Rekindle nunca instala hooks sem ser solicitado. Adicione a .cursor/hooks.json no seu projeto:

{
  "version": 1,
  "hooks": {
    "sessionStart": [ { "command": "rekindle session-start --client cursor" } ]
  }
}

Privacidade: o payload do hook do Cursor inclui seu e-mail de conta e caminhos do workspace. O adaptador trata esse payload como pessoal por padrão: ele extrai apenas o ID da sessão e a raiz do workspace (usados em processo para resolução de armazenamento), e nem o payload bruto, nem o e-mail, nem qualquer caminho são gravados em recibos ou qualquer outro artefato. Agentes em segundo plano são ignorados por padrão (com recibo verdadeiro); opte com REKINDLE_ORIENT_BACKGROUND_AGENTS=1.

rekindle/
  src/
    index.ts          MCP server entry point
    server.ts         Server setup, tool registration (10 tools)
    storage/
      sqlite.ts       SQLite + FTS5, schema migration, sessions
    orientation/
      types.ts        OrientationResult, Gap, ScoreItem
      GapDetector.ts  Structural gap detection (8 codes)
      Scorer.ts       Orientation scoring (6 criteria, 100pts)
      OrientationService.ts   Orchestrator
      OrientationRenderer.ts  Markdown + JSON output
    captures/
      types.ts        CaptureEntry, StructuredSnapshot, HookInput
      CaptureManager.ts   Parse, capture, list, read, review tracking
      discover-transcript.ts  Auto-discover session transcripts
      precompact-capture.ts   CLI hook entry point
      capture-now.ts          Manual capture CLI
    tools/
      boot-report.ts  Orientation + open loops + capture awareness
      end-session.ts  Structured session close + capture warning
      list-captures.ts  List PreCompact captures
      read-capture.ts   Read captures in 3 modes
      capture-now.ts    Model-triggered manual capture
      store.ts search.ts list.ts delete.ts update.ts
    delivery/
      budget.ts       8000-byte UTF-8 packet construction, truncation marker
      receipts.ts     Emission receipts (never claim model visibility)
      session-start.ts SessionStart hook adapter
      cursor.ts       Cursor hook adapter (privacy-whitelisted stdin)
      guidance.ts     Canonical workflow guidance, both channels
    init/
      cli.ts scaffold.ts setup-hooks.ts setup-delivery.ts templates/

Testes

npm test

148 testes: CRUD de armazenamento + ranqueamento FTS5, domínio de orientação (detecção de lacunas, pontuação, serviço, renderização), gerenciador de captura (análise, limites, rastreamento de revisão, formatação), entrega (orçamento de pacote, recibos, canais de orientação, sentinelas de privacidade do Cursor), configuração de hooks para ambos os hooks (esquema, idempotência, recusa de corrupção) e integração MCP (todas as 10 ferramentas mais metadados de servidor derivados do pacote).

Roadmap

v0.4: "Pensa em redes" — Ativação por propagação, busca semântica via embeddings, ferramentas de análise de lacunas, harness de avaliação.

Licença

MIT