dsh-obsidian-bridge

Bidirectional knowledge bridge between DeepSeek Harness (DSH) and Obsidian Vault.

What It Does

Gives DSH agents direct read/write access to your Obsidian Vault. The agent can search notes via SQLite FTS5 full-text search, read full content by path or wiki-link, write draft notes back to the vault, and create bidirectional links between DSH sessions and notes.

Unlike existing one-way export tools or MCP-based bridges, this plugin runs natively inside the DSH Cordis framework — no external server, no need for Obsidian to be running.

Status: v0.2.0 — Open Source Alpha

Verified Capabilities

Capability	Status	Test
Read note by file path	Pass	test/spike.mjs
Read note by wiki-link name	Pass	test/spike.mjs
Read note with spaces in name	Pass	test/spike.mjs
SQLite FTS5 full-text search	Pass	test/phase2-spike.mjs
BM25 relevance ranking	Pass	test/phase2-spike.mjs
Chinese text search (CJK tokenization)	Pass	test/phase2-spike.mjs
Incremental sync (mtime-based)	Pass	test/phase2-spike.mjs
500-note search performance	Pass (34ms)	test/spike.mjs
Path traversal protection	Pass	test/spike.mjs
Plugin loads in Cordis context	Pass	test/integration.mjs
Tool registration via defineTool	Pass	test/integration.mjs
Tool execute + render pipeline	Pass	test/integration.mjs
System prompt section injection	Pass	test/integration.mjs
Write draft note to vault	Pass	test/phase1-spike.mjs
Write draft with Unicode title	Pass	test/phase1-spike.mjs
Link session to vault note	Pass	test/phase1-spike.mjs
Link multiple notes to same session	Pass	test/phase1-spike.mjs
Keyword extraction (EN + CN)	Pass	test/phase1-spike.mjs
Auto-context hook (agent/pre-step)	Pass	test/phase1-integration.mjs
Auto-capture hook (tools/result)	Pass	test/phase1-integration.mjs
Auto-capture skips obsidian_* tools	Pass	test/phase1-integration.mjs
Zod config schema validation	Pass	test/phase2-spike.mjs
Plugin config via cordis.patch.yml	Pass	test/phase2-integration.mjs
Env var fallback compatibility	Pass	test/phase2-integration.mjs
Plugin disabled without vault path	Pass	test/phase2-integration.mjs
Hook disposer cleanup	Pass	test/phase2-integration.mjs
Plugin lifecycle cleanup (ctx.effect)	Pass	test/phase2-integration.mjs

Test Results

Phase 0 Spike:        25 passed, 0 failed
Phase 0 Integration:  49 passed, 0 failed
Phase 1 Spike:        35 passed, 0 failed
Phase 1 Integration:  45 passed, 0 failed
Phase 2 Spike:        35 passed, 0 failed
Phase 2 Integration:  23 passed, 0 failed
Total:               212 passed, 0 failed

Architecture

DSH Agent (Node.js process)
  └─ Cordis Framework
       └─ dsh-obsidian-bridge plugin (apply(ctx, config))
            ├─ Config Schema (zod: vaultPath, autoContext, autoCapture, draftFolder, sessionId)
            ├─ System Prompt: "obsidian-vault-aware" (tools + workflow guide)
            ├─ Tool: obsidian_search (FTS5 BM25 search across vault notes)
            ├─ Tool: obsidian_read_note (read full note by path or wiki-link)
            ├─ Tool: obsidian_write_draft (write draft to dsh-drafts/ folder)
            ├─ Tool: obsidian_link_session (bidirectional session-note linking)
            ├─ Hook: agent/pre-step (auto-inject vault context, opt-in)
            ├─ Hook: tools/result (auto-capture tool results, opt-in)
            ├─ ctx.effect() cleanup (closes SQLite, disposes tools/hooks)
            └─ VaultManager (file system access, caching, wiki-link resolution)
                 ├─ NoteIndex (SQLite FTS5 full-text index)
                 │    ├─ Incremental sync (mtime-based, throttled)
                 │    ├─ BM25 relevance ranking
                 │    ├─ Chinese CJK tokenization
                 │    └─ .dsh/index.db (WAL mode, 16MB cache)
                 └─ Obsidian Vault (plain Markdown files on disk)

Single process. No external server. Direct file system access.

Installation

Prerequisites

• Node.js >= 22.19 (or >= 24)
• DSH installed: npm install -g @deepseek-ai/dsh
• An Obsidian Vault directory

Build

cd dsh-obsidian-bridge
npm install
npm run build

Install into DSH

Option A: From GitHub (recommended — no npm account needed)

