pk

Structured project memory for AI agents. Decisions, questions, notes, and sources — organized, searchable, stored locally.

Install

One-liner (macOS / Linux):

curl -fsSL https://justestif.github.io/pk/install.sh | bash

Or manually:

# npm
npm install -g @justestif/pk

# bun
bun install -g @justestif/pk

# Homebrew
brew install justEstif/tap/pk

Requires:

• Git — tracks all knowledge operations via commits and git notes
• Bun — runtime

Note: If you have GPG commit signing enabled globally (commit.gpgsign=true), pk init bypasses it for the knowledge repo to avoid interactive prompts. No configuration needed.

Setup

pk init

Interactive: picks a project name and one or more harnesses (space to toggle, enter to confirm).

Non-interactive:

pk init my-project --harness claude
pk init my-project --harness claude,opencode   # multiple harnesses

Available harnesses: claude (Claude Code), opencode (OpenCode), pi (Pi).

pk init does three things:

1. Creates ~/.pk/<name>/ as the knowledge home for this project
2. Installs a hook or plugin that injects PK_KNOWLEDGE_DIR into the shell and calls pk prime for context
3. Installs the pk skill so your agent knows how to use the CLI

| Harness | Files written | Env injection | | ---------- | -------------------------------------------------------------------------- | ------------------------------------ | | claude | .claude/hooks/pk-session-start.sh, pk-eval.ts, .claude/settings.json| SessionStart → $CLAUDE_ENV_FILE | | opencode | .opencode/plugins/pk-eval.ts | shell.env plugin hook | | pi | .pi/extensions/pk-eval.ts | tool_call mutation |

Commands

pk init [name] [--harness h1,h2,...]   # set up project + hooks

pk new <type> <title> [--tags t1,t2]
pk delete <path>                       # JSON output, non-interactive
pk search <query> [--limit 5] [--type] [--status] [--tag] [--semantic]
pk synthesize [query] [--all]
pk history [--limit 20] [--type <type>] [--filter-type <type>] [--filter-tag <tag>] [--filter-operation <op>]
pk read <path>
pk vocab
pk index                               # rebuild FTS5 + markdown indexes
pk lint [paths...]
pk prime                               # output priming context for hooks
pk instructions <command>
pk config [--embedding <model>] [--no-embedding] [--base-url <url>]

All commands output JSON by default. Use --pretty for human-readable output.

Note types

| Type | Purpose | | ---------- | -------------------------------------------------- | | note | Durable project knowledge | | decision | Chosen direction with rationale and consequences | | question | Unresolved uncertainty that blocks or informs work | | source | Raw input preserved for provenance | | index | Navigation/map-of-content over a topic or tag |

Example

pk init acme --harness claude
pk new decision "Use SQLite for search index" --tags search,architecture
pk new question "Should we support multi-project mode?" --tags scope
pk index
pk search "sqlite"
pk synthesize

Knowledge structure

Notes live in ~/.pk/<name>/ as plain markdown files — human-editable and git-diffable. Agents access them exclusively through the CLI; humans can read and edit them directly.

~/.pk/
  <project-name>/
    notes/
    decisions/
    questions/
    sources/
    indexes/        ← generated by pk index
    .index.db       ← FTS5 search index, gitignored

Run pk index after creating or editing notes to update .index.db and indexes/.

pk vocab lists all tags by frequency — useful for orienting before searching.

pk history shows all knowledge operations (create, update, delete) as git commits and synthesize operations as git notes. Supports filtering by type, tag, and operation.

Embeddings (optional)

pk can generate embeddings via a local Ollama model and store them alongside the FTS5 index. Once enabled, pk search --semantic finds notes by meaning rather than keyword overlap.

# Install Ollama — https://ollama.com
ollama pull nomic-embed-text

# Enable embeddings
pk config --embedding nomic-embed-text

# Rebuild index to generate embeddings
pk index

# Search by meaning
pk search "slow database queries" --semantic

Embeddings are stored in .index.db and are rebuilt on pk index. FTS keyword search continues to work unchanged; --semantic is opt-in per query.

License

MIT