Files
synchronicity/docs/humans-agent-research.md
Greg ShuflinandClaude Opus 5.5 d46a858f3e humans: interactions are events, in the code as on screen
The Humans screen's second tab is Events, and the thing it lists is an event
everywhere: DocumentType::Event, Event/EventSummary, log_event, events_with,
the FFI's EventItem/EventDetail, HumansCmd::Events, syn humans events, the
desktop's EventsView/EventForm and the copy ("Log an event", "an event only
you were at"). "Event" fits a walk taken alone, which "interaction" never
did, and one name in the code and on screen is one less translation.

EdgeKind::Attendee and PropertyKind::OccurredOn keep their names: an event
has attendees and occurs. Documents' tag for the type is EVT now, not MET.

DocumentType rides bare on the sync wire, so the rename is a wire change and
SYNC_PROTOCOL_VERSION is bumped. A store holding interactions doesn't read
them as events; delete and recreate it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-07 23:55:28 -08:00

29 KiB

Humans agent: prior-art research and a richer model

Research notes for evolving the Humans agent past its current grab-bag of fields. Two reference points: Monica (monicahq/monica, the mainstream open-source PRM, in two quite different generations) and the Obsidian personal-CRM conventions that people converge on when they build one out of plain files.

This document is research plus a recommendation. It does not commit to an implementation; the open questions in the last section need answers first.

1. Where the agent is today

rust/lib/src/agents/humans.rs, ~800 lines, one HumansManager.

Concept Storage Notes
The person DocumentType::Human
Display name PropertyKind::Title mirrored from full name on create/rename
Circles PropertyKind::HumanCircles (Tags, SetUnion) freeform strings, e.g. "college", "work"
Full name, nickname, birth date, notes singleton Artifacts all String, all LastWriteWins, 255-char cap except notes
Quick facts ArtifactKind::Fact collection, keyed Implemented (§4F): user-named key/value, id derived from the key so two nodes converge. HumanJob/HumanReligion were retired into this.
Multi-valued facts ArtifactKind::ListFact collection A key with several values, one row per (key, value). A separate kind because the merge rule differs — see §4F. Presented as one "Facts" list with the above; the split is storage's business.
Contact methods ArtifactKind::ContactMethod collection Implemented (§4D): typed protocol + value + label, id derived from (protocol, canonical value). Phone numbers are stored E.164.
Gender singleton Artifact (Gender enum, with Other(String))
Pets, web presences ArtifactKind::ListFact, keyed Retired into facts. Pets under "Pets"; a link under its own tag ("website", "twitter"), or "Links" when untagged.
Events DocumentType::Event Implemented (§4A): a NoteBody write-up, an OccurredOn PartialDate, and EdgeKind::Attendee edges to everyone who was there.

Gaps that both reference systems treat as core:

  • No interaction history. — resolved. DocumentType::Event records that you saw someone, and events_with answers "when did I last talk to X" as one indexed edge query. Still missing: a channel (in person / phone / text), and any "who am I overdue to see" view built on top (§4E).
  • No relationships between humans. No way to say Alice is Bob's sister.
  • Dates are strings. birth_date: String can't be sorted, can't answer "whose birthday is next", and can't express "born in March, year unknown".
  • One notes blob per person, rather than dated notes accumulating over time.
  • Only web presences — resolved for phone/email/handles by ContactMethod (§4D). Postal addresses are still missing.
  • No reminder or notification infrastructure anywhere in the codebase — a grep across rust/lib and rust/syn-daemon finds none. There's the Jobs model (ADR 0011) and the periodic sync scheduler, and that's it.
  • religion is a hardcoded field — resolved. HumanJob and HumanReligion are gone, retired into the generic Fact artifact kind (rust/lib/src/documents/facts.rs). Monica hit exactly this and fixed it the same way (see §2.2 and §4F).

2. Monica

Monica exists in two generations with materially different data models. Both are worth mining: v4 for its mature feature set, v5 for the modeling lessons the rewrite encodes.

2.1 Monica v4 (the 4.x branch — the mature one)

