Marfa's architecture

The parts of Marfa and how they fit together, from the instance that holds a person's data to the apps, agents, devices and connectors that reach it.

Marfa has one center, the instance, which holds everything a person keeps: their files and pictures, their notes and bookmarks, and what they keep in other services. Everything else is a program outside it that reaches it over its HTTP API, with a credential that reaches only what the owner allowed.

The instance

An instance is one running Marfa server and the data it keeps, in one SQLite database and a folder of files. It belongs to one person, its owner, and runs on their own Mac or server. Install Marfa shows how to run one.

The instance is the source of truth. Apps, agents, devices and connectors read from it and write to it, and never talk to each other. When two of them change the same thing, the instance decides the outcome, and every copy comes into line with it.

The data

Everything in an instance is an item: one file, photo, note, bookmark, contact or conversation. Its type, such as core.file.image or core.note, says which properties it holds, and Marfa checks every write against it, so every app that reads an item knows what its type requires. Items and types explains both.

Around its properties, an item carries more:

  • Tags and extensions: free labels, and an app's own data kept on the item (Properties and metadata).
  • Tables: rows in typed columns, such as the messages of a conversation (Tables).
  • Edges: typed links to other items, such as a photo attached to a note (Edges).
  • A file's bytes: kept once as a blob, however many items name it (Files).

Changes

Every item has a version, and a write names the version it read, so Marfa can tell when someone else changed the item in between. Versions explains what Marfa does then.

Changes are recorded as events in one log. An app follows the log to stay current, or registers a webhook so the instance posts changes to it. Events and webhooks covers both.

Who can reach it

Nothing reads or writes an instance without a credential, and a credential reaches only what it was given: these types, read or edit, and these powers. A script or a connector uses a key. An app or an agent signs in with OAuth, so the owner sees what it asks for and approves it. Access explains both.

What reaches it

Every program that uses Marfa runs outside the server. What sits between it and the API differs:

  • The Swift SDK and the CLI embed the core, a Rust engine that sends their requests and can keep a working copy of the items they need. A program with a working copy is a device: it reads offline and sends its writes when it can reach the instance, as Devices explains. A synced folder is a device too: its working copy is a folder of ordinary files on your computer.
  • The TypeScript SDK sends each request straight to the API, and keeps no copy. Web pages, scripts and connectors use it.
  • AI agents, such as Claude or Codex, connect to the instance's MCP server at /mcp, or run the CLI, as Connect your agent shows.
  • Connectors are programs the owner runs that register with the instance and bring in records from another service, such as GitHub or a calendar, as Connectors explains.
Native clients
Keep working offline
Swift SDK
In an iPhone or Mac app
CLI
For agents, scripts and the terminal
Rust core
Sends requests, and can keep a working copy
Online clients
Send each request straight to the API
TypeScript SDK
In connectors, scripts and apps
HTTP API
Every request carries a credential
Your instance
The source of truth
One SQLite databaseA folder of files

Apps made by WithMarfa reach the instance the same way, through the same API and the same credentials as anything you build.

On this page