Ask a coding agent to organize your notes and the first wall you hit is access. Can the agent read the notes at all? Can it write without corrupting anything, and will you see what it changed afterward? Most note apps fail at the first question: the notes sit in a database behind an account, inside an app that assumes a human is the only writer.
Acres starts from the opposite assumption. It is a local-first, infinite-canvas note app for macOS and Windows. Notes are Markdown files with YAML frontmatter; boards are readable, pretty-printed JSON; everything lives in a folder you pick. The files are the product — the app is a view over them. An agent can grep the vault with the app closed, and build in it — cards, labeled connections, tinted sections, mindmaps — through an MCP server that ships inside the app. There is no mobile, web, or Linux version. The app is a one-time $59 purchase after a 14-day trial: no account, no subscription, no feature gates.
What makes a note app agent-friendly?
Five properties decide it, and the comparison table further down scores all five. Agents need notes they can read, ideally as files rather than through API ceremony. The notes should be reachable with the app closed. There should be an official tool surface — MCP, a CLI, or both — rather than a stack of community workarounds. Concurrent edits must be safe: an agent writing while you type should never silently destroy either side. And you need review — a record of what the agent did, and a way to undo it.
The file system is the one API every agent already speaks. Half of agent support is refusing to invent a format; Markdown was here first.
How do AI agents read an Acres vault?
Cards live at cards/<slug>.md as Markdown with YAML frontmatter. Boards live at boards/<slug>.board.json in a documented schema (acres.board/7). Any editor opens them; any script can process them; grep has worked on Markdown since before agents could talk, and it works here too.
Raw board JSON, though, is a bag of IDs — so every Acres vault self-describes. A generated AGENTS.md is the front door. ai/graph.json is a resolved knowledge graph (version 3): cards, tags, properties, board arrows, wikilink references, section membership. ai/map.md is a relationship map a human or an agent can just read, and a CLAUDE.md is seeded so Claude Code orients on first contact. All of it regenerates automatically on every change, with byte-stable rebuilds. The agent’s first read is AGENTS.md, not a guess.
Agents can also full-text search the vault — a ranked engine (title above tag above body) reachable through the MCP search tool, the CLI, and the in-app AI panel. One honest note: the human-facing ⌘K palette matches titles and snippets only. Today, full-text search in Acres is agents-first.
What can an agent actually do in an Acres vault?
Read is the easy half. Acres gives agents the build half: the MCP server exposes 29 tools (7 read, 22 write) plus 3 resources, the CLI carries 30 commands, and the in-app agent has 18 tools — the same vocabulary on every surface. Agents create cards, wire labeled connections, frame tinted sections, grow mindmaps from indented outlines, place stickies and captions, and organize whole boards. A 28-scenario parity suite drives every mutation through both MCP and CLI against twin vaults and diffs the results, so the surfaces cannot drift apart quietly.
Board organization runs through Board Intelligence: the agent proposes a plan, you see an ASCII preview, you approve, and only then does it apply. The model handles semantics; a deterministic layout engine handles geometry. The layout-plan schema contains no x/y field anywhere, so an agent structurally cannot push pixels. Shared board-design rules (2–5 sections, meaningful tints, 3–7 cards per group, few labeled arrows, hero cards) are spliced verbatim into the in-app agent, the MCP server, and AGENTS.md, so every agent arranges a board the same considered way. Validation errors come back written for the model to self-correct from.
What happens when an agent edits while you’re typing?
The documented failure mode in file-based note apps is the silent clobber: an agent writes a file, the app writes it back a moment later, and one side simply loses. Acres assumes it is not the only writer. Every save re-reads the disk and performs a 3-way merge against the last-synced bytes: boards merge per entity across 11 arrays, card bodies merge via diff3 with your in-progress typing winning, and tags merge as sets. When a merge genuinely cannot keep both sides, the losing external copy is preserved as a .conflict sidecar file. No conflict markers are ever written into your notes, and nothing is silently lost.
It holds up outside the lab, too: an agent can rearrange a board from the CLI while that board is open on screen, and the change folds into the canvas around whatever you are dragging. No restart. Verified end-to-end.
How do you supervise what an agent did?
Every agent change in Acres comes with a receipt. The agent ledger — append-only JSONL, stored in the vault — attributes each mutation to its actor: claude-code, cursor, a named CLI run, or “Outside Acres.” Changes group into sessions and render as word-level diffs, with per-change one-click revert. The revert is guarded: it never force-reverts over newer edits, and deletes go to trash rather than being hard-unlinked. Come back after a day away and a digest tells you plainly: “claude-code and cursor made 7 changes.”
Destructive edits go further. Card rewrites, removals, and re-layouts arrive as proposals — diffs and previews you approve or decline — and applying one is drift-guarded: if the card changed underneath, the apply refuses with “stale” instead of clobbering. One agent run equals one undo step (⌘Z). Two limits, stated plainly: client attribution is self-reported, not cryptographically verified, and card renames and property changes are outside the ledger’s revert today. Agents do the work; you stay editor-in-chief.
How does agent access compare — Acres vs Obsidian vs Heptabase?
Acres is not the only note app that takes agents seriously, and this page won’t pretend otherwise. Obsidian stored notes as plain Markdown before agents existed, and its community directory lists 6,762 plugins as of August 2026. There is no first-party Obsidian MCP server, but the community has several — the Local REST API plugin now ships one built in, with standalone servers like MarkusPfundstein’s mcp-obsidian alongside — and Obsidian’s CEO Steph Ango published obsidian-skills, an official pack teaching agents Obsidian’s file formats that has drawn 46.8k stars. Heptabase went first-party: an official read-write MCP server shipped on December 10, 2025 with 9 tools, and an official CLI for Claude Code, Codex, and Cursor followed in April 2026.
| Agent access | Acres | Obsidian | Heptabase |
|---|---|---|---|
| How agents read notes | Markdown cards + JSON boards on disk, plus generated AGENTS.md, ai/graph.json, ai/map.md |
Markdown files on disk; official obsidian-skills teach agents the formats | Via the cloud MCP or the CLI — notes live in an internal database, not files |
| Works with the app closed? | Yes — plain files; agents read and edit the vault whether Acres is open or not | Yes for the files; the Local REST API server needs Obsidian running | Partly — the MCP is a cloud API; the CLI requires the desktop app running |
| Official MCP server? | Yes — bundled in the app, 29 tools + 3 resources, no Node install | No — community servers (Local REST API, mcp-obsidian) | Yes — remote, OAuth, 9 tools (Dec 2025) |
| Official agent CLI? | Yes — 30 commands; needs a source checkout today | No — the official skills pack and community tools stand in | Yes — since Apr 2026; desktop app must be running |
| Concurrent-edit safety | Live 3-way merge on every save; losing copy kept as a .conflict sidecar |
No merge model — lost-write races with the app open are documented | Writes go through the API, so no file races (and no direct file access) |
| Change review & audit | Ledger: per-client attribution, word-level diffs, guarded revert, away digest | None built in — File Recovery snapshots; version history with paid Sync | Diff review for in-app agent edits |
The table’s shape is the argument. Obsidian gives agents files but no safety net: the lost-write races between Claude Code and an open Obsidian vault are documented, community-workaround territory, and nothing in the app reviews what an agent changed. Heptabase gives agents an official API but no files: its own docs forbid reading the database directly, the CLI needs the app running, and the notes live in Heptabase’s cloud on a subscription that turns read-only when you stop paying. Acres is the only one of the three built around what happens after the agent writes — the merge, the ledger, the revert. For the full head-to-head on each, see Acres vs Obsidian Canvas and Acres vs Heptabase.
What does this look like in practice?
A week of reading leaves thirty unfiled cards in your Inbox. You tell Claude Code to organize the research board. It reads AGENTS.md, pulls the knowledge graph, full-text searches for the threads that connect the cards, and calls describe_board for an honest picture of what is already there. Then it proposes a layout plan: four tinted sections, three to seven cards each, one hero card, a few labeled arrows. You get an ASCII preview in the terminal. You approve. The deterministic engine places everything — the agent never chose a coordinate, because the plan schema has none to choose — and if the board is open, the new arrangement folds in live around your cursor.
Or the smaller version: paste an indented outline into a prompt, and the agent grows it into a mindmap that renders in the open board, branch by branch. (More on that workflow in AI mind mapping on a Mac.) Either way, the ledger records the run under the client’s name, the whole run is one ⌘Z, and tomorrow’s digest tells you what happened while you were away.
How do you connect Claude Code, Cursor, or Codex?
Settings ▸ Agents, one click. Acres writes the MCP configuration for five clients — Claude Code, Cursor, OpenCode, Codex, and Claude Desktop — merging into your existing config files rather than overwriting them (for Codex’s TOML it even preserves your comments). The MCP server is bundled inside Acres and launched through the Acres binary itself, so there is no Node.js to install and no separate server to babysit. The 30-command CLI is the one surface with a prerequisite: it runs from a source checkout, so DMG users connect through MCP.
Because the vault is a folder, multi-device is whatever you make it — the files move with git, a synced drive, or anything else that moves files; an optional end-to-end encrypted sync service exists.
What about AI inside the app itself?
The same agent layer is available without leaving Acres. ⌘J opens an AI panel with a read-only chat mode and an agent mode carrying 18 tools; responses stream, cite cards (click one and the board pans to it), and sessions persist across restarts. It is bring-your-own-key, with no subscription: use a key from any of seven providers — Anthropic, OpenAI, Google, OpenRouter, xAI, Mistral, DeepSeek — or run Ollama locally with no key at all. Keys live in the OS keychain, never in the vault, and requests go straight from the app to the provider.
Where Acres falls short today
Acres is desktop-only — no mobile, no web app, no Linux. There is no plugin system and no real-time collaboration. Mindmap nodes are annotations, not searchable cards. The ⌘K palette does not run full-text search (agents get that; humans wait). And the agent CLI needs a source checkout. If you need agents in your notes on a phone or on Linux today, Obsidian’s files-plus-community-servers route or Heptabase’s cloud MCP will serve you sooner. If your notes live on a Mac or a Windows PC and you want agents that build in them — safely, with receipts — that is the exact thing Acres was designed to be.