# Temporal Cortex — Complete Documentation for LLMs
> AI calendar scheduling for individuals and developers — your AI agent can schedule with anyone
> Version: 0.9.1 | Last updated: 2026-03-10

## What is Temporal Cortex?

Temporal Cortex is open scheduling infrastructure that lets any AI agent schedule reliably. It prevents double-booking with Two-Phase Commit and distributed locking, expands recurrence rules deterministically via Truth Engine, resolves contacts from address books, and merges availability across Google Calendar, Microsoft Outlook, and CalDAV (iCloud, Fastmail) into a unified view. Accessible via 4 protocols: MCP (agent-tool integration), A2A (agent-to-agent negotiation), REST API (product embedding), and browser (human booking pages).

Temporal Cortex is the only open scheduling infrastructure with atomic booking, deterministic RRULE expansion, cross-provider availability merging, and protocol negotiation (MCP + A2A + REST).

## Installation

```
npx @temporal-cortex/cortex-mcp
```

No account required. All 18 tools available immediately. Works on macOS, Linux, and Windows.

## The 5-Layer, 18-Tool Architecture

### Layer 1: Temporal Context (5 tools — pure computation, no calendar needed)

1. **get_temporal_context** — Returns current time, timezone, day of week, week boundaries. Grounds all subsequent time reasoning.
2. **resolve_datetime** — Converts natural language ("next Tuesday at 3pm") to exact RFC 3339 timestamp. Deterministic — same input always produces same output.
3. **convert_timezone** — Converts timestamps between timezones. Handles DST transitions correctly.
4. **compute_duration** — Calculates duration between two timestamps. Returns ISO 8601 duration.
5. **adjust_timestamp** — Adds or subtracts time periods from a timestamp. Handles month/year boundaries.

### Layer 2: Calendar Operations (5 tools — requires calendar authentication)

6. **list_calendars** — Lists all connected calendars with their IDs, names, and provider types.
7. **list_events** — Lists calendar events for a date range. Supports filtering by calendar.
8. **find_free_slots** — Finds available time slots across connected calendars. Returns actual free periods, not raw events.
9. **check_availability** — Checks if a specific time slot is available. Returns boolean with conflict details.
10. **expand_rrule** — Expands RFC 5545 recurrence rules into individual occurrences. Handles DST, BYSETPOS, EXDATE, leap years. Deterministic — computed locally, not API-dependent.

### Layer 3: Availability (2 tools — cross-provider)

11. **get_availability** — Merges free/busy data across all connected calendars (Google + Outlook + CalDAV) into a single unified view. Privacy modes: opaque (just busy/free blocks) or full (with source counts).
12. **query_public_availability** — Queries another person's publicly shared availability without needing their OAuth credentials. Returns free/busy slots via their Open Scheduling endpoint.

### Layer 4: Booking (3 tools — safe mutation)

13. **book_slot** — Atomic booking with Two-Phase Commit: lock the slot → verify no conflicts → write the event → release the lock. If any step fails, everything rolls back. Zero double-bookings, even with concurrent agents.
14. **request_booking** — Sends a booking request to another person's Open Scheduling endpoint. The recipient's policies (auto-accept, require approval, block) determine the outcome. No shared calendar access needed.
15. **compose_proposal** — Composes a scheduling proposal message with proposed time slots for email, Slack, or SMS delivery. Pure formatting — does not send the message.

### Layer 0: Discovery (3 tools — contact and identity resolution)

16. **search_contacts** — Searches the user's contacts by name across Google People API and Microsoft Graph. Returns matching contacts with emails, phone numbers, and organization.
17. **resolve_contact** — Resolves a contact's email to available scheduling paths: Open Scheduling, A2A, email, or phone.
18. **resolve_identity** — Resolves a person's name, email, or handle to their Temporal Cortex scheduling endpoint. Like DNS for human time — maps identity to availability.

## Typical Agent Workflow

