People Context

Return one group and a bounded page of its recorded memberships. These are recorded memberships only: sharing a group is context, not proof that members know each other. Sensitive and restricted groups read as `found: false`, and sensitive or restricted memberships are omitted without affecting `truncated`.

Assemble a minimal-disclosure context bundle for one person. Pass `person_id` from `resolve_person`, or `person` (a name or alias) to resolve inline: an ambiguous name returns the candidates instead of context. Returns narrow identity fields, active relationships and affiliations, and one ranked facts/interactions slice capped by `max_items`. Set `include_communication=true` (or a `purpose` mentioning communication) to include communication traits. Sensitive and restricted records are never returned by this ordinary tool, and leave no trace that they exist. `truncated` says the item budget cu…

Return one person's recent history, newest first, as a bounded chronology. Pass `person_id` from `resolve_person`, or `person` (a name or alias) to resolve inline. Entries project durable records — interactions, observations, facts, affiliations, relationships, and traits — with the stored timestamp each was placed by and which field that was. Sensitive and restricted records are never returned by this ordinary tool, and a trait names only evidence that is itself ordinary. An unknown or removed person returns `found: false` rather than an error.

Return active relationship structure around one person, capped for bounded disclosure. Pass `person_id` from `resolve_person`, or `person` (a name or alias) to resolve inline.

Return context that may include sensitive and restricted records. This tool is absent from the normal MCP surface. The operator must restart the server with PEOPLE_CONTEXT_MCP_ENABLE_SENSITIVE=1 before a client can discover or invoke it.

Return people you have not interacted with recently, using ordinary interactions only.

Extract and atomically stage header-only candidates from a supported source without bodies. Accepted `source_type` values are `email`, `mbox`, `vcard`, `ics`, `linkedin`, `outlook`, and `whatsapp`. `self_sender` is an optional chat-export label for the user, such as a display name or a bare phone number, used to omit the user's own messages. A `path` import records a receipt for the file it read, so importing that exact file again reports the existing batch instead of staging a second copy. `forced` says the repeat is intentional: it stages the same content as a distinct processing session a…

Return a bounded page of one person's recorded group memberships with each group. Pass `person_id` from `resolve_person`, or `person` (a name or alias) to resolve inline. Only ordinary memberships in ordinary groups are returned. An unknown or removed person returns `found: false`.

List pull-based reminders, due-dated first and communication notes last. Filter by `person_id`, or by `person` (a name or alias) resolved inline; omit both for every person's reminders.

Merge a duplicate person into a primary person atomically.

Return traits, friction history, reminders, and the user's communication philosophy for a person.

Return a minimal-disclosure context bundle for a known person.

Create or update a person record, including aliases and summary.

Resolve a name, nickname, or partial reference to one or more known people.

Record a time-aware fact about an existing person. `sensitivity` defaults to `personal`; `sensitive` and `restricted` records are withheld from ordinary reads. Prefer `remember` for a single statement named by a person's name.

Record a concise interaction summary after validating all participants.

Record a subjective observation, separate from disclosed context.

Record a derived trait with validated category and provenance. `category` is one of `communication_style`, `temperament`, `values`, `preference`, `topics_to_avoid`, or `other`. Cite the observation or interaction it rests on in `evidence_note` or `evidence_ids` where you can.

Record one thing the user stated about one person, in a single call. Use this when the user directly tells you something durable — "Alice from Acme prefers short emails", "Bob is my manager", "I had coffee with Dana today". `person` is the name as the user said it: it is resolved first, and a new person is created only when nobody matches. `org`/`role` record an affiliation, `relationship` records how the user relates to them (e.g. `manager_of`, `friend_of`, from the user's point of view), and `note` records the statement as a `fact`, `trait`, or `interaction`. Leave `kind` as `auto` to class…

Create a new person or update the existing one matching `name`. Use this to durably record someone the user talks about. `aliases` is a list of `{value, kind?, lang?, script?}` objects (kinds: nickname, native_script, transliteration, handle, former_name, other); new aliases are merged into an existing record. Set `summary` to describe who they are, and `is_self=True` only for the user themselves. Returns the person and whether it was created.

Resolve a name, nickname, or partial reference to candidate people. Call this first whenever the user mentions someone, before asking who they mean. Returns ranked candidates with a score and match reason. If two or more candidates are close, the result is flagged `ambiguous` and all are returned so you can disambiguate with extra context or a clarifying question. An empty candidate list means no confident match — use `remember` or `remember_person` to create a new record. Put distinguishing context in `hints` (`org`, `role`, `relationship`) rather than in `query`.

Return staged candidates and statuses for one batch. The response carries a `batch_digest`. Pass it back to `amend_candidate`, `withdraw_candidates`, or `commit_import` to have the action refused if somebody else changed the batch after this read.

Free-text search over stored people for browsing or lookup. Broader than `resolve_person`: use this to list who is known that matches a query, rather than to pin down a single identity. Returns ranked candidates.

Search active people and safe interaction summaries by multilingual semantic similarity. This optional local search requires an explicit `pctx reindex --semantic` first. It never downloads a model while serving a query and refuses to mix vectors from different model revisions.

Create an affiliation, resolving an org id or get/creating by name.

Store communication philosophy verbatim while auditing lengths only.

Create a directed relationship between two existing people.

Create a reminder for an existing person. `kind` is `follow_up` (dated, something to do), `occasion` (a date that recurs), or `communication_note` (undated guidance surfaced with the person's context).

Stage agent-extracted people, interactions, records, relationships, groups, and memberships. Candidate types are `person`, `interaction`, `affiliation`, `fact`, `observation`, `trait`, `relationship`, `group`, and `group_membership`. Use this after extracting concise candidates from user-provided notes, meeting transcripts, or other agent-visible text. Distinguish what was stated (`fact`), what happened in this source (`observation`), and what you inferred (`trait`, which requires an explicit `confidence` and a concise `evidence_note`). Relationship candidates carry batch-local `from_ref`/`t…

Close a fact that was true and open its replacement from an effective date. Use this when a stored value was historically correct and the real-world state changed; `correct_record` remains the tool for a value that was simply wrong. The old fact keeps its person, predicate, value, and provenance and is closed the day before `effective_from`; the replacement inherits the old assertion's original end date, so a bounded claim is never widened into an open-ended one. Person, predicate, and the replacement's end date cannot be changed here. Omitting `confidence` or `sensitivity` inherits the old f…

Return ordinary birthdays and dated active reminders inside an inclusive upcoming window. Optionally narrow to one person by `person_id` or by `person` (a name or alias).

Drop staged candidates from consideration, returning the revised batch. A withdrawn candidate stays listed as `rejected` so the user can see what was dropped, and is never committed. Nothing else about the batch changes.