agent-knowledge 1.9.8 → 3.0.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 (179) hide show
  1. package/CHANGELOG.md +82 -0
  2. package/README.md +53 -52
  3. package/dist/events.d.ts +16 -0
  4. package/dist/events.d.ts.map +1 -0
  5. package/dist/events.js +31 -0
  6. package/dist/events.js.map +1 -0
  7. package/dist/index.js +31 -13
  8. package/dist/index.js.map +1 -1
  9. package/dist/knowledge/analyze.d.ts.map +1 -1
  10. package/dist/knowledge/analyze.js +18 -11
  11. package/dist/knowledge/analyze.js.map +1 -1
  12. package/dist/knowledge/consolidate.d.ts +2 -2
  13. package/dist/knowledge/consolidate.js +2 -2
  14. package/dist/knowledge/distill.d.ts.map +1 -1
  15. package/dist/knowledge/distill.js +28 -16
  16. package/dist/knowledge/distill.js.map +1 -1
  17. package/dist/knowledge/freshness.js +1 -1
  18. package/dist/knowledge/freshness.js.map +1 -1
  19. package/dist/knowledge/git.d.ts +3 -4
  20. package/dist/knowledge/git.d.ts.map +1 -1
  21. package/dist/knowledge/git.js +62 -49
  22. package/dist/knowledge/git.js.map +1 -1
  23. package/dist/knowledge/graph.d.ts +2 -0
  24. package/dist/knowledge/graph.d.ts.map +1 -1
  25. package/dist/knowledge/graph.js +8 -0
  26. package/dist/knowledge/graph.js.map +1 -1
  27. package/dist/knowledge/ingest-freshness.d.ts +22 -0
  28. package/dist/knowledge/ingest-freshness.d.ts.map +1 -0
  29. package/dist/knowledge/ingest-freshness.js +93 -0
  30. package/dist/knowledge/ingest-freshness.js.map +1 -0
  31. package/dist/knowledge/promote.js +1 -1
  32. package/dist/knowledge/promote.js.map +1 -1
  33. package/dist/knowledge/reflect.js +2 -2
  34. package/dist/knowledge/reflect.js.map +1 -1
  35. package/dist/knowledge/remove.d.ts +11 -0
  36. package/dist/knowledge/remove.d.ts.map +1 -0
  37. package/dist/knowledge/remove.js +24 -0
  38. package/dist/knowledge/remove.js.map +1 -0
  39. package/dist/knowledge/search.d.ts +76 -4
  40. package/dist/knowledge/search.d.ts.map +1 -1
  41. package/dist/knowledge/search.js +364 -37
  42. package/dist/knowledge/search.js.map +1 -1
  43. package/dist/knowledge/similar.d.ts +7 -0
  44. package/dist/knowledge/similar.d.ts.map +1 -0
  45. package/dist/knowledge/similar.js +51 -0
  46. package/dist/knowledge/similar.js.map +1 -0
  47. package/dist/knowledge/store.d.ts +20 -1
  48. package/dist/knowledge/store.d.ts.map +1 -1
  49. package/dist/knowledge/store.js +119 -84
  50. package/dist/knowledge/store.js.map +1 -1
  51. package/dist/lib.d.ts +1 -1
  52. package/dist/lib.d.ts.map +1 -1
  53. package/dist/lib.js.map +1 -1
  54. package/dist/package-meta.d.ts +4 -1
  55. package/dist/package-meta.d.ts.map +1 -1
  56. package/dist/package-meta.js +18 -9
  57. package/dist/package-meta.js.map +1 -1
  58. package/dist/rest-server.d.ts +31 -0
  59. package/dist/rest-server.d.ts.map +1 -0
  60. package/dist/rest-server.js +142 -0
  61. package/dist/rest-server.js.map +1 -0
  62. package/dist/search/bm25.d.ts +8 -0
  63. package/dist/search/bm25.d.ts.map +1 -1
  64. package/dist/search/bm25.js +32 -20
  65. package/dist/search/bm25.js.map +1 -1
  66. package/dist/search/excerpt.d.ts +1 -1
  67. package/dist/search/excerpt.d.ts.map +1 -1
  68. package/dist/search/excerpt.js +19 -1
  69. package/dist/search/excerpt.js.map +1 -1
  70. package/dist/search/lexicon.d.ts +37 -0
  71. package/dist/search/lexicon.d.ts.map +1 -0
  72. package/dist/search/lexicon.js +83 -0
  73. package/dist/search/lexicon.js.map +1 -0
  74. package/dist/search/mmr.d.ts +9 -3
  75. package/dist/search/mmr.d.ts.map +1 -1
  76. package/dist/search/mmr.js +21 -7
  77. package/dist/search/mmr.js.map +1 -1
  78. package/dist/search/types.d.ts +2 -0
  79. package/dist/search/types.d.ts.map +1 -1
  80. package/dist/server.d.ts +1 -5
  81. package/dist/server.d.ts.map +1 -1
  82. package/dist/server.js +1 -13
  83. package/dist/server.js.map +1 -1
  84. package/dist/sessions/human.d.ts +12 -0
  85. package/dist/sessions/human.d.ts.map +1 -0
  86. package/dist/sessions/human.js +52 -0
  87. package/dist/sessions/human.js.map +1 -0
  88. package/dist/sessions/indexer.d.ts +4 -0
  89. package/dist/sessions/indexer.d.ts.map +1 -1
  90. package/dist/sessions/indexer.js +6 -1
  91. package/dist/sessions/indexer.js.map +1 -1
  92. package/dist/sessions/parser.d.ts +39 -0
  93. package/dist/sessions/parser.d.ts.map +1 -1
  94. package/dist/sessions/parser.js +169 -15
  95. package/dist/sessions/parser.js.map +1 -1
  96. package/dist/sessions/search.d.ts +2 -0
  97. package/dist/sessions/search.d.ts.map +1 -1
  98. package/dist/sessions/search.js +147 -67
  99. package/dist/sessions/search.js.map +1 -1
  100. package/dist/sessions/snapshot.d.ts +19 -0
  101. package/dist/sessions/snapshot.d.ts.map +1 -0
  102. package/dist/sessions/snapshot.js +118 -0
  103. package/dist/sessions/snapshot.js.map +1 -0
  104. package/dist/sessions/summary.d.ts +24 -5
  105. package/dist/sessions/summary.d.ts.map +1 -1
  106. package/dist/sessions/summary.js +122 -146
  107. package/dist/sessions/summary.js.map +1 -1
  108. package/dist/slice.d.ts +5 -0
  109. package/dist/slice.d.ts.map +1 -0
  110. package/dist/slice.js +28 -0
  111. package/dist/slice.js.map +1 -0
  112. package/dist/text.d.ts +9 -0
  113. package/dist/text.d.ts.map +1 -0
  114. package/dist/text.js +16 -0
  115. package/dist/text.js.map +1 -0
  116. package/dist/tool-handlers.d.ts.map +1 -1
  117. package/dist/tool-handlers.js +6 -10
  118. package/dist/tool-handlers.js.map +1 -1
  119. package/dist/transport/guard.d.ts +5 -0
  120. package/dist/transport/guard.d.ts.map +1 -0
  121. package/dist/transport/guard.js +51 -0
  122. package/dist/transport/guard.js.map +1 -0
  123. package/dist/transport/http.d.ts +17 -0
  124. package/dist/transport/http.d.ts.map +1 -0
  125. package/dist/transport/http.js +97 -0
  126. package/dist/transport/http.js.map +1 -0
  127. package/dist/transport/rest.d.ts +4 -0
  128. package/dist/transport/rest.d.ts.map +1 -0
  129. package/dist/transport/rest.js +424 -0
  130. package/dist/transport/rest.js.map +1 -0
  131. package/dist/vectorstore/store.d.ts +9 -0
  132. package/dist/vectorstore/store.d.ts.map +1 -1
  133. package/dist/vectorstore/store.js +23 -0
  134. package/dist/vectorstore/store.js.map +1 -1
  135. package/dist/wakeup.d.ts +5 -0
  136. package/dist/wakeup.d.ts.map +1 -1
  137. package/dist/wakeup.js +10 -1
  138. package/dist/wakeup.js.map +1 -1
  139. package/docs/ARCHITECTURE.md +25 -39
  140. package/docs/HOOKS.md +138 -237
  141. package/docs/INGEST.md +1 -1
  142. package/docs/SETUP.md +87 -143
  143. package/docs/USER-MANUAL.md +169 -100
  144. package/package.json +20 -17
  145. package/{skills → plugin/skills}/knowledge-ingest/SKILL.md +1 -1
  146. package/{skills → plugin/skills}/knowledge-ingest/scripts/validate.mjs +2 -2
  147. package/scripts/plugins/opencode/agent-knowledge.ts +37 -86
  148. package/scripts/setup.js +80 -146
  149. package/scripts/source-walk.d.mts +12 -0
  150. package/scripts/source-walk.mjs +94 -0
  151. package/scripts/tree-sitter-extract.mjs +10 -76
  152. package/.claude-plugin/marketplace.json +0 -19
  153. package/.claude-plugin/plugin.json +0 -12
  154. package/.mcp.json +0 -8
  155. package/agent-desk-plugin.json +0 -20
  156. package/dist/dashboard.d.ts +0 -5
  157. package/dist/dashboard.d.ts.map +0 -1
  158. package/dist/dashboard.js +0 -666
  159. package/dist/dashboard.js.map +0 -1
  160. package/dist/ui/app.js +0 -1013
  161. package/dist/ui/index.html +0 -460
  162. package/dist/ui/morphdom.min.js +0 -1
  163. package/dist/ui/render-graph.js +0 -482
  164. package/dist/ui/render-knowledge.js +0 -288
  165. package/dist/ui/render-panel.js +0 -475
  166. package/dist/ui/render-search.js +0 -105
  167. package/dist/ui/render-sessions.js +0 -237
  168. package/dist/ui/styles.css +0 -2322
  169. package/dist/ui/template.js +0 -173
  170. package/dist/ui/ui-utils.js +0 -217
  171. package/dist/ui/vis-network.min.js +0 -34
  172. package/docs/DASHBOARD.md +0 -191
  173. package/scripts/copy-ui.js +0 -14
  174. package/scripts/hooks/first-prompt-inject.mjs +0 -242
  175. package/scripts/hooks/precompact-distill.mjs +0 -105
  176. package/scripts/hooks/precompact-flush.mjs +0 -192
  177. package/scripts/hooks/session-start-ingest.mjs +0 -238
  178. package/scripts/hooks/session-start.js +0 -212
  179. package/scripts/hooks/sessionend-distill.mjs +0 -198
