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.
Files changed (66) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/.mcp.json +1 -1
  3. package/CHANGELOG.md +101 -0
  4. package/README.md +43 -18
  5. package/agent-desk-plugin.json +1 -1
  6. package/dist/dashboard.d.ts.map +1 -1
  7. package/dist/dashboard.js +28 -1
  8. package/dist/dashboard.js.map +1 -1
  9. package/dist/knowledge/analyze.d.ts +18 -0
  10. package/dist/knowledge/analyze.d.ts.map +1 -1
  11. package/dist/knowledge/analyze.js +22 -0
  12. package/dist/knowledge/analyze.js.map +1 -1
  13. package/dist/knowledge/freshness.d.ts +99 -0
  14. package/dist/knowledge/freshness.d.ts.map +1 -0
  15. package/dist/knowledge/freshness.js +303 -0
  16. package/dist/knowledge/freshness.js.map +1 -0
  17. package/dist/knowledge/promote.d.ts +145 -0
  18. package/dist/knowledge/promote.d.ts.map +1 -0
  19. package/dist/knowledge/promote.js +532 -0
  20. package/dist/knowledge/promote.js.map +1 -0
  21. package/dist/knowledge/query-log.d.ts +88 -0
  22. package/dist/knowledge/query-log.d.ts.map +1 -0
  23. package/dist/knowledge/query-log.js +207 -0
  24. package/dist/knowledge/query-log.js.map +1 -0
  25. package/dist/knowledge/scoring.d.ts +22 -2
  26. package/dist/knowledge/scoring.d.ts.map +1 -1
  27. package/dist/knowledge/scoring.js +51 -3
  28. package/dist/knowledge/scoring.js.map +1 -1
  29. package/dist/knowledge/search.d.ts +56 -5
  30. package/dist/knowledge/search.d.ts.map +1 -1
  31. package/dist/knowledge/search.js +88 -10
  32. package/dist/knowledge/search.js.map +1 -1
  33. package/dist/knowledge/store.d.ts +12 -0
  34. package/dist/knowledge/store.d.ts.map +1 -1
  35. package/dist/knowledge/store.js +18 -0
  36. package/dist/knowledge/store.js.map +1 -1
  37. package/dist/search/mmr.d.ts +54 -0
  38. package/dist/search/mmr.d.ts.map +1 -0
  39. package/dist/search/mmr.js +138 -0
  40. package/dist/search/mmr.js.map +1 -0
  41. package/dist/server.d.ts +334 -0
  42. package/dist/server.d.ts.map +1 -1
  43. package/dist/server.js +378 -301
  44. package/dist/server.js.map +1 -1
  45. package/dist/sessions/indexer.d.ts.map +1 -1
  46. package/dist/sessions/indexer.js +13 -11
  47. package/dist/sessions/indexer.js.map +1 -1
  48. package/dist/tool-handlers.d.ts +10 -3
  49. package/dist/tool-handlers.d.ts.map +1 -1
  50. package/dist/tool-handlers.js +150 -21
  51. package/dist/tool-handlers.js.map +1 -1
  52. package/dist/ui/app.js +271 -1
  53. package/dist/ui/render-knowledge.js +3 -3
  54. package/dist/ui/styles.css +209 -0
  55. package/dist/wakeup.d.ts +59 -14
  56. package/dist/wakeup.d.ts.map +1 -1
  57. package/dist/wakeup.js +406 -43
  58. package/dist/wakeup.js.map +1 -1
  59. package/docs/ARCHITECTURE.md +31 -6
  60. package/docs/SETUP.md +20 -8
  61. package/docs/USER-MANUAL.md +205 -59
  62. package/docs/hooks.md +81 -21
  63. package/package.json +4 -1
  64. package/scripts/hooks/first-prompt-inject.mjs +230 -0
  65. package/scripts/hooks/precompact-flush.mjs +89 -60
  66. 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 4 hooks into `~/.claude/settings.json`, and grants `mcp__agent-knowledge__*` permission in one shot. Restart Claude Code afterwards to pick up the new config.
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 **4 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.
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 | Event | Purpose |
186
- | ------------------------ | ------------ | ------------------------------------------------------------- |
187
- | `session-start.js` | SessionStart | Announces the knowledge dashboard URL |
188
- | `precompact-flush.mjs` | PreCompact | Rich session summary via the compiled agent-knowledge library |
189
- | `precompact-distill.mjs` | PreCompact | Lightweight text snapshot of recent user prompts |
190
- | `sessionend-distill.mjs` | SessionEnd | Final summary (turn counts, tool uses, first 20 prompts) |
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": [
@@ -212,15 +212,17 @@ Knowledge base CRUD, git sync, and session-start hydration.
212
212
 
213
213
  **Parameters:**
