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>
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::Eventrecords that you saw someone, andevents_withanswers "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: Stringcan'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 byContactMethod(§4D). Postal addresses are still missing.- No reminder or notification infrastructure anywhere in the codebase — a grep
across
rust/libandrust/syn-daemonfinds none. There's the Jobs model (ADR 0011) and the periodic sync scheduler, and that's it. — resolved.religionis a hardcoded fieldHumanJobandHumanReligionare gone, retired into the genericFactartifact 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_preferencesis_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_starredis_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:
ContactImportantDatewith independently-nullableday/month/year, plus a user-definableContactImportantDateType(which carries aninternal_typeso "birthday" can still get special treatment). This replaces v4'sspecial_dates+ six nullable FK columns oncontacts. 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 hardcodedfood_preferencescolumn, and the answer to thereligion-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 arereserved_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(withprotocol) — v4's contact-fields idea, kept.Loanwith aloaner_id/loanee_idpivot, replacing v4's one-directionaldebts.Callgained real structure:duration,type,answered,who_initiated,call_reason, and anemotion.LifeEventnow hangs off aTimelineEventand has participants (many-to-many), pluscosts/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(withnumber_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, orYYYY-MM-DD - {{person}} - {{title}}), with an Attendees section wiki-linking each participant. The person note queriescontains(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 aPropertyKindif 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,
PartialDatealready 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
-
Edge payloads.
Edgecarries onlykind: EdgeKind, a closed enum, with no label. Relationship types ("sister of" / "brother of") are data, not code. EitherEdgegrows an optional label, orEdgeKindgrows a small closed set of relationship variants, or the relationship becomes its own tiny document. This decision gates (B). -
IsAnswered: its own type, sharing every part withEventits ownDocumentType, or aNote?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: anEventreusesNoteBodyverbatim, so it inherits the editor, the markup pipeline, the wikilink extraction, and sync. This is theDocumentType-is-semantic /Artifact-is-structural split doing its job. -
DoesAnswered: yes.HumanReligionget retired into quick facts?HumanJobandHumanReligionare removed; existing rows are converted toFacts keyed "Job"/"Religion" when the artifact store opens. -
Circles vs. groups-with-roles — keep circles indefinitely, or plan the migration?
Worth recording why circles are a
Propertywhile facts areArtifacts, 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. -
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 forfull_dateandyear, and returnsnullformonth_day— age is genuinely unknowable there, and the branch makes that explicit rather than returning a wrong number.formatDate()rendersfull_datein the user's preferred format,yearas the bare integer, andmonth_daythrough a year-stripped variant of the user's format (MMM DD,DD/MM, …). It parsesmonth_dayas 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, dayand buckets by month, ignoring the year entirely — recurrence never needs it. getVCardDate()emits RFC 6350 partial dates:--0314for "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()returnsOption<u32>and theNonecase is a variant you must match, not a runtime check someone can skip.next_occurrence()returnsOption<NaiveDate>—NoneforYear.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
- monicahq/monica —
main(v5) migrations andapp/Models, and the4.xbranch'sapp/Models/Contactand migrations - monicahq/monica on DeepWiki
- TalkingQuickly/obsidian-crm
- Dann Berg — My Obsidian People Note Template (gist)
- Obsidian Forum — Relationship and Contact Management with Dataview
- thephm/hal_md — person-note frontmatter conventions
- One For The Code — Building a Personal CRM with Obsidian and Dataview