Using Moldavite

Getting started

Install Moldavite with Homebrew:

brew install --cask mauropereiira/moldavite/moldavite

If you prefer a disk image, open the latest release, download the macOS DMG, and move Moldavite to Applications.

A Forge is a vault directory. Forges normally live side by side under the Forges root at ~/Documents/Moldavite/, although onboarding lets you choose a different root. Inside each Forge, notes are ordinary Markdown files organized into daily/, weekly/, and notes/.

• Multiple Forges: keep Work, Personal, or other vaults separate and switch from the control above sidebar search or the Switch Forge… quick-switcher action. Recents, pinned notes, plugins, and app-managed indexes follow the current Forge.
• Daily notes: Today opens the current date and creates its file when needed. Empty daily notes are removed automatically; images count as content.
• Weekly notes: select a calendar week to open its ISO-week note. Empty weekly notes are also cleaned up.
• Standalone notes: create regular notes under notes/, including nested folders. Folders can be created, renamed, and reorganized from the sidebar.

Import from Obsidian

Open Settings → Import and choose an Obsidian vault folder. Moldavite first shows a read-only preview, then copies the vault into a new Forge; it never edits, moves, or deletes anything in the source vault. You choose the new Forge name and can switch to it from the completion summary.

• Daily-note settings from .obsidian/daily-notes.json are detected when present. Formats made from YYYY, MM, and DD with -, _, ., or / separators are normalized to daily/YYYY-MM-DD.md; names that do not parse remain standalone notes.
• Other Markdown notes retain their folder structure with filesystem-safe, collision-deduped names. YAML frontmatter is preserved verbatim.
• Obsidian [[target|Display]] aliases become Moldavite [[Display|target]] aliases, while heading and block suffixes are removed from link targets. Referenced wiki embeds and local Markdown images are copied into images/ and rewritten to relative Markdown image paths.
• .obsidian/, .trash/, hidden items, Canvas files, and symlinks are never imported. Unreferenced attachments and unresolved embeds remain listed in the final report; unresolved embed text is left in the note.

The editor, wiki-links, and graph

Moldavite uses a TipTap rich-text editor while saving Markdown on disk. Markdown shortcuts work as you type: for example, # plus Space starts a heading and - starts a list.

Formatting and commands

• Headings, bullets, numbered lists, task lists, and blockquotes.
• Bold, italic, underline, strikethrough, highlights, and text alignment.
• Inline code, code blocks, links, and resizable images.
• A selection toolbar for formatting highlighted text.
• Type / for blocks and commands, including commands registered by enabled plugins.

Wiki-links and backlinks

Type [[Note Name]] to link a note, or [[Display text|target-note]] to separate the visible label from its target. Linked mentions below the editor and the backlinks sidebar show which notes point back to the current one. Unresolved links remain visibly distinct and can create a standalone note.

Rename a note without breaking its context

Rename a standalone note from its sidebar context menu or the editor's More menu. Moldavite updates the open note, tabs, recents, pinned state, colors, selection, and backlinks to the new path, then rewrites inbound wiki-links across the Forge. Daily and weekly notes stay date-named and cannot be renamed through this action.

Graph view

Open the graph from the quick switcher to explore connections. Nodes use complete Forge-relative paths, so folder notes, daily notes, and weekly notes with similar names remain distinct and open the correct file. Broken-link nodes stay visible without colliding with real notes.

• Hover a node to highlight its neighbors and connecting edges.
• Drag nodes, drag empty space to pan, and use the wheel or trackpad to zoom.
• Use Fit view whenever you want to recover a useful framing.
• Short springs and per-component gravity pull connected notes into visible clusters while isolated notes settle into peripheral rings. The bounded deterministic layout cools to a stop, refits on resize, and redraws when the theme changes.

Tags and templates

Inline #tags are aggregated in the sidebar; a tag can be renamed across the Forge from its context menu. Templates live under Settings → Templates and support these substitutions:

Pin up to six templates for quick access from an empty note.

Organization and search

Sidebar sections are collapsible, with their contents indented beneath each section header and a subtle guide line that makes the hierarchy clear at a glance.

