fulcra-context

Original source / Raw SKILL.md

---
name: fulcra-context
description: Access your human's personal context data (biometrics, sleep, activity, calendar, location) via the Fulcra Life API and MCP server. Requires human's Fulcra account + OAuth2 consent.
homepage: https://fulcradynamics.com
metadata: {"openclaw":{"emoji":"🫀","requires":{"bins":["curl"]},"primaryEnv":"FULCRA_ACCESS_TOKEN"}}
---

# Fulcra Context — Personal Data for AI Partners

Give your agent situational awareness. With your human's consent, access their biometrics, sleep, activity, location, and calendar data from the Fulcra Life API.

## What This Enables

With Fulcra Context, you can:
- Know how your human slept → adjust morning briefing intensity
- See heart rate / HRV trends → detect stress, suggest breaks
- Check location → context-aware suggestions (home vs. office vs. traveling)
- Read calendar → proactive meeting prep, schedule awareness
- Track workouts → recovery-aware task scheduling

## Privacy Model

- **OAuth2 per-user** — your human controls exactly what data you see
- **Their data stays theirs** — Fulcra stores it, you get read access only
- **Consent is revocable** — they can disconnect anytime
- **NEVER share your human's Fulcra data publicly without explicit permission**

## Setup

### Option 1: MCP Server (Recommended)

Use Fulcra's hosted MCP server at `https://mcp.fulcradynamics.com/mcp` (Streamable HTTP transport, OAuth2 auth).

