84 lines
4.6 KiB
Markdown
84 lines
4.6 KiB
Markdown
# 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
|
|
```
|