Skip to content

Your folder

On a computer with the desktop app, one normal folder holds your data: your entries as files you can open in any editor, your photos, and the database. You name it and choose its place on the first start (~/Kaizendex by default). Each collection is a folder, and each entry is one markdown file in it.

The Kaizendex folder: AGENTS.md, a read-only database copy, the hidden .kaizendex folder with the live database, Collections with one folder per collection (Notes and Dashboards among them) and one file per entry, Attachments by month, Settings, Chats, the inbox and the app’s own notes.~/Kaizendex/AGENTS.mdthe map for agents and peoplekaizendex.sqlitea read-only copy of the databaseCollections/one folder per collectionWorkouts/_collection.jsonproperties, views, the folder choice_schema.mdthe properties in plain wordsMorning run.mdone entry: one fileNotes/Health.mdRunning plan.mdits file says parent: [[Notes/Health]]Dashboards/one file per dashboard, with its tilesDiary/set to No AI, so its files are locked2026-10-08 77ab12cd.md.encencrypted; no title in the nameAttachments/2026-10/every photo and file, once, by monthSettings/sidebar, hubs, theme, designs, automationsChats/one file per chat_inbox/drop files here to import in bulk.kaizendex/hidden: the database, the app’s notes
Every entry lives in its collection’s folder, forever. Nesting notes only changes one line in the file.

Choose your folder

The first time the desktop app starts, it asks one thing: Where should your Kaizendex live? It works like Obsidian’s “Create local vault”.

  1. Folder name: Kaizendex by default.
  2. Location: your home folder by default. Browse… picks another place. The full path shows under them, for example C:\Users\Daniel\Kaizendex.
  3. Create makes the folder and its database, and the app opens in it.

One click on Create with the defaults is enough. The screen checks the place as you type, in one plain line:

The place What the screen says
A Kaizendex folder is already there “A Kaizendex folder is already here. Open this folder.” The button opens it.
A folder that is not empty “This folder is not empty. Pick another name or place.”
OneDrive, iCloud Drive, Dropbox, Google Drive or a network drive “This folder is on OneDrive, so your database stays on this computer.”
  • Open an existing folder… opens a Kaizendex folder you already have, for example after a restore.
  • Find my folder. If the folder the app knew is gone (moved, renamed, or on a drive that is not plugged in), the app says so and asks you to find it, or to start a new folder. It never opens an empty account in its place.
  • The choice is kept in ~/.kaizendex/location.json. The desktop app, kzx and the MCP server all read it.

The database in your folder

Your folder holds your entries as files, your photos, and the database. The database sits in the hidden .kaizendex folder: main.sqlite, locked.sqlite (locked items, encrypted) and vectors.sqlite (search by meaning).

  • Hidden only so it is not moved or changed by mistake. A name that starts with a dot is hidden by Windows and macOS.
  • Still yours, and still there. Any file app (turn on Show hidden items) or any SQLite tool can open it. Settings → Your data has Show in Explorer.
  • Do not edit it while Kaizendex is open. To change data from outside, edit your folder’s files or use kzx. For SQL, kaizendex.sqlite is a read-only copy.
  • On a cloud or network drive, the database stays on this computer, in the app’s data folder, because a live database that a cloud drive uploads while it is written can break. Settings → Your data says so, and where.
  • One folder is your whole account. Copy the folder with the app closed, then pick it with Open an existing folder…. Locked items open only where their key is: in this computer’s keychain. On a cloud drive the database is not in the folder, so move it with the app.

Moving the database or the whole folder is on Where your data lives.

What works today

The desktop app keeps the folder in step, both ways, from its first build. Some parts of the picture above come later.

Path What it is Today
AGENTS.md the map for agents and people yes
CLAUDE.md the name Claude Code reads; it imports AGENTS.md (one line, @AGENTS.md), so the two never differ yes
kaizendex.sqlite a read-only copy of the database, for SQL: one view per collection, and a links view yes
Collections/<Collection>/<Title>.md one file per entry yes
Collections/<Collection>/_collection.json the collection, its properties and views; you may edit it yes
Collections/<Collection>/_schema.md the properties, kinds and tag options in plain words; read only yes
Settings/<name>.json the sidebar, hubs, the theme and other settings yes
Chats/<Agent>/<date> <title>.md one file per chat written out only; edits are not read back
Attachments/ photos and files yes; a file a private entry holds is locked
.kaizendex/ hidden: the live database (main.sqlite, locked.sqlite, vectors.sqlite, sessions/) and the app’s own notes: manifest.json, problems.md, owner.lock, status.json, conflicts/ yes
_inbox/ bulk import: drop a CSV or markdown files in; imported files move to _inbox/imported/ yes
Collections/<Collection>/<date> <id>.md.enc a locked entry, encrypted; double-click it to open it in Kaizendex yes, written out only
Chats/<date> <id>.md.enc a locked chat (it names a locked entry or shows a locked photo), encrypted yes, written out only
Attachments/<month>/<id>.<ext>.enc a photo or file a locked entry holds, encrypted yes, written out only
  • You choose the folder on the first start. An account made before the first-start screen keeps its folder (~/Kaizendex-v2, because the old app’s kzx uses ~/Kaizendex). Settings → Your data moves it. KZ_FOLDER sets another place, for tests.
  • Private entries are locked. An entry or collection set to anything but Any AI, or Hidden, is written as <date> <id>.md.enc: the same text as its .md would hold, encrypted with the key in your keychain. Example: Collections/Diary/2026-10-08 77ab12cd.md.enc. No title in the name, no _collection.json or _schema.md beside it, and nothing in kaizendex.sqlite. The app writes these files; it does not read edits back. Delete one and it comes back; delete the entry in the app instead. On a computer without the key, they stay out. Double-click one and the desktop app opens at its entry.
  • AI, privacy and key settings stay out. These settings never reach Settings/: AI, privacy, security, the browser link and pairing, sharing, publishing, the account and keys.
  • One program syncs the folder at a time. .kaizendex/owner.lock says which. The desktop app wins over kzx.
  • The folder choice per collection (In the folder, Database only, Not in the folder) comes later. Today every Any AI collection is in the folder.

