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.

Reads have no total file-size limit. Each read returns up to 1 KiB, with byte offset, nextOffset, complete, total bytes, and a full-file SHA-256 revision. Continue with offset: nextOffset and that revision until complete: true; changed revisions require restarting the read. UTF-8 pages preserve character boundaries. Decode each base64 page separately before joining binary data. Writes remain limited to 2 MiB. Listings and searches return pages of up to 20 directory entries; continue with nextOffset until null, even when a search page has no matches. Search scans full Markdown files, including large notes, and memory search covers the entire accessible vault.

Vault results receive a separate 16,000-character harness allowance so ordinary read pages and their continuation metadata survive voice tool-result clipping. Context compaction and turn budgets still apply: the agent must disclose partial coverage and resume by path, revision and offset instead of claiming completeness. Hidden configuration and linked files remain excluded by the existing boundary.

Note and memory conventions

The agent searches vault memory at the start of tasks and reads relevant notes fully. The vault is its own. It writes, revises, and retires notes without asking. These semantic rules are agent guidance, not filesystem ACLs. The vault tool does not wait for a confirmation prompt. Other tools still do.

Conflicting historical folder/naming policies are reconciled by preserving existing notes and preferring their established folders. New categories default to articles/, memorandums/, notes/, and memory/; new filenames use kebab-case. Three directory levels and twenty direct subfolders are the guidance limits. Existing notes are not automatically migrated. New notes use YAML title, created, lastModified, category and tags (a list). Daily entries are append-only.

Search before creating duplicate notes; use meaningful, verified vault-relative/note links and project indexes. Obsidian automatically provides backlinks; renaming through this bridge still requires explicit updates to referencing notes. See Obsidian's internal links and properties documentation. Article notes retain sourceUrl and distinguish original text from summaries. Base64 is encoding, not encryption; secrets belong in an approved encrypted store.

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