How to Migrate from Logseq to VaultBook: A Complete Step-by-Step Guide

Elena Marsh did not decide to leave Logseq because of a feature comparison chart. She decided on a Tuesday morning, standing in her kitchen with a phone in one hand and a client deadline in the other, watching a small sync indicator refuse to move.

The night before, she had worked late. Elena is a freelance research analyst and writer. Companies hire her to make sense of messy subjects — a market they do not understand yet, a competitor they have underestimated, a pile of interviews, reports, and half-remembered decisions that needs to become a document someone can actually act on. For four years, almost all of that work has lived in one place: her Logseq graph.

Her daily journal was where each morning started. Her client research pages held the interview notes, the source summaries, and the slow accumulation of understanding that turned into paid work. Her reading notes held the books and papers she returned to again and again. Project pages held tasks, drafts in outline form, and the small, unglamorous blocks of text that never make it into a final report but explain why the final report says what it says. Altogether, the graph had grown to roughly 3,800 pages.

That Monday night, the work had gone well. She had restructured a client page on her laptop, added a run of notes from her phone while she was thinking about them away from her desk, and closed everything feeling, for once, ahead of the next morning.

On Tuesday, the graph told her otherwise.

The sync status stalled. Changes she knew she had made would not progress. On the phone, an edit she had made with confidence sat behind a status that suggested all was well, and yet the material was not where she expected it to be when she went looking for it on the laptop. Nothing dramatic exploded. No error message announced a catastrophe. That was almost the worst part. The system simply did not do the quiet, boring thing she had trusted it to do: keep one body of work, the same, in the places she worked on it.

She lost the morning to it. Not the whole graph — let us be precise, because precision matters in a migration guide — but a morning of checking, reopening, comparing, and rebuilding her confidence in which version of a page was the real one. A freelance analyst does not sell hours in the abstract. She sells mornings like that one. When a tool eats one, it has taken something real.

What made the morning decisive was not the stall itself. Sync problems happen. Software has bad versions. Elena had lived through rough edges before and stayed, because the core bargain of Logseq was so good. You kept plain Markdown files, in a folder you owned, written in a format any competent editor could open. You got an outliner that matched how research actually forms — in fragments, in hierarchies, in connections discovered later — plus daily journals, backlinks, linked references, block references, queries, and a graph view that sometimes showed you a relationship you had not consciously made. That bargain was worth tolerating a lot for.

Sitting with the stalled sync, she realised the bargain itself had split in two.

The Logseq she had chosen — the file-based version, built on Markdown files in a local folder — was no longer the future of the product. It would continue, but in maintenance mode: security and maintenance updates, no new features. The future was a different Logseq, a database version that stored a graph in a local SQLite database rather than in a folder of plain files. That version was in beta, it was where the development energy had gone, and adopting it meant giving up the exact property that had made her choose Logseq in the first place: files she could open, read, move, and understand without the application that created them.

She did not hate the database version. She did not think the people building it were villains, and she did not think everyone who had moved to it was foolish. We will meet the people who defend it, and defend it well, later in this guide, because any honest decision framework has to include them. Her conclusion was narrower and more personal: the product she had signed up for was now the legacy edition of itself, the product being built in its place asked for a trade she did not want to make, and the sync failure had shown her what it felt like when the machinery around her notes stopped being boring.

So she decided to migrate — and, crucially, to migrate now, on her own terms, while the decision was still cheap.

Cheap is the right word, and it is worth understanding why. Because her graph was still a file graph, her notes were still Markdown. Every page was a text file. Every link was text she could search. Every asset was a file in a folder. Moving was going to be work — this guide will not pretend otherwise, and the sections that follow will show you exactly where the work is — but it was work she could do with ordinary tools, at her own pace, with the original graph left untouched as a safety net. If she waited, drifted onto the database version out of inertia, and decided a year later that she wanted out, the same move would start with an export step known to be imperfect, and she would be migrating from a printout of her graph rather than from the graph itself.

This guide follows her migration, step by step, into VaultBook: a single-file HTML application, local-first, that makes zero network requests, holding her work in one encrypted file she controls, with entries, labels, wiki links, and full search, plus a set of built-in document, PDF, and audio tools her graph never had. It is not a one-click story. VaultBook has no Logseq importer, and Part B of this guide will describe the honest manual path — copying Markdown in, restructuring it into entries, rebuilding links as wiki links and labels — without dressing it up as automation. It is also not a story about a perfect destination. VaultBook has no graph view, no outliner, no block references, no Datalog queries, and no plugins, and if those are the centre of your working life, this guide will tell you plainly to stay where you are.

But if you recognise Elena’s morning — or, more quietly, if you recognise her realisation — then this guide is for you. It is written for the Logseq user who still loves much of what Logseq is, who is not looking for a fight, and who wants to move a working life’s worth of notes without losing the parts that matter. We will start with why so many people are reconsidering at the same time, then build an honest framework for deciding whether you should move at all, then audit a graph the way Elena audited hers, then lock down backups before a single file is touched. Only after that, in Part B, do the hands-on migration steps begin.

Why Logseq users are reconsidering now

To understand why migration guides for Logseq exist at all in this moment, you first have to understand how unusual Logseq’s original promise was — and how well, for a long time, it kept it.

Most note-taking products ask you to trust a container. Your notes live inside their database, behind their account system, reachable through their application, exportable in whatever form they choose to offer, on whatever schedule they choose to offer it. Logseq’s file graph asked for almost none of that trust. A graph was a folder. Pages were Markdown files — or Org-mode files, for those who preferred them — sitting in that folder with ordinary filenames. You could open the folder in a file manager and see your knowledge base as a pile of documents. You could open any page in a different editor and read it, because there was almost nothing proprietary to decode: headings, indented blocks, links written as text, properties written as text.

On top of those files, Logseq built a genuinely distinctive way of working. It is worth describing what people love about it properly, because people who write migration guides too often describe the product being left as though it were a mistake its users made. It was not a mistake. For many researchers, writers, students, and engineers, Logseq’s model fitted their thinking better than anything else they had tried.

The outliner came first. Research does not arrive as finished prose. It arrives as a sentence from an interview, a figure that needs checking, a contradiction between two sources, a question you cannot yet answer. An outliner lets you capture those fragments at the size they actually are, nest them under the page or heading they belong to, collapse what you are not working on, expand what you are, and rearrange the whole structure as understanding improves. Elena’s client pages were not essays; they were living outlines that slowly became essays elsewhere, and the outline was where the thinking happened.

The daily journal came second, and for many users it mattered even more. Each day opened a fresh page, dated, ready. You did not have to decide where a thought belonged before you were allowed to write it down. You wrote it in today’s journal, linked it to the pages it concerned, and trusted that backlinks and linked references would gather it again when you visited those pages later. Capture friction dropped close to zero, and a searchable, linked diary of your working life accumulated almost as a side effect. Rebuilding that journal flow is one of the hardest parts of leaving Logseq, and users who are considering a move name it again and again — not as a feature on a checklist, but as a habit woven into their days.

Then there were the connections. Links in Logseq were cheap to make and paid you back in several currencies: ordinary page links, backlinks listed automatically, linked references that pulled in blocks mentioning a page, block references that let one specific block appear, live, inside another page, and block embeds that went further still. A graph view drew the whole web of pages so you could see clusters and orphans. Queries let you build living lists — every open task tagged a certain way, every block with a certain property, every page touched this week — using a query language with real power behind it. Add tasks that lived inside your notes rather than in a separate application, PDF annotation that kept your reading attached to your pages, flashcards, whiteboards, and a plugin ecosystem that let people bend the tool toward their own trades, and you had something that was not really interchangeable with a folder of documents or a conventional notes app. Open-source, under the AGPL-3.0 licence, local-first, free at its core. It is no wonder people invested years in it.

Which is why the present moment is best described not as a failure, but as a fork.

One product, two Logseqs

Logseq now exists in two forms that share a name, a history, and a great deal of code and design language, but that rest on different answers to the most fundamental question a notes tool can ask: where, physically, do your notes live?

In Logseq OG — the file-based version, the one Elena chose — the answer is the folder. The application is, in an important sense, a very sophisticated way of viewing and editing a set of Markdown files that would still exist, legible and complete, if the application were deleted. The files are the truth. The application is an interpretation of them.

In the database version — Logseq 2.0, currently in beta — the answer is a local SQLite database. Your graph lives in that database. The database version is still local-first: this is not a story about notes being moved to someone else’s cloud against anyone’s will. But a SQLite database is a different kind of home from a folder of text files. You cannot browse it in a file manager and read your pages. You cannot open a page in another editor, because there is no page file to open. To use a database graph in Markdown editors at all, you must export it — and export, as we will see, is not the same as the files simply being there.

The division of labour between the two versions is what turns this fork into a decision. The file-based version continues with maintenance and security updates, but no new features. It is not being switched off, and nobody is being forced off it at gunpoint; Elena’s graph still opens, still works, and could have gone on opening and working for a long time. But a maintenance-only product is a product whose future is a slow narrowing. Bugs that are not security issues wait. Integrations age. The surrounding world — operating systems, sync services, the formats of things you clip and attach — keeps moving, and a tool standing still gradually fits it worse. Meanwhile the database version receives the development energy: new data-model features, new properties handling, performance work, the team’s attention. Staying on files therefore does not mean staying on the Logseq you have; it means staying on a snapshot of it, while the living product grows in a direction built on a storage model you did not choose.

That is the honest version of the split, and this guide will stick to it. It is not that the file version was taken away. It is that it was reclassified — from the product, to the predecessor.

Why the database question cuts so deep

If the new version merely changed an internal implementation detail, few people would care, and this guide would not exist. Users do not generally audit how their software stores data. The reason the database move produces such strong reactions among Logseq users specifically is that, for this user base, storage was never an implementation detail. It was the selection criterion.

People chose Logseq, in large numbers, because of the files. They say so, consistently, when they explain themselves: they came for plain Markdown that any editor can open, for a folder they could point at and call theirs, for freedom from exactly the kind of container-dependence they had experienced elsewhere. A database — even a local, well-understood, technically respectable database like SQLite — removes the property they bought. You can no longer read your notes without tooling. Backups become backups of one opaque artefact rather than of many legible ones. A corruption problem, if one occurs, threatens a single point of failure instead of a single replaceable page. Whether those fears are proportionate in every case is a fair question, and defenders of the database version argue, reasonably, that a database brings real benefits: a richer properties system, new organisational features such as supertags, faster navigation around a large graph once it is open, and relief from some of the file version’s known costs, including the way the file version loads pages into an in-memory database of its own and can grow heavy as a graph gets complex. Those arguments deserve their place, and they get it in the decision framework below. But even if every one of them is granted, the trade remains a trade: you are exchanging legibility and editor-independence for capability and structure, and users who chose the tool for legibility are entitled to experience that as a fundamental change, not a routine upgrade.

The export question sharpens the point. A database graph can be exported to Markdown — the door is not locked. But by multiple user accounts, the door does not open back onto the same landscape. Exporting can flatten a graph’s folder structure, placing files together in one folder rather than where they lived. Assets — the images, PDFs, and attachments a graph accumulates — have been reported as not coming along reliably. A mirror mode intended to keep a Markdown copy alongside the database has been reported as missing data on some pages. And the round trip can fray in the other direction too: importing a Markdown graph into the database version has, for some users, produced long lists of import errors, pages arriving as tags, and pages that did not arrive at all. None of this means export never works, or that every import is a mess; plenty of graphs have crossed over without drama. It means export is best understood as a translation, with the losses translations have, rather than as the files simply changing hands. If your notes are already Markdown, you hold the original text. If they become a database first, you hold a translation of it ever after.

Elena kept returning to a simple formulation during the week after the sync stall, and it may help you too: she did not object to databases. Her working life was full of them, and she trusted several with things she cared about. She objected to her notes becoming one — to the layer of interpretation becoming mandatory, permanent, and hers to depend on.

The sync problem, honestly stated

Storage is the strategic reason people reconsider Logseq now. Sync is very often the practical trigger — the bad morning that turns a background unease into a decision — and it deserves an equally honest treatment, because the truth here is uneven in both directions.

