agent-knowledge 1.7.3 → 1.8.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/.claude-plugin/plugin.json +1 -1
- package/.mcp.json +1 -1
- package/CHANGELOG.md +43 -0
- package/README.md +43 -18
- package/agent-desk-plugin.json +1 -1
- package/dist/knowledge/promote.d.ts +145 -0
- package/dist/knowledge/promote.d.ts.map +1 -0
- package/dist/knowledge/promote.js +517 -0
- package/dist/knowledge/promote.js.map +1 -0
- package/dist/knowledge/scoring.d.ts +6 -2
- package/dist/knowledge/scoring.d.ts.map +1 -1
- package/dist/knowledge/scoring.js +7 -3
- package/dist/knowledge/scoring.js.map +1 -1
- package/dist/knowledge/search.d.ts +32 -5
- package/dist/knowledge/search.d.ts.map +1 -1
- package/dist/knowledge/search.js +60 -10
- package/dist/knowledge/search.js.map +1 -1
- package/dist/knowledge/store.d.ts +6 -0
- package/dist/knowledge/store.d.ts.map +1 -1
- package/dist/knowledge/store.js +10 -0
- package/dist/knowledge/store.js.map +1 -1
- package/dist/search/mmr.d.ts +54 -0
- package/dist/search/mmr.d.ts.map +1 -0
- package/dist/search/mmr.js +138 -0
- package/dist/search/mmr.js.map +1 -0
- package/dist/server.d.ts +307 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +336 -301
- package/dist/server.js.map +1 -1
- package/dist/sessions/indexer.d.ts.map +1 -1
- package/dist/sessions/indexer.js +13 -11
- package/dist/sessions/indexer.js.map +1 -1
- package/dist/tool-handlers.d.ts +10 -3
- package/dist/tool-handlers.d.ts.map +1 -1
- package/dist/tool-handlers.js +56 -17
- package/dist/tool-handlers.js.map +1 -1
- package/docs/ARCHITECTURE.md +31 -6
- package/docs/SETUP.md +20 -8
- package/docs/USER-MANUAL.md +146 -39
- package/docs/hooks.md +81 -21
- package/package.json +4 -1
- package/scripts/hooks/first-prompt-inject.mjs +230 -0
- package/scripts/hooks/precompact-flush.mjs +89 -60
- package/scripts/hooks/session-start.js +73 -9
package/dist/server.js
CHANGED
|
@@ -7,317 +7,352 @@ import { getConfig } from './types.js';
|
|
|
7
7
|
import { getVersion } from './version.js';
|
|
8
8
|
import { toolHandlers, validateArgs, err, SCOPES } from './tool-handlers.js';
|
|
9
9
|
import { CATEGORIES } from './knowledge/store.js';
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
type: 'number',
|
|
31
|
-
description: '[wakeup] Max tokens to render (chars/4 estimate, default 800)',
|
|
32
|
-
},
|
|
33
|
-
category: {
|
|
34
|
-
type: 'string',
|
|
35
|
-
enum: [...CATEGORIES],
|
|
36
|
-
description: 'Category (action=list: filter; action=write: target directory). ' +
|
|
37
|
-
'One of: projects, people, decisions, workflows, notes',
|
|
38
|
-
},
|
|
39
|
-
tag: {
|
|
40
|
-
type: 'string',
|
|
41
|
-
description: 'Filter by tag (action=list)',
|
|
42
|
-
},
|
|
43
|
-
path: {
|
|
44
|
-
type: 'string',
|
|
45
|
-
description: "Relative path to the entry, e.g. 'projects/my-project.md' (action=read, delete)",
|
|
46
|
-
},
|
|
47
|
-
filename: {
|
|
48
|
-
type: 'string',
|
|
49
|
-
description: "Filename with or without .md extension (action=write), e.g. 'my-project.md'",
|
|
50
|
-
},
|
|
51
|
-
content: {
|
|
52
|
-
type: 'string',
|
|
53
|
-
description: 'Full markdown content for the entry (action=write)',
|
|
54
|
-
},
|
|
55
|
-
},
|
|
56
|
-
required: ['action'],
|
|
57
|
-
},
|
|
10
|
+
// ── Tool definitions ─────────────────────────────────────────────────────────
|
|
11
|
+
// All six tools are exposed to the LLM. An earlier draft (dropped pre-release)
|
|
12
|
+
// hid the four advanced tools by default — in practice that saved near-zero
|
|
13
|
+
// tokens for Claude Code (which defers MCP schemas via ToolSearch anyway) and
|
|
14
|
+
// broke the knowledge-ingest skill. Clients that want a smaller surface should
|
|
15
|
+
// filter at the MCP client layer, not inside the server.
|
|
16
|
+
const KNOWLEDGE_TOOL = {
|
|
17
|
+
name: 'knowledge',
|
|
18
|
+
description: 'Knowledge base CRUD, sync, and session-start hydration. Actions: ' +
|
|
19
|
+
'"list" (browse entries), "read" (get entry content), ' +
|
|
20
|
+
'"write" (create/update entry, auto git sync), ' +
|
|
21
|
+
'"delete" (remove entry, auto git sync), "sync" (manual git pull + push), ' +
|
|
22
|
+
'"wakeup" (return token-budgeted L0 identity + L1 top-weight entries — call once at session start).',
|
|
23
|
+
inputSchema: {
|
|
24
|
+
type: 'object',
|
|
25
|
+
properties: {
|
|
26
|
+
action: {
|
|
27
|
+
type: 'string',
|
|
28
|
+
enum: ['list', 'read', 'write', 'delete', 'sync', 'wakeup'],
|
|
29
|
+
description: 'Action to perform',
|
|
58
30
|
},
|
|
59
|
-
{
|
|
60
|
-
|
|
61
|
-
description: '
|
|
62
|
-
'Returns both session matches (semantic + TF-IDF) and knowledge base matches. ' +
|
|
63
|
-
'When "scope" is provided, searches within a specific domain (errors, plans, configs, tools, files, decisions) in sessions only.',
|
|
64
|
-
inputSchema: {
|
|
65
|
-
type: 'object',
|
|
66
|
-
properties: {
|
|
67
|
-
query: {
|
|
68
|
-
type: 'string',
|
|
69
|
-
description: 'Search query -- supports keywords and phrases',
|
|
70
|
-
},
|
|
71
|
-
scope: {
|
|
72
|
-
type: 'string',
|
|
73
|
-
enum: [...SCOPES],
|
|
74
|
-
description: 'Search scope (optional): errors (stack traces), plans (architecture, TODOs), ' +
|
|
75
|
-
'configs (settings, env vars), tools (MCP tool calls), ' +
|
|
76
|
-
'files (file paths, code refs), decisions (trade-offs, choices), all (no filter). ' +
|
|
77
|
-
'When provided, performs scoped recall instead of general search.',
|
|
78
|
-
},
|
|
79
|
-
project: {
|
|
80
|
-
type: 'string',
|
|
81
|
-
description: 'Restrict search to sessions from this project',
|
|
82
|
-
},
|
|
83
|
-
role: {
|
|
84
|
-
type: 'string',
|
|
85
|
-
enum: ['user', 'assistant', 'all'],
|
|
86
|
-
description: 'Filter by message role (default: all, ignored when scope is set)',
|
|
87
|
-
},
|
|
88
|
-
max_results: {
|
|
89
|
-
type: 'number',
|
|
90
|
-
description: 'Maximum number of results to return (default: 20)',
|
|
91
|
-
},
|
|
92
|
-
ranked: {
|
|
93
|
-
type: 'boolean',
|
|
94
|
-
description: 'Use TF-IDF ranking (default: true, ignored when scope is set). Set false for regex mode.',
|
|
95
|
-
},
|
|
96
|
-
semantic: {
|
|
97
|
-
type: 'boolean',
|
|
98
|
-
description: 'Blend semantic vector similarity with TF-IDF (default: true). Falls back to pure TF-IDF if embeddings unavailable.',
|
|
99
|
-
},
|
|
100
|
-
category: {
|
|
101
|
-
type: 'string',
|
|
102
|
-
enum: [...CATEGORIES],
|
|
103
|
-
description: 'Knowledge category to focus on (optional). Combine with category_mode to control whether non-matching entries are dropped or just down-ranked.',
|
|
104
|
-
},
|
|
105
|
-
category_mode: {
|
|
106
|
-
type: 'string',
|
|
107
|
-
enum: ['filter', 'boost'],
|
|
108
|
-
description: 'How `category` is applied to knowledge results: "filter" (default) hides non-matching entries; "boost" keeps them but gives matching entries a 25% score boost. Use "boost" when you might be wrong about the category.',
|
|
109
|
-
},
|
|
110
|
-
},
|
|
111
|
-
required: ['query'],
|
|
112
|
-
},
|
|
31
|
+
token_budget: {
|
|
32
|
+
type: 'number',
|
|
33
|
+
description: '[wakeup] Max tokens to render (chars/4 estimate, default 800)',
|
|
113
34
|
},
|
|
114
|
-
{
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
type: 'object',
|
|
120
|
-
properties: {
|
|
121
|
-
action: {
|
|
122
|
-
type: 'string',
|
|
123
|
-
enum: ['list', 'get', 'summary'],
|
|
124
|
-
description: 'Action to perform',
|
|
125
|
-
},
|
|
126
|
-
session_id: {
|
|
127
|
-
type: 'string',
|
|
128
|
-
description: 'Session UUID (required for get, summary)',
|
|
129
|
-
},
|
|
130
|
-
project: {
|
|
131
|
-
type: 'string',
|
|
132
|
-
description: 'Filter by project name (substring match)',
|
|
133
|
-
},
|
|
134
|
-
include_tools: {
|
|
135
|
-
type: 'boolean',
|
|
136
|
-
description: 'Include tool_use and tool_result messages (action=get, default: false)',
|
|
137
|
-
},
|
|
138
|
-
tail: {
|
|
139
|
-
type: 'number',
|
|
140
|
-
description: 'Only return the last N messages (action=get)',
|
|
141
|
-
},
|
|
142
|
-
limit: {
|
|
143
|
-
type: 'number',
|
|
144
|
-
description: 'Max sessions to return (action=list, default: 20, max: 500)',
|
|
145
|
-
},
|
|
146
|
-
offset: {
|
|
147
|
-
type: 'number',
|
|
148
|
-
description: 'Skip first N sessions (action=list, default: 0)',
|
|
149
|
-
},
|
|
150
|
-
},
|
|
151
|
-
required: ['action'],
|
|
152
|
-
},
|
|
35
|
+
category: {
|
|
36
|
+
type: 'string',
|
|
37
|
+
enum: [...CATEGORIES],
|
|
38
|
+
description: 'Category (action=list: filter; action=write: target directory). ' +
|
|
39
|
+
'One of: projects, people, decisions, workflows, notes',
|
|
153
40
|
},
|
|
154
|
-
{
|
|
155
|
-
|
|
156
|
-
description: '
|
|
157
|
-
'prune orphan session embeddings, or VACUUM the database. ' +
|
|
158
|
-
'Use action "status" for index stats, "config" to view or update settings, ' +
|
|
159
|
-
'"rebuild_embeddings" to re-embed all knowledge entries (useful when switching providers), ' +
|
|
160
|
-
'"prune_orphans" to delete embeddings for sessions no longer present on disk, ' +
|
|
161
|
-
'"vacuum" to reclaim free pages.',
|
|
162
|
-
inputSchema: {
|
|
163
|
-
type: 'object',
|
|
164
|
-
properties: {
|
|
165
|
-
action: {
|
|
166
|
-
type: 'string',
|
|
167
|
-
enum: ['status', 'config', 'rebuild_embeddings', 'prune_orphans', 'vacuum'],
|
|
168
|
-
description: 'Action: status (vector store stats), config (view/update settings), rebuild_embeddings (re-embed all entries), prune_orphans (delete embeddings for missing sessions), vacuum (reclaim free pages)',
|
|
169
|
-
},
|
|
170
|
-
vacuum: {
|
|
171
|
-
type: 'boolean',
|
|
172
|
-
description: 'Run VACUUM after pruning (action=prune_orphans, default true)',
|
|
173
|
-
},
|
|
174
|
-
force_vacuum: {
|
|
175
|
-
type: 'boolean',
|
|
176
|
-
description: 'Run VACUUM even if no orphans were pruned (action=prune_orphans)',
|
|
177
|
-
},
|
|
178
|
-
git_url: {
|
|
179
|
-
type: 'string',
|
|
180
|
-
description: 'Git remote URL (action=config). Set to empty string to remove.',
|
|
181
|
-
},
|
|
182
|
-
memory_dir: {
|
|
183
|
-
type: 'string',
|
|
184
|
-
description: 'Local knowledge base directory (action=config). Empty to reset.',
|
|
185
|
-
},
|
|
186
|
-
auto_distill: {
|
|
187
|
-
type: 'boolean',
|
|
188
|
-
description: 'Enable/disable session distillation (action=config)',
|
|
189
|
-
},
|
|
190
|
-
},
|
|
191
|
-
required: ['action'],
|
|
192
|
-
},
|
|
41
|
+
tag: {
|
|
42
|
+
type: 'string',
|
|
43
|
+
description: 'Filter by tag (action=list)',
|
|
193
44
|
},
|
|
194
|
-
{
|
|
195
|
-
|
|
196
|
-
description:
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
required: ['source', 'target', 'rel_type'],
|
|
274
|
-
},
|
|
275
|
-
},
|
|
276
|
-
origin: {
|
|
277
|
-
type: 'string',
|
|
278
|
-
description: 'Edge origin to delete (action=unlink_by_origin). E.g. "tree-sitter" to clear code graph before re-ingest.',
|
|
279
|
-
},
|
|
280
|
-
},
|
|
281
|
-
required: ['action'],
|
|
282
|
-
},
|
|
45
|
+
path: {
|
|
46
|
+
type: 'string',
|
|
47
|
+
description: "Relative path to the entry, e.g. 'projects/my-project.md' (action=read, delete)",
|
|
48
|
+
},
|
|
49
|
+
filename: {
|
|
50
|
+
type: 'string',
|
|
51
|
+
description: "Filename with or without .md extension (action=write), e.g. 'my-project.md'",
|
|
52
|
+
},
|
|
53
|
+
content: {
|
|
54
|
+
type: 'string',
|
|
55
|
+
description: 'Full markdown content for the entry (action=write)',
|
|
56
|
+
},
|
|
57
|
+
},
|
|
58
|
+
required: ['action'],
|
|
59
|
+
},
|
|
60
|
+
};
|
|
61
|
+
const KNOWLEDGE_SEARCH_TOOL = {
|
|
62
|
+
name: 'knowledge_search',
|
|
63
|
+
description: 'Search across sessions AND knowledge entries. ' +
|
|
64
|
+
'Returns `{mode, sessions, knowledge}`. ' +
|
|
65
|
+
'General mode (no `scope`): hybrid TF-IDF + semantic over both sources, with optional MMR diversity and category boost. ' +
|
|
66
|
+
'Scoped mode (`scope` set): sessions-only filtered recall for a specific domain (errors, plans, configs, tools, files, decisions).',
|
|
67
|
+
inputSchema: {
|
|
68
|
+
type: 'object',
|
|
69
|
+
properties: {
|
|
70
|
+
query: {
|
|
71
|
+
type: 'string',
|
|
72
|
+
description: 'Search query -- supports keywords and phrases',
|
|
73
|
+
},
|
|
74
|
+
scope: {
|
|
75
|
+
type: 'string',
|
|
76
|
+
enum: [...SCOPES],
|
|
77
|
+
description: 'Search scope (optional): errors (stack traces), plans (architecture, TODOs), ' +
|
|
78
|
+
'configs (settings, env vars), tools (MCP tool calls), ' +
|
|
79
|
+
'files (file paths, code refs), decisions (trade-offs, choices), all (no filter). ' +
|
|
80
|
+
'When set, response mode switches to "scoped" and results are sessions-only.',
|
|
81
|
+
},
|
|
82
|
+
project: {
|
|
83
|
+
type: 'string',
|
|
84
|
+
description: 'Restrict search to sessions from this project',
|
|
85
|
+
},
|
|
86
|
+
role: {
|
|
87
|
+
type: 'string',
|
|
88
|
+
enum: ['user', 'assistant', 'all'],
|
|
89
|
+
description: 'Filter by message role (default: all, ignored when scope is set)',
|
|
90
|
+
},
|
|
91
|
+
max_results: {
|
|
92
|
+
type: 'number',
|
|
93
|
+
description: 'Maximum number of results to return (default: 20)',
|
|
94
|
+
},
|
|
95
|
+
ranked: {
|
|
96
|
+
type: 'boolean',
|
|
97
|
+
description: 'Use TF-IDF ranking (default: true, ignored when scope is set). Set false for regex mode.',
|
|
98
|
+
},
|
|
99
|
+
semantic: {
|
|
100
|
+
type: 'boolean',
|
|
101
|
+
description: 'Blend semantic vector similarity with TF-IDF (default: true). Falls back to pure TF-IDF if embeddings unavailable.',
|
|
102
|
+
},
|
|
103
|
+
category: {
|
|
104
|
+
type: 'string',
|
|
105
|
+
enum: [...CATEGORIES],
|
|
106
|
+
description: 'Knowledge category hint (optional). By default applied as a boost (non-matching kept, matching +25%). Pass category_mode="filter" for the legacy hard-filter behavior.',
|
|
107
|
+
},
|
|
108
|
+
category_mode: {
|
|
109
|
+
type: 'string',
|
|
110
|
+
enum: ['filter', 'boost'],
|
|
111
|
+
description: 'How `category` is applied to knowledge results (default: "boost"). "boost" keeps all entries but gives matching-category entries a 25% score boost; "filter" restricts to matching category only.',
|
|
112
|
+
},
|
|
113
|
+
mmr: {
|
|
114
|
+
type: 'boolean',
|
|
115
|
+
description: 'Apply Maximal Marginal Relevance re-ranking to knowledge results (default: false). Trades a small amount of top-1 relevance for diversity in the top-K.',
|
|
116
|
+
},
|
|
117
|
+
mmr_lambda: {
|
|
118
|
+
type: 'number',
|
|
119
|
+
description: 'MMR tradeoff 0-1 (default: 0.7). 1.0 = pure relevance; 0.0 = pure diversity.',
|
|
120
|
+
},
|
|
121
|
+
explain: {
|
|
122
|
+
type: 'boolean',
|
|
123
|
+
description: 'When true, each knowledge hit carries `score_components` (bm25, decay, maturity, confidence, category_boost, mmr_penalty).',
|
|
283
124
|
},
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
125
|
+
},
|
|
126
|
+
required: ['query'],
|
|
127
|
+
},
|
|
128
|
+
};
|
|
129
|
+
const KNOWLEDGE_SESSION_TOOL = {
|
|
130
|
+
name: 'knowledge_session',
|
|
131
|
+
description: 'Session operations: list sessions, get a full conversation, or get a summary. ' +
|
|
132
|
+
'Use action "list" to browse sessions, "get" to retrieve messages, "summary" for a quick overview.',
|
|
133
|
+
inputSchema: {
|
|
134
|
+
type: 'object',
|
|
135
|
+
properties: {
|
|
136
|
+
action: {
|
|
137
|
+
type: 'string',
|
|
138
|
+
enum: ['list', 'get', 'summary'],
|
|
139
|
+
description: 'Action to perform',
|
|
140
|
+
},
|
|
141
|
+
session_id: {
|
|
142
|
+
type: 'string',
|
|
143
|
+
description: 'Session UUID (required for get, summary)',
|
|
144
|
+
},
|
|
145
|
+
project: {
|
|
146
|
+
type: 'string',
|
|
147
|
+
description: 'Filter by project name (substring match)',
|
|
148
|
+
},
|
|
149
|
+
include_tools: {
|
|
150
|
+
type: 'boolean',
|
|
151
|
+
description: 'Include tool_use and tool_result messages (action=get, default: false)',
|
|
152
|
+
},
|
|
153
|
+
tail: {
|
|
154
|
+
type: 'number',
|
|
155
|
+
description: 'Only return the last N messages (action=get)',
|
|
156
|
+
},
|
|
157
|
+
limit: {
|
|
158
|
+
type: 'number',
|
|
159
|
+
description: 'Max sessions to return (action=list, default: 20, max: 500)',
|
|
160
|
+
},
|
|
161
|
+
offset: {
|
|
162
|
+
type: 'number',
|
|
163
|
+
description: 'Skip first N sessions (action=list, default: 0)',
|
|
164
|
+
},
|
|
165
|
+
},
|
|
166
|
+
required: ['action'],
|
|
167
|
+
},
|
|
168
|
+
};
|
|
169
|
+
const KNOWLEDGE_ADMIN_TOOL = {
|
|
170
|
+
name: 'knowledge_admin',
|
|
171
|
+
description: 'Admin operations: view vector store stats, view/update configuration, rebuild embeddings, ' +
|
|
172
|
+
'prune orphan session embeddings, or VACUUM the database. ' +
|
|
173
|
+
'Use action "status" for index stats, "config" to view or update settings, ' +
|
|
174
|
+
'"rebuild_embeddings" to re-embed all knowledge entries (useful when switching providers), ' +
|
|
175
|
+
'"prune_orphans" to delete embeddings for sessions no longer present on disk, ' +
|
|
176
|
+
'"vacuum" to reclaim free pages.',
|
|
177
|
+
inputSchema: {
|
|
178
|
+
type: 'object',
|
|
179
|
+
properties: {
|
|
180
|
+
action: {
|
|
181
|
+
type: 'string',
|
|
182
|
+
enum: ['status', 'config', 'rebuild_embeddings', 'prune_orphans', 'vacuum', 'promote'],
|
|
183
|
+
description: 'Action: status (vector store stats), config (view/update settings), rebuild_embeddings (re-embed all entries), prune_orphans (delete embeddings for missing sessions), vacuum (reclaim free pages), promote (run the scored promoter — see promote_mode)',
|
|
184
|
+
},
|
|
185
|
+
vacuum: {
|
|
186
|
+
type: 'boolean',
|
|
187
|
+
description: 'Run VACUUM after pruning (action=prune_orphans, default true)',
|
|
188
|
+
},
|
|
189
|
+
force_vacuum: {
|
|
190
|
+
type: 'boolean',
|
|
191
|
+
description: 'Run VACUUM even if no orphans were pruned (action=prune_orphans)',
|
|
192
|
+
},
|
|
193
|
+
git_url: {
|
|
194
|
+
type: 'string',
|
|
195
|
+
description: 'Git remote URL (action=config). Set to empty string to remove.',
|
|
196
|
+
},
|
|
197
|
+
memory_dir: {
|
|
198
|
+
type: 'string',
|
|
199
|
+
description: 'Local knowledge base directory (action=config). Empty to reset.',
|
|
200
|
+
},
|
|
201
|
+
auto_distill: {
|
|
202
|
+
type: 'boolean',
|
|
203
|
+
description: 'Enable/disable scheduled promotion (action=config)',
|
|
204
|
+
},
|
|
205
|
+
promote_mode: {
|
|
206
|
+
type: 'string',
|
|
207
|
+
enum: ['apply', 'explain'],
|
|
208
|
+
description: 'action=promote mode (default: explain). "explain" returns score breakdowns without writing; "apply" promotes candidates that pass all gates.',
|
|
209
|
+
},
|
|
210
|
+
min_score: {
|
|
211
|
+
type: 'number',
|
|
212
|
+
description: '[promote] Minimum composite score to promote (default: 0.5).',
|
|
213
|
+
},
|
|
214
|
+
min_recall_count: {
|
|
215
|
+
type: 'number',
|
|
216
|
+
description: '[promote] Minimum recall count gate (default: 2).',
|
|
217
|
+
},
|
|
218
|
+
min_unique_queries: {
|
|
219
|
+
type: 'number',
|
|
220
|
+
description: '[promote] Minimum unique-query gate (default: 2).',
|
|
221
|
+
},
|
|
222
|
+
},
|
|
223
|
+
required: ['action'],
|
|
224
|
+
},
|
|
225
|
+
};
|
|
226
|
+
const KNOWLEDGE_GRAPH_TOOL = {
|
|
227
|
+
name: 'knowledge_graph',
|
|
228
|
+
description: 'Knowledge graph operations with temporal validity and code structure support. ' +
|
|
229
|
+
'Create/remove edges, traverse via directed BFS, bulk-import code graph edges. ' +
|
|
230
|
+
'Relationship types: related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on, calls, imports, inherits. ' +
|
|
231
|
+
'Code structure types (calls/imports/inherits) are created by knowledge-ingest and use "code:" prefixed node IDs.',
|
|
232
|
+
inputSchema: {
|
|
233
|
+
type: 'object',
|
|
234
|
+
properties: {
|
|
235
|
+
action: {
|
|
236
|
+
type: 'string',
|
|
237
|
+
enum: ['link', 'unlink', 'invalidate', 'list', 'traverse', 'bulk_link', 'unlink_by_origin'],
|
|
238
|
+
description: 'Action: link (create edge), unlink (remove edge), invalidate (set valid_to), list (list edges), traverse (directed BFS), bulk_link (batch-create edges), unlink_by_origin (delete all edges from a specific origin)',
|
|
239
|
+
},
|
|
240
|
+
source: {
|
|
241
|
+
type: 'string',
|
|
242
|
+
description: "Source entry path (action=link/unlink/invalidate), e.g. 'projects/my-project.md'",
|
|
243
|
+
},
|
|
244
|
+
target: {
|
|
245
|
+
type: 'string',
|
|
246
|
+
description: "Target entry path (action=link/unlink/invalidate), e.g. 'decisions/architecture.md'",
|
|
247
|
+
},
|
|
248
|
+
entry: {
|
|
249
|
+
type: 'string',
|
|
250
|
+
description: 'Entry path for filtering (action=list) or BFS start (action=traverse)',
|
|
251
|
+
},
|
|
252
|
+
rel_type: {
|
|
253
|
+
type: 'string',
|
|
254
|
+
enum: [...RELATIONSHIP_TYPES],
|
|
255
|
+
description: 'Relationship type (required for link, optional filter for unlink/invalidate/list)',
|
|
256
|
+
},
|
|
257
|
+
strength: {
|
|
258
|
+
type: 'number',
|
|
259
|
+
description: 'Edge strength 0-1 (action=link, default: 0.5)',
|
|
260
|
+
},
|
|
261
|
+
depth: {
|
|
262
|
+
type: 'number',
|
|
263
|
+
description: 'Max traversal depth in hops (action=traverse, default: 2)',
|
|
264
|
+
},
|
|
265
|
+
valid_from: {
|
|
266
|
+
type: 'string',
|
|
267
|
+
description: 'ISO date the fact became true (action=link, optional). Null/omitted = unbounded.',
|
|
268
|
+
},
|
|
269
|
+
valid_to: {
|
|
270
|
+
type: 'string',
|
|
271
|
+
description: 'ISO date the fact stopped being true (action=link/invalidate). For invalidate, defaults to today.',
|
|
272
|
+
},
|
|
273
|
+
as_of: {
|
|
274
|
+
type: 'string',
|
|
275
|
+
description: 'ISO date — only return edges valid at this date (action=list/traverse, optional)',
|
|
276
|
+
},
|
|
277
|
+
direction: {
|
|
278
|
+
type: 'string',
|
|
279
|
+
enum: ['outbound', 'inbound', 'both'],
|
|
280
|
+
description: 'Traversal direction (action=traverse, default: both). ' +
|
|
281
|
+
'outbound: follow source→target (what does X call?). ' +
|
|
282
|
+
'inbound: follow target→source (who calls X?). ' +
|
|
283
|
+
'both: undirected (default, preserves legacy behavior).',
|
|
284
|
+
},
|
|
285
|
+
edges: {
|
|
286
|
+
type: 'array',
|
|
287
|
+
description: 'Array of edges to create (action=bulk_link). Each: { source, target, rel_type, strength?, origin? }',
|
|
288
|
+
items: {
|
|
290
289
|
type: 'object',
|
|
291
290
|
properties: {
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
'gaps (entries with 0-1 edges), brief (compact knowledge base summary)',
|
|
298
|
-
},
|
|
299
|
-
category: {
|
|
300
|
-
type: 'string',
|
|
301
|
-
enum: [...CATEGORIES],
|
|
302
|
-
description: 'Scan only this category (omit for all)',
|
|
303
|
-
},
|
|
304
|
-
threshold: {
|
|
305
|
-
type: 'number',
|
|
306
|
-
description: 'Similarity threshold 0-1 (action=consolidate, default: 0.5)',
|
|
307
|
-
},
|
|
308
|
-
max_entries: {
|
|
309
|
-
type: 'number',
|
|
310
|
-
description: 'Max unconnected entries to include (action=reflect, default: 20)',
|
|
311
|
-
},
|
|
312
|
-
top_n: {
|
|
313
|
-
type: 'number',
|
|
314
|
-
description: 'Number of results (action=god_nodes default: 10, action=bridges default: 5)',
|
|
315
|
-
},
|
|
291
|
+
source: { type: 'string' },
|
|
292
|
+
target: { type: 'string' },
|
|
293
|
+
rel_type: { type: 'string', enum: [...RELATIONSHIP_TYPES] },
|
|
294
|
+
strength: { type: 'number' },
|
|
295
|
+
origin: { type: 'string' },
|
|
316
296
|
},
|
|
317
|
-
required: ['
|
|
297
|
+
required: ['source', 'target', 'rel_type'],
|
|
318
298
|
},
|
|
319
299
|
},
|
|
320
|
-
|
|
300
|
+
origin: {
|
|
301
|
+
type: 'string',
|
|
302
|
+
description: 'Edge origin to delete (action=unlink_by_origin). E.g. "tree-sitter" to clear code graph before re-ingest.',
|
|
303
|
+
},
|
|
304
|
+
},
|
|
305
|
+
required: ['action'],
|
|
306
|
+
},
|
|
307
|
+
};
|
|
308
|
+
const KNOWLEDGE_ANALYZE_TOOL = {
|
|
309
|
+
name: 'knowledge_analyze',
|
|
310
|
+
description: 'Analysis tools: find duplicates, unconnected entries, most-connected concepts (god nodes), ' +
|
|
311
|
+
'bridge entries, knowledge gaps, or generate a compact knowledge brief. ' +
|
|
312
|
+
'Actions: consolidate, reflect, god_nodes, bridges, gaps, brief.',
|
|
313
|
+
inputSchema: {
|
|
314
|
+
type: 'object',
|
|
315
|
+
properties: {
|
|
316
|
+
action: {
|
|
317
|
+
type: 'string',
|
|
318
|
+
enum: ['consolidate', 'reflect', 'god_nodes', 'bridges', 'gaps', 'brief'],
|
|
319
|
+
description: 'Action: consolidate (find duplicates), reflect (find unconnected entries), ' +
|
|
320
|
+
'god_nodes (most-connected entries), bridges (cross-cluster connectors), ' +
|
|
321
|
+
'gaps (entries with 0-1 edges), brief (compact knowledge base summary)',
|
|
322
|
+
},
|
|
323
|
+
category: {
|
|
324
|
+
type: 'string',
|
|
325
|
+
enum: [...CATEGORIES],
|
|
326
|
+
description: 'Scan only this category (omit for all)',
|
|
327
|
+
},
|
|
328
|
+
threshold: {
|
|
329
|
+
type: 'number',
|
|
330
|
+
description: 'Similarity threshold 0-1 (action=consolidate, default: 0.5)',
|
|
331
|
+
},
|
|
332
|
+
max_entries: {
|
|
333
|
+
type: 'number',
|
|
334
|
+
description: 'Max unconnected entries to include (action=reflect, default: 20)',
|
|
335
|
+
},
|
|
336
|
+
top_n: {
|
|
337
|
+
type: 'number',
|
|
338
|
+
description: 'Number of results (action=god_nodes default: 10, action=bridges default: 5)',
|
|
339
|
+
},
|
|
340
|
+
},
|
|
341
|
+
required: ['action'],
|
|
342
|
+
},
|
|
343
|
+
};
|
|
344
|
+
export const TOOLS = [
|
|
345
|
+
KNOWLEDGE_TOOL,
|
|
346
|
+
KNOWLEDGE_SEARCH_TOOL,
|
|
347
|
+
KNOWLEDGE_SESSION_TOOL,
|
|
348
|
+
KNOWLEDGE_ADMIN_TOOL,
|
|
349
|
+
KNOWLEDGE_GRAPH_TOOL,
|
|
350
|
+
KNOWLEDGE_ANALYZE_TOOL,
|
|
351
|
+
];
|
|
352
|
+
export function createServer(options) {
|
|
353
|
+
const server = new Server({ name: 'agent-knowledge', version: getVersion() }, { capabilities: { tools: {} } });
|
|
354
|
+
server.setRequestHandler(ListToolsRequestSchema, async () => ({
|
|
355
|
+
tools: [...TOOLS],
|
|
321
356
|
}));
|
|
322
357
|
server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
|
323
358
|
const { name, arguments: args = {} } = request.params;
|