# 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](https://obsidian.md/help/data-storage).

## 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](https://obsidian.md/help/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:

```sh
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
```