On a copy of a real account, the app wrote 5,436 files in 28 seconds, with no problems.

One entry, one file

“Morning run” in Workouts is the file Collections/Workouts/Morning run.md. Its values sit at the top (the frontmatter), and its Block page is the text below:

---
id: 0190f3a2-7c1e-7d4b-9a10-5b2e8f61c3d4
title: Morning run
date: 2026-10-11T07:00:00+03:00
parent: "[[Notes/Running plan]]"
icon: 🏃
Distance: 5.2
Felt: [Strong]
created: 2026-10-11T07:48:12+03:00
---
Easy pace along the river. Legs felt fresh.
  • Keep the id: line. It is how the app knows the file. A file with no id: becomes a new entry, and the app writes its id in.
  • Properties go by name: numbers, true or false, dates, tag names as a list, and links to other entries as "[[Collection/Title]]". created is written for you and never read back.
  • The file never moves when you nest or link entries. If “Morning run” sits inside the note “Running plan”, only its parent: line says so.
  • Mentions are [[links]] in the text: [[Notes/Running plan]], or [[Notes/Running plan|the plan]] when the mention shows other words. [[Notes]] links to the Notes collection. Type one in any editor and the app adds the mention. A link that names nothing stays plain text and is listed in problems.md.
  • Renaming an entry renames its file, and the app fixes every [[link]] that pointed to it.
  • Two entries with the same name in one folder get a short id in the file name: Ideas.md and Ideas 7f3a.md.
  • Several Block page and Dashboard fields stay in one file, with a marker line before each. With one Block page and no Dashboard, the text has no marker.

The exact shape of every file is on Folder format.

What each collection puts in the folder

Each collection has a folder choice, in its Share & privacy panel:

Folder choice What you see in the folder
In the folder (the default) One file per entry. Plain with the AI setting Any AI. Locked with any other AI setting, or Hidden.
Database only Only _collection.json and _schema.md. The entries are in the read-only database copy. Use it for huge numbers of tiny entries, such as heart-rate samples.
Not in the folder Nothing.

What is not in the folder

  • The backups, the photo store, AI models, paired browsers and app preferences. They are in the app data, ~/.kaizendex/app-data in your home folder, so deleting your folder does not delete your backups. Your folder’s photos are the same files as the store’s (hard links).
  • A second copy of your photos. The app keeps its own record of each photo in its data folder as a link to the same file, so a photo takes its space once. On a cloud drive or another disk a link cannot be made, so the app keeps a copy there.
  • Secrets. Sign-in tokens, API keys and the key for locked files stay in your computer’s keychain (its built-in password safe).
  • CSV tables. A spreadsheet copy would be a second place to edit the same value. For a spreadsheet, use Export as CSV once. For bulk edits, use the _inbox/ folder.

Which apps have a folder

App The folder
Desktop app (Windows, Mac, Linux) Yes, two-way. The folder belongs to the desktop app. With Read-only folder on, the app still writes it but ignores edits made in it.
A browser on the same computer The desktop app’s folder, through the link. A change made in the browser appears in the folder within seconds. The desktop app writes it, not the browser.
kzx (our command-line tool) on the same computer Yes, the same folder
A browser on a computer without the desktop app No folder, on any browser. Export and import a ZIP instead.
Phones (later) No folder. An optional read-only copy in the Files app, to read and share.

Want a folder? Install the desktop app. The folder has one writer, the desktop app, so two programs never change one file at the same time. Restore from my folder is in the desktop app too. See Backups, export and recovery.

There is no lock on the whole folder: it would shut out you, Obsidian and your AI agents. Disk encryption protects a stolen computer, and locked collections protect your sensitive data.

When the folder is in a cloud drive

A cloud drive changes files in its own ways. The app knows them, so you never lose an entry or get a double one:

  • A conflict copy is not a new entry. Sometimes a cloud drive makes a second copy of a file, such as Morning run (conflicted copy).md. The app knows the names that iCloud, OneDrive, Dropbox and Google Drive give these copies. Two files with the same entry id are a conflict on that one entry, never a second entry. The app keeps both versions for you to pick.
  • “Online only” is not a delete. A cloud drive can take a file off your disk to save space and leave only a placeholder. The app never reads that as a delete.
  • Cloud Sync wins. When the same change arrives through the cloud drive and through Cloud Sync, the app uses Cloud Sync and ignores the drive’s copy.

Git and This device only

Later, on the desktop app, Version this folder with Git saves your text files to a Git history. It never pushes the files of a This device only collection. Example: your Diary is This device only. Git pushes your Workouts files, and the Diary files stay on your computer.

Said plainly: your own Git history and your cloud drive are out of our reach. If you delete something for good, old copies can stay there.

A change to a privacy setting in _collection.json, such as Where or the AI choice, waits for your OK in the app. See Changes only you can make.