Installation guide: start with Obsidian — Shared Agent Vault

Why put the evidence in Obsidian?

Changing agents should not mean reconstructing every earlier decision. The Agent Vault bridge in obsidian-master keeps copies of supported conversations and notes, then returns source-linked excerpts when an agent needs them.

Obsidian gives us a place to read those files, follow links and maintain corrections. The vault is an ordinary folder. Python handles capture and retrieval, so Obsidian does not need to stay open for those commands to work. This setup needs no Obsidian community plugin, paid sync service or Obsidian API.

This is a recovery aid, not a circuit breaker. It helps an agent resume from recorded evidence after a stop. It does not enforce spending limits, stop tool calls or guarantee that an agent follows instructions.

Install Obsidian and open a new vault

This guide uses macOS, matching the installed project. Download the macOS installer from Obsidian, open it and drag the app into Applications. The official installation guide covers other platforms, but the scheduled setup below uses macOS launchd.

mkdir -p "$HOME/Knowledge/AgentVault"
open -a Obsidian

Choose Open folder as vault and select Knowledge/AgentVault in your home folder. Start with this separate vault instead of importing your personal notes immediately.

Create a note named START.md at the vault root. Give it a short description of what belongs here and link to a new note at Knowledge/Recovery rule.md. Put this synthetic example in that note:

# Recovery rule

After two failed attempts at the same task, stop and record the failed
approach, the evidence and the next proposed test. Ask before restarting.

This is a test note, not an automatically enforced policy. We will retrieve the same note through all three agents.

Keep notes, code and runtime files separate

~/Knowledge/AgentVault/                 Notes, captured originals, receipts
~/Developer/obsidian-master/             Bridge source and Python environment
~/Library/Application Support/AgentVaultGuide/  Intake config and queue

The bridge keeps its search database outside the vault too. We use AgentVaultGuide for the intake configuration so this tutorial does not overwrite an existing AgentVault deployment. Native agent sessions stay where their applications create them.

Conversation archives can contain private prompts, file contents and tool output. Keep the vault out of public Git repositories. Decide which folders may be captured before configuring an agent source.

Check before continuing

You should be able to read START.md and Knowledge/Recovery rule.md in Obsidian and Finder. No capture, model call or background service has been enabled yet. Next, install the bridge and retrieve the test note.