pkm-mcp-server 1.1.1 → 1.2.1

package/CHANGELOG.md

@@ -6,6 +6,33 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.2.1] - 2026-03-17
+
+### Added
+- CI workflow for automated npm publishing via GitHub releases (OIDC trusted publishing, no tokens)
+
+### Fixed
+- Hook setup instructions now included in main README Quick Start (previously only in `hooks/README.md`, invisible on npm)
+- `hooks/` directory added to architecture file tree in README
+
+## [1.2.0] - 2026-03-17
+
+### Added
+- `vault_capture` tool — signal a PKM-worthy capture (decision, task, research, bug); returns immediately while a background hook creates the note
+- PKM hook scripts for Claude Code integration:
+  - SessionStart hook (`session-start.js`) — loads project context from vault automatically
+  - PostToolUse hook (`capture-handler.sh`) — spawns Sonnet agent for explicit `vault_capture` calls
+  - Stop hook (`stop-sweep.sh`) — spawns Haiku agent for passive decision/task sweep at session end
+- Enum validation for task `status` (pending/active/done/cancelled) and `priority` (low/normal/high/urgent) fields in `vault_write` and `vault_update_frontmatter` — non-task note types are unaffected
+
+### Changed
+- `sqlite-vec` upgraded from pinned alpha (0.1.7-alpha.2) to stable release (0.1.7)
+- `@modelcontextprotocol/sdk` updated to 1.27.1
+- `better-sqlite3` updated to 12.8.0
+
+### Security
+- Resolved 7 transitive dependency vulnerabilities (hono, @hono/node-server, ajv, express-rate-limit, flatted, minimatch, qs)
+
 ## [1.1.0] - 2026-02-23
 
 ### Changed
@@ -55,6 +82,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Atomic file creation in `vault_write` (`wx` flag) prevents race conditions
 - Error messages sanitized to prevent leaking absolute vault paths
 
-[Unreleased]: https://github.com/AdrianV101/Obsidian-MCP/compare/v1.1.0...HEAD
+[Unreleased]: https://github.com/AdrianV101/Obsidian-MCP/compare/v1.2.1...HEAD
+[1.2.1]: https://github.com/AdrianV101/Obsidian-MCP/compare/v1.2.0...v1.2.1
+[1.2.0]: https://github.com/AdrianV101/Obsidian-MCP/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/AdrianV101/Obsidian-MCP/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/AdrianV101/Obsidian-MCP/releases/tag/v1.0.0

package/README.md

@@ -36,12 +36,12 @@ https://github.com/user-attachments/assets/58ad9c9b-d987-4728-89e7-33de20b73a38
 | `vault_recent` | Recently modified files |
 | `vault_links` | Wikilink analysis (incoming/outgoing) |
 | `vault_neighborhood` | Graph exploration via BFS wikilink traversal |
-| `vault_query` | Query notes by YAML frontmatter (type, status, tags, dates, custom fields, sorting) |
+| `vault_query` | Query notes by YAML frontmatter (type, status, tags/tags_any, dates, custom fields, sorting) |
 | `vault_tags` | Discover tags with counts; folder scoping, glob filters, inline tag parsing |
 | `vault_activity` | Session activity log for cross-conversation memory |
 | `vault_trash` | Soft-delete to `.trash/` (Obsidian convention), warns about broken incoming links |
 | `vault_move` | Move/rename files with automatic wikilink updating across vault |
-| `vault_update_frontmatter` | Atomic YAML frontmatter updates (set, create, remove fields) |
+| `vault_update_frontmatter` | Atomic YAML frontmatter updates (set, create, remove fields; validates enum fields by note type) |
 
 ### Fuzzy Path Resolution
 
@@ -148,6 +148,67 @@ Add your OpenAI API key to the env block:
 
 This 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.
 
