AI agents that read and write your files

AI agents that read and write files skip the clipboard entirely: you point one at a folder, it opens the .md files inside, and it saves its changes back to disk. That works because Markdown is plain text an agent can edit in place, a few lines at a time, in changes small enough that you can actually read them afterward. So the interesting question is no longer whether a model can understand your notes. It is what you let it change, and how you check the result.

This post is about the write side: how agents reach your files, why plain text is what makes editing safe, and the review habits that keep it from going wrong. Moving text by hand still works, and plenty of days it is the right call, because you want to read an answer before it touches anything. How to clean up messy AI Markdown covers that path, and nothing below replaces it.

How do AI agents actually get to your files?

Three paths cover most setups, and it is worth knowing which one you are using, because they differ in where the permission lives and in how hard the boundary actually is.

Terminal and coding agents. You launch the agent inside a directory, and it works there: it lists files, reads them, and applies edits with read, write, and edit operations. Convention is doing most of the work in that sentence. If the agent can also run shell commands, nothing at the OS level stops it from reading elsewhere on the disk. What holds the line is the agent's own rules and the approval prompt it shows before it acts.

MCP filesystem servers. The Model Context Protocol is a standard way for an assistant to call tools that live on your machine. A filesystem server is one of the common ones: you configure it with a folder path, and the assistant gains a set of callable tools for that folder, typically list, read, and write. The assistant is still a chat window. The server is what actually touches disk.

Desktop assistants with OS folder access. Some assistants ask the operating system for access to a folder, the same way any other app does. On macOS that is the Files and Folders prompt, and the grant is recorded in System Settings, where you can revoke it later. Windows and Linux are looser: a sandboxed app, a Store package or a Flatpak, goes through something similar, but an ordinary desktop app already has whatever access your user account has, so the folder you picked is a setting inside the app rather than a boundary the OS enforces.

Access path	What it can see	What it can change	Where the permission lives
Terminal / coding agent	The directory you launched it in, and further if it has a shell	The same, file by file	The agent's own rules and approval prompts
MCP filesystem server	The folder path in the server's config	The same folder, only if write tools are enabled	A config file on your machine, which you edit
Desktop assistant, OS access	Folders you granted it	Usually whatever it can see	The OS dialog on macOS; an app setting elsewhere

In every case the scope starts from a directory you named, and none of these is "the model has your hard drive." But only the macOS grant is enforced by the operating system. The others rest on configuration and on the agent behaving as designed, which is a good argument for keeping sensitive material out of reach instead of trusting the boundary. Open the config, read the path, know what you handed over.

Why plain Markdown is what makes writing possible

Reading is a format question. Writing is an editing question, and they are not the same problem.

Reading is nearly solved for any text format. That side of the argument, why models parse Markdown so fluently and so cheaply, is already covered in why Markdown is the language of AI, so take it as given.

Writing is different. When an agent edits a plain text file, the operation is: find this exact string, replace it with that one. Three lines change. Every other byte in the file is untouched, because nothing else was addressed. The file that comes out is the file that went in, plus a small, locatable difference.

A .docx has no equivalent move. It is a zip archive of XML, so the bytes on disk do not contain your sentence in any form a search can find. An agent has to open the document through a library, change it in memory, and write the whole file back out. Even when the result reads correctly, you have no cheap way to see what else shifted. A proprietary note database is stricter still: the agent goes through an API, mutates a record, and the change is a state transition you can only inspect through the vendor's own UI, if they expose it at all.

So plain text is not merely convenient here. It is the only common substrate where a machine edit is both surgical and legible. Surgical, because the agent can change one section without rewriting the document. Legible, because the change is a text difference you can read in ten seconds:

 ## Open questions
-- How to handle mid-month plan changes (undecided).
+- Mid-month plan changes: prorate at the daily rate. Decided 2026-08-04.
+- Refunds on downgrade: still undecided.

That is the entire edit. You can see the decision that landed, the question that stayed open, and the fact that nothing else in the file moved.

Your folder layout is the interface

An agent approaches your notes differently than you do. You open the app and scan visually. An agent lists and globs first, so filenames are literally the first content it sees. Then it reads a handful of files it guessed were relevant.

Three consequences worth designing for:

• Name files like you would name a function. billing-schema-decision.md tells an agent what is inside before it opens anything. notes-2.md tells it to open the file and hope.
• A path is an address. If a context file references projects/orchard/spec.md and you rename the folder, the reference breaks exactly like a moved URL. Stable paths are worth more than tidy ones.
• One topic per file means one thing can change at a time. An agent asked to update a spec should touch a spec. If your spec, your meeting notes, and your grocery list share a file, every edit is a wide edit.

What goes inside those files, instructions, memory, knowledge, index, is a separate craft, and it is covered in context engineering with plain files. The new point here is only that the layout is no longer for you alone. It is the interface a second writer navigates.

