Migrate Skill
Universal migration from any wiki, note tool, or brain system into GBrain.
Contract
- Source data is never modified or deleted; migration is additive only.
- Every migrated page is verified round-trip: written to gbrain, read back, spot-checked.
- Cross-references from the source system (wikilinks, block refs, tags) are converted to gbrain equivalents.
- Migration is tested on a sample (5-10 files) before bulk execution.
- Post-migration health check confirms page count, link integrity, and embedding coverage.
Supported Sources
| Source |
Format |
Strategy |
| Obsidian |
Markdown + [[wikilinks]] |
Direct import, convert wikilinks to gbrain links |
| Notion |
Exported markdown or CSV |
Parse Notion's export structure |
| Logseq |
Markdown with ((block refs)) |
Convert block refs to page links |
| Plain markdown |
Any .md directory |
Import directory into gbrain directly |
| CSV |
Tabular data |
Map columns to frontmatter fields |
| JSON |
Structured data |
Map keys to page fields |
| Roam |
JSON export |
Convert block structure to pages |
Phases
- Assess the source. What format? How many files? What structure?
- Plan the mapping. How do source fields map to gbrain fields (type, title, tags, compiled_truth, timeline)?
- Test with a sample. Import 5-10 files, verify by reading them back from gbrain and exporting.
- Bulk import. Import the full directory into gbrain.
- Verify. Check gbrain health and statistics, spot-check pages.
- Build links. Extract cross-references from content and create typed links in gbrain.
Obsidian Migration
Import the vault directory into gbrain (Obsidian vaults are markdown directories)
Wire the graph with native wikilink support (v0.12.1+):
gbrain extract links --source db --dry-run | head -20 # preview
gbrain extract links --source db # commit
extract links natively parses [[relative/path]] and [[relative/path|Display Text]]
alongside standard [text](page.md) markdown syntax. Ancestor-search resolution handles
wiki KBs where authors omit one or more leading ../ prefixes. The .md suffix is
inferred automatically for wikilinks.
Obsidian-specific:
- Tags (
#tag) become gbrain tags
- Frontmatter properties map to gbrain frontmatter
- Attachments (images, PDFs) are noted but handled separately via file storage
Notion Migration
- Export from Notion: Settings > Export > Markdown & CSV
- Notion exports nested directories with UUIDs in filenames
- Strip UUIDs from filenames for clean slugs
- Map Notion's database properties to frontmatter
- Import the cleaned directory into gbrain
CSV Migration
For tabular data (e.g., CRM exports, contact lists):
- For each row in the CSV, create a page with column values as frontmatter
- Use a designated column as the slug (e.g., name)
- Use another column as compiled_truth (e.g., notes)
- Store each page in gbrain
Verification
After any migration:
- Check gbrain statistics to verify page count matches source
- Check gbrain health for orphans and missing embeddings
- Export pages from gbrain for round-trip verification
- Spot-check 5-10 pages by reading them from gbrain
- Test search: search gbrain for "someone you know is in the data"
Anti-Patterns
- Bulk import without sample test. Never import the full dataset before verifying with 5-10 files. The cost of cleaning up hundreds of bad pages is enormous.
- Destroying source data. Migration is additive. Never modify, move, or delete the source files.
- Ignoring cross-references. Wikilinks, block refs, and tags from the source system must be converted to gbrain equivalents. Dropping them loses the knowledge graph.
- Skipping verification. A migration without post-import health check, page count comparison, and spot-check reads is incomplete.
Output Format
MIGRATION REPORT -- [source] -> GBrain
=======================================
Source: [format] ([file count] files, [size])
Mapping: [field mapping summary]
Sample Test (N files):
- Imported: N/N
- Round-trip verified: N/N
- Cross-refs converted: N
Bulk Import:
- Total imported: N
- Skipped (duplicates/errors): N
- Links created: N
- Tags migrated: N
Verification:
- Page count match: [yes/no]
- Health check: [pass/fail]
- Search test: [query] -> [result count] hits
Tools Used
- Store/update pages in gbrain (put_page)
- Read pages from gbrain (get_page)
- Link entities in gbrain (add_link)
- Tag pages in gbrain (add_tag)
- Get gbrain statistics (get_stats)
- Check gbrain health (get_health)
- Search gbrain (query)
Source: garrytan/gbrain → skills/migrate/SKILL.md
1---2name: migrate3description: "Universal migration from Obsidian, Notion, Logseq, markdown, CSV, JSON, Roam"4allowed-tools: "put_page search add_link add_tag sync_brain"5category: engineering-core6source_repo: garrytan/gbrain7source_path: "skills/migrate/SKILL.md"8source_url: https://github.com/garrytan/gbrain/blob/HEAD/skills/migrate/SKILL.md9metadata:10 source: https://skillmd.com/skills/garrytan/migrate11---121314# Migrate Skill1516Universal migration from any wiki, note tool, or brain system into GBrain.1718## Contract1920- Source data is never modified or deleted; migration is additive only.21- Every migrated page is verified round-trip: written to gbrain, read back, spot-checked.22- Cross-references from the source system (wikilinks, block refs, tags) are converted to gbrain equivalents.23- Migration is tested on a sample (5-10 files) before bulk execution.24- Post-migration health check confirms page count, link integrity, and embedding coverage.2526## Supported Sources2728| Source | Format | Strategy |29|--------|--------|----------|30| Obsidian | Markdown + `[[wikilinks]]` | Direct import, convert wikilinks to gbrain links |31| Notion | Exported markdown or CSV | Parse Notion's export structure |32| Logseq | Markdown with `((block refs))` | Convert block refs to page links |33| Plain markdown | Any .md directory | Import directory into gbrain directly |34| CSV | Tabular data | Map columns to frontmatter fields |35| JSON | Structured data | Map keys to page fields |36| Roam | JSON export | Convert block structure to pages |3738## Phases39401. **Assess the source.** What format? How many files? What structure?412. **Plan the mapping.** How do source fields map to gbrain fields (type, title, tags, compiled_truth, timeline)?423. **Test with a sample.** Import 5-10 files, verify by reading them back from gbrain and exporting.434. **Bulk import.** Import the full directory into gbrain.445. **Verify.** Check gbrain health and statistics, spot-check pages.456. **Build links.** Extract cross-references from content and create typed links in gbrain.4647## Obsidian Migration48491. Import the vault directory into gbrain (Obsidian vaults are markdown directories)502. Wire the graph with native wikilink support (v0.12.1+):5152 ```bash53 gbrain extract links --source db --dry-run | head -20 # preview54 gbrain extract links --source db # commit55 ```5657 `extract links` natively parses `[[relative/path]]` and `[[relative/path|Display Text]]`58 alongside standard `[text](page.md)` markdown syntax. Ancestor-search resolution handles59 wiki KBs where authors omit one or more leading `../` prefixes. The `.md` suffix is60 inferred automatically for wikilinks.6162Obsidian-specific:63- Tags (`#tag`) become gbrain tags64- Frontmatter properties map to gbrain frontmatter65- Attachments (images, PDFs) are noted but handled separately via file storage6667## Notion Migration68691. Export from Notion: Settings > Export > Markdown & CSV702. Notion exports nested directories with UUIDs in filenames713. Strip UUIDs from filenames for clean slugs724. Map Notion's database properties to frontmatter735. Import the cleaned directory into gbrain7475## CSV Migration7677For tabular data (e.g., CRM exports, contact lists):781. For each row in the CSV, create a page with column values as frontmatter792. Use a designated column as the slug (e.g., name)803. Use another column as compiled_truth (e.g., notes)814. Store each page in gbrain8283## Verification8485After any migration:861. Check gbrain statistics to verify page count matches source872. Check gbrain health for orphans and missing embeddings883. Export pages from gbrain for round-trip verification894. Spot-check 5-10 pages by reading them from gbrain905. Test search: search gbrain for "someone you know is in the data"9192## Anti-Patterns9394- **Bulk import without sample test.** Never import the full dataset before verifying with 5-10 files. The cost of cleaning up hundreds of bad pages is enormous.95- **Destroying source data.** Migration is additive. Never modify, move, or delete the source files.96- **Ignoring cross-references.** Wikilinks, block refs, and tags from the source system must be converted to gbrain equivalents. Dropping them loses the knowledge graph.97- **Skipping verification.** A migration without post-import health check, page count comparison, and spot-check reads is incomplete.9899## Output Format100101```102MIGRATION REPORT -- [source] -> GBrain103=======================================104105Source: [format] ([file count] files, [size])106Mapping: [field mapping summary]107108Sample Test (N files):109- Imported: N/N110- Round-trip verified: N/N111- Cross-refs converted: N112113Bulk Import:114- Total imported: N115- Skipped (duplicates/errors): N116- Links created: N117- Tags migrated: N118119Verification:120- Page count match: [yes/no]121- Health check: [pass/fail]122- Search test: [query] -> [result count] hits123```124125## Tools Used126127- Store/update pages in gbrain (put_page)128- Read pages from gbrain (get_page)129- Link entities in gbrain (add_link)130- Tag pages in gbrain (add_tag)131- Get gbrain statistics (get_stats)132- Check gbrain health (get_health)133- Search gbrain (query)134135---136137**Source:** [`garrytan/gbrain`](https://github.com/garrytan/gbrain) → `skills/migrate/SKILL.md`