agent-knowledge 1.7.3 → 1.8.1
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 +101 -0
- package/README.md +43 -18
- package/agent-desk-plugin.json +1 -1
- package/dist/dashboard.d.ts.map +1 -1
- package/dist/dashboard.js +28 -1
- package/dist/dashboard.js.map +1 -1
- package/dist/knowledge/analyze.d.ts +18 -0
- package/dist/knowledge/analyze.d.ts.map +1 -1
- package/dist/knowledge/analyze.js +22 -0
- package/dist/knowledge/analyze.js.map +1 -1
- package/dist/knowledge/freshness.d.ts +99 -0
- package/dist/knowledge/freshness.d.ts.map +1 -0
- package/dist/knowledge/freshness.js +303 -0
- package/dist/knowledge/freshness.js.map +1 -0
- package/dist/knowledge/promote.d.ts +145 -0
- package/dist/knowledge/promote.d.ts.map +1 -0
- package/dist/knowledge/promote.js +532 -0
- package/dist/knowledge/promote.js.map +1 -0
- package/dist/knowledge/query-log.d.ts +88 -0
- package/dist/knowledge/query-log.d.ts.map +1 -0
- package/dist/knowledge/query-log.js +207 -0
- package/dist/knowledge/query-log.js.map +1 -0
- package/dist/knowledge/scoring.d.ts +22 -2
- package/dist/knowledge/scoring.d.ts.map +1 -1
- package/dist/knowledge/scoring.js +51 -3
- package/dist/knowledge/scoring.js.map +1 -1
- package/dist/knowledge/search.d.ts +56 -5
- package/dist/knowledge/search.d.ts.map +1 -1
- package/dist/knowledge/search.js +88 -10
- package/dist/knowledge/search.js.map +1 -1
- package/dist/knowledge/store.d.ts +12 -0
- package/dist/knowledge/store.d.ts.map +1 -1
- package/dist/knowledge/store.js +18 -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 +334 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +378 -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 +150 -21
- package/dist/tool-handlers.js.map +1 -1
- package/dist/ui/app.js +271 -1
- package/dist/ui/render-knowledge.js +3 -3
- package/dist/ui/styles.css +209 -0
- package/dist/wakeup.d.ts +59 -14
- package/dist/wakeup.d.ts.map +1 -1
- package/dist/wakeup.js +406 -43
- package/dist/wakeup.js.map +1 -1
- package/docs/ARCHITECTURE.md +31 -6
- package/docs/SETUP.md +20 -8
- package/docs/USER-MANUAL.md +205 -59
- 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/docs/SETUP.md
CHANGED
|
@@ -69,7 +69,7 @@ From the agent-knowledge clone:
|
|
|
69
69
|
node scripts/setup.js
|
|
70
70
|
```
|
|
71
71
|
|
|
72
|
-
This detects Claude Code, registers the MCP server in `~/.claude.json`, wires all
|
|
72
|
+
This detects Claude Code, registers the MCP server in `~/.claude.json`, wires all 5 hooks into `~/.claude/settings.json`, and grants `mcp__agent-knowledge__*` permission in one shot. Restart Claude Code afterwards to pick up the new config.
|
|
73
73
|
|
|
74
74
|
#### Register the MCP server (manual)
|
|
75
75
|
|
|
@@ -180,14 +180,15 @@ curl -X PUT http://localhost:3423/api/knowledge/notes/my-note \
|
|
|
180
180
|
|
|
181
181
|
## Hooks
|
|
182
182
|
|
|
183
|
-
agent-knowledge ships **
|
|
183
|
+
agent-knowledge ships **5 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.
|
|
184
184
|
|
|
185
|
-
| Hook
|
|
186
|
-
|
|
|
187
|
-
| `session-start.js`
|
|
188
|
-
| `
|
|
189
|
-
| `precompact-
|
|
190
|
-
| `
|
|
185
|
+
| Hook | Event | Purpose |
|
|
186
|
+
| ------------------------- | ---------------- | -------------------------------------------------------------------------------- |
|
|
187
|
+
| `session-start.js` | SessionStart | Dashboard URL + auto-loads token-budgeted wakeup payload into context |
|
|
188
|
+
| `first-prompt-inject.mjs` | UserPromptSubmit | v1.8 — query-targeted knowledge hits injected on the session's first real prompt |
|
|
189
|
+
| `precompact-flush.mjs` | PreCompact | Rich session summary on disk + save-unsaved-context nudge into context |
|
|
190
|
+
| `precompact-distill.mjs` | PreCompact | Lightweight text snapshot of recent user prompts |
|
|
191
|
+
| `sessionend-distill.mjs` | SessionEnd | Final summary (turn counts, tool uses, first 20 prompts) |
|
|
191
192
|
|
|
192
193
|
See [`docs/hooks.md`](hooks.md) for the full hook reference including environment variables and test coverage.
|
|
193
194
|
|
|
@@ -207,6 +208,17 @@ See [`docs/hooks.md`](hooks.md) for the full hook reference including environmen
|
|
|
207
208
|
]
|
|
208
209
|
}
|
|
209
210
|
],
|
|
211
|
+
"UserPromptSubmit": [
|
|
212
|
+
{
|
|
213
|
+
"hooks": [
|
|
214
|
+
{
|
|
215
|
+
"type": "command",
|
|
216
|
+
"command": "node \"/path/to/agent-knowledge/scripts/hooks/first-prompt-inject.mjs\"",
|
|
217
|
+
"timeout": 10
|
|
218
|
+
}
|
|
219
|
+
]
|
|
220
|
+
}
|
|
221
|
+
],
|
|
210
222
|
"PreCompact": [
|
|
211
223
|
{
|
|
212
224
|
"hooks": [
|
package/docs/USER-MANUAL.md
CHANGED
|
@@ -212,15 +212,17 @@ Knowledge base CRUD, git sync, and session-start hydration.
|
|
|
212
212
|
|
|
213
213
|
**Parameters:**
|
|
214
214
|
|
|
215
|
-
| Name
|
|
216
|
-
|
|
|
217
|
-
| `action`
|
|
218
|
-
| `category`
|
|
219
|
-
| `tag`
|
|
220
|
-
| `path`
|
|
221
|
-
| `filename`
|
|
222
|
-
| `content`
|
|
223
|
-
| `token_budget`
|
|
215
|
+
| Name | Type | Required | Description |
|
|
216
|
+
| ----------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
|
217
|
+
| `action` | string | Yes | One of: `list`, `read`, `write`, `delete`, `sync`, `wakeup` |
|
|
218
|
+
| `category` | string | No | [list/wakeup] Filter by category; [write] Target directory. One of: `projects`, `people`, `decisions`, `workflows`, `notes` |
|
|
219
|
+
| `tag` | string | No | [list] Filter by tag |
|
|
220
|
+
| `path` | string | No | [read/delete] Relative path, e.g. `projects/my-project.md` |
|
|
221
|
+
| `filename` | string | No | [write] Filename with or without .md extension |
|
|
222
|
+
| `content` | string | No | [write] Full Markdown content (max 1MB) |
|
|
223
|
+
| `token_budget` | number | No | [wakeup] Max tokens for the rendered blob (chars/4 estimate, default 800, range 50–8000) |
|
|
224
|
+
| `sections` | string | No | [wakeup, v1.8.1] Comma-separated section list in priority order. See below for valid names. |
|
|
225
|
+
| `section_budgets` | object | No | [wakeup, v1.8.1] Per-section token budgets, e.g. `{"identity": 200, "top_weighted": 400}`. Unspecified sections share evenly. |
|
|
224
226
|
|
|
225
227
|
**Action: list**
|
|
226
228
|
|
|
@@ -273,23 +275,40 @@ knowledge with action "sync"
|
|
|
273
275
|
|
|
274
276
|
**Action: wakeup**
|
|
275
277
|
|
|
276
|
-
Return a
|
|
278
|
+
Return a token-budgeted, section-priority context bundle. Call once at session start so the agent has its world loaded before issuing any real search.
|
|
277
279
|
|
|
278
|
-
|
|
280
|
+
**Section-priority packing (v1.8.1):** the bundle is assembled from an ordered list of sections. Each section gets a per-section token budget; the packer fills them top-to-bottom, redistributes any unused budget to later sections, and stops once the global `token_budget` is hit.
|
|
281
|
+
|
|
282
|
+
Default section order (drag-to-reorder in a later UI pass):
|
|
283
|
+
|
|
284
|
+
1. `identity` — L0 identity from `~/agent-knowledge/identity.md` (always first).
|
|
285
|
+
2. `active_tasks` — placeholder pointing at agent-tasks (no in-repo task data today).
|
|
286
|
+
3. `recent_decisions` — newest entries in `decisions/`, up to K.
|
|
287
|
+
4. `known_gotchas` — entries tagged `gotcha` across any category.
|
|
288
|
+
5. `last_session_summary` — condensed meta of the most recent indexed session.
|
|
289
|
+
6. `top_weighted` — the legacy L1 logic: `recency × log(size+1)`.
|
|
290
|
+
7. `semantic_fallback` — pure top-weighted catch-all if earlier sections under-filled the budget.
|
|
291
|
+
|
|
292
|
+
Empty sections emit a short placeholder rather than disappearing silently, so downstream UIs keep a stable shape.
|
|
279
293
|
|
|
280
294
|
```
|
|
281
295
|
knowledge with action "wakeup"
|
|
282
296
|
knowledge with action "wakeup", token_budget 1200
|
|
283
297
|
knowledge with action "wakeup", category "projects"
|
|
298
|
+
knowledge with action "wakeup", sections "identity,recent_decisions,top_weighted"
|
|
299
|
+
knowledge with action "wakeup", token_budget 2000, section_budgets { "identity": 200, "recent_decisions": 400, "top_weighted": 800 }
|
|
284
300
|
```
|
|
285
301
|
|
|
302
|
+
**Backwards compat:** calling with only `token_budget` (+ optional `category`) and no `sections` / `section_budgets` routes to the v1.8.0 `identity + top_weighted` behaviour — the `rendered` output stays shape-compatible for existing callers.
|
|
303
|
+
|
|
286
304
|
**Response:**
|
|
287
305
|
|
|
288
306
|
- `identity` — text from `identity.md`, or a default placeholder.
|
|
289
|
-
- `entries` — array of `{ path, title, weight, excerpt }
|
|
307
|
+
- `entries` — array of `{ path, title, weight, excerpt }` from the `top_weighted` section (back-compat field).
|
|
308
|
+
- `sections` — array of `{ name, content, budget, used, truncated, empty }`, one per emitted section.
|
|
290
309
|
- `rendered` — the assembled Markdown blob ready to paste into a system prompt.
|
|
291
310
|
- `token_estimate` — `chars / 4`.
|
|
292
|
-
- `truncated` — `true`
|
|
311
|
+
- `truncated` — `true` if any section was cut to fit the budget.
|
|
293
312
|
|
|
294
313
|
---
|
|
295
314
|
|
|
@@ -297,26 +316,37 @@ knowledge with action "wakeup", category "projects"
|
|
|
297
316
|
|
|
298
317
|
Search across sessions and knowledge entries. Supports general search and scoped recall.
|
|
299
318
|
|
|
319
|
+
**Response shape** (v1.8): `{ mode, sessions, knowledge }`.
|
|
320
|
+
|
|
321
|
+
- `mode: "general"` — hybrid TF-IDF + semantic across both sources.
|
|
322
|
+
- `mode: "scoped"` — sessions-only filtered recall. `knowledge` is always `[]` in this mode (scoped search is session-only by design — the response now says so instead of the v1.7 silent polymorphism).
|
|
323
|
+
|
|
300
324
|
**Parameters:**
|
|
301
325
|
|
|
302
|
-
| Name
|
|
303
|
-
|
|
|
304
|
-
| `query`
|
|
305
|
-
| `scope`
|
|
306
|
-
| `project`
|
|
307
|
-
| `role`
|
|
308
|
-
| `max_results`
|
|
309
|
-
| `ranked`
|
|
310
|
-
| `semantic`
|
|
326
|
+
| Name | Type | Required | Description |
|
|
327
|
+
| --------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
328
|
+
| `query` | string | Yes | Search query -- supports keywords and phrases |
|
|
329
|
+
| `scope` | string | No | Search scope: `errors`, `plans`, `configs`, `tools`, `files`, `decisions`, `all`. When provided, performs scoped recall in sessions only. |
|
|
330
|
+
| `project` | string | No | Restrict to sessions from this project |
|
|
331
|
+
| `role` | string | No | Filter by message role: `user`, `assistant`, `all` (default: all, ignored when scope is set) |
|
|
332
|
+
| `max_results` | number | No | Maximum results (default: 20) |
|
|
333
|
+
| `ranked` | boolean | No | Use TF-IDF ranking (default: true, ignored when scope is set) |
|
|
334
|
+
| `semantic` | boolean | No | Blend semantic similarity with TF-IDF (default: true) |
|
|
335
|
+
| `category` | string | No | Category hint for the knowledge leg: `projects`, `people`, `decisions`, `workflows`, `notes` |
|
|
336
|
+
| `category_mode` | string | No | How `category` is applied: `boost` (v1.8 default, non-matches kept but matching entries get a 1.25× boost) or `filter` (legacy hard-filter) |
|
|
337
|
+
| `mmr` | boolean | No | Apply Maximal Marginal Relevance re-ranking to knowledge hits. Default `false`. Kills near-duplicate clusters in the top-K. |
|
|
338
|
+
| `mmr_lambda` | number | No | MMR tradeoff, `0`–`1` (default `0.7`). `1.0` = pure relevance; `0.0` = pure diversity. |
|
|
339
|
+
| `explain` | boolean | No | When `true`, each knowledge hit carries a `score_components` breakdown: `{bm25, decay, maturity, confidence, category_boost, mmr_penalty}`. |
|
|
311
340
|
|
|
312
341
|
**General search** (no scope):
|
|
313
342
|
|
|
314
343
|
```
|
|
315
344
|
knowledge_search with query "authentication error handling"
|
|
316
345
|
knowledge_search with query "database migration", project "backend"
|
|
346
|
+
knowledge_search with query "why postgres", category "decisions", mmr true, explain true
|
|
317
347
|
```
|
|
318
348
|
|
|
319
|
-
Returns both session matches and knowledge base matches.
|
|
349
|
+
Returns `{ mode: "general", sessions, knowledge }` — both session matches and knowledge base matches.
|
|
320
350
|
|
|
321
351
|
**Scoped recall** (with scope):
|
|
322
352
|
|
|
@@ -389,16 +419,22 @@ knowledge_session with action "summary", session_id "abc-123-def"
|
|
|
389
419
|
|
|
390
420
|
### knowledge_admin
|
|
391
421
|
|
|
392
|
-
Admin operations for configuration, index stats, and
|
|
422
|
+
Admin operations for configuration, index stats, embedding management, and the v1.8 scored promoter.
|
|
393
423
|
|
|
394
424
|
**Parameters:**
|
|
395
425
|
|
|
396
|
-
| Name
|
|
397
|
-
|
|
|
398
|
-
| `action`
|
|
399
|
-
| `git_url`
|
|
400
|
-
| `memory_dir`
|
|
401
|
-
| `auto_distill`
|
|
426
|
+
| Name | Type | Required | Description |
|
|
427
|
+
| -------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------- |
|
|
428
|
+
| `action` | string | Yes | One of: `status`, `config`, `rebuild_embeddings`, `prune_orphans`, `vacuum`, `promote` |
|
|
429
|
+
| `git_url` | string | No | [config] Git remote URL (empty string to remove) |
|
|
430
|
+
| `memory_dir` | string | No | [config] Local knowledge base directory (empty to reset) |
|
|
431
|
+
| `auto_distill` | boolean | No | [config] Enable/disable scheduled promotion (governs the promoter, not the legacy regex distiller) |
|
|
432
|
+
| `vacuum` | boolean | No | [prune_orphans] Run VACUUM after pruning (default `true`) |
|
|
433
|
+
| `force_vacuum` | boolean | No | [prune_orphans] Run VACUUM even when no orphans were pruned |
|
|
434
|
+
| `promote_mode` | string | No | [promote] `explain` (default — read-only, returns score breakdowns) or `apply` (write + git-commit) |
|
|
435
|
+
| `min_score` | number | No | [promote] Override minScore gate (default `0.5`) |
|
|
436
|
+
| `min_recall_count` | number | No | [promote] Override minRecallCount gate (default `2`) |
|
|
437
|
+
| `min_unique_queries` | number | No | [promote] Override minUniqueQueries gate (default `2`) |
|
|
402
438
|
|
|
403
439
|
**Action: status**
|
|
404
440
|
|
|
@@ -421,7 +457,7 @@ knowledge_admin with action "config"
|
|
|
421
457
|
# Update git URL
|
|
422
458
|
knowledge_admin with action "config", git_url "https://github.com/user/memory.git"
|
|
423
459
|
|
|
424
|
-
# Disable auto-
|
|
460
|
+
# Disable auto-promotion (the v1.8 scored promoter runs on backgroundIndex)
|
|
425
461
|
knowledge_admin with action "config", auto_distill false
|
|
426
462
|
```
|
|
427
463
|
|
|
@@ -435,36 +471,81 @@ knowledge_admin with action "rebuild_embeddings"
|
|
|
435
471
|
|
|
436
472
|
Wipes existing vectors, re-creates the store with the current provider's dimensions, and re-embeds all entries. Returns processed/failed counts.
|
|
437
473
|
|
|
474
|
+
**Action: prune_orphans**
|
|
475
|
+
|
|
476
|
+
Delete vector embeddings for sessions no longer present on disk. Optionally follows with VACUUM to reclaim pages.
|
|
477
|
+
|
|
478
|
+
```
|
|
479
|
+
knowledge_admin with action "prune_orphans"
|
|
480
|
+
knowledge_admin with action "prune_orphans", force_vacuum true
|
|
481
|
+
```
|
|
482
|
+
|
|
483
|
+
**Action: vacuum**
|
|
484
|
+
|
|
485
|
+
Reclaim free SQLite pages in the vector store.
|
|
486
|
+
|
|
487
|
+
```
|
|
488
|
+
knowledge_admin with action "vacuum"
|
|
489
|
+
```
|
|
490
|
+
|
|
491
|
+
**Action: promote** (v1.8)
|
|
492
|
+
|
|
493
|
+
Run the scored + gated promoter. Every project-level candidate is scored on six weighted signals (`relevance 0.30, frequency 0.24, queryDiversity 0.15, recency 0.15, consolidation 0.10, conceptualRichness 0.06`) and tested against three independent gates (`minScore`, `minRecallCount`, `minUniqueQueries` — all must pass). Candidates that pass are promoted to `projects/<id>.md`; every run drops an audit trail in `~/agent-knowledge/.dreams/YYYY-MM-DD.md`.
|
|
494
|
+
|
|
495
|
+
**Grounded rehydration**: if a candidate's source session file is no longer on disk, the promoter skips it. Prevents writing content the user has deleted.
|
|
496
|
+
|
|
497
|
+
```
|
|
498
|
+
# Score candidates + write the diary, DO NOT touch the KB
|
|
499
|
+
knowledge_admin with action "promote"
|
|
500
|
+
|
|
501
|
+
# Actually promote + git-commit
|
|
502
|
+
knowledge_admin with action "promote", promote_mode "apply"
|
|
503
|
+
|
|
504
|
+
# Tighten gates for a conservative run
|
|
505
|
+
knowledge_admin with action "promote", promote_mode "apply", min_score 0.7, min_recall_count 3
|
|
506
|
+
```
|
|
507
|
+
|
|
508
|
+
Returns `{ runStartedAt, runFinishedAt, mode, candidates[], promotedPaths[], skippedIds[], diaryPath, totals }`.
|
|
509
|
+
|
|
438
510
|
---
|
|
439
511
|
|
|
440
512
|
### knowledge_graph
|
|
441
513
|
|
|
442
|
-
Knowledge graph operations
|
|
514
|
+
Knowledge graph operations with temporal validity and code-structure support. Seven actions cover creation, removal, time-scoped invalidation, directed BFS traversal, and bulk ingestion for code graphs.
|
|
443
515
|
|
|
444
516
|
**Parameters:**
|
|
445
517
|
|
|
446
|
-
| Name
|
|
447
|
-
|
|
|
448
|
-
| `action`
|
|
449
|
-
| `source`
|
|
450
|
-
| `target`
|
|
451
|
-
| `entry`
|
|
452
|
-
| `rel_type`
|
|
453
|
-
| `strength`
|
|
454
|
-
| `depth`
|
|
518
|
+
| Name | Type | Required | Description |
|
|
519
|
+
| ------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
|
520
|
+
| `action` | string | Yes | One of: `link`, `unlink`, `invalidate`, `list`, `traverse`, `bulk_link`, `unlink_by_origin` |
|
|
521
|
+
| `source` | string | Varies | [link/unlink/invalidate] Source entry path |
|
|
522
|
+
| `target` | string | Varies | [link/unlink/invalidate] Target entry path |
|
|
523
|
+
| `entry` | string | No | [list] Filter by entry path; [traverse] BFS start node |
|
|
524
|
+
| `rel_type` | string | Varies | Relationship type (required for link, optional filter for unlink/invalidate/list/traverse) |
|
|
525
|
+
| `strength` | number | No | [link] Edge strength 0-1 (default: 0.5) |
|
|
526
|
+
| `depth` | number | No | [traverse] Max traversal depth in hops (default: 2) |
|
|
527
|
+
| `valid_from` | string | No | [link] ISO date the fact became true. Null/omitted = unbounded. |
|
|
528
|
+
| `valid_to` | string | No | [link/invalidate] ISO date the fact stopped being true. For `invalidate`, defaults to today. |
|
|
529
|
+
| `as_of` | string | No | [list/traverse] Only return edges valid at this ISO date. |
|
|
530
|
+
| `direction` | string | No | [traverse] `outbound` (source→target), `inbound` (target→source), or `both` (default — undirected). |
|
|
531
|
+
| `edges` | array | No | [bulk_link] Batch of `{source, target, rel_type, strength?, origin?}` edges. Used by knowledge-ingest for code graphs. |
|
|
532
|
+
| `origin` | string | No | [unlink_by_origin] Origin tag to delete by (e.g. `tree-sitter` to clear the code graph before re-ingest). Also accepted on `link`. |
|
|
455
533
|
|
|
456
534
|
**Relationship types:**
|
|
457
535
|
|
|
458
|
-
| Type | Description
|
|
459
|
-
| ---------------- |
|
|
460
|
-
| `related_to` | General association
|
|
461
|
-
| `supersedes` | Entry replaces another
|
|
462
|
-
| `depends_on` | Entry depends on another
|
|
463
|
-
| `contradicts` | Entries have conflicting information
|
|
464
|
-
| `specializes` | Entry is a specific case of another
|
|
465
|
-
| `part_of` | Entry is a component of another
|
|
466
|
-
| `alternative_to` | Entry is an alternative to another
|
|
467
|
-
| `builds_on` | Entry extends or builds on another
|
|
536
|
+
| Type | Description |
|
|
537
|
+
| ---------------- | ------------------------------------------------------------------- |
|
|
538
|
+
| `related_to` | General association |
|
|
539
|
+
| `supersedes` | Entry replaces another |
|
|
540
|
+
| `depends_on` | Entry depends on another |
|
|
541
|
+
| `contradicts` | Entries have conflicting information |
|
|
542
|
+
| `specializes` | Entry is a specific case of another |
|
|
543
|
+
| `part_of` | Entry is a component of another |
|
|
544
|
+
| `alternative_to` | Entry is an alternative to another |
|
|
545
|
+
| `builds_on` | Entry extends or builds on another |
|
|
546
|
+
| `calls` | Function/method X calls Y (code structure, v1.7+, `code:` node IDs) |
|
|
547
|
+
| `imports` | Module X imports Y (code structure) |
|
|
548
|
+
| `inherits` | Class X inherits from Y (code structure) |
|
|
468
549
|
|
|
469
550
|
**Action: link**
|
|
470
551
|
|
|
@@ -493,13 +574,43 @@ knowledge_graph with action "list", entry "projects/backend.md"
|
|
|
493
574
|
knowledge_graph with action "list", rel_type "depends_on"
|
|
494
575
|
```
|
|
495
576
|
|
|
577
|
+
**Action: invalidate**
|
|
578
|
+
|
|
579
|
+
Set `valid_to` on one or more edges without deleting them. Preserves history for temporal queries.
|
|
580
|
+
|
|
581
|
+
```
|
|
582
|
+
knowledge_graph with action "invalidate", source "projects/backend.md", target "decisions/use-jwt.md"
|
|
583
|
+
knowledge_graph with action "invalidate", source "projects/backend.md", target "decisions/use-jwt.md", valid_to "2026-03-15"
|
|
584
|
+
```
|
|
585
|
+
|
|
496
586
|
**Action: traverse**
|
|
497
587
|
|
|
498
|
-
BFS traversal from a starting entry. Returns a graph of connected entries.
|
|
588
|
+
Directed BFS traversal from a starting entry. Returns a graph of connected entries.
|
|
499
589
|
|
|
500
590
|
```
|
|
501
591
|
knowledge_graph with action "traverse", entry "projects/backend.md"
|
|
502
592
|
knowledge_graph with action "traverse", entry "projects/backend.md", depth 3
|
|
593
|
+
knowledge_graph with action "traverse", entry "code:src/auth.ts::login", direction "inbound", rel_type "calls"
|
|
594
|
+
knowledge_graph with action "traverse", entry "projects/backend.md", as_of "2026-01-01"
|
|
595
|
+
```
|
|
596
|
+
|
|
597
|
+
**Action: bulk_link**
|
|
598
|
+
|
|
599
|
+
Batch-create edges in a single transaction. Used by `knowledge-ingest` for code graphs (hundreds to thousands of edges per ingest).
|
|
600
|
+
|
|
601
|
+
```
|
|
602
|
+
knowledge_graph with action "bulk_link", edges [
|
|
603
|
+
{ "source": "code:src/a.ts", "target": "code:src/b.ts", "rel_type": "imports", "origin": "tree-sitter" },
|
|
604
|
+
...
|
|
605
|
+
]
|
|
606
|
+
```
|
|
607
|
+
|
|
608
|
+
**Action: unlink_by_origin**
|
|
609
|
+
|
|
610
|
+
Delete every edge matching a specific `origin` tag. Used to clear stale code-graph edges before a re-ingest.
|
|
611
|
+
|
|
612
|
+
```
|
|
613
|
+
knowledge_graph with action "unlink_by_origin", origin "tree-sitter"
|
|
503
614
|
```
|
|
504
615
|
|
|
505
616
|
---
|
|
@@ -510,13 +621,16 @@ Analysis tools for knowledge base maintenance.
|
|
|
510
621
|
|
|
511
622
|
**Parameters:**
|
|
512
623
|
|
|
513
|
-
| Name
|
|
514
|
-
|
|
|
515
|
-
| `action`
|
|
516
|
-
| `category`
|
|
517
|
-
| `threshold`
|
|
518
|
-
| `max_entries`
|
|
519
|
-
| `top_n`
|
|
624
|
+
| Name | Type | Required | Description |
|
|
625
|
+
| ------------------ | ------ | -------- | ---------------------------------------------------------------------------------------- |
|
|
626
|
+
| `action` | string | Yes | One of: `consolidate`, `reflect`, `god_nodes`, `bridges`, `gaps`, `brief`, `search_gaps` |
|
|
627
|
+
| `category` | string | No | Scan only this category (omit for all) |
|
|
628
|
+
| `threshold` | number | No | [consolidate] Similarity threshold 0-1 (default: 0.5) |
|
|
629
|
+
| `max_entries` | number | No | [reflect/gaps] Max entries to include (default: 20 for reflect, 30 for gaps) |
|
|
630
|
+
| `top_n` | number | No | [god_nodes/bridges] Max entries to return (default: 10 for god_nodes, 5 bridges) |
|
|
631
|
+
| `since_days` | number | No | [search_gaps] Lookback window in days (default: 30) |
|
|
632
|
+
| `min_count` | number | No | [search_gaps] Minimum occurrence count per merged group (default: 1) |
|
|
633
|
+
| `group_similarity` | number | No | [search_gaps] Jaccard token similarity threshold for grouping (default: 0.7) |
|
|
520
634
|
|
|
521
635
|
**Action: consolidate**
|
|
522
636
|
|
|
@@ -578,6 +692,23 @@ No parameters.
|
|
|
578
692
|
|
|
579
693
|
Returns: `{ total_entries, total_edges, core_concepts, active_projects, recent_decisions, stale_count, gap_count, generated_at, text }`. The `text` field is a ~200 token plain-text summary suitable for injection into agent prompts.
|
|
580
694
|
|
|
695
|
+
**Action: `search_gaps`**
|
|
696
|
+
|
|
697
|
+
Returns zero-result `knowledge_search` queries grouped by similarity — the single strongest signal for "what knowledge entries should I write next?". Every `knowledge_search` call is logged to a small `query_log` SQLite table (query text scrubbed for secrets before insertion). Queries that returned zero results are merged into groups via token-set Jaccard similarity, so `"gitlab token"` and `"gitlab credentials"` collapse into one row.
|
|
698
|
+
|
|
699
|
+
| Parameter | Type | Default | Description |
|
|
700
|
+
| ------------------ | ------ | ------- | ----------------------------------------------------------------- |
|
|
701
|
+
| `since_days` | number | 30 | Lookback window in days |
|
|
702
|
+
| `min_count` | number | 1 | Minimum occurrence count per merged group (raise to filter noise) |
|
|
703
|
+
| `group_similarity` | number | 0.7 | Jaccard token similarity threshold for merging queries (0-1) |
|
|
704
|
+
|
|
705
|
+
Returns: array of `{ query, count, last_seen, similar_queries? }` sorted by count descending, then by `last_seen` descending. `query` is the most-recent query text in the group; `similar_queries` lists the other variants collapsed into the same group (omitted when the group has only one member).
|
|
706
|
+
|
|
707
|
+
```
|
|
708
|
+
knowledge_analyze with action "search_gaps"
|
|
709
|
+
knowledge_analyze with action "search_gaps", since_days 7, min_count 3
|
|
710
|
+
```
|
|
711
|
+
|
|
581
712
|
---
|
|
582
713
|
|
|
583
714
|
## 6. REST API Reference
|
|
@@ -678,7 +809,11 @@ Knowledge entries are Markdown files with optional YAML frontmatter:
|
|
|
678
809
|
|
|
679
810
|
```markdown
|
|
680
811
|
---
|
|
812
|
+
title: JWT Authentication
|
|
681
813
|
tags: [auth, security, jwt]
|
|
814
|
+
updated: 2026-04-18
|
|
815
|
+
confidence: extracted
|
|
816
|
+
evergreen: true
|
|
682
817
|
---
|
|
683
818
|
|
|
684
819
|
# JWT Authentication
|
|
@@ -686,6 +821,17 @@ tags: [auth, security, jwt]
|
|
|
686
821
|
We use JWT with refresh tokens for stateless authentication...
|
|
687
822
|
```
|
|
688
823
|
|
|
824
|
+
**Recognised frontmatter fields:**
|
|
825
|
+
|
|
826
|
+
| Field | Type | Meaning |
|
|
827
|
+
| ------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
828
|
+
| `title` | string | Display title; derived from filename when omitted. |
|
|
829
|
+
| `tags` | string[] | Inline array form, e.g. `[auth, security]`. Filterable via `knowledge(action="list", tag=…)`. |
|
|
830
|
+
| `updated` | string (date) | Human-readable last-edited date. |
|
|
831
|
+
| `confidence` | string | `extracted` (user-written, 1.0× rank) or `inferred` (auto-distilled / auto-promoted, 0.85× rank). |
|
|
832
|
+
| `confidence_score` | number | Optional 0–1 float carrying a finer-grained model certainty for distilled content. |
|
|
833
|
+
| `evergreen` | boolean | **v1.8**: when `true`, the entry skips time-based decay in ranking AND the scored promoter appends to rather than overwrites the entry. Use for durable decisions / identity. |
|
|
834
|
+
|
|
689
835
|
### Categories
|
|
690
836
|
|
|
691
837
|
Entries are organized into categories (directories):
|
package/docs/hooks.md
CHANGED
|
@@ -1,38 +1,86 @@
|
|
|
1
1
|
# Hooks (Claude Code)
|
|
2
2
|
|
|
3
|
-
agent-knowledge ships
|
|
3
|
+
agent-knowledge ships five hook scripts that integrate with Claude Code's
|
|
4
4
|
lifecycle events. They live under `scripts/hooks/` and are installed by
|
|
5
5
|
`scripts/setup.js` into `~/.claude/settings.json`.
|
|
6
6
|
|
|
7
7
|
All hooks fail open — any internal error is logged to stderr and the hook
|
|
8
8
|
returns an empty JSON object so the user is never blocked.
|
|
9
9
|
|
|
10
|
-
| Script
|
|
11
|
-
|
|
|
12
|
-
| `session-start.js`
|
|
13
|
-
| `
|
|
14
|
-
| `precompact-
|
|
15
|
-
| `
|
|
10
|
+
| Script | Event | Purpose |
|
|
11
|
+
| ------------------------- | ---------------- | ------------------------------------------------------------------------ |
|
|
12
|
+
| `session-start.js` | SessionStart | Announces dashboard URL + auto-loads wakeup payload into context |
|
|
13
|
+
| `first-prompt-inject.mjs` | UserPromptSubmit | Injects query-targeted knowledge hits on the session's first real prompt |
|
|
14
|
+
| `precompact-flush.mjs` | PreCompact | Rich session summary on disk + save-unsaved-context nudge into context |
|
|
15
|
+
| `precompact-distill.mjs` | PreCompact | Lightweight text snapshot of recent user prompts |
|
|
16
|
+
| `sessionend-distill.mjs` | SessionEnd | Final summary (turn counts, tool uses, first 20 prompts) |
|
|
16
17
|
|
|
17
18
|
## session-start.js
|
|
18
19
|
|
|
19
|
-
|
|
20
|
-
|
|
20
|
+
Two jobs:
|
|
21
|
+
|
|
22
|
+
1. Prints the dashboard URL (`http://localhost:3423` by default, override via
|
|
23
|
+
`AGENT_KNOWLEDGE_PORT`) and injects it into SessionStart `additionalContext`.
|
|
24
|
+
2. Auto-loads a token-budgeted **wakeup** payload (L0 identity + L1 top-weighted
|
|
25
|
+
entries) into the same `additionalContext`, so the agent starts every session
|
|
26
|
+
with a small world-model already in the prompt — no manual
|
|
27
|
+
`knowledge(action="wakeup")` call required.
|
|
28
|
+
|
|
29
|
+
### Environment variables
|
|
30
|
+
|
|
31
|
+
| Variable | Default | Description |
|
|
32
|
+
| ------------------------------- | ------- | --------------------------------------------------- |
|
|
33
|
+
| `AGENT_KNOWLEDGE_PORT` | `3423` | Dashboard port announced in the context line |
|
|
34
|
+
| `AGENT_KNOWLEDGE_AUTOWAKE` | `1` | Set `0` / `false` to skip the wakeup auto-injection |
|
|
35
|
+
| `AGENT_KNOWLEDGE_WAKEUP_BUDGET` | `800` | Max tokens (chars/4 estimate) for the L0+L1 blob |
|
|
36
|
+
|
|
37
|
+
Requires `npm run build` to have succeeded — if `dist/wakeup.js` is missing,
|
|
38
|
+
only the dashboard-URL line is emitted (fail-open).
|
|
39
|
+
|
|
40
|
+
## first-prompt-inject.mjs
|
|
41
|
+
|
|
42
|
+
Fires on UserPromptSubmit. When the session's FIRST real user prompt arrives,
|
|
43
|
+
runs it through `searchKnowledge(prompt, { mmr: true })` and injects the top-K
|
|
44
|
+
hits into `additionalContext` before the model reads the prompt. Complements
|
|
45
|
+
the wakeup pack (which is query-agnostic) with query-targeted context.
|
|
46
|
+
|
|
47
|
+
Gates (all must pass to fire):
|
|
48
|
+
|
|
49
|
+
- Prompt length ≥ 10 characters.
|
|
50
|
+
- Prompt does NOT start with `/` (slash command) or `!` (bash shortcut).
|
|
51
|
+
- No marker file exists yet for this session ID.
|
|
52
|
+
|
|
53
|
+
The marker file (`{dataDir}/.first-prompt-seen/<session_id>`) is only written
|
|
54
|
+
AFTER a real search has run — skip-gates like `/clear` do NOT burn the shot,
|
|
55
|
+
so the user's next real question still gets injection.
|
|
56
|
+
|
|
57
|
+
### Environment variables
|
|
58
|
+
|
|
59
|
+
| Variable | Default | Description |
|
|
60
|
+
| -------------------------------------- | ------------------- | ------------------------------------------------------- |
|
|
61
|
+
| `AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT` | `1` | Set `0` / `false` / `off` to disable |
|
|
62
|
+
| `AGENT_KNOWLEDGE_FIRSTPROMPT_BUDGET` | `600` | Max tokens (chars/4 estimate), clamped to `[100, 8000]` |
|
|
63
|
+
| `AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS` | `4` | Max rendered entries, clamped to `[1, 20]` |
|
|
64
|
+
| `KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Knowledge base to search |
|
|
21
65
|
|
|
22
66
|
## precompact-flush.mjs
|
|
23
67
|
|
|
24
|
-
Called right before the host compacts the transcript.
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
68
|
+
Called right before the host compacts the transcript. Two jobs:
|
|
69
|
+
|
|
70
|
+
1. Imports `dist/sessions/summary.js` from the built library, pulls a rich
|
|
71
|
+
session summary via `getSessionSummary(sessionId)`, and writes it to
|
|
72
|
+
`~/agent-knowledge/sessions/<project-slug>/precompact-<timestamp>-<id>.md`.
|
|
73
|
+
If `dist/` is missing, the disk dump is skipped (fail-open).
|
|
74
|
+
2. Injects a short "save-unsaved-context" nudge into the PreCompact
|
|
75
|
+
`additionalContext` so the agent is prompted to write anything important
|
|
76
|
+
to the knowledge base BEFORE compaction summarises the transcript away.
|
|
30
77
|
|
|
31
78
|
### Environment variables
|
|
32
79
|
|
|
33
|
-
| Variable
|
|
34
|
-
|
|
|
35
|
-
| `KNOWLEDGE_MEMORY_DIR`
|
|
80
|
+
| Variable | Default | Description |
|
|
81
|
+
| ---------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
82
|
+
| `KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Where rich summaries are written |
|
|
83
|
+
| `AGENT_KNOWLEDGE_PRECOMPACT_NUDGE` | `1` | Set `0` / `false` to disable the nudge only. Set `off` to suppress both the nudge AND the disk dump. |
|
|
36
84
|
|
|
37
85
|
## precompact-distill.mjs
|
|
38
86
|
|
|
@@ -76,6 +124,17 @@ automatically. If you need to configure them by hand, add entries like:
|
|
|
76
124
|
]
|
|
77
125
|
}
|
|
78
126
|
],
|
|
127
|
+
"UserPromptSubmit": [
|
|
128
|
+
{
|
|
129
|
+
"hooks": [
|
|
130
|
+
{
|
|
131
|
+
"type": "command",
|
|
132
|
+
"command": "node \"/abs/path/to/agent-knowledge/scripts/hooks/first-prompt-inject.mjs\"",
|
|
133
|
+
"timeout": 10
|
|
134
|
+
}
|
|
135
|
+
]
|
|
136
|
+
}
|
|
137
|
+
],
|
|
79
138
|
"PreCompact": [
|
|
80
139
|
{
|
|
81
140
|
"hooks": [
|
|
@@ -111,6 +170,7 @@ Replace `/abs/path/to/agent-knowledge` with your clone path.
|
|
|
111
170
|
|
|
112
171
|
## Testing the hooks
|
|
113
172
|
|
|
114
|
-
`tests/hooks/hooks.test.ts` covers all
|
|
115
|
-
fail-open assertions
|
|
116
|
-
|
|
173
|
+
`tests/hooks/hooks.test.ts` covers all five scripts with shape-correct
|
|
174
|
+
fail-open assertions plus a positive-path render test for
|
|
175
|
+
`first-prompt-inject.mjs`. Run `npm test -- tests/hooks/` to execute them
|
|
176
|
+
in isolation.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agent-knowledge",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.8.1",
|
|
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",
|
|
@@ -41,6 +41,9 @@
|
|
|
41
41
|
"test": "vitest run",
|
|
42
42
|
"test:watch": "vitest",
|
|
43
43
|
"bench": "tsx bench/run.ts",
|
|
44
|
+
"bench:longmemeval": "tsx bench/longmemeval.ts",
|
|
45
|
+
"bench:longmemeval:matrix": "tsx bench/longmemeval-matrix.ts",
|
|
46
|
+
"bench:promote": "tsx bench/promote-bench.ts",
|
|
44
47
|
"test:coverage": "vitest run --coverage",
|
|
45
48
|
"lint": "eslint src/ tests/",
|
|
46
49
|
"lint:fix": "eslint src/ tests/ --fix",
|