+### 4. Enable PKM Hooks (optional)
+
+The hook system adds automatic context loading at session start and passive knowledge capture during coding. Requires the [Claude CLI](https://docs.anthropic.com/en/docs/claude-cli) installed and authenticated.
+
+Add to your `~/.claude/settings.json` (alongside the `mcpServers` block):
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "VAULT_PATH=\"/path/to/your/vault\" node /path/to/Obsidian-MCP/hooks/session-start.js",
+            "timeout": 15,
+            "statusMessage": "Loading PKM project context..."
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "VAULT_PATH=\"/path/to/your/vault\" /path/to/Obsidian-MCP/hooks/stop-sweep.sh",
+            "async": true,
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "mcp__obsidian-pkm__vault_capture",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "VAULT_PATH=\"/path/to/your/vault\" /path/to/Obsidian-MCP/hooks/capture-handler.sh",
+            "async": true,
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Replace `/path/to/your/vault` with your Obsidian vault path and `/path/to/Obsidian-MCP` with the path to this repo (or the global npm install location).
+
+| Hook | Event | What it does |
+|------|-------|--------------|
+| `session-start.js` | SessionStart | Loads project context (index, devlog, active tasks) at session start |
+| `stop-sweep.sh` | Stop | Scans each exchange for PKM-worthy decisions/tasks, appends to daily captures |
+| `capture-handler.sh` | PostToolUse | Creates structured vault notes when `vault_capture` is called |
+
+See [hooks/README.md](hooks/README.md) for architecture details and troubleshooting.
+
 ## Vault Structure
 
 The server works with any Obsidian vault. The included templates assume this layout:
@@ -203,6 +264,7 @@ graph LR
 ├── embeddings.js     # Semantic index (OpenAI embeddings, SQLite + sqlite-vec)
 ├── activity.js       # Activity log (session tracking, SQLite)
 ├── utils.js          # Shared utilities (frontmatter parsing, file listing)
+├── hooks/            # Claude Code hooks (session context, passive capture)
 ├── templates/        # Obsidian note templates
 └── sample-project/   # Sample CLAUDE.md for your repos
 ```
@@ -211,7 +273,7 @@ All paths passed to tools are relative to vault root. The server includes path s
 
 ## How It Works
 
-**Note 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`).
+**Note 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`). Optional frontmatter fields — `status`, `priority`, `project`, `deciders`, `due`, `source` — can be set per template type. Task notes enforce enum validation on `status` (pending/active/done/cancelled) and `priority` (low/normal/high/urgent).
 
 **Semantic search** embeds notes on startup and watches for changes via `fs.watch`. Long notes are chunked by `##` headings. The index is a regenerable cache stored in `.obsidian/` so it syncs across machines via Obsidian Sync. The initial sync runs in the background — search is available immediately but may return incomplete results until sync finishes (a progress message is shown).
 

package/handlers.js

@@ -848,6 +848,21 @@ export async function createHandlers({ vaultPath, templateRegistry, semanticInde
     };
   }
 
