agent-knowledge 1.9.8 → 2.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 (98) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +39 -41
  3. package/dist/events.d.ts +10 -0
  4. package/dist/events.d.ts.map +1 -0
  5. package/dist/events.js +23 -0
  6. package/dist/events.js.map +1 -0
  7. package/dist/index.js +19 -13
  8. package/dist/index.js.map +1 -1
  9. package/dist/knowledge/consolidate.d.ts +2 -2
  10. package/dist/knowledge/consolidate.js +2 -2
  11. package/dist/knowledge/freshness.js +1 -1
  12. package/dist/knowledge/freshness.js.map +1 -1
  13. package/dist/knowledge/git.d.ts.map +1 -1
  14. package/dist/knowledge/git.js +2 -3
  15. package/dist/knowledge/git.js.map +1 -1
  16. package/dist/knowledge/promote.js +1 -1
  17. package/dist/knowledge/promote.js.map +1 -1
  18. package/dist/knowledge/reflect.js +2 -2
  19. package/dist/knowledge/reflect.js.map +1 -1
  20. package/dist/knowledge/search.d.ts +6 -0
  21. package/dist/knowledge/search.d.ts.map +1 -1
  22. package/dist/knowledge/search.js +49 -3
  23. package/dist/knowledge/search.js.map +1 -1
  24. package/dist/knowledge/store.d.ts +3 -1
  25. package/dist/knowledge/store.d.ts.map +1 -1
  26. package/dist/knowledge/store.js +2 -5
  27. package/dist/knowledge/store.js.map +1 -1
  28. package/dist/lib.d.ts +1 -1
  29. package/dist/lib.d.ts.map +1 -1
  30. package/dist/lib.js.map +1 -1
  31. package/dist/package-meta.d.ts +4 -1
  32. package/dist/package-meta.d.ts.map +1 -1
  33. package/dist/package-meta.js +18 -9
  34. package/dist/package-meta.js.map +1 -1
  35. package/dist/rest-server.d.ts +21 -0
  36. package/dist/rest-server.d.ts.map +1 -0
  37. package/dist/rest-server.js +77 -0
  38. package/dist/rest-server.js.map +1 -0
  39. package/dist/server.d.ts +1 -5
  40. package/dist/server.d.ts.map +1 -1
  41. package/dist/server.js +1 -8
  42. package/dist/server.js.map +1 -1
  43. package/dist/sessions/indexer.d.ts +4 -0
  44. package/dist/sessions/indexer.d.ts.map +1 -1
  45. package/dist/sessions/indexer.js +6 -1
  46. package/dist/sessions/indexer.js.map +1 -1
  47. package/dist/sessions/parser.d.ts.map +1 -1
  48. package/dist/sessions/parser.js +32 -2
  49. package/dist/sessions/parser.js.map +1 -1
  50. package/dist/sessions/summary.d.ts.map +1 -1
  51. package/dist/sessions/summary.js +16 -1
  52. package/dist/sessions/summary.js.map +1 -1
  53. package/dist/transport/guard.d.ts +5 -0
  54. package/dist/transport/guard.d.ts.map +1 -0
  55. package/dist/transport/guard.js +51 -0
  56. package/dist/transport/guard.js.map +1 -0
  57. package/dist/transport/http.d.ts +17 -0
  58. package/dist/transport/http.d.ts.map +1 -0
  59. package/dist/transport/http.js +97 -0
  60. package/dist/transport/http.js.map +1 -0
  61. package/dist/transport/rest.d.ts +4 -0
  62. package/dist/transport/rest.d.ts.map +1 -0
  63. package/dist/transport/rest.js +307 -0
  64. package/dist/transport/rest.js.map +1 -0
  65. package/docs/ARCHITECTURE.md +23 -34
  66. package/docs/HOOKS.md +16 -16
  67. package/docs/INGEST.md +1 -1
  68. package/docs/SETUP.md +31 -26
  69. package/docs/USER-MANUAL.md +150 -89
  70. package/package.json +17 -14
  71. package/{skills → plugin/skills}/knowledge-ingest/SKILL.md +1 -1
  72. package/scripts/hooks/session-start.js +6 -7
  73. package/scripts/hooks/sessionend-distill.mjs +5 -5
  74. package/scripts/plugins/opencode/agent-knowledge.ts +6 -6
  75. package/scripts/setup.js +8 -7
  76. package/.claude-plugin/marketplace.json +0 -19
  77. package/.claude-plugin/plugin.json +0 -12
  78. package/.mcp.json +0 -8
  79. package/agent-desk-plugin.json +0 -20
  80. package/dist/dashboard.d.ts +0 -5
  81. package/dist/dashboard.d.ts.map +0 -1
  82. package/dist/dashboard.js +0 -666
  83. package/dist/dashboard.js.map +0 -1
  84. package/dist/ui/app.js +0 -1013
  85. package/dist/ui/index.html +0 -460
  86. package/dist/ui/morphdom.min.js +0 -1
  87. package/dist/ui/render-graph.js +0 -482
  88. package/dist/ui/render-knowledge.js +0 -288
  89. package/dist/ui/render-panel.js +0 -475
  90. package/dist/ui/render-search.js +0 -105
  91. package/dist/ui/render-sessions.js +0 -237
  92. package/dist/ui/styles.css +0 -2322
  93. package/dist/ui/template.js +0 -173
  94. package/dist/ui/ui-utils.js +0 -217
  95. package/dist/ui/vis-network.min.js +0 -34
  96. package/docs/DASHBOARD.md +0 -191
  97. package/scripts/copy-ui.js +0 -14
  98. /package/{skills → plugin/skills}/knowledge-ingest/scripts/validate.mjs +0 -0