Logseq’s core application is free. Its official sync service is the paid extra — priced, during the beta, at five dollars a month at the Backer tier or fifteen dollars a month at the Sponsor tier, through Open Collective — and many users never pay it, because the file-based design invites you to sync the folder yourself with iCloud, Dropbox, Git, Syncthing, or whatever you already run. That freedom is real, and it is part of the file bargain. But every route, official and do-it-yourself alike, has produced a recognisable set of complaints from the people who rely on it, and the pattern across them is more telling than any single incident.

The complaints cluster around a theme: the status you are shown and the state your data is in can come apart. Users of recent versions describe sync that stalls — an indicator showing unsynced changes that never progress, a mobile sync control that appears to do nothing — with the only reliable workaround being the drastic one: delete the local graph and download it again, after which the problem may return. Older accounts describe sync actively doing harm: blocks duplicated, blocks moved under different parents, material entered offline disappearing in the reconciliation that was supposed to merge it, leaving a choice between a corrupted version and a lost one. A mobile account is particularly hard to read in summary because nothing in it is exotic: a new page synced, edits were made, the application was reopened, an error appeared while the status insisted everything was synced, and the practical remedy — force-quitting — cleared the error at the cost of permanently losing the most recent material. The person in that account was a paying sync customer, on the Markdown version, and the underlying issue was understood to have been open for a long time. Other users, syncing through cloud drives, describe constant re-indexing, duplicated material, and links broken in places they should not break.

What can fairly be said is this: for a tool whose deepest appeal is the simplicity of files on disk, sync reintroduces exactly the opacity the files were meant to spare you. When a folder of Markdown files is in front of you, you can see what you have. When a sync system tells you that you are synced, you are trusting a claim — and Elena’s Tuesday morning was the moment she noticed how much of her working calm had quietly come to rest on claims of that kind. Her response was not to find a better sync service. It was to ask whether her notes needed sync machinery at all, or whether she could organise her work around a single file that she moved deliberately, on media she controlled, with encryption doing the protecting that an account system used to do. That question, more than the stall itself, is what led to VaultBook.

Performance, complexity, and the weight of a grown graph

The third reason users reconsider is slower and less dramatic: a graph that has grown up can become heavy to live in, and heavy in ways that have less to do with page count than with what is in the pages.

Accounts of performance trouble exist at surprisingly modest scales and conspicuously fail to exist at much larger ones. Some users describe graphs around a thousand to fifteen hundred pages becoming slow enough to interrupt the day — sluggish starts, lag in ordinary use, the application needing to be closed down several times daily. Others describe a graph of roughly five thousand pages taking a long time to load where other tools open near-instantly. And then, in the same discussions, other users report graphs of four thousand, seven thousand pages running acceptably, and mean it. Both sets of reports are credible, because page count is a poor proxy for weight. What seems to make a graph heavy is complexity: deep namespaces, nested pages, dense properties, many queries, many images and attachments, elaborate block structures. The file version’s habit of loading the graph into an in-memory database of its own means a complex graph asks a lot of the machine before you have typed a character. The database version promises relief on some of these fronts, and some who have moved report exactly that — faster movement around the graph once it is open — while others report that the new version brings lags, duplicates, or corruption of its own. There is no honest sentence of the form “Logseq is slow beyond N pages,” and this guide will not offer one. There is only a question each user has to answer from their own graph: has yours crossed the line where the tool’s weight is a daily tax on the work it holds?

For Elena, the honest answer was: nearly, and rising. Her graph was not the largest anyone runs, but it was dense in precisely the expensive ways — client namespaces, properties on research pages, queries she relied on to assemble status views, attachments everywhere, four years of journals. She could feel the start-up cost. More significant than raw speed, she had begun to feel the maintenance cost. A grown Logseq graph is not just notes; it is a small system. She had personal conventions to uphold, custom styling, plugins whose behaviour she depended on and some of which were not expected to survive the database move, and queries — dozens of them across her key pages, built up over years — that produced her dashboards. Maintaining the system had become a second job underneath the first one, small most weeks, spiky in bad ones. That experience is common enough among long-tenured users to be a theme in its own right: the tool rewards investment so richly that the investment itself eventually becomes a liability, an apparatus that only its builder fully understands and only its builder can repair.

The honest decision framework: who should stay, who should move

Before you audit a single page, decide whether you should be migrating at all. A migration done for the wrong reasons will disappoint you no matter how carefully you execute it, because no destination reproduces Logseq — and VaultBook, in particular, does not try to. It has no outliner, no block references, no graph view, no Datalog queries, and no plugins. What it offers instead is a different centre of gravity: one encrypted single-file vault, entries organised with labels and wiki links, search that reaches inside attachments and answers questions across the vault, and tools for the documents, PDFs, audio, images, and data that surround written work. That trade is excellent for some Logseq users and wrong for others. Here is how to tell which you are.

Stay if the outliner is the work itself

Stay with Logseq if your thinking genuinely happens at block level. If you routinely reference individual blocks from other pages, embed them, build queries that assemble your day from properties scattered across the graph, and lean on the graph view to navigate — if, in other words, the features with no equivalent elsewhere are not ornaments on your workflow but its load-bearing walls — then leaving will cost you the workflow, not just the tool. Users in that position who try to leave tend to return, and the returning is not failure; it is information. Block references are, consistently, the most-cited loss among people who migrate away from Logseq, precisely because nothing else does them the same way. Queries and properties likewise do not transfer cleanly anywhere. If you would have to rebuild hundreds of queries in a new home that cannot express most of them, the honest recommendation is to stay and solve your actual problem — which may be sync, or performance, or anxiety about the future — by other means.

Stay, also, if the database version genuinely suits you. The counter-voices here are real, and this guide refuses to caricature them. Some users have moved to the database version and like it better: they value the richer property handling and supertags, find navigation around a large graph faster once it is open, and are untroubled by the database because they trust their backups of the database file itself and never much used other editors on their notes. Some of them are impatient with the attachment to plain files, regarding it as nostalgia for a constraint rather than a benefit. They are not shills and they are not confused about what they traded; they weighed legibility against capability and chose capability, for work where capability is what they use daily. If that is your weighing too, VaultBook — which gives up even more power features than the database version does — is certainly not your destination.

Stay if your large graph runs fine. Performance in Logseq is uneven in the way described above: some graphs strain at fifteen hundred pages and some cruise at seven thousand. If yours is in the second group, do not let other people’s lag become your reason to abandon a system that serves you. Stay, similarly, if your sync works. If paid sync, or your own arrangement, has carried your graph between machines and phone for years without eating anything, the horror stories in the previous section are a reason to verify your backups, not necessarily to change your life. And take seriously the most common piece of advice in the community itself: stay on the build that works. The file version remains available and maintained for security. Running a known-good version, with good backups, while you watch how the database version matures, is not procrastination. It is a legitimate strategy with a long pedigree in every corner of software, and for many users it is the correct answer to the fork. You can revisit the decision in a year with more information and, if you are still on files, at no greater cost than you would pay today.

Move if the files were the point

Move if, when you examine your own history, you chose Logseq the way Elena did: files first, features second. If the folder of Markdown was the foundation of your trust, then the maintenance-only status of the file version is not a detail — it means the thing you bought has entered its long twilight, and every year you invest further in it is a year invested in a platform whose living successor asks you to surrender the foundation. Moving is also indicated if sync has already cost you work, or if you have caught yourself doing Elena’s Tuesday-morning labour — reconciling versions by eye, unsure which page is real — because that labour is the sound of a core promise failing. Move if your graph’s complexity has become a maintenance burden: plugins to tend, styling to repair, queries to rebuild, a system only you understand. Move if your work has drifted toward long-form writing, documents, PDFs, recordings, and client deliverables — material an outliner stores awkwardly and a document-centred vault handles natively. And move, especially, if what you need from your notes has simplified over the years. Many mature knowledge bases turn out, on inspection, to need excellent search, clear organisation, reliable encryption, and dependable access far more than they need live queries. If that inspection describes you, the power you would give up is power you no longer use, and the calm you would gain is real.

Why now is the cheapest moment you will ever get

If you do decide to move, timing matters, and the timing argument is the single most practical point in this guide. Migration cost is a function of format. Today, if you are on the file version, your graph is Markdown: human-readable, editor-independent, greppable, complete. Every difficulty in Part B of this guide — restructuring outlines into entries, converting block references by hand, rebuilding links — is a difficulty of form, not of access. You can see everything you own, in full, with a text editor.

Now imagine deferring the decision while drifting, as most users will drift, onto the database version because it is the one receiving updates, the one a fresh install offers, the one support will assume. Your notes become rows in a database. Deciding to leave then means exporting first, and export, as the accounts above describe, can flatten your folders, strand your assets, and pass your pages through a translation layer whose mirror copies have been reported incomplete. You would be migrating from the export, not from the graph — and every loss in that export would become a permanent feature of your new home before you had written a word in it. The same logic applies in miniature to delay on the file version itself: every additional year adds pages, attachments, properties, and habits, all of which must be audited and carried. Graphs do not get cheaper to move by growing.

So the rule is simple: if you are going to leave, leave from the files. Migrate while the original text is still in your hands, while the move is a reorganisation rather than a rescue. That is what “on her own terms” meant for Elena — not anger, not haste, but choosing the moment when the door was widest and walking through it deliberately, with the original graph preserved intact behind her in case the new home disappointed. The next two sections exist to protect that deliberateness: first, know exactly what you have; then, make it impossible to lose.

The pre-migration audit: knowing what your graph actually contains

Do not begin a migration by copying files. Begin by taking inventory. A graph that has grown organically for years will surprise its owner in both directions: there will be far more of some things than you expect, far less of others, and categories of material you had forgotten existed. Elena’s audit took two evenings. It saved her, by her own later estimate, days — because every decision she made during the actual move had already been made, calmly, in advance, and written down.

You will need a written audit, not a mental one. Create a simple document outside the graph — it will become part of your migration record — and work through the categories below, recording counts and notes for your own graph as Elena did for hers. If a count is hard to get exactly, an honest approximation is fine; what matters is knowing the shape of the job before you start it.

Pages, journals, and the shape of the whole

Start with pages: how many, of what kinds? List the graph folder and count the Markdown files, then sort them into the families you actually recognise — client or project pages, people pages, reading and reference notes, concept pages, templates, administrative pages, and the long tail of one-off captures that every graph accumulates. Note the namespaces: pages organised under a hierarchy carry their structure in their names, and that structure has to be deliberately translated into whatever organises the new home — in VaultBook’s case, labels and wiki links — rather than assumed to survive the move. Note, too, the pages that are really something else in disguise: the page that is actually a document draft, the page that is a table of figures, the page that exists only to hold a query. They will need different treatment from ordinary notes, and it is better to know which ones they are now.

Treat the journals as a separate family, because they are. Years of daily pages form a continuous diary with its own value and its own migration logic. Decide, in principle, how you think about them: are they reference material you search, an archive you keep for completeness, or a living practice you intend to continue in some form at the destination? Elena’s answer — archive them faithfully, search them when needed, and start fresh daily notes as ordinary entries in the new vault rather than trying to recreate Logseq’s journal machinery — will not be everyone’s, but everyone needs an answer before the move, because journals are numerous enough to distort every other decision if they are handled ad hoc.

Assets: the weight you cannot see in the text

Next, inventory the assets folder, and do it physically. Open it, look at its total size, and count by type: images, PDFs, audio files, video, everything else. Attachments are where migrations quietly fail, because Markdown text refers to assets rather than containing them, and a move that carries the text and strands the files produces pages full of confident references to things that are no longer there. For each type, ask what it is for. Elena’s assets held client-supplied PDFs she was contractually expected to retain, screenshots that were evidence for claims in her reports, photographs that were merely illustrative, and a stratum of duplicated images pasted twice and referenced once. Those four kinds deserved four different fates — carried carefully, carried, carried cheaply, and culled — and in VaultBook several of them would gain something in transit, since PDFs, images, and audio are things the vault can open, index, and work on with built-in tools rather than merely store. But none of that is possible for an asset you did not know you had. Record the size of the whole folder, too: it determines how long copying takes, what backup media you need, and whether your new single-file vault’s size is something to plan around.

