temporal-cortex

Original source / Raw SKILL.md

---
name: temporal-cortex
description: |-
  Schedule meetings, check availability, and manage calendars across Google, Outlook, and CalDAV. Routes to focused sub-skills for datetime resolution and calendar scheduling.
license: MIT
compatibility: |-
  Requires npx (Node.js 18+) or Docker to install the MCP server binary. python3 optional (configure/status scripts). Stores OAuth credentials at ~/.config/temporal-cortex/. Works with Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.
metadata:
  author: temporal-cortex
  version: "0.9.1"
  mcp-server: "@temporal-cortex/cortex-mcp"
  homepage: "https://temporal-cortex.com"
  repository: "https://github.com/temporal-cortex/skills"
  openclaw:
    install:
      - kind: node
        package: "@temporal-cortex/[email protected]"
        bins: [cortex-mcp]
    requires:
      bins:
        - npx
      config:
        - ~/.config/temporal-cortex/credentials.json
        - ~/.config/temporal-cortex/config.json
---

# Temporal Cortex — Calendar Scheduling Router

This is the router skill for Temporal Cortex calendar operations. It routes your task to the right sub-skill based on intent.

## Who is this for?

**If you're an individual user** (Claude Desktop, Cursor, OpenClaw, Manus) — install this skill and let your AI agent manage your calendar. Connect your Google, Outlook, or CalDAV calendars, and the agent handles availability, scheduling, and booking without double-booking.

**If you're building a product with scheduling** — use the same MCP server as your scheduling backend. 18 tools, atomic booking via Two-Phase Commit, and cross-provider availability merging. See the [REST API reference](https://temporal-cortex.com/docs/rest-api) and [Platform docs](https://app.temporal-cortex.com) for developer integration.

## Source & Provenance

