Obsidian Integration Setup Guide

This guide walks you through connecting your Obsidian vault to SurfSense for note search and AI-powered insights.

This connector requires direct file system access and only works with self-hosted SurfSense installations.

How it works

The Obsidian connector scans your local Obsidian vault directory and indexes all Markdown files. It preserves your note structure and extracts metadata from YAML frontmatter.

For follow-up indexing runs, the connector uses content hashing to skip unchanged files for faster sync.
Indexing should be configured to run periodically, so updates should appear in your search results within minutes.

What Gets Indexed

Content Type	Description
Markdown Files	All `.md` files in your vault
Frontmatter	YAML metadata (title, tags, aliases, dates)
Wiki Links	Links between notes (`[[note]]`)
Inline Tags	Tags throughout your notes (`#tag`)
Note Content	Full content with intelligent chunking

Binary files and attachments are not indexed by default. Enable "Include Attachments" to index embedded files.

Quick Start (Local Installation)

Navigate to Connectors → Add Connector → Obsidian
Enter your vault path: /Users/yourname/Documents/MyVault
Enter a vault name (e.g., Personal Notes)
Click Connect Obsidian

Find your vault path: In Obsidian, right-click any note → "Reveal in Finder" (macOS) or "Show in Explorer" (Windows).

Periodic Sync

Enable periodic sync to automatically re-index notes when content changes. Available frequencies: Every 5 minutes, 15 minutes, hourly, every 6 hours, daily, or weekly.

Docker Setup

For Docker deployments, you need to mount your Obsidian vault as a volume.

Step 1: Update docker-compose.yml

Add your vault as a volume mount to the SurfSense backend service:

services:
  surfsense:
    # ... other config
    volumes:
      - /path/to/your/obsidian/vault:/app/obsidian_vaults/my-vault:ro

The :ro flag mounts the vault as read-only, which is recommended for security.

Step 2: Configure the Connector

Use the container path (not your local path) when setting up the connector:

Your Local Path	Container Path (use this)
`/Users/john/Documents/MyVault`	`/app/obsidian_vaults/my-vault`
`C:\Users\john\Documents\MyVault`	`/app/obsidian_vaults/my-vault`

Example: Multiple Vaults

volumes:
  - /Users/john/Documents/PersonalNotes:/app/obsidian_vaults/personal:ro
  - /Users/john/Documents/WorkNotes:/app/obsidian_vaults/work:ro

Then create separate connectors for each vault using /app/obsidian_vaults/personal and /app/obsidian_vaults/work.

Connector Configuration

Field	Description	Required
Connector Name	A friendly name to identify this connector	Yes
Vault Path	Absolute path to your vault (container path for Docker)	Yes
Vault Name	Display name for your vault in search results	Yes
Exclude Folders	Comma-separated folder names to skip	No
Include Attachments	Index embedded files (images, PDFs)	No

Recommended Exclusions

Common folders to exclude from indexing:

Folder	Reason
`.obsidian`	Obsidian config files (always exclude)
`.trash`	Obsidian's trash folder
`templates`	Template files you don't want searchable
`daily-notes`	If you want to exclude daily notes
`attachments`	If not using "Include Attachments"

Default exclusions: .obsidian,.trash

Troubleshooting

Vault not found / Permission denied

Verify the path exists and is accessible
For Docker: ensure the volume is mounted correctly in docker-compose.yml
Check file permissions: SurfSense needs read access to the vault directory

No notes indexed

Ensure your vault contains .md files
Check that notes aren't in excluded folders
Verify the path points to the vault root (contains .obsidian folder)

Changes not appearing

Wait for the next sync cycle, or manually trigger re-indexing
For Docker: restart the container if you modified volume mounts

Docker: "path not found" error

Use the container path (/app/obsidian_vaults/...), not your local path
Verify the volume mount in docker-compose.yml matches

Obsidian

On this page