esc
Anthology / Yagnipedia / Logseq

Logseq

The Open-Source Roam That Almost Got It Right, Except the Files
Tool · First observed 2020 (the year everyone cloned Roam), though the ambition was older · Severity: So close (the most painful severity level)

Logseq is the open-source alternative to Roam Research that got almost everything right — the outliner, the bidirectional links, the daily notes, the block references, the community, the philosophy — and then stored it all in files that call themselves markdown but are markdown the way a platypus is a mammal: technically classified as such, but something clearly went sideways during development.

Logseq is the heartbreak of the PKM world. It is the tool you want to love. It is open source. It is free. It is local-first. It stores files on your filesystem. It has a community that contributes with genuine passion. It does everything Roam Research does without the $15/month, without the Datalog queries (well, actually — we’ll get to that), and without the performance problems of storing everything in a browser.

And then you open one of the files in another editor and discover that the markdown is not markdown.

The Promise

Logseq’s promise was irresistible: Roam, but open source, but local-first, but your files, but free.

Every word of that promise was sincere. Logseq is genuinely open source (MIT license, GitHub repo, community contributions). Logseq is genuinely local-first (files on your filesystem, no server required). Logseq is genuinely free (no subscription, no Believer tier, no tithe). Logseq genuinely stores files on your filesystem.

The files are the problem.

The File Format

Logseq’s files end in .md. They live in a folder. They look, from the outside, like the same files that Obsidian stores, that NotePlan stores, that any markdown editor can open. This is what the file explorer shows you. This is what ls shows you. This is a lie that the filesystem tells on Logseq’s behalf.

Open a Logseq file in another editor. What you see:

- This is a block
  - This is a nested block
  - DONE This is a completed task
    :LOGBOOK:
    CLOCK: [2026-03-10 Mon 14:30]--[2026-03-10 Mon 15:45]
    :END:
  - TODO This needs doing
    scheduled:: [[2026-03-14]]
    deadline:: [[2026-03-15]]
  - This block has properties
    type:: project
    status:: active
    priority:: high

This is not markdown. This is three languages in a trench coat pretending to be markdown.

The - bullets are markdown (outliner-flavored). The DONE and TODO keywords are from org-mode — the Emacs outliner that has existed since 2003 and whose community makes Roam Research’s cult look like casual acquaintances at a bus stop. The :LOGBOOK: and CLOCK: blocks are org-mode’s time-tracking syntax, transported wholesale from Emacs into a tool that is not Emacs. The property:: value pairs are Logseq’s own invention — not YAML frontmatter, not markdown metadata, but a custom format that only Logseq parses.

The result is a file that:

The Lizard picked up a Logseq file, held it to the light, turned it over, and set it down with the expression of a jeweler who has been handed a cubic zirconia labeled as diamond. It is a fine stone. It is not what the label says.

The Org-Mode Inheritance

Logseq’s debt to org-mode is deep, sincere, and confusing.

Org-mode is Emacs’s outliner/planner/spreadsheet/literate-programming/life-management system, created by Carsten Dominik in 2003. It is powerful in the way that Emacs is powerful: comprehensively, configurationally, and exclusively for people who have already committed several years of their life to the Emacs ecosystem. Org-mode users are productive. Org-mode users are also a self-selecting population of people who enjoy configuring text editors the way some people enjoy restoring vintage motorcycles — the process is the point.

Logseq borrowed org-mode’s task syntax (TODO, DONE, LATER, NOW), org-mode’s time tracking (:LOGBOOK: blocks), and org-mode’s general philosophy that an outliner should be able to do everything. This was a defensible choice — org-mode’s task management is excellent. But transplanting org-mode syntax into markdown files created a hybrid that belongs to neither world.

Org-mode users look at Logseq files and think: “close, but not org.”
Markdown users look at Logseq files and think: “close, but not markdown.”
Logseq users look at Logseq files and think: “these are my files and I can move them anywhere.”
Logseq users who try to move them discover: anywhere means Logseq.

The Datalog Returns

Logseq’s query language is Datalog.

