kindling

Local memory for AI-assisted development

You switch sessions. Your AI starts from zero. kindling remembers what happened: tool calls, file edits, commands, errors, decisions, and pinned findings. Everything stays on your machine in SQLite. Search it later with deterministic, explainable results.

Full guide: docs.eddacraft.ai/kindling

Try it in 60 seconds

No Node.js or Rust required:

curl -fsSL https://raw.githubusercontent.com/eddacraft/kindling/main/install.sh | sh
kindling demo
kindling search "JWT"
kindling browse

kindling demo loads sample memory (a JWT auth debugging session). kindling browse opens a local HTML viewer. No adapter needed to see how it works.

Terminal demo: run ./scripts/record-demo.sh, or record with asciinema rec -c "./scripts/record-demo.sh" docs/assets/kindling-demo.cast and embed the cast in this README.

Integrations

Tool	Status	How
Plain CLI	Supported	kindling log, search, browse, demo
Claude Code	Supported	Built-in hooks; plugin
VS Code / Cursor / Windsurf	Supported	VSIX: Cursor and Windsurf quickstart
OpenCode	Supported	kindling-adapter-opencode (from source)
PocketFlow	Supported	kindling-adapter-pocketflow (from source)
Rust SDK	Supported	kindling-client
Node client	Supported	packages/kindling (from source)
Custom adapter	Supported	Cookbook · minimal example

Full matrix: docs/integrations.md. No Claude Code? Quickstart without Claude Code.

What you get

• Local-first: project memory lives in SQLite on your machine.
• Deterministic retrieval: pins, current summaries, and ranked hits return in a predictable order, with provenance.
• Works with your stack: CLI, Rust SDK, thin Node client, and adapters for popular editors and agents.

Quick start: Claude Code

Install the binary, which the plugin's hooks call:

curl -fsSL https://raw.githubusercontent.com/eddacraft/kindling/main/install.sh | sh
# or: cargo install eddacraft-kindling

Then, inside Claude Code, add this repository's marketplace and install the plugin:

/plugin marketplace add eddacraft/kindling
/plugin install kindling@kindling-plugins

kindling init --claude-code checks this setup and prints the same commands. kindling captures tool calls, file edits, commands, and errors across sessions. Search with kindling search or the plugin's /memory commands.

Plugin: plugins/kindling-claude-code

Install

Channel	Command	Notes
Installer (recommended)	curl -fsSL https://raw.githubusercontent.com/eddacraft/kindling/main/install.sh | sh	Prebuilt binary; Linux, macOS, Windows
Cargo	cargo install eddacraft-kindling	Crate name is eddacraft-kindling; the binary is kindling
Homebrew (macOS/Linux)	brew install eddacraft/tap/kindling	Same tap as anvil: eddacraft/homebrew-tap
GitHub Release	Releases	Prebuilt archives with .sha256 sidecars, plus the editor extension VSIX

kindling init          # create the local database
kindling demo          # load sample memory (try before you capture)
kindling serve         # start the daemon (auto-spawned by clients)
kindling search "auth" # search captured context
kindling browse        # open local HTML viewer

Setup guide: docs.eddacraft.ai/kindling/quickstart/install

kindling is not published to npm. The @eddacraft/kindling packages on npm are the retired 0.1.x TypeScript engine and are deprecated; install the binary with one of the channels above instead.

Node.js client

packages/kindling is a thin TypeScript client over the Rust daemon (HTTP/1 over a Unix domain socket). It auto-spawns kindling serve on first use. It is not published to npm: it ships bundled inside the editor extension, and you can use it from a clone of this repository (see Development).

Rust SDK

[dependencies]
kindling-client = "0.4"   # daemon-backed; default for integrations
# kindling-service = "0.4"  # embedded, in-process, zero IPC

How it works

Observations are atomic captures: tool calls, commands, file diffs, errors, messages, and workflow events.

Capsules group observations into bounded units (a session, a workflow node).

Search returns three tiers: pins (always first), current summary, then provider hits (ranked full-text results with provenance).

CLI reference

kindling demo                              # load sample memory
kindling browse                            # open HTML viewer
kindling log "root cause: cache eviction"
kindling search "authentication error"     # scoped to the current git repo
kindling search "authentication error" --all-repos
kindling stats                             # counts by kind, capsules, pins, activity
kindling pin observation obs_abc --note "Root cause"
kindling capsule open --intent "debug leak"
kindling export ./backup.json
kindling serve

Full CLI reference: docs.eddacraft.ai/kindling/reference/cli

Programmatic usage

use kindling_client::{Client, CapsuleType, RetrieveOptions, ScopeIds};

#[tokio::main]
async fn main() -> Result<(), kindling_client::ClientError> {
    let client = Client::new()?;
    let scope = ScopeIds { session_id: Some("session-1".into()), ..Default::default() };
    let capsule = client
        .open_capsule(CapsuleType::Session, "debug auth", scope.clone(), None)
        .await?;
    let results = client
        .retrieve(RetrieveOptions { query: "token".into(), scope_ids: scope, ..Default::default() })
        .await?;
    client.close_capsule(&capsule.id, Default::default()).await?;
    Ok(())
}

Adapter guide: docs/adapters/cookbook.md

Architecture

Rust is the engine. Adapters and the CLI reach project memory through the daemon (kindling serve), which owns the SQLite store and serialises concurrent access.

        Adapters / hooks                CLI
  ┌──────────────────────────┐   ┌──────────────┐
  │ VS Code · Claude Code ·    │   │  kindling    │
  │ OpenCode · PocketFlow      │   │  <command>   │
  └────────────┬─────────────┘   └──────┬───────┘
               │  kindling-client       │
               ▼                        ▼
        kindling-server          kindling-service
        (daemon)                 (embedded)
               └────────┬─────────┘
                        ▼
                 SQLite + FTS5

Details: docs/architecture.md

Documentation

• Without Claude Code
• Cursor and Windsurf
• Integrations matrix
• Adapter cookbook
• Install
• Core concepts
• Use cases
• Vision and direction

Development

git clone https://github.com/eddacraft/kindling.git && cd kindling
cargo build && cargo test
pnpm install && pnpm run build && pnpm run test

Performance work uses the Criterion and resource-profiling harness documented in crates/kindling-bench.

See CONTRIBUTING.md.

Contributing

Read VISION.md for where kindling is heading, then CONTRIBUTING.md for which changes are welcome, which need discussion first, and which are not the direction. Security issues: SECURITY.md.

Licence

Apache 2.0. See LICENSE.

---

Built by eddacraft. kindling captures what happened; anvil adds governed plans and quality gates for teams that want that layer on top.