@justestif/pk 0.3.3 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +63 -35
  2. package/dist/index.js +26871 -13223
  3. package/package.json +22 -2
  4. package/skill/SKILL.md +22 -7
package/README.md CHANGED
@@ -1,22 +1,34 @@
1
1
  # pk
2
2
 
3
- Project knowledge CLI — structured intake, search, and recall.
3
+ Structured project memory for AI agents. Decisions, questions, notes, and sources — organized, searchable, stored locally.
4
4
 
5
5
  ## Install
6
6
 
7
- **npm:**
7
+ **One-liner (macOS / Linux):**
8
8
 
9
9
  ```bash
10
- npm install -g @justestif/pk
10
+ curl -fsSL https://justestif.github.io/pk/install.sh | bash
11
11
  ```
12
12
 
13
- **Homebrew:**
13
+ **Or manually:**
14
14
 
15
15
  ```bash
16
+ # npm
17
+ npm install -g @justestif/pk
18
+
19
+ # bun
20
+ bun install -g @justestif/pk
21
+
22
+ # Homebrew
16
23
  brew install justEstif/tap/pk
17
24
  ```
18
25
 
19
- Requires [Bun](https://bun.sh).
26
+ Requires:
27
+
28
+ - [Git](https://git-scm.com) — tracks all knowledge operations via commits and git notes
29
+ - [Bun](https://bun.sh) — runtime
30
+
31
+ > **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.
20
32
 
21
33
  ## Setup
22
34
 
@@ -30,56 +42,53 @@ Non-interactive:
30
42
 
31
43
  ```bash
32
44
  pk init my-project --harness claude
33
- pk init my-project --harness claude,codex # multiple harnesses
45
+ pk init my-project --harness claude,opencode # multiple harnesses
34
46
  ```
35
47
 
36
- **Git integration:** `pk init` creates a git repository in `~/.pk/<name>/.git` and tracks all knowledge operations via commits and git notes.
37
-
38
- Available harnesses: `claude` (Claude Code), `codex` (Codex), `opencode` (OpenCode).
48
+ Available harnesses: `claude` (Claude Code), `opencode` (OpenCode), `pi` (Pi).
39
49
 
40
50
  `pk init` does three things:
41
51
 
42
52
  1. Creates `~/.pk/<name>/` as the knowledge home for this project
43
- 2. Installs a hook or plugin that calls `pk prime` at session start to inject context into your agent
53
+ 2. Installs a hook or plugin that injects `PK_KNOWLEDGE_DIR` into the shell and calls `pk prime` for context
44
54
  3. Installs the pk skill so your agent knows how to use the CLI
45
55
 
46
- | Harness | Files written | Mechanism |
47
- |---|---|---|
48
- | `claude` | `.claude/hooks/pk-eval.ts`, `.claude/settings.json` | Hook spawns `pk prime` on every prompt |
49
- | `codex` | `AGENTS.md` | Codex reads AGENTS.md natively |
50
- | `opencode` | `.opencode/plugins/pk-eval.ts` | Plugin spawns `pk prime` at session start |
56
+ | Harness | Files written | Env injection |
57
+ | ---------- | -------------------------------------------------------------------------- | ------------------------------------ |
58
+ | `claude` | `.claude/hooks/pk-session-start.sh`, `pk-eval.ts`, `.claude/settings.json`| `SessionStart` → `$CLAUDE_ENV_FILE` |
59
+ | `opencode` | `.opencode/plugins/pk-eval.ts` | `shell.env` plugin hook |
60
+ | `pi` | `.pi/extensions/pk-eval.ts` | `tool_call` mutation |
51
61
 
52
62
  ## Commands
53
63
 
54
64
  ```bash
55
- pk init [name] [--harness h1,h2,…] # set up project + hooks
65
+ pk init [name] [--harness h1,h2,...] # set up project + hooks
56
66
 
57
67
  pk new <type> <title> [--tags t1,t2]
58
- pk edit <path> [--editor <cmd>] # edit existing note
59
- pk delete <path> [--yes] # delete note with confirmation
60
- pk search <query> [--limit 5] [--type] [--status] [--tag]
68
+ pk delete <path> # JSON output, non-interactive
69
+ pk search <query> [--limit 5] [--type] [--status] [--tag] [--semantic]
61
70
  pk synthesize [query] [--all]
62
71
  pk history [--limit 20] [--type <type>] [--filter-type <type>] [--filter-tag <tag>] [--filter-operation <op>]
63
- pk read <path> [--json]
64
- pk vocab [--json]
65
- pk rebuild
66
- pk lint [paths...] [--json]
72
+ pk read <path>
73
+ pk vocab
74
+ pk index # rebuild FTS5 + markdown indexes
75
+ pk lint [paths...]
67
76
  pk prime # output priming context for hooks
68
77
  pk instructions <command>
69
- pk config
78
+ pk config [--embedding <model>] [--no-embedding] [--base-url <url>]
70
79
  ```
71
80
 
72
- Every command supports `--json` for machine-readable output.
81
+ All commands output JSON by default. Use `--pretty` for human-readable output.
73
82
 
74
83
  ### Note types
75
84
 
76
- | Type | Purpose |
77
- |---|---|
78
- | `note` | Durable project knowledge |
79
- | `decision` | Chosen direction with rationale and consequences |
85
+ | Type | Purpose |
86
+ | ---------- | -------------------------------------------------- |
87
+ | `note` | Durable project knowledge |
88
+ | `decision` | Chosen direction with rationale and consequences |
80
89
  | `question` | Unresolved uncertainty that blocks or informs work |
81
- | `source` | Raw input preserved for provenance |
82
- | `index` | Navigation/map-of-content over a topic or tag |
90
+ | `source` | Raw input preserved for provenance |
91
+ | `index` | Navigation/map-of-content over a topic or tag |
83
92
 
84
93
  ### Example
85
94
 
@@ -87,7 +96,7 @@ Every command supports `--json` for machine-readable output.
87
96
  pk init acme --harness claude
88
97
  pk new decision "Use SQLite for search index" --tags search,architecture
89
98
  pk new question "Should we support multi-project mode?" --tags scope
90
- pk rebuild
99
+ pk index
91
100
  pk search "sqlite"
92
101
  pk synthesize
93
102
  ```
@@ -104,17 +113,36 @@ Agents access them exclusively through the CLI; humans can read and edit them di
104
113
  decisions/
105
114
  questions/
106
115
  sources/
107
- indexes/ ← generated by pk rebuild
116
+ indexes/ ← generated by pk index
108
117
  .index.db ← FTS5 search index, gitignored
109
118
  ```
110
119
 
111
- Search is powered by SQLite FTS5 with BM25 ranking and porter stemming.
112
- Partial word matching works — `pk search migr` matches "migration", "migrate", etc.
120
+ Run `pk index` after creating or editing notes to update `.index.db` and `indexes/`.
113
121
 
114
122
  `pk vocab` lists all tags by frequency — useful for orienting before searching.
115
123
 
116
124
  `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.
117
125
 
126
+ ## Embeddings (optional)
127
+
128
+ pk can generate embeddings via a local [Ollama](https://ollama.com) model and store them alongside the FTS5 index. Once enabled, `pk search --semantic` finds notes by meaning rather than keyword overlap.
129
+
130
+ ```bash
131
+ # Install Ollama — https://ollama.com
132
+ ollama pull nomic-embed-text
133
+
134
+ # Enable embeddings
135
+ pk config --embedding nomic-embed-text
136
+
137
+ # Rebuild index to generate embeddings
138
+ pk index
139
+
140
+ # Search by meaning
141
+ pk search "slow database queries" --semantic
142
+ ```
143
+
144
+ 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.
145
+
118
146
  ## License
119
147
 
120
148
  MIT