Using Moldavite

Getting started

macOS

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.

Windows

Open the latest release and download Moldavite_x.x.x_x64-setup.exe (recommended) or Moldavite_x.x.x_x64_en-US.msi. The installers are not Authenticode-signed, so SmartScreen may warn you. If you downloaded Moldavite from the official release page, choose More info, then Run anyway.

Linux (beta)

Open the latest release and download Moldavite_x.x.x_amd64.AppImage for any distribution, Moldavite_x.x.x_amd64.deb for Debian and Ubuntu, or Moldavite-x.x.x-1.x86_64.rpm for Fedora. All need glibc 2.38 or newer, so Ubuntu 24.04, Debian 13, Fedora 39 or later; the local semantic-search runtime sets that floor. Mark the AppImage executable once, and install libfuse2 if your distribution does not ship it (sudo apt install libfuse2 on Ubuntu). In-app updates work for the AppImage; the deb and the rpm are updated by installing the next one. Linux builds pass the same test suite as macOS and Windows but have not yet been exercised by hand, which is why they are beta.

A Forge is a vault directory. Forges normally live side by side under a Moldavite folder in Documents, 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 and tables 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.
• Images: pasted and inserted images are saved in the Forge's images/ folder and linked from the note as images/<file>, whichever folder the note is in, so they keep loading on every device that syncs the Forge.

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

Rename a note from its title

Click the title at the top of a note and type. Enter saves and moves you into the note's text, Escape abandons the edit, and an empty name is refused. A name that cannot be used is explained under the title as you type, and so is a rename that fails; once you leave the title the previous name comes back, so the page never shows a name the file on disk does not have. Inbound wiki-links are rewritten across the Forge either way. Daily and weekly notes are named by date and stay read-only here.

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.
• Tables, saved as Markdown pipe tables. Insert one from / or the Format menu; Tab moves to the next cell and adds a row after the last one, and the Format menu adds or removes rows and columns while the cursor is in a table. Cells hold text, so a list or heading pasted into one becomes plain lines.
• 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.

• Notes are drawn as stars, sized and brightened by how many links they carry, and the note you have open wears a thin ring. Opening the graph plays the field into focus from the centre outward.
• Hover a node to highlight its neighbors and connecting edges, dimming the rest.
• Drag nodes, drag empty space to pan, and use the wheel or trackpad to zoom.
• Panning is free in every direction, and the graph keeps your zoom and position for the rest of the session. Use Fit view, or double-click empty space, 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, frames itself once when you first open it, 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

Pin the notes you keep returning to

Right-click a note in the Index, or use More in the editor footer, and it joins a bar across the top of the app. The bar only exists while something is pinned. Four notes stay on it and the rest collapse behind a count; drag one to reorder it, or hold alt and press left or right when it has focus.

Opening a pinned note returns you to the tab you already had it in rather than opening a second copy of it.

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 ⌘/Ctrl P to open a note by its title or by the words in it, 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, answered from a local SQLite index so it stays instant as a Forge grows. Several words match a note that contains all of them, in any order. The index file sits in the app data directory rather than in the Forge, so a synced folder never carries it, and it is removed when its Forge is.
• Folders: a drag-and-drop tree for standalone notes when hierarchy helps.
• Colors: assign a sidebar color to individual notes.
• Themes and layout: Settings → Appearance offers Cream, Sage, Slate, Clay, Plum and Graphite, each in light and dark, and Settings → Layout → Rail side puts the icon rail on the left or the right. A pinned Index moves with the rail.
• Tabs: reorder open tabs, and pin up to five of them so they stay at the front of the tab strip.
• Timeline: browse notes grouped into Today, Yesterday, This Week, This Month, and Earlier.
• Shortcut help: press ⌘/Ctrl / for the current shortcut list.

Keyboard shortcuts

The app reads ⌘ and Ctrl interchangeably, so the same bindings work everywhere: on Windows and Linux, read ⌘ as Ctrl and ⌥ as Alt. The in-app list under ⌘ / is generated from the same registry as this table.

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.