Queries, properties, and block references: the machinery

Now the hard categories — the Logseq machinery that does not travel. Go through your graph for queries first. Find the pages that carry them and list what each query does for you in plain language: not its syntax, but its job. “Assembles every open client task” is a job; the code that does it is Logseq’s and stays behind. For each one, mark whether the job still needs doing at the destination, and if so, by what simpler means — a label, a search, a saved habit. Elena found queries she had forgotten she built, doing jobs she no longer had, alongside a handful she used weekly. The forgotten ones were liberating to leave. The weekly ones became a short, explicit rebuild list, which is exactly what a query should become before a migration: a requirement, written in English.

Properties come next. Pages and blocks in a mature graph carry properties — statuses, types, dates, ratings, client identifiers — that power sorting, filtering, and queries. Export the list of property keys your graph actually uses, and for each, decide whether it is information (in which case it must survive as text, as a label, or as structured content inside the new entry) or machinery (in which case it dies with the old system). The classic audit failure here is discovering, after the move, that a fact you relied on existed only as a property value in a form your new home silently dropped. Reading your properties now, while they are still attached to their pages, is the only reliable way to prevent it.

Finally, block references and embeds — the most delicate item in any Logseq audit. Search your pages for their traces and count the pages that depend on them. A block reference means content lives in one place and appears in another; in any destination without block references, each appearance must become either a link to the content’s new home or a copy of the content itself, and those are different decisions with different maintenance consequences. Elena’s approach was unsentimental: references that existed for genuine reuse — a standard client-background paragraph, a canonical definition — became single entries that other entries would link to with wiki links. References that existed merely because the outliner made cross-posting easy became copies, accepted as copies, in the pages that needed them. What she did not do was pretend the references would survive, or leave them to be discovered broken after the move. Your audit should end with a number: this many pages contain references, this many distinct blocks are referenced, these are the ones that matter. That number is the true size of the hardest part of your migration, and Part B will work from it directly.

The three piles: move, archive, leave behind

With the inventory complete, sort the entire graph into three piles. This sorting, not the copying, is the intellectual core of the migration.

The first pile is what deserves to move as living material: the pages you open weekly, the client and project work that is current or likely to be consulted, the reference notes you genuinely search, the writing you are proud of and the research you are paid to retain. This pile becomes real entries, restructured with care, links rebuilt, properties honoured. It will be smaller than you fear — for Elena, well under half the graph by page count, though it held nearly all of the graph’s value.

The second pile is what to archive as raw Markdown: complete, faithful, and deliberately unprocessed. Journals are the natural citizens here, along with finished projects, historical client work you must keep but rarely open, and anything whose value is completeness rather than use. Archiving as Markdown means exactly what it says — the original files, kept intact, in a folder structure you can search with ordinary tools forever — and some of it can also be brought into the vault as reference material without the expensive restructuring the first pile receives. The discipline is in not confusing the piles: archive material that gets full migration treatment burns the hours your living material needed.

The third pile is what to leave behind, and every honest audit finds one: duplicate captures, dead namespaces from abandoned projects, template debris, pages created by imports and never read, queries for jobs you no longer do, plugins’ scaffolding, and the archaeological layers of systems you tried for a fortnight in year two. Leaving behind does not mean deleting — nothing in this guide will tell you to delete your original graph — it means exempting material from the move, so that your new home starts life as a working tool instead of a perfect replica of your old one’s accumulated sediment. Elena’s third pile was the making of her migration’s morale: every page in it was an hour she did not have to spend, and the smaller, cleaner vault at the end was a place she wanted to open. Write your three piles down, with counts. Part B begins from them.

Backup and safety steps before touching anything

Everything so far has been thinking. This section is the last of the preparation, and it is non-negotiable: before any file is copied, converted, renamed, or restructured, your graph must exist, complete and verified, in more than one place — and the copy you migrate from must never be the only copy, or the copy you experiment on.

First, stop the moving parts. Close Logseq on every device. Pause whatever sync arrangement you use — official sync, a cloud drive, Git, Syncthing — so that nothing writes to the graph folder while you copy it, and so that a half-migrated state can never be faithfully propagated to your other machines. A backup taken while the folder is still changing can be internally inconsistent in exactly the ways you backed up to avoid. Elena did this on a Friday evening, deliberately: no client work pending, no phone capture she could not hold in her inbox for a weekend.

Second, copy the whole graph folder — not the pages alone. The complete folder means the Markdown and Org files, the assets folder with every attachment, and the graph’s own configuration and metadata, the unglamorous directories most people never open. Copy it as it stands, without tidying, renaming, or “fixing” anything first; a backup is a photograph, not an edit. Put this first copy on different physical media from the original: an external drive, not another folder on the same disk. Then make a second copy, by a different route if you can — Elena’s went to an encrypted archive on separate storage — because the failures that destroy a disk and the mistakes that delete a folder are different failures, and you want to survive both.

Third, verify the copies, because an unverified backup is a hope, not a backup. Compare file counts between original and copy, compare total sizes, and then do the test that actually proves something: open the copied graph — in Logseq pointed at the copy, or at minimum open a sample of pages in a plain editor, including recent journals, a page dense with properties, a page full of block references, and several assets of each type. If the copy opens and the attachments resolve, you have a backup. Record, in your migration document, where each copy lives and the date it was taken. If your graph has been under version control, commit and push everything as well; if it has not, this backup is your version control for the duration of the move.

Fourth, establish the working rule that governs everything in Part B: the original graph is read-only from this moment. All migration work happens on a separate working copy. Nothing is ever converted, restructured, or deleted in place. If an experiment ruins the working copy, you throw it away and copy fresh from the original, losing an hour instead of a history. Keep the original untouched even after the migration succeeds — Elena kept hers, archived exactly as it was on the Friday she stopped writing in it, as the permanent raw record behind everything in her new vault. VaultBook’s own protections belong to the destination side of that discipline: the vault is a single file you can copy as easily as the graph folder was, individual entries can be encrypted, and version history inside the vault guards against your own edits — but none of that substitutes for arriving with clean, verified copies in hand.

Finally, write down your rollback point in one sentence: “If the migration fails, I return to the untouched graph at this location, backed up on this date, and lose nothing but time.” If you cannot write that sentence truthfully, you are not ready to start. If you can — audit complete, three piles decided, backups verified, original sealed — then you are, and the next part of this guide picks up exactly here: opening the working copy, taking the first family of pages from Elena’s first pile, and beginning the hands-on work of turning a Logseq graph into a VaultBook vault, one deliberate step at a time.

Exporting and Preparing the Logseq Graph

The hands-on work starts before VaultBook is even open. It starts in the folder Elena Marsh already owns.

That is the advantage she is deliberately using while she still has it. Her graph is a file graph: plain Markdown files in a local folder, readable in any editor, copyable with any file tool, understandable without Logseq running at all. That portability is real, and it is exactly what makes migrating now the low-cost moment. If she waited until her working life lived inside the database version — graphs stored in a local SQLite database that require export before they can be used in Markdown editors at all — she would be starting from an export she did not control, not from files she already does.

So the first rule of this migration is simple: work from the original files wherever possible. Export only when you have no original files to work from. Never treat an export as your source of truth if the folder on your disk is still intact.

What a File Graph Actually Looks Like on Disk

Open your graph folder in your file manager, not in Logseq, and look at what is really there. A typical file graph has a small number of top-level folders that do distinct jobs, plus configuration tucked alongside them.

The pages/ folder holds most of what you think of as your notes: one Markdown file per page. A page called Client Research — Hartwell is a file in that folder. So is a reading note, a project page, a person page, and the sprawling reference page you have been adding to for three years. Namespaces complicate the filenames slightly — a namespaced page is still a file, but its name encodes the hierarchy — yet it is still one readable text file you can open, search, and copy without Logseq.

The journals/ folder holds your daily journals, one Markdown file per day, named by date. Those files are the spine of Elena’s four years: client calls, quick captures, tasks started and finished, links out to the pages where the real work happened. They look less structured than pages because they were written faster, under pressure, in the moment. Do not let that fool you into ranking them as less important. In most long-lived graphs the journals contain the only record of why a decision was made on a particular Tuesday.

The assets/ folder holds the attachments Logseq has collected on your behalf: PDFs you annotated, images you pasted, audio and screenshots and anything else that a block pointed at rather than contained. The Markdown files reference those assets; they do not contain them. Forget the assets folder and you will migrate thousands of pages that point, confidently, at files that are no longer there.

Around those three folders sits the rest of the graph machinery — configuration, Logseq’s own metadata, any custom CSS or plugin-related files you accumulated over the years. You do not need to migrate the machinery. You need to know it exists so you do not mistake it for content, and so you do not delete it before you are finished. Your custom queries, your plugin settings, and your theme tweaks belong to Logseq’s way of working. Some of their results matter a great deal and will be rebuilt later in this guide. The files themselves do not travel.

Elena’s inventory took less than an hour and changed her whole plan. Her pages/ folder held the bulk of her roughly 3,800 pages, her journals/ folder held four years of daily files, and her assets/ folder was larger than she expected — years of client PDFs, charts saved as images, and interview recordings attached inside Logseq. Counting files by folder, before moving a single one, told her this was not one migration but three smaller ones — pages, journals, and assets — with different risks in each. Do that count for your own graph: every later decision depends on knowing which pile is actually big for you.

Make Two Copies Before You Change Anything

Do not prepare your graph in place. Copy the entire graph folder twice: one working copy you will sort, rename, and pull apart, and one untouched archive copy you will not open for editing at all.

This is not paranoia. It is the difference between a migration you can pause and a migration you have to finish in a panic. Block references will be untangled by hand. Filenames will be cleaned up. Some pages will turn out to be duplicates, stubs, or accidents. All of that surgery belongs on the working copy. The archive copy is how you prove, weeks later, what a page said before you touched it — and VaultBook’s own version history will only protect you from the moment content enters the vault, not for anything you changed beforehand.

Elena kept her archive copy on a separate drive, zipped, with the date in the folder name. Her working copy sat next to her new vault while she migrated. Her live Logseq graph — the one Logseq itself was still opening — she left alone entirely until the very end. That three-way separation, live graph, working copy, archive, sounds fussy for about a day. Then you hit your first ambiguous page, go back to the archive, settle the question in two minutes, and never question the fuss again.

One more preparation step belongs here. Settle your sync state first. If you have used Logseq Sync or a third-party folder sync such as iCloud Drive, Dropbox, Git, or Syncthing, or edited on a phone as well as a computer, do not copy files until every device shows the same graph and no change is still in flight. The recurring community story is a stall that looks like success: a status that says everything is synced while recent edits have not landed. Migrating from a half-synced graph bakes that missing work into your new vault as a permanent absence. Confirm the last few days of journals match across devices, resolve any conflict copies, and only then take your two copies.

If You Are on the Database Version: Export First, and Know What the Export Loses

Everything above assumes you can walk up to a folder of Markdown files. If you have already moved to the database version, you cannot. Your graph lives in SQLite, and the first step of your migration is an export — and you need to go into that export clear-eyed about what it does not give you back.

Based on what database-version users consistently report, an export to Markdown does not round-trip the original graph. Files come out flattened into a single folder, so the folder structure you or Logseq maintained — the separation of pages, journals, and assets that makes a file graph legible — is lost or has to be reconstructed by inference from filenames and content. Assets are the sharper loss: the export centres on the text, and attached files are not reliably carried out with it, which leaves exported pages referencing PDFs and images that are not in the export at all. Mirror-style exports have also been reported to miss data on some pages without flagging which ones, and imports in the other direction — Markdown into the database version — have produced errors in bulk for some users, pages arriving as tags, and pages not arriving at all.

None of that makes export useless. It makes export a rescue operation rather than a tidy handover, and you should treat it accordingly, in three specific ways.