package/docs/SETUP.md CHANGED
@@ -18,7 +18,7 @@ Detailed instructions for installing, configuring, and integrating agent-knowled
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)
@@ -158,7 +158,7 @@ claude mcp list
158
158
 
159
159
  ### REST API
160
160
 
161
- If your tool doesn't support MCP, use the REST API:
161
+ 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
162
 
163
163
  ```bash
164
164
  # List entries
@@ -167,13 +167,13 @@ curl http://localhost:3423/api/knowledge
167
167
  # Search
168
168
  curl 'http://localhost:3423/api/knowledge/search?q=deployment+pipeline'
169
169
 
170
- # Read an entry
171
- curl http://localhost:3423/api/knowledge/projects/my-project
170
+ # Read an entry (the slash in the path sent encoded)
171
+ curl http://localhost:3423/api/knowledge/projects%2Fmy-project.md
172
172
 
173
173
  # Write an entry
174
- curl -X PUT http://localhost:3423/api/knowledge/notes/my-note \
174
+ curl -X POST http://localhost:3423/api/knowledge \
175
175
  -H 'Content-Type: application/json' \
176
- -d '{"content": "---\ntitle: My Note\ntags: [example]\n---\n\nContent here."}'
176
+ -d '{"category": "notes", "filename": "my-note", "content": "---\ntitle: My Note\ntags: [example]\n---\n\nContent here."}'
177
177
  ```
178
178
 
179
179
  ---
@@ -184,7 +184,7 @@ agent-knowledge ships **6 hook scripts** that wire into Claude Code's lifecycle
184
184
 
185
185
  | Hook | Event | Purpose |
186
186
  | -------------------------- | ---------------- | -------------------------------------------------------------------------------- |
187
- | `session-start.js` | SessionStart | Dashboard URL + auto-loads token-budgeted wakeup payload into context |
187
+ | `session-start.js` | SessionStart | Names the `/knowledge` pane + auto-loads the L0 identity into context |
188
188
  | `session-start-ingest.mjs` | SessionStart | Detects project + reports knowledge-ingest cache drift via SHA256 diff |
189
189
  | `first-prompt-inject.mjs` | UserPromptSubmit | v1.8 — query-targeted knowledge hits injected on the session's first real prompt |
190
190
  | `precompact-flush.mjs` | PreCompact | Rich session summary on disk + save-unsaved-context nudge into context |
@@ -289,7 +289,7 @@ Mirrors the Claude Code hooks where opencode has an equivalent event:
289
289
 
290
290
  | Claude Code hook | OpenCode analog | Behavior |
291
291
  | ------------------------- | --------------------------------- | --------------------------------------------------------------------- |
292
- | `session-start.js` | `event: session.created` | Dashboard URL toast + clears stale first-prompt marker on resume. |
292
+ | `session-start.js` | `event: session.created` | Knowledge-base toast + clears stale first-prompt marker on resume. |
293
293
  | `first-prompt-inject.mjs` | `chat.message` | Searches the KB and prepends a rendered hits block to the user parts. |
294
294
  | `precompact-flush.mjs` | `experimental.session.compacting` | Pushes a "save unsaved knowledge before compaction" nudge. |
295
295
  | `sessionend-distill.mjs` | `event: session.deleted` | Writes `~/agent-knowledge/projects/session-opencode-<slug>.md`. |
@@ -304,14 +304,14 @@ Not ported (opencode has no equivalent surface):
304
304
 
305
305
  Same as the Claude hooks, all optional:
306
306
 
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]`. |
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` | REST 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]`. |
315
315
 
316
316
  Every hook fails open — errors during search, toast, session walk, or disk write are swallowed and the user is never blocked.
317
317
 
@@ -372,7 +372,7 @@ Before ending a session, save non-obvious learnings to agent-knowledge:
372
372
  1. `knowledge_search` for existing entries that overlap with this session's work.
373
373
  2. `knowledge { action: "write" }` new entries for decisions, architecture changes, or error patterns
374
374
  that aren't already captured.
375
- 3. `knowledge_link` related entries together.
375
+ 3. Link related entries together with `knowledge_graph` action `link`.
376
376
 
377
377
  Categories: projects (project context), decisions (trade-offs made), workflows (processes),
378
378
  notes (everything else).
@@ -402,7 +402,7 @@ agent-knowledge ships a **knowledge-ingest** skill for bootstrapping or updating
402
402
 
403
403
  ### Manual installation
404
404
 
405
- Copy `skills/knowledge-ingest/SKILL.md` to any of these locations:
405
+ Copy `plugin/skills/knowledge-ingest/SKILL.md` to any of these locations:
406
406
 
407
407
  ```bash
