# Kairos

> Calendar, events, tasks, and contacts — Robert's personal productivity system of record.

- **MCP server name:** `kairos`
- **Prompt snippet:** [prompts/tools/kairos.md](../../prompts/tools/kairos.md)

## What It Is

Kairos covers Robert's calendars, events, tasks, and contacts. It's the system of record for personal scheduling and relationship logistics — the layer that holds the actual calendar entries, the actual contact records, the actual task lists. Tools are async, use ISO 8601 for dates/datetimes, and record Prometheus metrics via `record_tool_call()`.

Kairos holds the **raw records**; Neo4j holds the **agents' interpretation** layered on top. For contacts that means Kairos has the phone numbers and emails, while Shawn's Neo4j `Contact` nodes hold the relationship strength, last-contact tracking, and notes. Both are legitimate; they serve different purposes.

## MCP Capabilities

Kairos exposes async MCP tools across three areas. Coverage is incremental — check `tools/list` for the current set; the table below reflects what's available now.

### Calendar (6 tools)

| Tool | Mutating | Purpose |
|---|---|---|
| `list_calendars` | No | List calendars with sync/capability metadata |
| `list_events` | No | List events with optional calendar/date filters |
| `get_event` | No | Fetch a single event with full detail |
| `create_event` | Yes | Create an event on a calendar |
| `update_event` | Yes | Partial update of an event |
| `delete_event` | Yes | Delete an event |

### Tasks (5 tools)

Note: "Projects" in Kairos aren't a separate model — a project is a `Task` with `task_type='PROJECT'`. Project features (subtasks, dependencies, milestones, Gantt dates, comments, attachments) live on the Task model.

| Tool | Mutating | Purpose |
|---|---|---|
| `list_tasks` | No | Filter by status, priority, calendar, parent, date, starred |
| `get_task` | No | Single task incl. subtask and dependency IDs |
| `create_task` | Yes | Create a task or subtask |
| `update_task` | Yes | Partial update |
| `delete_task` | Yes | Delete task (cascades to subtasks) |

### Contacts (8 tools)

| Tool | Mutating | Purpose |
|---|---|---|
| `list_contacts` | No | Search across name, email, phone, org |
| `get_contact` | No | Contact with phones/emails/addresses |
| `create_contact` | Yes | Create a contact |
| `update_contact` | Yes | Partial update |
| `delete_contact` | Yes | Delete contact (cascade) |
| `add_contact_phone` | Yes | Add a phone number |
| `add_contact_email` | Yes | Add an email address |
| `add_contact_address` | Yes | Add a postal address |

### Coverage roadmap (not yet exposed via MCP)

The Kairos web UI supports more than the MCP currently exposes. Known gaps:

- **Calendars** — create, update, delete, sync trigger
- **Tasks** — dependency add/remove, comments CRUD, attachments list/delete, alerts, templates, project helpers
- **Contacts** — phone/email/address update and delete, address book operations
- **Cross-cutting** — tags CRUD, notifications, sync observability (ICS imports, sync logs)

If MCP discovery doesn't surface a tool you expected, MCP coverage may not include it yet. Surface the gap rather than confabulating a workaround.

## Who Uses Kairos

- **Shawn** — heavy, primary. Contact records, calendar events, communication tracking. Shawn's Neo4j Contact/Event/Communication nodes hold the *interpretation* (relationship strength, follow-up state); Kairos holds the actual entries.
- **Watson** — read-heavy. Pulls contact context (who Robert is talking about) and event history (life events, important dates) to inform emotional/relational work. Writes only when adding life events Watson is tracking.
- **Cristiano** — calendar only. Match dates, tournament schedules. Reads to know what's coming up; writes when Robert decides to attend something.
- **Nate** — calendar. Trip windows, blackout dates, scheduling around travel.

Other agents may read Kairos when their work intersects with personal logistics, but the three above are the primary users.

## What It's Good For

- Looking up who someone is before drafting a message
- Checking the calendar for conflicts before committing
- Creating events, tasks, contact records that need to live in the canonical store
- Pulling contact context (timezone, notes, history) for any conversation about a person
- Task tracking that needs to persist (vs. transient `Task` Neo4j nodes for cross-domain context)

## What It's Not Good For

- Emotional/relational interpretation — that's Watson's Neo4j nodes
- Cross-domain linking — Kairos is its own database; the cross-references between contacts, trips, training, finance, etc. live in Neo4j
- Synthesis or analysis — Kairos returns records; you interpret them
- Engineering or work logistics — Kairos is personal-scope; work and engineering have their own tools

## Known Gotchas

- **Mutating tools touch real records.** A `delete_contact` is not undone by walking it back in conversation. Confirm before mutating, especially for cascades (deleting a task cascades to subtasks; deleting a contact cascades to phones/emails/addresses).
- **Dependency between Kairos and Neo4j writes.** When creating a `Contact` in Kairos, also update Shawn's Neo4j `Contact` node if relationship-interpretation fields apply (importance, last_contact, notes). Otherwise the two stores drift.
- **ISO 8601 dates and datetimes.** Always pass dates and datetimes in ISO format. Time zones matter — specify explicitly when not in Robert's local time.
- **Tasks don't have a separate Project entity.** Projects are Tasks with `task_type='PROJECT'`. Use `list_tasks` with appropriate filtering, not a hypothetical `list_projects`.
- **Coverage is incremental.** The set of mutating operations expands over time. Don't assume a missing tool means the operation isn't supported in the underlying system — it may just not have an MCP wrapper yet.