migrate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrate Skill

GBrain数据迁移指南

Universal migration from any wiki, note tool, or brain system into GBrain.

支持从任意维基、笔记工具或知识系统迁移至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.

源数据绝不会被修改或删除，迁移仅为增量操作。
每个迁移的页面都会进行往返验证：写入GBrain、重新读取并抽样检查。
源系统中的交叉引用（维基链接、块引用、标签）将转换为GBrain的对应格式。
在批量执行迁移前，会先对样本（5-10个文件）进行测试。
迁移后健康检查会确认页面数量、链接完整性和嵌入覆盖率。

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

数据源	格式	迁移策略
Obsidian	Markdown + `[[wikilinks]]`	直接导入，将维基链接转换为GBrain链接
Notion	导出的Markdown或CSV	解析Notion的导出结构
Logseq	带有 `((block refs))` 的Markdown	将块引用转换为页面链接
纯Markdown	任意.md目录	直接将目录导入GBrain
CSV	表格数据	将列映射为前置元数据字段
JSON	结构化数据	将键映射为页面字段
Roam	JSON导出文件	将块结构转换为页面

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.

评估源数据。格式是什么？有多少文件？结构如何？
规划映射规则。源字段如何映射到GBrain字段（类型、标题、标签、compiled_truth、时间线）？
样本测试。导入5-10个文件，通过从GBrain读取并导出进行验证。
批量导入。将整个目录导入GBrain。
验证。检查GBrain的健康状态和统计数据，抽样检查页面。
构建链接。从内容中提取交叉引用，并在GBrain中创建类型化链接。

Obsidian Migration

Obsidian迁移步骤

Import the vault directory into gbrain (Obsidian vaults are markdown directories)
Wire the graph with native wikilink support (v0.12.1+):
bash
```
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

将Obsidian库目录导入GBrain（Obsidian库本质是Markdown目录）
利用原生维基链接支持构建图谱（v0.12.1及以上版本）：
bash
```
gbrain extract links --source db --dry-run | head -20    # preview
gbrain extract links --source db                         # commit
```
```
extract links
```
原生支持解析
```
[[relative/path]]
```
和
```
[[relative/path|Display Text]]
```
格式，同时兼容标准的
```
[text](page.md)
```
Markdown语法。祖先搜索解析功能可处理作者省略一个或多个
```
../
```
前缀的维基知识库。维基链接会自动推断
```
.md
```
后缀。

Obsidian专属处理：

标签（
```
#tag
```
）将转换为GBrain标签
前置元数据属性映射到GBrain前置元数据
附件（图片、PDF）会被记录，但通过文件存储单独处理

Notion Migration

Notion迁移步骤

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

从Notion导出：设置 > 导出 > Markdown & CSV
Notion导出的文件包含嵌套目录，文件名带有UUID
移除文件名中的UUID以获得简洁的别名（slug）
将Notion的数据库属性映射为前置元数据
将清理后的目录导入GBrain

CSV Migration

CSV迁移步骤

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

对于表格数据（如CRM导出、联系人列表）：

为CSV中的每一行创建一个页面，将列值作为前置元数据
使用指定列作为别名（slug，例如姓名列）
使用另一列作为compiled_truth（例如备注列）
将每个页面存储到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"

任何迁移完成后：

检查GBrain统计数据，确认页面数量与源数据一致
检查GBrain健康状态，排查孤立页面和缺失的嵌入内容
从GBrain导出页面进行往返验证
抽样检查5-10个页面，从GBrain中读取查看
测试搜索功能：在GBrain中搜索「数据中你认识的某个人」

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.

未做样本测试就批量导入。绝不要在验证5-10个文件前导入完整数据集。清理数百个错误页面的成本极高。
删除源数据。迁移是增量操作。绝不要修改、移动或删除源文件。
忽略交叉引用。源系统中的维基链接、块引用和标签必须转换为GBrain的对应格式。丢弃这些会导致知识图谱丢失。
跳过验证步骤。未进行导入后健康检查、页面数量对比和抽样检查的迁移是不完整的。

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

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)

在GBrain中存储/更新页面（put_page）
从GBrain读取页面（get_page）
在GBrain中关联实体（add_link）
在GBrain中为页面添加标签（add_tag）
获取GBrain统计数据（get_stats）
检查GBrain健康状态（get_health）
在GBrain中搜索（query）