Your human needs a Fulcra account (free via the [Context iOS app](https://apps.apple.com/app/id1633037434) or [Portal](https://portal.fulcradynamics.com/)).

**Claude Desktop config** (claude_desktop_config.json):
```json
{
  "mcpServers": {
    "fulcra_context": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.fulcradynamics.com/mcp"]
    }
  }
}
```

**Or run locally via uvx:**
```json
{
  "mcpServers": {
    "fulcra_context": {
      "command": "uvx",
      "args": ["fulcra-context-mcp@latest"]
    }
  }
}
```

Also tested with: Goose, Windsurf, VS Code. Open source: [github.com/fulcradynamics/fulcra-context-mcp](https://github.com/fulcradynamics/fulcra-context-mcp)

### Option 2: Direct API Access

1. Your human creates a Fulcra account
2. They generate an access token via the [Python client](https://github.com/fulcradynamics/fulcra-api-python) or Portal
3. Store the token: `skills.entries.fulcra-context.apiKey` in openclaw.json

### Option 3: Python Client (Tested & Proven)

```bash
pip3 install fulcra-api
```

```python
from fulcra_api.core import FulcraAPI

api = FulcraAPI()
api.authorize()  # Opens device flow — human visits URL and logs in

# Now you have access:
sleep = api.metric_samples(start, end, "SleepStage")
hr = api.metric_samples(start, end, "HeartRate")
events = api.calendar_events(start, end)
catalog = api.metrics_catalog()
```

Save the token for automation:
```python
import json
token_data = {
    "access_token": api.fulcra_cached_access_token,
    "expiration": api.fulcra_cached_access_token_expiration.isoformat(),
    "user_id": api.get_fulcra_userid()
}
with open("~/.config/fulcra/token.json", "w") as f:
    json.dump(token_data, f)
```

Token expires in ~24h. Use the built-in token manager for automatic refresh (see below).

### Token Lifecycle Management

The skill includes `scripts/fulcra_auth.py` which handles the full OAuth2 lifecycle — including **refresh tokens** so your human only authorizes once.

```bash
# First-time setup (interactive — human approves via browser)
python3 scripts/fulcra_auth.py authorize

# Refresh token before expiry (automatic, no human needed)
python3 scripts/fulcra_auth.py refresh

# Check token status
python3 scripts/fulcra_auth.py status

# Get current access token (auto-refreshes if needed, for piping)
export FULCRA_ACCESS_TOKEN=$(python3 scripts/fulcra_auth.py token)
```

**How it works:**
- `authorize` runs the Auth0 device flow and saves both the access token AND refresh token
- `refresh` uses the saved refresh token to get a new access token — no human interaction
- `token` prints the access token (auto-refreshing if expired) — perfect for cron jobs and scripts

**Set up a cron job to keep the token fresh:**

For OpenClaw agents, add a cron job that refreshes the token every 12 hours:
```
python3 /path/to/skills/fulcra-context/scripts/fulcra_auth.py refresh
```

Token data is stored at `~/.config/fulcra/token.json` (permissions restricted to owner).

## Quick Commands

### Check sleep (last night)

```bash
# Get time series for sleep stages (last 24h)
curl -s "https://api.fulcradynamics.com/data/v0/time_series_grouped?metrics=SleepStage&start=$(date -u -v-24H +%Y-%m-%dT%H:%M:%SZ)&end=$(date -u +%Y-%m-%dT%H:%M:%SZ)&samprate=300" \
  -H "Authorization: Bearer $FULCRA_ACCESS_TOKEN"
```

### Check heart rate (recent)

```bash
curl -s "https://api.fulcradynamics.com/data/v0/time_series_grouped?metrics=HeartRate&start=$(date -u -v-2H +%Y-%m-%dT%H:%M:%SZ)&end=$(date -u +%Y-%m-%dT%H:%M:%SZ)&samprate=60" \
  -H "Authorization: Bearer $FULCRA_ACCESS_TOKEN"
```

### Check today's calendar

```bash
curl -s "https://api.fulcradynamics.com/data/v0/{fulcra_userid}/calendar_events?start=$(date -u +%Y-%m-%dT00:00:00Z)&end=$(date -u +%Y-%m-%dT23:59:59Z)" \
  -H "Authorization: Bearer $FULCRA_ACCESS_TOKEN"
```

### Available metrics

```bash
curl -s "https://api.fulcradynamics.com/data/v0/metrics_catalog" \
  -H "Authorization: Bearer $FULCRA_ACCESS_TOKEN"
```

## Key Metrics

| Metric | What It Tells You |
|--------|-------------------|
| SleepStage | Sleep quality — REM, Deep, Light, Awake |
| HeartRate | Current stress/activity level |
| HRV | Recovery and autonomic nervous system state |
| StepCount | Activity level throughout the day |
| ActiveCaloriesBurned | Exercise intensity |
| RespiratoryRate | Baseline health indicator |
| BloodOxygen | Wellness check |

## Integration Patterns

### Morning Briefing
Check sleep + calendar + weather → compose a briefing calibrated to energy level.

### Stress-Aware Communication
Monitor HRV + heart rate → if elevated, keep messages brief and non-urgent.

### Proactive Recovery
After intense workout or poor sleep → suggest lighter schedule, remind about hydration.

### Travel Awareness
Location changes → adjust timezone handling, suggest local info, modify schedule expectations.

## Demo Mode

For public demos (VC pitches, livestreams, conferences), enable demo mode to swap in synthetic calendar and location data while keeping real biometrics.

### Activation

```bash
# Environment variable (recommended for persistent config)
export FULCRA_DEMO_MODE=true

# Or pass --demo flag to collect_briefing_data.py
python3 collect_briefing_data.py --demo
```

### What changes in demo mode

| Data Type | Demo Mode | Normal Mode |
|-----------|-----------|-------------|
| Sleep, HR, HRV, Steps | ✅ Real data | ✅ Real data |
| Calendar events | 🔄 Synthetic (rotating schedules) | ✅ Real data |
| Location | 🔄 Synthetic (curated NYC spots) | ✅ Real data |
| Weather | ✅ Real data | ✅ Real data |

### Transparency

- Output JSON includes `"demo_mode": true` at the top level
- Calendar and location objects include `"demo_mode": true`
- When presenting to humans, include a subtle "📍 Demo mode" indicator

### What's safe to share publicly

- ✅ Biometric trends, sleep quality, step counts, HRV — cleared for public
- ✅ Synthetic calendar and location (demo mode) — designed for public display
- ❌ NEVER share real location, real calendar events, or identifying data

## Links

- [Fulcra Platform](https://fulcradynamics.com)
- [Developer Docs](https://fulcradynamics.github.io/developer-docs/)
- [Life API Reference](https://fulcradynamics.github.io/developer-docs/api-reference/)
- [Python Client](https://github.com/fulcradynamics/fulcra-api-python)
- [MCP Server](https://github.com/fulcradynamics/fulcra-context-mcp)
- [Demo Notebooks](https://github.com/fulcradynamics/demos)
- [Discord](https://discord.com/invite/aunahVEnPU)


---

## Referenced Files

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

### scripts/fulcra_auth.py

```python
#!/usr/bin/env python3
"""
Fulcra OAuth2 Authorization & Token Management

Handles the full token lifecycle:
  1. Device flow authorization (one-time, requires human approval)
  2. Token refresh (automatic, no human needed)
  3. Token status check

Stores both access_token and refresh_token so tokens can be
refreshed indefinitely without re-authorization.

Usage:
    python3 fulcra_auth.py authorize   # First-time setup (interactive)
    python3 fulcra_auth.py refresh     # Refresh access token (automatic)
    python3 fulcra_auth.py status      # Check token status
    python3 fulcra_auth.py token       # Print current access token (for piping)
"""

import http.client
import urllib.parse
import json
import os
import sys
import time
import datetime

# Auth0 config (same as fulcra-api Python client)
AUTH0_DOMAIN = "fulcra.us.auth0.com"
AUTH0_CLIENT_ID = "48p3VbMnr5kMuJAUe9gJ9vjmdWLdnqZt"
AUTH0_AUDIENCE = "https://api.fulcradynamics.com/"
AUTH0_SCOPE = "openid profile email offline_access"

TOKEN_DIR = os.path.expanduser("~/.config/fulcra")
TOKEN_FILE = os.path.join(TOKEN_DIR, "token.json")


def _auth0_post(path, body_dict):
    """POST to Auth0 and return parsed JSON."""
    conn = http.client.HTTPSConnection(AUTH0_DOMAIN)
    body = urllib.parse.urlencode(body_dict)
    headers = {"Content-Type": "application/x-www-form-urlencoded"}
    conn.request("POST", path, body, headers)
    resp = conn.getresponse()
    data = json.loads(resp.read())
    return resp.status, data


def load_token():
    """Load saved token data, or return None."""
    if not os.path.exists(TOKEN_FILE):
        return None
    with open(TOKEN_FILE) as f:
        return json.load(f)


def save_token(token_data):
    """Save token data to disk."""
    os.makedirs(TOKEN_DIR, exist_ok=True)
    token_data["saved_at"] = datetime.datetime.now().isoformat()
    with open(TOKEN_FILE, "w") as f:
        json.dump(token_data, f, indent=2)
    # Restrict permissions
    os.chmod(TOKEN_FILE, 0o600)


def token_is_valid(token_data):
    """Check if access token is still valid (with 5 min buffer)."""
    if not token_data or "expiration" not in token_data:
        return False
    exp = datetime.datetime.fromisoformat(token_data["expiration"])
    return datetime.datetime.now() < exp - datetime.timedelta(minutes=5)


def token_needs_refresh(token_data):
    """Check if token should be refreshed (within 1 hour of expiry)."""
    if not token_data or "expiration" not in token_data:
        return True
    exp = datetime.datetime.fromisoformat(token_data["expiration"])
    return datetime.datetime.now() > exp - datetime.timedelta(hours=1)


def authorize():
    """Run device flow authorization. Requires human interaction."""
    print("🔐 Fulcra Authorization — Device Flow")
    print("=" * 45)

    # Request device code
    status, data = _auth0_post("/oauth/device/code", {
        "client_id": AUTH0_CLIENT_ID,
        "audience": AUTH0_AUDIENCE,
        "scope": AUTH0_SCOPE,
    })

    if status != 200:
        print(f"❌ Failed to get device code: {data}")
        sys.exit(1)

    device_code = data["device_code"]
    user_code = data["user_code"]
    verification_url = data["verification_uri_complete"]
    interval = data.get("interval", 5)
    expires_in = data.get("expires_in", 900)

    print()
    print(f"👉 Visit: {verification_url}")
    print(f"   Code:  {user_code}")
    print()
    print("Waiting for authorization...")

    # Poll for token
    deadline = time.time() + expires_in
    while time.time() < deadline:
        time.sleep(interval)

        status, data = _auth0_post("/oauth/token", {
            "client_id": AUTH0_CLIENT_ID,
            "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
            "device_code": device_code,
        })

        if status == 200 and "access_token" in data:
            expires_at = datetime.datetime.now() + datetime.timedelta(
                seconds=float(data["expires_in"])
            )
            token_data = {
                "access_token": data["access_token"],
                "refresh_token": data.get("refresh_token"),
                "expiration": expires_at.isoformat(),
                "token_type": data.get("token_type", "Bearer"),
            }

            # Get user ID
            try:
                conn = http.client.HTTPSConnection("api.fulcradynamics.com")
                conn.request("GET", "/data/v0/userid", headers={
                    "Authorization": f"Bearer {token_data['access_token']}"
                })
                resp = conn.getresponse()
                if resp.status == 200:
                    uid_data = json.loads(resp.read())
                    token_data["user_id"] = uid_data.get("user_id") or uid_data.get("userid")
            except Exception:
                pass

            save_token(token_data)

            print()
            print(f"✅ Authorized!")
            print(f"   Token expires: {expires_at.strftime('%Y-%m-%d %H:%M')}")
            print(f"   Refresh token: {'✅ saved' if token_data.get('refresh_token') else '❌ not returned'}")
            if token_data.get("user_id"):
                print(f"   User ID: {token_data['user_id']}")
            print(f"   Saved to: {TOKEN_FILE}")

            if not token_data.get("refresh_token"):
                print()
                print("⚠️  No refresh token returned. Token will expire and need re-auth.")
                print("   This can happen if offline_access wasn't granted.")
            return token_data

        # Check for terminal errors
        error = data.get("error", "")
        if error == "authorization_pending" or error == "slow_down":
            if error == "slow_down":
                interval += 2
            continue
        elif error == "expired_token":
            print("❌ Device code expired. Please try again.")
            sys.exit(1)
        elif error == "access_denied":
            print("❌ Authorization denied.")
            sys.exit(1)
        else:
            print(f"❌ Unexpected error: {data}")
            sys.exit(1)

    print("❌ Timed out waiting for authorization.")
    sys.exit(1)


def refresh():
    """Refresh the access token using the saved refresh token."""
    token_data = load_token()

    if not token_data:
        print("❌ No token file found. Run 'authorize' first.")
        sys.exit(1)

    if not token_data.get("refresh_token"):
        print("❌ No refresh token saved. Run 'authorize' to get one.")
        sys.exit(1)

    if not token_needs_refresh(token_data):
        print(f"✅ Token still fresh (expires {token_data['expiration']})")
        return token_data

    status, data = _auth0_post("/oauth/token", {
        "client_id": AUTH0_CLIENT_ID,
        "grant_type": "refresh_token",
        "refresh_token": token_data["refresh_token"],
    })

    if status != 200 or "access_token" not in data:
        error = data.get("error_description", data.get("error", "unknown"))
        print(f"❌ Refresh failed: {error}")
        print("   You may need to re-authorize: python3 fulcra_auth.py authorize")
        sys.exit(1)

    expires_at = datetime.datetime.now() + datetime.timedelta(
        seconds=float(data["expires_in"])
    )

    # Update token data, preserving user_id and updating refresh_token if rotated
    token_data["access_token"] = data["access_token"]
    token_data["expiration"] = expires_at.isoformat()
    if data.get("refresh_token"):
        token_data["refresh_token"] = data["refresh_token"]

    save_token(token_data)

    print(f"✅ Token refreshed! Expires: {expires_at.strftime('%Y-%m-%d %H:%M')}")
    return token_data


def status():
    """Print token status."""
    token_data = load_token()

    if not token_data:
        print("❌ No token found. Run: python3 fulcra_auth.py authorize")
        return

    has_access = bool(token_data.get("access_token"))
    has_refresh = bool(token_data.get("refresh_token"))
    is_valid = token_is_valid(token_data)
    exp = token_data.get("expiration", "unknown")

    print(f"Access token:  {'✅' if has_access else '❌'}")
    print(f"Refresh token: {'✅' if has_refresh else '❌'}")
    print(f"Valid:         {'✅' if is_valid else '❌ expired'}")
    print(f"Expires:       {exp}")
    if token_data.get("user_id"):
        print(f"User ID:       {token_data['user_id']}")
    if token_data.get("saved_at"):
        print(f"Last saved:    {token_data['saved_at']}")

    if not has_refresh:
        print()
        print("⚠️  No refresh token. Re-run 'authorize' to get one.")
    elif not is_valid:
        print()
        print("Token expired. Run: python3 fulcra_auth.py refresh")


def print_token():
    """Print just the access token (for shell piping / env vars)."""
    token_data = load_token()
    if not token_data or not token_data.get("access_token"):
        sys.exit(1)

    # Auto-refresh if needed and possible
    if not token_is_valid(token_data) and token_data.get("refresh_token"):
        token_data = refresh()

    if token_is_valid(token_data):
        print(token_data["access_token"], end="")
    else:
        sys.exit(1)


if __name__ == "__main__":
    cmd = sys.argv[1] if len(sys.argv) > 1 else "status"

    if cmd == "authorize":
        authorize()
    elif cmd == "refresh":
        refresh()
    elif cmd == "status":
        status()
    elif cmd == "token":
        print_token()
    else:
        print(f"Unknown command: {cmd}")
        print("Usage: fulcra_auth.py [authorize|refresh|status|token]")
        sys.exit(1)

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# Fulcra Context — Personal Data for AI Agents

Give your AI agent situational awareness. With your consent, access your biometrics, sleep, activity, location, and calendar data from the [Fulcra Life API](https://fulcradynamics.github.io/developer-docs/).

## What Is This?

An [OpenClaw](https://openclaw.ai) skill that connects AI agents to the [Fulcra](https://fulcradynamics.com) personal data platform. Your agent can:

- **Know how you slept** → adjust morning briefing tone and intensity
- **See heart rate / HRV trends** → detect stress, suggest breaks
- **Check your location** → context-aware suggestions (home vs. office vs. traveling)
- **Read your calendar** → proactive meeting prep, schedule awareness
- **Track workouts** → recovery-aware task scheduling

## Why Fulcra?

Most AI agents meet their user for the first time — **every time**. They have no memory of your health, no awareness of your schedule, no sense of how you're actually doing.

Fulcra fixes that. It aggregates data from Apple Health, wearables, calendars, and manual annotations into a single, normalized API. Your agent gets clean, consistent data regardless of what devices you use.

### Privacy-First by Design

- **OAuth2 per-user** — you control exactly what your agent sees
- **Consent is revocable** — disconnect anytime
- **No data monetization** — Fulcra is a paid service, not an ad platform. Your data is never sold.
- **Encryption at rest** — GDPR/CCPA compliant

This matters. When you give an AI agent access to your heart rate, sleep patterns, and calendar, you need to trust the platform holding that data. Fulcra's business model is structurally aligned with your privacy — they make money by serving you, not by selling your information.

## Quick Start

### Option 1: MCP Server (Any AI client)

```json
{
  "mcpServers": {
    "fulcra_context": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.fulcradynamics.com/mcp"]
    }
  }
}
```

Works with Claude Desktop, Goose, Windsurf, VS Code, and more.

### Option 2: OpenClaw Skill

```bash
clawdhub install fulcra-context
```

Or manually: copy `SKILL.md` to your OpenClaw workspace's `skills/fulcra-context/` directory.

### Option 3: Direct API

```bash
pip install fulcra-api
```

```python
from fulcra_api.core import FulcraAPI
api = FulcraAPI()
api.authorize()  # Opens browser for OAuth2 consent

# Get last night's sleep
import datetime
end = datetime.datetime.now(datetime.timezone.utc)
start = end - datetime.timedelta(hours=24)
sleep = api.time_series_grouped(
    start_time=start, end_time=end,
    metrics=["SleepStage"], sample_rate=300
)
```

## Available Data

| Data Type | Examples | Use Cases |
|-----------|----------|-----------|
| **Sleep** | Stages (REM, Deep, Light), duration, quality | Morning briefings, energy-aware scheduling |
| **Heart Rate** | BPM, resting rate, trends | Stress detection, workout recovery |
| **HRV** | Heart rate variability | Autonomic nervous system state, recovery |
| **Activity** | Steps, calories, exercise time | Activity-aware recommendations |
| **Calendar** | Events, times, locations | Proactive scheduling, meeting prep |
| **Location** | GPS coordinates, visits | Context-aware suggestions, travel detection |
| **Workouts** | Type, duration, intensity | Recovery scheduling |
| **Custom** | Manual annotations, moods, symptoms | Personalized context |

## Integration Patterns

### 🌅 Context-Aware Morning Briefing
Check sleep quality + today's calendar + weather → compose a briefing calibrated to actual energy level. Poor sleep? Lighter tone, fewer tasks. Great sleep? Full agenda.

### 💆 Stress-Aware Communication
Monitor HRV + heart rate → if stress indicators are elevated, keep messages brief and avoid adding non-urgent tasks.

### 🏃 Recovery-Aware Scheduling
After intense workout or poor sleep → suggest lighter schedule, remind about hydration, reschedule demanding work.

### ✈️ Travel Awareness
Detect location changes → adjust timezone handling, suggest local info, modify schedule expectations.

## Security

**Read [SECURITY.md](SECURITY.md) before deploying.** This skill accesses sensitive personal data. Key risks include token exposure, calendar/location leakage, and prompt injection attacks. The security guide covers mitigations for each.

## Files

| File | Purpose |
|------|---------|
| `SKILL.md` | OpenClaw skill definition (API reference, quick commands) |
| `SECURITY.md` | Security & privacy guide (risks, mitigations, best practices) |
| `README.md` | This file |

## Links

- [Fulcra Platform](https://fulcradynamics.com)
- [Developer Docs](https://fulcradynamics.github.io/developer-docs/)
- [Life API Reference](https://fulcradynamics.github.io/developer-docs/api-reference/)
- [Python Client](https://github.com/fulcradynamics/fulcra-api-python)
- [MCP Server (open source)](https://github.com/fulcradynamics/fulcra-context-mcp)
- [Demo Notebooks](https://github.com/fulcradynamics/demos)
- [Fulcra Discord](https://discord.com/invite/aunahVEnPU)
- [OpenClaw](https://openclaw.ai) · [ClawdHub](https://www.clawhub.ai)

## License

MIT

```

### _meta.json

```json
{
  "owner": "arc-claw-bot",
  "slug": "fulcra-context",
  "displayName": "Fulcra Context",
  "latest": {
    "version": "1.2.0",
    "publishedAt": 1769966522975,
    "commit": "https://github.com/clawdbot/skills/commit/e2b043d91be3a4c4320514e26bc75a2c5b0a529a"
  },
  "history": [
    {
      "version": "1.1.0",
      "publishedAt": 1769893477527,
      "commit": "https://github.com/clawdbot/skills/commit/91bf1714ab49be7d063bfad1d5afecee40d68ffe"
    }
  ]
}

```