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.

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 cut the list.

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 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.

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 classify the note by a fixed keyword rule, or set it explicitly when you know. Pass occurred_at when the statement says an interaction happened earlier ("met Dana last week"); without it such a note is refused rather than dated today, because that date is what the staleness report reads.

Identity is never guessed for a write: status: ambiguous or unconfirmed returns candidates and records nothing — ask the user, then call again with the exact canonical name or a unique alias. Everything recorded commits in one transaction and is audited like the individual tools. For material you extracted or inferred from a transcript rather than a direct statement, use stage_candidates so the user reviews it first.

Return sensitivity-gated signal for client-composed communication advice.

Pass person_id from resolve_person, or person (a name or alias) to resolve inline; an ambiguous name returns candidates instead of guidance.

Store communication philosophy verbatim while auditing lengths only.

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.

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).

Transition one active reminder to completed.

Add a normalized-deduplicated alias to an existing person.

kind is one of nickname, native_script, transliteration, handle, former_name, or other, and defaults to other. The published schema carries the enum, so an unlisted value is refused before the alias is built rather than dropped.

Create a directed relationship between two existing people.

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

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 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 a concise interaction summary after validating all participants.

Correct whitelisted assertion fields in place with before/after audit.

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 fact's.

Both rows commit together under one logical transaction, or neither commits.

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 one shortest relationship path, or a structured not-connected result.

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

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 one person's stored facts, traits, and observations plus how they relate.

Pass person_id from resolve_person, or person (a name or alias) to resolve inline.

Use this before proposing maintenance. signals names pairs of records that share a predicate or category and says how they stand — duplicate_fact, restated_fact, contradictory_fact, succeeding_fact, duplicate_trait, divergent_trait — comparing normalized values and inclusive validity periods only. It decides nothing: reading the evidence and proposing a correct_record, a supersede_fact, or a merge_people for the user to approve is your job, and several observations supporting one trait are separate evidence rather than duplicates.

This read never writes. Sensitive and restricted records are never returned, and a trait names only evidence that is itself ordinary. An unknown or removed person returns found: false rather than an error.

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).

Merge a duplicate person into a primary person atomically.

Hard-delete a person or record and redact identifying audit history.

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 and never weakens the duplicate rule for later calls. It is also the only way past source_previously_redacted after a hard forget — and for mbox, which is read from a path and cannot be resubmitted as inline content, the only way at all.

Stage agent-extracted people, interactions, affiliations, facts, observations, traits, and relationships.

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/to_ref and are ordinary-disclosure only: omit a relationship the user would consider sensitive or restricted rather than staging it.

References are batch-local; raw notes and source text must not be included in candidate fields. A request using observation, trait, or relationship is bounded to 500 candidates, a 128-character source, 1 MiB of candidate JSON, and 8 KiB per string.

A trait may name the records it was drawn from. Give a supporting observation or interaction any short evidence_ref label of your own and list those labels in the trait's evidence_refs; use evidence_ids for records already stored. Evidence must be about the trait's own person, and one trait cites at most 32 references and ids combined, each at most 256 characters.

source_kind optionally records an import receipt for this batch. It is a machine category such as meeting_transcript, at most 128 characters of letters, digits, ., _, -, or / — never a person, a title, or a description; put any human wording in label instead. If you can compute a SHA-256 over the exact source artifact, pass it as content_digest (64 lowercase hex characters) so re-importing that same source can be detected; without one, no duplicate detection is promised. extraction_fingerprint is optional and should be omitted unless you have explicit, bounded configuration semantics for it. None of these fields may carry source text.

Return staged candidates and statuses for one batch.

Commit accepted people and resolvable interactions idempotently.