PKM - Personal Knowledge Management Skill

You are a specialist in using

pkm

, a Personal Knowledge Management system that provides a knowledge layer between Claude Code (MCP) and lancer/LanceDB. PKM offers temporal awareness, quality filtering, token-efficient search, and document curation tools for managing workspace knowledge.

What is PKM?

pkm

is an advanced knowledge management system that provides:

Temporal awareness: Track document freshness and identify stale content
Quality filtering: Filter by certainty level and information type (facts, analysis, ideas)
Hybrid search: Combines vector (semantic) and BM25 (full-text) search
Relationship tracking: Document wikilinks, references, and backlinks
Quality audits: Systematic review of knowledge base quality
LSP server: Wikilink autocomplete in editors
MCP integration: Claude Desktop integration for intelligent search

Core Capabilities

Index: Index workspace documents (titles and/or content)
Search: Search with quality filters (certainty, info type, freshness)
Relationships: Track document relationships and wikilinks
Backlinks: Query what links to a document
Quality Audit: Review and improve knowledge base quality
Stats: Analyze indexed content statistics
LSP/MCP: Editor integration and Claude Desktop integration

Quick Start

Basic Search

bash

# Search workspace documents
pkm search "kubernetes deployment strategies"

# Search with quality filters
pkm search --facts-only --fresh-only "API authentication"

# Search with result limit
pkm search -n 5 "error handling patterns"

Basic Indexing

bash

# Index current directory (both titles and content)
pkm index

# Index specific directory
pkm index ~/Documents/notes/

# Index specific files
pkm index note1.md note2.md

Document Indexing

Index Command Options

bash

# Index both titles and content (default)
pkm index ./notes/

# Index only titles (LSP autocomplete)
pkm index --titles-only ./notes/

# Index only content (search)
pkm index --content-only ./notes/

# Index to specific table
pkm index --table my_knowledge ./notes/

# Index specific file extensions
pkm index --extensions md,txt,pdf ./documents/

# Force re-index
pkm index --force ./notes/

Index from stdin

bash

# Pipe file paths to index
find ~/Documents -name "*.md" -mtime -7 | pkm index --stdin

# From git changed files
git diff --name-only main | grep "\.md$" | pkm index --stdin

Index Modes

Hybrid index (default):

bash

# Vector + BM25 full-text search
pkm index ./notes/

Vector-only index:

bash

# Skip BM25 (faster indexing, semantic search only)
pkm index --no-hybrid ./notes/

Index Management

bash

# Quiet mode (suppress progress)
pkm index --quiet ./large-corpus/

# Dry run (see what would be indexed)
pkm index --dry-run ./notes/

# Verbose logging
pkm index -v ./notes/

Search Operations

Search Command Options

bash

# Basic search
pkm search "machine learning algorithms"

# Limit results
pkm search -n 10 "API design patterns"

# Set minimum score threshold
pkm search --min-score 0.1 "database optimization"

# Specify database path
pkm search --db-path ~/my-db "query"

# Specify workspace root
pkm search --workspace-root ~/Documents "query"

# Custom table name
pkm search --table-name custom_table "query"

Quality Filters

Filter by information type:

bash

# Show only facts
pkm search --info-type fact "kubernetes architecture"
pkm search --facts-only "docker commands"

# Show only analysis
pkm search --info-type analysis "performance bottlenecks"

# Show only ideas
pkm search --info-type idea "feature proposals"

Filter by certainty:

bash

# High certainty only
pkm search --certainty high "security best practices"

# Medium certainty
pkm search --certainty medium "migration strategies"

# Low certainty (speculative)
pkm search --certainty low "future trends"

Filter by freshness:

bash

# Maximum age in days
pkm search --max-age 30 "recent updates"

# Only fresh documents
pkm search --fresh-only "current status"

# Exclude stale documents
pkm search --exclude-stale "active projects"

Combined Filters

bash

# Facts from last 30 days
pkm search \
  --facts-only \
  --max-age 30 \
  "authentication implementation"

# High certainty analysis (fresh)
pkm search \
  --info-type analysis \
  --certainty high \
  --fresh-only \
  "performance optimization"

# Recent ideas with threshold
pkm search \
  --info-type idea \
  --max-age 14 \
  --min-score 0.15 \
  -n 5 \
  "feature enhancements"

Output Formats

bash

# Text output (default)
pkm search "query"

# JSON output for scripting
pkm search --output json "query" | jq '.results[] | .path'

# Verbose logging
pkm search -v "query"

Relationship Tracking

Query Outgoing Relationships

bash

# Show all links from a document
pkm relationships --source notes/architecture.md

# Filter by relationship type
pkm relationships --source notes/api.md --rel-type wikilink