First, export, then audit the export against the database graph while you still have both. Count the exported files. Search the export for pages you know are important — your most-linked project pages, recent journals, a namespaced page, a page heavy with attachments, a page with properties, tasks, and a PDF — and open each one to confirm the content is complete, not truncated or reduced to a title. You are establishing whether the export’s failures, if any, are random or patterned: a patterned failure can be compensated for systematically, while a random one means spot-checking throughout the migration.

Second, compensate for the lost folder structure by rebuilding the three piles manually before migrating anything: journal files together by their date names, asset references together, ordinary pages together. This is tedious, and it is far easier in one pass at the beginning, with the database graph open beside you, than halfway through VaultBook. Elena’s file-graph route spared her this step entirely — the concrete, present-tense value of migrating while the Markdown files are still the originals.

Third, hunt your assets down separately. They may still exist in the database graph’s storage, in a backup, in the folder you synced before switching versions, or where you originally downloaded them. List every asset your exported pages reference, check which you actually have, and treat the missing ones as a named problem list: re-download the public ones, re-request the client ones while the relationship is live, and mark truly unrecoverable ones in the affected pages during migration, so a future reader knows the chart is gone and why, instead of meeting a silent gap.

Record the fairness point too: the database version has genuine defenders — properties and supertags are more structured there, and some users find navigation faster once a large graph is open. If that is your experience, your export may be cleaner than the worst reports. Audit it anyway; the method does not change with optimism, it just finishes faster.

Clean the Working Copy — Lightly, and Only Where It Pays

With copies made and, if needed, the export audited, you can tidy the working copy. The discipline here is restraint. You are not renovating the graph. You are removing the specific kinds of mess that multiply when multiplied by a migration.

Fix filenames that will fight you: leading or trailing spaces, characters your other tools mishandle, and duplicate names that differ only in case. Merge true duplicates — the same client page created twice under two spellings is common in a four-year graph — by combining their content into one file in the working copy and noting the merge in a scratch list, so that when both names appear as links elsewhere you know they now mean one place. Delete nothing else on suspicion. Empty stub pages, one-line pages, and pages that look like accidents often turn out to be link targets holding a namespace together or a dated note whose meaning lives in its backlinks. In VaultBook terms they will become very short entries, which is harmless. A stub you deleted that forty blocks pointed at is not harmless.

Finally, write yourself a one-page migration scratch sheet — outside the graph, in any plain document — with four running lists you will add to throughout: pages merged, assets missing, block references that matter (you will meet them properly in the hard-cases section below), and queries worth rebuilding. Elena’s scratch sheet started during this preparation phase with eleven merges and two missing assets, and it became the single most useful document in her migration. Every later verification check in this guide is, in the end, a check against lists that started here.

Translating Logseq Structures Into VaultBook Structures

VaultBook is not an outliner, and this guide will not pretend otherwise. There is no block-level structure to translate into, no graph view waiting on the other side, and no query language to re-express your queries in. What VaultBook offers instead is a different, simpler set of structures — entries, labels, wiki links, notes, a built-in calendar, Kanban, Due and Expiring tracking, full search with semantic question-answering, OCR and attachment indexing, and version history on everything — inside a single encrypted file with zero network requests. The translation work below is therefore not a format conversion. It is a series of small, explicit decisions: this Logseq thing becomes that VaultBook thing, for this reason, accepting this difference. Worked through Elena’s graph, structure by structure, those decisions look like this.

Pages Become Entries

A Logseq page becomes a VaultBook entry. The Markdown text of the page becomes the body of the entry, the page name becomes the entry title, and the whole thing is pasted or copied in from your working copy, page by page or in small batches of related pages you can keep in your head at once. This is the honest manual path, and it is worth stating plainly what it is not: VaultBook has an Obsidian import among its built-in tools, but there is no one-click Logseq importer, and nothing in this guide relies on one. The files being plain Markdown is what makes the manual path workable at all — you are never decoding a proprietary format, only re-homing readable text.

In practice the move takes three passes over each page. First, the text: copy the Markdown in, then read it once as prose rather than outline — a bullet that was really a heading becomes a heading, child bullets that were really a paragraph become a paragraph, a genuinely list-shaped block stays a list. You are not rewriting content; you are letting it take the shape it always meant. Second, the furniture: properties, task markers, and query blocks are pulled out rather than copied blindly, because each translates separately below. Third, the connections: links, tags, and asset references are rebuilt using the structures covered next, while the original page is still open beside the new entry.

Elena’s worked example is her Hartwell — Q3 Pricing Research page: six weeks of interview notes, competitor figures, and a running synthesis, built as nested blocks under dated headings. As an entry, the dated headings became real headings, the interview notes stayed as structured lists under the person they came from, and the synthesis bullets — which she had always read as prose while squinting past the bullet markers — became three proper paragraphs. Nothing of substance was added or removed. What changed was that anyone arriving at that material cold could read it top to bottom without first learning to parse her outline habits. The first page in a new category is slow; the tenth is routine.

Namespaces and Tags Become Labels

Logseq gives you two organising devices that overlap in practice: namespaces, where a page name like client/hartwell/research places the page in a hierarchy, and tags, where #research or a page-as-tag gathers pages across hierarchies. VaultBook’s corresponding device is the label, applied to entries, and the translation rule is to let labels do both jobs — flatly, explicitly, and without trying to recreate the hierarchy as folder theatre.

Take the namespace apart at its slashes. Each meaningful level becomes a label. client/hartwell/research yields the labels client, hartwell, and research — or, where a level is so broad it would label half the vault, a combined label such as client-hartwell carries the pairing without flooding the rest. Tags translate one-for-one: a Logseq tag that genuinely gathered things becomes the same word as a VaultBook label. A Logseq tag that was really a status, a date, or a leftover experiment becomes a candidate for the scratch sheet rather than an automatic label, because labels you never filter by are just noise wearing a uniform.

Elena’s example shows the judgment involved. Her graph used a research/ namespace for everything from client work to personal reading, plus tags for methods — interview, desk-research, data — plus a handful of tags she had invented for one project in 2023 and never used again. Her label scheme for the vault kept the method tags exactly as they were, because she genuinely searched by them. The namespace became two labels, research and the client or topic name, so an entry could be found by kind, by owner, or by both together. The one-project tags from 2023 did not become labels at all; the five entries involved got a line in their text noting the old grouping, and the grouping itself was allowed to retire. Her rule, worth borrowing, was a question: will I ever deliberately pull up everything with this marker, on its own? Yes means label. No means a mention in the text, or nothing.

[[Links]] Become Wiki Links, and Backlinks Become Related Notes

This is the most faithful translation in the whole migration, because the underlying idea does not change. A Logseq [[link]] points at a page by name. A VaultBook wiki link points at an entry by title. Where the page has become an entry with the same title, the link is rebuilt as a wiki link to that entry, and it works the way you expect: a named connection, in the text, that you can follow.

The work is therefore mostly sequencing. A link can only be rebuilt confidently once its target exists as an entry — one reason the phased order at the end of this part puts active projects, dense clusters of heavily interlinked pages, first: within a cluster, targets come into existence quickly and links can be finished as you go. For links pointing outside the current cluster, leave the link text visible and exact — the title, in brackets — and add it to a running link list on your scratch sheet. A visible placeholder you later resolve is good practice; a link silently deleted because its target was inconvenient is a small act of archival dishonesty you will not remember at 3,800 pages.

Backlinks deserve a separate word, because Logseq users lean on linked references heavily. VaultBook does not reproduce Logseq’s linked-references panel as such, but the need it served — what else points at this, and what is this connected to? — is met from two directions: full search, which finds every entry mentioning a title or phrase, including through OCR and indexed attachments, and related notes, which surface connections alongside an entry. Together they answer the practical questions: who cites this source, which projects touched this client, where else did this figure appear. What they do not give you is the automatic, exhaustive, block-precise panel — and the entries where that precision mattered are usually the ones carrying block references, treated in the next major section.

Elena’s example is a source she cited constantly: a single page for an industry pricing report that dozens of client pages linked to. In the vault it became an entry with its faithful title, migrated early despite belonging to no active project, precisely because so much pointed at it. Each client entry, as it was created, rebuilt its wiki link to the report entry on sight. When all the client clusters were done, she searched the vault for the report’s title and compared the result count against the linked-references count she had noted from Logseq before starting. The numbers matched. That comparison — backlink count noted beforehand, search count checked afterwards — is the cheapest strong verification in this entire guide, and it is worth doing for your five or ten most-linked pages, whoever you are.

Daily Journals Become Dated Entries Plus the Calendar

Journals are where Logseq users most fear the flow will not recreate, and the fear deserves a direct answer: the individual journal days translate perfectly well, and what needs rebuilding is not the days but the habit around them, which is Part C’s subject. For the structural translation here, each journal file becomes a dated entry — title carrying the date in a consistent format you choose once and never vary — holding that day’s text with the same three-pass treatment as any page: outline surfaced into readable structure, furniture pulled out for separate translation, links rebuilt as wiki links.

Consistency of the date format is not cosmetic. Dated entries plus VaultBook’s built-in calendar and its Recent view are how the journal becomes navigable: the calendar gives you the at-a-glance month shape Logseq’s journal scroll gave you, Recent gives you the just-written days in order, and search over dated titles gives you every journal mentioning a client, person, or decision. Pick a format both like — Elena used the ISO date followed by a short label from the day’s dominant subject, so a day spent mostly on one client reads as a date plus that client’s name — and apply it without exception, including to dull days. A journal system with exceptions is a filing system; without them, it is a timeline.

Elena’s worked example is an ordinary Thursday journal from mid-project: a client call summary, four task blocks in various states, a pasted paragraph from a report she wanted to chase, and a two-line note about an invoice. As a dated entry it kept the call summary at full length — with names, figures, and the decision, exactly as written — converted the invoice note into a tracked item under the next step’s rules, kept the pasted paragraph with a wiki link to the report entry it came from and a line saying why she had saved it, and sent its four tasks to Kanban. Read back, the entry was shorter than the journal file and contained more usable information, which turned out to be the pattern for journals generally: outline capture over-records process, and translation is where the record separates from the process noise.

TODO and Task Blocks Become Kanban — and Due/Expiring

Logseq tasks live as blocks marked TODO, DOING, DONE and their relatives, often with scheduled and deadline dates, scattered across journals and project pages exactly where the work was thought of. VaultBook’s living task structure is its Kanban, supported by the calendar and the Recent/Due/Expiring sidebar, which together do the job Logseq’s task views and queries did: show what is open, what is moving, and what is about to bite.

Translate by state, not by location. Every open task block — TODO, DOING, waiting, however you marked not-finished — becomes a Kanban card, titled with the task’s own text, placed in the column matching its state, and linked back to its source entry with a wiki link, so task and reasoning never lose each other. Its deadline or scheduled date becomes a due date Due/Expiring can surface — this matters more than the board itself, because a board you must remember to visit is a list, while an expiring item that presents itself is a system. Finished DONE blocks mostly do not become cards at all: they are history, preserved as text in the journal or project entry where they already sit. Migrating four years of completed tasks onto a board would recreate the one thing a board must never be: an archive you scroll past to see today’s work.

Elena’s example compresses neatly. Across her active Hartwell project she found task blocks on the project page and in eleven different journals: twenty-six open in some form, over a hundred completed. The twenty-six became twenty-one cards — five turned out, on reading, to be duplicates of each other written on stressed days, which the scratch sheet recorded — sorted across her board as to-do, in progress, and waiting-on-client, with the two hard deadlines set as due dates. The completed hundred stayed where they belonged, in the dated entries and the project entry, as the project’s memory. Her test of whether the translation had worked was brutally practical: on the first Monday after that phase, Due/Expiring showed her the Hartwell interim deadline without her opening the board, the board, or a single journal. In Logseq, surfacing that same fact had quietly depended on a query she had written two years earlier and half-remembered maintaining — which brings the translation to its most delicate item.

Properties Become Entry Fields and Labels

Logseq properties — the key-value pairs at the top of a page or attached to a block, client::, status::, source-type::, and their kin — carry real information in a mature graph, and they also carry a great deal of ritual. The translation sorts them into three fates.

