fulcra-context

# 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)