# JSON output
pkm relationships --source notes/design.md --output json

Query Backlinks

bash

# Show what links to a document
pkm backlinks notes/concepts/auth.md

# Filter by relationship type
pkm backlinks notes/api-spec.md --rel-type reference

# JSON output
pkm backlinks notes/design.md --output json

Relationship Use Cases

bash

# Find related documents
pkm relationships --source current-work.md

# Discover document impact
pkm backlinks important-concept.md

# Build knowledge graph
pkm relationships --source index.md --output json | \
  jq '.relationships[] | .target'

# Find orphaned documents (no backlinks)
pkm backlinks my-note.md | grep -q "No backlinks" && \
  echo "Orphaned document"

Index a Single Document

bash

# Index document for relationship tracking
pkm index-doc notes/new-concept.md

# With custom database
pkm index-doc --db-path ~/kb notes/article.md

# Verbose output
pkm index-doc -v notes/research.md

Quality Management

Quality Audit

bash

# Audit entire workspace
pkm quality-audit

# Audit specific area/topic
pkm quality-audit --area kubernetes

# JSON output
pkm quality-audit --output json

# Verbose audit
pkm quality-audit -v

What quality-audit checks:

Documents missing quality metadata
Stale documents needing updates
Low certainty information
Missing or unclear info types
Document completeness

Find Stale Documents

bash

# Find documents exceeding freshness threshold
pkm find-stale

# With workspace root
pkm find-stale --workspace-root ~/Documents/notes

# Verbose output
pkm find-stale -v

Verification Queue

bash

# Show documents needing review
pkm verify-queue

# With specific workspace
pkm verify-queue --workspace-root ~/kb

# Verbose output
pkm verify-queue -v

Statistics and Analysis

Workspace Statistics

bash

# Show basic stats
pkm stats

# Detailed breakdown by file extension
pkm stats -d

# Detailed stats with custom database
pkm stats --db-path ~/my-kb -d

# JSON output
pkm stats --output json

Stats include:

Total documents indexed
Document counts by type
Table information
Embedding models used
Index sizes

Table Management

List Tables

bash

# List all tables in database
pkm tables

# With custom database path
pkm tables --db-path ~/my-kb

# Verbose output
pkm tables -v

Server Modes

LSP Server (Wikilink Autocomplete)

bash

# Start LSP server for editor integration
pkm lsp

# With verbose logging
pkm lsp -v

Purpose: Provides wikilink autocomplete in editors (VSCode, Neovim, etc.)

MCP Server (Claude Desktop)

bash

# Start MCP server
pkm mcp

# With verbose logging
pkm mcp -v

Purpose: Integrates PKM search into Claude Desktop for intelligent document retrieval.

Environment Variables

bash

# Set default database path
export PKM_DB_PATH=~/my-knowledge-base
pkm search "query"

# Set workspace root
export PKM_ROOT=~/Documents/notes
pkm index

# Both together
export PKM_DB_PATH=~/kb
export PKM_ROOT=~/notes
pkm search "query"

Common Workflows

Workflow 1: Initial Workspace Setup

bash

# 1. Index your workspace
cd ~/Documents/notes
pkm index

# 2. Check statistics
pkm stats -d

# 3. Test search
pkm search "recent projects"

# 4. Run quality audit
pkm quality-audit

Workflow 2: Daily Knowledge Work

bash

# 1. Find stale documents to review
pkm find-stale

# 2. Search for high-quality facts
pkm search --facts-only --certainty high "project status"

# 3. Index new/modified documents
find . -name "*.md" -mtime -1 | pkm index --stdin

# 4. Check relationships
pkm relationships --source today-notes.md

Workflow 3: Research and Analysis

bash

# 1. Search for recent analysis
pkm search \
  --info-type analysis \
  --max-age 30 \
  --certainty high \
  -n 20 \
  "performance optimization"

# 2. Find related documents
pkm relationships --source research-notes.md

# 3. Discover citations
pkm backlinks key-concept.md

# 4. Export for review
pkm search --output json "research topic" | \
  jq '.results[] | {path, score, summary}' > research.json

Workflow 4: Knowledge Base Maintenance

bash

# 1. Find documents needing review
pkm verify-queue

# 2. Run quality audit
pkm quality-audit --output json > audit-results.json

# 3. Find stale content
pkm find-stale

# 4. Re-index updated documents
pkm index --force ./updated-notes/

# 5. Verify improvements
pkm stats -d

Workflow 5: Incremental Updates

bash

# 1. Find recently modified files
find ~/notes -name "*.md" -mtime -7 > recent.txt

# 2. Index only recent changes
pkm index --stdin < recent.txt

# 3. Search fresh content
pkm search --max-age 7 "latest updates"