The contacts table itself carries a lot:

  • Names: first_name, middle_name, last_name, nickname; gender_id
  • description, job, company, food_preferences
  • is_partial — a stub person, created only so they can be the far end of a relationship ("Bob's wife"), with no profile of their own. Promoted to a real contact later. Scopes exist to filter these out of lists.
  • is_starred
  • is_dead + deceased_special_date_id
  • How you met: first_met_special_date_id, first_met_through_contact_id (another contact!), first_met_additional_info
  • Staying in touch: last_talked_to, stay_in_touch_frequency (days), stay_in_touch_trigger_date, last_consulted_at
  • CardDAV round-tripping: vcard, address_book_id, avatar_source

Satellite tables:

Table Shape
contact_field_types / contact_fields User-extensible typed contact methods. A type has a name, an icon, a protocol (mailto:, tel:, …), a type, and a delible flag; a field is (contact, type, data). LinkedIn was migrated into this rather than added as a column.
addresses name, street, city, province, postal_code, country
activities + activity_contact A shared thing you did, typed by activity_type (grouped by category), with description and date_it_happened. Many-to-many with contacts — one dinner is one activity attended by four people.
conversations + messages A logged conversation on a channel (contact_field_type_id, i.e. "over SMS"), with happened_at; messages carry content, written_at, written_by_me.
reminders + reminder_rules + reminder_outbox Recurring reminders with frequency, next-expected date, and a delivery outbox.
tasks label, description, completed, due date
notes body, is_favorited — many per contact
life_events (+ type, category) name, note, happened_at, with happened_at_month_unknown / happened_at_day_unknown flags
occupations title, company, description, salary + unit, currently_works_here, start/end date — job history, not just current job
relationships + relationship_types + relationship_type_groups See below
gifts, debts, documents, photos, pets, tags, journal entries

Relationships are the piece worth copying most directly: a relationship_type has both a name and a name_reverse_relationship, grouped into relationship_type_groups (love / family / friend / work). So recording "Alice is the mother of Bob" automatically yields "Bob is the child of Alice" on the other page, without storing two rows that can drift.

2.2 Monica v5 (main — the rewrite)

The rewrite generalized nearly everything the v4 schema had hardcoded. The lessons, in rough order of relevance:

  • ContactImportantDate with independently-nullable day / month / year, plus a user-definable ContactImportantDateType (which carries an internal_type so "birthday" can still get special treatment). This replaces v4's special_dates + six nullable FK columns on contacts. It handles "birthday, year unknown", "we met sometime in 2015", and arbitrary user-named dates in one uniform structure.
  • QuickFact + VaultQuickFactsTemplate — the vault defines quick-fact slots ("allergies", "how they take their coffee"), each contact fills them in. This is the direct replacement for v4's hardcoded food_preferences column, and the answer to the religion-shaped problem.
  • Template / TemplatePage / Module / ModuleRow / ModuleRowField — the contact detail page's layout is data. A contact points at a template; the template lists pages; pages list modules. Some modules are reserved_to_contact_information. This is over-engineering for a single-user tool, but the underlying idea (which sections appear is configuration, not code) is worth keeping in mind.
  • Group + GroupType + GroupTypeRole — a household, a band, a team, where each member has a role within the group. Strictly richer than a tag.
  • ContactInformation + ContactInformationType (with protocol) — v4's contact-fields idea, kept.
  • Loan with a loaner_id/loanee_id pivot, replacing v4's one-directional debts.
  • Call gained real structure: duration, type, answered, who_initiated, call_reason, and an emotion.
  • LifeEvent now hangs off a TimelineEvent and has participants (many-to-many), plus costs/currency, paid_by_contact_id, duration_in_minutes, distance + unit, from_place/to_place/place.
  • ContactFeedItem — a per-contact activity feed, so the detail page can show "what happened with this person recently" as a single stream.
  • Small lookup tables promoted to first-class models: Gender, Pronoun, Religion, Emotion, Label, Tag.
  • Feature sprawl to not copy: Goal/Streak, LifeMetric, MoodTrackingEvent (with number_of_hours_slept), Journal/Post/ PostSection/PostTemplate/SliceOfLife, JournalMetric. Each is a separate app wearing a CRM's clothes.