• Quick switcher: press ⌘ P to open a note, run an app action, repeat a recent search, switch Forges, or invoke a plugin command.
• Keyword search: full-text search with snippets across unlocked, non-trashed notes.
• Folders: a drag-and-drop tree for standalone notes when hierarchy helps.
• Colors: assign a sidebar color to individual notes.
• Tabs and pinning: reorder open tabs and pin up to five frequent notes.
• Timeline: browse notes grouped into Today, Yesterday, This Week, This Month, and Earlier.
• Shortcut help: press ⌘ ? for the current shortcut list.

Local semantic search

Keyword search matches words; semantic search matches meaning. A query such as “quarterly planning” can surface a note that only says “Q3 roadmap discussion.” The feature is off by default and must be enabled under Settings → AI & Agents.

Semantic search requires Apple Silicon on macOS. Intel Macs keep the full keyword search, and MCP search_notes transparently uses keyword mode.

Choose a transparent local model

Before the first download, Moldavite's consent dialog names the selected model and its approximate size. The model is cached in the app data directory, never in a Forge. Notes are embedded on your Mac; locked notes are never read or indexed.

Hugging Face is contacted only to retrieve the model after consent. Once the download is complete, indexing, queries, and related-note comparisons run offline.

Search and discover related notes

• Once the index is ready, sidebar search shows a Keyword / Semantic mode control. Semantic results are ranked by similarity.
• A Related section below the editor lists the five notes most similar to the note you are reading, alongside Linked mentions.

The per-Forge index updates incrementally on save, delete, rename, trash, and restore. Changing models performs a complete re-index with live progress. If results seem stale, use Rebuild index in Settings to embed the Forge again from scratch. Internal index data lives at <Forge>/.index/.

Safety, privacy, and external edits

Moldavite has no hosted note service, accounts, analytics, or telemetry. Notes stay in the directory you choose. The app still has explicit network paths: signed update checks, consented semantic-model downloads, and HTTPS calls made for a plugin to a host you approved.

• Atomic writes: note and app-data saves use a temporary file, flush, and rename so a mid-save crash cannot leave a truncated destination.
• Trash: deleted notes remain available with previews for seven days before automatic cleanup.
• Note locking: encrypted .md.locked files use AES-256-GCM with Argon2 key derivation, rate-limited unlock, and optional auto-lock.
• Backups and export: export Markdown, plaintext, PDF, full ZIP archives, or password-protected encrypted archives. Nested and weekly notes retain their folders.
• Signed updates: update artifacts are cryptographically verified before installation, and the app shows release notes afterwards.

External-edit conflict copies

A Forge can live in iCloud Drive, Dropbox, Syncthing, or git and can be edited in another app. The file watcher refreshes Moldavite when disk changes. If a note changed on disk after Moldavite last read it and you then save different edits, the app does not silently destroy the disk version:

1. The complete external file is preserved beside the original as <name> (conflict YYYY-MM-DD HHMM).md.
2. Your Moldavite edits are saved to the original path.
3. A warning toast names the conflict note and the sidebar refreshes so you can merge it.

Simultaneous conflict copies in the same minute receive a numeric suffix, which prevents one copy from overwriting another.

Calendars

The right panel can show a month and your events from two sources. Both are read-only: Moldavite never creates, edits, or deletes an event, and never writes one into a note by itself. Connect either or both in Settings → Calendar, then tick the individual calendars you want on the timeline.

• Apple Calendar: native EventKit on macOS. The system asks for permission the first time, and nothing leaves your machine.
• Google Calendar: connecting opens your browser for Google's consent screen and returns to a local port. Moldavite asks only for the read-only calendar scope. The refresh token is stored in your macOS Keychain and stays outside notes and settings files. Disconnect removes it, and you can also revoke access from your Google Account permissions page.

If one source fails, the timeline keeps the available source visible and reports the error above the grid. What each connection sends is listed in the Privacy Policy.

Staying up to date

Moldavite checks for updates silently about once a day, including when you return focus to the app after a day. When an update is pending, a small accent dot appears on the sidebar Settings gear and on the About tab. No popup interrupts your work.

Open Settings → About to install the pending update. You can also check manually from that tab at any time.

Plugins and Publish to WordPress

