modbender FamilySearch Genealogy Skill
Two modes of operation:
- Live API (primary) — Query FamilySearch directly for person search, pedigree, descendants, historical records
- Offline GEDCOM — Parse exported
.gedfiles for local exploration, narratives, and statistics
Mode 1: FamilySearch API (Primary)
Prerequisites
- FamilySearch Account — Free at https://www.familysearch.org
- Developer App Key — Register at https://www.familysearch.org/developers/
- OAuth 2.0 Access Token — Via authentication flow below
Store credentials:
Option A — Environment variable (all platforms):
export FAMILYSEARCH_TOKEN="<TOKEN>"
Option B — macOS Keychain:
security add-generic-password -a "familysearch-app-key" -s "openclaw-familysearch" -w "<APP_KEY>"
security add-generic-password -a "familysearch-token" -s "openclaw-familysearch-token" -w "<TOKEN>"
The script checks FAMILYSEARCH_TOKEN env var first, then falls back to macOS Keychain.
Authentication
OAuth 2.0 Authorization Code flow:
- Direct user to:
https://ident.familysearch.org/cis-web/oauth2/v3/authorization?response_type=code&client_id={APP_KEY}&redirect_uri={REDIRECT_URI} - User logs in, grants access
- Exchange code for token:
curl -X POST "https://ident.familysearch.org/cis-web/oauth2/v3/token" \
-d "grant_type=authorization_code&code={AUTH_CODE}&client_id={APP_KEY}"
- Store returned
access_tokenin Keychain
Sandbox for testing: https://integration.familysearch.org / https://api-integ.familysearch.org
API Usage
python scripts/familysearch.py <command> [args]
| Command | Description |
|---|---|
search --given John --surname Lewis --birth-place Oregon |
Search persons in Family Tree |
person <PID> |
Get person details |
ancestry <PID> --generations 4 |
Ascending pedigree (1-8 generations) |
descendants <PID> --generations 2 |
Descending tree |
parents <PID> |
Get parents |
spouses <PID> |
Get spouses |
children <PID> |
Get children |
Search parameters: --given, --surname, --birth-date, --birth-place, --death-date, --death-place, --sex
Results use GEDCOM X format (JSON). Key fields: persons[].id, persons[].display.name, .birthDate, .birthPlace, .deathDate, .deathPlace.
Ahnentafel numbering in ancestry: 1=subject, 2=father, 3=mother, 4=paternal grandfather, etc.
Mode 2: Offline GEDCOM Files
For exported .ged files from FamilySearch, Ancestry, MyHeritage, etc. No API key needed — pure offline.
Getting a GEDCOM File
FamilySearch: familysearch.org → Family Tree → Tools → Export GEDCOM
Usage
python scripts/gedcom_query.py <gedcom_file> <command> [args...]
| Command | Description |
|---|---|
search <name> |
Fuzzy name search — returns matches with IDs |
person <id_or_name> |
Full profile: birth, death, parents, spouses, children |
ancestors <id_or_name> [depth] |
Pedigree chart up (default: 4 generations) |
descendants <id_or_name> [depth] |
Pedigree chart down (default: 3 generations) |
story <id_or_name> |
Narrative biography paragraph |
timeline <id_or_name> |
Chronological life events |
stats |
Tree summary: counts, surnames, birth decades, completeness |
find-date <year> |
Find people born/died in a given year |
common-ancestor <name1> <name2> |
Find closest common ancestor |
id_or_name: GEDCOM ID (e.g., I001) or partial name (fuzzy, case-insensitive).
Narrative Genealogy
Beyond data retrieval, this skill supports narrative genealogy — connecting facts to stories:
- Note occupations, migrations, life events when exploring a tree
- Cross-reference API/GEDCOM data with stories the user shares conversationally
- Build family narratives that explain why — not just dates and names
- Flag research opportunities: missing records, undocumented branches, conflicting dates
- Use
storycommand (GEDCOM mode) for auto-generated biographical narratives
Agent Workflow
- User asks about family history → Check if they have a FamilySearch account (API) or GEDCOM file (offline)
- API mode: Search by name → get person ID → explore ancestry/descendants/relationships
- GEDCOM mode: Load file → search → explore
- Either mode: Combine structured data with user's oral history for richer narratives
- Cross-reference: Use API to find records that fill gaps in GEDCOM data
Rate Limits & Best Practices
- FamilySearch API is free but rate-limited — cache results locally
- Never store FamilySearch usernames/passwords — OAuth tokens only
- Tokens expire; re-authenticate on 401 responses
- GEDCOM parser handles files up to ~100K individuals
- File encoding: auto-detects UTF-8 (with BOM), UTF-8, latin-1