Obsidian Vault as the Core of Your Agent Harness

The Stack

Tested Against

Prerequisites

• macOS: `brew install coreutils git`, the linter is POSIX so BSD tools also work; Linux ships GNU coreutils already
• Obsidian 1.7.x, https://obsidian.md/download
• obsidian-cli: `npm i -g obsidian-cli@1` (optional, for richer search)
• Claude Code: `npm i -g @anthropic-ai/claude-code`, pin model `claude-sonnet-4.6` for the agent step
• git ≥ 2.30 for the commit/review loop

Steps

1. 1

   Check you have the right tools

   Before anything else, confirm the programs this recipe needs are actually installed, a missing tool is the most common reason a copy-pasted workflow breaks on someone else's machine. This stops with a clear message if a core tool is missing, and only warns about the agent-only ones (so the setup still runs anywhere). It also prints your OS so you know what you ran on.

   for bin in bash sed grep sort tr paste git; do
     command -v "$bin" >/dev/null 2>&1 || { echo "MISSING required: $bin"; exit 1; }
   done
   for bin in obsidian-cli claude; do
     command -v "$bin" >/dev/null 2>&1 || echo "optional (install before the agent step): $bin"
   done
   echo "preflight OK on $(uname -s)"

2. 2

   Set up the vault and a sample note

   Build the folder layout your agent reads on every run, memory, tasks, skills, an Inbox for raw captures, and a prompts folder, then drop in one deliberately messy note to work on. Safe to run again: it resets the sample vault, so a second run is identical to the first.

   rm -rf vault
   mkdir -p vault/memory vault/tasks vault/skills vault/Inbox vault/prompts
   cat > vault/Inbox/capture.md <<'EOF'
   ---
   title:   messy capture
   tags: RAG, Agents,RAG, agents
   ---
   A quick thought about retrieval augmented generation.
   EOF
   find vault -type d | sort

3. 3

   Save the agent's prompt and model

   Write the agent's instructions and the exact model it should use into a file in the vault, so every run starts from the same brief instead of whatever you happen to type that day. This is what turns the AI step from a one-off into something repeatable.

   cat > vault/prompts/guardian.md <<'EOF'
   # Knowledge Guardian, model: claude-sonnet-4.6 (pin the exact model)
   Review today's captures in Inbox/. For each note:
   1. Standardize frontmatter (lowercase, dedupe, sort tags).
   2. Add [[wikilinks]] by semantic similarity to existing notes.
   3. Append a one-line summary to the daily note.
   4. Flag notes untouched >30 days as #stale.
   Then: git add -A && git commit -m "guardian: $(date +%F)".
   EOF
   echo "prompt pinned: $(wc -l < vault/prompts/guardian.md) lines"

4. 4

   Clean up the note's tags automatically

   Standardize the messy frontmatter, lowercase, de-duplicate and sort the tags, using only portable shell tools that behave the same on Mac and Linux. The result is checked against a known-good file so you can confirm an exact match, not just eyeball it.

   RAW=$(sed -n 's/^tags:[[:space:]]*//p' vault/Inbox/capture.md)
   TAGS=$(printf '%s' "$RAW" | tr ',' '\n' | tr 'A-Z' 'a-z' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | sort -u | paste -sd, -)
   printf 'agents,rag\n' > vault/expected-tags.txt
   printf '%s\n' "$TAGS" > vault/actual-tags.txt
   if diff -q vault/expected-tags.txt vault/actual-tags.txt >/dev/null; then
     echo "normalized tags: $TAGS (MATCH golden)"
   else
     echo "MISMATCH"; exit 1
   fi

5. 5

   Find related notes, like the agent does

   Locate the notes relevant to a topic the same way the agent does before it links them together, a simple recursive search across the vault.

   grep -rl "retrieval" vault | sed 's#.*/##' | sort -u

6. 6

   Hand the vault to your agent (the AI step, not checked by CI)

   Now run the saved prompt: `claude --model claude-sonnet-4.6 -f vault/prompts/guardian.md`. It links related notes together, writes a daily summary, flags stale notes, and commits the result. This step uses judgement and needs an API key, so CI doesn't run it, the verified badge covers only the repeatable setup above, and this step's proof is the saved transcript.