+  async function handleCapture(args) {
+    const { type, title, content } = args;
+    if (!type || !title || !content) {
+      throw new Error(
+        `vault_capture requires type, title, and content. Got: type=${type || "(missing)"}, title=${title || "(missing)"}, content=${content ? "provided" : "(missing)"}`
+      );
+    }
+    return {
+      content: [{
+        type: "text",
+        text: `Capture queued: [${type}] ${title}`
+      }]
+    };
+  }
+
   return new Map([
     ["vault_read", handleRead],
     ["vault_write", handleWrite],
@@ -867,5 +882,6 @@ export async function createHandlers({ vaultPath, templateRegistry, semanticInde
     ["vault_trash", handleTrash],
     ["vault_move", handleMove],
     ["vault_update_frontmatter", handleUpdateFrontmatter],
+    ["vault_capture", handleCapture],
   ]);
 }

package/hooks/README.md

@@ -0,0 +1,125 @@
+# PKM Hook System
+
+Claude Code hooks that enable automatic knowledge capture during coding sessions.
+
+## Overview
+
+The hook system consists of three hooks:
+
+| Hook | Event | Purpose |
+|------|-------|---------|
+| `session-start.js` | SessionStart | Loads project context from the vault at the start of each session |
+| `stop-sweep.sh` | Stop | Passive capture: scans the latest exchange for PKM-worthy content |
+| `capture-handler.sh` | PostToolUse | Explicit capture: creates structured vault notes when `vault_capture` is called |
+
+### How it works
+
+- **SessionStart** (`session-start.js`): Runs synchronously. Resolves the current working directory to a vault project, reads the project index, recent devlog entries, and active tasks, then injects them as context.
+- **Stop** (`stop-sweep.sh`): Runs asynchronously after each assistant response. Spawns a background `claude -p` (Haiku) that reads the transcript, identifies decisions/tasks/findings from the latest exchange, and appends them to a daily captures file in `00-Inbox/`.
+- **PostToolUse** (`capture-handler.sh`): Runs asynchronously after `vault_capture` tool use. Spawns a background `claude -p` (Sonnet) that creates a properly structured vault note (ADR, task, research note, or troubleshooting log) from the capture payload.
+
+## Setup
+
+### Prerequisites
+
+- [Claude CLI](https://docs.anthropic.com/en/docs/claude-cli) installed and authenticated
+- This repository cloned locally
+- An Obsidian vault following the [vault structure convention](../CLAUDE.md#vault-structure-convention)
+
+### Configuration
+
+Add the following to your `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "VAULT_PATH=\"/path/to/your/vault\" node /path/to/Obsidian-MCP/hooks/session-start.js",
+            "timeout": 15,
+            "statusMessage": "Loading PKM project context..."
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "VAULT_PATH=\"/path/to/your/vault\" /path/to/Obsidian-MCP/hooks/stop-sweep.sh",
+            "async": true,
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "mcp__obsidian-pkm__vault_capture",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "VAULT_PATH=\"/path/to/your/vault\" /path/to/Obsidian-MCP/hooks/capture-handler.sh",
+            "async": true,
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Replace `/path/to/your/vault` with the absolute path to your Obsidian vault (e.g., `~/Documents/PKM`), and `/path/to/Obsidian-MCP` with the absolute path to this repository.
+
+## Architecture Notes
+
+### Command hooks with background subprocesses
+
+The hook system uses `type: "command"` hooks (not `type: "agent"`). The shell scripts themselves exit quickly (within the configured timeout), but they spawn `claude -p` as a detached background process via `nohup ... &`. This means:
+
+- The hook script exits immediately, satisfying the timeout constraint
+- The `claude -p` process continues running independently, doing the actual vault work
+- `--max-turns` limits how many tool calls the background process can make (5 for stop-sweep, 25 for capture-handler)
+
+### MCP config resolution
+
+The shell scripts use `cd "$(dirname "$0")" && pwd -P` to resolve their own location, then construct the path to `index.js` relative to the script directory. This means the scripts work regardless of the current working directory. The `VAULT_PATH` environment variable must be set in the hook command because hook scripts run outside the MCP server process.
+
+### Async behavior
+
+Both `stop-sweep.sh` and `capture-handler.sh` use `async: true` in the hook config. This means Claude Code does not wait for the hook script to finish before continuing. The script starts, spawns the background `claude -p` process, and exits. The background process runs to completion on its own.
+
+### Noise suppression and deduplication
+
+The stop-sweep hook is conservative by design. It only looks at the last exchange (one user message + one assistant response) and skips trivial interactions. If the exchange already contains an explicit `vault_capture` call, the stop-sweep skips that content to avoid duplication with the capture-handler.
+
+## Troubleshooting
+
+### Hook not firing
+
+- Verify the hook config is valid JSON in `~/.claude/settings.json`
+- Check that the `matcher` pattern matches (SessionStart uses `"startup|clear|compact"`, PostToolUse uses the full MCP tool name)
+- Ensure the script paths are absolute
+
+### Script errors
+
+- Check that `VAULT_PATH` is set correctly and the directory exists
+- Verify `node` is available in the hook's PATH
+- Test the script manually: `echo '{"cwd":"/tmp","transcript_path":"/tmp/test","session_id":"abc123"}' | VAULT_PATH="/path/to/vault" ./hooks/stop-sweep.sh`
+
+### Background process not running
+
+- Check for `claude` CLI in PATH
+- Look for `claude -p` processes: `ps aux | grep 'claude -p'`
+- Test `claude -p` directly: `echo "say hello" | claude -p --model sonnet`
+- Check logs in `$VAULT_PATH/.obsidian/hook-logs/` for background process output
+
+### macOS compatibility
+
+The scripts use POSIX-compatible `cd "$(dirname "$0")" && pwd -P` for path resolution, so they work on both Linux and macOS without additional dependencies.

package/hooks/capture-handler.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# PostToolUse hook: explicit PKM capture via vault_capture tool
+# Runs async after vault_capture returns. Spawns claude -p with Sonnet
+# to create a properly structured vault note.
+
+set -euo pipefail
+
+LOG_DIR="${VAULT_PATH:?}/.obsidian/hook-logs"
+mkdir -p "$LOG_DIR"
+PROMPT_FILE=""
+cleanup() { [ -n "$PROMPT_FILE" ] && rm -f "$PROMPT_FILE"; }
+trap 'echo "capture-handler: failed at line $LINENO" >> "$LOG_DIR/capture-errors.log"; cleanup' ERR
+trap cleanup EXIT
+
+# Read hook input from stdin
+INPUT=$(cat)
+
+# Extract tool_input fields (buffer all stdin before parsing)
+eval "$(echo "$INPUT" | node -e "
+  let b='';
+  process.stdin.on('data',c=>b+=c);
+  process.stdin.on('end',()=>{
+    const j=JSON.parse(b);
+    const ti=j.tool_input||{};
+    console.log('TOOL_INPUT='+JSON.stringify(JSON.stringify(ti)));
+    console.log('CAPTURE_TYPE='+JSON.stringify(ti.type||''));
+    console.log('CAPTURE_TITLE='+JSON.stringify(ti.title||''));
+    console.log('CAPTURE_CONTENT='+JSON.stringify(ti.content||''));
+  })
+")"
+
+# Skip if missing required fields
+if [ -z "$CAPTURE_TYPE" ] || [ -z "$CAPTURE_TITLE" ] || [ -z "$CAPTURE_CONTENT" ]; then
+  echo "capture-handler: skipping - missing required fields (type='$CAPTURE_TYPE')" >&2
+  exit 0
+fi
+
+# MCP config for obsidian-pkm server
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd -P)
+MCP_CONFIG=$(node -e "console.log(JSON.stringify({mcpServers:{'obsidian-pkm':{command:'node',args:[process.argv[1]],env:{VAULT_PATH:process.argv[2]}}}}))" "$SCRIPT_DIR/../index.js" "${VAULT_PATH:-$HOME/Documents/PKM}")
+
+# Build prompt via Node.js to avoid shell injection from user content
+PROMPT_FILE=$(mktemp)
+node -e "
+const ti = JSON.parse(process.argv[1]);
+const project = ti.project
+  ? 'The project is: ' + ti.project
+  : 'The project is not specified. Check vault_activity recent entries to infer the active project.';
+const prompt = \`You are a PKM note creation agent. Your job is NOT done until the note has real content — not template placeholders.
+
+## What to capture
+
+- Type: \${ti.type}
+- Title: \${ti.title}
+- Content: \${ti.content}
+- Priority: \${ti.priority || 'normal'}
+- \${project}
+
+## Required steps (you must do ALL of these)
+
+1. Create the note with vault_write using the appropriate template:
+   - research → template 'research-note', path: 01-Projects/{project}/research/{kebab-title}.md
+   - adr → template 'adr', path: 01-Projects/{project}/development/decisions/ADR-NNN-{kebab-title}.md (use vault_list to get next number)
+   - task → template 'task', path: 01-Projects/{project}/tasks/{kebab-title}.md (vault_query first to check for duplicates)
+   - bug → template 'troubleshooting-log', path: 01-Projects/{project}/development/debug/{kebab-title}.md
+   If vault_write fails because the file exists, use a different filename.
+
+2. Read the created note with vault_read.
+
+3. Use vault_edit to replace EVERY template placeholder with real content derived from the Title and Content above. For example, replace 'Brief description of the technology, tool, or concept.' with an actual description. Do this for EACH section — you will need multiple vault_edit calls.
+
+4. Read the note one final time to confirm no placeholder text remains.
+
+CRITICAL: If you stop after step 1 or 2, you have FAILED. The note will contain useless placeholder text like 'Brief description of the technology, tool, or concept.' which is worse than no note at all. You MUST reach step 4.\`;
+require('fs').writeFileSync(process.argv[2], prompt);
+" "$TOOL_INPUT" "$PROMPT_FILE"
+
+# Spawn claude -p in background with logging
+nohup claude -p --model sonnet --mcp-config "$MCP_CONFIG" --max-turns 25 --allowedTools "mcp__obsidian-pkm__vault_write mcp__obsidian-pkm__vault_read mcp__obsidian-pkm__vault_edit mcp__obsidian-pkm__vault_append mcp__obsidian-pkm__vault_query mcp__obsidian-pkm__vault_list mcp__obsidian-pkm__vault_update_frontmatter mcp__obsidian-pkm__vault_activity" < "$PROMPT_FILE" >> "$LOG_DIR/capture-$(date +%Y%m%d-%H%M%S).log" 2>&1 &
+
+exit 0

package/hooks/load-context.js

@@ -0,0 +1,64 @@
+import fs from "fs/promises";
+import path from "path";
+import { extractFrontmatter } from "../utils.js";
+import { extractTailSections } from "../helpers.js";
+
+export async function loadProjectContext(vaultPath, projectPath) {
+  const projectName = path.basename(projectPath);
+  const projectDir = path.join(vaultPath, projectPath);
+  const sections = [];
+
+  sections.push(`## PKM Project Context: ${projectName}`);
+
+  try {
+    const indexContent = await fs.readFile(path.join(projectDir, "_index.md"), "utf-8");
+    sections.push(`### Project Index\n${indexContent}`);
+  } catch (e) {
+    if (e.code !== "ENOENT") console.error("PKM load-context: error reading _index.md:", e.message);
+  }
+
+  try {
+    const devlogContent = await fs.readFile(
+      path.join(projectDir, "development", "devlog.md"), "utf-8"
+    );
+    const tailSections = extractTailSections(devlogContent, 3, 2);
+    sections.push(`### Recent Development Activity\n${tailSections}`);
+  } catch (e) {
+    if (e.code !== "ENOENT") console.error("PKM load-context: error reading devlog:", e.message);
+  }
+
+  const tasks = [];
+  try {
+    const taskDir = path.join(projectDir, "tasks");
+    const entries = await fs.readdir(taskDir);
+    for (const entry of entries) {
+      if (!entry.endsWith(".md")) continue;
+      const content = await fs.readFile(path.join(taskDir, entry), "utf-8");
+      const fm = extractFrontmatter(content);
+      if (!fm || (fm.status !== "active" && fm.status !== "pending")) continue;
+
+      const bodyStart = content.indexOf("\n---", 3);
+      const body = bodyStart !== -1 ? content.slice(bodyStart + 4).trim() : content;
+      const lines = body.split("\n");
+      const titleLine = lines.find(l => l.startsWith("# "));
+      const title = titleLine ? titleLine.slice(2).trim() : entry.replace(".md", "");
+      const descLines = lines
+        .filter(l => l.trim() && !l.startsWith("#"))
+        .slice(0, 2)
+        .map(l => `  ${l.trim()}`)
+        .join("\n");
+
+      tasks.push(`- ${title} (status: ${fm.status}, priority: ${fm.priority || "normal"})\n${descLines}`);
+    }
+  } catch (e) {
+    if (e.code !== "ENOENT") console.error("PKM load-context: error reading tasks:", e.message);
+  }
+
+  if (tasks.length > 0) {
+    sections.push(`### Active Tasks\n${tasks.join("\n")}`);
+  } else {
+    sections.push("### Active Tasks\nNo active tasks");
+  }
+
+  return sections.join("\n\n");
+}

package/hooks/resolve-project.js

@@ -0,0 +1,67 @@
+import fs from "fs/promises";
+import path from "path";
+import { resolvePath } from "../helpers.js";
+
+export async function resolveProject(cwd, vaultPath) {
+  try {
+    await fs.access(vaultPath);
+  } catch (e) {
+    if (e.code === "ENOENT") {
+      return { error: `VAULT_PATH does not exist: ${vaultPath}` };
+    }
+    return { error: `Cannot access VAULT_PATH (${e.code}): ${vaultPath}` };
+  }
+
+  const projectsDir = path.join(vaultPath, "01-Projects");
+  const cwdBasename = path.basename(cwd).toLowerCase();
+
+  try {
+    const entries = await fs.readdir(projectsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && entry.name.toLowerCase() === cwdBasename) {
+        return { projectPath: `01-Projects/${entry.name}` };
+      }
+    }
+  } catch (e) {
+    if (e.code !== "ENOENT") {
+      return { error: `Error reading 01-Projects/: ${e.message}` };
+    }
+    // 01-Projects/ doesn't exist -- fall through to CLAUDE.md check
+  }
+
+  try {
+    const claudeMd = await fs.readFile(path.join(cwd, "CLAUDE.md"), "utf-8");
+    const match = claudeMd.match(/^#\s+PKM:\s*(.+)$/m);
+    if (match) {
+      const annotatedPath = match[1].trim();
+      try {
+        resolvePath(annotatedPath, vaultPath);
+      } catch (e) {
+        if (e.message === "Path escapes vault directory") {
+          return { error: `CLAUDE.md annotation escapes vault directory: ${annotatedPath}` };
+        }
+        throw e;
+      }
+      try {
+        await fs.access(path.join(vaultPath, annotatedPath));
+        return { projectPath: annotatedPath };
+      } catch (e) {
+        if (e.code === "ENOENT") {
+          return { error: `CLAUDE.md annotation points to non-existent vault path: ${annotatedPath}` };
+        }
+        return { error: `Cannot access annotated vault path (${e.code}): ${annotatedPath}` };
+      }
+    }
+  } catch (e) {
+    if (e.code !== "ENOENT" && e.code !== "EACCES") {
+      return { error: `Error reading CLAUDE.md: ${e.message}` };
+    }
+    // No CLAUDE.md or not readable -- fall through
+  }
+
+  return {
+    error: `No vault project found for "${path.basename(cwd)}". ` +
+      `To fix: ensure your project folder name matches the repo name in 01-Projects/, ` +
+      `or add "# PKM: 01-Projects/YourProject" to your project's CLAUDE.md.`
+  };
+}

package/hooks/session-start.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+import { resolveProject } from "./resolve-project.js";
+import { loadProjectContext } from "./load-context.js";
+
+const VAULT_PATH = process.env.VAULT_PATH;
+
+async function main() {
+  let inputJson = "";
+  for await (const chunk of process.stdin) {
+    inputJson += chunk;
+  }
+
+  let input;
+  try {
+    input = JSON.parse(inputJson);
+  } catch {
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: "PKM hook error: could not parse hook input JSON."
+      }
+    };
+    console.log(JSON.stringify(output));
+    process.exit(0);
+  }
+
+  const { cwd } = input;
+
+  if (!cwd || typeof cwd !== "string") {
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: "PKM hook error: hook input missing 'cwd' field."
+      }
+    };
+    console.log(JSON.stringify(output));
+    process.exit(0);
+  }
+
+  if (!VAULT_PATH) {
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: "PKM hook warning: VAULT_PATH environment variable not set. Vault context unavailable."
+      }
+    };
+    console.log(JSON.stringify(output));
+    process.exit(0);
+  }
+
+  const { projectPath, error } = await resolveProject(cwd, VAULT_PATH);
+
+  if (error) {
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: `PKM: ${error}`
+      }
+    };
+    console.log(JSON.stringify(output));
+    process.exit(0);
+  }
+
+  let context;
+  try {
+    context = await loadProjectContext(VAULT_PATH, projectPath);
+  } catch (e) {
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: `PKM hook error: failed to load project context: ${e.message}`
+      }
+    };
+    console.log(JSON.stringify(output));
+    process.exit(0);
+  }
+
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: context
+    }
+  };
+  console.log(JSON.stringify(output));
+}
+
+main().catch((err) => {
+  console.error(`PKM SessionStart hook error: ${err.message}`);
+  process.exit(1);
+});