# Install directly from GitHub
dsh plugin --profile web add github:Daseanle/dsh-obsidian-bridge

# Configure via cordis.patch.yml
dsh web

Option B: From npm (when published)

dsh plugin --profile web add dsh-obsidian-bridge
dsh web

Option C: From local clone

git clone https://github.com/Daseanle/dsh-obsidian-bridge.git
cd dsh-obsidian-bridge && npm install && npm run build
dsh plugin --profile web add file:./dsh-obsidian-bridge
dsh web

Configuration

Create or edit cordis.patch.yml in your DSH config directory:

- id: dsh-obsidian-bridge
  config:
    vaultPath: /path/to/your/vault
    autoContext: false        # auto-inject vault context before each model step
    autoCapture: false        # auto-capture non-Obsidian tool results as drafts
    draftFolder: dsh-drafts   # folder for draft notes
    sessionId: ""             # optional: link drafts to a specific session

Or use environment variables (legacy, used as fallback when config values are not provided):

export OBSIDIAN_VAULT_PATH="/path/to/your/vault"
export DSH_OBSIDIAN_AUTO_CONTEXT=true   # optional
export DSH_OBSIDIAN_AUTO_CAPTURE=true   # optional
export DSH_SESSION_ID="my-session"      # optional

Verify

In the DSH agent, ask it to search your vault:

Search my Obsidian vault for notes about "architecture"

Project Structure

dsh-obsidian-bridge/
├── src/
│   ├── index.ts              # Plugin entry: apply(ctx, config) with zod schema
│   ├── vault-manager.ts      # Core: path resolution, note reading, search, write, link
│   ├── note-index.ts         # SQLite FTS5 full-text index with incremental sync
│   ├── hooks.ts              # Event hooks: auto-context, auto-capture (returns disposer)
│   └── tools/
│       ├── read-note.ts      # obsidian_read_note tool definition
│       ├── search.ts          # obsidian_search tool definition
│       ├── write-draft.ts    # obsidian_write_draft tool definition
│       └── link-session.ts   # obsidian_link_session tool definition
├── dist/                      # Compiled JavaScript (tsc output)
├── test/
│   ├── vault/                 # Test Obsidian Vault (4 sample notes)
│   ├── spike.mjs              # Phase 0 core logic tests (25 tests)
│   ├── integration.mjs        # Phase 0 plugin lifecycle tests (49 tests)
│   ├── phase1-spike.mjs       # Phase 1 write/link tests (35 tests)
│   ├── phase1-integration.mjs # Phase 1 tools+hooks tests (45 tests)
│   ├── phase2-spike.mjs       # Phase 2 FTS5+config tests (35 tests)
│   └── phase2-integration.mjs # Phase 2 config+cleanup tests (23 tests)
├── cordis.patch.yml          # Example plugin configuration
├── package.json
├── tsconfig.json
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
└── .npmignore

Configuration

Config Schema (zod)

Field	Type	Default	Description
vaultPath	string	""	Absolute path to your Obsidian Vault
autoContext	boolean	false	Auto-inject vault context before each model step
autoCapture	boolean	false	Auto-capture non-Obsidian tool results as drafts
draftFolder	string	"dsh-drafts"	Folder name for draft notes
sessionId	string	""	Session ID for draft frontmatter and session linking

Config is validated via zod Standard Schema V1. Values can be provided through cordis.patch.yml or environment variables (as fallback).

Environment Variables

Variable	Fallback For	Default
OBSIDIAN_VAULT_PATH	vaultPath	—
DSH_OBSIDIAN_AUTO_CONTEXT	autoContext	false
DSH_OBSIDIAN_AUTO_CAPTURE	autoCapture	false
DSH_SESSION_ID	sessionId	""

SQLite FTS5 Index

The plugin creates a .dsh/index.db SQLite database inside your vault directory:

• FTS5 virtual table with unicode61 tokenizer
• UNINDEXED columns for metadata (path, frontmatter, mtime, etc.)
• BM25 relevance ranking for search results
• Incremental sync: only re-reads notes whose mtime changed
• Throttled sync: skips re-sync within 2s of last sync (unless invalidated)
• Chinese support: CJK characters are split for unicode61 tokenization
• WAL mode with 16MB cache for performance

Roadmap

Phase	Scope	Status
Phase 0 — Spike	read_note + search, in-memory index, path traversal guard	Complete
Phase 1 — Self-use MVP	write_draft + link_session tools, hooks (auto-context, auto-capture)	Complete
Phase 2 — Open Source Alpha	SQLite FTS5, cordis.patch.yml config, npm publish, documentation	Complete

License

MIT