Properties that classify become labels. client:: hartwell is a label wearing key-value clothing; source-type:: interview likewise — if you would ever filter by the value, it is a label. Properties that state a fact become part of the entry itself, as a short facts block in readable prose or a tidy list: an interview date, the full name behind an abbreviation, the fee agreed, the status in words. Inside the entry that fact is searchable plain text a human can read on opening, not metadata only a property-aware tool can see. Properties that were really task machinery — priorities, scheduling markers — go to Kanban with the tasks, or expire if the task is done. Properties that fail all three tests, added because a template added them and never once consulted, go on the scratch sheet as dropped. Dropping them is not data loss; it is scaffolding coming off a standing building.

Elena’s Hartwell page carried eight properties. Three became labels: the client, the project phase, and the research type. Three became a facts block at the top of the entry: engagement dates, agreed deliverable, and the primary contact — information she had previously been unable to see without Logseq’s property rendering, now simply the first thing the entry says. One, a priority marker, went to the Kanban card for the project’s main open task. One, a legacy field from a template she had abandoned in 2022, was dropped and recorded. Eight properties, four fates, no information unaccounted for: that accounting — every property either labelled, written in, carried to the board, or consciously dropped on the list — is the standard to hold for every page where properties carry weight. On the hundreds of pages where properties are trivial or absent, the same accounting takes seconds. Do not let the trivial majority talk you out of doing it properly for the weighty minority, because the weighty minority is, by definition, the graph you actually run your work from.

Handling the Hard Cases Honestly

Every migration guide has a section it would rather skip. This is that section, and it is the reason this guide insists on the word honestly in its approach. Three Logseq structures have no like-for-like home in VaultBook: block references and embeds, queries, and the pair of whiteboards and flashcards. Pretending otherwise would produce a vault that looks migrated and behaves broken. Handling them well means deciding, for each one, what the structure was actually doing for you — and then meeting that need differently, archiving it deliberately, or letting it go on the record.

Block References and Embeds: From Live Mirrors to Explicit Links and Copied Context

Block references are the most-cited loss when Logseq users describe leaving, and the reports are right: VaultBook has no block references, no block embeds, and no outliner structure for them to reference. A Logseq block reference did two things at once. It pointed — this thought belongs to that exact block over there — and it mirrored, displaying the block’s content in its new home and updating everywhere when the original changed. Nothing in VaultBook mirrors. What VaultBook can do, reliably, is the honest version of the pointing: an explicit wiki link, accompanied by enough copied context that the new location makes sense on its own.

Translate each reference you decide to keep in this form: the note in the new entry, restated so it stands alone; the key line or figure from the referenced block, copied in as a quotation or plain statement; and a wiki link to the entry now holding the original block, placed where the claim is used. An embed translates the same way at larger scale: copy the section in if the receiving entry genuinely needs to contain it, or replace it with a pointer paragraph summarising what it says and linking to it. What you lose is automatic updating — copied context does not follow later changes. What you gain is that every entry becomes self-sufficient: readable, searchable, and understandable without resolving a chain of references into an outliner that no longer exists. Version history covers change honestly: when a source entry is revised, search for the quoted line to find and update the entries that quoted it, as a conscious edit rather than silent propagation.

You cannot do this for every reference, and you should not try. A four-year graph contains thousands of block references, most of them working conveniences of the moment — a journal line pulled into a project page for a week, a block mirrored while a draft was forming — whose mirroring job ended long ago. So triage, with a rule simple enough to apply at speed: a reference matters if the receiving page would be wrong, misleading, or unintelligible without the referenced content. Apply three quick tests as you meet each one. Would a reader of this entry, alone, misunderstand something without it? Does it carry a figure, a decision, or a commitment that other work relies on? Is the original block the only place that content exists? Yes to any one means the reference is in the few that matter: rebuild it as link plus copied context, and note it on your scratch sheet. No to all three means the reference was scaffolding: let the receiving entry stand on its own text, keep the visible title of what was referenced as a plain mention where that helps, and move on without guilt.

Elena’s triage is instructive in its proportions. Sampling her active projects and a month of journals, she found block references everywhere — and fewer than one in ten passed any of the three tests. The ones that passed were concentrated and predictable: figures from source pages quoted in client syntheses, decisions from journals embedded in project pages, and a small set of definition blocks she had reused across her whole practice. Those she rebuilt carefully. The rest — the daily plumbing of an outliner at work — she let go in a single pass, and nothing she has produced since has missed them. Where she did feel the loss, she felt it honestly and specifically: a live-updating figure would have been convenient twice in the following month, and each time, copying the revised figure in by hand took minutes and left a version record of the change. Log that trade in your own mind the same way. Block references are a real loss with a workable replacement for the minority that mattered, not a reason the migration fails.

Queries: Rebuild the Few as Saved Searches and Label Views — and Drop the Rest on Purpose

A Logseq query is a small program: show me blocks or pages matching these properties, these tags, this date logic, this task state. VaultBook has no Datalog queries and no query language, and no saved-search trick in this section should be dressed up as an equivalent. What VaultBook does have is a combination that covers most of what queries were actually delivering day to day: full search — including semantic question-answering, so you can ask for material by meaning as well as by exact wording — plus labels that gather entries into views, plus the calendar, Recent, Due/Expiring, and Kanban for the date-and-state questions. Most working queries, read closely, were standing questions of a few recurring kinds, and each kind has a home in that combination.

A query that gathered everything about X — a client, a topic, a source — becomes a label view if X is worth a label under the earlier rule, or a saved search habit if it is not: search for the title or term, and let OCR and attachment indexing widen the net beyond anything the query could see, since the query never looked inside your PDFs. A query that asked what needs me — open tasks, deadlines approaching — is not rebuilt at all, because Kanban and Due/Expiring answer it structurally. A query that asked what did I capture recently about Y becomes Recent plus a search term. And a query whose answer you cannot describe in plain words without the query syntax — the intricate constructions long-term users accumulate, sometimes in the hundreds, then maintain like a second system on top of their notes — is almost always a candidate to drop: a standing question you cannot state plainly is usually one you stopped actually asking.

Sort your queries the way Elena sorted hers, on the scratch sheet, into three explicit lists before rebuilding any of them. Rebuild as label or search: standing questions you asked weekly or oftener and can state in a sentence. Answered structurally: the task, date, and recency questions the board, calendar, and sidebar now handle. Dropped, deliberately: everything else, named with a word about what it once did, so the decision is recorded. Her pattern matched what other users describe on auditing their own systems: a small core rebuilt, a solid band answered structurally, a long tail dropped without being missed. Include the counterweight: some users prize the query system itself and get precise, block-level answers no label view will match. If that is genuinely you this month — not historically you — those lost queries are a real cost to weigh in the migration decision itself. Rebuild queries only after the material they ranged over has migrated; a saved search tested against a half-full vault teaches the wrong lesson.

Whiteboards and Flashcards: No Equivalent — Archive, Export, or Let Go

Say it without decoration: VaultBook has no whiteboards and no flashcards. There is no spatial canvas to receive a Logseq whiteboard, and no spaced-repetition system to receive a flashcard deck. Any guide that implies a workaround equivalent is misleading you, so the decision here is an archival one, made board by board and deck by deck while Logseq can still show you what you are deciding about.

For each whiteboard, ask what it was for. A board that was a thinking session — a client problem mapped once, a structure sketched for an article — has usually done its work, and its conclusion lives in the pages it shaped: export it as an image, file that image as an attachment to its entry (viewable in the Photo/Video Explorer), and let the board retire. A board still used as a live reference deserves one step more: export the image, and also write its content out as structured text in its entry, headings and lists carrying the groupings the board carried spatially — an image preserves how it looked, text preserves what it said, searchable and linkable. A board that was pure process needs only a scratch-sheet line. For flashcards the logic is colder. A deck you were actively reviewing is a study practice, not a document, and practices do not migrate into a vault with no review system: either keep that practice in a dedicated tool outside the vault — a choice many make happily — or export the deck’s content into an entry as a question-and-answer record, accepting that you have archived the knowledge and ended the drilling. A deck you had stopped reviewing needs only the second half of that choice: its content as text if the knowledge matters, nothing if it does not.

Elena had six whiteboards and a reading-notes deck she had not opened in over a year. Two boards became image-plus-text entries (a market map she still consults, and the structure board for a long article series). Three became image-only attachments. One became a scratch-sheet line. The deck became a single question-and-answer entry under her reading labels — still useful as a reference, honestly no longer a deck. Total time: one focused afternoon. Total loss, stated plainly: the spatial feel of the live boards, and the drilling habit she had already, in truth, lost before she migrated.

Moving Assets: PDFs, Images, and Audio

Assets are the part of the graph your Markdown files only point at, and they are where VaultBook stops merely receiving your old material and starts doing things with it that Logseq never did. Move them deliberately, type by type, after the entries that reference them exist — so each asset lands in a home, not in a pile.

PDFs: Consolidate, Split, Compress — Then Let Indexing Work

Gather every PDF from your assets/ folder and from wherever the database-export hunt found the strays. For each one, the receiving entry is the page that annotated or cited it. VaultBook’s built-in PDF tools change the housekeeping around that move. Years of Logseq use leave characteristic clutter: the same report saved three times at three sizes, a 200-page document of which one chapter mattered, three annexes that are really one document. The merge, split, and compress tools fix that at the door rather than importing the clutter faithfully: merge the annexes, split the long file so the cited chapter stands as its own attachment, compress bloated scans so a single-file vault stays a sensible size. Do it per entry, as you reach it — which part of this PDF does this entry need? can only be answered with the entry open.

Then let the vault see inside them. VaultBook’s search covers OCR and attachment indexing, which means a PDF attached to an entry is not a dead file with a hopeful filename: its text becomes findable from the same search you use for entries, and the semantic question-answering can draw on it alongside your notes. For Elena, whose client work rested on long reports she had previously searched by re-opening them one by one inside Logseq’s annotation view, this quietly changed the value of her archive: a figure buried on page 140 of an attached report now surfaces from a vault-wide search, attached to the entry that explains why it matters. Her PDF annotations from Logseq need one honest sentence here: annotations made inside Logseq live in Logseq’s structures, not in the PDF file itself in any form you should rely on, so the substance of annotations that matter — the highlighted finding, in your words — belongs in the receiving entry’s text, written during migration while the annotated original is open beside you. The PDF travels. The thinking about the PDF travels as prose. Neither is left pointing at a tool you no longer open.

Images: Photo/Video Explorer and EXIF

Images move as files attached to their receiving entries, with one VaultBook tool doing the organising work Logseq’s asset folder never could: the Photo/Video Explorer, which browses your images and video visually and reads their EXIF data. That matters for a research graph more than it sounds. Screenshots, photographs of documents and whiteboards (including the exported boards from the previous section), charts saved as pictures, and photographs from site visits all arrive in most graphs as undated, unlabelled files with camera-generated names. In the Explorer, the EXIF dates and details give you a fighting chance of re-anchoring an image to the day and place it came from, and the visual browse lets you confirm at a glance which of three near-identical chart images is the final version an entry should hold. Inline players cover the video side the same way: a clip attached to an entry plays where it sits, rather than sending you to a folder.

Audio: Cutter, Joiner, and Local Transcription

Audio is where the migration most obviously adds capability. Interview recordings, meeting captures, and voice notes in an assets/ folder are, in Logseq, playable attachments and nothing more — unsearchable, unquotable without manual transcription, effectively invisible to the rest of the graph. In VaultBook each recording, attached to its entry, can be played inline, trimmed or combined with the built-in MP3 cutter and joiner — a two-part interview becomes one file, a long recording’s dead opening minutes come off — and transcribed locally with the built-in Whisper transcription, entirely on your machine, in keeping with a vault that makes zero network requests. The transcript goes into the entry (or an entry of its own, wiki-linked both ways), where it becomes what audio in a notes system always should have been: searchable, quotable, and citable text, with the recording retained behind it as the authority.

