I wanted a mind-mapping tool that an AI agent could read and write the same way a human could. That was the design constraint, and everything else fell out of it.

So the file format is a folder. A manifest the app reads, a text outline an LLM can scan, and one markdown file per node where the substance lives. There is no MCP server, no custom protocol, no SDK. The agent writes to the files, the desktop app watches the directory, and the canvas updates. It's a small piece of work, but the idea behind it (the filesystem as the universal IPC between humans and agents) is the part that travels.

What it is

A FigJam-inspired mind-mapping app, public at github.com/and-human24/monkey-map. TypeScript and Rust, React on the canvas, Tauri for the desktop shell. The same compiled React bundle runs in two places: a CLI-launched local server you start from any repo, and a native desktop app with multi-tab projects and OS file dialogs.

The interesting surface, though, is the third one: a Claude Code skill that lets an agent generate, read, and edit maps using nothing but files on disk.

Why mind-mapping counts as memory infrastructure

Most agent memory today is either opaque (a vector store you query and pray) or implicit (whatever fit in the context window). A graph of nodes and edges is what memory looks like when you want it explainable. Make it visible on a canvas, editable in any text editor, addressable by an agent through a folder convention, and the question "what role does this play" stops being the diagram-tool question and starts being the memory question.

That reframing is what the format is for.

The v1 to v2 migration

v1 was a single JSON file. Nodes, edges, viewport, and per-node markdown details all in one document. It worked fine for the renderer. It was terrible for everything else. An agent had to load and parse the whole thing to find anything. So did a human grepping a repo.

v2 is a folder. The manifest holds only what the app needs to render: positions, edges, labels, metadata. Each node with substantial content gets its own markdown file in a nodes/ subdirectory. Next to the manifest sits map.md, an auto-generated text outline of the graph. The outline encodes hierarchy and lateral association as different glyphs, and tags every node with its short ID, so an agent reading it can navigate the graph as plain text and then open exactly the one or two node files it actually cares about.

This is the part I'd point to first if someone asked what was novel about the project. It's a structural index over content. The agent walks the tree in linear tokens, then drills down on demand. Selective retrieval, no embeddings, no similarity search. The whole graph is loadable but you almost never need to.

The split happens in Rust. Writing the folder pops the markdown out of each node into separate files, garbage-collects orphans, and regenerates the outline. Reading reverses it. Round-trip tests cover both sides, because the format is the contract. (On safety: node IDs reject path-shaped characters and the whole tree is constrained to the user's home directory. Standard hygiene.)

The Claude Code skill

The skill is one file. A frontmatter block declares its name, when to use it, and that the user can invoke it directly. The body is prompt scaffolding, the content that teaches a Claude agent how to think about mind-mapping as a task.

A few of the rules that earn their place:

• Nodes are short labels, three to six words. All substance goes in the node markdown files. The skeleton is cheap to render and the content is cheap to read on demand. This is the cardinal rule because LLMs default to stuffing paragraphs into labels.
• No hub-and-spoke for pipelines. Steps chain step then step then step. The skill explicitly warns against the "connect everything back to a central hub" pattern that LLMs reach for first.
• A fixed semantic color palette: green for done, red for failed, yellow for partial, indigo for structural, purple for conceptual. Hex codes match the canvas constants exactly so the agent's output and the app's rendering agree without translation.
• When reading an existing map, start with the text outline, find the IDs you need, then open the specific node files. Never parse the manifest. That's for the app.

Install with one copy command. Then /mind-map Audit this codebase and visualize the findings produces a real openable canvas, not a Mermaid blob in chat. Real artifact, not chat ephemera.

Filesystem-as-IPC

This is the argument I keep coming back to. The LLM already knows how to read and write files. That is its base capability, the thing every agent harness exposes first. A folder convention both sides understand has zero protocol surface to debug, zero versioning headache, zero auth model to implement. The format is inspectable with cat, diffable with git, editable in vim. Any tool that touches files can participate.

There is no MCP server here. No custom transport, no handshake, no SDK. The agent writes files. The desktop app's file watcher picks up the change, debounces a moment, reassembles the folder, and re-renders. The reverse works too: drag a node in the canvas, and the agent reads the updated outline on its next turn. (The one subtle bit is making sure the app's own writes don't echo back through the watcher and trigger an infinite loop. A small counter solves it.)

So you can sit in the app with a map open, prompt the agent to "add a node for the auth service," and watch the canvas update as the writes land. That live loop is the demo. The format is what makes it possible.

What I'd do differently

Honest gaps. Not published to npm yet, which is a ten-minute follow-up I keep not doing. No code-signed macOS bundle, so first launch hits a Gatekeeper warning. No hosted demo URL. The stateless in-memory mode for a public demo would be straightforward (the frontend already tolerates it) but I haven't shipped it.

None of these block what the project demonstrates. If I rebuilt it tomorrow I'd start with the folder format on day one instead of arriving at it through a v1 detour. The single-JSON version taught me what was wrong with it, but I could have read the lesson off any agent-memory paper from the last two years. Sometimes you just have to build the obvious bad version first.