threadnote 0.7.11 → 0.7.12
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/README.md +2 -422
- package/dist/mcp_server.cjs +2 -2
- package/docs/index.html +70 -7
- package/docs/web-manager.png +0 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -10,7 +10,8 @@
|
|
|
10
10
|
It is intentionally scoped to curated docs, memories, skills, and handoffs. It is not a source-navigation replacement,
|
|
11
11
|
and it does not index whole repositories by default.
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
**Walkthrough:** https://kashkovsky.github.io/threadnote/
|
|
14
|
+
**Wiki:** https://github.com/Kashkovsky/threadnote/wiki
|
|
14
15
|
|
|
15
16
|
## Real-World Uses
|
|
16
17
|
|
|
@@ -47,424 +48,3 @@ which memory to keep/update, which old handoffs to archive, and which exact dupl
|
|
|
47
48
|
Use `threadnote remember --replace <uri>` or `threadnote handoff --replace <uri>` to keep one current-state memory fresh
|
|
48
49
|
instead of accumulating near-duplicate progress notes. Replacing a shared `durable/` URI updates that shared memory in
|
|
49
50
|
place and pushes the shared repo, so you do not need a separate `share publish` step.
|
|
50
|
-
|
|
51
|
-
## Memory Lifecycle
|
|
52
|
-
|
|
53
|
-
Threadnote separates current durable knowledge from the historical handoff trail.
|
|
54
|
-
|
|
55
|
-
New `remember` records default to `kind: durable` and `status: active`. New `handoff` records use `kind: handoff` and
|
|
56
|
-
`status: active`. Add `--project` and `--topic` when the memory represents an ongoing issue or stable fact:
|
|
57
|
-
|
|
58
|
-
```bash
|
|
59
|
-
threadnote remember --project threadnote --topic install-health --text "Install/repair waits for OpenViking health."
|
|
60
|
-
threadnote handoff --project threadnote --topic lifecycle-storage --task "Implement lifecycle-aware memories"
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
Active memories with the same project/topic write to a stable lifecycle path, so later updates replace the current
|
|
64
|
-
version instead of creating another timestamped note. Untagged memories still use timestamped files when you want a
|
|
65
|
-
historical trail.
|
|
66
|
-
|
|
67
|
-
For feature branches, keep a durable feature memory and an active handoff side by side with the same project/topic:
|
|
68
|
-
|
|
69
|
-
```bash
|
|
70
|
-
threadnote remember --kind durable --project my-repo --topic feature-x --text "Feature knowledge: ..."
|
|
71
|
-
threadnote handoff --project my-repo --topic feature-x --task "Current status for feature X"
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
Agents should update the durable feature memory when valuable implementation knowledge changes, and update the handoff
|
|
75
|
-
when current status, tests, blockers, or next steps change.
|
|
76
|
-
|
|
77
|
-
Bare `threadnote handoff` defaults to the current repo and current git branch as its stable project/topic, so routine
|
|
78
|
-
handoffs update one active branch record. Use `threadnote handoff --timestamped` only when you intentionally want a
|
|
79
|
-
historical note.
|
|
80
|
-
|
|
81
|
-
Use `compact` when active memories for a project/topic start to overlap:
|
|
82
|
-
|
|
83
|
-
```bash
|
|
84
|
-
threadnote compact --project my-repo --topic feature-x --dry-run
|
|
85
|
-
threadnote compact --project my-repo --topic feature-x --apply
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
The dry-run plan is the default. Applying archives stale handoffs, forgets only exact duplicates, and preserves source
|
|
89
|
-
`viking://` URIs in the kept memory. Ambiguous durable or incident memories are left for manual review.
|
|
90
|
-
|
|
91
|
-
Use `archive` when an old handoff is useful for provenance but should stop being treated as current working context:
|
|
92
|
-
|
|
93
|
-
```bash
|
|
94
|
-
threadnote archive viking://user/example/memories/handoffs/active/threadnote/lifecycle-storage.md
|
|
95
|
-
threadnote recall --query "threadnote lifecycle storage"
|
|
96
|
-
threadnote recall --query "threadnote lifecycle storage" --include-archived
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
If OpenViking is still processing the original file, `archive` keeps the archived copy and tells you to retry
|
|
100
|
-
`threadnote forget <uri>` later.
|
|
101
|
-
|
|
102
|
-
## Why Not Just CLAUDE.md Or AGENTS.md?
|
|
103
|
-
|
|
104
|
-
Use them. Threadnote is not a replacement for checked-in instructions.
|
|
105
|
-
|
|
106
|
-
`CLAUDE.md`, `AGENTS.md`, Cursor rules, and repo docs are the right place for stable, canonical guidance: coding
|
|
107
|
-
standards, test commands, review rules, architecture notes, and anything the whole team should version and discuss.
|
|
108
|
-
|
|
109
|
-
They are less ideal for living context: what happened in the last agent session, which branch was halfway through a
|
|
110
|
-
refactor, what an on-call investigation concluded, which workaround was verified on one machine, or which duplicate
|
|
111
|
-
memories should be compacted. Putting that history into instruction files makes them noisy, stale, and expensive to load
|
|
112
|
-
into every context window.
|
|
113
|
-
|
|
114
|
-
Threadnote keeps that moving layer local, searchable, and shared across agents. Agents recall only the relevant durable
|
|
115
|
-
feature memories, handoffs, and skill/resource pointers when they need them, while the source files stay authoritative
|
|
116
|
-
for project rules.
|
|
117
|
-
|
|
118
|
-
The split is simple: put durable repo policy in `CLAUDE.md`/`AGENTS.md`; put feature knowledge, task history, handoffs,
|
|
119
|
-
personal workflow facts, and local cross-agent memory in Threadnote.
|
|
120
|
-
|
|
121
|
-
## Safety Model
|
|
122
|
-
|
|
123
|
-
- Machine writes stay **locally** under `THREADNOTE_HOME`, which defaults to `~/.openviking`.
|
|
124
|
-
- Curated manifests only: seed commands import only paths listed in `config/seed-manifest.example.yaml` or an explicit
|
|
125
|
-
per-developer manifest.
|
|
126
|
-
- Ignore rules: `.threadnoteignore` excludes build output, binary artifacts, local auth files, env files, and logs.
|
|
127
|
-
- Redaction: known config files such as `.mcp.json`, `config.toml`, and settings JSON are copied through a redactor
|
|
128
|
-
before import.
|
|
129
|
-
- Secret scanning: candidate files are skipped if common token or private-key patterns remain after redaction.
|
|
130
|
-
- User instructions: `install` upserts managed Threadnote guidance in `~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`,
|
|
131
|
-
`~/.cursor/rules/threadnote.md`, and `~/.copilot/instructions/threadnote.instructions.md` without replacing existing
|
|
132
|
-
personal instructions.
|
|
133
|
-
- Agent config changes are explicit: `mcp-install` prints commands and snippets by default; use `--apply` to run them.
|
|
134
|
-
|
|
135
|
-
## Install
|
|
136
|
-
|
|
137
|
-
Install with one command:
|
|
138
|
-
|
|
139
|
-
```bash
|
|
140
|
-
curl -fsSL https://raw.githubusercontent.com/Kashkovsky/threadnote/main/scripts/install.sh | sh
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
This installs the published package from npmjs and runs `threadnote install`. The install command sets up local config,
|
|
144
|
-
repairs the OpenViking Python environment, and starts the local server so health problems surface immediately. It does
|
|
145
|
-
not use npm `postinstall`, because setup writes local machine config and should be an explicit action.
|
|
146
|
-
|
|
147
|
-
Confirm it is healthy:
|
|
148
|
-
|
|
149
|
-
```bash
|
|
150
|
-
threadnote doctor --dry-run
|
|
151
|
-
```
|
|
152
|
-
|
|
153
|
-
If install or health checks fail, see [Troubleshooting](docs/troubleshooting.md).
|
|
154
|
-
|
|
155
|
-
To force a runtime:
|
|
156
|
-
|
|
157
|
-
```bash
|
|
158
|
-
curl -fsSL https://raw.githubusercontent.com/Kashkovsky/threadnote/main/scripts/install.sh | THREADNOTE_RUNTIME=bun sh
|
|
159
|
-
curl -fsSL https://raw.githubusercontent.com/Kashkovsky/threadnote/main/scripts/install.sh | THREADNOTE_RUNTIME=deno sh
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
Or install manually:
|
|
163
|
-
|
|
164
|
-
```bash
|
|
165
|
-
npm install --global threadnote
|
|
166
|
-
threadnote install
|
|
167
|
-
threadnote doctor --dry-run
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
### Update
|
|
171
|
-
|
|
172
|
-
Threadnote occasionally checks npm for a newer published version when you run human-facing commands such as `doctor`,
|
|
173
|
-
`start`, `install`, or `repair`. The check is cached under `THREADNOTE_HOME` and never runs in CI or when
|
|
174
|
-
`THREADNOTE_NO_UPDATE_CHECK` or `NO_UPDATE_NOTIFIER` is set.
|
|
175
|
-
|
|
176
|
-
Update the package and refresh local shims, user instructions, and MCP config with one command:
|
|
177
|
-
|
|
178
|
-
```bash
|
|
179
|
-
threadnote update
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
Check without changing anything:
|
|
183
|
-
|
|
184
|
-
```bash
|
|
185
|
-
threadnote version
|
|
186
|
-
threadnote update --check
|
|
187
|
-
threadnote update --dry-run
|
|
188
|
-
```
|
|
189
|
-
|
|
190
|
-
`threadnote version` prints the installed version, latest npm version, and GitHub release notes. When no update is
|
|
191
|
-
available, it shows the current release notes; when an update is available, it shows every newer version. `threadnote
|
|
192
|
-
update` prints the same full "What's new" diff when an update is available.
|
|
193
|
-
|
|
194
|
-
After updating, restart Cursor, Copilot, Codex, Claude, or open a fresh agent session so MCP tools reload.
|
|
195
|
-
|
|
196
|
-
Some releases include post-update memory migrations. `threadnote update` runs the new package's migration prompt after
|
|
197
|
-
repair, explains what will change, and asks before applying it. Use `threadnote update --yes` for unattended local
|
|
198
|
-
migrations or `threadnote update --no-post-update` to skip them.
|
|
199
|
-
|
|
200
|
-
Applied migrations are tracked by id under `THREADNOTE_HOME`, and migration commands are written to be safe to rerun.
|
|
201
|
-
|
|
202
|
-
If you update from an older Threadnote version that only knew how to run `repair`, the new repair step will still detect
|
|
203
|
-
applicable migrations and print the manual command to run next.
|
|
204
|
-
|
|
205
|
-
### MCP
|
|
206
|
-
|
|
207
|
-
Make the agents you use aware of Threadnote. Use only the MCP install lines for agents you actually use. Open a fresh
|
|
208
|
-
agent session after installing MCP so the new server registration is loaded.
|
|
209
|
-
|
|
210
|
-
Dry-run examples:
|
|
211
|
-
|
|
212
|
-
```bash
|
|
213
|
-
threadnote mcp-install codex
|
|
214
|
-
threadnote mcp-install claude
|
|
215
|
-
threadnote mcp-install cursor
|
|
216
|
-
threadnote mcp-install copilot
|
|
217
|
-
```
|
|
218
|
-
|
|
219
|
-
Apply after review:
|
|
220
|
-
|
|
221
|
-
```bash
|
|
222
|
-
threadnote mcp-install codex --apply
|
|
223
|
-
threadnote mcp-install claude --apply
|
|
224
|
-
threadnote mcp-install cursor --apply
|
|
225
|
-
threadnote mcp-install copilot --apply
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
Claude installs at `user` scope by default so the same OpenViking MCP server is available from any repo or worktree.
|
|
229
|
-
Use `--scope local` or `--scope project` only when you intentionally want repo-scoped Claude MCP config.
|
|
230
|
-
Cursor installs by updating the global `~/.cursor/mcp.json` file.
|
|
231
|
-
Copilot installs by updating the VS Code user-profile `mcp.json` file. Set `THREADNOTE_COPILOT_MCP_CONFIG` if you use a
|
|
232
|
-
custom VS Code profile or want to test against a temporary file.
|
|
233
|
-
|
|
234
|
-
If the package or checkout that originally installed `threadnote` has moved, run repair:
|
|
235
|
-
|
|
236
|
-
```bash
|
|
237
|
-
threadnote repair
|
|
238
|
-
```
|
|
239
|
-
|
|
240
|
-
This rewrites the `threadnote` shim and reinstalls the stdio MCP adapter for available agents so launcher paths point
|
|
241
|
-
at the current checkout.
|
|
242
|
-
|
|
243
|
-
The default install uses the bundled stdio MCP adapter, because OpenViking `0.3.12` does not expose the native `/mcp`
|
|
244
|
-
HTTP route:
|
|
245
|
-
|
|
246
|
-
```bash
|
|
247
|
-
codex mcp add threadnote -- threadnote-mcp-server
|
|
248
|
-
claude mcp add threadnote -- threadnote-mcp-server
|
|
249
|
-
```
|
|
250
|
-
|
|
251
|
-
Cursor uses the equivalent entry in `~/.cursor/mcp.json`.
|
|
252
|
-
Copilot uses the VS Code MCP `servers` entry in the user-profile `mcp.json`.
|
|
253
|
-
|
|
254
|
-
### Agent hooks (optional, opt-in)
|
|
255
|
-
|
|
256
|
-
The instruction files (`~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`, etc.) are the **cross-agent guidance floor** — they
|
|
257
|
-
ask agents to recall context, store handoffs, and so on, and they work for every supported agent. They rely on the
|
|
258
|
-
agent to comply.
|
|
259
|
-
|
|
260
|
-
For deterministic moments where the agent shouldn't have to remember, Threadnote can also install agent-side
|
|
261
|
-
**hooks** — currently for Claude Code (the only supported agent that exposes a hook surface today):
|
|
262
|
-
|
|
263
|
-
- **`PreCompact`** auto-stores a handoff snapshot for the current repo right before Claude compacts the conversation,
|
|
264
|
-
so the next turn can recall it even if the agent forgot to write a handoff manually.
|
|
265
|
-
- **`SessionStart`** preloads the latest threadnote handoff/feature memory for the current repo into the new session
|
|
266
|
-
context, so the first turn already knows where you left off. The same hook also runs a daily-cached check against
|
|
267
|
-
the npm registry and prints a one-line `[threadnote] vX.Y.Z available; run threadnote update` banner when the
|
|
268
|
-
installed version is behind, so you stop missing releases. Set `THREADNOTE_AUTO_UPDATE=1` to skip the nag and have
|
|
269
|
-
the hook spawn `threadnote update --yes` in the background instead — the new version takes effect on the next
|
|
270
|
-
session.
|
|
271
|
-
|
|
272
|
-
Install them per agent (Codex / Cursor / Copilot are no-ops today — Threadnote prints a clear explanation):
|
|
273
|
-
|
|
274
|
-
```bash
|
|
275
|
-
threadnote install-hooks claude --dry-run # preview the change
|
|
276
|
-
threadnote install-hooks claude --apply # add managed entries to ~/.claude/settings.json
|
|
277
|
-
threadnote install-hooks claude --remove --apply # take them out again
|
|
278
|
-
```
|
|
279
|
-
|
|
280
|
-
Or opt in at install time and let Threadnote drive every supported agent in one shot:
|
|
281
|
-
|
|
282
|
-
```bash
|
|
283
|
-
threadnote install --with-hooks
|
|
284
|
-
```
|
|
285
|
-
|
|
286
|
-
Managed entries are tagged with `"_threadnote": "managed"` so `threadnote repair` and `threadnote uninstall` can find
|
|
287
|
-
and rewrite/remove only those entries without touching any of your own hooks. Hooks complement, not replace, the
|
|
288
|
-
instruction files: the soft guidance covers semantic decisions ("is this memory durable?", "is this work meaningful
|
|
289
|
-
enough to publish?"); hooks cover deterministic moments the agent shouldn't be trusted to remember.
|
|
290
|
-
|
|
291
|
-
If a future OpenViking build exposes a healthy native endpoint, install it explicitly:
|
|
292
|
-
|
|
293
|
-
```bash
|
|
294
|
-
threadnote mcp-install claude --native-http --apply
|
|
295
|
-
```
|
|
296
|
-
|
|
297
|
-
### Seed Local Repos
|
|
298
|
-
|
|
299
|
-
Memories and handoffs work before seeding. Seed local repos when you want agents to recall repo guidance, docs, and
|
|
300
|
-
skills without reopening the same files by hand.
|
|
301
|
-
|
|
302
|
-
Create or update the local manifest with the repos you care about:
|
|
303
|
-
|
|
304
|
-
```bash
|
|
305
|
-
threadnote init-manifest --repo ~/src/my-service --repo ~/work/mobile-app
|
|
306
|
-
```
|
|
307
|
-
|
|
308
|
-
Review what will be imported, then seed curated repo guidance:
|
|
309
|
-
|
|
310
|
-
```bash
|
|
311
|
-
threadnote seed --dry-run
|
|
312
|
-
threadnote seed
|
|
313
|
-
```
|
|
314
|
-
|
|
315
|
-
For Git worktrees, seed the stable checkout by default:
|
|
316
|
-
|
|
317
|
-
```bash
|
|
318
|
-
threadnote init-manifest --repo ~/src/coda
|
|
319
|
-
```
|
|
320
|
-
|
|
321
|
-
You usually do not need to add every temporary worktree such as `~/src/worktrees/coda/my-branch`. Threadnote treats each
|
|
322
|
-
worktree path as its own manifest project today, so adding every worktree can duplicate seeded repo resources and make
|
|
323
|
-
recall noisier. Add a worktree only when it is long-lived or has branch-specific docs, instructions, or repo-local skills
|
|
324
|
-
that should be recalled separately.
|
|
325
|
-
|
|
326
|
-
Optionally seed shared and repo-local skills. This imports existing `SKILL.md` files as a searchable resource catalog so
|
|
327
|
-
agents can discover relevant workflow guidance; it does not install or activate skills in the agent runtime.
|
|
328
|
-
|
|
329
|
-
```bash
|
|
330
|
-
threadnote seed-skills --dry-run
|
|
331
|
-
threadnote seed-skills
|
|
332
|
-
```
|
|
333
|
-
|
|
334
|
-
When you add another local repo later, rerun `init-manifest --repo <path>` and seed again.
|
|
335
|
-
|
|
336
|
-
This is it! Start working with your agents as usual. The agent will automatically recall relevant memories and store the new ones. If you want to force it to recall/handoff something, just ask explicitly.
|
|
337
|
-
|
|
338
|
-
## Commands
|
|
339
|
-
|
|
340
|
-
- `doctor`: checks prerequisites, the generated command shim, manifest shape, templates, and local OpenViking health.
|
|
341
|
-
- `install`: installs `openviking[local-embed]==0.3.12` if missing, creates `~/.openviking` config files if absent,
|
|
342
|
-
writes the command shim, upserts user-level agent instructions, and starts/checks OpenViking health by default. Use
|
|
343
|
-
`--no-start` to skip the health check.
|
|
344
|
-
- `version`: prints the installed Threadnote version, latest npm version, and release notes for newer GitHub releases.
|
|
345
|
-
- `update`: updates the published Threadnote package, then runs `repair` so shims and MCP config point at the new
|
|
346
|
-
version. When an update is available, it prints release notes for the full version diff.
|
|
347
|
-
- `manage`: opens the local React web manager for browsing, recalling, reading, editing, archiving, forgetting,
|
|
348
|
-
publishing, consolidating, and diagnosing local/shared memories. It binds to `127.0.0.1` with a per-session token; use
|
|
349
|
-
`--no-open` to print the URL without opening a browser.
|
|
350
|
-
- `repair`: fixes install/config/shim/manifest/server health issues and rewrites Codex/Claude/Cursor/Copilot MCP configs
|
|
351
|
-
from the current checkout.
|
|
352
|
-
- `start`: starts `openviking-server` on `127.0.0.1:1933`.
|
|
353
|
-
- `stop`: stops the detached server pid or macOS LaunchAgent.
|
|
354
|
-
- `uninstall`: removes Threadnote shims, MCP config, launchd config, and managed user instructions. Memories are
|
|
355
|
-
preserved by default; pass `--erase-memories` to delete `THREADNOTE_HOME`.
|
|
356
|
-
- `init-manifest`: creates or updates `~/.openviking/seed-manifest.yaml` from one or more developer repo roots.
|
|
357
|
-
- `seed`: imports curated repo guidance and docs from the manifest.
|
|
358
|
-
- `seed-skills`: imports global and repo-local `SKILL.md` files as a searchable resource catalog so agents can discover
|
|
359
|
-
reusable workflow guidance. Use `seed-skills --native` only after configuring a working VLM provider.
|
|
360
|
-
- `mcp-install codex|claude|cursor|copilot`: installs or prints OpenViking MCP configuration for Codex, Claude, Cursor,
|
|
361
|
-
or GitHub Copilot in VS Code.
|
|
362
|
-
- `remember`: stores a durable memory. Use `--replace <uri>` to store an updated memory and remove a superseded personal
|
|
363
|
-
memory after the new memory succeeds; if `<uri>` is shared, Threadnote updates that shared memory in place and pushes
|
|
364
|
-
the shared repo. Use `--kind`, `--project`, and `--topic` to store lifecycle-aware current knowledge.
|
|
365
|
-
- `migrate-memories`: migrates legacy session-only `MEMORY` and `HANDOFF` records into durable memory files. Run
|
|
366
|
-
`migrate-memories --dry-run` first; use `--all-accounts` when importing from older local OpenViking accounts.
|
|
367
|
-
- `migrate-lifecycle`: moves clear legacy handoff memories from the old events path into archived lifecycle handoff
|
|
368
|
-
paths. It dry-runs by default; use `--apply` after reviewing the output.
|
|
369
|
-
- `recall`: searches shared OpenViking context. It infers repo or skill scope from queries like
|
|
370
|
-
`skills for api service`; use `--uri` or `--no-infer-scope` to override. Queries that mention `this branch` or
|
|
371
|
-
`current branch` are enriched with local git/workspace terms when available. Exact memory/resource matches skip
|
|
372
|
-
archived lifecycle paths unless `--include-archived` is passed. Recall also nudges scoped cleanup when many active
|
|
373
|
-
handoffs or overlapping returned memories surface.
|
|
374
|
-
- `compact`: prints or applies scoped memory hygiene for active personal memories. It dry-runs by default; use `--apply`
|
|
375
|
-
after reviewing the plan. It archives stale handoffs, forgets exact duplicates, and leaves ambiguous durable memories
|
|
376
|
-
for manual review.
|
|
377
|
-
- `read`: reads a `viking://` URI returned by `recall` or `list`.
|
|
378
|
-
- `list` / `ls`: lists a `viking://` directory.
|
|
379
|
-
- `handoff`: stores current git state and next-step notes as a durable handoff. Bare handoffs use the current repo and
|
|
380
|
-
current branch as stable project/topic; use `--timestamped` for historical notes or `--project` / `--topic` to override.
|
|
381
|
-
- `archive`: copies a memory into the archived lifecycle tree, then removes the original after the archive write
|
|
382
|
-
succeeds.
|
|
383
|
-
- `forget`: removes a `viking://` URI.
|
|
384
|
-
- `export-pack` / `import-pack`: moves local context through `.ovpack` files.
|
|
385
|
-
- `share init|status|sync|publish|unpublish|list|rename|set-url|remove`: opts a curated subset of durable memories into a team git
|
|
386
|
-
repo. Threadnote periodically fetches configured share repos and automatically syncs clean incoming changes before
|
|
387
|
-
agent recall/read; use `share sync` for dirty worktrees, conflicts, explicit pushes, or immediate manual sync.
|
|
388
|
-
Personal handoffs and preferences stay local. See `docs/share.md` for the full workflow and the publish-time scrubber
|
|
389
|
-
rules.
|
|
390
|
-
|
|
391
|
-
## Source Checkout
|
|
392
|
-
|
|
393
|
-
TypeScript sources live under `src/`; `src/threadnote.ts` is the CLI entrypoint and `src/mcp_server.ts` is the stdio MCP
|
|
394
|
-
adapter entrypoint.
|
|
395
|
-
|
|
396
|
-
For local development from this repo:
|
|
397
|
-
|
|
398
|
-
```bash
|
|
399
|
-
npm install
|
|
400
|
-
npm run build
|
|
401
|
-
npm run doctor -- --dry-run
|
|
402
|
-
npm run threadnote -- install
|
|
403
|
-
```
|
|
404
|
-
|
|
405
|
-
`install` writes a small command shim to `~/.local/bin/threadnote` by default and upserts user-level agent guidance in
|
|
406
|
-
`~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`, `~/.cursor/rules/threadnote.md`, and
|
|
407
|
-
`~/.copilot/instructions/threadnote.instructions.md`. After that, use the short command from any repo or working
|
|
408
|
-
directory:
|
|
409
|
-
|
|
410
|
-
```bash
|
|
411
|
-
threadnote doctor --dry-run
|
|
412
|
-
threadnote init-manifest --repo ~/src/my-service --repo ~/work/mobile-app
|
|
413
|
-
threadnote seed --dry-run
|
|
414
|
-
threadnote seed-skills --dry-run
|
|
415
|
-
```
|
|
416
|
-
|
|
417
|
-
If `~/.local/bin` is not on your `PATH`, either add it or set `THREADNOTE_BIN_DIR` before running `install`.
|
|
418
|
-
After reviewing dry-run output, remove `--dry-run` for the operation you want to perform.
|
|
419
|
-
|
|
420
|
-
The bundled `config/seed-manifest.example.yaml` is only an example. Each developer should create a local manifest at
|
|
421
|
-
`~/.openviking/seed-manifest.yaml` with `threadnote init-manifest`; repo paths can be anywhere.
|
|
422
|
-
|
|
423
|
-
## Configuration
|
|
424
|
-
|
|
425
|
-
Environment variables:
|
|
426
|
-
|
|
427
|
-
- `THREADNOTE_HOME`: local state directory, default `~/.openviking`.
|
|
428
|
-
- `THREADNOTE_MANIFEST`: seed manifest path. Defaults to `~/.openviking/seed-manifest.yaml` if present, otherwise
|
|
429
|
-
the bundled example manifest.
|
|
430
|
-
- `THREADNOTE_ACCOUNT`: OpenViking account header/config value, default `local`.
|
|
431
|
-
- `THREADNOTE_USER`: OpenViking user value, default local username.
|
|
432
|
-
- `THREADNOTE_AGENT_ID`: shared agent identity, default `threadnote`.
|
|
433
|
-
- `THREADNOTE_OPENVIKING_VERSION`: package version to install, default `0.3.12`.
|
|
434
|
-
- `THREADNOTE_NPM_REGISTRY`: npm registry used by the installer and updater, default `https://registry.npmjs.org/`.
|
|
435
|
-
- `THREADNOTE_NO_UPDATE_CHECK`: disables opportunistic update notifications.
|
|
436
|
-
- `THREADNOTE_BIN_DIR`: directory for the `threadnote` shim, default `~/.local/bin`.
|
|
437
|
-
- `THREADNOTE_COPILOT_MCP_CONFIG`: explicit VS Code/Copilot `mcp.json` path for `mcp-install copilot`.
|
|
438
|
-
- `THREADNOTE_HOST`: local bind host, default `127.0.0.1`.
|
|
439
|
-
- `THREADNOTE_PORT`: local bind port, default `1933`.
|
|
440
|
-
|
|
441
|
-
Local projects using `localhost:80` or `localhost:443` do not conflict with OpenViking on `127.0.0.1:1933`. A conflict
|
|
442
|
-
only occurs when another process already owns the same host and port. If that happens, choose a different
|
|
443
|
-
`THREADNOTE_PORT`.
|
|
444
|
-
|
|
445
|
-
## Misc
|
|
446
|
-
|
|
447
|
-
See `docs/migration.md` for switching an existing repo workflow to `threadnote` without deleting canonical
|
|
448
|
-
`AGENTS.md`, `CLAUDE.md`, `.claude/`, or `.agents/` files.
|
|
449
|
-
|
|
450
|
-
See `docs/agent-instructions.md` for the user-level agent guidance installed by `threadnote install`.
|
|
451
|
-
|
|
452
|
-
## Recall And Read
|
|
453
|
-
|
|
454
|
-
Recall is a search step. It returns candidate `viking://` URIs plus abstracts. Agents should then read or list the
|
|
455
|
-
selected URI:
|
|
456
|
-
|
|
457
|
-
```bash
|
|
458
|
-
threadnote recall --query "agent context"
|
|
459
|
-
threadnote read viking://agent/threadnote/memories/.abstract.md
|
|
460
|
-
threadnote list viking://agent/threadnote/memories --all --recursive
|
|
461
|
-
```
|
|
462
|
-
|
|
463
|
-
When MCP is installed, the agent should use Threadnote MCP `recall_context`, then `read_context` or `list_context`.
|
|
464
|
-
Agents must pass JSON arguments, for example `recall_context({"query":"agent context"})`. For MCP recall queries that
|
|
465
|
-
say "current repo" or "this branch", pass the current workspace path as `callerCwd` so Threadnote can resolve branch and
|
|
466
|
-
workspace terms without guessing from the MCP server's launch directory. Use `compact_context` for scoped memory hygiene
|
|
467
|
-
dry-runs before applying cleanup. Older adapters expose `search`, `read`, and `list` aliases. Before recall/read returns,
|
|
468
|
-
Threadnote automatically syncs clean incoming shared memory updates when a
|
|
469
|
-
configured share repo is behind; failures are reported as warnings and the local read still continues. The CLI commands
|
|
470
|
-
are the fallback path.
|
package/dist/mcp_server.cjs
CHANGED
|
@@ -36285,8 +36285,8 @@ async function runSharePublishTool(config2, sourceUri, options) {
|
|
|
36285
36285
|
`Refusing to publish: ${targetUri} already exists in the shared namespace. Inspect it via threadnote read; if it should be replaced, forget the existing shared copy first.`
|
|
36286
36286
|
);
|
|
36287
36287
|
}
|
|
36288
|
-
await ensureSharedDirectoryChain(config2, ov, targetUri, false);
|
|
36289
|
-
await writeMemoryFile(config2, ov, targetUri, content, "create", false);
|
|
36288
|
+
await ensureSharedDirectoryChain(config2, ov, targetUri, false, { quiet: true });
|
|
36289
|
+
await writeMemoryFile(config2, ov, targetUri, content, "create", false, { quiet: true });
|
|
36290
36290
|
const messages = [`Published ${sourceUri} -> ${targetUri}`];
|
|
36291
36291
|
for (const redaction of scrub.redactions) {
|
|
36292
36292
|
messages.push(`Redacted ${redaction.count}\xD7 ${redaction.name} before publish.`);
|
package/docs/index.html
CHANGED
|
@@ -765,6 +765,7 @@
|
|
|
765
765
|
<a href="#update" data-label="Update"><span>Update</span></a>
|
|
766
766
|
<a href="#lifecycle" data-label="Lifecycle"><span>Lifecycle</span></a>
|
|
767
767
|
<a href="#share" data-label="Share"><span>Share</span></a>
|
|
768
|
+
<a href="#manager" data-label="Web manager"><span>Manager</span></a>
|
|
768
769
|
<a href="#use-cases" data-label="Use cases"><span>Use cases</span></a>
|
|
769
770
|
<a href="#close" data-label="Get started"><span>Start</span></a>
|
|
770
771
|
</nav>
|
|
@@ -782,7 +783,7 @@
|
|
|
782
783
|
team-shared decisions — recallable from any session, on any agent, in any worktree.
|
|
783
784
|
</p>
|
|
784
785
|
<div class="cta-row">
|
|
785
|
-
<span class="pill"><span id="version-tag">v0.6.1</span> · local-first ·
|
|
786
|
+
<span class="pill"><span id="version-tag">v0.6.1</span> · local-first · GPL-3.0-or-later</span>
|
|
786
787
|
</div>
|
|
787
788
|
</div>
|
|
788
789
|
<div class="scroll-cue">scroll ↓ · <span class="kbd">↓</span> / <span class="kbd">j</span></div>
|
|
@@ -1400,10 +1401,72 @@ threadnote remember \
|
|
|
1400
1401
|
</div>
|
|
1401
1402
|
</section>
|
|
1402
1403
|
|
|
1403
|
-
<!-- 12.
|
|
1404
|
+
<!-- 12. WEB MANAGER -->
|
|
1405
|
+
<section id="manager" class="slide">
|
|
1406
|
+
<div class="slide-inner">
|
|
1407
|
+
<span class="slide-eyebrow">11 · Web manager</span>
|
|
1408
|
+
<h2>A local web UI for the whole memory store.</h2>
|
|
1409
|
+
<p class="lead">
|
|
1410
|
+
Prefer a UI to the CLI? <code>threadnote manage</code> serves a local React app on
|
|
1411
|
+
<code>127.0.0.1</code> with a per-session token. Browse the tree, edit Markdown, run health checks, and
|
|
1412
|
+
manage shares — everything it does, the CLI and MCP do too.
|
|
1413
|
+
</p>
|
|
1414
|
+
|
|
1415
|
+
<img
|
|
1416
|
+
src="web-manager.png"
|
|
1417
|
+
alt="Threadnote web manager — Health and Doctor view with the memory tree, Memory / Sharing / Health / Tools tabs, and Run Doctor / Start OpenViking / Repair controls"
|
|
1418
|
+
loading="lazy"
|
|
1419
|
+
style="
|
|
1420
|
+
width: 100%;
|
|
1421
|
+
height: auto;
|
|
1422
|
+
display: block;
|
|
1423
|
+
margin-top: 1.5rem;
|
|
1424
|
+
border: 1px solid var(--line);
|
|
1425
|
+
border-radius: var(--radius-lg);
|
|
1426
|
+
"
|
|
1427
|
+
/>
|
|
1428
|
+
|
|
1429
|
+
<div class="grid grid-2" style="margin-top: 1.5rem">
|
|
1430
|
+
<div class="card reveal">
|
|
1431
|
+
<span class="card-kicker">Memory</span>
|
|
1432
|
+
<h3>Browse & edit the tree</h3>
|
|
1433
|
+
<p>
|
|
1434
|
+
Resizable, filterable navigation. Markdown preview by default, raw edit on demand, and
|
|
1435
|
+
confirmation-gated bulk archive / publish / forget that never silently targets filtered-out files.
|
|
1436
|
+
</p>
|
|
1437
|
+
</div>
|
|
1438
|
+
<div class="card reveal">
|
|
1439
|
+
<span class="card-kicker">Health</span>
|
|
1440
|
+
<h3>Doctor on open</h3>
|
|
1441
|
+
<p>
|
|
1442
|
+
The default tab runs <code>doctor</code> automatically. Run Doctor, Start OpenViking, and Repair stream
|
|
1443
|
+
into a scrollable output pane — the view in the screenshot above.
|
|
1444
|
+
</p>
|
|
1445
|
+
</div>
|
|
1446
|
+
<div class="card reveal">
|
|
1447
|
+
<span class="card-kicker">Sharing</span>
|
|
1448
|
+
<h3>Team repos, no CLI</h3>
|
|
1449
|
+
<p>
|
|
1450
|
+
Status, publish, sync, rename, set-url, remove, and preserve-local — full parity with
|
|
1451
|
+
<code>threadnote share</code>.
|
|
1452
|
+
</p>
|
|
1453
|
+
</div>
|
|
1454
|
+
<div class="card reveal">
|
|
1455
|
+
<span class="card-kicker">Tools</span>
|
|
1456
|
+
<h3>Recall, compact, consolidate</h3>
|
|
1457
|
+
<p>
|
|
1458
|
+
Recall and read, scoped compaction dry-runs, import/export packs, seeding, and AI-assisted consolidation
|
|
1459
|
+
drafted by a local Codex or Claude CLI then applied on confirm.
|
|
1460
|
+
</p>
|
|
1461
|
+
</div>
|
|
1462
|
+
</div>
|
|
1463
|
+
</div>
|
|
1464
|
+
</section>
|
|
1465
|
+
|
|
1466
|
+
<!-- 13. USE CASES -->
|
|
1404
1467
|
<section id="use-cases" class="slide">
|
|
1405
1468
|
<div class="slide-inner">
|
|
1406
|
-
<span class="slide-eyebrow">
|
|
1469
|
+
<span class="slide-eyebrow">12 · Real-world use cases</span>
|
|
1407
1470
|
<h2>What you say. What the agent does.</h2>
|
|
1408
1471
|
<p class="lead">
|
|
1409
1472
|
You don't run threadnote commands yourself. You talk to your agent the way you already do; the agent calls
|
|
@@ -1495,10 +1558,10 @@ Stored: viking://user/you/memories/durable/projects/<repo>/release-process
|
|
|
1495
1558
|
</div>
|
|
1496
1559
|
</section>
|
|
1497
1560
|
|
|
1498
|
-
<!--
|
|
1561
|
+
<!-- 14. CLOSE -->
|
|
1499
1562
|
<section id="close" class="slide">
|
|
1500
1563
|
<div class="slide-inner">
|
|
1501
|
-
<span class="slide-eyebrow">
|
|
1564
|
+
<span class="slide-eyebrow">13 · Get started</span>
|
|
1502
1565
|
<h2>Try it on your machine in 90 seconds.</h2>
|
|
1503
1566
|
|
|
1504
1567
|
<pre style="margin-top: 1.5rem">
|
|
@@ -1522,8 +1585,8 @@ threadnote doctor --dry-run</code></pre>
|
|
|
1522
1585
|
</div>
|
|
1523
1586
|
|
|
1524
1587
|
<p class="colophon">
|
|
1525
|
-
threadnote ·
|
|
1526
|
-
<span class="kbd">j</span> <span class="kbd">k</span> to navigate
|
|
1588
|
+
threadnote · GPL-3.0-or-later · built on OpenViking 0.3.12 · use <span class="kbd">↑</span>
|
|
1589
|
+
<span class="kbd">↓</span> / <span class="kbd">j</span> <span class="kbd">k</span> to navigate
|
|
1527
1590
|
</p>
|
|
1528
1591
|
</div>
|
|
1529
1592
|
</section>
|
|
Binary file
|