408
408
  # Claude Code, OpenCode, Cursor
@@ -469,8 +469,8 @@ Architecture notes, deployment info, etc.
469
469
  | `AGENT_KNOWLEDGE_DATA_DIR` | (platform config) | Override primary host data root (adapters auto-detect otherwise) |
470
470
  | `AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS` | -- | Additional session directories, comma-separated |
471
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) |
472
+ | `AGENT_KNOWLEDGE_PORT` | `3423` | Local REST API port (the `/knowledge` pane, hooks, agent-tasks) |
473
+ | `AGENT_KNOWLEDGE_HOST` | `127.0.0.1` | REST bind address |
474
474
  | `AGENT_KNOWLEDGE_EMBEDDING_PROVIDER` | `local` | Embedding provider (local, openai, claude, gemini) |
475
475
  | `AGENT_KNOWLEDGE_EMBEDDING_ALPHA` | `0.5` | Blend weight for semantic vs TF-IDF search (0-1) |
476
476
  | `AGENT_KNOWLEDGE_EMBEDDING_IDLE_TIMEOUT` | — | Idle timeout for embedding worker (ms) |
@@ -496,13 +496,16 @@ $env:AGENT_KNOWLEDGE_MEMORY_DIR = "$env:USERPROFILE\agent-knowledge"
496
496
 
497
497
  ---
498
498
 
499
- ## Dashboard
499
+ ## The /knowledge pane
500
500
 
501
- Auto-starts with the MCP server at **http://localhost:3423**.
501
+ In Claude Code (2.1.289+), install the plugin and type `/knowledge`:
502
502
 
503
- 4 tabs: Knowledge, Search, Sessions, Embeddings. Supports light/dark theme.
503
+ ```bash
504
+ claude plugin marketplace add keshrath/agent-knowledge
505
+ claude plugin install agent-knowledge@agent-knowledge
506
+ ```
504
507
 
505
- Live reload: edit files in `src/ui/` and the browser refreshes automatically.
508
+ 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
509
 
507
510
  ---
508
511
 
@@ -524,7 +527,7 @@ cd ~/agent-knowledge && git pull && git push # Should work without prompts
524
527
 
525
528
  ## Session Sources
526
529
 
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.
530
+ 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
531
 
529
532
  | Tool | Format | Auto-detected path | Override |
530
533
  | ---------------- | -------------- | --------------------------------------------------------------- | ------------------------------------- |
@@ -557,12 +560,14 @@ To manually save knowledge from any client, use `knowledge` with `action: "write
557
560
 
558
561
  ### Port already in use
559
562
 
563
+ 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:
564
+
560
565
  ```bash
561
566
  # Find the process
562
567
  netstat -ano | findstr :3423 # Windows
563
568
  lsof -i :3423 # Linux/macOS
564
569
 
565
- # Use a different port
570
+ # Use a different port (for the MCP server and the pane alike)
566
571
  export AGENT_KNOWLEDGE_PORT=3424
567
572
  ```
568
573
 
@@ -5,7 +5,7 @@
5
5
  1. [Overview](#1-overview)
6
6
  2. [Installation](#2-installation)
7
7
  3. [Configuration](#3-configuration)
8
- 4. [Dashboard Guide](#4-dashboard-guide)
8
+ 4. [The /knowledge Pane](#4-the-knowledge-pane)
9
9
  5. [MCP Tools Reference](#5-mcp-tools-reference)
10
10
  6. [REST API Reference](#6-rest-api-reference)
11
11
  7. [Knowledge Base Management](#7-knowledge-base-management)
@@ -35,16 +35,17 @@ agent-knowledge is an MCP (Model Context Protocol) server that provides cross-se
35
35
  - **Knowledge analysis** -- find most-connected concepts (god nodes), cross-category bridges, and isolated entries (gaps).
36
36
  - **Knowledge brief** -- compact ~200 token summary of the knowledge base state for session-start orientation.
37
37
  - **Pre-extracted session insights** -- distillation extracts git commits, error patterns, URLs, and package changes from session transcripts via regex (no LLM cost).
38
- - **Real-time dashboard** -- web UI showing knowledge entries, sessions, and search results.
38
+ - **`/knowledge` pane** -- the knowledge base beside the conversation in Claude Code (agent-knowledge plugin).
39
39
 
40
40
  ### Architecture
41
41
 
42
42
  agent-knowledge has two entry points:
43
43
 
44
- | Entry Point | File | Purpose |
45
- | ---------------- | ---------------- | ----------------------------------------------------------------------------------------- |
46
- | MCP stdio server | `dist/index.js` | Communicates with the AI agent via JSON-RPC over stdin/stdout. Auto-starts the dashboard. |
47
- | HTTP server | `dist/server.js` | Standalone dashboard + REST API + WebSocket. |
44
+ | Entry Point | File | Purpose |
45
+ | ---------------- | --------------------- | ---------------------------------------------------------------------------------------------------- |
46
+ | MCP stdio server | `dist/index.js` | Communicates with the AI agent via JSON-RPC over stdin/stdout. |
47
+ | REST server | `dist/rest-server.js` | Started by the MCP process that holds the port (127.0.0.1:3423); the others take over when it exits. |
48
+ | Claude Code mod | `plugin/hooks/` | The `/knowledge` pane, reading the REST API. |
48
49
 
49
50
  Internally:
50
51
 
@@ -97,7 +98,7 @@ npx agent-knowledge
97
98
 
98
99
  | Variable | Default | Description |
99
100
  | ------------------------------------- | ------------------- | ----------------------------------------------- |
100
- | `AGENT_KNOWLEDGE_PORT` | `3423` | Dashboard HTTP/WebSocket port |
101
+ | `AGENT_KNOWLEDGE_PORT` | `3423` | Local REST API port |
101
102
  | `AGENT_KNOWLEDGE_DATA_DIR` | (platform config) | Override primary host data root (auto-detected) |
102
103
  | `AGENT_KNOWLEDGE_GIT_URL` | (none) | Git remote URL for knowledge base sync |
103
104
  | `AGENT_KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Local knowledge base directory |