# 4. Update statistics
pkm stats -d

Workflow 6: Integration with Git

bash

# Index files changed in current branch
git diff --name-only main | \
  grep "\.md$" | \
  pkm index --stdin

# Index uncommitted changes
git diff --name-only | \
  grep "\.md$" | \
  pkm index --stdin

# Re-index entire repository
pkm index --force .

Best Practices

1. Index Strategically

Title indexing (fast, for autocomplete):

bash

pkm index --titles-only ~/notes/

Content indexing (comprehensive, for search):

bash

pkm index --content-only ~/important-docs/

Full indexing (both):

bash

pkm index ~/knowledge-base/

2. Use Quality Filters Effectively

For verified information:

bash

pkm search --facts-only --certainty high "API endpoints"

For recent insights:

bash

pkm search --info-type analysis --max-age 14 "optimization"

For brainstorming:

bash

pkm search --info-type idea --exclude-stale "features"

3. Maintain Freshness

bash

# Regular freshness check
pkm find-stale

# Periodic re-indexing
pkm index --force ./active-projects/

# Exclude stale from searches
pkm search --exclude-stale "current work"

4. Track Relationships

bash

# After creating new note with wikilinks
pkm index-doc new-note.md
pkm relationships --source new-note.md

# Understand impact before editing
pkm backlinks important-concept.md

5. Regular Quality Audits

bash

# Weekly audit
pkm quality-audit --output json > audit-$(date +%Y%m%d).json

# Area-specific review
pkm quality-audit --area architecture

# Track verification queue
pkm verify-queue

6. Organize with Extensions

bash

# Index markdown notes
pkm index --extensions md ~/notes/

# Include PDFs and markdown
pkm index --extensions md,pdf ~/research/

# Text files only
pkm index --extensions txt ~/logs/

7. Use Appropriate Thresholds

Broad exploration:

bash

pkm search --min-score 0.05 "general topic"

Balanced results:

bash

pkm search --min-score 0.1 "specific concept"

High precision:

bash

pkm search --min-score 0.2 "exact information"

Integration Setups

Claude Desktop (MCP)

Add to

~/Library/Application Support/Claude/claude_desktop_config.json

json

{
  "mcpServers": {
    "pkm": {
      "command": "pkm",
      "args": ["mcp"],
      "env": {
        "PKM_ROOT": "/Users/username/Documents/notes",
        "PKM_DB_PATH": "/Users/username/.pkm/db"
      }
    }
  }
}

VSCode (LSP)

Start LSP server:
```
pkm lsp
```
Configure editor to connect to LSP endpoint
Get wikilink autocomplete in markdown files

Advanced Usage

Custom Database Locations

bash

# Work with multiple knowledge bases
pkm search --db-path ~/work-kb "work queries"
pkm search --db-path ~/personal-kb "personal queries"

# Separate workspace and database
pkm index \
  --workspace-root ~/Documents/notes \
  --db-path ~/kb/notes-index

Scripting and Automation

bash

# Daily index automation
#!/bin/bash
cd ~/notes
find . -name "*.md" -mtime -1 | pkm index --quiet --stdin
pkm stats --output json > ~/stats/$(date +%Y%m%d).json

# Weekly quality report
#!/bin/bash
pkm quality-audit --output json > audit.json
pkm find-stale > stale.txt
pkm verify-queue > queue.txt

Batch Processing

bash

