> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myme.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Tier

> The library / feed axis — the primary split between curated and high-volume items

Every item carries `tier`, an enum with two values: `library` and `feed`. The split is a first-class axis of the design, not a convenience flag.

## Library vs feed

Personal data divides cleanly into two zones:

* **Library** — deliberate, low-volume, long retention. Saved bookmarks. Notes the user wrote. Pinned clips. The kept stuff.
* **Feed** — high-volume, low-intent, short retention. Clipboard history. Unpinned clips. Auto-ingested sessions. A bookmarks app's default inbox. The firehose.

Treating these as the same thing loses information. Treating the split as a first-class axis is the single most load-bearing separator in Marfa's design.

## Default when omitted

If neither the caller nor the credential supplies a `tier`, items land in `library` — the "save it" instinct. Apps and credentials override this default when their writing pattern fits the other shape (auto-ingest, scrapers, watchers).

## Filtering

The `tier` query parameter controls which slice is returned:

```
GET /items                  # all items (library + feed)
GET /items?tier=library     # library items only
GET /items?tier=feed        # feed items only
```

Omitting the parameter returns both slices. The same behavior applies to `/search`.

## Setting tier on write

Items arrive with a reasonable default based on the writing context. Credentials carry a `default_tier` that stamps when the client omits the field. Apps override per item when the default doesn't fit.

| Writing pattern                      | Typical default |
| ------------------------------------ | --------------- |
| User creates in an app's primary UI  | `library`       |
| Sync agent / auto-ingest             | `feed`          |
| Explicit user "save" or "pin" action | `library`       |
| Scraper / watcher / capture          | `feed`          |

Client-supplied `tier` always wins over the credential default.

## Promotion is a first-class gesture

Moving an item from feed to library is a user action with system-wide consequences: blob tiers upgrade, permissions can expand. Apps bind their own triage gestures to library promotion — a read-later app's "shortlist" moves items to library; a clipboard manager's "pin" does the same.

These bindings are app-side. The server carries the result.

## Tier is about prominence, not retention

The `tier` field names the **kind of intent** — where in the UI an item belongs and how prominently it surfaces. It does not carry implicit retention semantics. A feed item is not automatically deleted after some time window; both library and feed items persist until the user (or an app acting on their behalf) trashes them.

If periodic purge of high-volume captures is wanted, it's a user-driven flow — a filtered view plus a bulk-action verb — not an automatic platform behavior.

## Storage tier

Library blobs are authoritative and replicated. Feed blobs can be deduplicated aggressively and stored on cheaper tiers. The `blob_ref` shape is identical; tiering is transparent to callers but not to perceived latency. Apps that need low-latency blob fetch should operate on library items.

## Default tier on credentials

Credentials carry a `default_tier` field — `library` or `feed` — that stamps the tier on items written by the credential when the client omits one. Clients can override per-write. There is no read-side tier-gate on the credential; filtering by tier is a query concern (`GET /items?tier=feed`), not a permission boundary.

## Tier vs lifecycle

<Info>
  Tier is orthogonal to [lifecycle](/concepts/lifecycle) `state`. A library or feed item can be any of `active` / `archived` / `trashed`. An app's "archive" button maps to `state: archived`; its "pin" or "keep" button maps to `tier: library`. Don't conflate them.
</Info>

## Tier and `system.*`

The tier dimension does not apply to [`system.*` items](/concepts/system-types) — devices, credentials, webhooks, app identities. These are operational items, not user content. The `tier` field is omitted from their wire shape; setting it on write returns `400 invalid_field`.