Skip to main content

Capsules

A capsule is a bounded unit of meaning: a group of related observations with an intent and a lifecycle. Where an observation records a single event, a capsule captures a whole episode of work — a session, or a single workflow node run.

Structure​

interface Capsule {
  id: string; // unique identifier
  type: CapsuleType; // "session" | "pocketflow_node"
  intent: string; // why this capsule exists
  status: CapsuleStatus; // "open" | "closed"
  openedAt: number; // epoch milliseconds
  closedAt?: number; // set when closed
  scopeIds: ScopeIds; // session / repo / agent / user / task
  observationIds: string[]; // members, in order
  summaryId?: string; // summary produced on close
}

Types​

TypeCreated by
sessionInteractive development sessions — the CLI default, and what the Claude Code and OpenCode adapters open.
pocketflow_nodeA single PocketFlow workflow node execution.

Intent​

Every capsule has an intent — a short statement of why it exists ("investigating the memory leak", "implement token refresh"). Intent is required when opening a capsule and helps organise and rank retrieved context.

Lifecycle​

Capsules move through two states: open → closed.

Open​

kindling capsule open --intent "debug authentication issue" --repo ./my-project

--type defaults to session. While a capsule is open, observations can be attached to it with kindling log --capsule <id>.

Close​

kindling capsule close <id> --summary "Fixed JWT expiration check in middleware"

Closing records closedAt and, when a summary is provided, attaches it as the capsule's summary. That summary feeds the current summary tier of retrieval, so a closed capsule's conclusion surfaces ahead of raw observations.

Scope​

Like observations, capsules carry a ScopeIds record (sessionId, repoId, agentId, userId, taskId). Scope set on a capsule is how its work is later isolated during search.

Listing capsules​

kindling list capsules
kindling list capsules --repo ./my-project

Filter open vs closed capsules in your shell or use search for ranked retrieval — list has no --status flag.

Next​