Yes. The same Datalog. The same declarative logic programming language from the 1970s. The same query language that Roam Research chose and that approximately seven people on Earth can write fluently. Logseq, having watched Roam alienate 99% of its users with Datalog, having had the opportunity to choose literally any other query language, having the entire history of Roam’s Datalog mistake available as a cautionary tale — chose Datalog.

#+BEGIN_QUERY
{:title "Overdue tasks"
 :query [:find (pull ?b [*])
         :where
         [?b :block/marker ?m]
         [(contains? #{"TODO" "LATER"} ?m)]
         [?b :block/scheduled ?d]
         [(< ?d 20260311)]]
 }
#+END_QUERY

This is the query for overdue tasks. A person who has seen this before recognises the Datalog, recognises the org-mode #+BEGIN_QUERY block delimiters, and recognises the specific flavour of despair that comes from a tool choosing the same wrong answer as its predecessor.

The difference: Logseq has a simpler query syntax too — “simple queries” that are more accessible. But for anything beyond the basics, you are back in Datalog. The monastery in Tibet now accepts Logseq users alongside the Roam refugee. The monk nods. The WiFi is still absent.

The Database Version

Logseq eventually decided to solve the file format problem by eliminating files. The database version — replacing the markdown-org-Datalog hybrid with a proper SQLite database — was announced, anticipated, and entered the specific state of software development known as “coming soon.”

A person with a finely calibrated rabbit hole detector actually tested it. Approximately a year ago. It existed. It ran. The notes went into a database. The database schema was — and this is being generous — not the kind of schema that a person would design if they wanted another tool to read it. But it worked, in the way that beta software works: provisionally, hopefully, with the understanding that things would improve.

Then riclib went to the Logseq website to download it again. The download link gives the old version. The file-based version. The one with the three-languages-in-a-trench-coat files. The database version is not on the download page. It is not clear where the database version is. It is not clear whether the database version is still being developed, has been shelved, or has achieved the quantum state of software that exists in a GitHub branch but not in a shipping product.

This triggered riclib’s rabbit hole alert — the specific pattern recognition that fires when a tool’s most important feature is simultaneously “the future” and “not on the download page.” The rabbit hole alert has a 100% accuracy rate. When the download link for the current version gives you the previous version, the project is either in a transition so ambitious it cannot be landed, or in a transition so troubled it cannot be discussed. Both outcomes produce the same download page.

The community waits with the patience of people who have invested deeply in an open-source project and believe in the team. The patience is genuine. The timeline is unclear. The existing file-based version continues to work, continues to be useful, and continues to produce files that are not quite markdown.

riclib might have tolerated the database version. riclib might have even respected it — SQLite is, after all, what lg uses, and riclib has a documented fondness for tools that store notes in databases that other tools can query. But “might have tolerated” requires the tool to be downloadable, and “downloadable” requires the download link to give you the version you’re looking for, and the download link does not.

What Logseq Got Right

Almost everything.

The outliner is excellent. Thinking in blocks — where every line is a discrete unit that can be referenced, moved, and nested — is genuinely natural once you adjust to it. The daily note is well-implemented. The bidirectional links work. The block references work. The community is passionate and generous. The project is open source with genuine conviction, not open source as a marketing strategy.

Logseq is the tool that proved the Roam model works without Roam’s price, Roam’s performance problems, or Roam’s Believer tier. Logseq democratised networked thought. Logseq made the revolution available to everyone.

The files are not markdown. But the tool is genuine. The community is genuine. The mission — free, open, local-first, privacy-respecting knowledge management — is genuine. The execution is 90% of the way there, and the remaining 10% is the file format, which is either a detail that doesn’t matter (if you stay in Logseq) or the only thing that matters (if you try to leave).

“Logseq is a good tool that writes bad files. Obsidian is a bad experience that writes good files. The Lizard writes good files without a tool. The Lizard acknowledges that this comparison is unfair to everyone except the Lizard.”
— The Lizard, whose files have always been exactly what they claim to be

Measured Characteristics

See Also

See Also