A useful research session should leave more than a good final response. It should leave notes a person can read, link, correct, and carry into the next project. If those notes exist only as opaque retrieval records, the human has a harder time understanding what the agent believes it knows.
The Obsidian plugin gives Agent Zero a Markdown vault, a CLI for working with it, and a live view of the Obsidian application in the Canvas. Its most consequential design choice is to keep the default vault outside the plugin's installation directory. The notebook is user data, with a lifecycle distinct from the software presenting it. Plugin overview
Research basis: We reviewed Obsidian 1.4.0 by King0James0 at
8fb42eec6ac2, including setup, the screencast bridge, surface API, skills, and cleanup. The repository's thirteen setup-security tests passed in the isolated framework container. We did not download Obsidian or exercise a live GUI, CLI socket, clipboard bridge, or uninstall operation.
The short version
- Put the document at the center. Notes, citations and links remain available for human inspection.
- The CLI needs the living app. The Canvas shows the same instance through the reviewed CDP bridge.
- The vault has a separate lifecycle. Default cleanup preserves it, but preservation is not a backup.
| Component | Reviewed lifecycle |
|---|---|
| App, wrapper and stream | Runtime managed by the plugin |
| Markdown vault | Outside the plugin folder; preserved by default |
| Linked external note | Edits can reach the original file |
| Project organization | Folder structure does not create access isolation |
Notes and retrieval solve different problems
The plugin supplies skills for reading and writing notes, maintaining a linked vault, and opening the application surface. Its initial structure includes project, knowledge, research, archive, and daily-note folders plus a Home index. Seeding is intended to provide a starting structure without overwriting existing notes. Vault-keeping skill Seeding code
This is a different artifact from a vector memory. A note can preserve a citation, a decision, a date, and a person's correction in a form that can be inspected directly. A link can express the author's intended relationship between two notes. The graph view can help explore that structure, but it does not establish that either note is correct.
For research, a useful note separates observed facts, interpretations, and open questions. Link to original sources and record when they were checked. That practice turns the vault into an inspectable working record rather than a collection of confident summaries.
The plugin does not automatically make Obsidian content equivalent to Agent Zero's _memory store. A note's existence and an agent's ability to retrieve it are separate facts. The supplied skills tell the agent how to query the notebook; assess that workflow directly.
The CLI needs a living application
Obsidian is an Electron application. The plugin launches an instance on a virtual display and writes a wrapper so the agent's CLI reaches the same application's environment and socket. The live Canvas and CLI share the instance and vault. Setup and wrapper
This explains why “headless notes” still need runtime processes. A Markdown file on disk can be read without a GUI, but the Obsidian CLI's behavior depends on the running application. Stopping a visible surface is therefore different from shutting down the app that serves CLI requests.
The surface API's close action stops the surface session while the application remains available. Opening it starts the stream through Agent Zero's desktop gateway. This keeps the display lifecycle separate from the note lifecycle. Surface API
The implementation has moved beyond parts of the README
The README describes an Xpra-shadow surface. The reviewed source uses a Chrome DevTools Protocol screencast bridge and configuration fields such as cdp_port and bridge_port. The setup launches Electron with a remote-debugging port, and the bridge handles screencast frames and input dispatch. Current bridge Current defaults
That difference is operationally significant. A troubleshooting guide based solely on the older Xpra description could direct attention to the wrong process or port. In this article, the source at the pinned revision governs the description. Some comments and error text still mention Xpra, so record the revision when reporting a problem.
The setup code also contains architecture-specific installation paths, including an ARM64 tarball path as well as the .deb path. Avoid assuming every installation follows the README's package example. Installation code
These observations do not establish a working surface on a particular host. They explain what to verify in an end-to-end check: app process, CLI communication, bridge session, gateway route, and actual note readback.
The default vault survives the plugin
With an empty configured vault path, setup resolves the default to /a0/usr/obsidian. Runtime application state is separate. Cleanup stops owned runtime processes, restores the desktop launcher, removes runtime state, and preserves the vault unless delete_vault_on_uninstall is explicitly enabled. Vault resolution and cleanup
This is a stronger data-lifecycle contract than storing all notes under the plugin directory and hoping an uninstall leaves them behind. It is still not a backup. A persistent Docker volume can be removed, files can be edited incorrectly, and a configured deletion switch changes cleanup behavior. Back up the vault as a collection of user documents.
The default is also one shared vault path, not automatic project isolation merely because Agent Zero projects are isolated elsewhere. Separate project organization within the vault from separate storage and access boundaries. If several projects must not share notes, configure and verify the intended vault arrangement rather than relying on folder names alone. Configuration and path resolution
Opening an external note can extend the edit boundary
The desktop launcher can take a Markdown file outside the vault and link it into an Inbox so the running Obsidian instance can open it. The README states that edits then write back to the original file. Desktop integration Launcher generation
That is convenient for editing an existing document. It also means “inside the Obsidian interface” does not necessarily mean “a separate copy inside the vault.” Before using the feature on a repository file or another important document, inspect whether the target is linked or copied and verify the resulting changes in the original location.
This is a concrete authority boundary in the plugin's workflow. It deserves to be part of the operating explanation rather than hidden behind an attractive graph view.
Downloads and tests have different assurances
The default Obsidian version setting is latest, and expected_sha256 is empty. Setup can verify a configured checksum and refuse a mismatch. Without one, the documented trust path relies on the official download over HTTPS. Pinning the plugin alone therefore does not pin the application download. Checksum verification Defaults
Our thirteen passing tests concern setup-security details, including safely generated launcher paths and environment handling. They do not establish successful package installation, GUI stability, clipboard interoperability, or persistence through a real removal and reinstall. Setup tests
A useful acceptance exercise would write a synthetic note through the CLI, read it in the Canvas, edit it visibly, and read it back through the CLI and filesystem. A lifecycle exercise would back up the synthetic vault, remove the plugin through its intended interface, and verify the preserved notes. Those exercises are proposed here, not claimed as completed.
Obsidian's appeal in Agent Zero is the human-readable artifact at the center of the system. The live application is helpful, but the enduring value is a notebook whose sources, links, and edits remain available for a person to inspect.
Sources
Obsidian for Agent Zero 1.4.0, King0James0, reviewed at
8fb42eec6ac2; author citation metadata.All motion illustrations are original and derived from the reviewed sources. Illustrative data is labeled.