pkm-mcp-server 1.4.0 → 1.4.2

package/CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.4.2] - 2026-03-21
+
+### Fixed
+- SessionStart hook crash — `load-context.js` imported `extractFrontmatter` and `extractTailSections` from parent-relative paths (`../utils.js`, `../helpers.js`) that don't exist when hooks are copied to `~/.claude/hooks/pkm/`. Inlined all three functions to make hooks fully self-contained.
+
+## [1.4.1] - 2026-03-21
+
+### Fixed
+- SessionStart hook crash when installed via `init` — `resolve-project.js` imported `resolvePath` from `../helpers.js` which doesn't exist at `~/.claude/hooks/pkm/`. Inlined the path security check to remove the external dependency.
+
 ## [1.4.0] - 2026-03-21
 
 ### Added

package/hooks/README.md

@@ -9,14 +9,14 @@ 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 |
+| `stop-sweep.js` | Stop | PKM librarian: creates structured, graph-linked vault notes from the latest exchange |
 | `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.
+- **Stop** (`stop-sweep.js`): Runs asynchronously after each assistant response. Resolves the current working directory to a vault project (no project = no captures). Spawns a background `claude -p` (Sonnet, 15 turns) that reads the transcript, classifies PKM-worthy content from the latest exchange, and creates properly structured vault notes in the project directory with wikilinks to related notes.
+- **PostToolUse** (`capture-handler.sh`): Runs asynchronously after `vault_capture` tool use. Spawns a background `claude -p` (Opus, 30 turns) that creates a properly structured vault note (ADR, task, research note, or troubleshooting log) from the capture payload with graph links.
 
 ## Setup
 
@@ -51,7 +51,7 @@ Add the following to your `~/.claude/settings.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "VAULT_PATH=\"/path/to/your/vault\" /path/to/Obsidian-MCP/hooks/stop-sweep.sh",
+            "command": "VAULT_PATH=\"/path/to/your/vault\" node /path/to/Obsidian-MCP/hooks/stop-sweep.js",
             "async": true,
             "timeout": 10
           }
@@ -85,19 +85,19 @@ The hook system uses `type: "command"` hooks (not `type: "agent"`). The shell sc
 
 - 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)
