agent-knowledge 2.0.0 → 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 +48 -0
- package/README.md +35 -32
- package/dist/events.d.ts +6 -0
- package/dist/events.d.ts.map +1 -1
- package/dist/events.js +10 -2
- package/dist/events.js.map +1 -1
- package/dist/index.js +12 -0
- 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/distill.d.ts.map +1 -1
- package/dist/knowledge/distill.js +28 -16
- package/dist/knowledge/distill.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 +60 -46
- 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/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 +74 -8
- package/dist/knowledge/search.d.ts.map +1 -1
- package/dist/knowledge/search.js +321 -40
- 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 +17 -0
- package/dist/knowledge/store.d.ts.map +1 -1
- package/dist/knowledge/store.js +117 -79
- package/dist/knowledge/store.js.map +1 -1
- package/dist/rest-server.d.ts +12 -2
- package/dist/rest-server.d.ts.map +1 -1
- package/dist/rest-server.js +75 -10
- package/dist/rest-server.js.map +1 -1
- 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.map +1 -1
- package/dist/server.js +0 -5
- 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/parser.d.ts +39 -0
- package/dist/sessions/parser.d.ts.map +1 -1
- package/dist/sessions/parser.js +142 -18
- 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 +106 -145
- 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/rest.d.ts.map +1 -1
- package/dist/transport/rest.js +152 -35
- package/dist/transport/rest.js.map +1 -1
- 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 +6 -9
- package/docs/HOOKS.md +138 -237
- package/docs/SETUP.md +61 -122
- package/docs/USER-MANUAL.md +39 -31
- package/package.json +6 -6
- package/plugin/skills/knowledge-ingest/scripts/validate.mjs +2 -2
- package/scripts/plugins/opencode/agent-knowledge.ts +32 -81
- package/scripts/setup.js +78 -145
- package/scripts/source-walk.d.mts +12 -0
- package/scripts/source-walk.mjs +94 -0
- package/scripts/tree-sitter-extract.mjs +10 -76
- 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 -211
- package/scripts/hooks/sessionend-distill.mjs +0 -198
package/docs/SETUP.md
CHANGED
|
@@ -12,8 +12,8 @@ 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)
|
|
@@ -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 \
|
|
@@ -178,83 +187,13 @@ curl -X POST http://localhost:3423/api/knowledge \
|
|
|
178
187
|
|
|
179
188
|
---
|
|
180
189
|
|
|
181
|
-
##
|
|
182
|
-
|
|
183
|
-
agent-knowledge ships **6 hook scripts** that wire into Claude Code's lifecycle events. `scripts/setup.js` installs them automatically; the block below shows the manual equivalent. Support varies by client.
|
|
190
|
+
## Session lifecycle
|
|
184
191
|
|
|
185
|
-
|
|
186
|
-
| -------------------------- | ---------------- | -------------------------------------------------------------------------------- |
|
|
187
|
-
| `session-start.js` | SessionStart | Names the `/knowledge` pane + auto-loads the L0 identity 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) |
|
|
192
|
+
What happens around each session, beyond the tools the model calls. Support varies by client.
|
|
193
193
|
|
|
194
|
-
|
|
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,24 +224,24 @@ 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
246
|
| Variable | Default | Description |
|
|
308
247
|
| -------------------------------------- | ------------------- | ------------------------------------------------------- |
|
|
@@ -311,9 +250,9 @@ Same as the Claude hooks, all optional:
|
|
|
311
250
|
| `AGENT_KNOWLEDGE_PORT` | `3423` | REST port (plugin queries `/api/knowledge/search`). |
|
|
312
251
|
| `AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT` | `1` | Set `0` / `false` / `off` to disable inject entirely. |
|
|
313
252
|
| `AGENT_KNOWLEDGE_FIRSTPROMPT_BUDGET` | `600` | Max inject tokens (chars/4), clamped `[100, 8000]`. |
|
|
314
|
-
| `AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS` | `
|
|
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
|
|
|
@@ -390,15 +329,15 @@ 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
|
|
|
@@ -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` | Local REST API port (the
|
|
473
|
-
| `AGENT_KNOWLEDGE_HOST` | `127.0.0.1` | REST bind address
|
|
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
|
|
|
@@ -621,7 +560,7 @@ If your session data is in a non-standard location, use `AGENT_KNOWLEDGE_EXTRA_S
|
|
|
621
560
|
| -------------------- | ----------- | -------------------- | ------------- | ---------- | ------------ | -------------- | -------------- |
|
|
622
561
|
| MCP stdio transport | Yes | Yes | Yes | Yes | Yes | -- | Yes |
|
|
623
562
|
| Session reading | Yes (JSONL) | Yes (JSONL) | Yes (SQLite) | Yes (JSON) | Yes (JSON) | Yes (MD/JSONL) | -- |
|
|
624
|
-
|
|
|
563
|
+
| Session lifecycle | Yes (mod) | No | Yes (plugins) | No | No | -- | No |
|
|
625
564
|
| Session auto-distill | Yes | Yes | Yes | Yes | Yes | Yes | -- |
|
|
626
565
|
| System prompt file | CLAUDE.md | .cursor/rules/\*.mdc | AGENTS.md | -- | -- | -- | .windsurfrules |
|
|
627
566
|
| REST API fallback | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
|
package/docs/USER-MANUAL.md
CHANGED
|
@@ -142,20 +142,18 @@ knowledge_admin with action "config", memory_dir "/custom/path/knowledge"
|
|
|
142
142
|
knowledge_admin with action "config", auto_distill false
|
|
143
143
|
```
|
|
144
144
|
|
|
145
|
-
###
|
|
145
|
+
### The session lifecycle
|
|
146
146
|
|
|
147
|
-
|
|
147
|
+
With the Claude Code plugin installed, each session works with the knowledge base on its own; there is nothing to configure:
|
|
148
148
|
|
|
149
|
-
|
|
|
150
|
-
|
|
|
151
|
-
|
|
|
152
|
-
|
|
|
153
|
-
|
|
|
154
|
-
| `
|
|
155
|
-
| `precompact-distill.mjs` | PreCompact | Lightweight text snapshot of recent user prompts |
|
|
156
|
-
| `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 |
|
|
157
155
|
|
|
158
|
-
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.
|
|
159
157
|
|
|
160
158
|
### Persistent Memory — agent-knowledge, not host auto-memory
|
|
161
159
|
|
|
@@ -200,7 +198,7 @@ Every picture below is from a recorded session in the real Claude Code CLI again
|
|
|
200
198
|
| `/knowledge <words>` | Search, with the hits for the words (entries and past sessions) |
|
|
201
199
|
| `/knowledge <path>` | that entry's page; `.md` may be left off (`/knowledge decisions/rest-only`) |
|
|
202
200
|
|
|
203
|
-
The command
|
|
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.
|
|
204
202
|
|
|
205
203
|

|
|
206
204
|
|
|
@@ -224,7 +222,7 @@ The same line shows what an action is doing (`searching "zebrafish"…`) and how
|
|
|
224
222
|
|
|
225
223
|

|
|
226
224
|
|
|
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.
|
|
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.
|
|
228
226
|
|
|
229
227
|

|
|
230
228
|
|
|
@@ -238,7 +236,7 @@ The category bar narrows the list; the counts are the knowledge base's.
|
|
|
238
236
|
|
|
239
237
|

|
|
240
238
|
|
|
241
|
-
A long list comes 25 rows at a time: `▸ 25 more
|
|
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.
|
|
242
240
|
|
|
243
241
|
### An entry
|
|
244
242
|
|
|
@@ -248,11 +246,11 @@ Its title, path, category, maturity, how often agents read it and when it was up
|
|
|
248
246
|
|
|
249
247
|

|
|
250
248
|
|
|
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`.
|
|
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`).
|
|
252
250
|
|
|
253
251
|

|
|
254
252
|
|
|
255
|
-
**Delete** is at the end of the page and asks first, with the ring on **
|
|
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: …`).
|
|
256
254
|
|
|
257
255
|

