Skip to main content

Context Tiers

Paddles has access to effectively unlimited context, but it cannot hold everything in working memory at once. The system manages this through four tiers with increasing depth and decreasing immediacy.

The Four Tiers​

TierWhat lives hereAccess
InlineCharacter-limited excerpts in working memoryDirect read, zero cost
TransitFull trace records in durable streamsReplay by task and record id
SiftIndexed evidence returned by search/refineSearch and refinement retrieval in the planner loop
FilesystemWorkspace files on diskPath-based file read

Think of these as concentric rings. Inline is the hottest, smallest cache. Transit holds the full history. Filesystem holds the authoritative source.

Typed Addressing​

When inline content is truncated, the artifact envelope carries a typed ContextLocator that says exactly where the full content lives:

  • ContextLocator::Inline { content } — the content itself
  • ContextLocator::Transit { task_id, record_id } — a specific record in a transit stream
  • ContextLocator::Filesystem { path } — a file on disk
  • ContextLocator::Sift { index_ref } — an indexed retrieval reference from search/refine evidence

Each locator encodes its target tier. Consumers do not need to guess where content lives.

Lazy Resolution​

Resolution is pull-based. No tier eagerly loads content from a deeper tier.

When a consumer needs the full content behind a truncated artifact, it calls resolver.resolve(&locator). The resolver dispatches based on the locator's tier:

  • Inline — returns the content directly
  • Transit — replays the task stream, finds the record, extracts the content
  • Filesystem — reads the file
  • Sift — currently surfaced as typed locator metadata; direct Sift resolution is not yet wired in the resolver

Resolution follows a local-first ordering. Inline returns immediately. Transit replays local streams. Filesystem reads local disk.

Fail-Closed Degradation​

When a tier is unavailable or a record is missing, resolution returns an explicit error naming the tier and the locator details. It does not silently fall back or return partial content.

Consumers degrade honestly — they can use the truncated inline content as a fallback, but they know they are doing so.