Rekindle

Rekindle

For Claude Code users who lose time re-explaining project context every session.

npx rekindle init

Your AI forgets everything between sessions. Rekindle fixes that.

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:

Add to ~/.claude.json:

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

Enable PreCompact protection (captures context before mid-session compaction):

npx rekindle setup-hooks

Enable session-start orientation delivery — the budgeted orientation packet arrives automatically at startup, resume, /clear, and /compact, so the model re-orients at every context boundary without being asked:

npx rekindle setup-delivery

Both hooks are opt-in; plain init never installs either. npx rekindle init --with-hooks --with-delivery does everything in one line.

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

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

Add to .cursor/mcp.json in your project root:

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

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

The setup-hooks command writes this to .claude/settings.local.json:

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

The hook receives session context on stdin (session_id, transcript_path, cwd, hook_event_name) and writes captures to .rekindle/captures/.

Storage root resolution. All Rekindle entry points (server, PreCompact hook) resolve the directory holding .rekindle/ through one rule, in order:

1. REKINDLE_BASE_DIR, if set — explicit always wins
2. Derived from REKINDLE_DB_PATH, when it points at a canonical <base>/.rekindle/db/ layout
3. An existing .rekindle/ in the current working directory (never when cwd is the filesystem root)
4. An existing .rekindle/ in your home directory
5. Otherwise: your home directory — never the spawn point

Rules 3 and 5 exist because some hosts (e.g. Claude Desktop) spawn MCP servers at cwd=/; a spawn point is not a storage location. If storage cannot be created, the server exits with a message naming the fix instead of a stack trace.

…