Loam is free and open source for macOS. Your notes stay plain Markdown files on your disk. Download for macOS.[Download for macOS.]
All pages

Get started

Your first vault

.md

Open a folder of Markdown notes as a vault, see what Loam writes into it, and find where its settings live.

This page shows how to open a folder as a vault, what Loam writes into it, and where its settings are stored. Any folder works as a vault: the app and the CLI open it the same way.

Open a folder as a vault

  1. Choose Open Vault… from the File menu (Shift+Cmd+O), or Open an Existing Vault… in the welcome window.
  2. Pick a folder of Markdown notes. To use a new folder, create it in the dialog.
  3. Click Open.

Loam reopens the last vault at the next launch. To open a given folder when Loam starts, quit Loam and run open -a Loam --args --vault ~/Notes. The folder must exist.

The very first time you launch Loam, it creates a vault for you in ~/Documents/Loam. A new, empty vault starts from a demo vault: a short tour of Loam written as notes.

What Loam creates

Loam keeps its own files in a hidden .loam/ folder at the root of the vault. The main file is .loam/config.json. Around it:

  • Your notes and folders, as plain files in the places you put them.
  • Deleted items, in .trash/. They stay there for 30 days by default, then they are removed for good.
  • Caches and build output, in .loam/cache/. Do not edit it by hand.
  • Attachments, such as images and PDFs, in the Attachments folder by default.

Contributors can build a different demo vault with make test-vault. It holds sample notes: Welcome.md, a Projects folder with a Projects.base collection, Areas/Health/Running.md, Maps/Trip ideas.md, and the daily note for today.

Where settings live

  • Plugin settings and keyboard shortcuts: .loam/config.json.
  • Themes: .loam/themes/. Pick one in Settings > Appearance.
  • Plugins you add: .loam/plugins/. Turn plugins on or off in Settings > Plugins.

Prefer the app, or loam plugins.set-setting, over editing config.json by hand.

Safe mode

Hold Option while Loam starts to open the vault in safe mode. Only the editor and the file explorer run. Loam also starts in safe mode when the last two launches on a vault did not finish starting.

For AI agents: loam --vault ~/Notes list lists every command. loam app info shows the vault open in the running app.