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.
- package/CHANGELOG.md +34 -0
- package/README.md +39 -41
- package/dist/events.d.ts +10 -0
- package/dist/events.d.ts.map +1 -0
- package/dist/events.js +23 -0
- package/dist/events.js.map +1 -0
- package/dist/index.js +19 -13
- package/dist/index.js.map +1 -1
- package/dist/knowledge/consolidate.d.ts +2 -2
- package/dist/knowledge/consolidate.js +2 -2
- package/dist/knowledge/freshness.js +1 -1
- package/dist/knowledge/freshness.js.map +1 -1
- package/dist/knowledge/git.d.ts.map +1 -1
- package/dist/knowledge/git.js +2 -3
- package/dist/knowledge/git.js.map +1 -1
- 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/search.d.ts +6 -0
- package/dist/knowledge/search.d.ts.map +1 -1
- package/dist/knowledge/search.js +49 -3
- package/dist/knowledge/search.js.map +1 -1
- package/dist/knowledge/store.d.ts +3 -1
- package/dist/knowledge/store.d.ts.map +1 -1
- package/dist/knowledge/store.js +2 -5
- 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 +21 -0
- package/dist/rest-server.d.ts.map +1 -0
- package/dist/rest-server.js +77 -0
- package/dist/rest-server.js.map +1 -0
- package/dist/server.d.ts +1 -5
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +1 -8
- package/dist/server.js.map +1 -1
- 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.map +1 -1
- package/dist/sessions/parser.js +32 -2
- package/dist/sessions/parser.js.map +1 -1
- package/dist/sessions/summary.d.ts.map +1 -1
- package/dist/sessions/summary.js +16 -1
- package/dist/sessions/summary.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 +307 -0
- package/dist/transport/rest.js.map +1 -0
- package/docs/ARCHITECTURE.md +23 -34
- package/docs/HOOKS.md +16 -16
- package/docs/INGEST.md +1 -1
- package/docs/SETUP.md +31 -26
- package/docs/USER-MANUAL.md +150 -89
- package/package.json +17 -14
- package/{skills → plugin/skills}/knowledge-ingest/SKILL.md +1 -1
- package/scripts/hooks/session-start.js +6 -7
- package/scripts/hooks/sessionend-distill.mjs +5 -5
- package/scripts/plugins/opencode/agent-knowledge.ts +6 -6
- package/scripts/setup.js +8 -7
- 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/{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
|
-
- [
|
|
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
|
|
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
|
|
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 |
|
|
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` |
|
|
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` |
|
|
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.
|
|
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` |
|
|
473
|
-
| `AGENT_KNOWLEDGE_HOST` | `127.0.0.1` |
|
|
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
|
-
##
|
|
499
|
+
## The /knowledge pane
|
|
500
500
|
|
|
501
|
-
|
|
501
|
+
In Claude Code (2.1.289+), install the plugin and type `/knowledge`:
|
|
502
502
|
|
|
503
|
-
|
|
503
|
+
```bash
|
|
504
|
+
claude plugin marketplace add keshrath/agent-knowledge
|
|
505
|
+
claude plugin install agent-knowledge@agent-knowledge
|
|
506
|
+
```
|
|
504
507
|
|
|
505
|
-
|
|
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
|
|
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
|
|
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
|
|
|
@@ -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 |
|
|
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.
|
|
180
|
+
## 4. The /knowledge Pane
|
|
180
181
|
|
|
181
|
-
|
|
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
|
-
|
|
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
|
+

|
|
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
|
+

|
|
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
|
-
|
|
225
|
+

|
|
186
226
|
|
|
187
|
-
|
|
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
|
-
|
|
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
|
+

|
|
195
230
|
|
|
196
|
-
|
|
231
|
+
The category bar narrows the list; the counts are the knowledge base's.
|
|
197
232
|
|
|
198
|
-
|
|
233
|
+

|
|
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
|
+
**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
|
-
|
|
237
|
+

|
|
208
238
|
|
|
209
|
-
|
|
239
|
+

|
|
210
240
|
|
|
211
|
-
|
|
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
|
-
|
|
243
|
+
### An entry
|
|
244
|
+
|
|
245
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
258
|
+
|
|
259
|
+

|
|
217
260
|
|
|
218
261
|
### Search
|
|
219
262
|
|
|
220
|
-
|
|
263
|
+

|
|
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
|
+

|
|
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
|
+

|
|
221
274
|
|
|
222
|
-
|
|
275
|
+

|
|
223
276
|
|
|
224
|
-
|
|
277
|
+
### Health
|
|
278
|
+
|
|
279
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
300
|
+
|
|
301
|
+

|
|
302
|
+
|
|
303
|
+
### When the server is away
|
|
225
304
|
|
|
226
|
-
|
|
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
|
-
|
|
307
|
+

|
|
229
308
|
|
|
230
|
-
|
|
309
|
+

|
|
231
310
|
|
|
232
|
-
|
|
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
|
|
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
|
|
761
|
-
GET
|
|
762
|
-
GET
|
|
763
|
-
GET
|
|
764
|
-
GET
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
GET
|
|
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
|
|
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/
|
|
865
|
+
GET /api/sessions/:id/summary Session summary (?project=); 404 when unknown
|
|
802
866
|
```
|
|
803
867
|
|
|
804
|
-
###
|
|
868
|
+
### Events
|
|
805
869
|
|
|
806
870
|
```
|
|
807
|
-
|
|
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
|
|
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
|
-
###
|
|
1047
|
+
### The /knowledge pane says the server is not reachable
|
|
987
1048
|
|
|
988
|
-
**
|
|
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.
|
|
993
|
-
2.
|
|
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": "
|
|
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
|
|
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
|
-
"
|
|
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",
|
|
@@ -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`:
|