|
|
258
256
|
|
|
@@ -262,13 +260,13 @@ The body is drawn as Markdown, without its frontmatter (those are the facts abov
|
|
|
262
260
|
|
|
263
261
|

|
|
264
262
|
|
|
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 **
|
|
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.
|
|
266
264
|
|
|
267
265
|

|
|
268
266
|
|
|
269
267
|
### Sessions
|
|
270
268
|
|
|
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.
|
|
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.
|
|
272
270
|
|
|
273
271
|

|
|
274
272
|
|
|
@@ -278,15 +276,15 @@ The recent sessions on this machine, newest first: project, when it started, how
|
|
|
278
276
|
|
|
279
277
|

|
|
280
278
|
|
|
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
|
|
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.
|
|
282
280
|
|
|
283
281
|

|
|
284
282
|
|
|
285
283
|
### Status line, toasts and what the model sees
|
|
286
284
|
|
|
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.
|
|
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.
|
|
288
286
|
|
|
289
|
-
A live event (a session
|
|
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.
|
|
290
288
|
|
|
291
289
|

|
|
292
290
|
|
|
@@ -302,7 +300,7 @@ Docked in the fullscreen layout the pane takes the right side of the window; on
|
|
|
302
300
|
|
|
303
301
|
### When the server is away
|
|
304
302
|
|
|
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
|
|
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.
|
|
306
304
|
|
|
307
305
|

|
|
308
306
|
|
|
@@ -835,40 +833,50 @@ knowledge_analyze with action "search_gaps", since_days 7, min_count 3
|
|
|
835
833
|
|
|
836
834
|
## 6. REST API Reference
|
|
837
835
|
|
|
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
|
|
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`).
|
|
839
837
|
|
|
840
838
|
### Health
|
|
841
839
|
|
|
842
840
|
```
|
|
843
|
-
GET /health Status, version, uptime,
|
|
841
|
+
GET /health Status, version, uptime, entries (curated) and snapshots
|
|
844
842
|
```
|
|
845
843
|
|
|
846
844
|
### Knowledge Entries
|
|
847
845
|
|
|
848
846
|
```
|
|
849
|
-
GET /api/overview
|
|
847
|
+
GET /api/overview entries (curated), snapshots, categories (curated), recent events (the pane)
|
|
850
848
|
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
|
|
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
|
|
853
851
|
GET /api/knowledge/:path/links Graph edges for an entry, each with the other end's title
|
|
854
852
|
DELETE /api/knowledge/:path Delete an entry (git synced)
|
|
855
853
|
POST /api/knowledge Write an entry: { category, filename, content } -> 201 { path, git, autoLinks?, duplicateWarnings? }
|
|
856
854
|
POST /api/knowledge/sync git pull + push
|
|
857
|
-
GET /api/analysis
|
|
855
|
+
GET /api/analysis { hubs, sparse, sparse_total, offset } (?offset=&limit=30): sparse fewest links first, then by title
|
|
858
856
|
```
|
|
859
857
|
|
|
860
858
|
### Sessions
|
|
861
859
|
|
|
862
860
|
```
|
|
863
|
-
GET /api/sessions Sessions, paged: { sessions, total } (?project=&limit=&offset=; limit default 50, max 500)
|
|
864
|
-
|
|
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
|
|
865
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
|
+
```
|
|
868
|
+
|
|
869
|
+
### Session lifecycle
|
|
870
|
+
|
|
871
|
+
```
|
|
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
|
|
866
874
|
```
|
|
867
875
|
|
|
868
876
|
### Events
|
|
869
877
|
|
|
870
878
|
```
|
|
871
|
-
POST /api/events { kind, message } -> 201 { id, ts }: a receipt the /knowledge pane
|
|
879
|
+
POST /api/events { kind, message } -> 201 { id, ts }: a receipt the /knowledge pane toasts (any host)
|
|
872
880
|
```
|
|
873
881
|
|
|
874
882
|
### Example Requests
|
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",
|
|
@@ -43,8 +43,8 @@
|
|
|
43
43
|
"bench:longmemeval:matrix": "tsx bench/longmemeval-matrix.ts",
|
|
44
44
|
"bench:promote": "tsx bench/promote-bench.ts",
|
|
45
45
|
"test:coverage": "vitest run --coverage",
|
|
46
|
-
"lint": "eslint src/ tests/",
|
|
47
|
-
"lint:fix": "eslint src/ tests/ --fix",
|
|
46
|
+
"lint": "eslint src/ tests/ plugin/",
|
|
47
|
+
"lint:fix": "eslint src/ tests/ plugin/ --fix",
|
|
48
48
|
"format": "prettier --write .",
|
|
49
49
|
"format:check": "prettier --check .",
|
|
50
50
|
"typecheck": "tsc --noEmit",
|
|
@@ -52,8 +52,8 @@
|
|
|
52
52
|
"plugin:check": "claude plugin validate plugin && claude plugin test plugin",
|
|
53
53
|
"clean": "rm -rf dist",
|
|
54
54
|
"prepare": "husky",
|
|
55
|
-
"e2e:claude": "
|
|
56
|
-
"manual:record": "
|
|
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",
|
|
@@ -117,7 +117,7 @@
|
|
|
117
117
|
"@huggingface/transformers": "3.8.1"
|
|
118
118
|
},
|
|
119
119
|
"lint-staged": {
|
|
120
|
-
"*.{ts,js}": [
|
|
120
|
+
"*.{ts,tsx,js,mjs}": [
|
|
121
121
|
"prettier --write",
|
|
122
122
|
"eslint --fix"
|
|
123
123
|
],
|
|
@@ -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
|
|