+- `--max-turns` limits how many tool calls the background process can make (15 for stop-sweep, 30 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.
+The hook scripts resolve their own location to construct the path to `index.js`. `stop-sweep.js` uses the ES module pattern (`import.meta.url` → `fileURLToPath` → `path.dirname`), while `capture-handler.sh` uses the POSIX pattern (`cd "$(dirname "$0")" && pwd -P`). Both work regardless of 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.
+Both `stop-sweep.js` 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.
+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. Deduplication is item-level: if the exchange contains a `vault_capture` call, the sweep reads its arguments and skips that specific item, but still captures other PKM-worthy content. The sweep also runs `vault_search` before creating notes to catch duplicates from concurrent sweep instances.
 
 ## Troubleshooting
 
@@ -111,7 +111,7 @@ The stop-sweep hook is conservative by design. It only looks at the last exchang
 
 - 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`
+- Test the script manually: `echo '{"cwd":"/tmp","transcript_path":"/tmp/test","session_id":"abc123"}' | VAULT_PATH="/path/to/vault" node ./hooks/stop-sweep.js`
 
 ### Background process not running
 

package/hooks/capture-handler.sh

@@ -1,7 +1,7 @@
 #!/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.
+# Runs async after vault_capture returns. Spawns claude -p with Opus
+# to create a properly structured vault note with graph links.
 
 set -euo pipefail
 
@@ -37,7 +37,11 @@ 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}")
+MCP_CONFIG=$(node -e "
+  const env = { VAULT_PATH: process.argv[2] };
+  if (process.env.OPENAI_API_KEY) env.OPENAI_API_KEY = process.env.OPENAI_API_KEY;
+  console.log(JSON.stringify({ mcpServers: { 'obsidian-pkm': { command: 'node', args: [process.argv[1]], env } } }));
+" "$SCRIPT_DIR/../index.js" "${VAULT_PATH:-$HOME/Documents/PKM}")
 
 # Build prompt via Node.js to avoid shell injection from user content
 PROMPT_FILE=$(mktemp)
@@ -71,11 +75,15 @@ const prompt = \`You are a PKM note creation agent. Your job is NOT done until t
 
 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.\`;
+5. Use vault_suggest_links with the note's content to find related notes. If the tool is available, add [[wikilinks]] to 2-3 of the most relevant suggestions in the note body using vault_edit.
+
+6. Use vault_search to verify no very similar note already exists. If a near-duplicate is found, consider appending to the existing note instead of creating a new one.
+
+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 6.\`;
 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 &
+nohup claude -p --model opus --mcp-config "$MCP_CONFIG" --max-turns 30 --allowedTools "mcp__obsidian-pkm__vault_read mcp__obsidian-pkm__vault_peek mcp__obsidian-pkm__vault_write mcp__obsidian-pkm__vault_append mcp__obsidian-pkm__vault_edit mcp__obsidian-pkm__vault_update_frontmatter mcp__obsidian-pkm__vault_search mcp__obsidian-pkm__vault_semantic_search mcp__obsidian-pkm__vault_suggest_links mcp__obsidian-pkm__vault_list mcp__obsidian-pkm__vault_recent mcp__obsidian-pkm__vault_links mcp__obsidian-pkm__vault_neighborhood mcp__obsidian-pkm__vault_query mcp__obsidian-pkm__vault_tags mcp__obsidian-pkm__vault_activity mcp__obsidian-pkm__vault_move" < "$PROMPT_FILE" >> "$LOG_DIR/capture-$(date +%Y%m%d-%H%M%S).log" 2>&1 &
 
 exit 0

package/hooks/load-context.js

@@ -1,7 +1,62 @@
 import fs from "fs/promises";
 import path from "path";
-import { extractFrontmatter } from "../utils.js";
-import { extractTailSections } from "../helpers.js";
+
+/**
+ * Extract YAML frontmatter as simple key-value pairs.
+ * Lightweight parser — only handles scalar values (sufficient for status/priority).
+ */
+function extractFrontmatter(content) {
+  if (!content.startsWith("---")) return null;
+  const endIndex = content.indexOf("\n---", 3);
+  if (endIndex === -1) return null;
+  const yamlContent = content.slice(4, endIndex);
+  const result = {};
+  for (const line of yamlContent.split("\n")) {
+    const match = line.match(/^(\w+):\s*(.+)$/);
+    if (match) result[match[1]] = match[2].trim();
+  }
+  return result;
+}
+
+function parseHeadingLevel(line) {
+  const match = line.match(/^(#{1,6})\s/);
+  return match ? match[1].length : 0;
+}
+
+/**
+ * Extract the last N sections at a given heading level from markdown content.
+ */
+function extractTailSections(content, n, level) {
+  let frontmatter = "";
+  let body = content;
+  if (content.startsWith("---")) {
+    const endIndex = content.indexOf("\n---", 3);
+    if (endIndex !== -1) {
+      frontmatter = content.slice(0, endIndex + 4);
+      body = content.slice(endIndex + 4);
+    }
+  }
+
+  const lines = body.split("\n");
+  const headingPositions = [];
+  let offset = 0;
+  for (const line of lines) {
+    if (parseHeadingLevel(line) === level) {
+      headingPositions.push(offset);
+    }
+    offset += line.length + 1;
+  }
+
+  if (headingPositions.length === 0) {
+    return content;
+  }
+
+  const startIdx = Math.max(0, headingPositions.length - n);
+  const sliceStart = headingPositions[startIdx];
+  const tail = body.slice(sliceStart);
+
+  return frontmatter + (frontmatter && !frontmatter.endsWith("\n") ? "\n" : "") + tail;
+}
 
 export async function loadProjectContext(vaultPath, projectPath) {
   const projectName = path.basename(projectPath);

package/hooks/resolve-project.js

@@ -1,6 +1,12 @@
 import fs from "fs/promises";
 import path from "path";
-import { resolvePath } from "../helpers.js";
+
+function assertPathWithinVault(relativePath, vaultPath) {
+  const resolved = path.resolve(vaultPath, relativePath);
+  if (resolved !== vaultPath && !resolved.startsWith(vaultPath + path.sep)) {
+    throw new Error("Path escapes vault directory");
+  }
+}
 
 export async function resolveProject(cwd, vaultPath) {
   try {
@@ -35,7 +41,7 @@ export async function resolveProject(cwd, vaultPath) {
     if (match) {
       const annotatedPath = match[1].trim();
       try {
-        resolvePath(annotatedPath, vaultPath);
+        assertPathWithinVault(annotatedPath, vaultPath);
       } catch (e) {
         if (e.message === "Path escapes vault directory") {
           return { error: `CLAUDE.md annotation escapes vault directory: ${annotatedPath}` };

package/hooks/stop-sweep.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { appendFileSync, closeSync, mkdirSync, openSync } from "node:fs";
+import { access } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveProject } from "./resolve-project.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const VAULT_PATH = process.env.VAULT_PATH;
+const LOG_DIR = VAULT_PATH ? join(VAULT_PATH, ".obsidian", "hook-logs") : null;
+
+function logError(message) {
+  if (!LOG_DIR) {
+    console.error(`stop-sweep: ${message}`);
+    return;
+  }
+  try {
+    mkdirSync(LOG_DIR, { recursive: true });
+    appendFileSync(join(LOG_DIR, "sweep-errors.log"), `${new Date().toISOString()} ${message}\n`);
+  } catch {
+    console.error(`stop-sweep: ${message}`);
+  }
+}
+
+async function main() {
+  // Read hook input from stdin
+  let inputJson = "";
+  for await (const chunk of process.stdin) {
+    inputJson += chunk;
+  }
+
+  let input;
+  try {
+    input = JSON.parse(inputJson);
+  } catch {
+    logError("could not parse hook input JSON");
+    return;
+  }
+
+  const { transcript_path, session_id, cwd } = input;
+
+  // Skip if no transcript
+  if (!transcript_path) return;
+  try {
+    await access(transcript_path);
+  } catch {
+    return; // transcript file missing — normal for non-conversation triggers
+  }
+
+  if (!VAULT_PATH) {
+    console.error("stop-sweep: VAULT_PATH not set");
+    return;
+  }
+
+  if (!cwd) {
+    logError("hook input missing 'cwd' field");
+    return;
+  }
+
+  // Resolve project — no project, no captures
+  const { projectPath, error } = await resolveProject(cwd, VAULT_PATH);
+  if (error || !projectPath) return;
+
+  // Build MCP config
+  const indexPath = join(__dirname, "..", "index.js");
+  const mcpEnv = { VAULT_PATH };
+  if (process.env.OPENAI_API_KEY) {
+    mcpEnv.OPENAI_API_KEY = process.env.OPENAI_API_KEY;
+  }
+  const mcpConfig = JSON.stringify({
+    mcpServers: {
+      "obsidian-pkm": {
+        command: "node",
+        args: [indexPath],
+        env: mcpEnv,
+      },
+    },
+  });
+
+  const prompt = `You are a PKM librarian agent. Your job is to identify PKM-worthy content from the most recent conversation exchange and file it correctly in the vault.
+
+## Context
+
+- Project: ${projectPath}
+- Session: ${session_id}
+- Transcript: ${transcript_path}
+
+## Step 1: Read the transcript
+
+Read the file at ${transcript_path}. Find the LAST user message and LAST assistant response — this is the current exchange. All prior messages are historical context only. Do NOT capture anything from prior messages.
+
+## Step 2: Classify what's PKM-worthy
+
+Be conservative. Most exchanges produce NOTHING worth capturing. Skip:
+- Trivial Q&A, clarifications, implementation details obvious from code
+- Anything restating existing project context
+- Content already handled by a vault_capture call in the same exchange
+  (read the vault_capture arguments to see what type/title/content was captured;
+  skip that specific item, but still capture other PKM-worthy content)
+
+Before creating any note, use vault_search to check if a very similar note already exists — another sweep instance may have captured the same content from a prior exchange in a rapid conversation.
+
+If you find something worth capturing, classify it:
+
+| Content Type | Action |
+|---|---|
+| New task identified | Create task note: vault_write(template: "task", path: "${projectPath}/tasks/{kebab-title}.md") |
+| Task completed/status changed | Find existing task via vault_query, then vault_update_frontmatter to update status |
+| Significant decision agreed upon | Create ADR: vault_write(template: "adr", path: "${projectPath}/development/decisions/ADR-NNN-{kebab-title}.md") — use vault_list on the decisions directory to find the next ADR number |
+| Research finding / gotcha | Create research note: vault_write(template: "research-note", path: "${projectPath}/research/{kebab-title}.md") |
+| Bug root cause documented | Create troubleshooting log: vault_write(template: "troubleshooting-log", path: "${projectPath}/development/debug/{kebab-title}.md") |
+| Minor implementation detail | SKIP — it's in the code/commits |
+
+## Step 3: Create/update notes properly
+
+For every note you create:
+1. Use vault_write with the correct template
+2. Use vault_edit to replace ALL template placeholders with real content
+3. Use vault_suggest_links to find related notes (skip gracefully if unavailable)
+4. Add [[wikilinks]] to the related notes in the body
+5. Verify the note has no placeholder text remaining
+
+For task updates:
+1. Use vault_query to find the task by title/tags
+2. Use vault_update_frontmatter to update status/priority
+3. Optionally vault_append to add context about what changed
+
+## Step 4: Quality check
+
+If you created any notes, read each one back to confirm:
+- No template placeholders remain
+- Wikilinks are present to related notes (if vault_suggest_links was available)
+- Frontmatter is complete and valid
+
+If nothing is PKM-worthy, do nothing. Doing nothing is the correct default.`;
+
+  // All vault tools except vault_trash and vault_capture
+  const allowedTools = [
+    "vault_read", "vault_peek", "vault_write", "vault_append", "vault_edit",
+    "vault_update_frontmatter", "vault_search", "vault_semantic_search",
+    "vault_suggest_links", "vault_list", "vault_recent", "vault_links",
+    "vault_neighborhood", "vault_query", "vault_tags", "vault_activity", "vault_move",
+  ].map(t => `mcp__obsidian-pkm__${t}`).join(" ");
+
+  // Ensure log directory exists
+  mkdirSync(LOG_DIR, { recursive: true });
+  const logFile = join(LOG_DIR, `sweep-${new Date().toISOString().replace(/[:.]/g, "").slice(0, 15)}.log`);
+  const fd = openSync(logFile, "a");
+
+  const child = spawn("claude", [
+    "-p",
+    "--model", "sonnet",
+    "--mcp-config", mcpConfig,
+    "--max-turns", "15",
+    "--allowedTools", allowedTools,
+  ], {
+    detached: true,
+    stdio: ["pipe", fd, fd],
+  });
+
+  child.on("error", (err) => {
+    logError(`spawn failed: ${err.message}`);
+  });
+
+  // Pipe prompt to stdin
+  child.stdin.write(prompt);
+  child.stdin.end();
+
+  closeSync(fd);
+
+  // Detach — let the background process run independently
+  child.unref();
+}
+
+main().catch((err) => {
+  logError(`uncaught: ${err.message}`);
+  process.exit(0);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pkm-mcp-server",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "MCP server for Obsidian vault integration with Claude Code — 19 tools for notes, search, and graph traversal",
   "main": "cli.js",
   "exports": {

package/hooks/stop-sweep.sh

@@ -1,81 +0,0 @@
-#!/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