A Heptabase library is more than its paragraphs. The positions of cards, the boards nested inside other boards and the links between ideas carry part of the work. Use a complete backup when trying Acres so the importer has that structure to read.
Acres provides a built-in Heptabase importer. You can evaluate a copied library in a separate local workspace, keeping your original Heptabase data available while you check the result. If the decision is still open, Acres vs Heptabase covers the features you would gain and give up, including mobile access, collaboration and research tools.
Export the full backup and keep it intact
Heptabase’s data portability guide documents a full export from its desktop or web app. Its current route is Settings → Backup → Export now. The complete ZIP contains Markdown exports and structured backup data in All-Data.json.
Keep that ZIP unchanged as your source backup. Extract a working copy into a local folder, and check where All-Data.json actually sits. An archive may unpack into an extra containing folder; Acres needs the folder with that file directly inside it.
Keep the accompanying files together. Copying only the JSON can leave the importer unable to locate PDFs or images. If the extracted folder is on a cloud drive, make sure the files are downloaded and readable before running the import.
A Markdown-only copy can be useful for reading notes elsewhere, but it does not supply the complete structured data for this migration. The full export is also distinct from a restore procedure inside Heptabase. Keep the original backup for that purpose and consult its support guidance if you need recovery.
Create a separate Acres destination
The Acres launcher import can recognize a Heptabase backup and create a new vault for the converted material.
- In the Acres launcher, choose the import option.
- Select the extracted backup folder containing
All-Data.json. - Choose a distinct name and location for the new Acres vault.
- Start the import and read its result and warnings.
- Open an imported whiteboard and compare it with the original.
The launcher copies from the selected source into the new workspace. Keeping the destination separate makes it easier to distinguish the backup, the original app and the converted Acres library.
If the importer says the folder is not a Heptabase backup, inspect the extracted folder before trying again. Common causes are selecting the ZIP itself, selecting the outer folder instead of the one holding All-Data.json, or using only the Markdown portion of the export.
Check the layout as well as the note count
Supported board elements are imported using their original coordinates and sizes. That saves rebuilding a visual map from a flat list. The imported board still renders in Acres, so text height, fonts and some object behavior can differ.
Start with three boards: a simple card map, a board with sections and labeled connections, and a board containing another whiteboard. Check that the relative arrangement still communicates the original idea. Follow several connections rather than judging only the overview.
The hierarchy is reconstructed from whiteboard embeds. If the same child board appears under several parents, check which place becomes its primary location in the board hierarchy. A visual embed and a single parent in a navigation tree are different relationships.
Trashed and empty boards can be skipped. Unsupported connections or missing targets can also produce differences. Review the warnings alongside the boards, especially where a layout appears incomplete.
Check the Markdown conversion
Heptabase card content is converted into Markdown for Acres. That gives you ordinary note files, but conversion between rich-text models deserves a closer look than opening one title.
| Sample material | What to check |
|---|---|
| Long note | Paragraph order, headings and lists |
| Note with references | Link targets and whether the source is still identifiable |
| Table or unusual formatting | Readability and conversion warnings |
| Reused card | Shared note content across its board placements |
| Library-only card | Presence in the Library even if absent from the first board |
| Journal entry | Correct date and readable imported content |
The import report can count placed cards separately from library-only notes and journal entries. A placement count is not necessarily the number of distinct notes you used in Heptabase. Before concluding that something is missing, look in the Library or journal and search for a distinctive phrase from the source.
Check a few notes that matter to your current work. If a specialized object or formatting style does not convert as you need, retain a reference copy and decide whether to simplify it in Acres or keep using Heptabase for that material.
PDFs and highlights need their own review
Open a PDF from an imported board to confirm the underlying file is available. Missing media can come from an incomplete extracted backup or an attachment the importer cannot resolve; read the reported warnings before assuming the PDF itself is damaged.
Placed text highlights import as board text containing the quote, note and source information. Area highlights can be represented by their snapshot images. Those representations preserve useful material on the board, but they are not automatically equivalent to a native annotation in the Acres PDF reader.
Check the highlighted passage against the source PDF. Keep enough source context to find it again, and preserve the original backup for highlights which need further work. Unplaced annotation behavior, source navigation and unusual PDF objects should not be inferred from a successful import of one visible quote.
Treat another import as a separate decision
The imported vault is a snapshot. New Heptabase work does not appear automatically, and Acres edits do not update Heptabase.
Do not use repeated imports as an assumed merge between two active libraries. Importing again can replace board data and imported journal sections; other content may be handled differently. Back up the destination before repeating the process, or create a fresh destination to inspect a newer snapshot without disturbing the trial you have edited.
Use one active project during the 14-day trial. Find an old card, inspect a source PDF, navigate the nested boards and make a small new note. If you want AI help after that, the local assistant guide covers Ollama and LM Studio, while the MCP workflow covers an external agent.
Heptabase’s access policy says content remains viewable and exportable after a subscription or trial ends. Keep your source available until the converted workspace has proved useful for your actual work.