package/hooks/stop-sweep.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Stop hook: passive PKM capture sweep
+# Runs async after each Claude response. Spawns claude -p with Haiku
+# to analyze the transcript and capture decisions/tasks/findings.
+
+set -euo pipefail
+
+LOG_DIR="${VAULT_PATH:?}/.obsidian/hook-logs"
+mkdir -p "$LOG_DIR"
+trap 'echo "stop-sweep: failed at line $LINENO" >> "$LOG_DIR/sweep-errors.log"' ERR
+
+# Read hook input from stdin
+INPUT=$(cat)
+
+eval "$(echo "$INPUT" | node -e "
+  let b='';
+  process.stdin.on('data',c=>b+=c);
+  process.stdin.on('end',()=>{
+    const j=JSON.parse(b);
+    console.log('TRANSCRIPT_PATH='+JSON.stringify(j.transcript_path||''));
+    console.log('SESSION_ID='+JSON.stringify(j.session_id||''));
+    console.log('CWD='+JSON.stringify(j.cwd||''));
+  })
+")"
+
+# Skip if no transcript
+if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+  echo "stop-sweep: skipping - transcript_path empty or missing ('$TRANSCRIPT_PATH')" >&2
+  exit 0
+fi
+
+# MCP config for obsidian-pkm server
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd -P)
+MCP_CONFIG=$(node -e "console.log(JSON.stringify({mcpServers:{'obsidian-pkm':{command:'node',args:[process.argv[1]],env:{VAULT_PATH:process.argv[2]}}}}))" "$SCRIPT_DIR/../index.js" "${VAULT_PATH:-$HOME/Documents/PKM}")
+
+PROJECT_NAME=$(basename "$CWD")
+SESSION_SHORT=$(echo "$SESSION_ID" | cut -c1-8)
+TODAY=$(date +%Y-%m-%d)
+NOW=$(date +%H:%M)
+
+# Build the prompt
+PROMPT="You are a PKM passive capture agent. Your job is to identify decisions, task changes, and research findings from the most recent conversation exchange and append them to the vault staging inbox.
+
+## Transcript
+
+Read the file at: $TRANSCRIPT_PATH
+
+Find the LAST user message and LAST assistant message at the end of the file — these are the current exchange. One exchange = one contiguous user message + one contiguous assistant response (the last complete turn pair). All prior messages are historical context only. Do NOT capture anything from prior messages.
+
+## What to Capture
+
+1. **Decisions**: Technical or architectural choices that were AGREED upon (not proposed, not still being discussed)
+2. **Task changes**: New tasks identified, tasks completed, priority changes, blockers discovered
+3. **Research findings**: Patterns discovered, library behaviors documented, gotchas found
+
+## Noise Suppression
+
+Be conservative. Skip: trivial exchanges, clarification Q&A that hasn't resolved, implementation details obvious from code, anything restating existing project context. When in doubt, don't capture.
+
+## Deduplication
+
+If the assistant message in the current exchange contains a vault_capture tool call, the content of that capture is already being handled by the explicit capture agent. Do NOT also capture it in the staging inbox — skip it to avoid semantic duplication.
+
+## Output
+
+If you find PKM-worthy content, use vault_append to add entries to 00-Inbox/captures-${TODAY}.md. If the file doesn't exist, create it first with vault_write (template: fleeting-note, tags: [capture, auto]). Each entry format:
+
+## ${NOW} — {Category}: {Title}
+
+{1-3 sentence description}
+
+**Source:** ${PROJECT_NAME}, session ${SESSION_SHORT}
+
+---
+
+If nothing is PKM-worthy, do nothing."
+
+# Spawn claude -p in background with logging
+echo "$PROMPT" | nohup claude -p --model haiku --mcp-config "$MCP_CONFIG" --max-turns 5 --allowedTools "mcp__obsidian-pkm__vault_write mcp__obsidian-pkm__vault_append mcp__obsidian-pkm__vault_read" >> "$LOG_DIR/sweep-$(date +%Y%m%d-%H%M%S).log" 2>&1 &
+
+exit 0

