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.5.0: a user card, one Markdown file about you that any agent can read, so a new agent starts out knowing how you work. Plus fixes for transcript discovery, capture tagging and identity scoring. Release notes

Quick Start

Requires Node.js 22 or newer.

npx rekindle init

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

Claude Code

One command registers the server:

claude mcp add rekindle -- npx -y rekindle

Or add it to ~/.claude.json by hand:

{

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

Without --global, both commands write the project-local .claude/settings.local.json, so the hooks run only for sessions started in that directory. With --global, they write the user-scope ~/.claude/settings.json, which Claude Code applies in every project on the machine; register the server at the same scope so it is present wherever the hooks fire: claude mcp add --scope user rekindle -- npx -y rekindle (plain claude mcp add is local to the current project).

Session-start delivery resolves the hook's real working directory through .rekindle/projects.json. Exact roots match by default; nested directories inherit only when an entry sets "include_descendants": true. An unmapped or ambiguous workspace is reported as UNKNOWN PROJECT and never receives a checkpoint or context record from another project. REKINDLE_PROJECT remains an explicit override, and receipts record which resolution rule won.

.rekindle/policy.json controls transcript handling, the startup byte budget, and mandatory versus optional packet sections. Mandatory sections are atomic: if they do not fit, Rekindle emits a bounded failure manifest instead of a partial anchor. Optional sections are omitted whole and recorded in the receipt. Set "transcript_mode": "excluded" to prevent SessionStart from reading transcript files or paths and to mark transcript coverage N/A in the orientation score. Set "background_writes_allowed": false to make the automatic PreCompact hook exit without creating a capture; manual capture remains a separate, explicit action.

Claude Desktop

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

{

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

</details>

Cursor

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

{

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

</details>

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

Carry you between agents: the user card (v0.5)

identity.md tells the agent who *it* is. The user card tells any agent who *you* are: how to talk to you, your boundaries, your projects, what to avoid. It's one plain Markdown file that you own and edit; agents suggest changes, you decide.

Start one from the template:

npx rekindle card template ~/user-card.md     # never overwrites an existing file

Or draft one from what your agent already knows, review it, and save what you accept as your card:

mkdir -p ~/card-draft

npx rekindle card compile --out ~/card-draft # writes card-draft.md and card-worksheet.md cp ~/card-draft/card-draft.md ~/user-card.md # after you've reviewed and edited the draft

Then point this store at it:

npx rekindle card path ~/user-card.md

card path only records where the card is. An agent receives the card through Rekindle's orientation output: the SessionStart delivery hook (npx rekindle setup-delivery) in Claude Code, the Cursor adapter, or a boot_report call from any other MCP client.

• Opt-in. If no card is configured, the card feature adds nothing: no card section and no user_card receipt field.
• Whole or nothing. With the default policy, the card is the first optional section after the required ones. If it doesn't fit the startup budget it's left out, never cut off partway.
• Diagnostics stay out of the packet. What happened to the card (included, dropped, missing, unreadable, empty) is recorded in the receipt's user_card field, which holds only the source and status, never the card text or path.
• `compile` drafts, you decide. It selects records whose type is preference or constraint, or whose category is preference (project-less by default, plus any projects you name, each project line dated), your identity file's "What I Know About My Person" section, and any reviewed files you pass with --from, which it copies verbatim. It reads at most 2,000 records, newest first. It never writes over your card. Its detection of conflicts, secrets and stale entries is incomplete, so the draft is a candidate list for you to review, not a cleaned card. Details.
• One card, many agents. Point every store you use at the same file. Agents that can't read your machine (cloud agents) need their own copy; see docs/user-card.md.
• Trust limit. Any agent with ordinary file access can edit the card file. Rekindle doesn't prevent that; keep the card somewhere you review.

REKINDLE_USER_CARD overrides the configured path; a blank value counts as unset.

---

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.5.0

• User card ([#32](ht