@cad0p/pi-napkin 0.2.4
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.
- package/LICENSE +22 -0
- package/README.md +377 -0
- package/extensions/distill/README.md +86 -0
- package/extensions/distill/auto-setup.ts +480 -0
- package/extensions/distill/distill-workspace.ts +1344 -0
- package/extensions/distill/index.ts +1808 -0
- package/extensions/distill/scripts/distill-wrapper.sh +692 -0
- package/extensions/distill/scripts/git_retry.sh +65 -0
- package/extensions/distill/scripts/napkin-distill-merge +455 -0
- package/extensions/distill/scripts-paths.ts +30 -0
- package/extensions/distill/session-touched-files.ts +216 -0
- package/extensions/distill/should-distill-on-shutdown.ts +68 -0
- package/extensions/napkin-context/index.ts +259 -0
- package/package.json +68 -0
- package/skills/napkin/SKILL.md +44 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Michael Liv (upstream Michaelliv/pi-napkin)
|
|
4
|
+
Copyright (c) 2026 Pier Carlo Cadoppi (cad0p/pi-napkin fork)
|
|
5
|
+
|
|
6
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
7
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
8
|
+
in the Software without restriction, including without limitation the rights
|
|
9
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
10
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
11
|
+
furnished to do so, subject to the following conditions:
|
|
12
|
+
|
|
13
|
+
The above copyright notice and this permission notice shall be included in all
|
|
14
|
+
copies or substantial portions of the Software.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
17
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
18
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
19
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
20
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
21
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
22
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,377 @@
|
|
|
1
|
+
# pi-napkin
|
|
2
|
+
|
|
3
|
+
๐งป [Napkin](https://github.com/cad0p/napkin) integration for [pi](https://github.com/badlogic/pi-mono).
|
|
4
|
+
|
|
5
|
+
Gives a pi agent first-class access to an Obsidian-compatible knowledge vault, with automatic knowledge distillation that safely captures conversation context into notes as you work.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
pi-napkin depends on the [`@cad0p/napkin`](https://github.com/cad0p/napkin) CLI. Install it first:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install -g @cad0p/napkin
|
|
13
|
+
# or: bun add -g @cad0p/napkin
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Then install the pi-napkin extension:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
pi install npm:@cad0p/pi-napkin
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
<details>
|
|
23
|
+
<summary>Pre-release / dev installs</summary>
|
|
24
|
+
|
|
25
|
+
- Pre-release (calver snapshots from `main`, published to npm `@next` on every push):
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
pi install npm:@cad0p/pi-napkin@next
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
pi pins npm installs with an explicit tag or version โ `pi update` won't auto-bump this. Re-run the install to pick up newer `@next` builds.
|
|
32
|
+
|
|
33
|
+
- Install from source for local development:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pi install git:github.com/cad0p/pi-napkin
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
</details>
|
|
40
|
+
|
|
41
|
+
## What you get
|
|
42
|
+
|
|
43
|
+
Two pi extensions, one skill, two slash commands, one agent tool.
|
|
44
|
+
|
|
45
|
+
### Extensions
|
|
46
|
+
|
|
47
|
+
| Extension | What it does |
|
|
48
|
+
|---|---|
|
|
49
|
+
| `napkin-context` | On session start, injects the vault overview into the agent's context. Registers `kb_search` + `kb_read` tools. |
|
|
50
|
+
| `napkin-distill` | Automatic knowledge distillation. Runs on a timer and at shutdown, forks the conversation, and asks a cheap model to extract structured notes into the vault. |
|
|
51
|
+
|
|
52
|
+
### Skill
|
|
53
|
+
|
|
54
|
+
The [`napkin` skill](skills/napkin/SKILL.md) gives the agent a full CLI reference โ all commands, flags, and patterns.
|
|
55
|
+
|
|
56
|
+
### Slash commands
|
|
57
|
+
|
|
58
|
+
- `/distill` โ Trigger a manual distill now. Works in any vault; does not require git.
|
|
59
|
+
- `/distill-auto-this-session` โ Turn the automatic timer off / on for the current session. Persists across pi restarts.
|
|
60
|
+
- `/distill-status` โ Show active background distill processes for the current vault.
|
|
61
|
+
|
|
62
|
+
### Agent tool
|
|
63
|
+
|
|
64
|
+
- `napkin_distill_status` โ JSON version of `/distill-status`, for the agent to query programmatically before making concurrent vault edits.
|
|
65
|
+
|
|
66
|
+
## Auto-distill requires subdir vault layout
|
|
67
|
+
|
|
68
|
+
Auto-distill (interval + shutdown) uses git worktrees for concurrency safety.
|
|
69
|
+
That requires the vault to use napkin's **subdir layout** โ the config in a
|
|
70
|
+
`.napkin/` subdir distinct from the content root:
|
|
71
|
+
|
|
72
|
+
```
|
|
73
|
+
my-vault/
|
|
74
|
+
.napkin/
|
|
75
|
+
config.json โ napkin config here, with `"vault": { "root": ".." }`
|
|
76
|
+
NAPKIN.md
|
|
77
|
+
changelog/
|
|
78
|
+
daily/
|
|
79
|
+
โฆ
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
`napkin init` creates this layout by default, so freshly created vaults work out
|
|
83
|
+
of the box. If your vault uses the **legacy embedded layout** (config at
|
|
84
|
+
`<vault>/config.json` with no `.napkin/` subdir, where `configPath ===
|
|
85
|
+
contentPath`), you'll see a migration notification at session start and
|
|
86
|
+
auto-distill will be disabled for the session. Legacy layout continues to
|
|
87
|
+
work for manual `/distill` (which doesn't need concurrency safety) and for
|
|
88
|
+
napkin CLI commands generally โ only auto-distill requires the subdir
|
|
89
|
+
layout.
|
|
90
|
+
|
|
91
|
+
### Why
|
|
92
|
+
|
|
93
|
+
Worktree-based concurrency relies on the worktree having a `.napkin/`
|
|
94
|
+
subdir post-checkout, so the wrapper's `git add -A` + `git commit` +
|
|
95
|
+
`git merge --squash` operations on the worktree see the isolated
|
|
96
|
+
vault layout. On a subdir-layout vault, the branch tracks
|
|
97
|
+
`.napkin/config.json`, so every checked-out worktree has the
|
|
98
|
+
`.napkin/` subdir. On a legacy-embedded vault, the branch has no
|
|
99
|
+
`.napkin/` subdir at all (`.napkin/` IS the vault), so the worktree
|
|
100
|
+
has nothing to operate on โ the wrapper would silently produce empty
|
|
101
|
+
commits, and the per-distill napkin shim's `--vault $WORKTREE` would
|
|
102
|
+
point at a directory napkin doesn't recognize as a vault. The
|
|
103
|
+
concurrency guarantee silently degrades to nothing.
|
|
104
|
+
|
|
105
|
+
### Where worktrees live
|
|
106
|
+
|
|
107
|
+
Active distill worktrees are placed under
|
|
108
|
+
`$XDG_CACHE_HOME/napkin-distill/<vault-hash>/<id>/` (typically
|
|
109
|
+
`~/.cache/napkin-distill/โฆ`), outside your vault. `<vault-hash>` is
|
|
110
|
+
`sha256(contentPath).slice(0, 16)` so worktrees from multiple vaults never
|
|
111
|
+
collide. External placement avoids:
|
|
112
|
+
|
|
113
|
+
- **Cloud-sync pollution** โ OneDrive/Dropbox don't respect `.gitignore`;
|
|
114
|
+
in-vault worktrees would upload tens of MB per distill spawn.
|
|
115
|
+
- **Filesystem-walker pollution** โ Obsidian plugins and `find` descend
|
|
116
|
+
into worktrees and see N full vault copies for N concurrent distills.
|
|
117
|
+
- **Autocommit-cron noise** โ gitlinks can surface in `git status` under
|
|
118
|
+
some command sequences; external placement eliminates the surface.
|
|
119
|
+
|
|
120
|
+
Inspect active distills with `/distill-status`. If you ever need to nuke
|
|
121
|
+
all distill state for a vault (stuck lock, etc.):
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
rm -rf ~/.cache/napkin-distill/<hash>/
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Safe โ anything valuable is either already committed to main or was
|
|
128
|
+
never going to commit.
|
|
129
|
+
|
|
130
|
+
### Migration from legacy layout
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
# From your vault directory (e.g. ~/.napkin or wherever configPath == contentPath)
|
|
134
|
+
mkdir .napkin
|
|
135
|
+
mv config.json .napkin/config.json
|
|
136
|
+
# Edit .napkin/config.json and add at the top level:
|
|
137
|
+
# "vault": { "root": ".." }
|
|
138
|
+
# After editing, reload pi (or /quit and restart).
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Verify with `napkin vault --json` โ the `path` field should point at
|
|
142
|
+
`<vault>/.napkin/` (that's the new configPath) and napkin should still
|
|
143
|
+
find all your notes.
|
|
144
|
+
|
|
145
|
+
## Vault resolution
|
|
146
|
+
|
|
147
|
+
Both extensions use napkin's built-in vault resolution. The resolution order is:
|
|
148
|
+
|
|
149
|
+
1. **Local project vault** โ walk up from cwd looking for `.napkin/` (or `.obsidian/.napkin/`)
|
|
150
|
+
2. **Global fallback** โ read `$XDG_CONFIG_HOME/napkin/config.json` (defaults to `~/.config/napkin/config.json`)
|
|
151
|
+
3. **Bare vault** โ create a new vault at cwd as a last resort
|
|
152
|
+
|
|
153
|
+
```json
|
|
154
|
+
// ~/.config/napkin/config.json
|
|
155
|
+
{
|
|
156
|
+
"vault": "~/path/to/vault"
|
|
157
|
+
}
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Local project vaults take priority when present.
|
|
161
|
+
|
|
162
|
+
### Migrating from `~/.pi/agent/napkin.json`
|
|
163
|
+
|
|
164
|
+
If you previously configured your vault in `~/.pi/agent/napkin.json`, move it to the new location:
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
mkdir -p ~/.config/napkin
|
|
168
|
+
cp ~/.pi/agent/napkin.json ~/.config/napkin/config.json
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## Auto-distill
|
|
172
|
+
|
|
173
|
+
Auto-distill is the core feature. It runs in the background without prompting the user, periodically forking your pi session and asking a cheap model to extract knowledge into the vault. It's off by default.
|
|
174
|
+
|
|
175
|
+
### Enable it
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
napkin --vault ~/path/to/vault config set --key distill.enabled --value true
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Or edit `<vault>/.napkin/config.json` directly:
|
|
182
|
+
|
|
183
|
+
```jsonc
|
|
184
|
+
{
|
|
185
|
+
"distill": {
|
|
186
|
+
"enabled": true,
|
|
187
|
+
"intervalMinutes": 60,
|
|
188
|
+
"onShutdown": true,
|
|
189
|
+
"model": { "provider": "kiro", "id": "claude-sonnet-4-6" }
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
### Config keys
|
|
195
|
+
|
|
196
|
+
| Setting | Default | Description |
|
|
197
|
+
|---|---|---|
|
|
198
|
+
| `distill.enabled` | `false` | Master switch. When false, nothing auto-distill related happens. |
|
|
199
|
+
| `distill.intervalMinutes` | `60` | Timer interval. |
|
|
200
|
+
| `distill.maxDurationMinutes` | `10` | Maximum wall-clock duration a detached distill subprocess is allowed before the parent's poll loop declares it stuck and force-cleans its worktree. Values `<= 0` or non-finite silently fall back to the 10-minute default so a bad config can't disable the timeout entirely. Lower this for short-session vaults where a 10-minute hang is unacceptable; raise it for vaults with large merge windows or slow providers. |
|
|
201
|
+
| `distill.onShutdown` | `true` | Also run a final distill at pi shutdown, to capture anything the interval missed. |
|
|
202
|
+
| `distill.model.provider` | `"anthropic"` | Model provider for the distill subprocess. |
|
|
203
|
+
| `distill.model.id` | `"claude-sonnet-4-6"` | Model ID. Prefer a cheap, fast model โ distill is automated, not interactive. |
|
|
204
|
+
|
|
205
|
+
### How it works
|
|
206
|
+
|
|
207
|
+
When enabled, on session start the extension:
|
|
208
|
+
|
|
209
|
+
1. Runs `ensureVaultReadyForAutoDistill` on the vault (see below) โ git-inits if needed and scaffolds `.gitignore` / `.gitattributes`.
|
|
210
|
+
2. Sweeps stale distill worktrees left by crashed pi instances (`cleanupStaleWorktrees`).
|
|
211
|
+
3. Arms a timer (`intervalMinutes`) that spawns a detached `pi -p` subprocess on tick.
|
|
212
|
+
4. On shutdown (unless `distill.onShutdown` is false or the session file is already captured), spawns one final distill.
|
|
213
|
+
|
|
214
|
+
Each distill subprocess gets its own isolated copy of the vault via `git worktree add`. See [Concurrency](#concurrency) below.
|
|
215
|
+
|
|
216
|
+
The distill subprocess runs a prompt that asks the model to:
|
|
217
|
+
- Learn the vault structure via `napkin overview` and `_about.md` files
|
|
218
|
+
- Read the templates via `napkin template list`
|
|
219
|
+
- Search for existing notes on a topic before creating duplicates
|
|
220
|
+
- Create or append to notes as appropriate
|
|
221
|
+
- Add `[[wikilinks]]` to related notes
|
|
222
|
+
- Tag superseded notes with `supersedes: ["path/to/old.md"]` frontmatter for a future janitor to archive
|
|
223
|
+
|
|
224
|
+
### Auto-init on first use
|
|
225
|
+
|
|
226
|
+
When you enable `distill.enabled: true` on a vault that isn't a git repo, pi-napkin auto-initializes it on the next session start:
|
|
227
|
+
|
|
228
|
+
1. Runs `git init`.
|
|
229
|
+
2. Scaffolds `.gitignore` (excludes `.napkin/distill/` โ the per-worktree session fork) and `.gitattributes` (routes `*.md` through the LLM merge driver). Distill worktrees themselves live outside the vault (see [Where worktrees live](#where-worktrees-live)), so `.gitignore` doesn't need to exclude them.
|
|
230
|
+
3. Commits everything as `napkin: initial vault commit (auto-distill setup)`.
|
|
231
|
+
4. Notifies you once, with instructions to undo (`rm -rf <vault>/.git`) or opt out (`distill.enabled: false`).
|
|
232
|
+
|
|
233
|
+
Auto-distill requires git **and** the subdir vault layout (see [Auto-distill requires subdir vault layout](#auto-distill-requires-subdir-vault-layout)). Manual `/distill` requires neither โ it just spawns a detached `pi -p` with the session forked to a temp dir, no worktree.
|
|
234
|
+
|
|
235
|
+
### Running an auto-distill loop
|
|
236
|
+
|
|
237
|
+
Once configured, nothing further is required: open any pi session in a directory under the vault and the timer arms automatically. You'll see a `distill: Xm..s` countdown in the status bar and a one-time notice when a distill begins, completes, or fails.
|
|
238
|
+
|
|
239
|
+
To pause for the current session only (e.g., you're drafting sensitive content you don't want captured):
|
|
240
|
+
|
|
241
|
+
```
|
|
242
|
+
/distill-auto-this-session off
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
Toggles back on with `/distill-auto-this-session on`. State persists across pi restarts of that same session.
|
|
246
|
+
|
|
247
|
+
## Concurrency
|
|
248
|
+
|
|
249
|
+
Running multiple pi sessions against the same vault (for example, autonomous agent fleets spawning many sessions in parallel) or having Obsidian open while a distill is running would race on file writes. pi-napkin uses git worktrees to make this safe.
|
|
250
|
+
|
|
251
|
+
### Worktree per distill
|
|
252
|
+
|
|
253
|
+
Each auto-distill invocation (interval fire or shutdown) creates its own temporary branch and worktree under `$XDG_CACHE_HOME/napkin-distill/<vault-hash>/<branch-suffix>/` (typically `~/.cache/napkin-distill/โฆ`). pi runs at the **parent session's cwd** (not the worktree) so the system prompt's `Current working directory:` line stays byte-identical to the parent's, preserving prompt-cache hits. Vault writes from the agent's bash tool are routed back to the worktree by a per-distill napkin shim at `<worktree>/.napkin/distill/bin/napkin` that injects `--vault <worktree>` into every napkin invocation. The wrapper's own git operations (`git add` / `commit` / `merge --squash`) all run with `git -C <worktree>` against the isolated checkout. See [Where worktrees live](#where-worktrees-live) for why the worktree dir is external to the vault.
|
|
254
|
+
|
|
255
|
+
### LLM merge driver
|
|
256
|
+
|
|
257
|
+
When the distill commits its changes and merges back to main, conflicts are resolved by a custom git merge driver (`.napkin-distill-merge`) that calls the same model as the distill itself. The driver is registered per-worktree via `git config --local` and routed at the file level by an `*.md merge=napkin-distill-merge` entry in `.gitattributes`.
|
|
258
|
+
|
|
259
|
+
The driver makes three attempts per conflict. After three strikes, the driver exits 1 and git leaves conflict markers โ handled by the next step.
|
|
260
|
+
|
|
261
|
+
### Partial-merge salvage
|
|
262
|
+
|
|
263
|
+
If the LLM merge driver fails on some files, we don't abort the whole merge. Files that merged cleanly keep the distill's content; files that failed fall back to main's version via `git checkout main -- <file>`.
|
|
264
|
+
|
|
265
|
+
Think of it as: "save what you can, log what you lost." A per-failure entry is written to `<vault>/.napkin/distill/errors/` so you can inspect what was discarded, and the dangling distill commit SHA is kept for ~2 weeks of git gc grace in case you want to recover it manually.
|
|
266
|
+
|
|
267
|
+
### Linear history
|
|
268
|
+
|
|
269
|
+
Successful distill lifecycles produce exactly one squash commit on `main`, with an LLM-generated summary message. This keeps history clean and makes it easy to revert a bad distill with `git revert <sha>`.
|
|
270
|
+
|
|
271
|
+
## Agent visibility
|
|
272
|
+
|
|
273
|
+
When a background distill completes a squash-merge that touches files you've also written this session, pi-napkin posts a one-line notice into the conversation as a custom session message so the agent knows its recent writes may have been merged or overwritten:
|
|
274
|
+
|
|
275
|
+
```
|
|
276
|
+
โ ๏ธ Background napkin distill is editing files you've also touched: notes/foo.md.
|
|
277
|
+
Recent writes to these files may be overwritten or merged automatically at distill
|
|
278
|
+
completion; consider re-reading before further edits.
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
Key properties:
|
|
282
|
+
- **Trigger**: per distill completion (when the wrapper's squash-merge has landed and the worktree is gone), not per agent turn. Files actually changing in the parent's view is the right moment to surface the overlap.
|
|
283
|
+
- **Channel**: posted via `appendCustomMessageEntry` with `customType: "napkin-distill-overlap"`. Lives in session history (so distill subprocesses inherit it cleanly via session-fork) and is displayed in the TUI so you see it too.
|
|
284
|
+
- **Cache parity**: custom messages land at the END of the message array, so Anthropic-style prompt caching's prefix stays byte-identical. The notice itself becomes a one-time cache write rather than the recurring cache-bust the previous per-turn `appendSystemPrompt` mechanism produced.
|
|
285
|
+
- **Frequency**: bounded by the per-distill-completion trigger โ typically ~5โ12 messages/day for an active session, only when actual file overlap exists.
|
|
286
|
+
- **Cursor**: each completion only considers entries added since the previous completion. On a fresh session this starts at 0; on a resumed session it starts at the pre-resume entry count, so resume doesn't surface stale notices for files written in earlier pi processes.
|
|
287
|
+
|
|
288
|
+
The session-touched-files detector reimplements pi's internal `extractFileOpsFromMessage` (not exported from pi) and tracks `write`, `edit`, and bash-redirection-style writes. A companion version-check test (`session-touched-files.version-check.test.ts`) pins pi's upstream utility so we get an explicit test failure if pi renames / removes it.
|
|
289
|
+
|
|
290
|
+
## Vault setup
|
|
291
|
+
|
|
292
|
+
### New vault
|
|
293
|
+
|
|
294
|
+
```bash
|
|
295
|
+
mkdir my-vault && cd my-vault
|
|
296
|
+
napkin init
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
Then edit `.napkin/config.json` to set `distill.enabled: true`. On first pi session in the vault, auto-distill will auto-init git for you.
|
|
300
|
+
|
|
301
|
+
### Existing Obsidian vault
|
|
302
|
+
|
|
303
|
+
Just `cd` into it and run `pi`. napkin will detect `.obsidian/` and treat it as a vault. The `.napkin/` config dir lives alongside `.obsidian/`.
|
|
304
|
+
|
|
305
|
+
If you want auto-distill on an existing Obsidian vault:
|
|
306
|
+
|
|
307
|
+
1. Set `distill.enabled: true` in `.napkin/config.json` (create the file if missing).
|
|
308
|
+
2. Start a pi session in the vault.
|
|
309
|
+
3. On session start, pi-napkin prompts to auto-init git if the vault isn't already one.
|
|
310
|
+
|
|
311
|
+
If your vault IS already a git repo (common for "vault as project"), pi-napkin just adds the `.gitignore` / `.gitattributes` scaffolds and moves on.
|
|
312
|
+
|
|
313
|
+
## Troubleshooting
|
|
314
|
+
|
|
315
|
+
### "No vault in cwd"
|
|
316
|
+
|
|
317
|
+
Some command or tool couldn't resolve a vault from the current directory. Either:
|
|
318
|
+
- Run from a directory under a vault (any ancestor with `.napkin/` or `.obsidian/`)
|
|
319
|
+
- Set the global fallback in `~/.config/napkin/config.json`
|
|
320
|
+
- Pass `--vault <path>` to the napkin CLI
|
|
321
|
+
|
|
322
|
+
### Auto-distill stopped working
|
|
323
|
+
|
|
324
|
+
Check `/distill-status` to see if there are stale / dead worktrees. The next session start will sweep them automatically (`cleanupStaleWorktrees`). If that doesn't help, nuke the per-vault cache dir:
|
|
325
|
+
|
|
326
|
+
```bash
|
|
327
|
+
rm -rf ~/.cache/napkin-distill/<vault-hash>/
|
|
328
|
+
# Or, if you're not sure which hash matches your vault, the nuclear option:
|
|
329
|
+
rm -rf ~/.cache/napkin-distill/
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
Safe โ anything valuable is either already committed to main or was never going to commit.
|
|
333
|
+
|
|
334
|
+
### Merge driver fails repeatedly
|
|
335
|
+
|
|
336
|
+
Error log: `<vault>/.napkin/distill/errors/<ISO-timestamp>-<pid>-<branch-hash>.log`.
|
|
337
|
+
|
|
338
|
+
Each log has the conflicted files, the last LLM response, and an optional one-liner describing the failure. Common causes:
|
|
339
|
+
|
|
340
|
+
- Model is rate-limited โ retry later.
|
|
341
|
+
- LLM returned empty / tiny / huge output โ driver sanity-check rejects it. Usually a transient provider issue.
|
|
342
|
+
- Conflicted content is genuinely unmergeable (same line added with different content) โ the partial-merge salvage falls back to main's version; the distill commit SHA is kept in reflog for ~2 weeks if you want to recover it.
|
|
343
|
+
|
|
344
|
+
### "vault not a git repo" / "legacy embedded layout"
|
|
345
|
+
|
|
346
|
+
Auto-distill requires **git** and the **subdir vault layout**. If you see:
|
|
347
|
+
|
|
348
|
+
- `vault not a git repo` โ either set `distill.enabled: true` and let pi-napkin auto-init git for you on next session, run `git init` in the vault root manually, or disable auto-distill with `distill.enabled: false`.
|
|
349
|
+
- `legacy embedded layout` โ follow the [migration steps](#migration-from-legacy-layout). Auto-distill stays off for this session; manual `/distill` works regardless.
|
|
350
|
+
|
|
351
|
+
Manual `/distill` works without git and works on any vault layout.
|
|
352
|
+
|
|
353
|
+
### Testing hooks
|
|
354
|
+
|
|
355
|
+
The distill wrapper (`extensions/distill/scripts/distill-wrapper.sh`) reads several environment variables that exist solely to make integration tests deterministic. Production code never sets them; documenting here so future maintainers know they exist and what they do, and so a future-you grepping for one of these names can land on this section.
|
|
356
|
+
|
|
357
|
+
| Variable | Purpose |
|
|
358
|
+
|---|---|
|
|
359
|
+
| `NAPKIN_DISTILL_PI_BIN` | Override the `pi` binary path. Tests point this at `/usr/bin/true` (exits 0 quickly) or a stub script so the wrapper completes its lifecycle without contacting a real LLM. |
|
|
360
|
+
| `NAPKIN_DISTILL_MERGE_MOCK` | Forwarded to `napkin-distill-merge` (the LLM driver). Set to `fail` to force every conflict to 3-strike, or `ok-after-N` to succeed after N attempts. Used to exercise the partial-merge salvage path. |
|
|
361
|
+
| `NAPKIN_DISTILL_SKIP_PI=1` | Skip BOTH the napkin shim install AND the `pi` invocation. Used by tests that pre-stage file changes manually and only want to exercise the wrapper's git lifecycle (commit/merge/squash). |
|
|
362
|
+
| `NAPKIN_DISTILL_HALT_AFTER_META=1` | Halt right after rewriting `meta.json`'s pid to the wrapper's pid. Lets tests inspect the updated meta without the cleanup trap wiping the worktree. Clears the `EXIT` trap so cleanup is skipped โ caller is responsible for tearing down the worktree afterwards. |
|
|
363
|
+
| `NAPKIN_DISTILL_HALT_AFTER_SHIM=1` | Halt right after the per-distill napkin shim is installed at `<worktree>/.napkin/distill/bin/napkin`. Lets tests inspect the shim contents and PATH injection without the cleanup trap firing. |
|
|
364
|
+
| `NAPKIN_DISTILL_FORCE_MERGE_HEAD=1` | Force `MERGE_HEAD` to exist right before the escape-hatch check. Lets tests cover the belt-and-braces "merge did not complete" bail-out path, which isn't reliably triggerable via real driver output (git clears `MERGE_HEAD` on driver exit 0). |
|
|
365
|
+
| `NAPKIN_DISTILL_FORCE_MERGE_RC=<n>` | Override the captured merge exit code. Lets tests cover the unexpected-exit-code branch (128 etc.) without contriving a real git failure of that shape. |
|
|
366
|
+
|
|
367
|
+
Production never sets any of these. If you find one in your environment by accident, `unset` it and re-run โ the wrapper falls back to its normal behaviour automatically.
|
|
368
|
+
|
|
369
|
+
## Future: builder-deleter
|
|
370
|
+
|
|
371
|
+
Next major feature: a "builder-deleter" janitor that acts on the `supersedes:` frontmatter convention that auto-distill already writes. When a note lists `supersedes: ["old/note.md"]`, the janitor archives the superseded file. Threshold-triggered to avoid running on every distill, git gc as the safety net.
|
|
372
|
+
|
|
373
|
+
See [features/pi-napkin-distill/builder-deleter](https://github.com/cad0p/pi-napkin/blob/main/features/) (design pending) for the full design.
|
|
374
|
+
|
|
375
|
+
## License
|
|
376
|
+
|
|
377
|
+
MIT
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# napkin-distill
|
|
2
|
+
|
|
3
|
+
Pi extension that automatically distills knowledge from conversations into your napkin vault.
|
|
4
|
+
|
|
5
|
+
## How it works
|
|
6
|
+
|
|
7
|
+
1. Runs on a configurable interval (default: 60 minutes)
|
|
8
|
+
2. Checks if the conversation changed since last distill
|
|
9
|
+
3. Sends the new conversation to a model
|
|
10
|
+
4. The model extracts structured notes using your vault's templates
|
|
11
|
+
5. Notes are written directly into the vault
|
|
12
|
+
|
|
13
|
+
## Setup
|
|
14
|
+
|
|
15
|
+
Enable distill in your vault config:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
napkin config set --key distill.enabled --value true
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Or edit `.napkin/config.json` directly:
|
|
22
|
+
|
|
23
|
+
```json
|
|
24
|
+
{
|
|
25
|
+
"distill": {
|
|
26
|
+
"enabled": true,
|
|
27
|
+
"intervalMinutes": 60,
|
|
28
|
+
"model": {
|
|
29
|
+
"provider": "anthropic",
|
|
30
|
+
"id": "claude-sonnet-4-6"
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Configuration
|
|
37
|
+
|
|
38
|
+
All distill settings live in `.napkin/config.json` under the `distill` key:
|
|
39
|
+
|
|
40
|
+
| Field | Default | Description |
|
|
41
|
+
|-------|---------|-------------|
|
|
42
|
+
| `distill.enabled` | `false` | Enable automatic distillation |
|
|
43
|
+
| `distill.intervalMinutes` | `60` | How often to check for new content |
|
|
44
|
+
| `distill.model.provider` | `"anthropic"` | LLM provider |
|
|
45
|
+
| `distill.model.id` | `"claude-sonnet-4-6"` | Model for distillation |
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
## Manual trigger
|
|
49
|
+
|
|
50
|
+
Use `/distill` in pi to manually trigger distillation of the full conversation.
|
|
51
|
+
|
|
52
|
+
## Turn off for this session
|
|
53
|
+
|
|
54
|
+
`/distill-auto-this-session` turns auto-distill off or on for the current session only. Manual `/distill` still works regardless.
|
|
55
|
+
|
|
56
|
+
| Invocation | Effect |
|
|
57
|
+
|------------|--------|
|
|
58
|
+
| `/distill-auto-this-session` | Toggle (on โ off) |
|
|
59
|
+
| `/distill-auto-this-session on` | Turn auto-distill on |
|
|
60
|
+
| `/distill-auto-this-session off` | Turn auto-distill off |
|
|
61
|
+
| `/distill-auto-this-session status` | Report current state and time to next run |
|
|
62
|
+
|
|
63
|
+
### Status bar indicator
|
|
64
|
+
|
|
65
|
+
| Display | Meaning |
|
|
66
|
+
|---------|---------|
|
|
67
|
+
| `distill: 59m30s` | Auto-distill is on โ countdown to next run |
|
|
68
|
+
| `distill: off (session)` | Auto-distill is off for this session |
|
|
69
|
+
| `distill: off` | Distill is disabled at the vault level (`distill.enabled=false`) |
|
|
70
|
+
| `โ distill 12s` | A distillation is currently running |
|
|
71
|
+
|
|
72
|
+
### Persistence
|
|
73
|
+
|
|
74
|
+
The off/on state is written into the session file as a `CustomEntry` (it does not enter the LLM context). Resuming the same session with `pi --session <path>` โ or picking it from the session list โ restores the state. Other sessions (and new sessions) are unaffected.
|
|
75
|
+
|
|
76
|
+
On resume, a brief notification reminds you when auto-distill is still off, so you don't lose track of it.
|
|
77
|
+
|
|
78
|
+
Turning auto-distill back on resets the countdown so the next run respects the full interval instead of firing immediately.
|
|
79
|
+
|
|
80
|
+
Persistent vault-wide opt-out still lives in `.napkin/config.json` (`distill.enabled`).
|
|
81
|
+
|
|
82
|
+
### Notes
|
|
83
|
+
|
|
84
|
+
- `/distill-auto-this-session off` does **not** interrupt a distillation already in flight. It only suppresses future scheduled runs.
|
|
85
|
+
- If `distill.enabled` is `false` in the vault config, the command warns that the session flag has no effect โ enable distill in the vault config first.
|
|
86
|
+
- Forking a session with auto-distill off carries the state forward (the CustomEntry is copied with the rest of the session). Run `/distill-auto-this-session on` in the fork to turn it back on.
|