118 lines
6.8 KiB
Markdown
118 lines
6.8 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.
|
|
|
|
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
|
|
```
|