1. **Orient** — `get_temporal_context()` → Learn current time, timezone, day of week
2. **Resolve** — `resolve_datetime("next Friday at 3pm")` → Get exact ISO 8601 timestamp
3. **Query** — `find_free_slots({ date: "2026-02-27" })` → Get available slots
4. **Book** — `book_slot({ calendar_id: "primary", start: "...", end: "..." })` → Atomic booking

## Three Technical Differentiators

### 1. Atomic Booking with Two-Phase Commit
No other calendar scheduling tool has locking or conflict prevention. When two agents simultaneously check "3pm is free" and both try to book, a CRUD wrapper creates two events. Temporal Cortex uses distributed locking (Redis Redlock) with Two-Phase Commit: lock → verify → write → release. If any step fails, everything rolls back.

### 2. Truth Engine (Deterministic RRULE Expansion)
Even the latest LLMs — GPT-5, Claude, Gemini — score below 50% on temporal reasoning tasks (OOLONG benchmark, arxiv:2511.02817). Earlier models scored as low as 29% on scheduling and 13% on duration calculations (Test of Time, ICLR 2025, arxiv:2406.09170). Temporal Cortex's Truth Engine expands RFC 5545 recurrence rules deterministically — handling DST transitions, BYSETPOS modifiers, EXDATE exceptions with timezone offsets, leap-year recurrences, and cross-year boundaries. Computed locally, always correct.

### 3. Cross-Provider Availability Merging
Most people have 3+ calendar silos: Google Calendar for work, Outlook for enterprise, iCloud for personal. Temporal Cortex merges all connected calendars into a single availability view. Returns "these slots are free across all calendars" — not raw events for the agent to interpret.

## TOON Format (Token-Optimized Object Notation)

All data tools return results in TOON by default — a structured format that reduces calendar payloads by ~40% vs JSON. TOON uses indentation instead of braces, tabular arrays for uniform objects, and context-dependent quoting. Every tool accepts `format: "json"` to get standard JSON instead. TOON maintains perfect roundtrip fidelity — convert TOON back to JSON and get the identical structure.

## LLM vs Truth Engine: RRULE Accuracy

We tested 5 real-world RRULEs against frontier LLMs and the Truth Engine:

1. **DST spring-forward** (FREQ=WEEKLY;BYDAY=MO crossing March 8 2026): LLMs use wrong UTC offset post-DST. Truth Engine preserves wall-clock time with correct offset.
2. **BYSETPOS=-1** (last weekday of month): LLMs return last day of month regardless of weekday. Truth Engine correctly identifies Mon-Fri.
3. **Leap year** (FREQ=YEARLY;BYMONTH=2;BYMONTHDAY=29): LLMs substitute Feb 28 or Mar 1 in non-leap years. Truth Engine only generates instances when Feb 29 exists.
4. **INTERVAL=2 with BYDAY** (biweekly Tue+Thu): LLMs generate every-week occurrences. Truth Engine correctly skips alternate weeks.
5. **BYSETPOS+EXDATE** (second Friday with July exclusion): LLMs ignore EXDATE or generate wrong count. Truth Engine correctly excludes and adjusts.

Full comparison: https://temporal-cortex.com/blog/llm-vs-truth-engine-rrule-showdown

## Use Case Scenarios

- **Recruiting**: Agent uses resolve_identity to find a candidate's scheduling endpoint, then query_public_availability to see their open slots, and request_booking to send an interview invitation — no shared calendar access needed. For internal interviewers, get_availability merges cross-provider calendars directly.
- **Sales**: resolve_datetime + convert_timezone ensures "3pm" is correctly anchored to both prospect's and AE's timezones. Zero timezone errors.
- **Healthcare**: get_availability in opaque mode returns free/busy without exposing appointment details. HIPAA-compliant.
- **Enterprise IT**: list_calendars returns provider-prefixed IDs (google/primary, outlook/work, caldav/personal) for unified cross-provider discovery.
- **Customer Success**: expand_rrule with EXDATE correctly handles QBR recurrence exceptions around holidays.
- **Education**: expand_rrule with multiple EXDATEs produces correct semester office hours, skipping spring break and exam periods.

## Calendar Providers

