# 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?"

## Deleting a Contact

To remove a single contact from the graph:

- "Delete Dan from my contacts"
- "Remove the duplicate contact for Sarah Chen"
- "Delete the contact with email dan@example.com"

Maxy will confirm which Person record matches, then remove the Person node and its direct relationships (e.g. links to conversations, other people) using a graph detach-delete. The contact is gone after confirmation — this cannot be undone.

This is different from GDPR erasure (`contact-erase`). Deleting a contact removes the Person node from the graph only. GDPR erasure cascades across all data stores — access credentials, conversations, messages, and emails — to satisfy an Article 17 right-to-erasure request. Use "delete" for routine contact cleanup; use "erase all data" when fulfilling a data subject's erasure request.

## 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", "booked") |
| `createdOn` | When the record was created |