Obsidian PKM Plugin

Give Claude persistent, structured memory across conversations using your Obsidian vault. Read, write, search, and navigate your knowledge base — all from within Claude Code.

Under the hood, this Claude Code plugin provides 20 MCP (Model Context Protocol) tools for note creation, semantic search, graph traversal, metadata queries, and session memory — plus agents, hooks, and skills for seamless workflow integration. Published on npm as obsidian-pkm.

If you find this useful, please star the repo — it helps others discover the plugin.

Watch the demo video

Why

Claude Code has built-in memory, but it's flat text files scoped to individual projects — no structure, no search beyond exact matches, no connections between notes, and no way to query across projects. As knowledge grows, it doesn't scale. This server replaces that with a proper PKM layer: structured notes with enforced metadata, semantic search, a navigable knowledge graph, and cross-project access through a single Obsidian vault.

Structured session memory — Every tool call is logged with timestamps and session IDs, so Claude can recall exactly what was read, written, and searched in previous conversations — not just what was saved to a text file.
Structured knowledge creation — ADRs, research notes, devlogs, and tasks are created from enforced templates with validated frontmatter — not freeform text dumps. Your vault stays consistent and queryable.
Semantic discovery — "Find my notes about caching strategies" works even if you never used the word "caching." Conceptual search surfaces relevant knowledge that keyword search misses.
Graph-aware connections — Claude explores your knowledge graph by following wikilinks, discovering related notes by proximity rather than just content. Link suggestions help weave new notes into your existing web of knowledge.
Knowledge capture — Decisions, tasks, and research findings are captured by specialized agents in the background without interrupting your coding flow.

Without this, knowledge stays fragmented across per-project memory files and chat logs. With it, your AI assistant maintains a unified knowledge base that compounds over time.

How It Compares

| | obsidian-pkm | remember | Claude built-in memory | |---|---|---|---| | Knowledge base | Your Obsidian vault (markdown files you own) | Compressed conversation logs (.remember/ dir) | CLAUDE.md + auto-memory files | | Scope | Cross-project (one vault for everything) | Per-project | Per-project (git-repo scoped) | | Semantic search | OpenAI embeddings | — | — | | Graph traversal | Wikilink BFS, link health audits | — | — | | Structured notes | 13 templates with validated frontmatter | Plain markdown | Plain markdown | | Metadata queries | Filter by type, status, tags, dates, custom fields | — | — | | Session memory | Activity log (every tool call with timestamps) | Tiered daily summaries (Haiku-compressed) | Manual (user writes CLAUDE.md) | | Setup effort | Medium (vault path + optional OpenAI key) | Low (auto hooks, no config) | None (built-in) | | MCP tools | 20 | 0 (hooks-based) | 0 | | Agents | 3 (explorer, capture, auditor) | 0 | 0 |

remember is great for lightweight session continuity with minimal setup. obsidian-pkm is for developers who want a structured, searchable, interconnected knowledge base that grows with every project.

Features

Knowledge Creation & Editing

| Tool | Description | |------|-------------| | vault_write | Create notes from templates with enforced frontmatter (ADRs, research, devlogs, tasks, etc.) | | vault_append | Add content to notes, with positional insert (after/before heading, end of section) | | vault_edit | Surgical string replacement for precise edits | | vault_update_frontmatter | Atomic YAML frontmatter updates (set, create, remove fields; validates enums by note type) |

Discovery & Search

| Tool | Description | |------|-------------| | vault_search | Full-text keyword search across markdown files | | vault_semantic_search | Conceptual similarity search via OpenAI embeddings — finds related notes even with different wording | | vault_query | Query by YAML frontmatter (type, status, tags, dates, custom fields) with sorting | | vault_tags | Discover all tags with per-note counts; folder scoping, glob filters, inline tag parsing | | vault_suggest_links | Suggest relevant notes to link based on content similarity |

Graph & Connections

| Tool | Description | |------|-------------| | vault_links | Wikilink analysis (incoming and outgoing links for a note) | | vault_neighborhood | Graph exploration via BFS wikilink traversal — discover related notes by proximity | | vault_add_links | Add annotated wikilinks to a note's section with deduplication | | vault_link_health | Audit link quality — find orphans, broken links, weak connections, ambiguous links |

Reading & Navigation

| Tool | Description | |------|-------------| | vault_read | Read note contents (pagination by heading, tail, chunk, line range; auto-redirects large files) | | vault_peek | Inspect file metadata and structure without reading full content | | vault_list | List files and folders | | vault_recent | Recently modified files |

Organization & Maintenance

| Tool | Description | |------|-------------| | vault_move | Move/rename files with automatic wikilink updating across the vault | | vault_trash | Soft-delete to .trash/ (Obsidian convention), warns about broken incoming links |

Session Memory

| Tool | Description | |------|-------------| | vault_activity | Cross-conversation memory — logs every tool call with timestamps and session IDs |

Agents, Skills & Commands

Agents (3) run autonomously in foreground or background:

| Agent | Purpose | |-------|---------| | vault-explorer | Research existing knowledge before creating notes | | pkm-capture | Devlog entries + knowledge capture after commits and work blocks | | link-auditor | Audit vault link health after bulk note changes |

Skills (3) are guided workflows triggered by slash commands:

| Skill | Purpose | |-------|---------| | pkm-write | Duplicate checking, link discovery, and annotations when creating notes | | pkm-explore | Graph + semantic exploration to map existing knowledge on a topic | | pkm-session-end | Session wrap-up: devlog, undocumented work capture, link health audit |

Commands (2) for setup and configuration:

| Command | Purpose | |---------|---------| | /obsidian-pkm:setup | Configure vault path, API keys, and permissions | | /obsidian-pkm:init-project | Connect a code repository to a vault project folder |

Prerequisites

Node.js >= 20 (Node 18 is EOL; uses native fetch and ES modules)
An MCP-compatible client such as Claude Code

Prebuilt native binaries are included for Node 20/22 on Linux x64, macOS (x64/arm64), and Windows x64. Most users need nothing else. If the prebuilt fails, you'll need C++ build tools — see Troubleshooting.

Quick Start

1. Install the Plugin

claude plugin marketplace add AdrianV101/obsidian-pkm-plugin
claude plugin install obsidian-pkm

2. Configure

Run the setup skill in Claude Code:

/obsidian-pkm:setup

The setup skill walks you through vault path, API keys, tool permissions, and verification. Hooks are registered automatically by the plugin system.

Important: Restart your Claude Code session after setup completes so the MCP server picks up the new configuration.

3. Scaffold Your Vault (optional)

If you need templates and the PARA folder structure, run the vault scaffolding wizard:

npx obsidian-pkm init

This is separate from the plugin install above — it only sets up your vault's directory structure (PARA folders, note templates). Nothing is written until you confirm each step.

Note: The first npx run downloads and compiles native dependencies, which may take 30-60 seconds. Subsequent runs are instant.

<details> <summary>Scaffold details</summary>

Step 1 — Vault path. Point to an existing Obsidian vault or create a new one. The wizard resolves ~, $HOME, and relative paths automatically. Safety checks prevent using system directories (/, /home, etc.) as a vault. For existing non-empty directories you can use it as-is, create a subfolder inside it, or wipe it (with triple confirmation). You

Obsidian Pkm Plugin

Install / Use

README