Be precise about the workflow, because it is manual like the rest of this migration: there is no automatic transcription of your whole assets folder. You choose the recordings that matter — for a researcher, the interviews and meetings where decisions were spoken rather than written — and transcribe those, entry by entry, as their phase arrives. Elena transcribed eleven of her forty-odd recordings in the first pass: every client interview for active projects, none of the ambient captures she had already fully written up in journals; those stayed as audio attachments alone, their content already in the vault as dated entries. That rule — transcribe what exists nowhere as text; merely attach what already does — kept the audio phase to days rather than weeks, and repaid itself the first time a search surfaced a client’s own phrasing from an interview she would otherwise have had to re-listen to at length.

Close the asset phase with the missing-assets list from your scratch sheet, revisited line by line: found and attached, replaced from its source, or marked as missing in its entry’s text. An asset migration is finished not when the folder is empty, but when every reference in every migrated entry either resolves to a file in the vault or carries an honest note explaining why it does not.

A Phased Order of Work — and How to Verify Each Phase

Nobody migrates 3,800 pages in a sitting, and the attempt to migrate them in folder order — page one to page three thousand eight hundred, journals whenever you reach them — is the single most reliable way to stall a migration at page four hundred with nothing usable on either side. Order the work by usefulness instead. The vault should be genuinely live for your most important work after the first phase, and merely incomplete after every phase that follows. Elena’s order, generalised, has four phases, and the journals — counter-intuitively, for a journal-centred tool — come last.

Phase one: active projects first. Migrate the pages, tasks, assets, and people of the work you are doing this month, as complete clusters: the project page becomes its entry, its namespaced children and linked sources follow, its open tasks become Kanban cards with due dates, its PDFs and recordings move and are indexed and transcribed as needed. Active work first means every translation rule in this guide gets tested immediately against material whose correctness you can judge — you know what the Hartwell synthesis should say — and it means the new vault starts earning its place in your day while the old graph still exists beside it. Verify phase one hard (the checks below), because every later phase repeats its patterns.

Phase two: standing reference. Your most-linked pages, your recurring sources, your person and organisation pages, your templates-turned-reference, your label scheme’s backbone. Much of this will already have arrived during phase one as link targets; phase two finishes it as entries in their own right and settles the labels across the whole core. Phase three: recent history. Journals and project material from roughly the last year — recent enough to be consulted, old enough to be history — with completed tasks left as text, assets attached, and the few block references that pass the triage rebuilt. Phase four: journals in bulk, and the deep archive. The remaining journals, oldest pages, and long tail, migrated faster and lighter: dated entries with faithful text and working wiki links, dropping-by-list the queries and references that fail the tests, accepting short entries for stub pages. Deep archive material earns speed rather than scrutiny because its realistic future is to be searched occasionally, not reread — and search works on faithful text however quickly it was moved.

After each phase, run the same five verification checks before starting the next. First, counts: pages expected in the phase against entries created, every difference explained by a merge or drop on the scratch sheet — no unexplained arithmetic, ever. Second, link integrity: search for placeholder markers and unresolved bracketed titles, resolve or consciously list every one, and repeat the most-linked-pages check — backlink count noted from Logseq against search-result count in the vault — for any hub the phase touched. Third, assets: open a sample of entries and follow every attachment, then search for a distinctive phrase from inside one attached PDF and one transcribed recording, proving OCR, indexing, and transcription actually landed. Fourth, systems: confirm the phase’s tasks are on the board with due dates, Due/Expiring and the calendar show what they should, and the phase’s rebuilt label views or saved searches behave against the real content now present. Fifth, spot-read for truth: pick three entries at random and one you know is delicate — a figure-heavy synthesis, a decision record — and read them fully against the archive copy, checking numbers, names, dates, and quotations character by character. A migration does not fail in bulk; it fails in one wrong figure nobody rechecked.

Lock each finished phase in the plainest way available: note its completion and its check results on the scratch sheet, and rely on VaultBook’s version history from here on for the content inside the vault, while the untouched archive copy of the graph remains the authority for everything before it. Elena ran four phases across three weeks of evenings, with her active client work fully live in the vault at the end of week one and her journals — the four-year spine of her Logseq life — arriving last, into a system whose labels, links, board, and search were already proven and waiting for them. The graph she feared losing became, phase by verified phase, a vault she could already trust before it was even complete. What remained was not moving at all, but living there: rebuilding the daily journal habit, the capture routines, and the working rhythms that a graph quietly provided — and doing it, this time, in structures she had chosen one by one.

Rebuilding the Daily Workflows in VaultBook

Moving the files is only half a migration. The other half — the half that decides whether you are still using the new system in March — is whether your mornings still work.

That fear is not hers alone. In thread after thread from people who have considered leaving Logseq — or have left and come back — the journal flow is named as one of the hardest things to recreate elsewhere. Not the file format. Not the links. The flow. The feeling that today has a page, that page is already waiting for you, and everything you type into it will be there when you come back on another device, or after lunch, or after a crash. Rebuilding that flow, honestly and without pretending VaultBook is an outliner, is where Part C begins.

The journal habit: dated entries, the calendar, and the Recent sidebar

Her rebuilt habit looks like this. Each morning she creates — or opens — an entry dated for today. The title carries the date and a short working label: the day, plus the client or project that will dominate it. That matters more than it sounds. In Logseq, the date alone was the title, and the content had to tell you what the day had been about. In VaultBook she can scan a week of entry titles in the sidebar and see the shape of the week at a glance: which days were client delivery days, which were reading days, which were admin. The entry itself is a document, not an outline. She writes the morning dump as ordinary paragraphs at the top, drops in follow-ups as a simple list underneath, and links out to the relevant client entries with wiki links as she goes.

The built-in calendar is how she navigates backward and forward. Instead of scrolling a journal stream or typing a date into a search box and hoping the page exists, she opens the calendar, picks the day, and sees what is attached to it. Reviewing last Tuesday’s decisions before a client call takes seconds. Planning next week means creating the dated entries in advance, with the questions she wants to answer on each day already waiting inside them. It is a small shift in mechanics — calendar first, rather than journal stream first — but the underlying promise is identical: every day has a place, and she can get to any day’s place without thinking about file paths or folder structure.

The Recent sidebar does the quiet work that Logseq’s journal stream used to do by accident. In Logseq, returning to the journal meant yesterday’s and today’s pages were always near the top of her awareness, and from there the linked references pulled the rest of the day into view. In VaultBook, Recent performs the same re-entry function. The client brief she had open at 6 p.m., the reading note she half-finished, the journal entry from this morning — they are listed in the order she last touched them. On a Monday morning, after a weekend away from the vault, Recent is how she rebuilds context in under a minute. She opens the last three or four items, skims them, and she knows where she left off. No re-indexing wait. No wondering whether the version on this machine is the version she last saw.

Capture without sync anxiety

This is where Elena’s relationship with Logseq had genuinely broken, and her experience matches a pattern described repeatedly by other users. Sync that stalls and never progresses, a status indicator that shows all is well while recent edits are in fact lost, a phone edit that vanishes behind a reassuring message, the suggested remedy of deleting a local graph and downloading it again — only for the stall to return. Other users describe older versions of the same wound: blocks duplicated or moved by sync, material entered offline wiped before a merge could protect it, third-party file sync causing constant re-indexing, duplicates, and broken links in search results. Mobile comes up again and again as the weak point — not the capture interface, but the reliability underneath it. People can tolerate a clumsy app. They cannot tolerate typing something important into an app and discovering later that the app kept the confidence and lost the words.

VaultBook removes the entire category of problem by removing sync from the capture path altogether. VaultBook is a single-file HTML app — roughly 1.5 MB — that makes zero network requests. There is no server to stall against, no account to sign into before you can write, no status icon whose job is to reassure you about a process happening somewhere else. You open the file, you type, the note is in the vault. The vault is the file, and the file is on the machine in front of you.

The trade-off is real and belongs in this section, not hidden at the end: VaultBook has no first-party cloud sync. Moving the vault between your own machines is your job — copy the single file by whatever method you already trust, the same way you would move any important document. For Elena that was a relief disguised as a chore. One file, copied deliberately, at moments she chooses, versus a graph folder syncing opaquely in the background. She knows exactly which copy is current because she put it there. Users whose paid Logseq Sync works well — and some report exactly that, and their experience counts — will feel this differently. If seamless multi-device sync is the heart of your workflow and yours genuinely works, weigh that carefully in the limits section below. But if sync is the part of your current setup you no longer trust, understand what you are trading toward: certainty about where your words are, in exchange for moving one file yourself.

Finding things: search, semantic Q&A, and related notes instead of graph browsing

For deliberate finding, VaultBook’s search is the workhorse, and it goes considerably further than matching titles. Search covers the full text of entries, and the vault also indexes attachments, so a fact buried in a PDF you filed months ago is findable from the same search box as your own prose. Optical character recognition means text inside scanned images and screenshots is searchable too — the photographed whiteboard, the scanned letter, the screenshot of a table a client sent as a picture rather than a document. For a research analyst, that last capability quietly changes what “file it and forget it” means. Elena’s graph had always had a shadow archive: images and PDFs attached to pages, present but effectively invisible to search, retrievable only if she remembered which page they hung from. In the vault, those attachments joined the searchable record. Material she had filed in her first year — and had mentally written off as lost unless she went digging — surfaced again in ordinary searches during her second week.

On top of full-text search sits the semantic Q&A. Instead of constructing the perfect keyword search, you ask the vault a question in ordinary language and it answers from your entries. This is the tool Elena reaches for when she remembers the substance of a note but none of its wording — the argument a source made, not the terms it used. Keyword search fails that job whenever your memory and your past phrasing disagree, which for any researcher is often. Asking the question directly, and getting an answer grounded in her own material, replaced a whole category of frustrated searching: the five-variant keyword spiral, the scrolling through near-miss results, the eventual resigned re-reading of a long page. It does not replace reading the source entry — she still opens the entry the answer rests on before she cites anything to a client — but it collapses the distance between “I know I wrote this down” and the page itself.

Exploratory finding is where honesty is required, because VaultBook has no graph view. There is no visual web of nodes to wander. What it offers instead is related notes: from any entry, the vault surfaces other entries connected in substance, so the sideways step — from this source to the project that used it, from this client note to the earlier engagement with the same problem — remains one click, just without the picture. Combined with labels, which let her pull every entry sharing a topic regardless of where it sits, and wiki links, which preserve the deliberate connections she built by hand, related notes covers most of what Elena actually used graph browsing for. Notice the qualifier, because it matters: most, and actual use. When she audited her own habits honestly, graph wandering was rarely how she found things that mattered. It was how she procrastinated pleasantly, and occasionally how she noticed a connection. Related notes delivers the noticing. Search and Q&A deliver the finding. The pleasant wandering is gone, and the limits section will say so without dressing it up.

Long-form writing without outliner friction

The outliner is a superb thinking tool and an awkward writing tool, and the tension between those two truths runs through years of discussion among Logseq writers. Blocks structure thought beautifully: atomic, rearrangeable, linkable. But prose is not blocks. Prose is paragraphs that flow, arguments that build across a page, drafts that need to be read as a reader will read them. Writers describe headings and block structure getting in the way of drafting, and the unglamorous labour of converting block-structured material into headed, flowing documents at scale — across hundreds or thousands of pages — before it can be used as writing. If your graph is primarily a thinking space, none of this bites. If, like Elena, your graph gradually became the place where client reports and articles were drafted as well as researched, it bites every working day.

In VaultBook, an entry is a document. She drafts a client report as a document from the first sentence: headings where the argument needs them, paragraphs that run as long as the thought requires, lists only where a list is genuinely the right form. There is no intermediate conversion step between “notes on the report” and “the report” — the research entries sit alongside the draft, linked by wiki links and labels, and the draft itself is written in the form it will be delivered in. Dynamic tabs support this more than their modest description suggests. Researching and writing at once means holding several entries open and moving between them constantly: the draft in one tab, two source notes in others, the client brief in a fourth. Tabs that persist and rearrange as she works turn the vault from a one-page-at-a-time notebook into a desk with papers spread across it — which is, not coincidentally, how she worked on paper for a decade before any of these apps existed.

