\n\n# Vault PKM\n\nGive Claude persistent, structured memory across conversations using your Obsidian vault. Read, write, search, and navigate your knowledge base — all from within Claude Code.\n\nUnder the hood, this Claude Code plugin provides 20 [MCP](https://modelcontextprotocol.io/) (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`](https://www.npmjs.com/package/obsidian-pkm).\n\n> If you find this useful, please [star the repo](https://github.com/AdrianV101/obsidian-pkm-plugin) — it helps others discover the plugin.\n\n[Watch the demo video](https://github.com/user-attachments/assets/564e70d1-9006-4a29-8bed-1ed167bdfe56)\n\n## Why\n\nClaude 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.\n\n- **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.\n- **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.\n- **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.\n- **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.\n- **Knowledge capture** — Decisions, tasks, and research findings are captured by specialized agents in the background without interrupting your coding flow.\n\nWithout 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.\n\n### How It Compares\n\n| | Vault PKM | [remember](https://github.com/Digital-Process-Tools/claude-remember) | Claude built-in memory |\n|---|---|---|---|\n| **Knowledge base** | Your Obsidian vault (markdown files you own) | Compressed conversation logs (`.remember/` dir) | CLAUDE.md + auto-memory files |\n| **Scope** | Cross-project (one vault for everything) | Per-project | Per-project (git-repo scoped) |\n| **Semantic search** | OpenAI embeddings | — | — |\n| **Graph traversal** | Wikilink BFS, link health audits | — | — |\n| **Structured notes** | 13 templates with validated frontmatter | Plain markdown | Plain markdown |\n| **Metadata queries** | Filter by type, status, tags, dates, custom fields | — | — |\n| **Session memory** | Activity log (every tool call with timestamps) | Tiered daily summaries (Haiku-compressed) | Manual (user writes CLAUDE.md) |\n| **Setup effort** | Medium (vault path + optional OpenAI key) | Low (auto hooks, no config) | None (built-in) |\n| **MCP tools** | 20 | 0 (hooks-based) | 0 |\n| **Agents** | 3 (explorer, capture, auditor) | 0 | 0 |\n\n**remember** is great for lightweight session continuity with minimal setup. **Vault PKM** is for developers who want a structured, searchable, interconnected knowledge base that grows with every project.\n\n## Features\n\n### Knowledge Creation & Editing\n\n| Tool | Description |\n|------|-------------|\n| `vault_write` | Create notes from templates with enforced frontmatter (ADRs, research, devlogs, tasks, etc.) |\n| `vault_append` | Add content to notes, with positional insert (after/before heading, end of section) |\n| `vault_edit` | Surgical string replacement for precise edits |\n| `vault_update_frontmatter` | Atomic YAML frontmatter updates (set, create, remove fields; validates enums by note type) |\n\n### Discovery & Search\n\n| Tool | Description |\n|------|-------------|\n| `vault_search` | Full-text keyword search across markdown files |\n| `vault_semantic_search` | Conceptual similarity search via OpenAI embeddings — finds related notes even with different wording |\n| `vault_query` | Query by YAML frontmatter (type, status, tags, dates, custom fields) with sorting |\n| `vault_tags` | Discover all tags with per-note counts; folder scoping, glob filters, inline tag parsing |\n| `vault_suggest_links` | Suggest relevant notes to link based on content similarity |\n\n### Graph & Connections\n\n| Tool | Description |\n|------|-------------|\n| `vault_links` | Wikilink analysis (incoming and outgoing links for a note) |\n| `vault_neighborhood` | Graph exploration via BFS wikilink traversal — discover related notes by proximity |\n| `vault_add_links` | Add annotated wikilinks to a note's section with deduplication |\n| `vault_link_health` | Audit link quality — find orphans, broken links, weak connections, ambiguous links |\n\n### Reading & Navigation\n\n| Tool | Description |\n|------|-------------|\n| `vault_read` | Read note contents (pagination by heading, tail, chunk, line range; auto-redirects large files) |\n| `vault_peek` | Inspect file metadata and structure without reading full content |\n| `vault_list` | List files and folders |\n| `vault_recent` | Recently modified files |\n\n### Organization & Maintenance\n\n| Tool | Description |\n|------|-------------|\n| `vault_move` | Move/rename files with automatic wikilink updating across the vault |\n| `vault_trash` | Soft-delete to `.trash/` (Obsidian convention), warns about broken incoming links |\n\n### Session Memory\n\n| Tool | Description |\n|------|-------------|\n| `vault_activity` | Cross-conversation memory — logs every tool call with timestamps and session IDs |\n\n### Agents, Skills & Commands\n\n**Agents** (3) run autonomously in foreground or background:\n\n| Agent | Purpose |\n|-------|---------|\n| `vault-explorer` | Research existing knowledge before creating notes |\n| `pkm-capture` | Devlog entries + knowledge capture after commits and work blocks |\n| `link-auditor` | Audit vault link health after bulk note changes |\n\n**Skills** (6) are guided workflows triggered by slash commands:\n\n| Skill | Purpose |\n|-------|---------|\n| `pkm-write` | Duplicate checking, link discovery, and annotations when creating notes |\n| `pkm-explore` | Graph + semantic exploration to map existing knowledge on a topic |\n| `pkm-session-end` | Session wrap-up: devlog, undocumented work capture, link health audit |\n| `add-task` | Fast task capture from a title with duplicate detection, priority shorthands, and due date |\n| `triage-tasks` | Surface open tasks as a numbered list with git completion hints; batch-update via shorthand (e.g. `1,3 done \\| 2 active`) |\n| `tackle-task` | Work a task end-to-end: read, explore vault context, route to the right workflow tier, close when done |\n\n**Commands** (2) for setup and configuration:\n\n| Command | Purpose |\n|---------|---------|\n| `/vault-pkm:setup` | Configure vault path, API keys, and permissions |\n| `/vault-pkm:init-project` | Connect a code repository to a vault project folder |\n\n## Prerequisites\n\n- **Node.js >= 20** (Node 18 is EOL; uses native `fetch` and ES modules)\n- **An MCP-compatible client** such as [Claude Code](https://claude.ai/code)\n\nPrebuilt 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](#better-sqlite3-build-fails-during-install).\n\n## Quick Start\n\n### 1. Install the Plugin\n\n```bash\nclaude plugin marketplace add anthropics/claude-plugins-community\nclaude plugin install vault-pkm@claude-community\n```\n\n### 2. Configure\n\nRun the setup skill in Claude Code:\n\n```\n/vault-pkm:setup\n```\n\nThe setup skill walks you through vault path, API keys, tool permissions, and verification. Hooks are registered automatically by the plugin system.\n\n**Important:** Restart your Claude Code session after setup completes so the MCP server picks up the new configuration.\n\n### 3. Scaffold Your Vault (optional)\n\nIf you need templates and the PARA folder structure, run the vault scaffolding wizard:\n\n```bash\nnpx obsidian-pkm init\n```\n\nThis 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.\n\n> **Note:** The first `npx` run downloads and compiles native dependencies, which may take 30-60 seconds. Subsequent runs are instant.\n\n\nScaffold details\n\n**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'll be offered an optional backup before any changes.\n\n**Step 2 — Note templates.** Copies template files into `/05-Templates/`. Three options:\n- **Full set** — all 13 templates (`adr`, `daily-note`, `devlog`, `fleeting-note`, `literature-note`, `meeting-notes`, `moc`, `note`, `permanent-note`, `project-index`, `research-note`, `task`, `troubleshooting-log`)\n- **Minimal** — just `note.md` (a single generic template)\n- **Skip** — for users with their own templates\n\nExisting templates are never overwritten.\n\n**Step 3 — PARA folder structure.** Creates 7 top-level folders with `_index.md` stubs:\n\n| Folder | Purpose |\n|--------|---------|\n| `00-Inbox/` | Quick captures and unsorted notes |\n| `01-Projects/` | Active project folders |\n| `02-Areas/` | Ongoing areas of responsibility |\n| `03-Resources/` | Reference material and reusable knowledge |\n| `04-Archive/` | Completed or inactive items |\n| `05-Templates/` | Note templates |\n| `06-System/` | System configuration and metadata |\n\nEach `_index.md` has `type: moc` frontmatter. Existing folders and index files are skipped.\n\n\n\n### 4. Verify It Works\n\nOpen Claude Code and try:\n\n> List the folders in my vault\n\nClaude should call `vault_list` and show your vault's directory structure. If it works, the server is connected and ready.\n\n### 5. Enable Semantic Search (optional)\n\nAdd your OpenAI API key to `~/.claude/settings.json` under the `env` block:\n\n```json\n{\n \"env\": {\n \"VAULT_PATH\": \"/path/to/vault\",\n \"VAULT_PKM_OPENAI_KEY\": \"sk-your-key-here\"\n }\n}\n```\n\nUse `VAULT_PKM_OPENAI_KEY` (preferred) to avoid conflicts with project-level OpenAI keys. `OPENAI_API_KEY` is also accepted as a fallback. The previously-documented `OBSIDIAN_PKM_OPENAI_KEY` still works as a deprecated fallback — plan to rename it in your config. Restart Claude Code after saving.\n\n**Optional: `VAULT_PKM_VAULT_NAME`** — overrides the vault name used in `obsidian://` links emitted in tool output. Defaults to `basename(VAULT_PATH)`, which is correct for most setups. Set this only if your on-disk folder name differs from the vault name you registered in Obsidian (e.g. `VAULT_PATH=/Users/me/Notes` but Obsidian shows the vault as `My PKM`).\n\nThis enables `vault_semantic_search` and `vault_suggest_links`. Uses `text-embedding-3-large` with a SQLite + sqlite-vec index stored at `.obsidian/semantic-index.db`. The index rebuilds automatically — delete the DB file to force a full re-embed.\n\n\nVault Structure\n\nThe server works with any Obsidian vault. The included templates assume this layout:\n\n```\nVault/\n├── 00-Inbox/\n├── 01-Projects/\n│ └── ProjectName/\n│ ├── _index.md\n│ ├── planning/\n│ ├── research/\n│ └── development/decisions/\n├── 02-Areas/\n├── 03-Resources/\n├── 04-Archive/\n├── 05-Templates/ # Note templates loaded by vault_write\n└── 06-System/\n```\n\n### Templates\n\n`vault_write` loads all `.md` files from `05-Templates/` at startup and enforces frontmatter on every note created. Run `npx obsidian-pkm init` to install them automatically, or copy the files from `templates/` manually.\n\n13 included templates: `adr`, `daily-note`, `devlog`, `fleeting-note`, `literature-note`, `meeting-notes`, `moc`, `note`, `permanent-note`, `project-index`, `research-note`, `task`, `troubleshooting-log`. Add your own templates to `05-Templates/` and they become available to `vault_write` automatically.\n\nTask notes enforce `status` (pending, active, done, cancelled) and `priority` (low, normal, high, urgent) enums. All other note types accept any string values for these fields.\n\n### CLAUDE.md for Your Projects\n\n`sample-project/CLAUDE.md` is a template you can drop into any code repository to wire up Claude Code with your vault. It defines context loading, documentation rules, and ADR/devlog conventions.\n\n\n\n\nArchitecture\n\nModule dependencies:\n\n```mermaid\ngraph LR\n CC[Claude Code] -->|MCP protocol| IDX[index.js]\n IDX --> HND[handlers.js]\n IDX --> E[embeddings.js]\n IDX --> A[activity.js]\n HND --> H[helpers.js]\n HND --> G[graph.js]\n HND --> U[utils.js]\n HND -->|read/write| V[(Obsidian Vault)]\n E -->|embeddings API| OAI[OpenAI]\n E -->|vector store| DB[(SQLite + sqlite-vec)]\n A -->|activity log| DB2[(SQLite)]\n```\n\nFile layout:\n\n```\n├── index.js # MCP server setup, tool registration, lifecycle\n├── handlers.js # Tool handler implementations\n├── helpers.js # Pure functions (path security, filtering, templates, frontmatter)\n├── graph.js # Wikilink resolution and BFS graph traversal\n├── embeddings.js # Semantic index (OpenAI embeddings, SQLite + sqlite-vec)\n├── activity.js # Activity log (session tracking, SQLite)\n├── utils.js # Shared utilities (frontmatter parsing, file listing)\n├── cli.js # CLI entry point (routes `init` subcommand or starts server)\n├── init.js # Vault scaffolding wizard (templates, PARA folders)\n├── .claude-plugin/ # Plugin packaging\n│ └── plugin.json # Plugin manifest (identity, components, permissions)\n├── hooks/ # Claude Code hooks (context loading, project resolution, session start)\n├── agents/ # Specialized agents (vault-explorer, pkm-capture, link-auditor)\n├── skills/ # PKM workflow skills (pkm-write, pkm-explore, pkm-session-end, add-task, triage-tasks, tackle-task)\n├── commands/ # Slash commands (setup, init-project)\n├── templates/ # Obsidian note templates\n├── tests/ # Test suite (Node.js built-in test runner)\n├── sample-project/ # Sample CLAUDE.md for your repos\n└── docs/ # Supplementary documentation\n```\n\n`index.js` initializes the semantic index and activity log, then injects them into `createHandlers()`. All paths passed to tools are relative to vault root. The server includes path security to prevent directory traversal.\n\n\n\n## How It Works\n\n**Knowledge creation** is template-based. `vault_write` loads templates from `05-Templates/`, substitutes Templater-compatible variables (`<% tp.date.now(\"YYYY-MM-DD\") %>`, `<% tp.file.title %>`), and validates required frontmatter fields (`type`, `created`, `tags`). This ensures every note in your vault has consistent metadata — making it queryable, sortable, and discoverable from day one. Task notes enforce enum validation on `status` and `priority`; other types accept `project`, `deciders`, `due`, and `source`.\n\n**Knowledge discovery** works at two levels. Keyword search (`vault_search`) finds exact terms. Semantic search embeds notes using OpenAI and finds conceptually related content — so \"managing overwhelm\" surfaces notes about \"cognitive load\" even if those exact words never appear together. The semantic index watches for file changes in real-time and syncs across machines via Obsidian Sync.\n\n**Knowledge connections** are maintained through Obsidian's `[[wikilink]]` graph. `vault_neighborhood` traverses links via BFS to discover related notes by proximity, while `vault_suggest_links` recommends connections you haven't made yet. `vault_move` rewrites wikilinks across the vault when you reorganize, and `vault_trash` warns about links that would break.\n\n**Session memory** records every tool call with timestamps and session IDs, so Claude can recall what was read, written, or searched in previous conversations. This turns ephemeral chat sessions into a continuous thread of work.\n\n**Knowledge capture** uses the `pkm-capture` agent to update the project devlog and persist PKM-worthy content from a session (decisions, research findings, tasks, bug root causes) in one pass. It is triggered automatically after git commits via a PreToolUse hook, or can be dispatched manually after significant work blocks. Runs in the background without interrupting the coding flow.\n\n**Fuzzy path resolution** lets read-only tools accept short names instead of full vault paths. `vault_read({ path: \"devlog\" })` resolves to `01-Projects/MyApp/development/devlog.md` automatically (`.md` extension optional). Folder-scoped tools like `vault_list`, `vault_search`, and `vault_query` accept partial folder names — `folder: \"MyApp\"` resolves to `01-Projects/MyApp`. Ambiguous matches return an error listing candidates. Write/destructive tools always require exact paths.\n\n## Troubleshooting\n\n**`better-sqlite3` build fails during install**\nYou need C++ build tools. See [Prerequisites](#prerequisites) for your platform. On Linux, `sudo apt install build-essential python3` usually fixes it.\n\n**Server starts but all tool calls fail with ENOENT**\nYour `VAULT_PATH` is wrong or missing. The server validates this at startup and exits with a clear error. Run `/vault-pkm:setup` to reconfigure the vault path.\n\n**`vault_write` says \"no templates available\"**\nRun `npx obsidian-pkm init` to install templates, or copy the `templates/` files from this repo into your vault's `05-Templates/` directory. The server loads templates from there at startup.\n\n**Semantic search not appearing in tool list**\nSet `VAULT_PKM_OPENAI_KEY` in `~/.claude/settings.json`. See [Enable Semantic Search](#5-enable-semantic-search-optional). Without it, `vault_semantic_search` and `vault_suggest_links` are hidden entirely.\n\n**Server not showing up in Claude Code after install**\nRun `claude mcp list` to check. If `vault-pkm` is missing, reinstall the plugin: `claude plugin install vault-pkm@claude-community`. Then run `/vault-pkm:setup` to configure it.\n\n**Semantic index not updating after file changes**\nCheck your Node version with `node -v`. The file watcher uses `fs.watch({ recursive: true })` which requires Node.js >= 20.\n\n**Not sure if everything is set up correctly?**\nRun `npx obsidian-pkm doctor` for a diagnostic checklist that validates your Node version, vault path, templates, API keys, and native dependencies.\n\n## Contributing\n\nContributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style guidelines, and the pull request process before submitting changes.\n\nSee [CHANGELOG.md](CHANGELOG.md) for release history, [SECURITY.md](SECURITY.md) to report vulnerabilities, and [PRIVACY.md](PRIVACY.md) for how the plugin handles your data.\n\n## License\n\nMIT\n\n",
"bytes": 20668,
"sha": "05a505fc4b39ef4d06aa5612999e193b4ba86d98e97f9166b424bf40c09ce13d",
"repo_slug": "adrianv101/obsidian-pkm-plugin",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_adrianv101_obsidian_pkm_plugin_vault_pkm_35a96824/readme"
}
![\"Vault](\"assets/banner.svg\")
\n![\"npm](\"https://img.shields.io/npm/v/obsidian-pkm\")
![\"npm](\"https://img.shields.io/npm/dw/obsidian-pkm\")
![\"GitHub](\"https://img.shields.io/github/stars/AdrianV101/obsidian-pkm-plugin?style=flat\")
![\"License:](\"https://img.shields.io/badge/License-MIT-yellow.svg\"){kind=icon}
\n ![\"CI\"](\"https://github.com/AdrianV101/obsidian-pkm-plugin/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n ![\"Tests\"](\"https://img.shields.io/badge/tests-574%20passing-brightgreen\"){kind=icon}