People

People

Most of what a person knows about the people in their life is never written down. It sits in their head, decays, and is gone. The parts that survive land in five places that do not talk to each other: a contacts app with names and nothing else, a notes app, message history, memory, and the vague sense that they owe someone a call.

This skill is one place for all of it, on their machine, in a file they own.

The design is ported from Amber's identity service with the permission of its authors, Karthik Devarakonda and Sagar Tiwari. Amber is a multi-tenant Cloud SQL service; this is one SQLite file on a laptop. The ideas carried over; the tenancy did not.

The two failure modes

Inventing a fact about a person is worse here than almost anywhere else, because the user will act on it. They will congratulate someone on a job they did not get, or ask after a partner who left. If you did not read it from the database or hear it in this conversation, do not say it. When you write a fact, record how you know it with --source.

Recording a maybe as a fact is the second one. "Thinking about moving to SF" and "moved to SF" are different rows, not different phrasings. That is what --modality is for, and getting it wrong produces a confidently wrong answer rather than a vague one. Default is actual; use planned, hypothetical, desired, available, or declined whenever the user's own wording hedges.

The CLI

Everything goes through people, which ships with this kit. Run it rather than reading the database, and never write SQL against it directly.

people today                      # birthdays and who is slipping
people show maggie                # everything known about one person
people note maggie "got promoted" --dim financial
people log maggie --channel call  # you actually talked
people reconnect                  # who you owe a message
people mute <who> --because "..."  # keep the record, stop the nudges
people unmute <who> | people muted
people rank --dim financial       # who is struggling with what
people search "hiking"
people intro Anthropic            # who could introduce them
people import --mac               # read the macOS Contacts app
people task add maggie "send the book" --due 2026-09-20
people ask maggie                 # what you still do not know about her
people dashboard                  # who you texted, ranked and categorised

people help has the rest. Add --json nowhere: this CLI prints for humans, and you should read its output the same way.

The dashboard

people dashboard serves a page at http://localhost:7373 that answers one question: who have I been texting, most recent first, and what group are they from. It syncs on load and every two minutes, so it is current without being asked.

people dashboard --install puts it behind a LaunchAgent with KeepAlive, so it survives a reboot and a crash and the link always works. --uninstall removes the agent and touches no data.

The categories come from the contact names, not from inference. Somebody who saved a contact as "Sid Chowdhury A2F USC IYA" has already done the labelling, and they know what those letters mean. The dashboard reads the tags out of the name, shows them as badges, and strips them from the displayed name so it reads as a name again. Guessing that "Nemmy" means a residential college would be an invention, so the tag is shown as written.

The one piece of real logic is that a label which is also a given name only counts after the first token. Without that rule "Maia IYA" and "Christian Stiker IYA" both lose their actual names.

New tags go in TAGS and HARD/SOFT in bin/lib/people-dashboard.js. It binds to loopback deliberately: this is the user's entire message history and it does not belong on the local network.

Write as the conversation happens

This is the whole point, and it is the part that gets skipped. When the user mentions something about a person, write it in the same turn, without announcing it. Do not offer to. Do not batch it for the end.

"just got off the phone with maggie, she's stressed about funding"

people log maggie --channel call
people note maggie "stressed about the raise" --dim financial,emotional

Then answer what they actually asked. One line at the end is enough: "noted".

Things that should always produce a write:

The promise is the one that gets missed. Observations hold what is true and interactions hold what happened, and neither has anywhere for "I said I'd send him the book". When the user says they will do something for a named person, that is a people task add, not a note.

people rel maggie mother declan writes both directions, so you never have to add the inverse yourself.

people check-on refuses to run without --because. That is deliberate: a reminder with no reason is a default rather than a decision, and it surfaces in people today with the reason attached so it is actionable rather than nagging.

people update --company is not the same as editing a field. It records the move as an observation, because a job change is news and worth congratulating somebody on, while an overwrite silently destroys the fact that it happened.

Dimensions: pass them, do not let the CLI guess

Every observation is scored across six dimensions: spiritual, emotional, physical, intellectual, social, financial. They each decay at their own rate, because someone's physical situation changes far faster than their spiritual one.

Without --dim, the CLI falls back to keyword matching, which is worse than you at this and often produces nothing. Always pass --dim. Multiple are fine and often right: losing a job is financial,emotional.

That is what makes people rank --dim financial work, and that question is the reason the scoring exists at all.

Circles

A circle is a group: "Hiking", "Church", "Japan 2026", "the Silo team". Members are people in their address book, not accounts, so anyone can be added whether or not they have heard of this tool.

When the user makes a circle, classify it in the same turn, because that is what propagates a fact to every member:

people circle create "Japan 2026" --desc "the trip crew"
people circle classify "Japan 2026" --kind experience --fact "was on the Japan trip in 2026"
people circle add "Japan 2026" maggie declan sagar

--kind is interest, experience, affiliation, or other. The --fact must be a short third-person statement true of every member and naming the topic so it is searchable. It is written onto each member and revoked automatically when membership changes or the circle is deleted.

Before coffee, a call, or a message

Run people show <who> first. It now carries the whole picture in one screen: quick facts, who they are related to, their dates, what you owe them, anything of theirs you still have, and the reason for the next check-in.