@@ -119,7 +120,7 @@ Add to `~/.claude.json`:
119
120
  }
120
121
  ```
121
122
 
122
- The dashboard auto-starts at http://localhost:3423.
123
+ The first MCP process also serves the local REST API on `127.0.0.1:3423`; in Claude Code, `/knowledge` (agent-knowledge plugin) shows the knowledge base in a pane.
123
124
 
124
125
  ### Permissions (settings.json)
125
126
 
@@ -147,7 +148,7 @@ agent-knowledge ships six lifecycle hook scripts that integrate with Claude Code
147
148
 
148
149
  | Script | Event | Purpose |
149
150
  | -------------------------- | ---------------- | ------------------------------------------------------------------------- |
150
- | `session-start.js` | SessionStart | Dashboard URL + auto-loads token-budgeted wakeup payload into context |
151
+ | `session-start.js` | SessionStart | Names the `/knowledge` pane + auto-loads the L0 identity into context |
151
152
  | `session-start-ingest.mjs` | SessionStart | Detects project + reports knowledge-ingest cache drift via SHA256 diff |
152
153
  | `first-prompt-inject.mjs` | UserPromptSubmit | Query-targeted knowledge hits injected on the session's first real prompt |
153
154
  | `precompact-flush.mjs` | PreCompact | Rich session summary on disk + save-unsaved-context nudge into context |
@@ -176,60 +177,148 @@ sessions.
176
177
 
177
178
  ---
178
179
 
179
- ## 4. Dashboard Guide
180
+ ## 4. The /knowledge Pane
180
181
 
181
- ### Accessing the Dashboard
182
+ In Claude Code (2.1.289+), the agent-knowledge plugin adds `/knowledge`: the knowledge base in a pane beside the conversation. Install it with:
182
183
 
183
- The dashboard is available at **http://localhost:3423** (or the port configured via `AGENT_KNOWLEDGE_PORT`).
184
+ ```bash
185
+ claude plugin marketplace add keshrath/agent-knowledge
186
+ claude plugin install agent-knowledge@agent-knowledge
187
+ ```
188
+
189
+ The pane reads the local REST API (section 6). There is no web dashboard: it was removed in 2.0.
190
+
191
+ Every picture below is from a recorded session in the real Claude Code CLI against a scratch knowledge base (`npm run manual:record`).
192
+
193
+ ![The /knowledge pane: open it, open an entry, follow a link](images/manual/hero.gif)
194
+
195
+ ### Opening it
196
+
197
+ | Type | Opens |
198
+ | -------------------- | --------------------------------------------------------------------------- |
199
+ | `/knowledge` | Browse, every entry newest first |
200
+ | `/knowledge <words>` | Search, with the hits for the words (entries and past sessions) |
201
+ | `/knowledge <path>` | that entry's page; `.md` may be left off (`/knowledge decisions/rest-only`) |
202
+
203
+ The command answers in the conversation with the counts (`8 entries · 2 sessions`), how many hits a search found, which entry it opened (`opened REST only, no WebSocket`), or why nothing answers. The pane opens beside the conversation in the fullscreen layout, above the prompt otherwise.
204
+
205
+ ![Opening the pane](images/manual/open.gif)
206
+
207
+ ### Keys
208
+
209
+ | Key | Does |
210
+ | ------------------- | ------------------------------------------------------------------- |
211
+ | `1` `2` `3` `4` | Browse, Search, Sessions, Health |
212
+ | `r` | Refresh |
213
+ | `Tab` / `shift+Tab` | move the focus ring |
214
+ | `Enter` | press what holds the ring (open a row, follow a link, fold, delete) |
215
+ | `↑` `↓` | scroll the pane |
216
+ | `Esc` | give the keyboard back to the prompt |
217
+ | `ctrl+x tab` | take it again; the ring is where you left it |
218
+
219
+ The line under the tabs says what the keys do. In a text field (Find, Search) the digits and `r` type into the field; the tab bar drops their numbers and the line says `Tab leaves the field`. With the mouse (fullscreen layout), a click presses a tab, a row or a button.
220
+
221
+ The same line shows what an action is doing (`searching "zebrafish"…`) and how it went (`✓ synced with the remote`, `✗ sync failed: …`), and clears itself after a few seconds.
222
+
223
+ ### Browse
184
224
 
185
- ### Knowledge Tab
225
+ ![Browse](images/manual/browse.png)
186
226
 
187
- Shows all knowledge base entries organized by category. Each entry card displays:
227
+ Every entry, newest first. Under each title: its category, `evergreen` for entries kept from decay, its maturity once it is past `candidate` (`established`, `proven`), its first tags and how long ago it was updated. Files at the top of the knowledge folder are under `other`. An entry another session writes or deletes shows on the next poll, without a key; the ring stays on the row it held.
188
228
 
189
- - **Title** extracted from the Markdown content or filename.
190
- - **Category** badge (`projects`, `people`, `decisions`, `workflows`, `notes`).
191
- - **Tags** from YAML frontmatter.
192
- - **Maturity** level (`candidate`, `established`, `proven`).
193
- - **Access count** -- how many times the entry has been read.
194
- - **Last accessed** timestamp.
229
+ ![Browse, the whole screen](images/manual/browse-full.png)
195
230
 
196
- Click an entry to view its full Markdown content, related entries (from the knowledge graph), and score data.
231
+ The category bar narrows the list; the counts are the knowledge base's.
197
232
 
198
- The Knowledge tab header includes analysis buttons:
233
+ ![A category](images/manual/category.gif)
199
234
 
200
- - **Duplicates** — scans entries for near-duplicates (TF-IDF similarity)
201
- - **Reflect** — finds entries with no graph connections, generates a structured prompt for the agent
202
- - **God Nodes** — opens a panel showing the most-connected entries (your core concepts)
203
- - **Bridges** — shows entries that connect different categories with a `why` explanation
204
- - **Gaps** — lists isolated entries (0-1 edges) sorted by maturity
205
- - **Brief** — displays the knowledge base summary suitable for session-start orientation
235
+ **Find** narrows by title, path or tag; a row found by a tag says `tag <name>`, and the list is headed **Matches** (`Matches in notes` with a category picked). When nothing matches, the ring is on **Clear the filter**.
206
236
 
207
- ### Sessions Tab
237
+ ![Find](images/manual/find.png)
208
238
 
209
- Lists discovered sessions from all configured sources (Claude Code, Cursor, OpenCode). Each session shows:
239
+ ![Finding by a tag](images/manual/find.gif)
210
240
 
211
- - **Session ID** (UUID).
212
- - **Project** name.
213
- - **Message count** and duration.
214
- - **Last modified** timestamp.
241
+ A long list comes 25 rows at a time: `▸ 25 more (n left)` adds the next page and puts the ring on its first row.
215
242
 
216
- Click a session to view its messages.
243
+ ### An entry
244
+
245
+ ![An entry](images/manual/entry.png)
246
+
247
+ Its title, path, category, maturity, how often agents read it and when it was updated; its tags, author and when an agent last read it (reads from the pane do not count). **Links** are its graph edges both ways: `→` it points at another entry, `←` another points at it, with the relation (`depends on`, `related to`, …) and where the link came from when it was not made by hand (`auto-link`). `Enter` on a link opens that entry; `‹` goes back the way you came, with the ring on the link you followed. Dates read as the rows read them up to a week (`2d ago`), then as the date.
248
+
249
+ ![Following a link and back](images/manual/entry.gif)
250
+
251
+ The body is drawn as Markdown, without its frontmatter (those are the facts above) and without a first heading that only repeats the title. A long body folds after 30 lines: `▸ Show all n lines`.
252
+
253
+ ![Folding a long body](images/manual/fold.gif)
254
+
255
+ **Delete** is at the end of the page and asks first, with the ring on **Never mind**; the confirmation says what happens: without a git remote the file goes from this machine, with one the deletion is pushed too, and a remote that refuses is said with it (`✓ deleted notes/x.md (not pushed: …)`).
256
+
257
+ ![Delete asks first](images/manual/confirm-delete.png)
258
+
259
+ ![Deleting](images/manual/delete.gif)
217
260
 
218
261
  ### Search
219
262
 
220
- The search bar performs hybrid search across both knowledge entries and sessions. Results are ranked by relevance combining TF-IDF and semantic similarity scores.
263
+ ![Search](images/manual/search.png)
264
+
265
+ Search finds words, and close spellings, in every entry and in past sessions (Claude Code, Cursor, OpenCode). Best matches first: **Entries** with their category and a line of the text around the match, then **Sessions** with the project, when, whether you asked it or the agent answered, and the line. An excerpt is the entry's text without its headings and code blocks, paragraphs, list items and table rows joined with `·`. The ring lands on the best hit; `Enter` opens it. With no hit the line under the tabs says so: a search typed in the field keeps the ring there to try again, and one run as `/knowledge <words>` leaves the ring on a button, so the next command you type runs as a command.
266
+
267
+ ![Searching and opening a hit](images/manual/search.gif)
268
+
269
+ ### Sessions
270
+
271
+ The recent sessions on this machine, newest first: project, when it started, how long it ran, the git branch and the first thing asked. A session opens on its summary: what was asked, files changed, commits, errors (in red) and the tools used.
272
+
273
+ ![A session's summary](images/manual/session.png)
221
274
 
222
- ### Stats
275
+ ![Sessions](images/manual/sessions.gif)
223
276
 
224
- Displays vector store statistics: total entries, knowledge entries, session entries, database size, embedding provider, and dimensions.
277
+ ### Health
278
+
279
+ ![Health](images/manual/health.png)
280
+
281
+ How many entries (by category) and sessions there are, whether search uses meaning too (`words and meaning: n vectors`) or words only, where the knowledge folder is and whether a git remote syncs it. **Sync now** (shown with a remote) pulls and pushes. **Analyze links** lists the most linked entries (two links or more) and, apart from them, the ones with one link or none: those are the entries nothing much leads to. The folder is cut from the left to fit (`…\knowledge`). **Recent activity** lists what the hooks reported, such as a session distilled at its end.
282
+
283
+ ![Analyzing the links](images/manual/health.gif)
284
+
285
+ ### Status line, toasts and what the model sees
286
+
287
+ The status line under the prompt reads `agent-knowledge: 8 entries · 2 sessions`, from the moment a session starts; `offline` when nothing answers, `old server x on the port` when an agent-knowledge from before the pane does.
288
+
289
+ A live event (a session distilled at its end) is toasted once, beside the conversation, and listed under Health.
290
+
291
+ ![A toast](images/manual/toast.png)
292
+
293
+ The model is told, once per conversation, what the knowledge base holds (`agent-knowledge holds 8 entries · 2 sessions (projects 2, …)`), to search it before saying something is unknown, and that you browse it in `/knowledge`.
294
+
295
+ ### Layouts
296
+
297
+ Docked in the fullscreen layout the pane takes the right side of the window; on a narrow window it is about 40 columns wide and its tab bar wraps between two tabs. Without the fullscreen layout it opens above the prompt.
298
+
299
+ ![Docked narrow](images/manual/narrow.png)
300
+
301
+ ![Above the prompt](images/manual/inline.png)
302
+
303
+ ### When the server is away
225
304
 
226
- ### Theme Toggle
305
+ One agent-knowledge MCP process serves the REST API on `127.0.0.1:3423`; when its session ends another one takes the port over within a few seconds. While nothing answers, the pane says so and offers only **Refresh**; it comes back by itself on the next poll.
227
306
 
228
- Dark and light themes available. Preference saved in `localStorage`.
307
+ ![The server away](images/manual/server-down.png)
229
308
 
230
- ### Real-Time Updates
309
+ ![The server away and back](images/manual/server-down.gif)
231
310
 
232
- The dashboard connects via WebSocket. On connect, it receives the full state snapshot. A file watcher monitors the UI directory for hot-reload during development. The state snapshot is cached for 30 seconds to avoid expensive disk and database scans.
311
+ ### Troubleshooting
312
+
313
+ | You see | Do |
314
+ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
315
+ | `The agent-knowledge server is not reachable` | Check in `/mcp` that agent-knowledge is connected; `AGENT_KNOWLEDGE_PORT` must be the same for the pane and the server. |
316
+ | `An older agent-knowledge (1.x) holds the port` | End the sessions (or the process) still running 1.x; a current one takes the port over. Then **Refresh**. |
317
+ | `words only: no embeddings yet` | Search still works; for meaning too, configure an embedding provider (section 3). |
318
+ | `no remote: entries stay on this machine` | Set `AGENT_KNOWLEDGE_GIT_URL` or make the knowledge folder a git clone. |
319
+ | `pane not shown: …` after `/knowledge` | The window is too narrow for a docked pane; widen it or leave the fullscreen layout. |
320
+
321
+ The pictures are recorded with `npm run manual:record` (needs `npm run build` and a logged-in `claude`; it makes no model calls). `npm run manual:record -- health` writes only the pictures whose name contains `health`.
233
322
 
234
323
  ---
235
324
 
@@ -746,7 +835,7 @@ knowledge_analyze with action "search_gaps", since_days 7, min_count 3
746
835
 
747
836
  ## 6. REST API Reference
748
837
 
749
- The REST API is served by the dashboard. All endpoints are loopback only: foreign `Host`/`Origin` headers get 403, request bodies must be `application/json`, no wildcard CORS. Rate limited: 100 requests/minute general, 20 requests/minute for search/analyze endpoints.
838
+ The first MCP process serves a local REST API on `127.0.0.1:3423` (`AGENT_KNOWLEDGE_PORT`); the other sessions retry the port and take it over when that process exits. It is what the `/knowledge` pane, the hook scripts, the opencode plugin and agent-tasks call. Loopback only: a foreign `Host` or any `Origin` header gets 403, request bodies must be `application/json`, no CORS. A `:path` with a slash is sent encoded (`projects%2Fbackend.md`).
750
839
 
751
840
  ### Health
752
841
 
@@ -757,54 +846,29 @@ GET /health Status, version, uptime, knowledge ent
757
846
  ### Knowledge Entries
758
847
 
759
848
  ```