package/index.js

@@ -344,6 +344,40 @@ Pass custom <%...%> variables via the 'variables' parameter.`,
         },
         required: ["old_path", "new_path"]
       }
+    },
+    {
+      name: "vault_capture",
+      description: "Signal that something is worth capturing in the PKM vault. " +
+        "Returns immediately — a background agent handles the actual note creation. " +
+        "Use this when you identify a decision, task, or research finding worth preserving.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          type: {
+            type: "string",
+            enum: ["adr", "task", "research", "bug"],
+            description: "The type of capture: adr (decision), task, research (finding/pattern), bug (issue/fix)"
+          },
+          title: {
+            type: "string",
+            description: "Brief descriptive title (e.g., 'Use sqlite-vec over Chroma')"
+          },
+          content: {
+            type: "string",
+            description: "The substance of the capture — context, rationale, details. 1-5 sentences."
+          },
+          priority: {
+            type: "string",
+            enum: ["low", "normal", "high", "urgent"],
+            description: "Priority level (tasks only, default: normal)"
+          },
+          project: {
+            type: "string",
+            description: "Project name for vault routing (e.g., 'Obsidian-MCP'). If omitted, inferred from session context."
+          }
+        },
+        required: ["type", "title", "content"]
+      }
     }
   ];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pkm-mcp-server",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "MCP server for Obsidian vault integration with Claude Code — 18 tools for notes, search, and graph traversal",
   "main": "index.js",
   "exports": {
@@ -17,6 +17,7 @@
     "*.js",
     "!eslint.config.js",
     "CHANGELOG.md",
+    "hooks/",
     "templates/",
     "sample-project/"
   ],
@@ -54,7 +55,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "better-sqlite3": "^12.6.2",
     "js-yaml": "^4.1.0",
-    "sqlite-vec": "0.1.7-alpha.2"
+    "sqlite-vec": "^0.1.7"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",