A developer's notes app has no database, just a folder of Markdown

Mohak Bajaj shipped Jot, a small Mac app for capture and dictation that saves a note when someone selects text anywhere and taps Shift twice. He considered SQLite, a sync server, and an account system, and he shipped none of them, leaving all of Jot's storage in the folder ~/Documents/Jot. sayjot.xyz's report, dated 2026-11-09, describes that folder, and the app is free for 3 days, then $9 once at the launch price on sayjot.xyz.

This piece covers how that folder works, what broke, and why AI agents turned out to be the best reason for it. It is for Mac users who capture text and dictation, and for people who hand the same vault to Claude Code, Codex, or Cursor. The storage layer is about 600 lines of TypeScript that read and write ~/Documents/Jot.

01One note is one file

Every note is one Markdown file with YAML front matter, named YYYY-MM-DD-<id>.md. The id is six random characters from [0-9a-z], and the date at the front makes ls sort by day for free. The folder holds 2026-11-09-6tjhzv.md, 2026-11-09-gnump0.md, INDEX.md, SKILL.md, attachments/6tjhzv/, and .trash/.

The sample file for id 6tjhzv sets archived to false, done to false, and pin to false, with section left as an empty string and images as an empty list. Source is Safari, the url field is https://example.com/article, and the tags list contains reading. Created and updated are both 2026-11-09T09:12:04.511Z, and the body is the line "A line I selected and wanted to keep."

If a file loses its created field, Jot falls back to the date in the filename, so the order stays stable. Images and audio go in attachments/<id>/, which puts this note's media in attachments/6tjhzv/. A deleted note moves to .trash/<id>/, and undo is a rename of that path back into the vault.

02Half-written files and outside edits

If the app crashes in the middle of a write, the note is gone, which is one problem a database would have solved. Every write now goes to a temp file next to the real one (.name.<16 hex>.tmp), and a rename puts it in place. A rename is atomic on one filesystem, and the rename lives in the folder entry, so Jot also syncs the folder, or a power cut can undo it.

When Jot opens the vault, it deletes temp files left by a crash. Each operation lists the folder again, and parsing hundreds of files with YAML on each keypress is slow, so Jot keeps a cache keyed by inode, mtime, and size. An atomic write gives the file a new inode, so any change misses the cache, and a file that did not change is not parsed again.

The files can be edited in Vim, Obsidian, or a script. If the front matter stops parsing, Jot leaves that one file out of the list, logs why once, and keeps going. It does not crash and it does not fix the file, and if another program adds or edits a file, the folder watcher updates the inbox by itself.

03Stdio server and seven tools

Bajaj added a CLI first, with jot list, jot search, jot add, jot tag, jot done, and jot archive. The jot mcp command then starts an MCP server on stdio, so Claude Code, Codex, and Cursor can use the same ~/Documents/Jot vault.

The MCP server has seven tools: list_jots lists by status, section, or tag, newest first, and search_jots does a case-insensitive match on body, tags, source app, and URL. read_jot returns the whole file plus absolute paths to its images, and add_jot creates a note whose first line is the title. tag_jot adds tags while existing tags stay, set_done marks a note done or opens it again, and archive_jot hides it from the inbox while the file stays.

There is no delete tool, on purpose: an agent can add, tag, finish, and archive, and it cannot remove anything, so the worst it can do is leave a mess visible in Finder. The server reads the files, changes the front matter, and writes them back with the same atomic write. The app sees the change through the folder watcher, with no IPC between the server and the app, and the app does not need to be running.

04INDEX.md and SKILL.md for agents

Two generated files are for agents even without the MCP server. INDEX.md lists every note as a Markdown link with its title, so an agent reads one file and knows what is there. SKILL.md describes the layout: where files live, what the front matter means, and how ids look, so any agent that can read a folder can use the vault correctly.

The setup for most agents is just this: "my notes are in ~/Documents/Jot, read SKILL.md." Something like "what was I thinking about last week" becomes a grep and a read. That grep and read still work when jot mcp is not running.

05Sync, search, and schema limits

Jot does not sync. Putting the folder in iCloud Drive or Syncthing is the substitute, and conflict handling for two Macs that write at the same time is not built. Fast queries over large vaults are not built either: search is a substring scan over parsed files, which he calls fine for thousands of notes, and for hundreds of thousands he would add an index.

Schema migrations are the third limit. The front matter is now an on-disk format that other tools read, so he can only add fields, not rename them. For a capture inbox, he treats those trades as worth it: notes outlive the app, every tool the user already uses can open them, and ls ~/Documents/Jot is the admin panel.