3. Obsidian personal-CRM conventions

No single schema, but the community converges hard on a few patterns, and the patterns disagree with Monica in an instructive way.

The person note stays small. Frontmatter is a stable core — some subset of name/aliases, company, title/role, email, phone, birthday, location, met (date), tags — and the body is freeform. Dann Berg's widely-copied template is only company / location / title / email / website / aliases plus a Notes heading and a Dataview block.

The interaction log does not live in the person note. It lives in daily notes and meeting notes that link to the person, and the person's page renders the reverse view via a Dataview query over inlinks. Two variants:

  • Meeting-note-per-interaction (Timestamps/Meetings, or YYYY-MM-DD - {{person}} - {{title}}), with an Attendees section wiki-linking each participant. The person note queries contains(file.outlinks, [[]]).
  • Inline field in the daily note: visit:: called [[Mom]] today #contact/phone.

"Last contacted" is derived, never stored. The canonical Dataview query flattens inlinks from daily notes, groups by person, and takes reverse(sort(rows.IN))[0]. A per-person Contact Frequency:: ("7 days", "1 month", "2 years") is compared against days-elapsed to produce an overdue list. This is Monica's stay_in_touch_frequency — but computed from the log rather than maintained as a denormalized last_talked_to column that can go stale.

aliases is load-bearing. It's what lets [[Bob]] and [[Robert Smith]] resolve to the same note, which is what makes wiki-linking a person from anywhere in the vault frictionless — and that frictionless link is the interaction log.

Reference fields link people to non-person entities: organization-slug, skill-slugs, product-slugs, tech-stack-slugs, plus a wall of social handle fields (twitter-id, github-id, linkedin-id, …).

The payoff is backlinks and graph view — seeing everything that touches a person without having filed any of it under them.

What the two approaches disagree about

Monica Obsidian
Interaction record First-class typed rows (activity, call, conversation, task) attached to the contact An ordinary note that happens to link the person
"Last talked to" A stored column, updated on write Derived from inlinks at query time
Field set Fixed schema (v4) → vault-defined slots (v5) Whatever you type in frontmatter
Who can be linked Contacts, and a few enumerated entity types Anything in the vault

Synchronicity can take the Obsidian side on derivation and linking while taking the Monica side on typed structure, because it has a real graph (Edge/EdgeKind) and a real query layer, which a pile of markdown does not.

4. Recommendations, mapped onto Synchronicity's data model

Ordered by value per unit of work. Document / Property / Artifact / Edge choices follow the test in docs/data-model.md §"Property vs. Artifact".

A. Events as documents, attendees as edges — the big one (implemented)

DocumentType::Event exists, and it needed no new storage concepts: the write-up is an ArtifactKind::NoteBody exactly as a Note's is, the date is PropertyKind::OccurredOn (a PartialDate, so "sometime in 2019" is sayable), and attendees are EdgeKind::Attendee edges to each Human — so one dinner covers four people, which is Monica's activity_contact pivot and Obsidian's attendee wiki-links in the same shape. "Last contacted" is a query over inbound edges, Obsidian's derivation rather than a stale column.

Three things this section proposed that were not built, deliberately:

  • channel (in person / phone / text / …). No code branches on it yet, so by §4F's rule it has not earned a field; when something does, it is a quick fact away from being a keyed value, and a PropertyKind if it needs to be filtered on.
  • A separate summary. The title property is the summary.
  • An optional date. The date is required. Being dated is what separates an event from a note about someone, PartialDate already covers vagueness, and the document store has no way to remove a property (there is no property tombstone), so an optional date would have been settable and never clearable.

The one design point worth restating: attendance is deliberately not a wikilink. Writing [[Ada Lovelace]] in the body links her — the same re-derive-on-save machinery a note uses — but does not put her on the guest list. A note about someone is not contact with them, so a "who am I overdue to see" view built on wikilinks would be quietly wrong. Both frontends show the two lists under separate headings for the same reason.

B. Human ↔ Human relationships

Copy Monica's forward/reverse naming so one stored fact renders correctly on both pages. Needs a decision about edge payloads — see §5.

