gnome-jarvis/docs/obsidian.md

Obsidian agent vault

Jarvis has an opt-in, native JavaScript filesystem bridge. It works with ordinary Markdown notes, frontmatter, wiki links, and attachments, including while Obsidian is closed. There is no REST server, plugin, API key, or new runtime dependency. Obsidian uses local folders of Markdown files.

Setup

1. Open Jarvis Settings → Access. Enable the Obsidian bridge and optionally vault memory, then Save only.
2. On Obsidian, choose an empty folder or enter an absolute path to a new folder. A blank path uses $XDG_DATA_HOME/jarvis/obsidian-agent, normally ~/.local/share/jarvis/obsidian-agent.
3. Press Apply to save the vault folder.
4. Press Initialize vault, then Verify access. Verification performs an actual temporary write/read/delete in the vault and separately in memory/ when memory access is enabled. Refresh shows applied configuration and access.
5. In Obsidian, select Open folder as vault and register that folder once. The settings Folder button locates it; Obsidian uses the official open URI after registration. Obsidian installation and registration are separate from filesystem verification.

Both switches default to false. Opening settings, starting the daemon, and reading status never initialize a vault. Initialization rejects nonempty personal vaults. A Jarvis ownership marker is required for subsequent access. Apply resets conversation context when these settings change, without restarting the daemon. Disabling the bridge preserves the vault and removes its tool from the agent.

Agent operations

The obsidian tool supports status, list, read, write, mkdir, move, delete, trash, restore, search, and memory_search. All paths are relative to the agent vault. Write notes as .md; frontmatter and links are preserved as raw Markdown. Binary attachments use encoding: "base64" for read/write.

Read a file first to obtain its SHA-256 revision. Replacement, move, and delete require that revision, rejecting stale edits. New files omit it. Writes use a sibling temporary file and rename. Moves reject existing destinations and do not automatically rewrite links; the agent can search and edit referencing notes. Deleting files moves them into .trash with their original path and deletion time. Restore takes trashId, optionally a new destination, and never overwrites an existing file. Folder deletion only removes empty folders; organize folder contents by moving individual files. There is no permanent-delete tool.

When memory is enabled, the agent uses memory/*.md and memory_search for new durable memory instead of the built-in memory tools. Existing workspace memory remains as legacy context; there is no automatic migration, synchronization, or bulk disclosure to the vault. Settings can browse files, search notes/memory, and read selected Markdown. Turning memory off hides and rejects memory/ paths and their trash records through the bridge. Other workspace files and broader file access permissions remain governed by the existing agent settings.

Hidden files, .obsidian configuration/plugin code, symlinks, hardlinks, traversal, and special files are excluded from agent operations. The bridge does not execute note contents. This is a dedicated-vault boundary, not an OS sandbox against another process running as the same user. Avoid concurrent automated writers: revision checks detect edits made before the check, not every possible filesystem race with another application.

Files are limited to 2 MiB per bridge operation. Listings stop at 10,000 visited entries or 32 levels. Search scans Markdown, up to 32 MiB and 50 matches, and reports truncation. Larger attachments can remain in the vault but cannot be read or managed through this bounded bridge.

Configuration and verification

config.json fields: obsidianEnabled (false), obsidianVaultPath (empty string), obsidianMemoryEnabled (false). GNOME preferences and Control Center share the same catalog and page. Changes are applied through ReloadSettings.

D-Bus io.qvac.Jarvis.Session.ObsidianAction(s) → s accepts a JSON tool action and returns JSON. Settings additionally use initialize and verify. Initialization is intentionally unavailable as an agent tool. GetRuntimeStatus includes an obsidian status object. Errors propagate as D-Bus errors.

Run:

node --test --experimental-test-isolation=none test/obsidian.test.js test/settings.test.js
bash packaging/bare-launch.sh packaging/bare-run.js scripts/smoke-obsidian.js
gjs -m scripts/smoke-settings-ui.js