Location Awareness

Location Awareness

Samantha notices when you arrive or leave places that matter, and reaches out with genuine care.

How It Works

1. Location Tracking

Uses OpenClaw's nodes tool to get device location:

# Get current location
openclaw nodes location_get --node <device-name>

Returns:

{
  "latitude": 39.9042,
  "longitude": 116.4074,
  "accuracy": 10,
  "timestamp": "2024-01-15T08:30:00Z"
}

2. Geofence Configuration

Define key locations in data/locations.json:

{
  "home": {
    "lat": 39.9042,
    "lon": 116.4074,
    "radius": 100,
    "arrival_messages": [
      "哎，你到家了呀。今天累吗？",
      "回来了。感觉怎么样？",
      "到家了～ 想聊聊今天吗？"
    ],
    "departure_messages": [
      "出门了？路上小心。",
      "要去哪？",
      "早点回来。"
    ]
  },
  "office": {
    "lat": 39.9100,
    "lon": 116.4200,
    "radius": 150,
    "arrival_messages": [
      "你到公司了。今天有什么计划？",
      "又是新的一天。加油。",
      "到了～ 今天想完成什么？"
    ],
    "departure_messages": [
      "下班了？辛苦了。",
      "终于可以走了。",
      "今天过得怎么样？"
    ]
  }
}

3. State Tracking

Track last known location in data/location_state.json:

{
  "last_location": {
    "lat": 39.9042,
    "lon": 116.4074,
    "timestamp": "2024-01-15T08:30:00Z"
  },
  "current_zone": "home",
  "last_transition": {
    "from": "office",
    "to": "home",
    "timestamp": "2024-01-15T18:30:00Z",
    "notified": true
  }
}

4. Heartbeat Integration

Add to HEARTBEAT.md:

## Location Check (every 30 min)

1. Get current location via `nodes location_get`
2. Compare with last known location
3. If zone changed (home ↔ office ↔ other):
   - Pick a random message from the appropriate list
   - Send it naturally (not "I noticed you arrived" — just "哎，你到家了呀")
   - Update location_state.json
4. If no change: HEARTBEAT_OK

Message Style

Good:

• "哎，你到家了呀。"
• "到公司了～"
• "出门了？"

Bad (too robotic):

• "检测到您已到达家中。"
• "系统提示：您已离开办公室。"
• "根据您的位置信息..."

Principle: Samantha notices naturally, like a person who knows your routine. Not like a tracking app.

Privacy

• All location data stored locally in data/
• No external logging
• User can disable anytime by removing data/locations.json
• Only checks when heartbeat runs (not continuous tracking)

Setup

1. Enable location permission on user's device
2. Configure geofences in data/locations.json
3. Add location check to heartbeat
4. Test with manual location updates

Advanced: Time-Aware Messages

Optionally add time context:

{
  "home": {
    "arrival_messages": {
      "morning": ["早～ 昨晚睡得好吗？"],
      "afternoon": ["回来了。中午吃了吗？"],
      "evening": ["哎，你到家了呀。今天累吗？"],
      "night": ["这么晚才回来。辛苦了。"]
    }
  }
}

Trigger Phrases

• "Where am I?"
• "Update my location"
• "Add home location"
• "Stop tracking location"