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.
- package/CHANGELOG.md +82 -0
- package/README.md +53 -52
- package/dist/events.d.ts +16 -0
- package/dist/events.d.ts.map +1 -0
- package/dist/events.js +31 -0
- package/dist/events.js.map +1 -0
- package/dist/index.js +31 -13
- package/dist/index.js.map +1 -1
- package/dist/knowledge/analyze.d.ts.map +1 -1
- package/dist/knowledge/analyze.js +18 -11
- package/dist/knowledge/analyze.js.map +1 -1
- package/dist/knowledge/consolidate.d.ts +2 -2
- package/dist/knowledge/consolidate.js +2 -2
- package/dist/knowledge/distill.d.ts.map +1 -1
- package/dist/knowledge/distill.js +28 -16
- package/dist/knowledge/distill.js.map +1 -1
- package/dist/knowledge/freshness.js +1 -1
- package/dist/knowledge/freshness.js.map +1 -1
- package/dist/knowledge/git.d.ts +3 -4
- package/dist/knowledge/git.d.ts.map +1 -1
- package/dist/knowledge/git.js +62 -49
- package/dist/knowledge/git.js.map +1 -1
- package/dist/knowledge/graph.d.ts +2 -0
- package/dist/knowledge/graph.d.ts.map +1 -1
- package/dist/knowledge/graph.js +8 -0
- package/dist/knowledge/graph.js.map +1 -1
- package/dist/knowledge/ingest-freshness.d.ts +22 -0
- package/dist/knowledge/ingest-freshness.d.ts.map +1 -0
- package/dist/knowledge/ingest-freshness.js +93 -0
- package/dist/knowledge/ingest-freshness.js.map +1 -0
- package/dist/knowledge/promote.js +1 -1
- package/dist/knowledge/promote.js.map +1 -1
- package/dist/knowledge/reflect.js +2 -2
- package/dist/knowledge/reflect.js.map +1 -1
- package/dist/knowledge/remove.d.ts +11 -0
- package/dist/knowledge/remove.d.ts.map +1 -0
- package/dist/knowledge/remove.js +24 -0
- package/dist/knowledge/remove.js.map +1 -0
- package/dist/knowledge/search.d.ts +76 -4
- package/dist/knowledge/search.d.ts.map +1 -1
- package/dist/knowledge/search.js +364 -37
- package/dist/knowledge/search.js.map +1 -1
- package/dist/knowledge/similar.d.ts +7 -0
- package/dist/knowledge/similar.d.ts.map +1 -0
- package/dist/knowledge/similar.js +51 -0
- package/dist/knowledge/similar.js.map +1 -0
- package/dist/knowledge/store.d.ts +20 -1
- package/dist/knowledge/store.d.ts.map +1 -1
- package/dist/knowledge/store.js +119 -84
- package/dist/knowledge/store.js.map +1 -1
- package/dist/lib.d.ts +1 -1
- package/dist/lib.d.ts.map +1 -1
- package/dist/lib.js.map +1 -1
- package/dist/package-meta.d.ts +4 -1
- package/dist/package-meta.d.ts.map +1 -1
- package/dist/package-meta.js +18 -9
- package/dist/package-meta.js.map +1 -1
- package/dist/rest-server.d.ts +31 -0
- package/dist/rest-server.d.ts.map +1 -0
- package/dist/rest-server.js +142 -0
- package/dist/rest-server.js.map +1 -0
- package/dist/search/bm25.d.ts +8 -0
- package/dist/search/bm25.d.ts.map +1 -1
- package/dist/search/bm25.js +32 -20
- package/dist/search/bm25.js.map +1 -1
- package/dist/search/excerpt.d.ts +1 -1
- package/dist/search/excerpt.d.ts.map +1 -1
- package/dist/search/excerpt.js +19 -1
- package/dist/search/excerpt.js.map +1 -1
- package/dist/search/lexicon.d.ts +37 -0
- package/dist/search/lexicon.d.ts.map +1 -0
- package/dist/search/lexicon.js +83 -0
- package/dist/search/lexicon.js.map +1 -0
- package/dist/search/mmr.d.ts +9 -3
- package/dist/search/mmr.d.ts.map +1 -1
- package/dist/search/mmr.js +21 -7
- package/dist/search/mmr.js.map +1 -1
- package/dist/search/types.d.ts +2 -0
- package/dist/search/types.d.ts.map +1 -1
- package/dist/server.d.ts +1 -5
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +1 -13
- package/dist/server.js.map +1 -1
- package/dist/sessions/human.d.ts +12 -0
- package/dist/sessions/human.d.ts.map +1 -0
- package/dist/sessions/human.js +52 -0
- package/dist/sessions/human.js.map +1 -0
- package/dist/sessions/indexer.d.ts +4 -0
- package/dist/sessions/indexer.d.ts.map +1 -1
- package/dist/sessions/indexer.js +6 -1
- package/dist/sessions/indexer.js.map +1 -1
- package/dist/sessions/parser.d.ts +39 -0
- package/dist/sessions/parser.d.ts.map +1 -1
- package/dist/sessions/parser.js +169 -15
- package/dist/sessions/parser.js.map +1 -1
- package/dist/sessions/search.d.ts +2 -0
- package/dist/sessions/search.d.ts.map +1 -1
- package/dist/sessions/search.js +147 -67
- package/dist/sessions/search.js.map +1 -1
- package/dist/sessions/snapshot.d.ts +19 -0
- package/dist/sessions/snapshot.d.ts.map +1 -0
- package/dist/sessions/snapshot.js +118 -0
- package/dist/sessions/snapshot.js.map +1 -0
- package/dist/sessions/summary.d.ts +24 -5
- package/dist/sessions/summary.d.ts.map +1 -1
- package/dist/sessions/summary.js +122 -146
- package/dist/sessions/summary.js.map +1 -1
- package/dist/slice.d.ts +5 -0
- package/dist/slice.d.ts.map +1 -0
- package/dist/slice.js +28 -0
- package/dist/slice.js.map +1 -0
- package/dist/text.d.ts +9 -0
- package/dist/text.d.ts.map +1 -0
- package/dist/text.js +16 -0
- package/dist/text.js.map +1 -0
- package/dist/tool-handlers.d.ts.map +1 -1
- package/dist/tool-handlers.js +6 -10
- package/dist/tool-handlers.js.map +1 -1
- package/dist/transport/guard.d.ts +5 -0
- package/dist/transport/guard.d.ts.map +1 -0
- package/dist/transport/guard.js +51 -0
- package/dist/transport/guard.js.map +1 -0
- package/dist/transport/http.d.ts +17 -0
- package/dist/transport/http.d.ts.map +1 -0
- package/dist/transport/http.js +97 -0
- package/dist/transport/http.js.map +1 -0
- package/dist/transport/rest.d.ts +4 -0
- package/dist/transport/rest.d.ts.map +1 -0
- package/dist/transport/rest.js +424 -0
- package/dist/transport/rest.js.map +1 -0
- package/dist/vectorstore/store.d.ts +9 -0
- package/dist/vectorstore/store.d.ts.map +1 -1
- package/dist/vectorstore/store.js +23 -0
- package/dist/vectorstore/store.js.map +1 -1
- package/dist/wakeup.d.ts +5 -0
- package/dist/wakeup.d.ts.map +1 -1
- package/dist/wakeup.js +10 -1
- package/dist/wakeup.js.map +1 -1
- package/docs/ARCHITECTURE.md +25 -39
- package/docs/HOOKS.md +138 -237
- package/docs/INGEST.md +1 -1
- package/docs/SETUP.md +87 -143
- package/docs/USER-MANUAL.md +169 -100
- package/package.json +20 -17
- package/{skills → plugin/skills}/knowledge-ingest/SKILL.md +1 -1
- package/{skills → plugin/skills}/knowledge-ingest/scripts/validate.mjs +2 -2
- package/scripts/plugins/opencode/agent-knowledge.ts +37 -86
- package/scripts/setup.js +80 -146
- package/scripts/source-walk.d.mts +12 -0
- package/scripts/source-walk.mjs +94 -0
- package/scripts/tree-sitter-extract.mjs +10 -76
- package/.claude-plugin/marketplace.json +0 -19
- package/.claude-plugin/plugin.json +0 -12
- package/.mcp.json +0 -8
- package/agent-desk-plugin.json +0 -20
- package/dist/dashboard.d.ts +0 -5
- package/dist/dashboard.d.ts.map +0 -1
- package/dist/dashboard.js +0 -666
- package/dist/dashboard.js.map +0 -1
- package/dist/ui/app.js +0 -1013
- package/dist/ui/index.html +0 -460
- package/dist/ui/morphdom.min.js +0 -1
- package/dist/ui/render-graph.js +0 -482
- package/dist/ui/render-knowledge.js +0 -288
- package/dist/ui/render-panel.js +0 -475
- package/dist/ui/render-search.js +0 -105
- package/dist/ui/render-sessions.js +0 -237
- package/dist/ui/styles.css +0 -2322
- package/dist/ui/template.js +0 -173
- package/dist/ui/ui-utils.js +0 -217
- package/dist/ui/vis-network.min.js +0 -34
- package/docs/DASHBOARD.md +0 -191
- package/scripts/copy-ui.js +0 -14
- package/scripts/hooks/first-prompt-inject.mjs +0 -242
- package/scripts/hooks/precompact-distill.mjs +0 -105
- package/scripts/hooks/precompact-flush.mjs +0 -192
- package/scripts/hooks/session-start-ingest.mjs +0 -238
- package/scripts/hooks/session-start.js +0 -212
- package/scripts/hooks/sessionend-distill.mjs +0 -198
package/docs/USER-MANUAL.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
1. [Overview](#1-overview)
|
|
6
6
|
2. [Installation](#2-installation)
|
|
7
7
|
3. [Configuration](#3-configuration)
|
|
8
|
-
4. [
|
|
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
|
-
-
|
|
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
|
|
45
|
-
| ---------------- |
|
|
46
|
-
| MCP stdio server | `dist/index.js`
|
|
47
|
-
|
|
|
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` |
|
|
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
|
|
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
|
|
|
@@ -141,20 +142,18 @@ knowledge_admin with action "config", memory_dir "/custom/path/knowledge"
|
|
|
141
142
|
knowledge_admin with action "config", auto_distill false
|
|
142
143
|
```
|
|
143
144
|
|
|
144
|
-
###
|
|
145
|
+
### The session lifecycle
|
|
145
146
|
|
|
146
|
-
|
|
147
|
+
With the Claude Code plugin installed, each session works with the knowledge base on its own; there is nothing to configure:
|
|
147
148
|
|
|
148
|
-
|
|
|
149
|
-
|
|
|
150
|
-
|
|
|
151
|
-
|
|
|
152
|
-
|
|
|
153
|
-
| `
|
|
154
|
-
| `precompact-distill.mjs` | PreCompact | Lightweight text snapshot of recent user prompts |
|
|
155
|
-
| `sessionend-distill.mjs` | SessionEnd | Final summary (turn counts, tool uses, first 20 prompts) |
|
|
149
|
+
| When | What happens |
|
|
150
|
+
| -------------------------------- | --------------------------------------------------------------------------------------------------- |
|
|
151
|
+
| The conversation's first message | The model knows what the knowledge base holds, who you are (or asks you once), and the ingest state |
|
|
152
|
+
| Your first real prompt | The entries that match it ride beside it; one line in the transcript names them |
|
|
153
|
+
| A compaction | The session is snapshotted into `sessions/<project>/`; the summary keeps what is still to be saved |
|
|
154
|
+
| The session ending or `/clear` | The session's last snapshot; open `/knowledge` panes toast it |
|
|
156
155
|
|
|
157
|
-
Every
|
|
156
|
+
Every part fails open: with the server down the session goes on as without the plugin. Each has a switch (`AGENT_KNOWLEDGE_AUTOWAKE`, `AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT`, `AGENT_KNOWLEDGE_PRECOMPACT_NUDGE`, budgets) — see [`docs/HOOKS.md`](HOOKS.md). Hosts without the plugin (Cursor, Windsurf) keep the MCP tools; OpenCode has its own plugin.
|
|
158
157
|
|
|
159
158
|
### Persistent Memory — agent-knowledge, not host auto-memory
|
|
160
159
|
|
|
@@ -176,60 +175,148 @@ sessions.
|
|
|
176
175
|
|
|
177
176
|
---
|
|
178
177
|
|
|
179
|
-
## 4.
|
|
178
|
+
## 4. The /knowledge Pane
|
|
180
179
|
|
|
181
|
-
|
|
180
|
+
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
181
|
|
|
183
|
-
|
|
182
|
+
```bash
|
|
183
|
+
claude plugin marketplace add keshrath/agent-knowledge
|
|
184
|
+
claude plugin install agent-knowledge@agent-knowledge
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
The pane reads the local REST API (section 6). There is no web dashboard: it was removed in 2.0.
|
|
188
|
+
|
|
189
|
+
Every picture below is from a recorded session in the real Claude Code CLI against a scratch knowledge base (`npm run manual:record`).
|
|
190
|
+
|
|
191
|
+

|
|
192
|
+
|
|
193
|
+
### Opening it
|
|
194
|
+
|
|
195
|
+
| Type | Opens |
|
|
196
|
+
| -------------------- | --------------------------------------------------------------------------- |
|
|
197
|
+
| `/knowledge` | Browse, every entry newest first |
|
|
198
|
+
| `/knowledge <words>` | Search, with the hits for the words (entries and past sessions) |
|
|
199
|
+
| `/knowledge <path>` | that entry's page; `.md` may be left off (`/knowledge decisions/rest-only`) |
|
|
200
|
+
|
|
201
|
+
The command's reply goes to the model too, so it says something only when something is wrong: nothing found for the words, no such entry, nothing answers at the port, or the pane could not be shown (then with the counts). Plain `/knowledge` shows every entry, clearing a Find or category left from before. The pane opens beside the conversation in the fullscreen layout, above the prompt otherwise; an open pane is opened afresh.
|
|
202
|
+
|
|
203
|
+

|
|
204
|
+
|
|
205
|
+
### Keys
|
|
206
|
+
|
|
207
|
+
| Key | Does |
|
|
208
|
+
| ------------------- | ------------------------------------------------------------------- |
|
|
209
|
+
| `1` `2` `3` `4` | Browse, Search, Sessions, Health |
|
|
210
|
+
| `r` | Refresh |
|
|
211
|
+
| `Tab` / `shift+Tab` | move the focus ring |
|
|
212
|
+
| `Enter` | press what holds the ring (open a row, follow a link, fold, delete) |
|
|
213
|
+
| `↑` `↓` | scroll the pane |
|
|
214
|
+
| `Esc` | give the keyboard back to the prompt |
|
|
215
|
+
| `ctrl+x tab` | take it again; the ring is where you left it |
|
|
216
|
+
|
|
217
|
+
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.
|
|
218
|
+
|
|
219
|
+
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.
|
|
220
|
+
|
|
221
|
+
### Browse
|
|
222
|
+
|
|
223
|
+

|
|
184
224
|
|
|
185
|
-
|
|
225
|
+
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`; the session snapshots are their own category, `snapshots`, last in the bar and not in `all`. An entry another session writes or deletes shows on the next poll, without a key; the ring stays on the row it held, and while the pane has the keyboard the rows keep their order (a new one comes at the end). An empty knowledge base offers the next step: **Ingest <project> ›** puts `/knowledge-ingest <folder>` in the prompt for you to run.
|
|
186
226
|
|
|
187
|
-
|
|
227
|
+

|
|
188
228
|
|
|
189
|
-
|
|
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
|
+
The category bar narrows the list; the counts are the knowledge base's.
|
|
195
230
|
|
|
196
|
-
|
|
231
|
+

|
|
197
232
|
|
|
198
|
-
|
|
233
|
+
**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**.
|
|
199
234
|
|
|
200
|
-
|
|
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
|
+

|
|
206
236
|
|
|
207
|
-
|
|
237
|
+

|
|
208
238
|
|
|
209
|
-
|
|
239
|
+
A long list comes 25 rows at a time: `▸ 25 more` adds the next page and puts the ring on its first row, shown whole.
|
|
210
240
|
|
|
211
|
-
|
|
212
|
-
- **Project** name.
|
|
213
|
-
- **Message count** and duration.
|
|
214
|
-
- **Last modified** timestamp.
|
|
241
|
+
### An entry
|
|
215
242
|
|
|
216
|
-
|
|
243
|
+

|
|
244
|
+
|
|
245
|
+
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.
|
|
246
|
+
|
|
247
|
+

|
|
248
|
+
|
|
249
|
+
The body is drawn as Markdown, without its frontmatter (those are the facts above) and without a first heading that only repeats the title. Code is drawn apart, a dim `│` before each line: a long command that wraps continues indented, with no bar, so it never reads as a second one. Links in the text are listed with the links (`→ mentions`); a table too wide for the pane reads a row a line, each value with its header (`Owner: alice`). A long body folds after 30 lines: `▸ Show all n lines`. The page follows its file: an edit from another session shows on the next poll, said (`! notes/x.md changed elsewhere`), and an entry deleted elsewhere takes you back to the list (`! notes/x.md was deleted elsewhere`).
|
|
250
|
+
|
|
251
|
+

|
|
252
|
+
|
|
253
|
+
**Delete** is at the end of the page and asks first, with **Keep it** first and the ring on it, and **Delete notes/x.md** beside it. The question says what happens: without a git remote the file goes from this machine for good, with one the deletion is pushed too (its git history keeps it), and how many entries that link to it lose that link. A remote that refuses is said as a warning (`! deleted notes/x.md, not pushed: …`).
|
|
254
|
+
|
|
255
|
+

|
|
256
|
+
|
|
257
|
+

|
|
217
258
|
|
|
218
259
|
### Search
|
|
219
260
|
|
|
220
|
-
|
|
261
|
+

|
|
262
|
+
|
|
263
|
+
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 **In past 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. `2` again (or `Enter` on the tab) puts the ring in the field with the last search's words, to edit. With no hit the page 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.
|
|
264
|
+
|
|
265
|
+

|
|
266
|
+
|
|
267
|
+
### Sessions
|
|
268
|
+
|
|
269
|
+
The recent sessions on this machine, newest first: the project's folder name (this session marked `(this session)`), when it started, how long it ran, the git branch and the first thing asked (a slash command is not a question). Sessions where nothing was asked, a `/clear` alone say, are folded behind `▸ n more where nothing was asked`. `▸ 25 more` goes on past the newest 100, loading older sessions from the server. A session opens on its summary: how many prompts, its id and how to resume it (`claude --resume <id>`), what was asked, files changed, commits, errors (in red) and the tools used. A session snapshot's page opens its session when its transcript is on this machine, and back leads to the snapshot.
|
|
270
|
+
|
|
271
|
+

|
|
272
|
+
|
|
273
|
+

|
|
221
274
|
|
|
222
|
-
###
|
|
275
|
+
### Health
|
|
276
|
+
|
|
277
|
+

|
|
278
|
+
|
|
279
|
+
How many entries (by category), session snapshots 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, and whether this project's code is ingested (**Ingest <project> ›** when it was never, or files changed since). **Sync now** (shown with a remote) pulls and pushes; the ring never lands on it by itself. **Recent activity** lists what was reported, such as a session saved or a sync that failed. **Analyze links** lists the most linked entries (two links or more) and, apart from them, the ones with one link or none, fewest first, 30 at a time (`▸ 30 more`): those are the entries nothing much leads to. The folder is shown whole, wrapped when long.
|
|
280
|
+
|
|
281
|
+

|
|
282
|
+
|
|
283
|
+
### Status line, toasts and what the model sees
|
|
284
|
+
|
|
285
|
+
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. While the pane is shown it says the last outcome for its 10 seconds (it may be scrolled out of view). Outcomes are marked: ✓ done, ✗ failed or refused, ! changed elsewhere, – nothing happened.
|
|
286
|
+
|
|
287
|
+
A live event (a session saved at its end) is toasted once, beside the conversation (`Session saved: demo · 2026-11-13 · fix the sync`; three at most, then `+n more`), and listed under Health. A project never ingested, or files changed since its ingest, is toasted once with the conversation's first message.
|
|
288
|
+
|
|
289
|
+

|
|
290
|
+
|
|
291
|
+
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`.
|
|
292
|
+
|
|
293
|
+
### Layouts
|
|
294
|
+
|
|
295
|
+
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.
|
|
296
|
+
|
|
297
|
+

|
|
298
|
+
|
|
299
|
+

|
|
300
|
+
|
|
301
|
+
### When the server is away
|
|
302
|
+
|
|
303
|
+
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 **Refresh** tries again (`✗ still nothing answers at http://127.0.0.1:3423 (12:04:31)`); the tabs stay, so `1`–`4` never land in the prompt, and it comes back by itself on the next poll.
|
|
223
304
|
|
|
224
|
-
|
|
305
|
+

|
|
225
306
|
|
|
226
|
-
|
|
307
|
+

|
|
227
308
|
|
|
228
|
-
|
|
309
|
+
### Troubleshooting
|
|
229
310
|
|
|
230
|
-
|
|
311
|
+
| You see | Do |
|
|
312
|
+
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
313
|
+
| `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. |
|
|
314
|
+
| `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**. |
|
|
315
|
+
| `words only: no embeddings yet` | Search still works; for meaning too, configure an embedding provider (section 3). |
|
|
316
|
+
| `no remote: entries stay on this machine` | Set `AGENT_KNOWLEDGE_GIT_URL` or make the knowledge folder a git clone. |
|
|
317
|
+
| `pane not shown: …` after `/knowledge` | The window is too narrow for a docked pane; widen it or leave the fullscreen layout. |
|
|
231
318
|
|
|
232
|
-
The
|
|
319
|
+
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
320
|
|
|
234
321
|
---
|
|
235
322
|
|
|
@@ -746,65 +833,50 @@ knowledge_analyze with action "search_gaps", since_days 7, min_count 3
|
|
|
746
833
|
|
|
747
834
|
## 6. REST API Reference
|
|
748
835
|
|
|
749
|
-
The REST API
|
|
836
|
+
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 Claude Code plugin (the `/knowledge` pane and the session lifecycle), 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
837
|
|
|
751
838
|
### Health
|
|
752
839
|
|
|
753
840
|
```
|
|
754
|
-
GET /health Status, version, uptime,
|
|
841
|
+
GET /health Status, version, uptime, entries (curated) and snapshots
|
|
755
842
|
```
|
|
756
843
|
|
|
757
844
|
### Knowledge Entries
|
|
758
845
|
|
|
759
846
|
```
|
|
760
|
-
GET
|
|
761
|
-
GET
|
|
762
|
-
GET
|
|
763
|
-
GET
|
|
764
|
-
GET
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
GET
|
|
769
|
-
GET /api/knowledge/brief Cached knowledge base brief
|
|
847
|
+
GET /api/overview entries (curated), snapshots, categories (curated), recent events (the pane)
|
|
848
|
+
GET /api/knowledge List entries with scoring (?category=&tag=)
|
|
849
|
+
GET /api/knowledge/search Search entries (?q=&category=&max_results=&mmr=true&skip=sessions&min_terms=2&prompt=true; prompt: q is a prompt, reply-format phrases dropped)
|
|
850
|
+
GET /api/knowledge/:path Read entry content (enriched with score data; a snapshot adds session_on_machine); 404 when missing
|
|
851
|
+
GET /api/knowledge/:path/links Graph edges for an entry, each with the other end's title
|
|
852
|
+
DELETE /api/knowledge/:path Delete an entry (git synced)
|
|
853
|
+
POST /api/knowledge Write an entry: { category, filename, content } -> 201 { path, git, autoLinks?, duplicateWarnings? }
|
|
854
|
+
POST /api/knowledge/sync git pull + push
|
|
855
|
+
GET /api/analysis { hubs, sparse, sparse_total, offset } (?offset=&limit=30): sparse fewest links first, then by title
|
|
770
856
|
```
|
|
771
857
|
|
|
772
|
-
###
|
|
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`
|
|
858
|
+
### Sessions
|
|
791
859
|
|
|
792
|
-
|
|
860
|
+
```
|
|
861
|
+
GET /api/sessions Sessions, paged: { sessions, total } (?project=&limit=&offset=; limit default 50, max 500);
|
|
862
|
+
userMessageCount = real prompts (no /commands), preview '' without one
|
|
863
|
+
GET /api/sessions/search Search sessions (?q=&role=&max_results=&ranked=&project=&semantic=); hits carry name
|
|
864
|
+
GET /api/sessions/:id/summary Session summary (?project=); 404 when unknown
|
|
865
|
+
POST /api/sessions/:id/snapshot { event: compact|end, cwd? } -> { path, prompts, messages, tools }: the session into
|
|
866
|
+
sessions/<project>/<day>-<id>.md (path null: nothing was asked); 404 when unknown
|
|
867
|
+
```
|
|
793
868
|
|
|
794
|
-
###
|
|
869
|
+
### Session lifecycle
|
|
795
870
|
|
|
796
871
|
```
|
|
797
|
-
GET /api/
|
|
798
|
-
GET /api/
|
|
799
|
-
GET /api/sessions/:id/summary Get session summary (?project=)
|
|
800
|
-
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=)
|
|
872
|
+
GET /api/wakeup The wakeup bundle (?sections=identity,...&budget=) and onboarding: configured|declined|pending
|
|
873
|
+
GET /api/ingest The folder's ingest freshness (?cwd=): state none|never|current|stale, project, counts
|
|
802
874
|
```
|
|
803
875
|
|
|
804
|
-
###
|
|
876
|
+
### Events
|
|
805
877
|
|
|
806
878
|
```
|
|
807
|
-
|
|
879
|
+
POST /api/events { kind, message } -> 201 { id, ts }: a receipt the /knowledge pane toasts (any host)
|
|
808
880
|
```
|
|
809
881
|
|
|
810
882
|
### Example Requests
|
|
@@ -817,7 +889,7 @@ curl http://localhost:3423/health
|
|
|
817
889
|
curl http://localhost:3423/api/knowledge
|
|
818
890
|
|
|
819
891
|
# Read a specific entry
|
|
820
|
-
curl http://localhost:3423/api/knowledge/projects
|
|
892
|
+
curl http://localhost:3423/api/knowledge/projects%2Fbackend.md
|
|
821
893
|
|
|
822
894
|
# Search knowledge
|
|
823
895
|
curl "http://localhost:3423/api/knowledge/search?q=authentication&max_results=5"
|
|
@@ -825,9 +897,6 @@ curl "http://localhost:3423/api/knowledge/search?q=authentication&max_results=5"
|
|
|
825
897
|
# Search sessions
|
|
826
898
|
curl "http://localhost:3423/api/sessions/search?q=deploy+error&role=assistant&max_results=10"
|
|
827
899
|
|
|
828
|
-
# Scoped recall
|
|
829
|
-
curl "http://localhost:3423/api/sessions/recall?scope=errors&q=ECONNREFUSED"
|
|
830
|
-
|
|
831
900
|
# List sessions for a project
|
|
832
901
|
curl "http://localhost:3423/api/sessions?project=backend&limit=20"
|
|
833
902
|
```
|
|
@@ -983,14 +1052,14 @@ If no provider is available, search falls back to pure TF-IDF.
|
|
|
983
1052
|
|
|
984
1053
|
## 9. Troubleshooting
|
|
985
1054
|
|
|
986
|
-
###
|
|
1055
|
+
### The /knowledge pane says the server is not reachable
|
|
987
1056
|
|
|
988
|
-
**
|
|
1057
|
+
**Cause:** no running session serves the REST API, or something other than agent-knowledge holds port 3423.
|
|
989
1058
|
|
|
990
1059
|
**Solutions:**
|
|
991
1060
|
|
|
992
|
-
1.
|
|
993
|
-
2.
|
|
1061
|
+
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.
|
|
1062
|
+
2. If another program holds 3423, set `AGENT_KNOWLEDGE_PORT=3424` for the MCP server and the pane alike.
|
|
994
1063
|
|
|
995
1064
|
### Search Returns No Results
|
|
996
1065
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agent-knowledge",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "3.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
|
|
36
|
+
"build": "tsc",
|
|
40
37
|
"start": "node dist/index.js",
|
|
41
38
|
"dev": "tsc --watch",
|
|
42
39
|
"test": "vitest run",
|
|
@@ -46,14 +43,17 @@
|
|
|
46
43
|
"bench:longmemeval:matrix": "tsx bench/longmemeval-matrix.ts",
|
|
47
44
|
"bench:promote": "tsx bench/promote-bench.ts",
|
|
48
45
|
"test:coverage": "vitest run --coverage",
|
|
49
|
-
"lint": "eslint src/ tests/",
|
|
50
|
-
"lint:fix": "eslint src/ tests/ --fix",
|
|
46
|
+
"lint": "eslint src/ tests/ plugin/",
|
|
47
|
+
"lint:fix": "eslint src/ tests/ plugin/ --fix",
|
|
51
48
|
"format": "prettier --write .",
|
|
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": "tsc --outDir dist-e2e && node tests/e2e-claude/run.mjs",
|
|
56
|
+
"manual:record": "tsc --outDir dist-e2e && 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
|
-
"
|
|
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
|
-
"@
|
|
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",
|
|
@@ -114,7 +117,7 @@
|
|
|
114
117
|
"@huggingface/transformers": "3.8.1"
|
|
115
118
|
},
|
|
116
119
|
"lint-staged": {
|
|
117
|
-
"*.{ts,js}": [
|
|
120
|
+
"*.{ts,tsx,js,mjs}": [
|
|
118
121
|
"prettier --write",
|
|
119
122
|
"eslint --fix"
|
|
120
123
|
],
|
|
@@ -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`:
|
|
@@ -134,7 +134,7 @@ function main() {
|
|
|
134
134
|
if (cache.files && typeof cache.files === 'object') {
|
|
135
135
|
let missingHashes = 0;
|
|
136
136
|
let missingEntryRefs = 0;
|
|
137
|
-
for (const
|
|
137
|
+
for (const meta of Object.values(cache.files)) {
|
|
138
138
|
if (!meta.sha256 || typeof meta.sha256 !== 'string' || meta.sha256.length !== 64) {
|
|
139
139
|
missingHashes++;
|
|
140
140
|
}
|
|
@@ -163,7 +163,7 @@ function main() {
|
|
|
163
163
|
issues,
|
|
164
164
|
};
|
|
165
165
|
|
|
166
|
-
|
|
166
|
+
process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
|
|
167
167
|
process.exit(issues.length === 0 ? 0 : 1);
|
|
168
168
|
}
|
|
169
169
|
|