Plugins add commands to the command palette and slash menu. Each plugin runs in a Web Worker without direct DOM, network, Tauri IPC, or global app-state access. Moldavite shows its requested permissions before enabling it and re-prompts whenever the manifest or code hash changes.

The current plugin API can expose active-editor HTML, trusted prompt forms, unlocked note reads, host-performed HTTPS to exact approved hosts, and plugin-namespaced macOS Keychain secrets. It does not provide note-write methods or custom panels. See the complete author guide for the exact API and security model.

Browse the community directory

The website directory is searchable by plugin name, description, author, and permission. Its Install in Moldavite links use the app's moldavite://plugin/<id> URL scheme to open Settings directly on the chosen plugin. Moldavite still shows a confirmation with permissions and never installs or enables a plugin silently.

1. Use an install link on the website, or open Settings → Plugins and select Browse community plugins.
2. That click is the explicit action that contacts GitHub; Moldavite never fetches the registry during startup or in the background.
3. Review the author, requested permissions, and exact network hosts, then select Install.
4. Moldavite downloads only from its pinned community repository and verifies both files in Rust against the registry SHA-256 hashes before installing them atomically.
5. Read the About this plugin setup dialog, then enable the plugin and grant its permissions separately. The ⓘ action reopens those instructions at any time.

Installed registry versions are labeled clearly. Updating requires confirmation, and any manifest or code change invalidates the old consent hash so the plugin remains disabled until you review it again.

Install the first-party WordPress reference

1. Open Settings → Plugins.
2. Select Install Publish to WordPress, then enable the plugin.
3. Run Configure WordPress publishing and enter an HTTPS site URL, username, and WordPress Application Password in the Moldavite-rendered prompt.
4. Approve the exact site host. The plugin verifies the credentials before saving them.
5. Open a note and run Publish note to WordPress….

The first publish creates a draft. Publishing the same Forge-relative note path again updates the mapped post and avoids a duplicate. Configuration and the path-to-post map live in the plugin's Keychain namespace and stay outside the Forge.

Use a Forge as agent memory

File-capable agents can work with a Forge directly because it is plain Markdown. Open Settings → AI & Agents and select Make this Forge agent-ready to write two files at the Forge root:

• AGENTS.md describes daily, weekly, and standalone paths; optional frontmatter; Unicode-aware wiki-link slugs; tags; locked notes; and rules that keep agents away from app-managed directories.
• .gitignore lists .trash/, .plugins/, .index/, and .DS_Store.

If either file exists, Moldavite asks before replacing it. Settings also shows whether the current Forge already has an AGENTS.md.

Connect an MCP client

The normal Moldavite app binary becomes a local stdio MCP server when launched with --mcp. It does not initialize the GUI and does not open a network listener. Settings resolves the exact binary path on your Mac and provides copy-ready snippets for each supported client; use those generated snippets whenever possible.

Claude Code

Run the generated command in a terminal. A standard app installation looks like this:

claude mcp add moldavite -- "/Applications/Moldavite.app/Contents/MacOS/moldavite" --mcp

Claude Desktop

Add a server to claude_desktop_config.json:

{
  "mcpServers": {
    "moldavite": {
      "command": "/Applications/Moldavite.app/Contents/MacOS/moldavite",
      "args": ["--mcp"]
    }
  }
}

Cursor

Save the same server shape as .cursor/mcp.json:

{
  "mcpServers": {
    "moldavite": {
      "command": "/Applications/Moldavite.app/Contents/MacOS/moldavite",
      "args": ["--mcp"]
    }
  }
}

Generic stdio MCP client

Use the resolved binary as command and pass --mcp as its first argument. Moldavite's generic snippet is:

{
  "moldavite": {
    "command": "/Applications/Moldavite.app/Contents/MacOS/moldavite",
    "args": ["--mcp"]
  }
}

Choose a Forge

MCP mode uses the active Forge by default. To pin a different existing Forge, append --forge and its exact name. For JSON clients that means "args": ["--mcp", "--forge", "Work"].

Read tools are the default

Enable the three write tools only through Settings → AI & Agents → Allow agents to write notes. The setting is re-read for every request, so turning it off removes and blocks write tools in already-running sessions. Locked notes remain inaccessible, and every client-supplied path is validated.