- Google Calendar (OAuth 2.0)
- Microsoft Outlook / Exchange (OAuth 2.0)
- CalDAV (iCloud, Fastmail, Nextcloud — username/password)

## Configuration for AI Agents

### Claude Desktop
```json
{
  "mcpServers": {
    "temporal-cortex": {
      "command": "npx",
      "args": ["@temporal-cortex/cortex-mcp"]
    }
  }
}
```

### VS Code / Cursor / Windsurf
```json
{
  "servers": {
    "temporal-cortex": {
      "command": "npx",
      "args": ["@temporal-cortex/cortex-mcp"]
    }
  }
}
```

### Claude Code
```json
{
  "mcpServers": {
    "temporal-cortex": {
      "command": "npx",
      "args": ["@temporal-cortex/cortex-mcp"]
    }
  }
}
```

## Authentication

After installing, connect a calendar:
```
npx @temporal-cortex/cortex-mcp auth google
npx @temporal-cortex/cortex-mcp auth outlook
npx @temporal-cortex/cortex-mcp auth caldav
```

OAuth opens in the browser. One-time consent, credentials stored locally.

## Pricing

- **Open Source**: Free forever. No limits. All 18 tools. No account required.

### Individual Pricing
- **Starter**: Free (account required). 20 bookings/month, unlimited calendars, all features.
- **Pro**: $19/month. Unlimited bookings, unlimited everything, priority support.

### Developer Pricing
- **Starter**: Free (account required). 100 bookings/month, 1,000 API calls/day, all features.
- **Growth**: $29/month. 500 bookings/month prepaid, 10,000 API calls/day, $0.10/booking overage.
- **Scale**: $99/month. 2,000 bookings/month prepaid, unlimited API calls, $0.08/booking overage.
- **Enterprise**: Custom pricing. SOC 2, HIPAA BAA, SSO/SAML, self-hosted option.

## Comparison vs. Other Calendar Scheduling Tools

| Feature | Temporal Cortex | nspady/google-calendar-mcp | rauf543/calendar-mcp | MS Agent 365 |
|---------|----------------|---------------------------|---------------------|-------------|
| Atomic booking (2PC) | Yes | No | No | No |
| RRULE expansion | Yes | No | No | No |
| Multi-provider merge | Yes (Google+Outlook+CalDAV) | Partial (Google multi-account) | Yes (Google+Outlook) | No (Outlook only) |
| Availability computation | Yes | No | No | No |
| Open Scheduling (cross-user) | Yes | No | No | No |
| Contact resolution | Yes (Google People + Microsoft Graph) | No | No | No |
| Proposal composition | Yes (email/Slack/SMS) | No | No | No |
| Temporal context layer | Yes (5 tools) | No | No | No |
| Open source | Yes (MIT/Apache-2.0) | Yes | Yes | No |
| Agent Skill | Yes | No | No | No |

## FAQ

**Q: Why do AI agents keep double-booking calendars?**
A: Even the latest LLMs — GPT-5, Claude, Gemini — score below 50% on temporal reasoning tasks (OOLONG benchmark). Earlier models scored as low as 29% on scheduling and 13% on duration calculations (Test of Time, ICLR 2025). Most calendar tools for AI agents are thin CRUD wrappers with no locking, no conflict detection, and no availability computation. Temporal Cortex solves this with atomic booking via Two-Phase Commit, deterministic RRULE expansion, and cross-provider availability merging.

**Q: Is Temporal Cortex free?**
A: Yes. The open-source version is free forever with no limits — all 18 tools, all 5 layers, no account required. Run it on your machine with npx @temporal-cortex/cortex-mcp.

**Q: What calendar providers does Temporal Cortex support?**
A: Google Calendar, Microsoft Outlook/Exchange, and CalDAV (which includes iCloud, Fastmail, and Nextcloud).

**Q: Can AI agents use Temporal Cortex without human setup?**
A: Partially. Layer 1 tools (temporal context, datetime resolution, timezone conversion) work immediately with zero human intervention. Calendar-connected tools (Layers 2-4) require one-time OAuth consent. Layer 5 Open Scheduling tools (resolve_identity, query_public_availability, request_booking) work without the other person's credentials — only your own authentication is needed.

