# 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.

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. Its system guidance requires explicit authorization for concrete writes,
including saving memory; a user request to save specified content provides that
authorization. These semantic rules are agent guidance, not filesystem ACLs.
Existing built-in tool permission gates also remain in effect.

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|label]] links and project indexes. Obsidian automatically
provides backlinks; renaming through this bridge still requires explicit updates
to referencing notes. See Obsidian's [internal links](https://obsidian.md/help/links)
and [properties](https://obsidian.md/help/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:

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