contacts

Contacts

Manage contacts in ~/Vault/Contacts/. Each contact is a markdown file with YAML frontmatter.

Contact File Location

~/Vault/Contacts/<Name>.md

Index file: ~/Vault/Contacts/index.md — wikilink list of all contacts.

Frontmatter Schema

---
name: Full Name
aliases: [nickname, handle]
role: Current Role / Title
organizations: [Org1, Org2]
vip: true  # or false
slack_user_id: U0XXXXXXX
slack_dm_channel: D0XXXXXXX  # null if unknown
website: https://example.com
github: username
twitter: handle
email: user@example.com
tags: [vip, instructor, creator, family, employee]
---

Sections

# Name

## Contact Channels
- Slack, email, social handles, website

## Projects
- Active projects, courses, collaborations

## Key Context
- Relationship notes, working style, history

## Recent Activity
- YYYY-MM-DD | channel | summary

See ~/Vault/Contacts/Matt Pocock.md for a fully enriched example.

Adding a Contact

Option 1: Fire the Enrichment Pipeline (preferred)

Send an Inngest event. The contact-enrich function fans out across 7 sources (Slack, Roam, web/GitHub, Granola, recall memory, Typesense), synthesizes with LLM, and writes the Vault file.

# Via curl (CLI has OTEL import bug under Bun v1.3.9)
curl -s -X POST "http://localhost:8288/e/$INNGEST_EVENT_KEY" \
  -H "Content-Type: application/json" \
  -d '[{
    "name": "contact/enrich.requested",
    "data": {
      "name": "Person Name",
      "depth": "full",
      "hints": {
        "slack_user_id": "U0XXXXXXX",
        "github": "username",
        "twitter": "handle",
        "email": "user@example.com",
        "website": "https://example.com"
      }
    },
    "ts": EPOCH_MS
  }]'

Depth modes:

• full (~60s, ~$0.05): All 7 sources + LLM synthesis. Use for new contacts or periodic refresh.
• quick (~10s, ~$0.01): Slack + memory only. Good for real-time VIP detection.

Hints are optional but help: Any known identifiers (Slack ID, GitHub, email, Twitter, website) seed the search and improve results.

Option 2: Quick Manual Create

For simple contacts where enrichment is overkill:

---
name: Person Name
aliases: []
role: Role
organizations: [Org]
vip: false
slack_user_id: null
website: null
github: null
twitter: null
email: null
tags: [tag1]
---

# Person Name

## Contact Channels
- ...

## Key Context
- ...

Write to ~/Vault/Contacts/Person Name.md and add [[Person Name]] to index.md.

Updating Contacts

Re-run enrichment with the existing vault path:

{
  "name": "contact/enrich.requested",
  "data": {
    "name": "Person Name",
    "vault_path": "Contacts/Person Name.md",
    "depth": "full"
  }
}

The synthesizer merges new data with existing content — it won't discard existing facts unless contradicted.

VIP Contacts (ADR-0151)

Mark vip: true in frontmatter. VIPs get deep enrichment + ongoing monitoring.

Deep Enrichment Playbook (one-time)

Every VIP gets the full treatment. This is what we did for Kent C. Dodds (Feb 26, 2026):

Step	Source	What to Capture
1. Web presence	Web search {name} + {org}	Bio, role, location, personal details
2. Podcast/interviews	Web search {name} podcast interview	Appearance list, own podcasts, audiences
3. Joel collaborations	Their website, appearances pages	Joint podcasts, co-organized events, shared projects
4. Career timeline	Defuddle 2-3 key interview transcripts	Origin story, career arc, key decisions, values
5. GitHub profile	GitHub API or web	Repos, followers, orgs, contribution patterns
6. X/Twitter profile	X API v2 (use x-api skill)	Bio, followers, recent tweets, engagement
7. Key relationships	Cross-reference transcripts + contacts	Who they work with, who they mention, who we know in common
8. Content catalog	Website crawl (defuddle)	Courses, blog posts, open source projects
9. Audience reach	Podcast counts, social followers	Conference circuit, community presence

Index to Typesense after enrichment:

• Batch-import appearances/content to discoveries collection (NDJSON, action=upsert)
• Tag all docs with person's name slug (e.g. kent-c-dodds) for filtering
• Fields: id, title, url, summary, tags[], timestamp
• Write a Vault/Resources/{name}-media-appearances.md reference doc linking back to contact

Output sections in the vault note:

• Background & Story (origin, career timeline)
• Teaching/Work Philosophy (or equivalent for non-educators)
• Key Relationships (cross-linked [[wikilinks]] to other contacts)
• Audience & Reach
• Content/Products
• Podcast/Collaboration History with Joel
• Recent Activity (timestamped)

Ongoing Monitoring (Phase 2-4 of ADR-0151)

Channel	Tool	Signal
Google Alerts	joelclawbot Google account	Name mentions in news, blogs, press
X/Twitter list	joelclaw X account	Tweets, engagement
GitHub activity	GitHub API (polling)	New repos, releases
Podcast RSS	Feed monitoring	New episodes
Website changes	Periodic defuddle + diff	Blog posts, launches, bio changes

High-signal (immediate): course launches, role changes, mentions of Joel/egghead/Skill, fundraising. Low-signal (daily/weekly digest): regular tweets, blog posts, OSS activity.

Current VIPs

• Get notified to Joel via gateway after enrichment
• Are refreshed weekly via scheduled cron
• Have priority in channel intelligence pipeline (ADR-0131, ADR-0132)
• Get ongoing monitoring when ADR-0151 Phase 2+ is implemented

Roam Research Enrichment

Joel's Roam archive (~/Code/joelhooks/egghead-roam-research/) contains the full egghead-era graph (2019-2024). Many contacts have extensive history there.

Quick Search (Python regex)

cd ~/Code/joelhooks/egghead-roam-research
python3 -c "
import re
with open('egghead-2026-01-19-13-09-38.edn', 'r') as f:
    content = f.read()
pattern = r':block/string\s+\"([^\"]*?)\"'
matches = []
for m in re.findall(pattern, content):
    if '[[SEARCH_TAG]]' in m.lower():
        matches.append(m)
print(f'Found {len(matches)} blocks')
for m in matches[:30]:
    print(f'  - {m[:200]}')
"

People Taxonomy

People are tagged with relationship prefixes in Roam:

• [[collaborator/Name]] — Strategic partners (Ian Jones, Alex Hillman)
• [[client/Name]] — egghead instructors (Matt Pocock, Jacob Paris)
• [[staff/Name]] — egghead team (Will Johnson, Daniel Miller, Maggie Appleton)
• [[name]] (no prefix) — Informal references (Zac is [[zac]])

Page Title Search

python3 -c "
import re
with open('egghead-2026-01-19-13-09-38.edn', 'r') as f:
    content = f.read()
pattern = r':node/title\s+\"([^\"]*?SEARCH_TERM[^\"]*?)\"'
for m in re.findall(pattern, content):
    print(f'  page: {m}')
"

Adding to Contacts

When extracting person data from Roam, add roam_tag to frontmatter:

roam_tag: "[[collaborator/Ian Jones]]"

This enables future re-queries and cross-referencing.

Datalog Queries (advanced)

The EDN file is Datomic-style. Clojure scripts exist at scripts/ for structured analysis. See the roam-research skill for full Datalog patterns.

Resolving Unknown People

When you encounter a Slack user ID (<@U0XXXXXXX>):

# Lease token and look up profile
SLACK_USER=$(secrets lease slack_user_token --ttl 5m)
curl -s "https://slack.com/api/users.info?user=U0XXXXXXX" \
  -H "Authorization: Bearer $SLACK_USER" | jq '.user.real_name, .user.profile.email'
secrets revoke --all

Then fire enrichment with the resolved name and hints.

Inngest Function

• Function: contact-enrich (packages/system-bus/src/inngest/functions/contact-enrich.ts)
• Event: contact/enrich.requested
• ADR: ~/Vault/docs/decisions/0133-contact-enrichment-pipeline.md
• Concurrency: 3 max
• Sources: Slack, Slack Connect, Roam archive, GitHub/web, Granola meetings, recall memory, Typesense

Privacy

• Contact files are in Vault (private, not in public repos)
• Slack data stays private — never surface in public content
• Email/phone are stored for Joel's reference only