Windows and Linux builds include semantic search. On macOS it requires Apple Silicon; 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 computer; 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. A locked note stays encrypted in the Trash and is restored locked.
• Note locking: encrypted .md.locked files use AES-256-GCM with Argon2 key derivation, rate-limited unlock, and optional auto-lock. A locked note opened with its password is view only; remove the lock to edit it.
• 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.

Start an iCloud Forge on Mac

Turn on Settings → General → Use synced Forge to create or open your shared iCloud folder. You can start writing on Mac before installing the iOS app. Your existing local Forges stay separate.

Use Open synced folder in Finder to add Markdown files to its notes/ folder. Other Apple devices using the same Apple Account can open the same Forge when you enable it there. iCloud Drive must be enabled; allow time for uploads and downloads. A note that is only in iCloud shows a small cloud in the note list; open it and choose Download to fetch it. See the Mac iCloud guide for setup, copying existing notes, and connection help. On iPhone and iPad, get Moldavite from the App Store and turn on the synced Forge there.

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 is macOS-only; Google Calendar works on macOS, Windows and Linux. The month grid and your daily-note markers work with no calendar connected at all.

• 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 the OS credential store (macOS Keychain, Windows Credential Manager, or the Linux Secret Service) 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 OS credential-store 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.

Publish to WordPress.com from the editor footer

If you write on WordPress.com, nothing needs installing. Open a note and select WordPress in the editor footer, then Connect WordPress.com…. Your browser opens, you sign in and approve, and the browser hands you back to Moldavite. There is no credential to create, copy, or paste.

Once connected, the same button lists the sites you can publish to. Pick one and select Publish. The first publish creates a draft; publishing that note again updates the same draft rather than leaving another one behind. The mapping is remembered per site, so the same note published to two blogs is two posts.

Sites you can only read are left out of the list: they look like a choice and fail on use. Disconnect removes the stored token and forgets which posts came from which notes. You can also revoke access from WordPress.com under Security → Connected Applications.

Install the first-party WordPress reference

This plugin is for self-hosted WordPress, which has no WordPress.com account to sign in with. On WordPress.com, use the footer button above instead.

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 OS credential-store namespace and stay outside the Forge.

Clipping pages from your browser

The Moldavite clipper turns the page you are reading into a Markdown note in the Forge you choose. Headings, lists, quotes, code, and tables survive; links are kept and rewritten to absolute addresses so they still work from a note; images and styling are dropped. Notes land in notes/Clippings/ with the source URL and date in frontmatter, and clipping the same page twice never overwrites the first one.

The extension is distributed from the Moldavite repository rather than the Chrome Web Store or the Firefox add-on gallery. Both browsers ask for something unusual as a result, and neither is a defect in Moldavite:

• Chrome, Edge, and Brave: download and unzip the archive, open chrome://extensions, turn on Developer mode, then choose Load unpacked. Chrome only permits extensions from outside its store in Developer mode; that is Chrome's rule for anything unlisted.
• Firefox: download the .xpi and open it. Firefox installs only signed add-ons, so the file is signed by Mozilla. It is not listed in their store. The Chrome archive is built and attached automatically on every release; the .xpi has to be signed and uploaded by hand afterwards, so a given release may not have one yet.

Then open Settings → Plugins → Browser clipper and press Connect browser. Nothing can reach your notes until you do: pairing writes a native-messaging manifest naming the exact extension allowed to connect, and the browser enforces it. The channel is write-only: it can create a clipping and list your Forge names, and there is no way to read a note through it. Because the browser starts Moldavite's binary on demand, clipping works whether or not the app is open. The clipper reference covers troubleshooting.

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 computer and provides copy-ready snippets for each supported client; use those generated snippets whenever possible.

Claude Code

Run the generated command in a terminal. The examples below show a standard macOS app installation; on Windows and Linux, use the generated snippets so the path matches your installer. A deb or rpm installs /usr/bin/moldavite; for an AppImage the path is the .AppImage file itself, wherever you keep it.

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 blocks the very next write call in a session that is already running. The tool list is a separate matter: Moldavite sends no list-changed notification, so a connected client keeps showing the write tools until it asks for the list again. No tool returns a locked note's contents, and every client-supplied path is validated.