760
- GET /api/knowledge List entries (?category=&tag=)
761
- GET /api/knowledge/:path Read entry content (enriched with score data)
762
- GET /api/knowledge/:path/links Get graph edges for an entry
763
- GET /api/knowledge/search Search entries (?q=&category=&max_results=)
764
- GET /api/knowledge/consolidate Find duplicates (?category=&threshold=)
765
- GET /api/knowledge/reflect Find unconnected entries (?category=&max_entries=)
766
- GET /api/knowledge/god-nodes Most-connected entries (?top_n=)
767
- GET /api/knowledge/bridges Cross-category connectors (?top_n=)
768
- GET /api/knowledge/gaps Isolated entries (?max_entries=)
769
- GET /api/knowledge/brief Cached knowledge base brief
849
+ GET /api/overview Counts, categories, recent events (the pane)
850
+ GET /api/knowledge List entries with scoring (?category=&tag=)
851
+ GET /api/knowledge/search Search entries (?q=&category=&max_results=)
852
+ GET /api/knowledge/:path Read entry content (enriched with score data); 404 when missing
853
+ GET /api/knowledge/:path/links Graph edges for an entry, each with the other end's title
854
+ DELETE /api/knowledge/:path Delete an entry (git synced)
855
+ POST /api/knowledge Write an entry: { category, filename, content } -> 201 { path, git, autoLinks?, duplicateWarnings? }
856
+ POST /api/knowledge/sync git pull + push
857
+ GET /api/analysis Hubs and isolated entries (the pane)
770
858
  ```
771
859
 
772
- ### `GET /api/knowledge/god-nodes`
773
-
774
- Query params: `top_n` (number, default 10).
775
-
776
- Returns: same as `knowledge_analyze(action: "god_nodes")`.
777
-
778
- ### `GET /api/knowledge/bridges`
779
-
780
- Query params: `top_n` (number, default 5).
781
-
782
- Returns: same as `knowledge_analyze(action: "bridges")`.
783
-
784
- ### `GET /api/knowledge/gaps`
785
-
786
- Query params: `max_entries` (number, default 30).
787
-
788
- Returns: same as `knowledge_analyze(action: "gaps")`.
789
-
790
- ### `GET /api/knowledge/brief`
791
-
792
- No query params. Returns the cached knowledge brief.
793
-
794
860
  ### Sessions
795
861
 
796
862
  ```