# Process multiple directories
for dir in ~/notes/*/; do
  echo "Indexing $dir"
  pkm index "$dir"
done

# Selective re-indexing
pkm stats --output json | \
  jq -r '.tables[] | select(.doc_count < 10) | .name' | \
  xargs -I {} pkm index --force --table {}

Troubleshooting

Issue: Search returns no results

Solutions:

bash

# Check if content is indexed
pkm stats -d

# Lower score threshold
pkm search --min-score 0.01 "query"

# Remove quality filters
pkm search "query"  # No filters

# Verify database path
pkm search --db-path ~/kb -v "query"

Issue: Stale documents not detected

Solutions:

bash

# Force re-index
pkm index --force .

# Check verbose output
pkm find-stale -v

# Verify workspace root
pkm find-stale --workspace-root ~/notes

Issue: Relationships not tracked

Solutions:

bash

# Index document for relationships
pkm index-doc document.md

# Verbose indexing
pkm index-doc -v document.md

# Re-index entire workspace
pkm index --force .

Issue: Poor search quality

Solutions:

bash

# Enable hybrid search (vector + BM25)
pkm index .  # Default is hybrid

# Adjust filters
pkm search --min-score 0.05 "query"

# Check for sufficient indexed content
pkm stats -d

Issue: LSP/MCP not working

Solutions:

bash

# Verify server starts
pkm lsp -v
pkm mcp -v

# Check environment variables
echo $PKM_ROOT
echo $PKM_DB_PATH

# Restart server
pkill -f "pkm lsp"
pkm lsp -v

Quick Reference

bash

# Indexing
pkm index                                # Index current directory
pkm index ~/notes/                       # Index specific directory
pkm index --titles-only ~/notes/         # Titles only (LSP)
pkm index --force ~/notes/               # Force re-index
pkm index --extensions md,pdf ~/docs/    # Specific file types

# Searching
pkm search "query"                       # Basic search
pkm search -n 10 "query"                 # Limit results
pkm search --facts-only "query"          # Facts only
pkm search --fresh-only "query"          # Fresh only
pkm search --certainty high "query"      # High certainty
pkm search --max-age 30 "query"          # Last 30 days

# Relationships
pkm relationships --source note.md       # Show outgoing links
pkm backlinks note.md                    # Show incoming links
pkm index-doc note.md                    # Index for relationships

# Quality management
pkm quality-audit                        # Audit workspace
pkm find-stale                          # Find stale documents
pkm verify-queue                        # Documents needing review
pkm stats -d                            # Detailed statistics

# Servers
pkm mcp                                 # Start MCP server
pkm lsp                                 # Start LSP server

# Output formats
pkm search --output json "query"        # JSON output
pkm stats --output json                 # JSON stats
pkm quality-audit --output json         # JSON audit

Common Patterns

Pattern 1: Quick Fact Lookup

bash

pkm search --facts-only --certainty high -n 5 "API authentication"

Pattern 2: Recent Analysis

bash

pkm search --info-type analysis --max-age 30 --fresh-only "optimization"

Pattern 3: Explore Related Content

bash

pkm relationships --source research.md && \
pkm backlinks research.md

Pattern 4: Daily Maintenance

bash

find . -name "*.md" -mtime -1 | pkm index --quiet --stdin && \
pkm find-stale

Pattern 5: Quality-Focused Search

bash

pkm search \
  --facts-only \
  --certainty high \
  --fresh-only \
  --min-score 0.15 \
  -n 10 \
  "deployment procedures"

Summary

Primary use cases:

Personal knowledge management with quality awareness
Temporal tracking of document freshness
Relationship discovery and backlink tracking
Quality audits and knowledge base maintenance
Integration with Claude via MCP

Key advantages:

Quality filtering (certainty, info type)
Freshness tracking (temporal awareness)
Hybrid search (semantic + full-text)
Relationship tracking (wikilinks, backlinks)
Token-efficient results for Claude
LSP integration for editor autocomplete

Most common commands:

```
pkm index ~/notes/
```
- Index workspace

pkm search --facts-only --fresh-only "query"

- Quality search

```
pkm relationships --source note.md
```
- Find relationships
```
pkm quality-audit
```
- Audit knowledge base
```
pkm stats -d
```
- Analyze workspace

pkm

NPX Install

Tags

SKILL.md Content

PKM - Personal Knowledge Management Skill

What is PKM?

Core Capabilities

Quick Start

Basic Search

Basic Indexing

Document Indexing

Index Command Options

Index from stdin

Index Modes

Index Management

Search Operations

Search Command Options

Quality Filters

Combined Filters

Output Formats

Relationship Tracking

Query Outgoing Relationships

Query Backlinks

Relationship Use Cases

Index a Single Document

Quality Management

Quality Audit

Find Stale Documents

Verification Queue

Statistics and Analysis

Workspace Statistics

Table Management

List Tables

Server Modes

LSP Server (Wikilink Autocomplete)

MCP Server (Claude Desktop)

Environment Variables

Common Workflows

Workflow 1: Initial Workspace Setup

Workflow 2: Daily Knowledge Work

Workflow 3: Research and Analysis

Workflow 4: Knowledge Base Maintenance

Workflow 5: Incremental Updates

Workflow 6: Integration with Git

Best Practices

1. Index Strategically

2. Use Quality Filters Effectively

3. Maintain Freshness

4. Track Relationships

5. Regular Quality Audits

6. Organize with Extensions

7. Use Appropriate Thresholds

Integration Setups

Claude Desktop (MCP)

VSCode (LSP)

Advanced Usage

Custom Database Locations

Scripting and Automation

Batch Processing

Troubleshooting

Issue: Search returns no results

Issue: Stale documents not detected

Issue: Relationships not tracked

Issue: Poor search quality

Issue: LSP/MCP not working

Quick Reference

Common Patterns

Pattern 1: Quick Fact Lookup

Pattern 2: Recent Analysis

Pattern 3: Explore Related Content

Pattern 4: Daily Maintenance

Pattern 5: Quality-Focused Search

Summary