koios/docs/tools/kairos.md

Kairos

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

• MCP server name: kairos
• Prompt snippet: 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.