How do you review what an agent wrote?

Before you point anything with write access at a folder, do this once:

cd ~/notes
git init
git add -A
git commit -m "floor"

That takes thirty seconds and gives you a known-good state. From then on, git diff is your review surface, and this is the shift that matters: you review the change, not the file. Reading a 900-word note to figure out what moved is hopeless. Reading six changed lines is trivial.

git diff                    # what the agent changed, not yet committed
git diff --stat             # which files it touched, and how much
git checkout -- notes/spec.md   # throw one file's changes away

What to look for:

In the diff	What it usually means
A few changed lines inside one section	The agent did the narrow job you asked for
The whole file rewritten, same meaning	Silent reformatting. Revert and ask again, more narrowly
Frontmatter or metadata changed	The most common unnoticed edit. Check dates and tags
A file you did not mention	It decided to be helpful. Decide whether you agree
Every line marked changed	Line endings or trailing whitespace normalized by a tool

File size decides whether this works. Ten focused notes produce diffs you can read. One 5,000-word catch-all produces a wall of red and green that you will skim, which is the same as not reviewing at all.

There is a second, lighter mechanism. An editor that reads files from disk, rather than importing them into its own database, notices when something else writes to the folder: the file list refreshes, and a note you have open flags that the copy on disk no longer matches the copy on screen, so you choose which one wins. That is not a substitute for the diff, and it will not tell you what changed. It just means you find out now rather than a week later.

What should an agent be allowed to touch?

Opinionated defaults, in rough order of how much trouble they save:

1. Scope to a working subfolder, not your whole vault. ~/notes/projects/orchard is a job. ~/notes is your life.
2. Prefer read-only until you have watched a few runs. Most useful agent work, summarizing, answering from your notes, drafting into the chat, needs no write access at all. Turn writing on when you have a reason.
3. Keep secrets out of the opened folder. API keys, credentials, client-confidential material, anything under NDA. A tool that can read the folder can read all of it, and some of it will end up in a context window that leaves your machine.
4. Do not open a sync folder to a writing agent if you can avoid it. This is the sharp one. If a folder is simultaneously an iCloud Drive, Dropbox, or OneDrive target and an agent's write target, neither side coordinates with the other. The sync client sees a file change under it while it is mid-upload, and you get conflicted copies: spec 2.md, spec (conflicted copy).md. It is not frequent, and it is not catastrophic with Git underneath, but it is real. Give the agent a local working folder and sync deliberately.

What are the honest limits?

• A wrong answer becomes a wrong file. An agent states a bad edit as confidently as a good one, and the only difference from a bad chat reply is that this one landed on disk. Your undo is version history, not Ctrl+Z.
• A paper trail only helps if you read it. Git history is not review. Nobody has ever been saved by a diff they scrolled past.
• There is no file locking. Two agents on one file is a race, and last write wins. Give parallel work separate output files.
• Long files still blow past a context window. An agent that cannot see the whole file may edit a section based on a partial view of the document.
• Voice does not survive rewriting. An agent can restructure a note into something technically fine and completely unlike anything you would have written. That is not a bug you can catch with a linter.

This is the point where AI orchestration with Markdown files stopped, on the line that the files do not run themselves and something has to execute the steps. The runner has arrived. The review discipline it assumed has not changed at all.

A setup you can run today

1. Pick one folder. A single project, not your whole notes directory.
2. Run git init and commit once. This is your floor.
3. Point the agent at that folder only. Check the path in the config rather than trusting the default.
4. Give it one narrow job. For example: Read meetings/2026-08-04.md. Update only the "Open questions" section of spec.md to reflect what was decided. Do not change any other section.
5. Read the diff before you keep anything. git diff, top to bottom.
6. Commit or revert. Both are one command, and both are fine outcomes.

Step 4 is the one people skip, and it is the one that decides whether this works. "Clean up my notes" is not a job, it is an invitation. A narrow instruction produces a small diff, and a small diff is a review you will actually do.

The short version

Markdown was already the format models read. What changed is that they write it too, straight to disk, with no clipboard in the middle. The property that makes that safe is not intelligence, it is plain text: an edit you can see, in a file you own, in a folder you scoped. Set the floor with one git init, ask for one small change at a time, and read the diff.

Where Apioni fits

Apioni is not a folder an agent can open. It is a web service: you sign in, your notes sync to your account across devices, and you write in Markdown, so the text itself still moves in and out of any model without conversion.

What it does with that text is the part an agent loop does not hand you. Each note is broken into atoms — the smallest pieces that carry one idea — with entities and tags pulled out of them and relations inferred between them. Search runs full text and meaning in a single query. AI chat answers from your own library, names the notes each claim came from, and declines when your notes do not support an answer.

The two approaches are not rivals. Point an agent at a folder when you want files changed. Use Apioni when you want the notes you already wrote to answer a question. Open Apioni, or see what each plan includes on the pricing page.