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