npx rekindle init

Rekindle is an MCP continuity engine that solves session orientation, not just storage. Orient at session start, capture at session end, survive mid-session compaction. All local, all SQLite, zero API keys.

v0.3.3 — version-consistent MCP metadata and package documentation, on top of v0.3.2's one-command session-start delivery installer. Release notes

Quick Start

Requires Node.js 20 or newer.

npx rekindle init

This creates .rekindle/ in your project with a SQLite database, identity template, captures directory, and transcript directory. Then add the MCP server config for your client:

{
  "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"]
    }
  }
}

Then fill in .rekindle/identity.md and paste the boot instructions into your project's CLAUDE.md.

Session 1 stores. Session 2 remembers. Session 10 anticipates.

The Problem (43 Sessions of Data)

Over 43 sessions, we measured what an AI assistant failed to load at session start:

Existing memory tools (Mem0, Letta, Zep) optimize for retrieval accuracy: can the AI find what it stored? That's necessary but not sufficient. None of them address whether the AI loaded the right context for this session, or whether it can detect what it missed.

Rekindle solves session orientation: loading identity, recent context, memory health, and missing-context warnings before the assistant starts work.

See docs/gap-analysis.md for the full research dataset.

What It Does

Boot: orient at session start

boot_report runs an orientation pipeline before any work begins:

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]"

Survive the Long Middle: PreCompact capture (v0.3)

Mid-session compaction destroys reasoning chains, failed approaches, relational texture, and tone. The PreCompact hook fires automatically before compaction and saves what would otherwise be lost:

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

Three read modes control token cost:

• summary — one paragraph, cheap
• structured — decisions/loops/warnings, moderate
• raw — full transcript excerpt, expensive (only when needed)

Capture: close the loop at session end

end_session stores structured continuity records — not just a summary:

All records stored with type, source, and session_id metadata. Next boot_report loads the checkpoint automatically.

Between sessions: search and manage

Categories: preference lesson context relationship general

Why not just CLAUDE.md?

A static file is passive. Your AI reads it, but it can't search it, rank it, track what's been retrieved, or tell you what's missing. Rekindle adds:

• Search — full-text with importance-weighted ranking
• Structure — category and project scoping across memories
• Orientation — proactive context loading at boot, not just on-demand retrieval
• Gap detection — flags missing identity, empty categories, stale data
• Scoring — transparent checklist so you know how oriented the AI is
• Session capture — structured close with checkpoints, decisions, and open loops
• Compaction survival — PreCompact captures preserve what summaries flatten

Release Highlights

v0.3.3

• Version-consistent protocol metadata — the MCP initialize response derives its version from the shipped package metadata, preventing release-version drift
• Package-page accuracy — the README shipped to npm identifies the current release before the tag and package are created
• 148 automated tests, plus a packed-artifact check that compares MCP metadata to the installed package version

v0.3.2

• One-command delivery install — npx rekindle setup-delivery (or init --with-delivery) configures the SessionStart hook opt-in: idempotent, preserves other tools' hooks, refuses corrupted settings files
• 147 automated tests

v0.3.1 — "Five Measured Gates"

• Session-start delivery — rekindle session-start emits a budgeted orientation packet via the SessionStart hook at startup, resume, /clear, and /compact
• Budgeted packets, truthful receipts — packets cap at 8,000 valid UTF-8 bytes with an in-packet truncation marker; receipts attest emission only and never claim model visibility
• Desktop-safe storage — storage root never derives from the spawn point (Claude Desktop spawns MCP servers at /); explicit resolution order, fail-loud
• Dual-channel guidance — workflow guidance rides both tool descriptions and MCP instructions, drift structurally impossible
• Cursor adapter — session-start --client cursor with whitelist stdin parsing; email and workspace paths never reach receipts
• Measured, not assumed — every claim above is backed by a published measurement (evidence, spike results)

v0.3.0 — "Survive the Long Middle" added the PreCompact capture system, open loops, and review tracking — v0.3.0 release notes

CLI Commands

Install from Source