kindling-plugins

Kindling

Local memory and continuity engine for AI-assisted development

Kindling captures what happens during AI-assisted development — tool calls, diffs, commands, errors — and makes it retrievable across sessions. All data stays local in embedded SQLite.

Quick Start: Claude Code

The fastest way to use Kindling — automatic memory for every Claude Code session.

# Install and set up in one step
curl -fsSL https://raw.githubusercontent.com/EddaCraft/kindling/main/install.sh | sh

# Or with npx (no global install)
npx @eddacraft/kindling-cli init --claude-code

That's it. Kindling now captures your Claude Code sessions automatically — tool calls, file edits, commands, errors — all searchable across sessions.

Manual setup: If you prefer to configure hooks yourself, add to .claude/settings.json:

{
  "hooks": {
    "SessionStart": [{ "type": "command", "command": "kindling-hook session-start" }],
    "PostToolUse": [{ "type": "command", "command": "kindling-hook post-tool-use" }],
    "Stop": [{ "type": "command", "command": "kindling-hook stop" }]
  }
}

Install

Node.js >= 20 required. Prebuilt binaries ship for Linux (glibc), macOS (Intel + Apple Silicon), and Windows (x64).

# Recommended: one-line installer (installs CLI + Claude Code plugin)
curl -fsSL https://raw.githubusercontent.com/EddaCraft/kindling/main/install.sh | sh

# Or install with your preferred package manager
npm install -g @eddacraft/kindling-cli    # CLI (global)
npm install @eddacraft/kindling            # Library (project-local)

pnpm add -g @eddacraft/kindling-cli
pnpm add @eddacraft/kindling

yarn global add @eddacraft/kindling-cli
yarn add @eddacraft/kindling

bun add -g @eddacraft/kindling-cli
bun add @eddacraft/kindling

Platform Notes

If prebuilt binaries aren't available for your platform

Kindling uses better-sqlite3 which needs a C++ compiler to build from source:

• Debian/Ubuntu: sudo apt-get install build-essential python3
• Fedora/RHEL: sudo dnf groupinstall "Development Tools"
• Alpine (musl): apk add build-base python3
• macOS: xcode-select --install
• Windows (Admin): npm install -g windows-build-tools

CLI Usage

The CLI is both a reader and a writer — you can capture observations manually, not just search for them.

# Initialize Kindling (creates database, optionally sets up Claude Code)
kindling init
kindling init --claude-code

# --- Write: capture context from the command line ---

# Log an observation directly
kindling log "JWT tokens expire after 15 minutes, not 1 hour"
kindling log --kind error "segfault in auth middleware after upgrade"

# Open/close capsules for manual sessions
kindling capsule open --intent "investigating memory leak" --repo ./my-project
kindling capsule close cap_abc123 --summary "root cause: unbounded cache in SessionStore"

# --- Read: search and inspect your memory ---

# Search across all captured context
kindling search "authentication error"
kindling search "auth" --session session-123 --repo ./my-project

# List entities
kindling list capsules
kindling list capsules --status open
kindling list observations --kind error

# Show database status
kindling status

# Pin important findings (always returned first in searches)
kindling pin observation obs_abc123 --note "Root cause identified"
kindling pin observation obs_abc123 --ttl 7d

# Inspect details
kindling inspect observation obs_abc123
kindling inspect capsule cap_xyz789

# Export / import
kindling export ./backup.json
kindling import ./backup.json

# Start API server (for multi-agent access)
kindling serve --port 3000

How It Works

Kindling organizes memory into two layers:

Observations — atomic units of captured context (tool calls, commands, file diffs, errors, messages). These flow in automatically from adapters or manually via the CLI.

Capsules — bounded groups of observations (a session, a workflow run). Each capsule has an intent, a lifecycle (open/close), and a summary.

When you search, Kindling returns results in three tiers:

1. Pins — user-marked priority items (always first, non-evictable)
2. Current Summary — active session context
3. Provider Hits — ranked FTS results with provenance ("why was this returned?")

Adapters

Kindling captures context automatically through adapters: