# Contacts Guide

## What a Contact Is

A contact is a Person node in Maxy's memory graph. Each person has a first name and at least one identifier — email address, phone number, or both. Optional fields include last name and job title. Contacts are linked to conversations, other people, and business context.

## Adding a Contact

Tell Maxy naturally:

- "Add John Smith to my contacts — he's a potential client I met at the conference"
- "Create a contact for sarah@acme.com, her name is Sarah Chen, she's the head of procurement at Acme"
- "Add Hazel to contacts, phone +27747309676, she's a virtual assistant"

Maxy will extract the details and confirm the record before saving.

Required: first name and at least one of email or phone number. Everything else is optional but useful.

## Looking Up a Contact

Ask naturally:

- "What do you know about John Smith?"
- "Look up Sarah Chen"
- "Find the contact from Acme procurement"
- "Look up +27747309676"

Maxy searches by name, email, phone number, or any detail you provide.

## Updating a Contact

Tell Maxy what changed:

- "Update John Smith's email to john@newcompany.com"
- "Add a note to Sarah Chen's record: prefers evening calls"
- "John Smith is now at Horizon Capital, not Acme"

## Listing Contacts

- "List all my contacts"
- "Show me everyone from Acme"
- "Who are my contacts in fintech?"

## The Waitlist

For businesses using Maxy's public agent: when a visitor expresses interest in signing up, the public agent collects their name and email in conversation. The waitlist plugin's scheduled extraction job processes these conversations and creates Person nodes with status `waitlist`.

To review the waitlist: "Show me the waitlist" or "Who's on the waitlist?"

## Exporting Contact Data (GDPR Subject Access)

When a person requests a copy of all data held about them, ask Maxy:

- "Export all data we hold on john@example.com"
- "Show me everything we know about +447700900123"

Maxy gathers the Person record, access credentials, conversation history, and emails into a single structured document. The output is self-contained — it can be handed directly to the data subject to satisfy an Article 15 request.

## Erasing Contact Data (GDPR Right to Erasure)

When a person requests deletion of all their data, ask Maxy:

- "Delete all data we hold on john@example.com"
- "Erase everything for Sarah Chen"

Maxy first shows a preview of what would be deleted (counts per data type). Confirm the deletion to proceed. The erasure cascade covers:

- The Person record itself
- All access credentials (AccessGrant nodes)
- Conversations and messages attributed to the contact
- Emails sent to or from the contact's email address

The deletion is permanent and irreversible. A receipt is returned listing exactly what was removed.

Note: server logs may contain residual references to the contact's identifiers. Manual log review is recommended for complete erasure.

## Stored Fields

| Field | Description |
|-------|-------------|
| `givenName` | First name (required) |
| `familyName` | Last name (optional) |
| `email` | Email address (identifier — at least one of email or telephone required; used to deduplicate) |
| `telephone` | Phone number (identifier — at least one of email or telephone required; used to deduplicate) |
| `jobTitle` | Job title or role |
| `source` | Where this contact came from (e.g. "public.maxy.bot", "telegram", "manual") |
| `status` | Contact status (e.g. "active", "prospect", "waitlist") |
| `createdOn` | When the record was created |
