cold-start

# Cold Start — Day-One Brain Bootstrapping You have a working brain. Search works. Now what? An empty brain is a static database. A brain with your email history, calendar, contacts, conversations, and social media is a **live context membrane** that makes every future interaction smarter. This skill sequences the highest-leverage data sources to get you from zero to useful in one session. ## Contract - Every import phase is gated on user consent (ask-user pattern) before proceeding. - **The agent never holds raw OAuth tokens or API keys.** This is a safety requirement, not a preference. Three paths satisfy it for Google data: the native connector (`gbrain google setup` — tokens live in gbrain's credential vault, mode 0600, never in the agent's context; see `docs/guides/google-connect.md` and `skills/google-loops/SKILL.md`), ClawVisor (a hosted credential gateway that vaults credentials, enforces task-scoped authorization, logs every API call, and requires human approval for destructive operations — needs a harness with the integration), or offline file exports (Google Takeout, Twitter archive download). - Each phase is independently valuable — the user can stop after any phase and still have a useful brain. - Progress is tracked in `~/.gbrain/cold-start-state.json` so interrupted sessions can resume. - Entity detection and cross-linking run on every import, not as a separate pass. ## Prerequisites - GBrain installed and initialized (`gbrain doctor --json` all green) - Brain repo cloned and synced - Agent has terminal access and can run `gbrain` CLI commands ## The Priority Stack Data sources ranked by **information density × ease of import**: | Priority | Source | Why | Time | Pages Created | |----------|--------|-----|------|---------------| | 1 | Existing markdown/Obsidian | Highest density — it's already structured | 5 min | 100s-1000s | | 2 | Google Contacts | Seeds the people/ directory — names, emails, companies | 10 min | 50-500 | | 3 | Google Calendar (90 days) | Meeting history with attendee context | 15 min | 30-90 | | 4 | Gmail (recent threads) | Relationship context, active threads, org chart signals | 20 min | 50-200 | | 5 | Conversations (ChatGPT/Claude exports) | Your thinking, questions, mental models | 15 min | 10-100 | | 6 | X/Twitter archive | Your public positions, takes, engagement patterns | 20 min | 30-365 | | 7 | File archives (Dropbox/Drive/local) | Historical documents, old writing, photos | 30+ min | varies | | 8 | Meeting transcripts (Circleback/etc.) | Deep relationship context from recorded calls | 20 min | 10-50 | ## Phase 0: ClawVisor Setup (only if your agent harness integrates ClawVisor) **Harness check first.** ClawVisor requires an agent host with a ClawVisor integration (for example, an OpenClaw deployment). On harnesses without one, such as Codex or Claude Code, skip this phase: the default for Contacts, Calendar, and Gmail is the native connector — `gbrain google setup` (live sync; tokens in gbrain's local credential vault, never with the agent; see `skills/google-loops/SKILL.md`) — with a [Google Takeout](https://takeout.google.com) export as the offline alternative covering all three (contacts CSV, calendar ICS, Gmail mbox). Phases 2-4 below document the Takeout path first. > **Safety boundary:** An AI agent with raw OAuth tokens to your Gmail, Calendar, > and Contacts is an uncontrolled attack surface. One prompt injection, one > malicious tool call, and your entire Google account is exposed. ClawVisor > eliminates this risk class entirely. [ClawVisor](https://clawvisor.com) is a credential gateway that sits between the agent and your APIs. The agent never sees your credentials — ClawVisor injects them at request time, enforces policies, and logs everything. **What ClawVisor gives you:** - **Credential vaulting** — agent sees shadow tokens, never real secrets - **Task-scoped authorization** — each workflow declares exactly what it needs - **Audit trail** — every API call logged with metadata (who, what, when) - **Human approval gates** — destructive operations (send email, modify calendar) require your explicit approval - **Multi-service** — Gmail, Calendar, Contacts, Drive, GitHub, iMessage from one gateway - **Revocation** — disable the agent's access in one click, no token rotation needed **Setup (15 min):** 1. Sign up at [app.clawvisor.com](https://app.clawvisor.com) 2. Create an agent in the dashboard, copy the agent token 3. Set environment variables (in the host agent's environment — shell profile or harness config; gbrain itself has no ClawVisor config keys, these are consumed by the host's ClawVisor integration. This requires an agent host with a ClawVisor integration, such as an OpenClaw deployment. Codex and Claude Code do not consume these variables; use the offline import path instead): ```bash export CLAWVISOR_URL="https://app.clawvisor.com" export CLAWVISOR_AGENT_TOKEN="<token>" ``` 4. Activate Google services (Gmail, Calendar, Contacts) in the dashboard 5. Create a standing task with expansive scope: > "Full brain bootstrapping: read emails, calendar events, and contacts to > populate knowledge base. List, read, and search across all connected accounts." 6. Save the standing task ID the same way: ```bash export CLAWVISOR_TASK_ID="<task_id>" ``` **Critical scoping rule:** Be expansive in task purposes. "Email triage" gets rejected by intent verification. "Full executive assistant email management including inbox triage, searching by any criteria, reading emails, tracking threads" works. The intent model uses the purpose to judge each request. ### If the user declines ClawVisor Do NOT fall back to direct OAuth. Instead, proceed with offline-only imports: - **Phases 2-4** (Contacts, Calendar, Gmail) — work from a Google Takeout export - **Phase 1** (markdown/Obsidian) — works without any API access - **Phase 5** (conversation exports) — works from downloaded JSON files - **Phase 6** (X/Twitter) — works from downloaded archive - **Phase 7** (file archives) — works from local files - **Phase 8** (meeting transcripts) — works from exported transcripts Tell the user: > "No problem. Two options: the native connector (`gbrain google setup`) does > live Gmail/Calendar/Contacts sync with your own OAuth app — tokens stay in > gbrain's local credential vault, never with me — or a Google Takeout export > covers all three as a point-in-time snapshot." **Do NOT hold raw Google tokens yourself.** An agent holding tokens in its context is a security liability. The native connector is the sanctioned OAuth path precisely because gbrain vaults the tokens (0600 file, redacted listings) and the agent only ever runs CLI commands; secrets travel by file or env intake, never argv or chat. See `skills/google-loops/SKILL.md` for the exact protocol. ## Phase 1: Existing Markdown / Obsidian Import For an existing company Git repository, use the migrate (host-side) company workflow instead of the generic import below. On the trusted brain host, start with `gbrain sources inspect <path> --profile company-brain`; confirm an initialized company brain and a new source, show the connect destination/access preview, and obtain approval before `--yes`. Do not flatten its vocabulary by activating or normalizing an unrelated personal schema. The offline `gbrain sources demo company-brain` needs no keys or private data. Details: `docs/guides/company-brain-ingestion.md`. For this company path, stop after reporting the durable receipt; skip the generic import and post-bootstrap checklist below. Later enrichment or scheduling needs separate consent and must respect the source's immutable keyless sync policy. **The highest-leverage first import.** If the user already has a notes system, this is hundreds or thousands of structured pages ready to go. ### Discovery ```bash echo "=== Markdown Repository Discovery ===" for dir in ~/git/* ~/Documents/* ~/notes/* ~/obsidian/*; do if [ -d "$dir" ]; then md_count=$(find "$dir" -name "*.md" -not -path "*/node_modules/*" \ -not -path "*/.git/*" -not -path "*/.obsidian/*" 2>/dev/null | wc -l | tr -d ' ') if [ "$md_count" -gt 5 ]; then total_size=$(du -sh "$dir" 2>/dev/null | cut -f1) echo " $dir ($total_size, $md_count .md files)" fi fi done ``` ### Import ```bash # Obsidian vaults are markdown directories — import directly, then wire wikilinks # (full flow: migrate (host-side)) gbrain import /path/to/vault --no-embed --workers 4 gbrain extract links --source db # parses [[wikilinks]] natively # For plain markdown directories gbrain import /path/to/dir --no-embed --workers 4 # Verify gbrain stats gbrain search "<topic from the imported data>" ``` ### Post-import - Run link extraction: `gbrain extract links --source db` - Run timeline extraction: `gbrain extract timeline --source db` - Start embeddings: `gbrain embed --stale` (runs in background) > **Track progress:** > ```bash > echo '{"phase_1_complete": true, "pages_imported": N}' > ~/.gbrain/cold-start-state.json > ``` ## Phase 2: Google Contacts → People Pages **Seeds the people/ directory.** Every person in your contacts becomes a brain page with name, email, phone, company, and notes. This is the foundation that all other imports build on — when Gmail references "john@acme.com", the brain already knows who John is. ### Via Google Takeout (default on harnesses without ClawVisor) 1. Export contacts from [takeout.google.com](https://takeout.google.com) (select Contacts, CSV format), or directly from [contacts.google.com](https://contacts.google.com) via Export → Google CSV. 2. Parse the CSV: each row carries name, email(s), phone(s), organization, and notes. 3. Run each row through the processing rules below to create people/ pages. ### Via ClawVisor (ClawVisor-integrated hosts only; pseudo-code) ```javascript // Fetch all contacts const contacts = await clawvisor('google.contacts', 'list_contacts', { limit: 1000, fields: 'names,emailAddresses,phoneNumbers,organizations,biographies' }); ``` ### Processing rules For each contact: 1. **Filter out noise** — skip contacts with no name, no email, or that are clearly automated (noreply@, no-reply@, support@, notifications@) 2. **Check brain first** — `gbrain search "name"` to avoid duplicates 3. **Create people/ page** with: - Name, email(s), phone(s), company, title - Source attribution: `[Source: Google Contacts, YYYY-MM-DD]` - Any notes from the contact as initial context 4. **Link to company** — if the contact has an organization, create/update the company page and link the person to it ### Quality gate After importing 5 contacts, pause and show the user a sample page. Ask: > "Here's what a contact page looks like. Want me to continue with the rest, or > adjust the format first?" ## Phase 3: Google Calendar (Last 90 Days) **Meeting history with attendee context.** Calendar events reveal who the user meets with, how often, and in what context. Combined with contacts, this builds a rich relationship map. ### Fetch events **Via Google Takeout (default on harnesses without ClawVisor):** export Calendar from [takeout.google.com](https://takeout.google.com) (ICS format, one file per calendar). Parse each event (title, start/end, attendees), keep the last 90 days, and file them into the brain structure below. **Via ClawVisor (ClawVisor-integrated hosts only; pseudo-code):** ```javascript // Via ClawVisor — query ALL calendar accounts const accounts = ['primary@gmail.com', 'work@company.com']; for (const account of accounts) { const events = await clawvisor(`google.calendar:${account}`, 'list_events', { timeMin: new Date(Date.now() - 90 * 86400000).toISOString(), timeMax: new Date().toISOString(), singleEvents: true, orderBy: 'startTime' }); } ``` ### Brain structure Follow the three-tier calendar architecture: ``` brain/daily/calendar/ ├── calendar-log.md ← compiled truth (patterns, key people) ├── YYYY/ │ ├── YYYY-MM.md ← monthly summary │ └── YYYY-MM-DD.md ← daily event log ``` ### Entity enrichment For each event with attendees: 1. Look up each attendee in the brain (they should exist from Phase 2), by exact match only (`gbrain whois <email or name> --json`) ([identity rule](../conventions/brain-first.md#identity-exact-match)) 2. Add a timeline entry to their page: met at [event title] on [date] 3. If an attendee has no brain page and appears in 3+ events, create one 4. Link attendees who appear in the same meeting ## Phase 4: Gmail (Recent Threads) **Relationship context and active threads.** Email reveals organizational relationships, ongoing conversations, and communication patterns. On harnesses without a ClawVisor integration, the source is the Gmail mbox file from a [Google Takeout](https://takeout.google.com) export. The sampling and filtering rules below apply the same way. ### Strategy: Smart sampling, not bulk import Don't import every email. Import the **signal**: 1. **Sent mail (last 30 days)** — who the user actively communicates with 2. **Starred/important emails** — user-curated signal 3. **Threads with 3+ replies** — active conversations worth tracking 4. **Emails from people already in the brain** — enrichment, not cold import ### Processing For each email thread: 1. **Entity detection** — extract people, companies mentioned 2. **Update people pages** — add communication context to timeline 3. **Create meeting pages** — if the email is a meeting summary or follow-up 4. **Skip noise** — newsletters, automated notifications, marketing ### Filtering rules **Auto-skip (never import):** - noreply@, no-reply@, notifications@, support@, mailer-daemon@ - Unsubscribe-heavy senders (marketing) - GitHub/Jira/Linear notification emails - Calendar invites (already captured in Phase 3) **Always import:** - Direct emails from people in the brain - Starred/flagged emails - Emails the user sent (their words are highest-value signal) ## Phase 5: Conversation Exports (ChatGPT / Claude / Perplexity) **Your thinking, captured.** AI conversation exports reveal what the user was researching, building, and thinking about. This is original thinking preserved in dialog form. ### Supported formats - **ChatGPT:** Settings → Data Controls → Export → `conversations.json` - **Claude:** Download from claude.ai conversation history - **Perplexity:** Export from settings ### Processing For each conversation: 1. **Assess significance** (1-5 scale): - 1 = Pure utility (how-tos, quick lookups) → skip or minimal page - 2 = Minor context → 1-paragraph note - 3 = Notable (reveals interests, building something) → full page - 4 = Important (deep personal processing, strategic thinking) → rich page - 5 = Defining (identity work, breakthrough insights) → full treatment 2. **Extract entities** — people, companies, concepts discussed 3. **Capture original thinking** — the user's exact phrasing is the signal. Never paraphrase. 4. **File by primary subject** — not in a "conversations/" dump. A conversation about a person goes to people/, about a concept goes to concepts/, etc. ### Quality rule Only import conversations rated 3+. The brain is for signal, not noise. ## Phase 6: X/Twitter Archive **Your public positions and engagement patterns.** Twitter reveals what the user thinks, who they engage with, and what ideas they're developing publicly. ### Data sources 1. **Twitter data export** (Settings → Your Account → Download Archive) - Contains all tweets, likes, DMs, bookmarks 2. **Live API** (if available) — recent tweets and engagement 3. **Bookmarks** — curated signal, high value ### Brain structure ``` brain/media/x/{handle}/ ├── x-log.md ← compiled truth (themes, voice, key threads) ├── daily/YYYY-MM-DD.md ← daily tweet log ├── monthly/YYYY-MM.md ← monthly rollup └── bookmarks/ ← saved/bookmarked content ``` ### Processing - **Original tweets** → capture with full context, extract entities - **Quote tweets** → capture the user's commentary + the source tweet - **Threads** → reconstruct as a single narrative - **Bookmarks** → high-signal curation, import with tags - **Likes** — low signal, skip unless the user wants them ## Phase 7: File Archives **Historical documents, old writing, photos with metadata.** This is the long tail — less structured but potentially very high value (old journals, letters, early writing). Delegate to the `archive-crawler` skill. It handles: - Crawling directory structures