Obsidian vault as agent memory for Claude Code — hybrid retrieval over plain markdown, no vector database

README.md

Obsidian vault as agent memory for Claude Code — hybrid retrieval over plain markdown, no vector database

Point an MCP server at the folder of markdown you already keep. No Obsidian plugins, no REST API, no OAuth — files on disk.

Last tested: 2026-06-12 — @reneza/ats-adapter-obsidian v0.4, Claude Code via ats-mcp. See Changelog at the bottom.

If this saves you setup time, follow @renezander030 — practical AI / coding-agent infrastructure notes.

Full repo: github.com/renezander030/agentic-task-system

TL;DR cheat sheet

Goal	Use
Obsidian vault in Claude Code	claude mcp add ats -e ATS_ADAPTER=@reneza/ats-adapter-obsidian -e ATS_OBSIDIAN_VAULT="$HOME/Documents/MyVault" -- ats-mcp
Search the vault from the terminal	ats find "<query>" — keyword + title-fuzzy + (optional) dense/sparse, RRF-fused
Deep link back into Obsidian	ats url "<note title>" → obsidian://open?vault=<vault>&file=<path>
Verify the setup	ats doctor
Headless / server use	works — the adapter reads files, not the Obsidian app

Recommended setup (60 seconds)

npm install -g @reneza/ats-cli @reneza/ats-mcp @reneza/ats-adapter-obsidian
export ATS_OBSIDIAN_VAULT="$HOME/Documents/MyVault"
ats config use obsidian
ats doctor                       # verifies vault resolution + retrieval
ats find "deployment runbook"
claude mcp add ats -e ATS_ADAPTER=@reneza/ats-adapter-obsidian -e ATS_OBSIDIAN_VAULT="$HOME/Documents/MyVault" -- ats-mcp

ATS_OBSIDIAN_VAULT_NAME overrides the vault name used in obsidian:// deep links (defaults to the folder name).

How the vault maps to the adapter contract

ATS concept	Obsidian
project	a folder of notes (vault root = .)
task / note	a .md file
id	vault-relative path without .md, e.g. Projects/Runbook
urlFor	obsidian://open?vault=<vault>&file=<path>
tags	frontmatter tags: + inline #tags
title	frontmatter title: if set, else filename

Frontmatter is parsed for tags, due, optional title and modified; everything else is left untouched. Writes round-trip without lossy re-encoding — the adapter is contract-tested (ats adapter test).

Why not the existing Obsidian MCP servers?

• Most popular Obsidian MCP servers drive the running Obsidian app through a plugin (Local REST API or similar). That means Obsidian must be open, and nothing works headless or on a server.
• This adapter treats the vault as what it is — files on disk. Works in CI, on a VPS, in a cron. Your vault stays plain markdown; Obsidian never knows.
• And it's not CRUD-only: retrieval is the point. Keyword + title-fuzzy + optional dense/sparse embeddings, fused with Reciprocal Rank Fusion, every hit tagged with which branch found it.

If you want Templater integration or the app's UI features, the plugin-based servers are the right tool. For agent memory, files win.

Retrieval pipeline

ats find "<query>"
   ├── hybrid   (dense + sparse via qdrant, optional)
   ├── keyword  (substring scan over the corpus cache)
   └── notes_find (title-fuzzy)
        ↓
   RRF fusion: score(doc) = Σ 1/(60 + rank_in_branch)
        ↓
   top-K with sources: [...] provenance

No vector database required — without qdrant you still get keyword + title-fuzzy + RRF. Add the optional local stack (qdrant + ollama + nomic-embed-text, all Docker) only if you want the semantic branch.

Smoke test

ATS_OBSIDIAN_VAULT=/path/to/vault ats adapter test   # contract conformance: pass/fail/skip
ats find "a topic you have notes on" --json | jq '.tasks[] | {title, sources}'
ats url "<a real note title>"                        # clickable obsidian:// link

Passes if adapter test is green, find returns hits with a sources array, and the obsidian:// link opens the right note.

Setups I would avoid

• Pointing it at a vault with secrets before checking what your MCP client logs. The agent can read anything in the vault — scope with a sub-folder vault if needed.
• Symlinked vaults on iCloud — file timestamps lie, which confuses modified-based freshness.
• Expecting Dataview queries to work — this reads markdown, not Obsidian plugin state.

Series

Companion to Production AI Automation Notes #3: Claude Code persistent memory between sessions — the TickTick side, bench numbers, agent-data note pattern. TickTick MCP setup: gist · Series #1: Agent Approval Gates.

Sources

• Adapter source + contract: https://github.com/renezander030/agentic-task-system (packages/adapter-obsidian, docs/adapter-interface.md)
• Obsidian URI scheme: https://help.obsidian.md/Concepts/Obsidian+URI

Comment with your setup

Vault size (note count), whether you run the semantic branch, your retrieval winner (ats bench score), and any vault layout that broke the folder→project mapping.

Changelog

2026-06-12

• Initial publication. Deliberate skips: no hardware matrix (not hardware-bound); no new companion repo (agentic-task-system already exists).