797
- GET /api/sessions List sessions (?project=&limit=&offset=)
798
- GET /api/sessions/:id Get session messages (?project=&include_tools=&tail=)
799
- GET /api/sessions/:id/summary Get session summary (?project=)
863
+ GET /api/sessions Sessions, paged: { sessions, total } (?project=&limit=&offset=; limit default 50, max 500)
800
864
  GET /api/sessions/search Search sessions (?q=&role=&max_results=&ranked=&project=&semantic=)
801
- GET /api/sessions/recall Scoped recall (?scope=&q=&max_results=&project=)
865
+ GET /api/sessions/:id/summary Session summary (?project=); 404 when unknown
802
866
  ```
803
867
 
804
- ### Index Status
868
+ ### Events
805
869
 
806
870
  ```
807
- GET /api/index-status Vector store statistics
871
+ POST /api/events { kind, message } -> 201 { id, ts }: a receipt the /knowledge pane shows (the sessionend hook)
808
872
  ```
809
873
 
810
874
  ### Example Requests
@@ -817,7 +881,7 @@ curl http://localhost:3423/health
817
881
  curl http://localhost:3423/api/knowledge
818
882
 
819
883
  # Read a specific entry
820
- curl http://localhost:3423/api/knowledge/projects/backend.md
884
+ curl http://localhost:3423/api/knowledge/projects%2Fbackend.md
821
885
 
822
886
  # Search knowledge
823
887
  curl "http://localhost:3423/api/knowledge/search?q=authentication&max_results=5"
@@ -825,9 +889,6 @@ curl "http://localhost:3423/api/knowledge/search?q=authentication&max_results=5"
825
889
  # Search sessions
826
890
  curl "http://localhost:3423/api/sessions/search?q=deploy+error&role=assistant&max_results=10"
827
891
 
828
- # Scoped recall
829
- curl "http://localhost:3423/api/sessions/recall?scope=errors&q=ECONNREFUSED"
830
-
831
892
  # List sessions for a project
832
893
  curl "http://localhost:3423/api/sessions?project=backend&limit=20"
833
894
  ```
