Skip to main content

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.

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 patternTypical default
User creates in an app’s primary UIlibrary
Sync agent / auto-ingestfeed
Explicit user “save” or “pin” actionlibrary
Scraper / watcher / capturefeed
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

Tier is orthogonal to 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.

​
Tier and system.*

The tier dimension does not apply to system.* items — 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.