FamilySearch Genealogy Skill

Two modes of operation: 1. Live API (primary) — Query FamilySearch directly for person search, pedigree, descendants, historical records 2. Offline GEDCOM — Parse exported .ged files 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: 1. Direct user to: https://ident.familysearch.org/cis-web/oauth2/v3/authorization?response_type=code&client_id={APP_KEY}&redirect_uri={REDIRECT_URI} 2. User logs in, grants access 3. 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_token in 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 story command (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