The Reader is the second half of the writing workflow: the reading-back. Every writer knows the draft that looked fine in the editor and falls apart when read cold. Reader presents entries cleanly for exactly that cold read — and for the long reading sessions her research demands, working through filed sources and her own older notes without the visual clutter of editing. She reads a draft in Reader, notes the weak sections, switches back, and fixes them. It is a small loop, done many times a week, and each pass makes a deliverable better in a way a client can feel even if they never learn the tool’s name.

Deadlines: Due and Expiring instead of query maintenance

VaultBook’s answer is deliberately simpler: a Due and Expiring sidebar. Entries carry dates that matter — a delivery deadline, a contract renewal, a licence or document expiry, a follow-up promised for a specific day — and the sidebar surfaces what is due and what is expiring, in order, without her constructing or maintaining a single query. Her morning routine absorbed it in a day: journal entry first, then the Due list, then work. The client report due Thursday is there. The source whose access expires this month is there. The follow-up she promised a prospect is there, on the day she promised it, not discovered apologetically in an old journal page three weeks late.

The Security Upgrade: From a Folder of Plain Text to an Encrypted Vault

There is a sentence Elena had never quite said to herself during four years in Logseq, and the migration forced her to say it: her entire professional life — every client engagement, every piece of unpublished research, every candid note about a negotiation — sat in a folder of plain-text Markdown files that any program, any person, and any piece of malware with access to her machine could read in full, instantly, without asking anyone’s permission.

Per-entry encryption for the pages that needed it

VaultBook’s encryption is per-entry, using AES-256-GCM with PBKDF2 key derivation through the Web Crypto API, and the per-entry part is what makes it usable rather than merely impressive. Whole-vault encryption forces a choice between locking everything — and paying the unlocking friction on every grocery list and reading note — and locking nothing. Per-entry encryption lets her draw the line where the sensitivity actually is.

In practice, after migration, her vault has three tiers, though she never formally named them. The open tier is the bulk of the vault: reading notes, public research, drafts of published work, the daily journal’s ordinary business. These entries are unencrypted, instantly searchable, zero friction. The sensitive tier is client work: engagement notes, interview write-ups, anything containing a client’s unpublished figures, plans, or internal politics. These entries are encrypted individually. Opening one asks for the passphrase; the rest of the vault does not care. The small, highest tier is the handful of entries that are sensitive in a different way — personal financial notes, credential recovery information, the candid assessments she writes after difficult engagements — encrypted the same way, and few enough that she can list them from memory.

What changed is not theoretical. Before migration, a stolen laptop, a carelessly shared folder, a backup drive left in the wrong place, or a sync account compromise would have exposed client material in readable form to whoever picked it up. After migration, the same incident exposes her reading notes and leaves the client work as ciphertext. That is a materially different conversation to have with a client, and with herself. It is also, not incidentally, the first time her tooling matched the confidentiality language in her own contracts.

Two disciplines make encryption real rather than decorative. The first is the passphrase: long, unique, not reused anywhere, and stored outside the vault — hers lives in her password manager, and a sealed copy exists with her paper records, because an encrypted vault with a forgotten passphrase is not secure, it is simply gone. The second is scope honesty: encrypt the entries that need it at the moment you create or migrate them, as a habit, rather than planning a grand encryption weekend that never happens. Elena encrypted the client entries as she rebuilt them during migration, while her judgment about each one was fresh. Fifteen minutes of decisions, made once, entry by entry, at exactly the moment she was already reading each page with a critical eye.

Version history: the undo that spans weeks

Ask people who keep years of work in any notes system what their worst moment was, and a surprising number will describe the same shape of loss: not a crash, not a sync failure, but an edit. A page overwritten with the wrong version. A long note replaced by a fragment. A restructuring that deleted more than it meant to, discovered days later when the ordinary undo was long gone and the daily backup — if any — had already rotated past the good version.

VaultBook keeps a version history for entries, and in a migration context it earns its keep twice. The first time is during the migration itself. Restructuring 3,800 pages’ worth of material is editing at scale: entries split, merged, retitled, rebuilt. Mistakes are not a risk but a certainty, and the only question is whether a mistake is an inconvenience or a loss. With version history, Elena could restructure aggressively — combine the three overlapping source notes into one, rewrite the client summary entry from scratch — knowing the earlier state of any entry remained recoverable. That knowledge changed how she worked: faster, less timid, fewer precautionary duplicate entries cluttering the vault “just in case,” because “just in case” was a feature now, not a filing habit.

The password generator, and the small tools that close loops

A built-in password generator sounds like a minor convenience until you place it inside Elena’s actual work. Research analysts accumulate accounts the way travellers accumulate adapters: database trials, source platforms, client portals, survey tools, each demanding credentials, each a small security decision made under time pressure. The predictable failure — reusing a strong password, or inventing a weak new one — happens at exactly those moments. A generator inside the tool already open on her desk removes the friction at the moment of decision. New client portal, new generated password, straight into her password manager, vault never closed. Small tool, real loop closed.

The same logic runs through the rest of VaultBook’s built-in tools, and it is worth seeing them as a security-and-workflow surface rather than a feature list. The PDF tools — merge, split, compress — mean client documents are assembled inside the vault instead of being uploaded to a free online PDF service of unknown provenance, which is where an astonishing amount of confidential material is casually sent every working day. The local Whisper transcription means interview audio is transcribed on her machine rather than uploaded to a cloud transcription service: her interviewees’ voices and words never leave the building, which for recorded client conversations is not a preference but an obligation she had previously been meeting with a separate, awkward offline process. The MP3 cutter means she can excerpt the relevant ninety seconds of a long recording for her own notes without shipping the whole file anywhere. The File and Folder Analyzer lets her audit what is actually in a folder of material a client sends, before opening things at random. The Photo and Video Explorer, with EXIF data, keeps the when-and-where of visual evidence attached to the evidence. None of these individually justifies a migration. Together they describe a pattern: the jobs that used to push her most sensitive material out to a scattering of cloud utilities now happen inside one local file, and material that never leaves the machine cannot be breached on someone else’s.

What zero network requests means at 9 a.m. on a Tuesday

At 9 a.m., Elena opens her vault. Nothing signs in. Nothing checks a licence server, syncs a status, loads a remote configuration, or phones home with usage telemetry, because the app makes zero network requests — not “no requests except a few harmless ones,” but none. The file she opens is the whole system: a single HTML file of about 1.5 MB, containing the application itself and her data, running locally in her browser. If her internet connection died at 8:59, her 9 a.m. would proceed identically in every particular. There is no status page to check, no incident feed to wonder about, no moment of squinting at an icon to decide whether it is telling the truth about her notes being safe.

That is the security upgrade in one sentence: from confidentiality that depended on nobody bothering to look inside a folder of plain text, to confidentiality enforced by encryption on the entries that need it, history on the entries that change, and an architecture in which the most common way modern knowledge gets exposed — somebody else’s servers — has been designed out of her working life entirely.

When Someone Else’s Incident Takes Your Knowledge Offline: The GitBook Breach

This section exists because of something that happened this week, to a different company, to different customers — and because it illustrates, with uncomfortable precision, the risk that an offline vault is designed to remove.

GitBook, a widely used platform for documentation and knowledge bases, has published an official post mortem of a serious security incident. The post mortem is dated Wednesday, November 4, 2026, and it concerns an event on November 2, 2026. You can read it in full at the source: https://www.gitbook.com/status/security-incident-2026-11-03

According to GitBook’s own account, an attacker exploited a flaw in single sign-on to gain access to staff sessions, and from there — via a misconfigured GitHub App and a Cloudflare API key — obtained access to production infrastructure. The access came in two windows, one of roughly two hours and forty-five minutes and another of about forty minutes. GitBook’s response, again in its own telling, proceeded on a stark and responsible assumption: all customer data was treated as exposed. The categories named include API tokens, integration tokens and secrets, session signing secrets, questions asked of the GitBook Assistant, authenticated documentation, and content. GitBook took its own application offline deliberately as part of the response; the service was down from 20:32 UTC on November 2 until 11:56 UTC on November 3 — roughly sixteen hours. Every secret was rotated and all API tokens were invalidated, which means every customer using the API must create new tokens and rotate their integration secrets. The post mortem also records what was not compromised — billing information, passwords, and intellectual property in the sense the notice defines — and that the company found no evidence that other customers’ content was modified.

Read that summary again from the customer’s chair, because that is the chair Elena used to sit in — and the chair anyone sits in whose knowledge lives primarily inside a vendor’s cloud. Through no fault of their own, doing nothing unusual, GitBook’s customers woke to three simultaneous facts: material they had entrusted to the platform had to be assumed exposed; integrations they depended on had stopped working because every token had been invalidated at once; and for roughly sixteen hours, the knowledge base itself was simply unavailable — switched off, deliberately and correctly, by the vendor, as part of containing someone else’s attack. Each of those decisions by GitBook was defensible. The offline period probably prevented worse. That is exactly the point: when your knowledge lives in someone else’s infrastructure, even good decisions, made well, by a company acting responsibly, can expose your material and remove your access on a timeline you do not control, for reasons that have nothing to do with you.

Now place Elena’s vault against that shape of incident, concretely rather than rhetorically. Her vault is a single HTML file on her own machines. There is no VaultBook infrastructure holding her research, so there is no infrastructure breach that can treat her data as exposed. There are no API tokens for her vault — no tokens to invalidate, no integration secrets to rotate in a hurry on a Tuesday morning, no downstream automations silently broken by a mass revocation she learns about from a status page. There is no vendor who can take her knowledge offline to contain an incident, because there is no online for it to be taken from: the app makes zero network requests, and her access to her own work depends on her laptop and her passphrase and nothing else on earth. An attacker wanting her client material cannot reach it by compromising a documentation company, a sync provider, or a cloud region. They would have to compromise her, specifically, on her hardware — and there they meet per-entry AES-256-GCM encryption on everything sensitive, rather than a folder of plain text or a server’s worth of readable content.

None of this makes GitBook a villain of this guide, and the incident should not be inflated beyond what the post mortem says. Cloud knowledge platforms exist for good reasons: collaboration, publishing, integrations — real capabilities, which the limits section below discusses honestly. The lesson of this week is narrower and more useful. It is that “my notes are in the cloud” is not one decision but two: a decision about features, and a decision about whose incidents become your incidents. For a personal professional vault — one person’s research, clients, and working memory, needing no audience and no collaborators — the second decision deserves to be made deliberately. Elena made it when she migrated. The GitBook post mortem, published two days ago, is what the road not taken looks like when it has a bad week.

Honest Limits: What VaultBook Does Not Do, and Who Should Not Migrate

There is no graph view. If the visual graph is how you think — if you open it to plan, to spot clusters, to teach, to find your way — VaultBook offers nothing in its place. Related notes surface connections as a list, usefully and unglamorously. There is no map. For some users this is a footnote; for visual thinkers it is the whole product, and no amount of search quality compensates for a way of seeing that is simply absent.

There is no outliner, and there are no block references or block embeds. This is the deepest difference, and it is the loss migrants from Logseq cite most often when they describe what broke in previous moves to other tools. If your graph is woven together at block level — paragraphs referenced and reused across dozens of pages, transcluded into briefs and dashboards, forming a genuine block-level web — that web does not transfer. Not to VaultBook, and frankly not to anywhere else either; it has to be unwoven by hand, block references converted into ordinary links and rewritten passages, and some of the fine structure is simply lost in the conversion. Elena’s graph used block references lightly, which is why her migration was measured in days. A graph built on them heavily is a different project — weeks, with real losses to weigh. Count your reliance on block references before you count anything else. If the number is “my whole system,” this guide is not for you, and it says so plainly.

There are no Datalog queries. VaultBook’s Due and Expiring sidebar, labels, search, and semantic Q&A cover the everyday questions — what is due, what do I hold on this topic, what did I write about that argument. They do not cover arbitrary structured questions across custom properties, the kind advanced Logseq users build their dashboards and workflows from. If your practice runs on hand-built queries, you would be trading a programmable system for a fixed, simpler one. Some people experience that as relief. The people who built the queries rarely do.

