What a contact is

One folder per person or organization. Inside, one text file that says who they are, and one line for each exchange you had with them.

The people below are made up to show the shape. Priya Shah owns the folder; everyone else is a contact. Contract 0.2.0 for a person, 0.1.0 for an organization and an exchange.

The picture

The person file, as a table

One row is one person. A field is one column.

id	name	organization	title	email	telephone	tags	confidence	filed_by
`per_sam-lee`	Sam Lee	`org_eastside-tool-library`	Founder	sam@example.org	+1 713 555 0100	builder, houston	confident	intake:vcf
`per_ana-ruiz`	Ana Ruiz	Studio Ruiz	Designer	ana@example.org ana@studio.example	+1 713 555 0142	design	verified	intake:json
`per_kai-tran`	Kai Tran			kai@example.org			verified	agent

Sam's organization is on record, so their file points at its id. Ana's is not, so it is the name as their card gives it.Ana came in twice, as a card and as their own profile. Their emails were merged; nothing on file was overwritten.

The organization file, as a table

The same local fields a person carries, on a Murmurations organizations profile.

id	visibility	name	primary_url	email	tags	filed_by
`org_eastside-tool-library`	local	Eastside Tool Library	eastside.example	hello@eastside.example	community	intake:vcf

What each field holds

id: per_ plus the name they use, or org_ plus the organization's name. Given once and never changed; everything else joins on it.
linked_schemas: The formats this file follows: the Murmurations profile first, then this folder's add-on.
name: The name they use, from their own signature or profile. Never guessed from a calendar title or an email address.
primary_url: Their own site. Left out when they have none.
urls: Any further links, as the card gives them, so a card with two links comes back out with two.
email: Every address they have written from.
telephone: Phone numbers, as the card gives them.
title: A person's job title, as their card or signature gives it.
organization: Where a person works. An org_ id when the organization is on record, otherwise its name as the card gives it.
description: One or two sentences on who they are, in your words.
tags: Words you use to find them.
relationships: Who or what they are connected to: a relation and a person, an organization or a project, the Murmurations triple.
visibility: Who may see this file. local means it never leaves your computer.
met_through: How you met a person, in a phrase.
first_exchange, last_exchange: Worked out from their exchanges, never typed.
elsewhere: Where the same person also lives: a profile, a contact card. A pointer, never a copy.
filed_at, filed_by: When this file was written, and what wrote it: you, a routine, the processor.
confidence: How sure you can be this is one real person or organization: verified, confident or unsure, and why. More.
contact_preferences: A person's only. How they like to be reached and talked to, and how things made for them should look. More.

An exchange

What passed between you: an email, a call, a file, a set of links. One line each in records/<id>/exchanges.jsonl, added to and never rewritten.

id	at	from	to	route	subject	carried	filed_by
`exc_3f9a1c0b2d`	2026-10-08 10:10	`per_kai-tran`	`per_priya-shah`	email	This week: three libraries	1 link, 1 ask	agent
`exc_7d20e4a915`	2026-10-09 12:00	`per_priya-shah`	`per_sam-lee`	file	for-sam.md	1 file	agent

Every line says when it happened (at) and, apart from that, when and how it was filed. The same event filed twice gets the same id.

What the file looks like inside

JSON, a plain text format. This is Ana's file, records/per_ana-ruiz/person.json.

{
  "id": "per_ana-ruiz",
  "linked_schemas": ["people_schema-v0.1.0", "contacts_person_addon-v0.2.0"],
  "name": "Ana Ruiz",
  "primary_url": "https://ana.example",
  "email": ["ana@example.org", "ana@studio.example"],
  "title": "Designer",
  "organization": "Studio Ruiz",
  "telephone": ["+1 713 555 0142"],
  "tags": ["design"],
  "relationships": [
    { "predicate_url": "collaborator", "object_url": "per_sam-lee" }
  ],
  "elsewhere": [
    { "system": "murmurations-profile", "ref": "ana-profile.json" },
    { "system": "vcard", "ref": "phone-export.vcf" }
  ],
  "visibility": ["local"],
  "filed_at": "2026-10-08T13:09:49-05:00",
  "filed_by": "intake:json",
  "confidence": {
    "level": "verified",
    "because": ["On 2 email threads with you, latest 2026-10-02"],
    "set_at": "2026-10-09",
    "set_by": "experiment-01:levels"
  },
  "contact_preferences": {
    "reach_by": ["email"],
    "how_to_talk": "Direct. Lead with the ask.",
    "from": "notes/people/Ana Ruiz.md"
  }
}

And one line of Kai's exchanges, records/per_kai-tran/exchanges.jsonl, spread out here to read. In the file it is one line.

{
  "id": "exc_3f9a1c0b2d",
  "at": "2026-10-08T10:10:16-05:00",
  "from": "per_kai-tran",
  "to": ["per_priya-shah"],
  "route": "email",
  "subject": "This week: three libraries",
  "carried": [
    { "kind": "link", "title": "Activity guides", "url": "https://example.org/guides" },
    { "kind": "ask", "title": "Feedback on the practice prompts" }
  ],
  "source_ref": "mail:1a11c10b3ced9ea2",
  "filed_at": "2026-10-08T11:41:00-05:00",
  "filed_by": "agent",
  "how_filed": "Typed into an intake note from the email; links copied as sent.",
  "visibility": ["local"]
}

How it connects

Getting started →
How sure we are →
How someone likes to be reached →
Projects →
What the manifest is →