name	pkm
description	Use pkm for personal knowledge management with temporal awareness, quality filtering, hybrid search, and relationship tracking with LSP and MCP server integration.

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

# 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

# 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

# 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

# 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):

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

Vector-only index:

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

Index Management

# 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

# 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:

# 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:

# 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:

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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)

# 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)

# Start MCP server
pkm mcp

# With verbose logging
pkm mcp -v

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

Environment Variables

# 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

# 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

# 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

# 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

# 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

# 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

# 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):

pkm index --titles-only ~/notes/

Content indexing (comprehensive, for search):

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

Full indexing (both):

pkm index ~/knowledge-base/

2. Use Quality Filters Effectively

For verified information:

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

For recent insights:

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

For brainstorming:

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

3. Maintain Freshness

# 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

# 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

# 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

# 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:

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

Balanced results:

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

High precision:

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

Integration Setups

Claude Desktop (MCP)

Add to ~/Library/Application Support/Claude/claude_desktop_config.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

# 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

# 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

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

# 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

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

Pattern 2: Recent Analysis

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

Pattern 3: Explore Related Content

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

Pattern 4: Daily Maintenance

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

Pattern 5: Quality-Focused Search

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

Install Skill

SKILL.md

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