Pkm

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

1. Index: Index workspace documents (titles and/or content)
2. Search: Search with quality filters (certainty, info type, freshness)
3. Relationships: Track document relationships and wikilinks
4. Backlinks: Query what links to a document
5. Quality Audit: Review and improve knowledge base quality
6. Stats: Analyze indexed content statistics
7. 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)

1. Start LSP server: pkm lsp
2. Configure editor to connect to LSP endpoint
3. 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