214
214
 
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 L0+L1 blob (chars/4 estimate, default 800, range 50–8000) |
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 small "L0 + L1" context blob: identity (from `~/agent-knowledge/identity.md`) plus the highest-weighted entries, fit under a token budget. Call once at session start so the agent has its world loaded before issuing any real search.
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
- Weight = `recency × log(size+1)` — recently-edited and substantial entries float to the top. The blob is rendered as Markdown with one bullet per L1 entry; each bullet is a short excerpt.
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 }`, top-weighted first.
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` when the budget cut off the L1 list.
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 | Type | Required | Description |
303
- | ------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
304
- | `query` | string | Yes | Search query -- supports keywords and phrases |
305
- | `scope` | string | No | Search scope: `errors`, `plans`, `configs`, `tools`, `files`, `decisions`, `all`. When provided, performs scoped recall in sessions only. |
306
- | `project` | string | No | Restrict to sessions from this project |
307
- | `role` | string | No | Filter by message role: `user`, `assistant`, `all` (default: all, ignored when scope is set) |
308
- | `max_results` | number | No | Maximum results (default: 20) |
309
- | `ranked` | boolean | No | Use TF-IDF ranking (default: true, ignored when scope is set) |
310
- | `semantic` | boolean | No | Blend semantic similarity with TF-IDF (default: true) |
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 embedding management.
422
+ Admin operations for configuration, index stats, embedding management, and the v1.8 scored promoter.
393
423
 
394
424
  **Parameters:**
395
425
 
396
- | Name | Type | Required | Description |
397
- | -------------- | ------- | -------- | -------------------------------------------------------- |
398
- | `action` | string | Yes | One of: `status`, `config`, `rebuild_embeddings` |
399
- | `git_url` | string | No | [config] Git remote URL (empty string to remove) |
400
- | `memory_dir` | string | No | [config] Local knowledge base directory (empty to reset) |
401
- | `auto_distill` | boolean | No | [config] Enable/disable session distillation |
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-distillation
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 for creating and traversing relationships between entries.
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 | Type | Required | Description |
447
- | ---------- | ------ | -------- | ---------------------------------------------------------------------- |
448
- | `action` | string | Yes | One of: `link`, `unlink`, `list`, `traverse` |
449
- | `source` | string | Varies | [link/unlink] Source entry path |
450
- | `target` | string | Varies | [link/unlink] Target entry path |
451
- | `entry` | string | No | [list] Filter by entry path; [traverse] BFS start node |
452
- | `rel_type` | string | Varies | Relationship type (required for link, optional filter for unlink/list) |
453
- | `strength` | number | No | [link] Edge strength 0-1 (default: 0.5) |
454
- | `depth` | number | No | [traverse] Max traversal depth in hops (default: 2) |
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 | Type | Required | Description |
514
- | ------------- | ------ | -------- | -------------------------------------------------------------------------------- |
515
- | `action` | string | Yes | One of: `consolidate`, `reflect`, `god_nodes`, `bridges`, `gaps`, `brief` |
516
- | `category` | string | No | Scan only this category (omit for all) |
517
- | `threshold` | number | No | [consolidate] Similarity threshold 0-1 (default: 0.5) |
518
- | `max_entries` | number | No | [reflect/gaps] Max entries to include (default: 20 for reflect, 30 for gaps) |
519
- | `top_n` | number | No | [god_nodes/bridges] Max entries to return (default: 10 for god_nodes, 5 bridges) |
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 four hook scripts that integrate with Claude Code's
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 | Event | Purpose |
11
- | ------------------------ | ------------ | -------------------------------------------------------- |
12
- | `session-start.js` | SessionStart | Announces the knowledge dashboard URL |
13
- | `precompact-flush.mjs` | PreCompact | Rich session summary via the library |
14
- | `precompact-distill.mjs` | PreCompact | Lightweight text snapshot of recent user prompts |
15
- | `sessionend-distill.mjs` | SessionEnd | Final summary (turn counts, tool uses, first 20 prompts) |
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
- Prints the dashboard URL (`http://localhost:3423` by default, override via
20
- `AGENT_KNOWLEDGE_PORT`) and injects it as session context.
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. Imports
25
- `dist/sessions/summary.js` from the built agent-knowledge library, pulls a
26
- rich session summary via `getSessionSummary(sessionId)`, and writes it to
27
- `~/agent-knowledge/sessions/<project-slug>/precompact-<timestamp>-<id>.md`.
28
- Requires `npm run build` to have succeeded — if `dist/` is missing, the hook
29
- logs the reason to stderr and emits `{}`.
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 | Default | Description |
34
- | ---------------------- | ------------------- | -------------------------------- |
35
- | `KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Where rich summaries are written |
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 four scripts with shape-correct
115
- fail-open assertions. Run `npm test -- tests/hooks/` to execute them in
116
- isolation.
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.7.3",
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",