pkm-mcp-server 1.4.1 → 1.4.2

package/CHANGELOG.md

@@ -6,6 +6,11 @@ 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

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/stop-sweep.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { spawn } from "node:child_process";
-import { appendFileSync, createWriteStream, mkdirSync } from "node:fs";
+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";
@@ -147,6 +147,7 @@ If nothing is PKM-worthy, do nothing. Doing nothing is the correct default.`;
   // 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",
@@ -156,17 +157,18 @@ If nothing is PKM-worthy, do nothing. Doing nothing is the correct default.`;
     "--allowedTools", allowedTools,
   ], {
     detached: true,
-    stdio: ["pipe", "pipe", "pipe"],
+    stdio: ["pipe", fd, fd],
+  });
+
+  child.on("error", (err) => {
+    logError(`spawn failed: ${err.message}`);
   });
 
   // Pipe prompt to stdin
   child.stdin.write(prompt);
   child.stdin.end();
 
-  // Log stdout and stderr to file
-  const logStream = createWriteStream(logFile, { flags: "a" });
-  child.stdout.pipe(logStream);
-  child.stderr.pipe(logStream);
+  closeSync(fd);
 
   // Detach — let the background process run independently
   child.unref();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pkm-mcp-server",
-  "version": "1.4.1",
+  "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