Also copy is_partial: creating "Bob's wife" as a stub Human with only a name, excluded from the main list until promoted, is what makes relationship entry bearable in practice.

C. Structured, partial dates

See §7 for the full analysis — this is the piece with the most transferable detail. In short: replace HumanBirthDate: String with a collection artifact HumanImportantDate { label, role: Option<DateRole>, date: PartialDate }, where PartialDate is a three-variant enum, not a struct of three Options:

/// A calendar date known to varying precision. Not an instant: a birthday is a
/// civil date, and rendering it through a UTC `Timestamp` shifts the day.
pub enum PartialDate {
    /// Year, month and day all known.
    Full { year: i32, month: u8, day: u8 },
    /// Recurs annually, year genuinely unknown — a birthday you celebrate but
    /// whose year you were never told.
    MonthDay { month: u8, day: u8 },
    /// Only the year: "we met in 2015".
    Year(i32),
}

This subsumes birthday, anniversary, first-met, and deceased date, and unlocks "whose birthday is next" — currently impossible against a string.

D. Contact methods as a typed collection (implemented)

ArtifactKind::ContactMethod carries { protocol, value, label }, where protocol is a closed enum with an Other(String) escape hatch. Monica's protocol field was the useful detail and this is it: ContactProtocol::uri renders a working tel: / mailto: / profile link rather than dead text.

This is the one promotion out of facts, and it meets §4F's bar — the code genuinely dispatches on the protocol, which a free-text key cannot support ("twitter", "x" and "X" are three keys and one thing, and nothing rejects "twiter"). Anything with no such dispatch stays a fact, including Other.

The subtle part turned out to be normalization rather than the type. Merging "020 7946 0958" with "+44 20 7946 0958" needs libphonenumber, whose answers are region- and version-dependent — so it runs at write time and the canonical E.164 form is stored, leaving the derived row id a frozen function of stored bytes. See documents::contact and docs/data-model.md's "Derived ids, and why they must be frozen"; the same reasoning applies to any future kind that wants to normalize before comparing.

Not done: addresses (a structured multi-line thing, not a protocol), and no per-protocol validation beyond phone numbers.

E. Stay in touch — as a derived view, not notifications

Per-human desired cadence (an artifact), plus an "overdue" list derived from (A). Do not build reminders yet: there is no notification or scheduling infrastructure for user-facing events in this codebase, and building one is its own project. A derived overdue view is what Obsidian users actually get, it needs no new infrastructure, and it respects the instant-feedback invariant.

F. Quick facts — the escape hatch (implemented)

Built, as two kinds, both generic across document types rather than scoped to Human:

  • ArtifactValue::Fact { key, value } — a key with one value, row id derived from the key, so concurrent writes reconcile per key.
  • ArtifactValue::ListFact { key, value } — a key with several, row id derived from (key, value), so concurrent additions converge to the union.

Two kinds and not a Vec in one, because a collection artifact's row id is its identity across nodes and merge_strategy() dispatches on the kind alone: a list in one row would reconcile last-write-wins over the whole list, losing one of two concurrently-added pets. The accessors in documents::facts are what derive those ids, and are the only correct way to write either kind. This is the general answer to "I want to track that she's allergic to shellfish", and it's why HumanReligion should probably be retired into it rather than joined by ten more hardcoded siblings. ArtifactKind is a closed Rust enum synced across nodes, so a user-defined kind isn't available — label-as-data inside one kind is the way to get the same affordance.

Monica's own history is the argument here: v4 hardcoded food_preferences; the v5 rewrite deleted it in favour of QuickFact.

G. Notes on a person, plural and dated

Today: one singleton HumanNotes blob. Wanted: many dated notes. The cheapest version reuses machinery that already exists — let a Note wiki-link a Human (EdgeKind::WikiLink is already defined and synced), and render backlinks on the human's detail page. That is precisely the Obsidian model, and most of it is already built.

H. Avatar

No avatar today. ArtifactKind::Thumbnail exists, as does DocumentType::Image; either an edge to an Image or a Thumbnail artifact would do.

