docs(personal): restructure bourdain docs to separate system prompt
Refactor documentation to distinguish character reference from AI system prompt. Removed user context and persona definitions. System prompt instructions moved to prompts/personal/bourdain.md.
This commit is contained in:
95
docs/tools/kairos.md
Normal file
95
docs/tools/kairos.md
Normal file
@@ -0,0 +1,95 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user