@@ -983,14 +1044,14 @@ If no provider is available, search falls back to pure TF-IDF.
983
1044
 
984
1045
  ## 9. Troubleshooting
985
1046
 
986
- ### Dashboard Won't Start
1047
+ ### The /knowledge pane says the server is not reachable
987
1048
 
988
- **Symptom:** Port 3423 already in use.
1049
+ **Cause:** no running session serves the REST API, or something other than agent-knowledge holds port 3423.
989
1050
 
990
1051
  **Solutions:**
991
1052
 
992
- 1. Set `AGENT_KNOWLEDGE_PORT=3424` in the MCP config env.
993
- 2. Multiple MCP instances share the same database. Only one serves the dashboard.
1053
+ 1. Check in `/mcp` that agent-knowledge is connected: the first MCP process serves the port, and when it exits another session takes it over within about 5 seconds.
1054
+ 2. If another program holds 3423, set `AGENT_KNOWLEDGE_PORT=3424` for the MCP server and the pane alike.
994
1055
 
995
1056
  ### Search Returns No Results
996
1057
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-knowledge",
3
- "version": "1.9.8",
3
+ "version": "2.0.0",
4
4
  "description": "Cross-session memory and recall for AI agents — git-synced knowledge base, knowledge graph, confidence scoring, hybrid semantic+TF-IDF search, auto-distillation with secrets scrubbing",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -26,17 +26,14 @@
