Contacts

Document who people are, their relationship to you, and how to communicate with them.

Purpose

The contacts database helps the AI understand who's emailing you and how to respond. Instead of treating every email as anonymous, the AI can tailor its approach.

Contact Structure

{
  "email": "[email protected]",
  "name": "Sarah Chen",
  "company": "Big Client Inc",
  "role": "VP of Engineering",
  "relationship": "client",
  "tone": "professional, formal",
  "tags": ["vip", "enterprise", "technical"],
  "account_id": "work-account-uuid",
  "notes": "Always CC her assistant [email protected]. Prefers detailed technical responses. Timezone: PST.",
  "last_contact": "2025-01-15"
}

Field Reference

Field	Description	Example
`email`	Primary email (unique identifier)	[email protected]
`name`	Full name or preferred name	Sarah Chen
`company`	Their organization	Big Client Inc
`role`	Job title or role	VP of Engineering
`relationship`	Your relationship type	client, vendor, colleague, family
`tone`	How to communicate	casual, professional, formal
`tags`	Categorization labels	["vip", "enterprise"]
`account_id`	Which account they're associated with	work-account-uuid
`notes`	Free-form context	Any relevant info
`last_contact`	ISO date of last interaction	2025-01-15

Relationship Types

Common relationship values:

customer — Someone who pays you
lead — Potential customer
client — Ongoing business relationship
vendor — Someone you pay
partner — Business partnership
colleague — Coworker or team member
friend — Personal friend
family — Family member

Tone Guidelines

Be specific about communication style:

// Good - specific and actionable
"tone": "casual, uses first name, occasional humor is fine"
// Bad - too vague
"tone": "normal"

Tone Examples

"casual, friendly, first name basis"
"professional but warm, can use some personality"
"formal, always use full name and title"
"brief and direct, no small talk"
"detailed technical responses welcome"

Using Tags

Tags help categorize contacts and can trigger special handling:

{
  "tags": ["vip", "enterprise", "techdeals", "ltd"]
}

Useful tag categories:

Priority: vip, important, low-priority
Source: techdeals, website, referral
Type: enterprise, smb, individual
Status: active, churned, trial

When to Add Contacts

Add a contact when:

You've exchanged multiple emails with someone
They're a VIP who needs special treatment
They have specific communication preferences
You want the AI to remember context about them

Quality Over Quantity

Don't try to add everyone. Focus on contacts where the AI would benefit from knowing more context. Random one-time emailers don't need entries.

Example Entries

VIP Client

{
  "email": "[email protected]",
  "name": "Michael Roberts",
  "company": "Enterprise Corp",
  "role": "CEO",
  "relationship": "client",
  "tone": "professional, concise, always address concerns immediately",
  "tags": ["vip", "enterprise", "decision-maker"],
  "notes": "Responds quickly to urgent matters. Prefers bullet points. His EA is [email protected] - CC her for scheduling."
}

TechDeals Customer

{
  "email": "[email protected]",
  "name": "Alex",
  "relationship": "customer",
  "tone": "casual, friendly",
  "tags": ["techdeals", "ltd", "2x"],
  "notes": "Purchased LTD 2X via TechDeals. Had redemption issues - email typo pattern."
}

Team Member

{
  "email": "[email protected]",
  "name": "Dev",
  "company": "Acme Corp",
  "role": "Developer",
  "relationship": "colleague",
  "tone": "casual, direct",
  "tags": ["team", "technical"],
  "notes": "Handles technical issues. CC for debugging and video problems."
}

File Location

~/.config/pontius/knowledge/contacts/contacts.json

How AI Uses Contacts

When the AI sees an incoming email, it:

Checks if the sender is in the contacts database
If found, uses the relationship and tone to inform response style
Applies any notes or special handling
Uses tags to identify patterns (e.g., all "vip" contacts get priority)