I. Deferred / declined

  • Groups with roles (Monica v5). Genuinely richer than circles, but needs a new document type. Circles are cheap and adequate; revisit later.
  • Job history (Monica v4 occupations). Nice, low priority.
  • Gifts, loans/debts, mood tracking, goals/streaks, journal metrics, salary, activity statistics. Monica's sprawl. Skip.
  • The Template/Module layout engine. Over-engineered for a single-user tool.

J. The Synchronicity-specific opportunity neither reference has

Both Monica and Obsidian model people as inert records. This project has real cryptographic peers: a Human who is also someone whose ensemble you exchange data with is a first-class thing here and has no analogue in either system. Linking a Human to a peer identity — and eventually to sharing/permissions — is where this agent could be better than the prior art rather than a reimplementation of it.

Related, and much nearer-term: vCard import. Both Monica generations store a raw vcard blob plus distant_uuid/distant_etag/distant_uri for CardDAV round-tripping. The repo already has documents/import.rs and url_import.rs. vCard import is the obvious on-ramp so the agent doesn't start empty.

5. Open questions

  1. Edge payloads. Edge carries only kind: EdgeKind, a closed enum, with no label. Relationship types ("sister of" / "brother of") are data, not code. Either Edge grows an optional label, or EdgeKind grows a small closed set of relationship variants, or the relationship becomes its own tiny document. This decision gates (B).

  2. Is Event its own DocumentType, or a Note? Answered: its own type, sharing every part with Note. The objection that settled it is the second one — "every note about a person counts as contact" is wrong — and only a distinct type makes the two distinguishable. But the first consideration was right too, and cost nothing: an Event reuses NoteBody verbatim, so it inherits the editor, the markup pipeline, the wikilink extraction, and sync. This is the DocumentType-is-semantic / Artifact-is-structural split doing its job.

  3. Does HumanReligion get retired into quick facts? Answered: yes. HumanJob and HumanReligion are removed; existing rows are converted to Facts keyed "Job"/"Religion" when the artifact store opens.

  4. Circles vs. groups-with-roles — keep circles indefinitely, or plan the migration?

    Worth recording why circles are a Property while facts are Artifacts, since the two look similar enough to invite merging them. The list screen filters by circle, so a node has to know someone's circles to place them in a tab at all — and properties sync eagerly with the document record while artifacts are fetched separately and may legitimately be absent. Move circles into facts and filtering silently breaks on any node that has the person but not yet their content. The tiers are the distinction; the UI labels for them were the confusing part, and "Groups" is gone.

  5. Does the "overdue to contact" view live in the Humans agent, or does it want a general per-user surfacing mechanism that other agents would also use?

6. Documentation drift spotted along the way

docs/data-model.md (~line 105) says "HumanTitle is a Property". There is no HumanTitle; humans use the shared PropertyKind::Title. The point being made is still correct — worth fixing the name when this area is next touched. The same passage lists HumanBirthDate etc. as example Artifacts; HumanJob and HumanReligion no longer exist and should not be re-added to it.

7. Partial dates in depth

The current birth_date: String avoids committing to ISO 8601, which is the right instinct — a birthday is not an instant and often isn't fully known. But Monica has been through both alternatives, and the second one is much better than a string.

7.1 What Monica v4 did, and why the rewrite abandoned it

special_dates stored a real date column plus two booleans, is_year_unknown and is_age_based. The model's own docblock explains the three cases it was covering: a full date; a day+month with no year; or an age ("this person is 33, I don't know their birthdate, so we'll give an estimation").

The implementation is the cautionary tale:

// createFromDate: year 0 represents the `unknown` choice in the dropdown
if ($year != 0) { $date = Carbon::createFromDate($year, $month, $day); $this->is_year_unknown = false; }
else            { $date = Carbon::createFromDate(now()->year, $month, $day); $this->is_year_unknown = true; }

// createFromAge: fabricate January 1st, `age` years ago
$this->date = now()->subYears($age)->month(1)->day(1);
$this->is_age_based = true;

