DocVault: Obsidian as a
Knowledge Base for AI

CLAUDE.md is great for instructions, but it's a single flat file. As your projects grow, you need architecture docs, infrastructure maps, decision records, daily digests, and issue tracking. That's a knowledge base problem.

Obsidian is a perfect fit because it stores everything as plain markdown files in a git repo. Claude Code can read, write, and search them with the tools it already has (Read, Write, Grep, Glob). No special API, no vector database, no cloud dependency. Just files.

The key insight: bidirectional wikilinks ([[Page Name]]) create a knowledge graph that Obsidian visualizes and Claude can traverse. When Claude writes a session digest with [[StakTrakr]] and [[Portainer]] in the text, those connections show up in Obsidian's graph view and backlinks panel — making it easy to see how everything relates.

The vault uses a hierarchical index tree. Every folder has an _Index.md that lists its pages with one-line summaries. Claude reads the root INDEX.md first, then follows links into the relevant section.

The _Index.md Pattern

Every content folder has an _Index.md that serves as a table of contents. This is what makes the vault navigable by Claude — it reads the index, finds the relevant page, and reads just that page instead of scanning the whole directory.

---
tags: [index]
updated: 2026-04-04
---

# Projects Index

| Page | Summary |
|------|---------|
| [[StakTrakr]] | Precious metals portfolio tracker with live prices |
| [[HexTrackr]] | Network vulnerability monitoring and device inventory |
| [[Forge]] | Network configuration template generator |
| [[MyMelo]] | AI companion chat app with persistent memory |
| [[WhoseOnFirst]] | Network device first-seen tracking |

Two conventions make the vault machine-readable: YAML frontmatter for metadata and wikilinks for cross-references.

Frontmatter

Every note has a YAML frontmatter block with at minimum tags, created, and updated. This enables Obsidian's Bases feature (structured database queries over your notes) and helps Claude understand when a page was last updated.

---
tags: [infrastructure, docker]
created: 2026-01-15
updated: 2026-04-01
---

# Portainer

Docker container management dashboard running on pve2.
Stack registry, volume inventory, and deployment workflows.

Wikilinks

Use [[Page Name]] syntax for all internal references. Obsidian resolves these by filename (not path), so [[Portainer]] works from any folder. This creates bidirectional links — when you mention [[Portainer]] in a daily digest, Portainer's backlinks panel shows that reference.

# Good — wikilinks connect the knowledge graph
Deployed the poller to [[Portainer]] Stack 7 and [[Fly.io]].
See [[STAK-498]] for the parent issue.

# Bad — plain text creates no connections
Deployed the poller to Portainer Stack 7 and Fly.io.

Not everything belongs in the vault. The key question: "Does it change when the code changes?"

Gray area test: If it partially changes with code, split it. Put the stable overview in the vault and the code-specific details in the repo. For example, a project's architecture overview goes in the vault; its API endpoint list stays in-repo.

Two skills automate vault operations, and the Obsidian CLI enables programmatic access.

/vault-update Workflow

This is a hard gate in the development workflow — vault documentation must be updated and committed before pushing any project PR. The skill:

1. Identifies which vault pages are affected by the code changes
2. Reads the current page content
3. Updates with accurate, current information
4. Maintains _Index.md tables (add/update/remove rows)
5. Updates frontmatter timestamps
6. Commits directly to main (vault uses direct commits, no PRs)
7. Pushes to remote

Obsidian CLI Examples

The Obsidian CLI ships with Obsidian Desktop (v1.12+). It communicates via IPC socket, so Obsidian must be running.

# Set the CLI path
OBS='/Applications/Obsidian.app/Contents/MacOS/obsidian'

# Vault health
$OBS vault="DocVault" orphans total        # Files with no incoming links
$OBS vault="DocVault" unresolved verbose   # Broken wikilinks
$OBS vault="DocVault" deadends total       # Files with no outgoing links

# Search
$OBS vault="DocVault" search query="portainer" format=json limit=10

# Read and write notes
$OBS vault="DocVault" read path="Infrastructure/Portainer.md"
$OBS vault="DocVault" append path="Infrastructure/Portainer.md" \
  content="\n## New Section\nContent here."

# Property management (for issue tracking)
$OBS vault="DocVault" property:set \
  name="status" value="done" \
  path="Projects/StakTrakr/Issues/STAK-498.md"

# Backlinks — what references this page?
$OBS vault="DocVault" backlinks file="Portainer" format=json

# Vault stats
$OBS vault="DocVault" vault   # name, path, files, folders, size

Several pipeline components write to the vault automatically. All generated content must follow the wikilink convention to stay connected in the knowledge graph.

Wikilink Rules for Generated Content

Every piece of auto-generated content must include inline wikilinks and a footer section.

# Inline wikilinks in the prose — first mention only
"lbruton fixed the price scraper bug in [[StakTrakr]].
 The fix was deployed to [[Portainer]] Stack 7. See [[STAK-498]]."

# Footer section at the end
## Related Pages

- [[StakTrakr Overview]] — poller pipeline context
- [[Portainer]] — deployment target
- [[STAK-498]] — parent issue

Obsidian Canvas files (.canvas) store visual flowcharts and architecture diagrams as JSON. Claude can read and write them — they're just nodes with positions, edges with connections.

{
  "nodes": [
    {
      "id": "api",
      "type": "text",
      "text": "## API Server\nExpress + SQLite",
      "x": 0, "y": 0,
      "width": 250, "height": 120
    },
    {
      "id": "poller",
      "type": "text",
      "text": "## Price Poller\nCron + Puppeteer",
      "x": 400, "y": 0,
      "width": 250, "height": 120
    }
  ],
  "edges": [
    {
      "id": "e1",
      "fromNode": "poller", "fromSide": "left",
      "toNode": "api", "toSide": "right",
      "label": "POST /prices"
    }
  ]
}

Canvas files render as interactive diagrams in Obsidian. They're version-controlled in git alongside the markdown. Use them for architecture overviews, data flow diagrams, and system topology maps.

1. Create the vault

mkdir -p ~/DocVault
cd ~/DocVault
git init

2. Create the index tree

# Root index
cat > INDEX.md << 'EOF'
# DocVault

| Section | Description |
|---------|-------------|
| [[Projects Index\|Projects]] | Project documentation |
| [[Infrastructure Index\|Infrastructure]] | Network, servers, services |
| [[Architecture Index\|Architecture]] | Cross-project patterns |
EOF

# Create folders with _Index.md files
for dir in Projects Infrastructure Architecture; do
  mkdir -p "$dir"
  echo -e "---\ntags: [index]\nupdated: $(date +%Y-%m-%d)\n---\n\n# $dir Index\n\n| Page | Summary |\n|------|---------|\n" > "$dir/_Index.md"
done

3. Add a CLAUDE.md

cat > CLAUDE.md << 'EOF'
# DocVault

Central knowledge base. Navigate from INDEX.md.

## Rules
- Use [[wikilinks]] for all internal references
- Every folder has _Index.md — update it when adding/removing pages
- Update frontmatter `updated:` timestamp when editing
- Commit directly to main (no PRs needed)
- No secrets — reference Infisical key names, never paste keys
EOF

4. Open in Obsidian

Open Obsidian, choose "Open folder as vault," and select your DocVault directory. Enable the Graph View core plugin to visualize your wikilink connections.

5. Tell Claude about it

Add a line to your global ~/.claude/CLAUDE.md:

## Knowledge Base
Read ~/DocVault/ for architecture, infrastructure, and design questions.
Start at INDEX.md and follow the index tree.