> ## 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.

# Introduction

> What Marfa is and the problem it solves

Marfa is a **typed data layer** for structured personal data. It stores items against a shared type system, exposes them through a REST + SSE API, and lets many apps read and write the same person's data without speaking custom-to-each-other.

## The problem

Every app has its own data silo. A notes app stores notes one way. A bookmarks app stores bookmarks another. A photo library does its own thing. If you want to use your data across apps — search your highlights alongside your notes, see bookmarks in a timeline with photos — you're writing glue between incompatible APIs.

Marfa sits underneath. One place where typed data from many sources lives together, stays queryable across apps, and carries its provenance honestly.

## Three primitives

Marfa is built on three primitives.

<CardGroup cols={3}>
  <Card title="Items" href="/concepts/items">
    Typed records. Your data, schema-validated, with a metadata layer.
  </Card>

  <Card title="Types" href="/concepts/types">
    Schemas. A disciplined core set plus app-registered custom types.
  </Card>

  <Card title="Edges" href="/concepts/edges">
    Named relationships between items. First-class, typed, queryable both ways.
  </Card>
</CardGroup>

Alongside those, every item carries a **tier** (`library` or `feed` — curated vs. firehose), a **lifecycle state** (active / archived / trashed), and a **provenance stamp** (which app wrote it, what kind of actor produced it).

## How apps use Marfa

<CardGroup cols={2}>
  <Card title="As a backend">
    A simple app uses Marfa directly. The SDK is the database client. No separate server needed for the app to operate.
  </Card>

  <Card title="As a consolidation point">
    An app with its own backend syncs relevant data to Marfa. A read-later service pushes highlights. A fitness tracker pushes workouts. Marfa becomes the destination where data from many sources lives together.
  </Card>
</CardGroup>

Both patterns use the same SDK, the same types, the same wire shape.

## Design principles

Four principles shape the product. Every other decision flows from them.

* **Types are the primary structure.** Everything is a typed item. The core type set is opinionated and narrow; custom types are the main road; inheritance lets custom types extend core ones cleanly. See [Types](/concepts/types).
* **Tier is the primary axis of intent.** Personal data divides cleanly into a curated library (deliberate, low-volume) and a high-volume feed (low-intent). Every item carries `tier: 'library' | 'feed'`; storage tiering and permissions are tier-aware. Tier is a prominence signal, not a retention policy — items persist until the user (or an app acting on their behalf) trashes them. See [Tier](/concepts/library).
* **Relationships are first-class and typed.** Items connect through named, typed edges — not embedded ids in properties. Edges are queryable from both ends and carry per-type constraints. See [Edges](/concepts/edges).
* **Multi-tenant, multi-app, honest provenance.** Every item carries `source` (which app wrote it). In server-synced mode it's credential-stamped and non-forgeable. See [Provenance](/concepts/provenance).

## What Marfa is not

Scope discipline. A few things Marfa deliberately does not do:

* **Not a real-time collaborative editor.** Sync is event-driven at the item level, not operation-level. No CRDT.
* **Not a binary-replication transport.** Moving bytes between devices is for Syncthing, iCloud, Dropbox, Obsidian Sync. The Sync Agent uses those underneath; Marfa provides the typed structure on top.
* **Not a federated identity service.** Marfa issues OAuth and OIDC identity tokens to apps that trust Marfa as a tenant boundary. It does not resolve user identity across other companies' systems the way WorkOS, Auth0, or Okta do.
* **Not a workflow engine.** No rules, automations, or triggers beyond webhooks. Apps build rule engines on top of Marfa's events.
* **Not a protocol or standard.** A product with an SDK and a server. The conformance suite checks contract alignment for any reimplementation — Marfa is not trying to be IETF.
* **Not a secrets manager.** Credentials, passwords, 2FA secrets belong in a password manager or OS keychain.
* **No semantic or vector search.** Full-text only.
* **Not a hosted multi-tenant product at scale yet.** Self-hosted by design today.

## What's in these docs

<CardGroup cols={2}>
  <Card title="Concepts" href="/concepts/items">
    The mental model. Items, types, edges, namespaces, the tier axis, lifecycle, metadata, provenance, spaces. Start here.
  </Card>

  <Card title="API" href="/api/authentication">
    How the API works. Authentication, permissions, realtime events, search, webhooks, errors.
  </Card>

  <Card title="SDKs" href="/sdks/typescript">
    TypeScript and Swift clients for talking to a Marfa server. Both mirror the same concepts.
  </Card>

  <Card title="API reference">
    Every endpoint, generated from the OpenAPI spec.
  </Card>

  <Card title="Clients" href="/clients/overview">
    In-house clients (CLI, MCP, sync agent, Raycast) and patterns for building your own.
  </Card>

  <Card title="Self-hosting" href="/self-hosting/configuration">
    Running your own Marfa server. Configuration, deployment modes.
  </Card>
</CardGroup>