The stored date is partly fiction — a placeholder year, or a fabricated Jan 1 — and correctness depends on every reader remembering to check the flags. toShortString() branches on is_year_unknown to pick a formatter; getAge() returns null if it's set. Miss the check anywhere and you silently display or compute against invented data. A sentinel year == 0 in the input path on top.

This is exactly the failure mode of "store a full date and flag which parts are unreliable," and it is the strongest available argument against reaching for ISO 8601 plus caveats. The v5 rewrite deleted it.

7.2 What Monica v5 does

contact_important_dates stores day, month, year as three independently nullable integers, plus a required label string and an optional FK to a ContactImportantDateType. Nothing is fabricated and there are no flags.

The precision is derived, not stored. ImportantDateHelper::determineType() inspects which components are present and returns one of three constants:

Present Type
day + month + year TYPE_FULL_DATE
day + month, no year TYPE_MONTH_DAY
year only TYPE_YEAR
nothing null

Every consumer dispatches on that:

  • getAge() computes an age for full_date and year, and returns null for month_day — age is genuinely unknowable there, and the branch makes that explicit rather than returning a wrong number.
  • formatDate() renders full_date in the user's preferred format, year as the bare integer, and month_day through a year-stripped variant of the user's format (MMM DD, DD/MM, …). It parses month_day as year 1900 purely to get a date object to format from; that 1900 is never displayed.
  • The 12-month upcoming-dates report sorts by month, day and buckets by month, ignoring the year entirely — recurrence never needs it.
  • getVCardDate() emits RFC 6350 partial dates: --0314 for "March 14, year unspecified". Worth knowing that partial dates are a standard, not a Monica invention — vCard 4.0 and ISO 8601-2 both define truncated representations. So this shape round-trips through real interchange formats; a free string does not.
  • The entry UI is literally three radio buttons — "full date" / "month and day" / "year" — each revealing only the fields it needs. The reminder checkbox next to it is hidden when the choice is year, since a year-only date can't recur.

7.3 The one thing to change when porting it

Three nullable integers admit eight states, of which only four are meaningful. Monica's own determineType() shows the cost: the four nonsense combinations (month alone, year+month, year+day, day alone) fall through every if and leave $type as the empty string '' — not null, not an error, just a value nothing else handles. That's a latent bug the schema invites.

SQL forced that encoding on them. Rust doesn't. The three radio buttons in Monica's own UI are the sum type, so model it as one directly (§4C). Then:

  • The four nonsense states are unrepresentable rather than merely unhandled.
  • age() returns Option<u32> and the None case is a variant you must match, not a runtime check someone can skip.
  • next_occurrence() returns Option<NaiveDate> — None for Year.
  • recurs_annually() is a one-line match, which is what the "offer a reminder?" and "show in the upcoming-12-months view" decisions both key off.
  • Sorting for "whose birthday is next" is well-defined per variant.

Deliberately not carried over from v4: the age-based case ("she's 33"). It is a real thing people know, but v5 dropped it, and storing it as Year(current_year - 33) is the same fabrication that made v4 fragile. Better to leave it out than to encode a guess as data.

Keep the label/role split from v5: label is a required free string the user invents per date ("Birthday", "Day we adopted the cat"), and a separate optional role marks the handful the code special-cases. Monica does this with ContactImportantDateType.internal_type (birthdate, deceased_date) and a query scope that finds "the birthday" without caring what the user named it. In Synchronicity that's label: String as data plus role: Option<DateRole> as a small closed enum — user-extensible taxonomy, with a reserved set the code knows.

7.4 What a string still buys, and where to put it instead

A date type of any precision cannot express "born sometime in the late 80s" or "around Christmas one year." That vagueness is real, and it's the honest argument for the current string. But the answer isn't to weaken the date type — it's to keep the vague version as free text alongside it (a note, or a quick fact per §4F) and leave PartialDate for what's actually known. Monica reached the same place: v5 has both structured dates and free-text notes, and doesn't try to make one do the other's job.

One further reason not to reuse an existing type: documents::Timestamp wraps DateTime<Utc>, an instant. A birthday is a civil date. Rendering an instant in a different time zone moves it by a day, which is precisely the bug that makes birthday features embarrassing.

Sources