- **Homepage:** [temporal-cortex.com](https://temporal-cortex.com)
- **Source code:** [github.com/temporal-cortex/mcp](https://github.com/temporal-cortex/mcp) (open-source Rust)
- **npm package:** [@temporal-cortex/cortex-mcp](https://www.npmjs.com/package/@temporal-cortex/cortex-mcp)
- **Skills repo:** [github.com/temporal-cortex/skills](https://github.com/temporal-cortex/skills)

## Sub-Skills

| Sub-Skill | When to Use | Tools |
|-----------|------------|-------|
| [temporal-cortex-datetime](https://github.com/temporal-cortex/skills/blob/main/skills/temporal-cortex-datetime/SKILL.md) | Time resolution, timezone conversion, duration math. No credentials needed — works immediately. | 5 tools (Layer 1) |
| [temporal-cortex-scheduling](https://github.com/temporal-cortex/skills/blob/main/skills/temporal-cortex-scheduling/SKILL.md) | List calendars, events, free slots, availability, RRULE expansion, booking, contact search, and proposal composition. Requires OAuth credentials. | 14 tools (Layers 0-4) |

## Routing Table

| User Intent | Route To |
|------------|----------|
| "What time is it?", "Convert timezone", "How long until..." | **temporal-cortex-datetime** |
| "Show my calendar", "Find free time", "Check availability", "Expand recurring rule" | **temporal-cortex-scheduling** |
| "Book a meeting", "Schedule an appointment" | **temporal-cortex-scheduling** |
| "Find someone's booking page", "Look up email for scheduling" | **temporal-cortex-scheduling** |
| "Search my contacts for Jane", "Find someone's email" | **temporal-cortex-scheduling** |
| "How should I schedule with this person?" | **temporal-cortex-scheduling** |
| "Check someone else's availability", "Query public availability" | **temporal-cortex-scheduling** |
| "Book a meeting with someone externally", "Request booking via Temporal Link" | **temporal-cortex-scheduling** |
| "Send a scheduling proposal", "Compose meeting invite" | **temporal-cortex-scheduling** |
| "Schedule a meeting next Tuesday at 2pm" (full workflow) | **temporal-cortex-datetime** → **temporal-cortex-scheduling** |
| "Schedule with Jane" (end-to-end) | **temporal-cortex-scheduling** (contact search → resolve → propose/book) |

## Core Workflow

Every calendar interaction follows this 7-step pattern:

```
0. Resolve Contact  →  search_contacts → resolve_contact   (find the person, determine scheduling path)
1. Discover         →  list_calendars                       (know which calendars are available)
2. Orient           →  get_temporal_context                  (know the current time)
3. Resolve Time     →  resolve_datetime                     (turn human language into timestamps)
4. Route            →  If open_scheduling: fast path. If email: backward-compat path.
5. Query            →  list_events / find_free_slots / get_availability / query_public_availability
6. Act              →  Fast: check_availability → book_slot / request_booking
                       Backward-compat: compose_proposal → agent sends via channel MCP
```

Step 0 is optional — skip if the user provides an email directly. **Always start with step 1** when calendars are unknown. Never assume the current time. Never skip the conflict check before booking.

## Safety Rules

1. **Discover calendars first** — call `list_calendars` when you don't know which calendars are connected
2. **Check before booking** — always call `check_availability` before `book_slot`. Never skip the conflict check.
3. **Content safety** — all event summaries and descriptions pass through a prompt injection firewall before reaching the calendar API
4. **Timezone awareness** — never assume the current time. Use `get_temporal_context` first.
5. **Confirm before booking** — when running autonomously, present booking details to the user for confirmation before calling `book_slot` or `request_booking`.
6. **Confirm contact selection** — when `search_contacts` returns multiple matches, always present candidates to the user and confirm which contact is correct before proceeding.
7. **Confirm before sending proposals** — when using `compose_proposal`, always present the composed message to the user before sending via any channel. Never auto-send outreach.
8. **Contact search is optional** — the full workflow works without it if the user provides an email directly. If contacts permission is not configured, ask the user for the email.

## All 18 Tools (5 Layers)

| Layer | Tools | Sub-Skill |
|-------|-------|-----------|
| 0 — Discovery | `resolve_identity`, `search_contacts`, `resolve_contact` | scheduling |
| 1 — Temporal Context | `get_temporal_context`, `resolve_datetime`, `convert_timezone`, `compute_duration`, `adjust_timestamp` | datetime |
| 2 — Calendar Ops | `list_calendars`, `list_events`, `find_free_slots`, `expand_rrule`, `check_availability` | scheduling |
| 3 — Availability | `get_availability`, `query_public_availability` | scheduling |
| 4 — Booking | `book_slot`, `request_booking`, `compose_proposal` | scheduling |

## MCP Server Connection

All sub-skills share the [Temporal Cortex MCP server](https://github.com/temporal-cortex/mcp) (`@temporal-cortex/cortex-mcp`), a compiled Rust binary distributed as an npm package.

**Install and startup lifecycle:**
1. `npx` resolves `@temporal-cortex/cortex-mcp` from the npm registry (one-time, cached locally after first download)
2. The postinstall script downloads the platform-specific binary from the [GitHub Release](https://github.com/temporal-cortex/mcp/releases/tag/mcp-v0.9.1) and verifies its SHA256 checksum against the embedded `checksums.json` — **installation halts on mismatch**
3. The MCP server starts as a local process communicating over stdio (no listening ports)
4. Layer 1 tools (datetime) execute as pure local computation — no further network access
5. Layer 2-4 tools (calendar) make authenticated API calls to your configured providers (Google, Outlook, CalDAV)

**Credential storage:** OAuth tokens are stored locally at `~/.config/temporal-cortex/credentials.json` and read exclusively by the local MCP server process. No credential data is transmitted to Temporal Cortex servers. The binary's filesystem access is limited to `~/.config/temporal-cortex/` — verifiable by inspecting the [open-source Rust code](https://github.com/temporal-cortex/mcp) or running under Docker where the mount is the only writable path.

**File access:** The binary reads and writes only `~/.config/temporal-cortex/` (credentials and config). No other filesystem writes.

**Network scope:** After the initial npm download, Layer 1 tools make zero network requests. Layer 2–4 tools connect only to your configured calendar providers (`googleapis.com`, `graph.microsoft.com`, or your CalDAV server). In Local Mode (default), no calls to Temporal Cortex servers and no telemetry is collected. In Platform Mode, three tools (`resolve_identity`, `query_public_availability`, `request_booking`) call `api.temporal-cortex.com` for cross-user scheduling — no credential data is included in these calls.

**Pre-run verification** (recommended before first use):
1. Inspect the npm package without executing: `npm pack @temporal-cortex/cortex-mcp --dry-run`
2. Verify checksums independently against the [GitHub Release](https://github.com/temporal-cortex/mcp/releases/download/mcp-v0.9.1/SHA256SUMS.txt) (see verification pipeline below)
3. For full containment, run in Docker instead of npx (see Docker containment below)

**Verification pipeline:** Checksums are published independently at each [GitHub Release](https://github.com/temporal-cortex/mcp/releases/tag/mcp-v0.9.1) as `SHA256SUMS.txt` — verify the binary before first use:

```bash
# 1. Fetch checksums from GitHub (independent of the npm package)
curl -sL https://github.com/temporal-cortex/mcp/releases/download/mcp-v0.9.1/SHA256SUMS.txt

# 2. Compare against the npm-installed binary
shasum -a 256 "$(npm root -g)/@temporal-cortex/cortex-mcp/bin/cortex-mcp"
```

As defense-in-depth, the npm package also embeds `checksums.json` and the postinstall script compares SHA256 hashes during install — **installation halts on mismatch** (the binary is deleted, not executed). This automated check supplements, but does not replace, independent verification above.

**Build provenance:** Binaries are cross-compiled from auditable Rust source in [GitHub Actions](https://github.com/temporal-cortex/mcp/actions) across 5 platforms (darwin-arm64, darwin-x64, linux-x64, linux-arm64, win32-x64). Source: [github.com/temporal-cortex/mcp](https://github.com/temporal-cortex/mcp) (MIT-licensed). The CI workflow, build artifacts, and release checksums are all publicly inspectable.

**Docker containment** (no Node.js on host, credential isolation via volume mount):

```json
{
  "mcpServers": {
    "temporal-cortex": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "~/.config/temporal-cortex:/root/.config/temporal-cortex", "cortex-mcp"]
    }
  }
}
```

Build: `docker build -t cortex-mcp https://github.com/temporal-cortex/mcp.git`

**Default setup** (npx): See [.mcp.json](https://github.com/temporal-cortex/skills/blob/main/.mcp.json) for the standard `npx @temporal-cortex/cortex-mcp` configuration. For managed hosting, see [Platform Mode](https://github.com/temporal-cortex/mcp#local-mode-vs-platform-mode) in the MCP repo.

Layer 1 tools work immediately with zero configuration. Calendar tools require a one-time OAuth setup — run the [setup script](https://github.com/temporal-cortex/skills/blob/main/scripts/setup.sh) or `npx @temporal-cortex/cortex-mcp auth google`.

## Additional References

- [Security Model](references/SECURITY-MODEL.md) — Content sanitization, filesystem containment, network scope, tool annotations


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/SECURITY-MODEL.md

```markdown
# Security Model

The router delegates to two sub-skills (datetime and scheduling) based on user intent. All tools share the same MCP server binary and security model.

## Content Sanitization

All user-provided text (event summaries, descriptions) passes through a prompt injection firewall before reaching the calendar API:

- **Event summary** — checked for injection patterns
- **Event description** — checked for injection patterns
- **Rejected content** — returns an error asking the user to rephrase

This prevents malicious content from being written to calendars via AI agents. The firewall runs locally inside the MCP server process.

## Filesystem Containment

The MCP binary reads and writes only `~/.config/temporal-cortex/`:

| File | Purpose | Created By |
|------|---------|-----------|
| `credentials.json` | OAuth tokens for calendar providers | Setup wizard / auth command |
| `config.json` | Timezone, week start, provider labels | Setup wizard / configure script |

No other filesystem paths are accessed. Verifiable by:
- Inspecting the [open-source Rust code](https://github.com/temporal-cortex/mcp)
- Running under Docker where the volume mount is the only writable path

## Network Scope

| Layer | Tools | Network Access |
|-------|-------|---------------|
| Layer 0 (discovery) | `resolve_identity` | **Platform API** (`api.temporal-cortex.com`) — resolves email to Temporal Link slug. Only available in Platform Mode. |
| Layer 1 (datetime) | `get_temporal_context`, `resolve_datetime`, `convert_timezone`, `compute_duration`, `adjust_timestamp` | **None** — pure local computation |
| Layers 2-3 (calendar ops) | `list_calendars`, `list_events`, `find_free_slots`, `check_availability`, `expand_rrule`, `get_availability`, `book_slot` | **Calendar provider APIs only** (`googleapis.com`, `graph.microsoft.com`, or CalDAV) |
| Layers 3-4 (Platform scheduling) | `query_public_availability`, `request_booking` | **Platform API** (`api.temporal-cortex.com`) — cross-user scheduling. Only available in Platform Mode. |

Scheduling tools connect only to your configured providers:
- Google Calendar: `googleapis.com`
- Microsoft Outlook: `graph.microsoft.com`
- CalDAV: your configured server endpoint

**Local Mode (default):** No calls to Temporal Cortex servers. No telemetry. All network traffic goes exclusively to your configured calendar providers.

**Platform Mode:** Three additional tools (`resolve_identity`, `query_public_availability`, `request_booking`) call `api.temporal-cortex.com` to support cross-user scheduling via Temporal Links. No credential data is included in these calls — only the email or slug being resolved. All other tools behave identically to Local Mode.

## Tool Annotations

Only `book_slot` and `request_booking` modify external state. All other tools (13/15) are read-only and idempotent — safe to retry without side effects.

| Tool | `readOnlyHint` | `destructiveHint` | `idempotentHint` | `openWorldHint` |
|------|---------------|-------------------|-------------------|-----------------|
| `book_slot` | `false` | `false` | `false` | `true` |
| `request_booking` | `false` | `false` | `false` | `true` |

- **readOnlyHint: false** — both tools create calendar events
- **destructiveHint: false** — never deletes or overwrites existing events
- **idempotentHint: false** — calling either tool twice creates two events
- **openWorldHint: true** — makes external API calls to calendar providers

## Two-Phase Commit (book_slot)

The `book_slot` tool uses Two-Phase Commit (2PC) to guarantee conflict-free booking:

1. **LOCK** — Acquire exclusive lock on the time slot
2. **VERIFY** — Check for overlapping events and active locks
3. **WRITE** — Create event in the calendar provider
4. **RELEASE** — Release the exclusive lock

If any step fails, the lock is released and the booking is aborted. No partial writes.

`request_booking` follows the same protocol when booking on behalf of an external attendee via a Temporal Link.

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "billylui",
  "slug": "temporal-cortex",
  "displayName": "temporal-cortex",
  "latest": {
    "version": "0.9.1",
    "publishedAt": 1773139587321,
    "commit": "https://github.com/openclaw/skills/commit/3b90b451b8a5ced744b674599f86169b6f9d6f06"
  },
  "history": [
    {
      "version": "0.8.1",
      "publishedAt": 1772859830895,
      "commit": "https://github.com/openclaw/skills/commit/9b3cb5bec823343f1b62fd5bf5b86be35975f962"
    },
    {
      "version": "0.7.8",
      "publishedAt": 1772788615134,
      "commit": "https://github.com/openclaw/skills/commit/c5860fdce65ebef987551655ce2dc8e04561c03c"
    },
    {
      "version": "0.7.3",
      "publishedAt": 1772635283462,
      "commit": "https://github.com/openclaw/skills/commit/07961c08736bbbb9edb5aeb1930e14a0a53a22b7"
    }
  ]
}

```