Core Concepts

The mental model in one sitting. If you understand these eight ideas, you understand MindWiki.

1. Your vault is plain markdown

Every page is a .md file with optional YAML frontmatter on top and [[wikilinks]] in the body. Nothing proprietary. The format is identical to what most modern markdown editors use, and it stays readable in any text editor on the planet. If MindWiki disappeared tomorrow, your folder of notes still works.

2. Two surfaces, one vault

The macOS app and the web app are two clients pointed at the same vault. Edits propagate both ways. You can capture on web, edit deeply on macOS, and ask your AI to read and update — all against the same files.

The macOS app is the richer editing surface (slash commands, knowledge graph, properties inspector, attachments, full keyboard navigation). The web app is the lighter capture and review surface, plus everything related to your account, connections, and API keys.

3. Capture is its own thing

capture/ is the only folder MindWiki creates for you. It is intentionally a single, frictionless inbox for raw input. Drop everything in there first — thoughts, links, voice memos, forwarded emails, AI conversations worth keeping. You sort, link, and refine later, when you have time. This separates the act of capturing from the act of organizing, so neither one slows the other down.

4. The structure is yours

Beyond capture/, MindWiki ships no preset folder structure. No projects/, no research/, no _templates/. You decide what folders mean and when to create them. Your vault should reflect how you actually think, not a template someone else designed.

When you do want suggestions, the recommended folders are documented in Vault Structure — but those are reference patterns, not requirements.

5. Wikilinks build the graph

Type [[page name]] anywhere in a page to link to another page. Every wikilink creates a backlink on the target — so you can always see what links to what. The full network is browsable as a knowledge graph in the macOS app.

You can also [[page name|display text]] to use a custom label. Wikilink autocomplete is built into both editors and the [[ slash command in the macOS app.

6. Properties are structured metadata

Every page can carry typed properties at the top, in YAML frontmatter. The macOS app exposes these as a Properties panel with checkbox, date, list, link, url, number, and text inputs. Use them to filter, sort, group, and find pages later — much faster than searching by content alone.

Canonical fields like title, area, type, created, updated, confidence, and tags are surfaced first. You can add any custom property you want. See Properties for the full reference.

7. Your AI connects through MCP

MindWiki speaks the Model Context Protocol — an open standard that lets AI assistants connect to external data and tools. One endpoint at https://api.mindwiki.io/mcp handles connections from Claude.ai, Claude Desktop, ChatGPT, Codex, Claude Code, and anything else that supports MCP.

Through MCP, your AI gains 20 tools: search, read pages, write pages, capture, ask questions, traverse the knowledge graph, find similar pages, list pages, run a vault health check, and create proposals for changes you can review before they happen.

For tools that do not yet speak MCP, you can also call the REST API directly with a personal API key.

8. The agents workspace shows what AI is doing

Every MCP tool call is recorded. The Agents workspace in the macOS app shows every connected AI client, every tool call (with status, duration, files touched), every pending proposal, plus vault health and the permissions matrix. You always see what your AI is doing and can revoke access at any time.

How these fit together

You capture into capture/. You edit in the web or macOS app, with wikilinks building graph structure as you write. You add properties to anything that needs faster recall. Your AI clients connect through MCP and read the same vault, with the agents workspace giving you full visibility and control. Everything syncs so you can move between devices freely.

That's the whole system.