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.
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”.
- Folder name:
Kaizendexby default. - Location: your home folder by default. Browse… picks another place. The full path
shows under them, for example
C:\Users\Daniel\Kaizendex. - 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,kzxand 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.sqliteis 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’skzxuses~/Kaizendex). Settings → Your data moves it.KZ_FOLDERsets 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.mdwould hold, encrypted with the key in your keychain. Example:Collections/Diary/2026-10-08 77ab12cd.md.enc. No title in the name, no_collection.jsonor_schema.mdbeside it, and nothing inkaizendex.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.locksays which. The desktop app wins overkzx. - 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-5b2e8f61c3d4title: Morning rundate: 2026-10-11T07:00:00+03:00parent: "[[Notes/Running plan]]"icon: 🏃Distance: 5.2Felt: [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 noid:becomes a new entry, and the app writes its id in. - Properties go by name: numbers,
trueorfalse, dates, tag names as a list, and links to other entries as"[[Collection/Title]]".createdis 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 inproblems.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.mdandIdeas 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-datain 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.