Proposals

Proposals are how an AI suggests a change to your vault without making it unilaterally. Instead of writing or deleting directly, the AI calls mindwiki_create_proposal, which creates a pending entry you review and approve before anything happens.

This makes AI behavior predictable on your most important knowledge. The AI gets to say "I think this should change" without you handing over total trust.

Where proposals live

The Proposals view in the Agents workspace (macOS app) lists every proposal the AI has created. Each entry shows the type, summary, target files, and status.

The same data is available via:

  • The mindwiki_list_proposals MCP tool — for any connected AI client
  • The REST endpoint /vault/agents/summary — for scripts and integrations
  • The web app's account dashboard — pending proposal counts surface there

Anatomy of a proposal

When an AI creates a proposal, it provides:

  • Type — what kind of change it's proposing (see types below)
  • Summary — a one-line human-readable description
  • Rationale — why the AI thinks this change is useful
  • Target files — the vault paths affected
  • Diff — an optional unified diff or before/after explanation
  • Payload — optional structured data for the change

The proposal is recorded with a status of pending. Approval, rejection, and "applied" status are tracked over time.

Proposal types

The proposal protocol supports these types — chosen by the AI based on what it's suggesting:

TypeWhat it means
edit_noteModify the body of an existing page
create_noteCreate a new page
merge_notesCombine two or more pages
split_noteBreak one page into several
rename_noteChange a page's title or path
move_noteMove a page to a different folder
add_tagsAdd frontmatter tags
update_linksAdd or fix wikilinks
archive_noteArchive a stale or superseded page
flag_contradictionSurface conflicting claims across pages
create_decisionRecord a decision page
create_summarySynthesize a summary across pages

The AI picks the type. Your job is to read the proposal and accept, reject, or ignore.

Reviewing a proposal

In the Proposals view:

  • Read the summary and rationale to understand what's being suggested.
  • Open the target files to see the current state.
  • View the diff to see exactly what would change.
  • Approve to mark the proposal accepted (manual application is the current model).
  • Reject to dismiss it.
  • Ignore to leave it as pending — no decision required immediately.

The current iteration of the macOS app provides the proposal review surface; one-click apply for every proposal type is on the roadmap. For now, an approved proposal is a clear signal you've decided to take the action — typically by asking your AI to execute it, or by making the change manually.

When to expect proposals

Proposals are most useful for:

  • Stale knowledge cleanup. "These three pages cover the same thing. Merge them."
  • Cross-domain connections. "These five pages share the same structure. Worth promoting to a pattern page."
  • Decision records. "You've been weighing this trade-off across three conversations. Here's a decision page summarizing it."
  • Tag canonicalization. "You're using meeting and meetings interchangeably. Pick one."

You can also explicitly ask your AI to use proposals: prompt with something like "Don't write directly — propose this as a vault change for me to review."

Filtering proposals

The view supports filtering by status:

  • pending — awaiting review (the default view)
  • approved — you've accepted but they haven't been applied yet
  • rejected — dismissed
  • applied — fully executed

The MCP tool mindwiki_list_proposals accepts the same status filter and a limit parameter (default 50, max 200).

Where to go next