26
26
  "files": [
27
27
  "dist/",
28
28
  "scripts/",
29
- "skills/",
30
- ".claude-plugin/",
31
- ".mcp.json",
32
- "agent-desk-plugin.json",
29
+ "plugin/skills/",
33
30
  "docs/*.md",
34
31
  "README.md",
35
32
  "CHANGELOG.md",
36
33
  "LICENSE"
37
34
  ],
38
35
  "scripts": {
39
- "build": "tsc && node scripts/copy-ui.js",
36
+ "build": "tsc",
40
37
  "start": "node dist/index.js",
41
38
  "dev": "tsc --watch",
42
39
  "test": "vitest run",
@@ -52,8 +49,11 @@
52
49
  "format:check": "prettier --check .",
53
50
  "typecheck": "tsc --noEmit",
54
51
  "check": "npm run typecheck && npm run lint && npm run format:check && npm run test",
52
+ "plugin:check": "claude plugin validate plugin && claude plugin test plugin",
55
53
  "clean": "rm -rf dist",
56
- "prepare": "husky"
54
+ "prepare": "husky",
55
+ "e2e:claude": "npm run build && node tests/e2e-claude/run.mjs",
56
+ "manual:record": "npm run build && tsx tests/e2e-claude/manual.ts"
57
57
  },
58
58
  "keywords": [
59
59
  "mcp",
@@ -84,25 +84,28 @@
84
84
  "homepage": "https://github.com/keshrath/agent-knowledge#readme",
85
85
  "dependencies": {
86
86
  "@modelcontextprotocol/sdk": "^1.0.0",
87
- "agent-common": "^1.1.2",
88
87
  "better-sqlite3": "^12.8.0",
89
- "morphdom": "^2.7.8",
90
88
  "sqlite-vec": "^0.1.0",
91
89
  "tree-sitter-wasms": "^0.1.13",
92
- "vis-data": "^8.0.3",
93
- "vis-network": "^10.0.2",
94
- "web-tree-sitter": "^0.24.7",
95
- "ws": "^8.20.0"
90
+ "web-tree-sitter": "^0.24.7"
96
91
  },
97
92
  "devDependencies": {
98
93
  "@eslint/js": "^10.0.1",
94
+ "@playwright/test": "^1.59.1",
99
95
  "@types/better-sqlite3": "^7.6.0",
100
96
  "@types/node": "^25.5.0",
97
+ "@types/pngjs": "^6.0.5",
101
98
  "@types/stream-json": "^1.7.8",
102
- "@types/ws": "^8.18.1",
99
+ "@xterm/addon-serialize": "^0.14.0",
100
+ "@xterm/addon-unicode11": "^0.9.0",
101
+ "@xterm/headless": "^6.0.0",
102
+ "@xterm/xterm": "^6.0.0",
103
103
  "eslint": "^10.1.0",
104
+ "gifenc": "^1.0.3",
104
105
  "husky": "^9.0.0",
105
106
  "lint-staged": "^16.0.0",
107
+ "node-pty": "^1.1.0",
108
+ "pngjs": "^7.0.0",
106
109
  "prettier": "^3.8.1",
107
110
  "stream-json": "^2.1.0",
108
111
  "tsx": "^4.21.0",
@@ -180,7 +180,7 @@ knowledge_graph({ action: "link", source: "decisions/<project>-<decision>.md", t
180
180
  23. Run the validation script to verify the ingest produced correct results:
181
181
 
182
182
  ```bash
183
- node "<agent-knowledge-repo>/skills/knowledge-ingest/scripts/validate.mjs" "<target-path>"
183
+ node "<agent-knowledge-repo>/plugin/skills/knowledge-ingest/scripts/validate.mjs" "<target-path>"
184
184
  ```
185
185
 
186
186
  24. Parse the JSON output. If `status` is `FAIL`: