Skip to main content

Capsules

Capsules are the primary organisational unit in Kindling.

What is a Capsule?​

A capsule is a container for related observations. Think of it as a folder for knowledge about a specific context:

Capsule: payment-integration
├── Observation: "Stripe uses cents, not dollars"
├── Observation: "Webhook signature verification required"
├── Observation: "Test cards: 4242..."
└── Observation: "Idempotency keys prevent duplicates"

Why Capsules?​

Bounded Context​

Observations make sense within their context. "Use the new API" means different things in different projects.

Capsules provide that context.

Search Scope​

Searching within a capsule returns relevant results:

kindling search "API" --capsule payment-integration
# Returns payment-related API knowledge

kindling search "API" --capsule auth-system
# Returns auth-related API knowledge

Portability​

Each capsule is a standalone SQLite database. You can:

  • Back up individual capsules
  • Share capsules with teammates
  • Archive completed projects
  • Move capsules between machines

Capsule Lifecycle​

1. Create​

When starting new work:

kindling capsule create feature-auth

2. Use​

Set as active:

kindling capsule use feature-auth

3. Populate​

Record observations during work:

kindling observe "JWT tokens stored in httpOnly cookies"

4. Query​

Retrieve knowledge:

kindling search "cookie"

5. Archive​

When work completes:

kindling capsule archive feature-auth

6. Export (Optional)​

Extract for documentation:

kindling export --capsule feature-auth --format markdown

Capsule Types​

Global Capsules​

Stored in ~/.kindling/capsules/:

kindling capsule create my-capsule

Available everywhere on your machine.

Project-Local Capsules​

Stored in project directory:

kindling capsule create --local .

Creates .kindling/ in current directory. Benefits:

  • Version controlled
  • Team shared
  • Project-specific

Temporary Capsules​

For throwaway exploration:

kindling capsule create --temp

Automatically deleted after 24 hours.

Capsule Metadata​

Each capsule stores metadata:

{
  "name": "payment-integration",
  "created": "2024-01-10T09:00:00Z",
  "lastUpdated": "2024-01-15T16:30:00Z",
  "observationCount": 42,
  "status": "active",
  "tags": ["project:shop", "team:payments"]
}

Custom Metadata​

Add project-specific metadata:

kindling capsule set payment-integration \
  --meta project=shop \
  --meta team=payments

Best Practices​

One Capsule Per Context​

# ✓ Good: specific context
kindling capsule create api-v2-migration
kindling capsule create security-audit-2024

# ✗ Avoid: too broad
kindling capsule create work
kindling capsule create notes

Descriptive Names​

# ✓ Good: descriptive
kindling capsule create stripe-integration
kindling capsule create auth-refresh-tokens

# ✗ Avoid: cryptic
kindling capsule create proj1
kindling capsule create temp

Archive When Done​

Don't delete—archive. You might need it later:

kindling capsule archive completed-feature

Review Periodically​

List capsules and clean up:

kindling capsule list --all

Next: Observations →