Agents Overview

The Agents workspace is where you see and control AI activity in your vault. It's the panel that answers three questions at any moment: which AI clients are connected, what have they done, and what are they asking permission to do.

The Agents workspace lives in the macOS app. Connection management (OAuth, API keys, scopes) happens in the web app at mindwiki.io/account/connections and mindwiki.io/account/api-keys.

What "agents" means here

In MindWiki, "agent" covers two distinct things:

  • Interactive AI clients — Claude.ai, Claude Desktop, Claude Code, ChatGPT, Codex, Cursor, or any custom MCP-aware tool — connected through MCP. They read your vault, search it, ask questions about it, and (with write scope) add to it or propose changes during your conversations with them.
  • MindWiki Pro automation — scheduled jobs that run inside the MindWiki backend on Pro accounts only. They use MindWiki-owned AI, not your Claude or ChatGPT subscription. The four jobs are Auto-Linker, Weekly Classifier, Pattern Detection, and Monthly Summary. Each one is proposal-first: the automation creates entries in the Proposals view that you review before any change lands. The single exception is Monthly Summary, which writes one additive page per month at outputs/monthly-summary/YYYY-MM.md.

Whether the source is an interactive client or scheduled automation, every action that touches your vault is recorded in the activity log.

Where to find it

In the macOS app, click the Agents icon in the left rail (it's the icon between Search and Settings). The Agents workspace opens with seven views in the sub-sidebar:

  • Mission Control — the home view, with summary cards, vault health, recent sessions and proposals at a glance
  • Sessions — every connected MCP client and their connection state
  • Proposals — vault changes an AI has proposed for your review
  • Patterns — derived insights about activity (orphan knowledge, repeated edits, recent errors, inactive sessions)
  • Context Packs — saved bundles of pages you can hand to an AI for setup
  • Vault Health — orphans, broken links, integrity score
  • Permissions — the matrix of what AI clients can and can't do

Each is documented separately in this section.

What gets recorded

Every MCP tool call your connected AI clients make is recorded. The recorded data includes:

  • The tool name (mindwiki_read_page, mindwiki_search, etc.)
  • The arguments that were passed
  • The status (ok or error)
  • The duration in milliseconds
  • A summary of the result
  • Files read or written

You see this stream in Sessions & Activity. There's no way for an AI client to operate against your vault without leaving a trace.

What requires your approval

Read tools (search, read pages, list, ask, similar, graph, lint, list activity) execute immediately when called.

The four write tools — mindwiki_write_page, mindwiki_capture, mindwiki_update_index, and mindwiki_create_proposal — require the connected token to have write scope. OAuth-connected clients get read+write by default after you approve them in your browser. Personal API keys obey whatever scopes you selected when you minted the key.

For the most sensitive operations, an AI can also call mindwiki_create_proposal instead of writing directly. That creates a pending proposal you review and approve in the Proposals view before any change lands. Proposals are how AI clients can suggest a rename, a merge, an archive, or a structured edit without taking action unilaterally.

Live status indicators

The Agents sidebar shows three live indicators based on recent activity:

  • Linker — green if recent linking-related tool calls succeeded, red on errors
  • Pattern Engine — shows the count of derived patterns surfaced in the Patterns view
  • Auditor — shows the vault health score, or an error count if there are recent failures

These are read-only summaries derived from real activity — both interactive MCP tool calls and MindWiki Pro scheduled automation runs. Every signal traces back to a row in the activity log.

Disconnecting an agent

You can revoke an agent's access two ways:

Once revoked, the client immediately stops working. Existing recorded activity is retained.

Where to go next