AI overview
Two ways an agent works a vault: directly on the files when it can reach your disk, and over MCP when it cannot.
Because notes are plain files, an AI does not need an integration to work with them. Baalda's job is to make the AI's edits merge with everyone else's rather than overwrite them, and to apply the same permissions to an agent that it applies to a person.
Two paths
| Local agent | MCP endpoint | |
|---|---|---|
| Examples | Claude Code, Codex, any CLI tool with disk access | A cloud assistant, a custom connector, an autonomous agent |
| Setup | None. Point it at the vault folder | Create a token, register the endpoint |
| How it edits | Writes the .md file. The watcher diffs it into operations | Calls tools that write through the same sync engine |
| What limits it | Your own filesystem permissions | The same per-folder access the token's owner has |
| Needs a server | No. It works on a local-only vault | Yes, and the vault must be synced |
Why an AI edit merges
Whichever path it takes, the change becomes operations on the same CRDT document a person is typing into. A rewrite of one paragraph while a teammate edits another converges, instead of one write winning. If the note is open you will watch the AI type in real time.
What an agent may reach
Over MCP, a token is scoped to one person in one vault, and every call is resolved against that person's effective permission. A folder that person cannot see does not appear in a listing, does not appear in search results and cannot be read, written or renamed. The same rules cover files, not only notes.
Writing safely
read_notereturns arevision. Passing it back asexpectedRevisionmakes the write fail if the note changed in between, rather than merging into something the agent has not read.edit_noteworks at exact anchors and refuses the whole call if an anchor is missing or matches more than once, so a partial edit is never written.append_notetakes an idempotency key, so a retried call cannot append the same text twice.- Every tool carries annotations saying whether it is read-only or destructive, which a client can show before it calls.
This page is written from README.md and docs/specs/00-architecture-overview.md in the repository. Those documents go further, and they are the ones that change first.
Read it on GitHubWas this page helpful?