How to Import Heptabase Data into Flexnote in One Click

When you switch note apps, the real cost is rarely learning a new interface. It is whether years of history can move with you. If you have already built up cards, whiteboards, PDF highlights, journals, and tags in Heptabase for literature work or long research, starting from an empty workspace is usually not realistic.

Flexnote can now read local Heptabase data (hepta.db or a Backup) and import it by space in one click. You can create a matching Flexnote workspace for each Heptabase space, or write selected content into the current workspace; on a second import you can skip or overwrite. The importer only reads the source—it does not modify, delete, or move your existing Heptabase files.

What can be imported?

This is not a plain text copy. Flexnote scans local Heptabase data and converts each content type structurally. Current support:

Before you import: main conversion rules

Use the local database, not JSON export alone

The current version imports from a local hepta.db or Backup folder. If you only have an all-data.json export and no matching database, whiteboard structure and attachment paths cannot be fully restored yet. Desktop Flexnote will try to detect Heptabase automatically; if it cannot, you can pick a Backup folder manually.

Whiteboards convert by structure, not as screenshots

Card instances, sections, text elements, media, PDFs, mind-map nodes, and connections on the board are converted by type. Connections keep path style, arrows, color, and rich-text labels as much as possible. Because Heptabase and Flexnote canvas models are not identical, spot-check your most-used boards after import—especially complex nested sections, color semantics, or unusual nodes.

PDF highlights and note highlights map separately

Text and area highlights in PDFs land in the PDF reader, with color and position aligned to the source as closely as possible. Highlight marks in card bodies become Flexnote note highlights and keep their linked notes. After import, check a few PDFs and notes with highlights to confirm display and jump behavior.

Card height follows the size Heptabase recorded

The two products differ in content padding and default type size. To reduce overlapping cards on the whiteboard, import keeps the card height recorded by Heptabase and turns off auto height. You can still resize manually in Flexnote afterward, or turn auto height back on.

Steps

Step 1: Open import and detect local Heptabase

Open the import dialog from the Flexnote sidebar and choose Heptabase. Desktop will try to read local data; on success it shows the version plus note, whiteboard, journal, and tag counts per space. If auto-detect fails, click Choose Backup to pick a folder, or run Detect again.

Step 2: Choose spaces and write target

Select the Heptabase spaces to import, then choose where they go:

• Create a workspace for each space: closest to the original structure; best for a full migration. If the free plan only allows one workspace, upgrade before importing spaces separately.
• Import into the current workspace: writes selected spaces into the open workspace—useful for one project or a small trial.

Step 3: Start import and verify

After you start, progress is shown. When it finishes, you get totals for new notes, journals, whiteboards, PDFs, highlights, mind maps, properties, views, and attachments. Then verify: boards you use often, notes with backlinks or mentions, PDFs with highlights, and tagged journals.

Re-import and deduplication

By default, already-imported objects are not created again. Flexnote remembers the mapping from source to target. When you import the same batch again, you can:

• Skip existing: keep versions you already edited in Flexnote, and only add what is still missing—best for day-to-day incremental migration.
• Overwrite: update existing items from current Heptabase content and sync new whiteboard items. Confirm first that Flexnote does not hold local edits you still need to keep.

Suggested migration flow

1. Back up Heptabase data (or confirm Backup is available), and back up Flexnote data;
2. Prefer a smaller space that already mixes notes, whiteboards, and PDFs for a trial import;
3. Check whiteboard layout, connection labels, PDF highlight colors, and card mentions / backlinks;
4. If that looks good, import the remaining spaces;
5. For later incremental imports, prefer Skip existing; only choose Overwrite when you intentionally want Heptabase as the source of truth.

Import lowers the cost of moving data—it does not require you to drop your current workflow overnight. You can migrate the project board you are actively working on, keep using local-first whiteboards, multimedia annotation, and a one-time purchase plan in Flexnote, and leave Heptabase as a read-only archive for a while after a full move. Validate on a small sample of real work first, then decide how much to migrate next.