Then run people ask <who>, which lists the questions from the template that are still blank for that person. That is what turns the completeness score into something you can act on: it names what to ask about rather than telling you a relationship is 40 percent known. A message that references what someone is actually going through beats a well-written generic one, and this is the difference between a tool that remembers and a tool that autocompletes.

Check the modality on what you find. Never write "congrats on the move" off a row marked planned.

Storage, and the honest limits

Lives in ~/.chewbacca/people/people.db, or $PEOPLE_DIR. It works with no setup and never touches the network.

people sync init <private-git-url> turns the directory into a git repo so it follows them to another machine. Tell them to make the repo private: it is everything they know about everyone. people export writes readable markdown next to the database, and sync push runs it first so the repo carries both.

Events: what actually happened, on the day it happened

A relationship is made of things that happened on days. The store knew a message was sent on a date, but not that the two of them got In-N-Out that night, so a trajectory had nothing in it but message frequency.

people events scan --since 2025-01-01     read the messages, log what happened
people events list "Sagar"                what you did together, newest first
people events reset                       forget which days were read, not the events

scan is a two-stage funnel. A lexicon picks which person-DAYS are worth reading, which cuts hundreds of thousands of messages to a few thousand days; then Claude reads each day's conversation whole and says what happened. The lexicon is deliberately loose, because a day it misses is a day the model never sees, and precision is the model's job rather than the filter's.

The hard part is telling a plan from a memory, and it is the whole reason this is not a regex. "6pm in n out?" and "grabbing in n out now with Shirley" are the same words about opposite facts. That distinction lands in observations.modality, which already existed for exactly this: actual, planned, declined. Only actual is written by default, because a plan that was never confirmed is noise on a timeline of a life.

Two things it does that are easy to miss:

• Other people named as present get the event on their record too, as third_party rather than told_directly, because it came from somebody else's message. A contact saved as "Sagar Tiwari GOAT" still resolves from "Sagar", but only when exactly one person matches. Two people named Chris is a reason to record neither.
• The person's own name is stripped from their own row. "met Sagar at village" reads wrong on Sagar's record, so it becomes "met at village". This is done deterministically after the model answers, not by asking it again more firmly.

State is kept per person-day, so rescanning never re-asks about a day already read and never writes the same dinner twice. Runs take a while: budget roughly one Claude call per dozen days.

It keeps itself up to date. The SessionStart hook runs people texts sync and then people events auto, so new conversations become logged events without anyone asking. auto throttles to once every six hours and caps each run, so twenty sessions in a day cost one bounded scan rather than twenty open-ended ones, and it stays silent unless it actually found something. Tell the user it is already running before offering to run a scan by hand; a full-history backfill is the only thing they need to start themselves.

Relationship graphs over time

Everything else answers "where does this stand today". These three answer "is it getting better or worse", which is the question that changes what they do.

people history "Sagar" --days 365 --steps 12   one person's trajectory
people trend --days 90                         who is warming, who is cooling
people snapshot                                freeze today's numbers

history prints a sparkline for overall standing, warmth, and every dimension that has any evidence, with the start value, the end value, and the direction. --json gives the raw series for charting.

Scores for a past date are recomputed, not looked up. Only observations recorded on or before that date are allowed to count, so a trajectory is available the day the feature is installed rather than a year later. That filter is the whole correctness story: without it a note written last week would land in last year's score with a negative age, and exponential decay run backwards becomes exponential growth. Every relationship would appear to be improving.

snapshot freezes the current numbers into score_history. Use it when they are about to correct or delete old observations and want the curve to remember what it actually knew at the time. history prefers a frozen point over a recomputed one for the same day and says so in its output.

Two honest limits to state when it comes up:

• A flat line usually means missing evidence, not a flat relationship. The curve is only as good as what has been written down. Check the observation count in the footer before reading anything into the shape.
• Warmth needs message history. It decays from the last contact as of each point on the curve, taking the later of a logged interaction and a synced message. Someone whose texts were never imported reads as flat zero. people texts sync --days 3200 backfills the full archive; on a real machine that is around 500k messages and takes under a minute.
• Standing and warmth answer different questions. Warmth moves every time they talk. Standing only moves when something gets written down, so it stays flat for people with no observations no matter how close they are. trend ranks on both together for that reason.

Three things this does not do, which you should say plainly rather than fake:

• No semantic search. Search is full-text, so it matches words, not meaning. "Who is stressed about money" will not find "worried about rent". Use people rank --dim financial for that question instead.
• Syncing a database through git is a compromise. The .db is binary, so git cannot merge it. Editing on two machines without pulling first means one side has to win. Pull before you write. When both sides have already moved, people sync diff compares the exported markdown, which is readable even though the database is not, and the error tells you the two commands that resolve it.
• No integrations. Nothing reads their LinkedIn, Instagram, or X. Contact import is macOS Contacts, vCard, or CSV, and everything else is written by them or by you.

Never

• Never invent a fact about a person, or infer one confidently from a name
• Never record a hedge as actual
• Never overwrite a company or role without people update, which keeps the history
• Never people import --mac unprompted: it reads their entire address book
• Never write the .db with SQL directly; the CLI keeps the search index and the derived scores in step, and raw writes silently desynchronize both
• Never quote a score as if it means something absolute. It is a ranking signal built from tunable guesses, and people dims shows every one of them