01 / The story
The project continues. The conversation changes.
The starting question was simple. Could we keep our working history in an Obsidian vault and use it across agents and machines? A project can outlive a chat session, a model choice or the application we started in. Its decisions still matter.
I wanted something easy to install and run locally, ideally on any operating system. The notes had to be Markdown so I could read and edit them myself, even without an agent. I also wanted a minimal dashboard to see what the system was doing without building another application around it.
Obsidian fitted that idea. It gave me a reader for the Markdown files, links between notes and a graph of those connections. Its support for HTML in notes also suited the lightweight interface I had in mind. Easy installation and support across operating systems were requirements to work towards, not things I wanted to assume were already solved.
Copying a summary into the next conversation helps, but a summary can lose the reason behind a decision. It can also carry an old mistake forward without the correction that came later. We wanted to be able to check the original.
We built obsidian-master around ordinary files and a shared retrieval command. Native agent sessions stay in their own locations. The bridge keeps copies of supported records in a separate vault, where changing the agent does not mean abandoning the archive.
After one week
The graph gives me a way to explore the connections. To understand a particular decision, I still need to open the note and follow it back to the source. The dashboards answer a different question: what did the bridge capture, judge and return?
02 / The problem
Saving everything is not the same as remembering what matters
An archive can grow far beyond what belongs in a prompt. Sending the whole history to a model adds noise and makes it harder to see which evidence an answer actually used.
The opposite shortcut is risky too. If a model decides that a passage is unimportant and we discard the original, a later question may need evidence we no longer have. Our bridge therefore preserves sources before optional judging.
We also need to distinguish a user's decision from an assistant's suggestion. Both can be worth keeping. Neither should silently turn into a verified fact because another agent retrieved it.
03 / How it works
One archive, a local search index, several agents
Obsidian makes the files readable
The vault holds captured originals, maintained notes and records of review. Obsidian lets us follow links between them and edit the notes we own. The bridge does not need an Obsidian community plugin or a paid sync service. Its command-line work can continue with the app closed.
Markdown is the format for the notes I maintain and read. The supporting records use the formats that suit them: JSONL for captured conversations, JSON for receipts and manifests, and HTML for dashboard views. Keeping the notes readable does not mean converting every original record into Markdown and losing its structure.
The source scanner can also copy files from existing notes folders. It preserves physical copies and revisions rather than depending on links to folders that may be absent on another machine.
The bridge preserves who said what
Host-specific adapters recognise supported Codex, Claude Code and Pi conversation records. Incremental capture keeps new segments with their source identity. The original records remain separate from the visible-message text used for search.
That separation matters. A search result can point back to the preserved source, but not every tool record or binary attachment becomes searchable text. Host transcript formats can change, so capture needs a real-message check after updates.
Retrieve a small set of evidence when it is needed
SQLite FTS5 searches the local archive. The retrieval command returns bounded excerpts with source references and attribution. The agent receives relevant history without loading the whole vault into every conversation.
Agent asks a focused question
→ Local search finds candidate excerpts
→ A size-limited bundle includes source references
→ The agent answers using that evidence
→ You can open the original and check itEach agent has an instruction explaining when and how to call the same retrieval command. This is explicit retrieval, not a replacement for the application's native memory. It also depends on the agent having access to the bridge and index.
Where we use Jev
We use Jev as the judge in this workflow. On intake, it assesses a selected passage for useful signal, assigns a category and scores its potential reuse. A decision, a preference and a proposed procedure need different treatment. The result is a structured judgment saved alongside the source, rather than a replacement for it.
Signal estimates usefulness under our rubric, not the probability that a statement is true. Reusability is a score, not another confidence probability. We keep the provider's result and the request in a receipt so the judgment can be inspected later.
Jev also has an optional role during retrieval. Local search finds a shortlist first; Jev can then assess relevance and support for the current question to help rank that evidence. This is separate from the earlier decision that a passage was worth reviewing.
These Jev calls use a hosted service and send selected text outside the machine. They are optional in the setup. Capture and local keyword search work without a key, and the installation guides start with judging paused.
Judgments stay advisory. A review step can promote a source-linked excerpt into a maintained note, while preserving the original. Corrections can be attached to earlier claims so a later search can return the correction with the evidence it changes.
Small dashboards that show the work
I wanted to inspect the process without reading every raw receipt. The bridge generates HTML views under System/Dashboard, alongside the Markdown notes and source records.
Judging.htmlshows the source passage, Jev's signal, category and reusability results, review status, latency and estimated cost when available. Each result links to its original and full receipt.Retrieval.htmlshows a recorded query, the candidate excerpts and which ones reached the answer bundle. Where reranking ran, it also shows relevance and support judgments.Operations.htmlbrings together the latest capture status, queue, search index, review counts and backup checks. Its timestamps describe observed runs, not a guarantee that everything is still running.Evaluation.htmllets us inspect saved comparisons of the evidence supplied to an answer. The separate local evaluation runner handles new tests and human review, so context size, timing and answer quality can be examined separately.
Obsidian supports HTML inside notes, with sanitisation and limits. That is different from running a complete interactive HTML application inside a note. The generated dashboard files can be opened in a browser, and the interactive evaluation tool runs through a separate local server.
These views reflect the workflows that have actually run. A read-only search does not create a new retrieval report, and a fresh installation will not have judging results or evaluations yet. The files and receipts remain the evidence behind the dashboard.
Test the handoff, not just the answer
The practical check is to record a harmless decision in one agent, capture it, then ask another agent to find it and cite the source. A plausible answer alone does not prove the bridge worked. The retrieval call and returned reference do.
Word-based search can miss evidence expressed differently. A ranker cannot recover a source that never reached its candidates. Smaller context is therefore something to measure alongside missing evidence, not proof of better answers or lower bills.
04 / Local control and portability
Your files can move with you
The design is portable because the evidence lives in files rather than only inside one agent's session store. A verified backup can carry the vault and bridge to another machine. The search index can be rebuilt from those files.
That does not yet mean a one-click installer that runs everywhere. The walkthrough uses macOS. The bridge uses Python and POSIX file locking, and the scheduled setup uses macOS launchd. Moving it requires checking the runtime, changing local paths and reconnecting the agent sources. Native Windows installation is not covered by this guide.
Local storage also does not mean every later use stays local. Turning on hosted judging sends selected text to that service. Giving retrieved evidence to a cloud-backed agent can send it to the agent's model provider. You choose those connections separately.
Backups deserve a check of their own. The recovery module verifies hashes, restores files into an isolated directory and rebuilds search. It does not restore a complete native agent environment, including credentials and runtime queues.
05 / Installation
Start with one note. Then connect your agents.
The guides begin with a new Obsidian vault and a synthetic note. Next comes Python, the bridge and a local retrieval test. Connect the agents you actually use before adding scheduled capture, optional judging and backups.
You currently need an authorised checkout of obsidian-master. There is no public installer supplied with this source snapshot. The guides make that prerequisite explicit and keep hosted judging disabled during the first checks.
Start with the Obsidian installation guide, or choose the part you need below.