There are no plugins. Logseq’s plugin ecosystem, themes, and custom scripts let users bend the tool toward their exact practice — and, as users themselves note, that power comes with maintenance: plugins to update, personal CSS to tend, extensions that break when the platform moves. VaultBook is a fixed, single-file application. What it does — entries, labels, wiki links, search and Q&A, OCR and attachment indexing, the calendar and sidebars, Kanban boards, Reader, data visualisation, the PDF and audio tools, Photo and Video Explorer, File and Folder Analyzer, password generator, version history, encryption — it does without extension, and what it does not do, you cannot add. The ceiling is lower. So is the upkeep: there is nothing to break on update, because the model is deliberately closed.

There is no real-time collaboration. VaultBook is a personal vault in the literal sense. You cannot invite a colleague into an entry, co-edit a page, comment in the margins, or publish from the vault to a team. Teams whose knowledge work is genuinely shared — a research group writing into one graph, a company documenting together — need a tool built for that, and this is not it. Elena’s case worked because her practice is solo: clients receive finished documents, not access to her process. If your process is the shared product, stay where sharing is native.

There is no first-party cloud sync. Covered earlier as a capture question, it belongs here too as a limit. If you move constantly between devices and your current sync genuinely works — and some users report exactly that with Logseq, paid or otherwise — VaultBook asks you to carry a file yourself, and that will feel like a step backwards every single day. A limit does not stop being a limit because it is also a design principle.

So who should not migrate? Graph thinkers. Block-reference architects. Query builders. Plugin extenders. Collaborating teams. Happy sync users. That is a large and honourable list — plausibly the majority of Logseq’s most devoted users, which tracks with the tone of the discussions among people who considered leaving: affectionate, reluctant, often deciding to stay on the build that works for them. And there are defenders of Logseq’s database direction whose experience deserves its due in any honest account: users who find the new version’s navigation fast, its supertags and properties genuinely better, their large graphs running fine. Performance in the file version is uneven rather than simply bad — some graphs of a few thousand pages strain, others of four to seven thousand pages run well, with complexity of namespaces, properties, queries, and images making the difference. If your graph is in the happy half of that distribution and your sync holds, your reasons to move are weak and your reasons to stay are strong.

Who should migrate, then? The profile is narrower and specific: a solo knowledge worker whose graph is primarily documents, notes, and journals rather than a block web; whose client or personal material has outgrown plain text; who has been bitten — or plausibly fears being bitten — by sync unreliability, opaque statuses, and edits lost behind reassuring messages; who is unsettled, as many are, by a roadmap that moves their portable files toward a database whose export back to Markdown loses folder structure and assets and does not cleanly round-trip; and who would rather have a smaller set of tools that are entirely theirs than a larger set maintained on someone else’s terms. If that paragraph describes you, read on. The next thirty days are the difference between a migration that sticks and a vault that becomes one more abandoned experiment.

The First 30 Days After Migration

Most migrations do not fail on the day of the move. They fail in week three, quietly, when the new system meets its first genuinely bad day — a deadline crunch, a lost note scare, a moment of friction at 11 p.m. — and the old system, still sitting there, looks like home. The thirty-day plan that follows is Elena’s, generalised. Its purpose is not productivity theatre. It is to carry the new vault across that third week with your trust intact, and to tell you exactly when the old graph can honourably retire.

Days 1 to 7: parallel running, with VaultBook in front

For the first week, run both systems — but with a strict rule about which one is real. VaultBook is where new work goes: today’s journal entry, today’s client notes, today’s captures. Logseq stays open only as a reference library, consulted when a piece of work needs material that has not migrated yet or that you are deliberately leaving behind. This asymmetry is the whole trick. Parallel running where both systems receive new notes is not a trial; it is a fork, and forks in personal knowledge are how people end up with two half-trusted archives and a permanent low-grade anxiety about which one holds the true version of anything. One writer, one reader. New ink only in the vault.

Expect friction this week, and pre-forgive it. You will reach for block operations that do not exist. You will type a query out of habit before remembering the sidebar exists. You will create an entry with a slightly wrong label and fix it on day four. None of this is signal about whether the migration was right; it is the ordinary cost of four years of muscle memory meeting a new desk. What is signal: whether capture feels safe, whether search finds what you ask for, whether the morning routine — journal, Recent, Due — completes without a workaround. Those three are the load-bearing walls. Elena’s week one verdict rested on them entirely.

Days 8 to 21: living in the vault, migrating on demand

Material will still be missing; plan for it rather than treating each gap as a failure. Elena’s rule was migration on demand: when real work reached for a page still stranded in the old graph, she migrated that page properly in that moment — restructured as an entry, labelled, links rebuilt as wiki links, encrypted if it carried client material — and logged it in a running “still in Logseq” list whenever she chose not to. The list mattered. It turned an unknown residue (“there is stuff back there, somewhere”) into a finite, visible queue that shrank every week. Most of it, she found, was never reached for at all, which is information in itself: a graph accumulates ceremonial pages, kept from tidiness rather than use, and a migration is the one honest audit of what your knowledge actually consists of.

Keep the counter-voices in mind during this phase, especially on the bad days. Some migrants go back. The discussions are full of leaving-and-returning, and returning is not failure — it is data that the thing you left was load-bearing for you in a way no guide could have known. If by day twenty-one you are reaching for the graph view daily, or your work has stalled twice on missing block references, read that data honestly. VaultBook keeps no hostage: your Markdown archive is intact, your old graph opens exactly as you left it, and the exit door is the same door you came in by. A migration you can reverse is a migration you can evaluate truthfully, because nobody — including you — has to pretend it worked to justify the cost.

Days 22 to 30: retiring the old graph — without deleting anything that matters

Retiring as a working system means three specific things. First, the “still in Logseq” list reaches zero or is consciously closed: every remaining item is either migrated, or formally written off as not worth migrating — written off in the log, by name, so the decision is a decision and not a drift. Second, daily life no longer routes through the old app: no reference lookups, no “just checking,” because each casual return reopens the question the thirty days were meant to settle. Third, the vault gets its first full backup discipline check: version history sampled on a few entries to confirm it holds what you expect, an external copy of the single file made and dated, the passphrase verified in its storage place. Trust, but only after verification.

Keeping the raw archive means something equally specific, and it is the easiest step in this entire guide to get wrong, so attend closely: do not tidy it. Do not restructure it, rename its folders, prune its duplicates, or “finish” it in any way. Export or copy the graph’s Markdown files exactly as they are — the same folder structure, the same assets, the same everything — into a clearly named archive location, and then leave it alone, forever, as the frozen record of four years of work in its original form. Its value is precisely that it is unedited: if a question arises in two years about what a note said before migration restructured it, the archive answers it. If you ever need to return to Logseq or move onward to another Markdown-based tool, the archive is the clean starting point, unmodified by either your enthusiasm or your regrets. Elena’s archive sits in a dated folder she has opened twice since creating it — both times to answer exactly that kind of question, in minutes. That is what a good archive is for: not nostalgia, but evidence.

Common Migration Questions — and Elena, Three Months On

How long does the move actually take? For a graph of Elena’s size — roughly 3,800 pages, light on block references, heavy on documents and reading notes — the honest answer is: a focused weekend for the core move, plus the thirty days described above for the migration to become true. The weekend covers the structured pass: exporting and copying the Markdown, restructuring the material that matters into entries, rebuilding the important links as wiki links, applying labels, and encrypting the client entries. Then migration on demand handles the long tail during real work, a few pages at a time, across the following weeks. Scale the estimate by your own graph’s shape, not its page count alone. A thousand pages built on block references and queries can take longer than four thousand pages of documents. And be suspicious of any estimate, including this one, that does not include the parallel-running month: the file move is an afternoon-to-weekend problem, but a migration is not finished when the files arrive. It is finished when the mornings work.

What breaks? Name it without flinching. Block references and embeds break — they become ordinary text and links, or get rewritten by hand. Queries break; their everyday jobs are picked up by search, labels, and the Due and Expiring sidebar, but the queries themselves do not transfer. Page properties do not carry across as a structured system; anything a property meant has to be re-expressed as a label, a date, or words in the entry. Journal flow changes shape, from an automatic stream to dated entries with a calendar and Recent. The graph view ends. Plugin behaviour ends. If any item on that list is a load-bearing part of your practice, reread the limits section before proceeding, because no technique in this guide restores those things, and pretending otherwise would waste your weekend and your goodwill. What does not break matters too: your text. Every word you wrote arrives, because Markdown is portable and VaultBook entries are built from it. The writing survives the move intact; it is the machinery around the writing that changes.

What about the database question — should I migrate before or after trying Logseq 2.0? This guide takes no position on the database version’s merits; some users report real gains from it, and their graphs and judgement are their own. The timing observation is narrower, and it is the one Elena acted on: migrating from the file-based version is migrating from plain Markdown files that any tool can read today, at a moment when that portability is at its maximum. The discussions among users are consistent on the mechanics of the other path — export from the database version back to Markdown loses folder structure and assets, and material reported missing in mirror modes means the round trip does not return you to where you started. If there is any chance you will one day want your graph as clean files again, the low-cost moment to secure that option is now, while the files are already files. Make the archive copy described above even if you decide to stay: an untouched Markdown snapshot, taken today, is cheap insurance under every future scenario, including the one where you happily use the database version for a decade and never need it.

Can I go back? Yes — cleanly, and by design. This is the property Elena insisted on before she began, and the property you should insist on too. Because the migration described in this guide never modifies the original graph, and because you keep the raw Markdown archive untouched, going back is not a rescue operation. Open Logseq, point it at the archived graph, and your four years are exactly where you left them. The entries you built in VaultBook during the trial are the only sunk cost, and even they are not hostage: the work you did in the vault during a month of real use is real work, readable and exportable as documents, whatever you decide about the tool. Going back after an honest trial, because the graph view or block references turned out to be load-bearing for you, is a successful experiment with a clear result — not a failed migration. The only genuinely bad outcome available here is the one the thirty-day discipline exists to prevent: never fully arriving in either system, forking your knowledge across two tools until neither can be trusted to hold the whole story.

Should I encrypt everything, to be safe? No. Encrypt the entries whose exposure would harm you or someone who trusted you: client material, credentials-adjacent notes, the personal records you would not read aloud. Leave the ordinary bulk of the vault open, so search, Q&A, and your own morning routine stay frictionless. Security that makes the tool unpleasant gets quietly switched off by tired people at busy moments, and a tired person at a busy moment is who all of this is ultimately for. Per-entry encryption exists precisely so that the line can be drawn sensibly — use it to draw the line where the risk actually lives.

Three months on

Elena’s vault, three months after the parallel week ended, is not a monument. It is a working file with a working person’s habits in it, which is a better outcome than a monument.

Her mornings are four actions long: today’s dated entry, the Recent sidebar to recover yesterday’s threads, the Due and Expiring list scanned over coffee, and then the first real task — which now sits in a tab alongside its source notes more often than not. The journal habit survived the move, altered in mechanics and intact in function. Capture has become boring, and boring is the highest praise she has for infrastructure: she types, it is there, the thought ends. She has not thought about sync in eleven weeks, except once — when a colleague described, with the particular weariness this guide’s readers may recognise, a morning lost to a stalled graph and a re-download — and felt the small, unglamorous relief of a problem that is no longer shaped like her life.

The client work is where the change has compounded. Two new engagements were set up encrypted from their first entries, as a matter of routine rather than resolve. An interview was transcribed locally the same afternoon it was recorded, and the excerpt she needed was cut from the audio without the recording ever leaving her machine. When a client asked, in the careful language clients use, how their material was stored, she had a short answer that was entirely true: in an encrypted vault, on her hardware, under no third party’s control, with version history and dated backups. The contract language and the reality matched for the first time in her practice, and she noticed that the client noticed.

That, in the end, is the whole argument of this guide, stripped of its thousands of words. Migrate if your graph has become a body of documents carrying more sensitivity than plain text should bear, on a platform whose direction and sync you no longer fully trust — and do it now, deliberately, while your Markdown files make the leaving easy and the archive makes it reversible. Stay if the graph, the blocks, and the queries are the thinking itself; no honest guide would take them from you. Either way, make the archive copy today. Futures are uncertain for every tool in this story. A folder of your own words, in files you can read, in a place you control, is the one hedge that pays out under all of them.