Obsidian for DevOps: ADRs, Runbooks and an AI That Remembers

Executive Summary

• The problem: "Why did we pick Postgres?" usually has an answer, but it sits in a Jira ticket, a Confluence page, a PR thread and someone's memory.
• The fix: one Obsidian vault of plain Markdown notes: one note per decision (ADR), incident and runbook, linked to each other and to the services they touch.
• New in Obsidian 1.14 (October 5): a Kanban view for Bases to track decisions by status, and opening any Markdown file from outside the vault, so runbooks can stay in the repo.
• For AI agents: the vault is a memory your agent can read. An AGENTS.md sets the rules, and the Obsidian CLI gives scripts and agents a supported way in.
• Sync on your terms: Self-hosted LiveSync syncs through your own CouchDB with end-to-end encryption.

I made a 60-second video of this setup on X; this post is the written version with the templates and commands.

Decisions scattered across Jira, Confluence, GitHub, Google Docs, PagerDuty and team chat

Why DevOps teams lose decisions

Ops work produces a lot of small, important records: why a database was chosen, what broke at 3 a.m., which steps actually fixed it, which change was rolled back. Each tool keeps its own slice. Tickets close, chat scrolls away, wiki pages go stale, and the person who knew the answer changes teams.

A vault does not replace those tools. It is the place where the outcome is written down once, in a file you own, with links back to the ticket, the PR and the dashboard.

Set up an ops vault

A vault is just a folder of Markdown files, so it works offline, can live in a git repository and never locks you in. A layout that works for infrastructure teams:

ADRs/          one note per decision
Incidents/     one note per incident, linked to the ADRs and runbooks involved
Runbooks/      short notes that link to the canonical runbooks in git
Services/      one note per service: owners, dashboards, dependencies
Daily/         deploy log and on-call notes
AGENTS.md      rules for AI agents working in the vault
Decisions.base a Bases view over every ADR

Give every ADR the same front matter so Bases can filter and group it:

---
type: adr
status: accepted        # proposed | accepted | superseded
date: 2026-03-03
service: "[[postgres]]"
supersedes: "[[ADR-004 MongoDB]]"
---
# ADR-007: Use Postgres

## Context
We need JSON documents and multi-row transactions in the same store.

## Decision
Postgres 17 for the api and worker services.

## Consequences
- Seen in [[INC-42]]; failover steps in [[DB failover]].

An ADR note opened as plain Markdown, with front matter and links

Track decisions with the Bases Kanban view

Obsidian 1.14 added a Kanban layout to Bases. Group a base by status and every ADR becomes a card in a Proposed, Accepted or Superseded column. According to the Kanban view docs, dragging a card to another column updates the grouped property in that note, so the board and the files never disagree.

A Decisions base in Kanban view: ADR cards grouped by status

Link everything

Links are what turn notes into memory. Link each incident to the services it hit, the decision behind them and the runbook that fixed it. A month later, "INC-42" leads to "postgres", which leads to "ADR-007", in one hop.

A map of linked notes: from incident INC-42 to postgres to ADR-007

Keep runbooks in git, open them in Obsidian

Runbooks belong next to the code they operate on, reviewed in pull requests. Since 1.14, Obsidian can open any Markdown file from outside the vault ("Open file from outside the vault…"), shows up in the operating system's Open with menu, and can be the default app for .md files. On macOS, Quick Look previews Markdown even when Obsidian is closed. Keep the canonical runbook in the repo and link to it from the vault.

Right-click a runbook in the repo, Open With, Obsidian

Log deploys with the Obsidian CLI

Obsidian 1.12 added a command line interface. Turn it on in Settings → General → Command line interface (it needs the 1.12.7+ installer), then append to today's note from a deploy script:

obsidian daily:append content="- api v2.4.1 → prod"
obsidian search query="INC-42"

The help page also says these commands let agentic coding tools test and debug, which makes the CLI a clean way for an AI agent to search the vault.

Give your AI agent the vault as memory

AI coding agents forget everything between sessions. A vault fixes that: start the agent inside the vault folder and it can read the notes before it answers. The open-source obsidian-second-brain project is one example of this pattern for Claude Code and other CLI agents.

Put the rules in an AGENTS.md at the root. These are adapted from my own vault:

# Vault rules for AI agents
Read this file before editing the vault.
Repository runbooks and specs stay canonical: link to them, never copy them.
Mark AI-written summaries `status: unreviewed`. Only a human sets `reviewed`.
Never mark a decision accepted or an incident resolved without a linked source.
Do not store secrets, credentials or personal data.
Ask before bulk moves, deletions, external uploads or sync changes.

An AI agent answers from ADR-007 and saves its answer as unreviewed

Sync through your own server

If the vault holds internal notes, sync it through infrastructure you control. Self-hosted LiveSync is an MIT-licensed community plugin that syncs through CouchDB or S3-compatible storage (with an experimental WebRTC peer-to-peer mode) and supports end-to-end encryption. Two practical notes: it is not compatible with Obsidian Sync, so pick one, and put HTTPS in front of CouchDB so mobile clients can connect. Turn encryption on before the first sync.

Laptop, your own CouchDB server and an on-call phone syncing with end-to-end encryption

Six rules for a DevOps vault

1. One ADR per decision, with the same front matter.
2. Status moves proposed → accepted → superseded; never edit history, supersede it.
3. Link every incident to the ADRs and runbooks involved.
4. Runbooks stay in git; the vault links to them.
5. AI-written notes start as "unreviewed".
6. Encrypt before you sync.

Sources

• Obsidian 1.14 desktop changelog (October 5, 2026)
• Obsidian 1.12 desktop changelog (February 27, 2026)
• Obsidian CLI help and Bases Kanban view help
• Self-hosted LiveSync on GitHub
• obsidian-second-brain on GitHub