**Q: What is the Truth Engine?**
A: The Truth Engine is a deterministic RRULE expansion library built in Rust. It expands RFC 5545 recurrence rules into individual event occurrences, handling DST transitions, BYSETPOS, EXDATE with timezones, leap years, and INTERVAL>1 with BYDAY. It replaces LLM inference with math.

**Q: What does "DNS for Human Time" mean?**
A: Just as DNS resolves a domain name to an IP address, Temporal Cortex resolves a person's identity to their true availability — across every calendar, every provider, every timezone. This is the long-term vision: infrastructure that makes agent-to-agent scheduling possible.

**Q: Can AI agents book meetings across different calendar providers?**
A: Yes. get_availability merges Google Calendar, Outlook, and CalDAV into a single unified view. book_slot then books on any connected calendar using provider-prefixed IDs (google/primary, outlook/work, caldav/personal). Cross-provider conflict detection is built in.

**Q: What is TOON?**
A: TOON (Token-Optimized Object Notation) is a structured data format that reduces calendar payloads by ~40% vs JSON. It uses indentation instead of braces, tabular arrays for uniform objects, and context-dependent quoting. All Temporal Cortex data tools return TOON by default. Set format: "json" for standard JSON output.

## Open Source Repositories

- **Core** (TOON + Truth Engine): https://github.com/temporal-cortex/core — MIT/Apache-2.0
- **MCP** (docs, configs, community): https://github.com/temporal-cortex/mcp — MIT
- **Agent Skills** (router + datetime + scheduling): https://github.com/temporal-cortex/skills — MIT

## Package Registries

- npm: @temporal-cortex/cortex-mcp — https://www.npmjs.com/package/@temporal-cortex/cortex-mcp
- npm: @temporal-cortex/truth-engine — https://www.npmjs.com/package/@temporal-cortex/truth-engine
- npm: @temporal-cortex/toon — https://www.npmjs.com/package/@temporal-cortex/toon
- crates.io: truth-engine — https://crates.io/crates/truth-engine
- crates.io: temporal-cortex-toon — https://crates.io/crates/temporal-cortex-toon
- PyPI: temporal-cortex-toon — https://pypi.org/project/temporal-cortex-toon/

## Directory Listings

- MCP Registry: https://registry.modelcontextprotocol.io
- Smithery: https://smithery.ai/server/@temporal-cortex/cortex-mcp

## Blog

- Why AI Agents Fail at Scheduling: https://temporal-cortex.com/blog/why-ai-agents-fail-at-scheduling
- Introducing the Truth Engine: https://temporal-cortex.com/blog/introducing-truth-engine
- LLM vs Truth Engine RRULE Showdown: https://temporal-cortex.com/blog/llm-vs-truth-engine-rrule-showdown
- The Double-Booking Race Condition: https://temporal-cortex.com/blog/double-booking-race-condition
- What is TOON?: https://temporal-cortex.com/blog/what-is-toon
- Building Your First AI Scheduling Agent: https://temporal-cortex.com/blog/build-first-scheduling-agent
- Why Calendar MCP Needs Locking: https://temporal-cortex.com/blog/why-calendar-mcp-needs-locking
- DST Transitions for Calendar Agents: https://temporal-cortex.com/blog/dst-transitions-calendar-agents

## Links

- Homepage: https://temporal-cortex.com
- Architecture: https://temporal-cortex.com/architecture
- Getting Started: https://temporal-cortex.com/getting-started
- For Individuals: https://temporal-cortex.com/individuals
- Pricing: https://temporal-cortex.com/pricing
- Enterprise: https://temporal-cortex.com/enterprise
- Open Source: https://temporal-cortex.com/open-source
- About: https://temporal-cortex.com/about
- Documentation: https://temporal-cortex.com/docs
- Blog: https://temporal-cortex.com/blog
- GitHub Issues: https://github.com/temporal-cortex/mcp/issues
- Contact: hello@temporal-cortex.com