# mcp-obsidian-vault
**Turn your Obsidian vault into an AI command center.**
[](https://www.npmjs.com/package/mcp-obsidian-vault)
[](https://github.com/t-rhex/obsidian-mcp-server/actions)
[](https://nodejs.org)
[](LICENSE)
An MCP server that gives AI agents direct filesystem access to your Obsidian vault — no Obsidian running required. Manage notes, orchestrate multi-agent task workflows, persist context across sessions, and sync everything with git.
[Quick Start](#quick-start) • [Tools](#tools-27) • [Task Orchestration](#task-orchestration) • [Configuration](#configuration)
---
## Why This Exists
Every time you start a new AI chat session, your agent forgets everything. Decisions made, bugs discovered, tasks in progress — all gone.
**mcp-obsidian-vault** solves this by making your Obsidian vault the single source of truth for AI development work:
- **Notes** are your knowledge base — searchable, linked, tagged
- **Tasks** are your work queue — agents claim, track, and complete them
- **Projects** orchestrate multi-agent parallel work with dependency graphs
- **Decisions & Discoveries** persist the *why* so future sessions don't repeat mistakes
- **Context briefings** give any new session a full situation report in one call
```
npx mcp-obsidian-vault
```
---
## How It Works
```mermaid
graph TB
subgraph Clients["AI Clients"]
CC[Claude Code]
OC[opencode]
CX[Codex CLI]
end
subgraph MCP["mcp-obsidian-vault"]
direction TB
NT["Note Tools
read, create, update, delete
search, tags, wikilinks, daily"]
TT["Task Tools
create, claim, update, complete
projects, dashboard"]
CT["Context Tools
get_context, log_decision
log_discovery"]
GS["Git Sync
commit, pull, push
auto-sync on write"]
end
subgraph Vault["Obsidian Vault (filesystem)"]
direction TB
Notes["Notes/"]
Tasks["Tasks/
DASHBOARD.md"]
Dec["Decisions/"]
Disc["Discoveries/"]
end
subgraph Remote["Remote"]
GH["GitHub / GitLab"]
Phone["Phone
Obsidian Git plugin"]
end
CC & OC & CX -->|MCP Protocol| MCP
NT --> Notes
TT --> Tasks
CT --> Dec & Disc
GS -->|auto-push| GH
GH -->|pull| Phone
style MCP fill:#1a1a2e,stroke:#e94560,color:#fff
style Vault fill:#16213e,stroke:#0f3460,color:#fff
style Clients fill:#0f3460,stroke:#533483,color:#fff
style Remote fill:#1a1a2e,stroke:#533483,color:#fff
```
---
## Features
### Vault Management
| Feature | Description |
|---------|-------------|
| **CRUD Notes** | Read, create, update, delete with full YAML frontmatter support |
| **Wikilinks** | Resolve `[[links]]`, find backlinks, outlinks, and broken links |
| **Full-Text Search** | Regex-capable search with folder filtering and timeout protection |
| **Tag Management** | Add, remove, list tags with automatic deduplication |
| **Daily Notes** | Get, create, append by date — `today`, `yesterday`, `2025-03-08` |
| **Vault Browsing** | Recursive directory listing with depth control |
### Task Orchestration
| Feature | Description |
|---------|-------------|
| **Agent Task Queue** | Structured tasks with priority, type, scope, and deadlines |
| **Atomic Claims** | Race-condition-safe task claiming for multi-agent setups |
| **Dependency Graphs** | Tasks block/unblock automatically based on `depends_on` |
| **Project Management** | Create projects with sub-tasks, track rollup progress |
| **Append Mode** | Add new sub-tasks to existing projects with `project_id` |
| **Conditional Workflows** | Routing rules: branch task execution based on output (v0.3) |
| **Auto Dashboard** | `DASHBOARD.md` regenerated after every mutation |
### Human-in-the-Loop (v0.3)
| Feature | Description |
|---------|-------------|
| **Review Gates** | Tasks with `review_required` redirect to `needs_review` on completion |
| **Approve / Reject** | `review_task` tool for humans/agents to approve, reject, or request changes |
| **Feedback Loop** | Rejected tasks enter `revision_requested` → agents revise → resubmit |
| **Risk Levels** | Tag tasks as `low` / `medium` / `high` / `critical` risk |
### Agent Management (v0.3)
| Feature | Description |
|---------|-------------|
| **Agent Registry** | Register agents with capabilities, tags, and model info |
| **Capability Routing** | `suggest_assignee` recommends the best agent for a task |
| **Timeout Detection** | `check_timeouts` scans for overdue tasks with auto-retry and escalation |
| **Usage Tracking** | Record and aggregate token usage and cost per agent/task/project |
| **Webhook Events** | Fire HTTP POST notifications on task lifecycle events |
### Context Persistence
| Feature | Description |
|---------|-------------|
| **Session Briefings** | `get_context` returns full situation report for new sessions |
| **Decision Records** | Log architectural decisions with rationale and alternatives |
| **Discovery Notes** | Capture gotchas, TILs, and patterns for future agents |
| **Project Filtering** | Scope context briefings to a specific project |
### Git Sync
| Feature | Description |
|---------|-------------|
| **Auto-Sync** | Commit + push after every write (debounced) |
| **Manual Control** | commit, pull, push, sync, diff, log, init, remote management |
| **Cross-Device** | Laptop-to-phone sync via Obsidian Git plugin |
---
## Quick Start
### 1. Install
Pick your MCP client and add the config:
Claude Code
```bash
claude mcp add obsidian -- npx -y mcp-obsidian-vault
```
Then set your vault path:
```bash
claude mcp add obsidian \
-e OBSIDIAN_VAULT_PATH=/path/to/your/vault \
-e GIT_AUTO_SYNC=true \
-- npx -y mcp-obsidian-vault
```
Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["-y", "mcp-obsidian-vault"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
}
}
}
}
```
opencode
Add to `~/.config/opencode/opencode.json` (opencode has no `env` field — use `sh -c`):
```json
{
"mcp": {
"obsidian": {
"type": "local",
"command": [
"sh", "-c",
"OBSIDIAN_VAULT_PATH=/path/to/your/vault GIT_AUTO_SYNC=true npx -y mcp-obsidian-vault"
],
"enabled": true
}
}
}
```
Codex CLI
```toml
[mcp_servers.obsidian]
command = "npx"
args = ["-y", "mcp-obsidian-vault"]
[mcp_servers.obsidian.env]
OBSIDIAN_VAULT_PATH = "/path/to/your/vault"
GIT_AUTO_SYNC = "true"
```
From source
```bash
git clone https://github.com/t-rhex/obsidian-mcp-server.git
cd obsidian-mcp-server
npm install && npm run build
OBSIDIAN_VAULT_PATH=/path/to/vault node build/index.js
```
### 2. Try It
Once configured, open a chat with your AI agent and try these:
```
"Read my Projects/roadmap note"
```
```
"Search my vault for anything about authentication"
```
```
"Create a task to refactor the auth module, high priority"
```
```
"What's the current context? Call get_context."
```
That's it. The agent now has full access to your vault through 27 MCP tools. Keep reading for real-world workflows.
### 3. Real-World Workflows
#### Scaffold a new project
Tell your agent what you want to build. It handles the rest:
```
"I need to build a REST API for user management. Set up a project with tasks for:
1. Design the database schema (research)
2. Set up Express with TypeScript (code)
3. Implement CRUD endpoints (code, depends on 1 and 2)
4. Add JWT authentication (code, depends on 3)
5. Write integration tests (code, depends on 4)
6. Write API documentation (writing)"
```
The agent calls `create_project` and your vault now has:
```
Tasks/
├── DASHBOARD.md # auto-generated summary
└── user-management-api/ # project subfolder
├── proj-2026-03-09-a1b2c3-user-management-api.md # project note
├── task-2026-03-09-d4e5f6-design-database-schema.md # pending (no deps)
├── task-2026-03-09-g7h8i9-set-up-express.md # pending (no deps)
├── task-2026-03-09-j0k1l2-implement-crud.md # blocked (waits on 1, 2)
├── task-2026-03-09-m3n4o5-add-jwt-auth.md # blocked (waits on 3)
├── task-2026-03-09-p6q7r8-write-tests.md # blocked (waits on 4)
└── task-2026-03-09-s9t0u1-write-api-docs.md # pending (no deps)
```
Each task file has structured frontmatter (status, priority, dependencies, scope) and sections for description, acceptance criteria, and an agent log. The dashboard shows what's claimable, what's blocked, and overall progress.
From here, the agent (or multiple agents) can claim tasks, work them, and mark them done. Blocked tasks auto-unblock as their dependencies complete.
```
"Claim the database schema task and start working on it."
```
```
"What's the project status?"
→ 1/6 complete (17%), 2 in progress, 3 blocked
```
#### Save context before ending a session
When you're wrapping up a session, tell your agent:
```
"Log a decision: we chose Zod over Joi for validation because of TypeScript inference."
```
```
"Log a discovery: the Stripe webhook endpoint requires idempotency keys or charges double."
```
These get saved as structured notes in `Decisions/` and `Discoveries/`. The next session picks them up automatically.
#### Pick up where you left off
Start any new session with:
```
"Call get_context to see what's in progress."
```
The agent gets back: active projects, in-progress tasks, blockers, recent decisions, recent discoveries, and pending work. No manual briefing needed.
#### Grow a project mid-flight
Requirements change. Append new tasks to an existing project without recreating it:
```
"Add these tasks to the User Management API project:
- Add rate limiting middleware (code)
- Add password reset flow (code, depends on JWT auth)
- Security audit (research, depends on rate limiting and password reset)"
```
New tasks slot into the existing dependency graph. The dashboard updates automatically.
#### Multi-session continuity
```
Session 1: "Create a task to fix the memory leak in the worker pool"
→ agent claims it, investigates, logs progress, runs out of context
Session 2: "Call get_context"
→ sees the in-progress task, picks up from the agent log
→ completes the fix, marks task done
Session 3: "Call get_context"
→ sees the completed task, continues to next priority
```
#### Daily notes as a work journal
```
"Append to today's daily note: deployed v2.1 to staging, waiting on QA"
```
```
"What did I log yesterday?"
```
---
## Tools (27)
### Note Tools
read_note — Read a note's content, frontmatter, tags, and metadata
```
path: "Projects/my-note.md" # .md added automatically if missing
includeRaw: false # include unparsed content
```
create_note — Create a note with optional YAML frontmatter (parent folders auto-created)
```
path: "Projects/new-idea"
content: "# My Idea\n\nSome content here."
frontmatter: { "tags": ["idea", "project"], "status": "draft" }
overwrite: false # fails if note exists (default)
```
update_note — Replace, append, or prepend content; merge frontmatter
```
path: "Projects/my-note"
content: "## New Section\n\nAdded content."
mode: "append" # "replace" | "append" | "prepend"
frontmatter: { "status": "in-progress" }
```
delete_note — Delete a note (moves to .trash/ by default)
```
path: "Projects/old-note"
permanent: false # true for hard delete
```
search_vault — Full-text search with regex support
```
query: "meeting notes"
regex: false
caseSensitive: false
folder: "Projects" # limit to subfolder
maxResults: 20
```
list_vault — Browse vault file and folder structure
```
path: "Projects" # defaults to vault root
recursive: true
maxDepth: 5
notesOnly: false # true to filter to .md files only
```
manage_tags — Read, add, or remove frontmatter tags
```
path: "Projects/my-note"
action: "add" # "list" | "add" | "remove"
tags: ["important", "review"]
```
daily_note — Get, create, or append to daily notes
```
action: "append" # "get" | "create" | "append"
date: "today" # "today" | "yesterday" | "tomorrow" | "2025-03-08"
content: "- Met with team about roadmap"
```
wikilinks — Navigate [[wikilinks]]: resolve, backlinks, outlinks, unresolved
```
action: "backlinks" # "resolve" | "backlinks" | "outlinks" | "unresolved"
path: "Projects/my-note"
```
| Action | Description |
|--------|-------------|
| `resolve` | Find the file a `[[wikilink]]` points to |
| `backlinks` | Find all notes that link TO a given note |
| `outlinks` | List all `[[wikilinks]]` FROM a note |
| `unresolved` | Find all broken `[[wikilinks]]` across the vault |
git_sync — Git version control: commit, pull, push, sync, diff, log, init
```
action: "sync" # full pull + commit + push
message: "update notes" # optional commit message
```
| Action | Description |
|--------|-------------|
| `status` | Working tree status |
| `commit` | Stage all + commit |
| `pull` | Pull from remote (rebase by default) |
| `push` | Push to remote |
| `sync` | Pull + commit + push in one call |
| `log` | Recent commit history |
| `diff` | Uncommitted changes |
| `init` | Initialize git repo with `.gitignore` |
| `remote_add` | Add a git remote |
| `remote_list` | List configured remotes |
### Task Tools
create_task — Create a task in the agent work queue
```
title: "Implement auth module"
description: "Build JWT-based authentication for the API."
priority: "high" # "critical" | "high" | "medium" | "low"
type: "code" # "code" | "research" | "writing" | "maintenance" | "other"
depends_on: ["task-abc-123"] # task IDs that must complete first
scope: ["src/auth.ts"] # advisory: files this task modifies
acceptance_criteria: ["Tests pass", "Docs written"]
timeout_minutes: 120
```
list_tasks — Query tasks by status, priority, type, tags, or assignee
```
status: "pending" # or "all"
priority: "high" # or "all"
type: "code" # or "all"
tags: ["auth"] # filter by tags
assignee: "claude-code-1"
unassigned_only: true
project: "proj-..." # filter by project
```
claim_task — Atomically claim a task (race-condition safe)
```
task_id: "task-2026-03-09-abc123"
assignee: "claude-code-1"
worktree_branch: "worktree-auth-api" # optional — for parallel multi-agent work
worktree_path: "/repo/.claude/worktrees/auth-api" # optional
```
Blocks if dependencies aren't met. Two agents claiming the same task → second gets `TASK_ALREADY_CLAIMED`. Worktree fields are optional — pass them when using git worktrees for parallel development.
update_task — Update status, priority, or append to Agent Log
```
task_id: "task-2026-03-09-abc123"
status: "in_progress"
log_entry: "Found root cause — null check missing in auth middleware."
```
complete_task — Mark done/failed/cancelled with summary and deliverables
```
task_id: "task-2026-03-09-abc123"
summary: "Auth module implemented with JWT support."
deliverables: ["src/auth.ts", "https://github.com/org/repo/pull/42"]
status: "completed" # "completed" | "failed" | "cancelled"
```
Completing a task auto-unblocks dependent tasks (`blocked` → `pending`).
create_project — Create a project with sub-tasks and dependency graph
**New project:**
```
title: "Auth Rewrite"
description: "Rewrite authentication to use JWT tokens."
tasks: [
{ title: "Design API schema", type: "research" },
{ title: "Implement JWT", type: "code", depends_on_indices: [0] },
{ title: "Write tests", type: "code", depends_on_indices: [1] },
{ title: "Update docs", type: "writing" }
]
```
**Append to existing project:**
```
project_id: "proj-2026-03-09-abc123"
tasks: [
{ title: "Add rate limiting", type: "code" },
{ title: "Security audit", depends_on_existing: ["task-..."] }
]
```
get_project_status — Rollup progress, active agents, blockers
```
project_id: "proj-2026-03-09-abc123"
```
Returns progress percentage, status breakdown, active agents, overdue tasks, and blockers.
### Context Tools
get_context — Full situation briefing for new sessions
```
project_id: "proj-..." # optional: focus on one project
hours: 48 # lookback window (default: 48)
include_completed: true
```
Returns: active projects, in-progress work, pending tasks, blockers, failures, overdue tasks, recent decisions, recent discoveries, pinned notes.
log_decision — Record architectural decisions with rationale
```
title: "Use JWT over session tokens"
context: "Need stateless auth for microservices."
decision: "JWT with RS256, 15min access tokens, refresh rotation."
alternatives: ["Session tokens with Redis", "API keys"]
consequences: ["Stateless (good)", "Revocation needs deny-list (tradeoff)"]
```
log_discovery — Capture gotchas, TILs, and patterns
```
title: "gray-matter crashes on undefined values"
discovery: "js-yaml throws when serializing undefined. Strip before serialize."
impact: "high"
recommendation: "Filter with Object.entries().filter() first."
category: "bug"
```
### Review & HITL Tools
review_task — Approve, reject, or request changes on tasks in review
```
task_id: "task-2026-03-09-abc123"
action: "approve" # "approve" | "reject" | "request_changes"
reviewer: "human-alice"
feedback: "Looks good, ship it." # required for reject/request_changes
```
On approve, the task moves to `completed` and dependents are unblocked. On reject/request_changes, the task moves to `revision_requested` for the assignee to revise and resubmit.
### Agent Tools
register_agent — Register an agent with capabilities and metadata
```
agent_id: "claude-code-1"
capabilities: ["code", "research", "writing"]
tags: ["auth", "backend"]
model: "claude-sonnet-4"
max_concurrent: 3
```
Creates/updates an agent profile in the `Agents/` folder. Agents are tracked with status (`active`, `idle`, `offline`) and heartbeat timestamps.
list_agents — Query registered agents with filters
```
capability: "code" # filter by capability
tag: "auth" # filter by tag
status: "active" # "active" | "idle" | "offline"
available_only: true # only agents below max_concurrent
```
suggest_assignee — Get capability-based agent recommendations for a task
```
task_id: "task-2026-03-09-abc123"
```
Returns a ranked list of agents sorted by capability match, tag overlap, and current workload.
check_timeouts — Scan for overdue tasks, apply retry and escalation
```
dry_run: false # true for preview without changes
```
Scans all claimed/in_progress tasks for `timeout_minutes` violations. For overdue tasks:
- If `retry_count < max_retries`: resets to `pending` for retry
- If retries exhausted + `escalate_to` set: marks as escalated
- Returns list of all actions taken
### Usage Tracking Tools
log_usage — Record token usage and cost for an interaction
```
agent_id: "claude-code-1"
task_id: "task-abc-123" # optional
input_tokens: 15000
output_tokens: 3000
model: "claude-sonnet-4"
cost_usd: 0.042
duration_seconds: 30
notes: "Implemented auth module"
```
get_usage_report — Aggregate usage stats with filters and grouping
```
agent_id: "claude-code-1" # optional filter
project_id: "proj-..." # optional filter
task_id: "task-..." # optional filter
from_date: "2026-03-01" # optional
to_date: "2026-03-09" # optional
```
Returns: `total_input_tokens`, `total_output_tokens`, `total_cost_usd`, `record_count`, grouped by agent and model.
---
## Task Orchestration
### Single Agent Workflow
```mermaid
sequenceDiagram
participant H as Human
participant A as Agent
participant V as Vault
H->>V: create_task("Fix login bug")
A->>V: list_tasks(status: "pending")
V-->>A: [task-abc: "Fix login bug"]
A->>V: claim_task(task_id, assignee: "agent-1")
A->>V: update_task(status: "in_progress")
A->>V: update_task(log: "Found null check issue")
A->>V: complete_task(summary: "Fixed!", deliverables: [...])
V-->>V: Auto-unblock dependents
V-->>V: Refresh DASHBOARD.md
```
### Multi-Agent Project Workflow
```mermaid
sequenceDiagram
participant H as Human
participant A as Agent A
participant B as Agent B
participant C as Agent C
participant V as Vault
H->>V: create_project("Auth Rewrite", tasks: [...])
Note over V: Tasks created:
1. Design API (pending)
2. Implement JWT (blocked on 1)
3. Write tests (blocked on 2)
4. Update docs (pending)
par Parallel Work
A->>V: claim_task("Design API")
B->>V: claim_task("Update docs")
end
A->>V: complete_task("Design API")
Note over V: "Implement JWT" auto-unblocked
C->>V: claim_task("Implement JWT")
C->>V: complete_task("Implement JWT")
Note over V: "Write tests" auto-unblocked
H->>V: get_project_status(project_id)
V-->>H: 3/4 complete (75%)
```
### Task Dependency Graph
```mermaid
graph LR
A["Design API
research"] --> B["Implement JWT
code"]
B --> C["Write Tests
code"]
D["Update Docs
writing"]
style A fill:#2ecc71,stroke:#27ae60,color:#fff
style B fill:#3498db,stroke:#2980b9,color:#fff
style C fill:#e74c3c,stroke:#c0392b,color:#fff
style D fill:#2ecc71,stroke:#27ae60,color:#fff
```
Green = claimable immediately | Blue = blocked | Red = blocked (2 levels deep)
### Append Mode — Growing Projects
When requirements evolve mid-project, append new tasks to an existing project without recreating it:
```mermaid
graph TB
subgraph Original["Original Project (4 tasks)"]
A1["Design API"] --> A2["Implement JWT"]
A2 --> A3["Write Tests"]
A4["Update Docs"]
end
subgraph Appended["Appended (3 new tasks)"]
B1["Add Rate Limiting"]
B1 --> B2["Security Audit"]
A2 -.->|depends_on_existing| B3["Load Testing"]
end
style Original fill:#1a1a2e,stroke:#0f3460,color:#fff
style Appended fill:#16213e,stroke:#e94560,color:#fff
```
```
create_project(
project_id: "proj-...", // existing project
tasks: [
{ title: "Add Rate Limiting", type: "code" },
{ title: "Security Audit", depends_on_indices: [0] },
{ title: "Load Testing", depends_on_existing: ["task-implement-jwt-id"] }
]
)
```
### Task State Machine
```mermaid
stateDiagram-v2
[*] --> pending: create_task
pending --> claimed: claim_task
pending --> blocked: update_task
pending --> cancelled: update_task
claimed --> in_progress: update_task
claimed --> pending: unclaim
claimed --> blocked: update_task
claimed --> cancelled: update_task
in_progress --> completed: complete_task
in_progress --> needs_review: complete_task (review_required)
in_progress --> failed: complete_task
in_progress --> blocked: update_task
in_progress --> pending: update_task
in_progress --> cancelled: update_task
needs_review --> completed: review_task (approve)
needs_review --> revision_requested: review_task (reject)
revision_requested --> in_progress: update_task
blocked --> pending: auto-unblock / update
blocked --> cancelled: update_task
completed --> pending: reopen
failed --> pending: retry
cancelled --> pending: reactivate
completed --> [*]
```
---
## Multi-Agent Parallel Development
Run multiple AI agents on the same codebase simultaneously, each in its own git worktree, with the vault coordinating who's working on what.
**The architecture:** Git worktrees provide filesystem isolation. The vault provides coordination metadata. No conflicts, no stepping on each other's work.
### How It Works
1. **Claim a task with worktree metadata** — when an agent claims a task, it records the branch and worktree path
2. **Work in isolation** — each agent works in its own directory on its own branch
3. **Vault tracks everything** — `get_context` shows which agents are on which branches, `list_tasks` includes worktree info
4. **Complete and PR** — when done, `complete_task` tells you the branch is ready for a pull request
### With Claude Code (Recommended)
Claude Code v2.1.49+ has native worktree support via `--worktree` (`-w`):
```bash
# Terminal 1: Agent works on auth API
claude --worktree design-api
# → "Claim the 'Design API' task with worktree_branch 'worktree-design-api'"
# Terminal 2: Agent works on documentation
claude --worktree update-docs
# → "Claim the 'Update docs' task with worktree_branch 'worktree-update-docs'"
```
Claude Code creates worktrees at `/.claude/worktrees/` with branch `worktree-`. Each agent works in its own directory, on its own branch.
### With opencode / Codex CLI
Create worktrees manually, then point the agent at the right directory:
```bash
# Create worktrees
git worktree add .worktrees/auth-api -b worktree-auth-api
git worktree add .worktrees/update-docs -b worktree-update-docs
# Start agents in their worktrees
cd .worktrees/auth-api && opencode
# → "Claim task X with worktree_branch 'worktree-auth-api' and worktree_path '$(pwd)'"
```
### What the Vault Tracks
When you claim a task with worktree fields:
```yaml
# Task frontmatter after claim
status: claimed
assignee: claude-code-1
worktree_branch: worktree-auth-api
worktree_path: /repo/.claude/worktrees/auth-api
```
`get_context` includes worktree info for all active work:
```json
{
"active_work": [
{
"id": "task-2026-03-09-abc123",
"title": "Design API endpoints",
"assignee": "claude-code-1",
"worktree_branch": "worktree-design-api",
"worktree_path": "/repo/.claude/worktrees/design-api"
},
{
"id": "task-2026-03-09-def456",
"title": "Update documentation",
"assignee": "claude-code-2",
"worktree_branch": "worktree-update-docs",
"worktree_path": "/repo/.claude/worktrees/update-docs"
}
]
}
```
When a task completes, the response tells you the branch is ready:
```
Task "Design API endpoints" completed. Branch `worktree-design-api` is ready for PR.
```
---
## Context Persistence
The core problem: **AI agents lose all context between sessions.** Decisions, discoveries, and in-flight work vanish.
mcp-obsidian-vault solves this with three tools that build a persistent knowledge layer:
```mermaid
graph TB
subgraph Session1["Session 1"]
S1A["Discovers: gray-matter
crashes on undefined"] --> S1B["log_discovery()"]
S1C["Decides: use RS256
for JWT signing"] --> S1D["log_decision()"]
S1E["Completes 3 tasks,
2 still in progress"]
end
subgraph Vault["Obsidian Vault"]
V1["Discoveries/
gray-matter-crash.md"]
V2["Decisions/
use-rs256-signing.md"]
V3["Tasks/
DASHBOARD.md"]
end
subgraph Session2["Session 2 (new agent, fresh context)"]
S2A["get_context()"] --> S2B["Receives:
- 2 tasks in progress
- RS256 decision
- gray-matter gotcha
- project at 60%"]
S2B --> S2C["Continues work
without repeating
mistakes"]
end
S1B --> V1
S1D --> V2
S1E --> V3
V1 & V2 & V3 --> S2A
style Session1 fill:#1a1a2e,stroke:#e94560,color:#fff
style Vault fill:#16213e,stroke:#0f3460,color:#fff
style Session2 fill:#0f3460,stroke:#533483,color:#fff
```
### Context-First Discipline
Every new session should start with one call:
```
get_context() → {
active_projects: [{ id, title, progress: "3/7 (43%)" }],
in_progress: [{ id, title, assignee, claimed_at }],
pending_work: { "proj-abc": [...], standalone: [...] },
blockers: [{ id, title, waiting_on: [{ id, title }] }],
recent_decisions: [{ title, decision, status }],
recent_discoveries: [{ title, discovery, recommendation }],
pinned_notes: [...]
}
```
---
## Git Sync & Cross-Device Flow
```mermaid
sequenceDiagram
participant L as Laptop
(MCP Server)
participant G as GitHub
(Private Repo)
participant P as Phone
(Obsidian Git)
L->>L: Agent edits note
L->>G: Auto-sync: commit + push
P->>G: Pull on open
G-->>P: Latest notes
P->>P: Edit on the go
P->>G: Commit + push
L->>G: Pull (next auto-sync)
G-->>L: Phone changes merged
```
### Setup
1. **Laptop** — set `GIT_AUTO_SYNC=true` with a private GitHub repo
2. **Phone (iOS)** — [Obsidian Git](https://github.com/Vinzent03/obsidian-git) plugin or [Working Copy](https://workingcopy.app/)
3. **Phone (Android)** — [Obsidian Git](https://github.com/Vinzent03/obsidian-git) plugin (built-in git on Android)
| Obsidian Git Setting | Value | Why |
|---------------------|-------|-----|
| Auto pull on open | Enabled | Get latest when you open the app |
| Auto push after commit | Enabled | Push edits immediately |
| Pull on interval | 5-10 min | Catch changes while app is open |
| Commit message | `mobile: {{date}}` | Distinguish mobile vs MCP commits |
> **Use a private repo.** Your notes are personal.
---
## Task Note Structure
Tasks are markdown notes with structured YAML frontmatter. Project tasks are organized in per-project subfolders, while standalone tasks live at the `Tasks/` root:
```
Tasks/
├── DASHBOARD.md
├── auth-rewrite/ # project subfolder
│ ├── proj-2026-03-09-abc123-auth-rewrite.md
│ ├── task-2026-03-09-def456-design-api.md
│ └── task-2026-03-09-ghi789-implement-jwt.md
├── api-migration/ # another project
│ └── ...
└── task-2026-03-09-mno345-fix-typo.md # standalone task
```
Example task note:
```markdown
---
id: task-2026-03-09-abc123
title: Implement auth module
status: in_progress
priority: high
type: code
assignee: claude-code-1
created: "2026-03-09T14:00:00.000Z"
updated: "2026-03-09T15:45:00.000Z"
depends_on: []
scope:
- src/auth.ts
tags:
- auth
---
## Description
Build JWT-based authentication for the API.
## Acceptance Criteria
- [ ] Tests pass
- [ ] Docs written
## Agent Log
- **[2026-03-09 14:30:00]** Starting implementation. Found 3 endpoints to modify.
- **[2026-03-09 15:45:00] [COMPLETED]** Auth module done with JWT support.
## Deliverables
- src/auth.ts
- src/auth.test.ts
```
A `DASHBOARD.md` is auto-generated after every task mutation with summary counts, active work, pending queue, blockers, and recent completions.
---
## Agent Prompts
Three built-in MCP prompts for different agent personas:
| Prompt | Role | Use When |
|--------|------|----------|
| `task-worker` | Find, claim, complete tasks | Spawning a coding agent |
| `project-manager` | Plan projects, decompose work, monitor | Orchestrating multi-agent work |
| `vault-assistant` | Read, search, organize notes | General vault management |
Request via MCP:
```json
{
"method": "prompts/get",
"params": {
"name": "task-worker",
"arguments": { "agent_id": "claude-1", "project_id": "proj-abc" }
}
}
```
Or copy from [`prompts/`](./prompts) into your agent's system prompt.
---
## Configuration
### Required
| Variable | Description |
|----------|-------------|
| `OBSIDIAN_VAULT_PATH` | Absolute path to your vault |
### Vault
| Variable | Default | Description |
|----------|---------|-------------|
| `DAILY_NOTE_FOLDER` | `Daily Notes` | Subfolder for daily notes |
| `TRASH_ON_DELETE` | `true` | Move to `.trash/` instead of permanent delete |
| `MAX_FILE_SIZE_BYTES` | `10485760` | Max file size (10 MB) |
| `MAX_SEARCH_RESULTS` | `50` | Max search results |
| `SEARCH_TIMEOUT_MS` | `30000` | Search timeout |
| `NOTE_EXTENSIONS` | `.md,.markdown` | Note file extensions |
| `TASKS_FOLDER` | `Tasks` | Task notes subfolder |
| `DECISIONS_FOLDER` | `Decisions` | Decision records subfolder |
| `DISCOVERIES_FOLDER` | `Discoveries` | Discovery notes subfolder |
| `AGENTS_FOLDER` | `Agents` | Agent profile notes subfolder |
| `USAGE_FOLDER` | `Usage` | Token usage records subfolder |
### Git
| Variable | Default | Description |
|----------|---------|-------------|
| `GIT_AUTO_SYNC` | `false` | Auto commit + push after every write |
| `GIT_AUTO_SYNC_DEBOUNCE_MS` | `5000` | Debounce interval |
| `GIT_COMMIT_MESSAGE_PREFIX` | `vault: ` | Auto-commit message prefix |
| `GIT_REMOTE` | `origin` | Default remote |
| `GIT_BRANCH` | `main` | Default branch |
| `GIT_TIMEOUT_MS` | `30000` | Git operation timeout |
| `GIT_PULL_REBASE` | `true` | Use `--rebase` on pull |
### Webhooks
| Variable | Default | Description |
|----------|---------|-------------|
| `WEBHOOK_URL` | — | Comma-separated webhook URLs for task event notifications |
| `WEBHOOK_SECRET` | — | HMAC-SHA256 secret for signing webhook payloads |
| `WEBHOOK_TIMEOUT_MS` | `5000` | Webhook HTTP request timeout |
---
## Security
- **Path traversal prevention** — all paths validated against vault root, including symlink resolution
- **No shell injection** — git commands use `execFile` (not `exec`)
- **Atomic writes** — temp file + rename prevents partial writes on crash
- **Overwrite protection** — `create_note` fails if note exists unless explicitly overridden
- **Trash safety** — unique filenames prevent collision in `.trash/`
- **File size limits** — configurable cap prevents reading huge files
- **Search timeout** — prevents runaway searches
- **Git mutex** — prevents concurrent git commands from conflicting
---
## Robustness
- **Retry failed tasks** — `update_task(status: "pending")` clears assignee, increments `retry_count`
- **Unclaim stuck tasks** — reclaim tasks from crashed agents
- **Timeout detection** — `list_tasks` flags tasks past `timeout_minutes` with `is_overdue: true`
- **Dependency validation** — warns on nonexistent `depends_on` references
- **Dashboard health** — all mutation responses include `dashboard_refreshed` status
### Known Limitations
- **No file locking** — claims are atomic within a single server process (Node event loop). Multiple server processes sharing a vault need external coordination.
- **Scope is advisory** — `scope[]` is not enforced by the server. Agents should respect it.
- **Timeouts need `check_timeouts`** — overdue tasks are detected but not auto-released; an agent or cron must call `check_timeouts` periodically.
- **Webhooks are fire-and-forget** — webhook delivery is best-effort with one retry. No persistent queue.
---
## Project Structure
```
src/
├── index.ts # MCP server entry, 27 tools + 3 prompts
├── config.ts # Environment variable parsing
├── errors.ts # Typed errors + safe handler wrapper
├── vault.ts # Filesystem: path safety, atomic writes, list, search
├── frontmatter.ts # YAML parse/serialize, tag extraction
├── git.ts # Git CLI wrapper with mutex
├── events.ts # EventBus with typed task lifecycle events
├── webhooks.ts # WebhookEmitter with HMAC-SHA256 signing
├── agent-registry.ts # Agent profiles, scanning, capability matching
├── task-schema.ts # Task types, IDs, validation, state machine
├── task-dashboard.ts # Task scanning + DASHBOARD.md generation
├── prompts.ts # MCP prompt registration
└── tools/ # One file per tool (27 files)
prompts/ # Agent persona prompts (ship with npm)
skills/ # Agent skills (ship with npm, skills.sh compatible)
test/run.mjs # 342 integration tests
```
---
## Development
```bash
npm install
npm run build # TypeScript → build/
npm test # 342 integration tests
npm run dev # tsc --watch
```
---
## License
MIT