package/docs/SETUP.md CHANGED
@@ -12,13 +12,13 @@ Detailed instructions for installing, configuring, and integrating agent-knowled
12
12
  - [Cursor](#cursor)
13
13
  - [Windsurf](#windsurf)
14
14
  - [REST API](#rest-api)
15
- - [Hooks](#hooks)
16
- - [Claude Code Hooks](#claude-code-hooks)
15
+ - [Session lifecycle](#session-lifecycle)
16
+ - [Claude Code](#claude-code-1)
17
17
  - [OpenCode Plugins](#opencode-plugins)
18
18
  - [Cursor and Windsurf](#cursor-and-windsurf)
19
19
  - [Knowledge Base Setup](#knowledge-base-setup)
20
20
  - [Environment Variables](#environment-variables)
21
- - [Dashboard](#dashboard)
21
+ - [The /knowledge pane](#the-knowledge-pane)
22
22
  - [Multi-Machine Sync](#multi-machine-sync)
23
23
  - [Session Sources](#session-sources)
24
24
  - [Session Auto-Distillation](#session-auto-distillation)
@@ -61,17 +61,26 @@ agent-knowledge works with any MCP client (stdio) or HTTP client (REST API). Pic
61
61
 
62
62
  ### Claude Code
63
63
 
64
- #### Quick setup (recommended)
64
+ #### The plugin (recommended)
65
65
 
66
- From the agent-knowledge clone:
66
+ ```bash
67
+ claude plugin marketplace add keshrath/agent-knowledge
68
+ claude plugin install agent-knowledge@agent-knowledge
69
+ ```
70
+
71
+ It runs the MCP server (`npx agent-knowledge@^3`), adds the `knowledge-ingest` skill and a mod (Claude Code 2.1.289+): the `/knowledge` pane and the [session lifecycle](HOOKS.md). Nothing goes into `settings.json`.
72
+
73
+ Coming from 2.x, run once from the clone:
67
74
 
68
75
  ```bash
69
- node scripts/setup.js
76
+ node scripts/setup.js --host=claude
70
77
  ```
71
78
 
72
- This detects Claude Code, registers the MCP server in `~/.claude.json`, wires all 6 lifecycle hooks into `~/.claude/settings.json`, and grants `mcp__agent-knowledge__*` permission in one shot. Restart Claude Code afterwards to pick up the new config.
79
+ It removes the six command hooks 2.x installed into `~/.claude/settings.json` (their scripts are gone in 3.0) and grants `mcp__agent-knowledge__*`. Remove a hand-written `agent-knowledge` entry from `~/.claude.json` as well, so the tools do not appear twice.
80
+
81
+ #### Register the MCP server alone (manual)
73
82
 
74
- #### Register the MCP server (manual)
83
+ Without the plugin there is no pane and no lifecycle, only the tools:
75
84
 
76
85
  ```bash
77
86
  claude mcp add agent-knowledge -s user \
@@ -158,7 +167,7 @@ claude mcp list
158
167
 
159
168
  ### REST API
160
169
 
161
- If your tool doesn't support MCP, use the REST API:
170
+ If your tool doesn't support MCP, use the local REST API (served on `127.0.0.1:3423` while any session runs the MCP server; loopback only, JSON only, no `Origin` header):
162
171
 
163
172
  ```bash
164
173
  # List entries
@@ -167,94 +176,24 @@ curl http://localhost:3423/api/knowledge
167
176
  # Search
168
177
  curl 'http://localhost:3423/api/knowledge/search?q=deployment+pipeline'
169
178
 
170
- # Read an entry
171
- curl http://localhost:3423/api/knowledge/projects/my-project
179
+ # Read an entry (the slash in the path sent encoded)
180
+ curl http://localhost:3423/api/knowledge/projects%2Fmy-project.md
172
181
 
173
182
  # Write an entry
174
- curl -X PUT http://localhost:3423/api/knowledge/notes/my-note \
183
+ curl -X POST http://localhost:3423/api/knowledge \
175
184
  -H 'Content-Type: application/json' \
176
- -d '{"content": "---\ntitle: My Note\ntags: [example]\n---\n\nContent here."}'
185
+ -d '{"category": "notes", "filename": "my-note", "content": "---\ntitle: My Note\ntags: [example]\n---\n\nContent here."}'
177
186
  ```
178
187
 
179
188
  ---
180
189
 
181
- ## Hooks
190
+ ## Session lifecycle
182
191
 
183
- agent-knowledge ships **6 hook scripts** that wire into Claude Code's lifecycle events. `scripts/setup.js` installs them automatically; the block below shows the manual equivalent. Support varies by client.
192
+ What happens around each session, beyond the tools the model calls. Support varies by client.
184
193
 
185
- | Hook | Event | Purpose |
186
- | -------------------------- | ---------------- | -------------------------------------------------------------------------------- |
187
- | `session-start.js` | SessionStart | Dashboard URL + auto-loads token-budgeted wakeup payload into context |
188
- | `session-start-ingest.mjs` | SessionStart | Detects project + reports knowledge-ingest cache drift via SHA256 diff |
189
- | `first-prompt-inject.mjs` | UserPromptSubmit | v1.8 — query-targeted knowledge hits injected on the session's first real prompt |
190
- | `precompact-flush.mjs` | PreCompact | Rich session summary on disk + save-unsaved-context nudge into context |
191
- | `precompact-distill.mjs` | PreCompact | Lightweight text snapshot of recent user prompts |
192
- | `sessionend-distill.mjs` | SessionEnd | Final summary (turn counts, tool uses, first 20 prompts) |
193
-
194
- See [`docs/HOOKS.md`](HOOKS.md) for the full hook reference including environment variables and test coverage.
195
-
196
- ### Claude Code Hooks
194
+ ### Claude Code
197
195
 
198
- ```json
199
- {
200
- "hooks": {
201
- "SessionStart": [
202
- {
203
- "hooks": [
204
- {
205
- "type": "command",
206
- "command": "node \"/path/to/agent-knowledge/scripts/hooks/session-start.js\"",
207
- "timeout": 5
208
- },
209
- {
210
- "type": "command",
211
- "command": "node \"/path/to/agent-knowledge/scripts/hooks/session-start-ingest.mjs\"",
212
- "timeout": 10
213
- }
214
- ]
215
- }
216
- ],
217
- "UserPromptSubmit": [
218
- {
219
- "hooks": [
220
- {
221
- "type": "command",
222
- "command": "node \"/path/to/agent-knowledge/scripts/hooks/first-prompt-inject.mjs\"",
223
- "timeout": 10
224
- }
225
- ]
226
- }
227
- ],
228
- "PreCompact": [
229
- {
230
- "hooks": [
231
- {
232
- "type": "command",
233
- "command": "node \"/path/to/agent-knowledge/scripts/hooks/precompact-flush.mjs\"",
234
- "timeout": 10
235
- },
236
- {
237
- "type": "command",
238
- "command": "node \"/path/to/agent-knowledge/scripts/hooks/precompact-distill.mjs\"",
239
- "timeout": 10
240
- }
241
- ]
242
- }
243
- ],
244
- "SessionEnd": [
245
- {
246
- "hooks": [
247
- {
248
- "type": "command",
249
- "command": "node \"/path/to/agent-knowledge/scripts/hooks/sessionend-distill.mjs\"",
250
- "timeout": 10
251
- }
252
- ]
253
- }
254
- ]
255
- }
256
- }
257
- ```
196
+ The plugin's mod: each conversation starts knowing what the knowledge base holds, who the person is (or asks them once) and the project's ingest state; the first real prompt carries the matching entries; the session is snapshotted into `sessions/<project>/` when it is compacted and when it ends. No command hooks. See [HOOKS.md](HOOKS.md) for every part and its switches.
258
197
 
259
198
  ### OpenCode Plugins
260
199
 
@@ -285,35 +224,35 @@ node scripts/setup.js --host=all # both Claude Code an
285
224
 
286
225
  #### What the plugin does
287
226
 
288
- Mirrors the Claude Code hooks where opencode has an equivalent event:
227
+ The Claude Code lifecycle where opencode has an equivalent event:
289
228
 
290
- | Claude Code hook | OpenCode analog | Behavior |
291
- | ------------------------- | --------------------------------- | --------------------------------------------------------------------- |
292
- | `session-start.js` | `event: session.created` | Dashboard URL toast + clears stale first-prompt marker on resume. |
293
- | `first-prompt-inject.mjs` | `chat.message` | Searches the KB and prepends a rendered hits block to the user parts. |
294
- | `precompact-flush.mjs` | `experimental.session.compacting` | Pushes a "save unsaved knowledge before compaction" nudge. |
295
- | `sessionend-distill.mjs` | `event: session.deleted` | Writes `~/agent-knowledge/projects/session-opencode-<slug>.md`. |
229
+ | Claude Code (mod) | OpenCode analog | Behavior |
230
+ | -------------------------------- | --------------------------------- | --------------------------------------------------------------------- |
231
+ | the context block | `event: session.created` | Knowledge-base toast + clears stale first-prompt marker on resume. |
232
+ | the first real prompt | `chat.message` | Searches the KB and prepends a rendered hits block to the user parts. |
233
+ | compaction: keep what is unsaved | `experimental.session.compacting` | Pushes a "save unsaved knowledge before compaction" nudge. |
234
+ | the session snapshot at the end | `event: session.deleted` | Writes `~/agent-knowledge/projects/session-opencode-<slug>.md`. |
296
235
 
297
- Not ported (opencode has no equivalent surface):
236
+ Not here (opencode has no equivalent surface):
298
237
 
299
- - `session-start-ingest.mjs` (paired with the `/knowledge-ingest` skill flow).
300
- - `precompact-distill.mjs` (opencode compaction does not expose the transcript to plugins).
301
- - L0 identity auto-load (no `additionalContext` equivalent — put identity in `AGENTS.md` or call `knowledge(action="wakeup")` manually).
238
+ - The ingest freshness of the project (pair `/knowledge-ingest` by hand).
239
+ - The snapshot at compaction (opencode compaction does not expose the transcript to plugins).
240
+ - L0 identity auto-load (no context-block equivalent — put identity in `AGENTS.md` or call `knowledge(action="wakeup")` manually).
302
241
 
303
242
  #### Environment variables
304
243
 
305
- Same as the Claude hooks, all optional:
244
+ As for the Claude Code mod, all optional:
306
245
 
307
- | Variable | Default | Description |
308
- | -------------------------------------- | ------------------- | -------------------------------------------------------- |
309
- | `AGENT_KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Knowledge base root. |
310
- | `AGENT_KNOWLEDGE_DATA_DIR` | `<memory>/.data` | Marker/cache dir (first-prompt-seen markers live here). |
311
- | `AGENT_KNOWLEDGE_PORT` | `3423` | Dashboard port (plugin queries `/api/knowledge/search`). |
312
- | `AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT` | `1` | Set `0` / `false` / `off` to disable inject entirely. |
313
- | `AGENT_KNOWLEDGE_FIRSTPROMPT_BUDGET` | `600` | Max inject tokens (chars/4), clamped `[100, 8000]`. |
314
- | `AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS` | `4` | Max rendered hits, clamped `[1, 20]`. |
246
+ | Variable | Default | Description |
247
+ | -------------------------------------- | ------------------- | ------------------------------------------------------- |
248
+ | `AGENT_KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Knowledge base root. |
249
+ | `AGENT_KNOWLEDGE_DATA_DIR` | `<memory>/.data` | Marker/cache dir (first-prompt-seen markers live here). |
250
+ | `AGENT_KNOWLEDGE_PORT` | `3423` | REST port (plugin queries `/api/knowledge/search`). |
251
+ | `AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT` | `1` | Set `0` / `false` / `off` to disable inject entirely. |
252
+ | `AGENT_KNOWLEDGE_FIRSTPROMPT_BUDGET` | `600` | Max inject tokens (chars/4), clamped `[100, 8000]`. |
253
+ | `AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS` | `2` | Max rendered hits, clamped `[1, 2]`. |
315
254
 
316
- Every hook fails open — errors during search, toast, session walk, or disk write are swallowed and the user is never blocked.
255
+ Every part fails open — errors during search, toast, session walk, or disk write are swallowed and the user is never blocked.
317
256
 
318
257
  Combine with `AGENTS.md` instructions (see below).
319
258
 
@@ -372,7 +311,7 @@ Before ending a session, save non-obvious learnings to agent-knowledge:
372
311
  1. `knowledge_search` for existing entries that overlap with this session's work.
373
312
  2. `knowledge { action: "write" }` new entries for decisions, architecture changes, or error patterns
374
313
  that aren't already captured.
375
- 3. `knowledge_link` related entries together.
314
+ 3. Link related entries together with `knowledge_graph` action `link`.
376
315
 
377
316
  Categories: projects (project context), decisions (trade-offs made), workflows (processes),
378
317
  notes (everything else).
@@ -390,19 +329,19 @@ agent-knowledge ships a **knowledge-ingest** skill for bootstrapping or updating
390
329
 
391
330
  ### Automatic installation
392
331
 
393
- `node scripts/setup.js` installs the skill to both `~/.claude/skills/` and `~/.agents/skills/`, covering all major platforms:
332
+ The Claude Code plugin carries the skill. `node scripts/setup.js` installs it to `~/.agents/skills/` for the other platforms:
394
333
 
395
- | Platform | Discovery path | Covered by setup.js |
396
- | ----------- | ---------------------------------------- | ------------------- |
397
- | Claude Code | `~/.claude/skills/` | Yes |
398
- | OpenCode | `~/.claude/skills/`, `~/.agents/skills/` | Yes |
399
- | Cursor | `~/.claude/skills/`, `~/.agents/skills/` | Yes |
400
- | Codex CLI | `~/.agents/skills/` | Yes |
401
- | Gemini CLI | `~/.agents/skills/` | Yes |
334
+ | Platform | Discovery path | Covered by |
335
+ | ----------- | ---------------------------------------- | ----------------------- |
336
+ | Claude Code | the plugin | `claude plugin install` |
337
+ | OpenCode | `~/.claude/skills/`, `~/.agents/skills/` | setup.js |
338
+ | Cursor | `~/.claude/skills/`, `~/.agents/skills/` | setup.js |
339
+ | Codex CLI | `~/.agents/skills/` | setup.js |
340
+ | Gemini CLI | `~/.agents/skills/` | setup.js |
402
341
 
403
342
  ### Manual installation
404
343
 
405
- Copy `skills/knowledge-ingest/SKILL.md` to any of these locations:
344
+ Copy `plugin/skills/knowledge-ingest/SKILL.md` to any of these locations:
406
345
 
407
346
  ```bash
408
347
  # Claude Code, OpenCode, Cursor
@@ -463,24 +402,24 @@ Architecture notes, deployment info, etc.
463
402
 
464
403
  ## Environment Variables
465
404
 
466
- | Variable | Default | Description |
467
- | --------------------------------------------------------- | ------------------- | ---------------------------------------------------------------- |
468
- | `AGENT_KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Path to git-synced knowledge base |
469
- | `AGENT_KNOWLEDGE_DATA_DIR` | (platform config) | Override primary host data root (adapters auto-detect otherwise) |
470
- | `AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS` | -- | Additional session directories, comma-separated |
471
- | `OPENCODE_DATA_DIR` | (platform default) | Override OpenCode data dir (default `~/.local/share/opencode`) |
472
- | `AGENT_KNOWLEDGE_PORT` | `3423` | Dashboard HTTP/WebSocket port |
473
- | `AGENT_KNOWLEDGE_HOST` | `127.0.0.1` | Dashboard bind address (`0.0.0.0` exposes it to the network) |
474
- | `AGENT_KNOWLEDGE_EMBEDDING_PROVIDER` | `local` | Embedding provider (local, openai, claude, gemini) |
475
- | `AGENT_KNOWLEDGE_EMBEDDING_ALPHA` | `0.5` | Blend weight for semantic vs TF-IDF search (0-1) |
476
- | `AGENT_KNOWLEDGE_EMBEDDING_IDLE_TIMEOUT` | — | Idle timeout for embedding worker (ms) |
477
- | `AGENT_KNOWLEDGE_EMBEDDING_THREADS` | — | Number of ONNX threads for local embeddings |
478
- | `AGENT_KNOWLEDGE_EMBEDDING_MODEL` | — | Model name for embedding provider |
479
- | `AGENT_KNOWLEDGE_GIT_URL` | — | Remote git URL for knowledge base sync |
480
- | `AGENT_KNOWLEDGE_AUTO_DISTILL` | — | Enable auto-distillation of sessions (true/false) |
481
- | `AGENT_KNOWLEDGE_OPENAI_API_KEY` / `OPENAI_API_KEY` | — | API key for OpenAI embeddings |
482
- | `AGENT_KNOWLEDGE_ANTHROPIC_API_KEY` / `ANTHROPIC_API_KEY` | — | API key for Claude/Voyage embeddings |
483
- | `AGENT_KNOWLEDGE_GEMINI_API_KEY` / `GEMINI_API_KEY` | — | API key for Gemini embeddings |
405
+ | Variable | Default | Description |
406
+ | --------------------------------------------------------- | ------------------- | ----------------------------------------------------------------------- |
407
+ | `AGENT_KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Path to git-synced knowledge base |
408
+ | `AGENT_KNOWLEDGE_DATA_DIR` | (platform config) | Override primary host data root (adapters auto-detect otherwise) |
409
+ | `AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS` | -- | Additional session directories, comma-separated |
410
+ | `OPENCODE_DATA_DIR` | (platform default) | Override OpenCode data dir (default `~/.local/share/opencode`) |
411
+ | `AGENT_KNOWLEDGE_PORT` | `3423` | Local REST API port (the Claude Code and opencode plugins, agent-tasks) |
412
+ | `AGENT_KNOWLEDGE_HOST` | `127.0.0.1` | REST bind address |
413
+ | `AGENT_KNOWLEDGE_EMBEDDING_PROVIDER` | `local` | Embedding provider (local, openai, claude, gemini) |
414
+ | `AGENT_KNOWLEDGE_EMBEDDING_ALPHA` | `0.5` | Blend weight for semantic vs TF-IDF search (0-1) |
415
+ | `AGENT_KNOWLEDGE_EMBEDDING_IDLE_TIMEOUT` | — | Idle timeout for embedding worker (ms) |
416
+ | `AGENT_KNOWLEDGE_EMBEDDING_THREADS` | — | Number of ONNX threads for local embeddings |
417
+ | `AGENT_KNOWLEDGE_EMBEDDING_MODEL` | — | Model name for embedding provider |
418
+ | `AGENT_KNOWLEDGE_GIT_URL` | — | Remote git URL for knowledge base sync |
419
+ | `AGENT_KNOWLEDGE_AUTO_DISTILL` | — | Enable auto-distillation of sessions (true/false) |
420
+ | `AGENT_KNOWLEDGE_OPENAI_API_KEY` / `OPENAI_API_KEY` | — | API key for OpenAI embeddings |
421
+ | `AGENT_KNOWLEDGE_ANTHROPIC_API_KEY` / `ANTHROPIC_API_KEY` | — | API key for Claude/Voyage embeddings |
422
+ | `AGENT_KNOWLEDGE_GEMINI_API_KEY` / `GEMINI_API_KEY` | — | API key for Gemini embeddings |
484
423
 
485
424
  Set in your shell profile or pass via MCP config:
486
425
 
@@ -496,13 +435,16 @@ $env:AGENT_KNOWLEDGE_MEMORY_DIR = "$env:USERPROFILE\agent-knowledge"
496
435
 
497
436
  ---
498
437
 
499
- ## Dashboard
438
+ ## The /knowledge pane
500
439
 
501
- Auto-starts with the MCP server at **http://localhost:3423**.
440
+ In Claude Code (2.1.289+), install the plugin and type `/knowledge`:
502
441
 
503
- 4 tabs: Knowledge, Search, Sessions, Embeddings. Supports light/dark theme.
442
+ ```bash
443
+ claude plugin marketplace add keshrath/agent-knowledge
444
+ claude plugin install agent-knowledge@agent-knowledge
445
+ ```
504
446
 
505
- Live reload: edit files in `src/ui/` and the browser refreshes automatically.
447
+ The pane opens beside the conversation and reads the local REST API, which the first running MCP process serves on `127.0.0.1:3423`; when that session exits, another one takes the port over. There is no web dashboard (removed in 2.0).
506
448
 
507
449
  ---
508
450
 
@@ -524,7 +466,7 @@ cd ~/agent-knowledge && git pull && git push # Should work without prompts
524
466
 
525
467
  ## Session Sources
526
468
 
527
- agent-knowledge auto-discovers sessions from all major AI coding assistants. If a tool is installed on your machine, its sessions appear automatically in search results and the dashboard Sessions tab.
469
+ agent-knowledge auto-discovers sessions from all major AI coding assistants. If a tool is installed on your machine, its sessions appear automatically in search results and in the `/knowledge` pane.
528
470
 
529
471
  | Tool | Format | Auto-detected path | Override |
530
472
  | ---------------- | -------------- | --------------------------------------------------------------- | ------------------------------------- |
@@ -557,12 +499,14 @@ To manually save knowledge from any client, use `knowledge` with `action: "write
557
499
 
558
500
  ### Port already in use
559
501
 
502
+ One MCP process serves the REST API; the others wait for the port, so a port held by another agent-knowledge is normal. If something else holds it:
503
+
560
504
  ```bash
561
505
  # Find the process
562
506
  netstat -ano | findstr :3423 # Windows
563
507
  lsof -i :3423 # Linux/macOS
564
508
 
565
- # Use a different port
509
+ # Use a different port (for the MCP server and the pane alike)
566
510
  export AGENT_KNOWLEDGE_PORT=3424
567
511
  ```
568
512
 
@@ -616,7 +560,7 @@ If your session data is in a non-standard location, use `AGENT_KNOWLEDGE_EXTRA_S
616
560
  | -------------------- | ----------- | -------------------- | ------------- | ---------- | ------------ | -------------- | -------------- |
617
561
  | MCP stdio transport | Yes | Yes | Yes | Yes | Yes | -- | Yes |
618
562
  | Session reading | Yes (JSONL) | Yes (JSONL) | Yes (SQLite) | Yes (JSON) | Yes (JSON) | Yes (MD/JSONL) | -- |
619
- | Lifecycle hooks | Yes (JSON) | No | Yes (plugins) | No | No | -- | No |
563
+ | Session lifecycle | Yes (mod) | No | Yes (plugins) | No | No | -- | No |
620
564
  | Session auto-distill | Yes | Yes | Yes | Yes | Yes | Yes | -- |
621
565
  | System prompt file | CLAUDE.md | .cursor/rules/\*.mdc | AGENTS.md | -- | -- | -- | .windsurfrules |
622
566
  | REST API fallback | Yes | Yes | Yes | Yes | Yes | Yes | Yes |