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.
Files changed (44) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/.mcp.json +1 -1
  3. package/CHANGELOG.md +43 -0
  4. package/README.md +43 -18
  5. package/agent-desk-plugin.json +1 -1
  6. package/dist/knowledge/promote.d.ts +145 -0
  7. package/dist/knowledge/promote.d.ts.map +1 -0
  8. package/dist/knowledge/promote.js +517 -0
  9. package/dist/knowledge/promote.js.map +1 -0
  10. package/dist/knowledge/scoring.d.ts +6 -2
  11. package/dist/knowledge/scoring.d.ts.map +1 -1
  12. package/dist/knowledge/scoring.js +7 -3
  13. package/dist/knowledge/scoring.js.map +1 -1
  14. package/dist/knowledge/search.d.ts +32 -5
  15. package/dist/knowledge/search.d.ts.map +1 -1
  16. package/dist/knowledge/search.js +60 -10
  17. package/dist/knowledge/search.js.map +1 -1
  18. package/dist/knowledge/store.d.ts +6 -0
  19. package/dist/knowledge/store.d.ts.map +1 -1
  20. package/dist/knowledge/store.js +10 -0
  21. package/dist/knowledge/store.js.map +1 -1
  22. package/dist/search/mmr.d.ts +54 -0
  23. package/dist/search/mmr.d.ts.map +1 -0
  24. package/dist/search/mmr.js +138 -0
  25. package/dist/search/mmr.js.map +1 -0
  26. package/dist/server.d.ts +307 -0
  27. package/dist/server.d.ts.map +1 -1
  28. package/dist/server.js +336 -301
  29. package/dist/server.js.map +1 -1
  30. package/dist/sessions/indexer.d.ts.map +1 -1
  31. package/dist/sessions/indexer.js +13 -11
  32. package/dist/sessions/indexer.js.map +1 -1
  33. package/dist/tool-handlers.d.ts +10 -3
  34. package/dist/tool-handlers.d.ts.map +1 -1
  35. package/dist/tool-handlers.js +56 -17
  36. package/dist/tool-handlers.js.map +1 -1
  37. package/docs/ARCHITECTURE.md +31 -6
  38. package/docs/SETUP.md +20 -8
  39. package/docs/USER-MANUAL.md +146 -39
  40. package/docs/hooks.md +81 -21
  41. package/package.json +4 -1
  42. package/scripts/hooks/first-prompt-inject.mjs +230 -0
  43. package/scripts/hooks/precompact-flush.mjs +89 -60
  44. package/scripts/hooks/session-start.js +73 -9
@@ -297,26 +297,37 @@ knowledge with action "wakeup", category "projects"
297
297
 
298
298
  Search across sessions and knowledge entries. Supports general search and scoped recall.
299
299
 
300
+ **Response shape** (v1.8): `{ mode, sessions, knowledge }`.
301
+
302
+ - `mode: "general"` — hybrid TF-IDF + semantic across both sources.
303
+ - `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).
304
+
300
305
  **Parameters:**
301
306
 
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) |
307
+ | Name | Type | Required | Description |
308
+ | --------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
309
+ | `query` | string | Yes | Search query -- supports keywords and phrases |
310
+ | `scope` | string | No | Search scope: `errors`, `plans`, `configs`, `tools`, `files`, `decisions`, `all`. When provided, performs scoped recall in sessions only. |
311
+ | `project` | string | No | Restrict to sessions from this project |
312
+ | `role` | string | No | Filter by message role: `user`, `assistant`, `all` (default: all, ignored when scope is set) |
313
+ | `max_results` | number | No | Maximum results (default: 20) |
314
+ | `ranked` | boolean | No | Use TF-IDF ranking (default: true, ignored when scope is set) |
315
+ | `semantic` | boolean | No | Blend semantic similarity with TF-IDF (default: true) |
316
+ | `category` | string | No | Category hint for the knowledge leg: `projects`, `people`, `decisions`, `workflows`, `notes` |
317
+ | `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) |
318
+ | `mmr` | boolean | No | Apply Maximal Marginal Relevance re-ranking to knowledge hits. Default `false`. Kills near-duplicate clusters in the top-K. |
319
+ | `mmr_lambda` | number | No | MMR tradeoff, `0`–`1` (default `0.7`). `1.0` = pure relevance; `0.0` = pure diversity. |
320
+ | `explain` | boolean | No | When `true`, each knowledge hit carries a `score_components` breakdown: `{bm25, decay, maturity, confidence, category_boost, mmr_penalty}`. |
311
321
 
312
322
  **General search** (no scope):
313
323
 
314
324
  ```
315
325
  knowledge_search with query "authentication error handling"
316
326
  knowledge_search with query "database migration", project "backend"
327
+ knowledge_search with query "why postgres", category "decisions", mmr true, explain true
317
328
  ```
318
329
 
319
- Returns both session matches and knowledge base matches.
330
+ Returns `{ mode: "general", sessions, knowledge }` — both session matches and knowledge base matches.
320
331
 
321
332
  **Scoped recall** (with scope):
322
333
 
@@ -389,16 +400,22 @@ knowledge_session with action "summary", session_id "abc-123-def"
389
400
 
390
401
  ### knowledge_admin
391
402
 
392
- Admin operations for configuration, index stats, and embedding management.
403
+ Admin operations for configuration, index stats, embedding management, and the v1.8 scored promoter.
393
404
 
394
405
  **Parameters:**
395
406
 
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 |
407
+ | Name | Type | Required | Description |
408
+ | -------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------- |
409
+ | `action` | string | Yes | One of: `status`, `config`, `rebuild_embeddings`, `prune_orphans`, `vacuum`, `promote` |
410
+ | `git_url` | string | No | [config] Git remote URL (empty string to remove) |
411
+ | `memory_dir` | string | No | [config] Local knowledge base directory (empty to reset) |
412
+ | `auto_distill` | boolean | No | [config] Enable/disable scheduled promotion (governs the promoter, not the legacy regex distiller) |
413
+ | `vacuum` | boolean | No | [prune_orphans] Run VACUUM after pruning (default `true`) |
414
+ | `force_vacuum` | boolean | No | [prune_orphans] Run VACUUM even when no orphans were pruned |
415
+ | `promote_mode` | string | No | [promote] `explain` (default — read-only, returns score breakdowns) or `apply` (write + git-commit) |
416
+ | `min_score` | number | No | [promote] Override minScore gate (default `0.5`) |
417
+ | `min_recall_count` | number | No | [promote] Override minRecallCount gate (default `2`) |
418
+ | `min_unique_queries` | number | No | [promote] Override minUniqueQueries gate (default `2`) |
402
419
 
403
420
  **Action: status**
404
421
 
@@ -421,7 +438,7 @@ knowledge_admin with action "config"
421
438
  # Update git URL
422
439
  knowledge_admin with action "config", git_url "https://github.com/user/memory.git"
423
440
 
424
- # Disable auto-distillation
441
+ # Disable auto-promotion (the v1.8 scored promoter runs on backgroundIndex)
425
442
  knowledge_admin with action "config", auto_distill false
426
443
  ```
427
444
 
@@ -435,36 +452,81 @@ knowledge_admin with action "rebuild_embeddings"
435
452
 
436
453
  Wipes existing vectors, re-creates the store with the current provider's dimensions, and re-embeds all entries. Returns processed/failed counts.
437
454
 
455
+ **Action: prune_orphans**
456
+
457
+ Delete vector embeddings for sessions no longer present on disk. Optionally follows with VACUUM to reclaim pages.
458
+
459
+ ```
460
+ knowledge_admin with action "prune_orphans"
461
+ knowledge_admin with action "prune_orphans", force_vacuum true
462
+ ```
463
+
464
+ **Action: vacuum**
465
+
466
+ Reclaim free SQLite pages in the vector store.
467
+
468
+ ```
469
+ knowledge_admin with action "vacuum"
470
+ ```
471
+
472
+ **Action: promote** (v1.8)
473
+
474
+ 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`.
475
+
476
+ **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.
477
+
478
+ ```
479
+ # Score candidates + write the diary, DO NOT touch the KB
480
+ knowledge_admin with action "promote"
481
+
482
+ # Actually promote + git-commit
483
+ knowledge_admin with action "promote", promote_mode "apply"
484
+
485
+ # Tighten gates for a conservative run
486
+ knowledge_admin with action "promote", promote_mode "apply", min_score 0.7, min_recall_count 3
487
+ ```
488
+
489
+ Returns `{ runStartedAt, runFinishedAt, mode, candidates[], promotedPaths[], skippedIds[], diaryPath, totals }`.
490
+
438
491
  ---
439
492
 
440
493
  ### knowledge_graph
441
494
 
442
- Knowledge graph operations for creating and traversing relationships between entries.
495
+ 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
496
 
444
497
  **Parameters:**
445
498
 
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) |
499
+ | Name | Type | Required | Description |
500
+ | ------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
501
+ | `action` | string | Yes | One of: `link`, `unlink`, `invalidate`, `list`, `traverse`, `bulk_link`, `unlink_by_origin` |
502
+ | `source` | string | Varies | [link/unlink/invalidate] Source entry path |
503
+ | `target` | string | Varies | [link/unlink/invalidate] Target entry path |
504
+ | `entry` | string | No | [list] Filter by entry path; [traverse] BFS start node |
505
+ | `rel_type` | string | Varies | Relationship type (required for link, optional filter for unlink/invalidate/list/traverse) |
506
+ | `strength` | number | No | [link] Edge strength 0-1 (default: 0.5) |
507
+ | `depth` | number | No | [traverse] Max traversal depth in hops (default: 2) |
508
+ | `valid_from` | string | No | [link] ISO date the fact became true. Null/omitted = unbounded. |
509
+ | `valid_to` | string | No | [link/invalidate] ISO date the fact stopped being true. For `invalidate`, defaults to today. |
510
+ | `as_of` | string | No | [list/traverse] Only return edges valid at this ISO date. |
511
+ | `direction` | string | No | [traverse] `outbound` (source→target), `inbound` (target→source), or `both` (default — undirected). |
512
+ | `edges` | array | No | [bulk_link] Batch of `{source, target, rel_type, strength?, origin?}` edges. Used by knowledge-ingest for code graphs. |
513
+ | `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
514
 
456
515
  **Relationship types:**
457
516
 
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 |
517
+ | Type | Description |
518
+ | ---------------- | ------------------------------------------------------------------- |
519
+ | `related_to` | General association |
520
+ | `supersedes` | Entry replaces another |
521
+ | `depends_on` | Entry depends on another |
522
+ | `contradicts` | Entries have conflicting information |
523
+ | `specializes` | Entry is a specific case of another |
524
+ | `part_of` | Entry is a component of another |
525
+ | `alternative_to` | Entry is an alternative to another |
526
+ | `builds_on` | Entry extends or builds on another |
527
+ | `calls` | Function/method X calls Y (code structure, v1.7+, `code:` node IDs) |
528
+ | `imports` | Module X imports Y (code structure) |
529
+ | `inherits` | Class X inherits from Y (code structure) |
468
530
 
469
531
  **Action: link**
470
532
 
@@ -493,13 +555,43 @@ knowledge_graph with action "list", entry "projects/backend.md"
493
555
  knowledge_graph with action "list", rel_type "depends_on"
494
556
  ```
495
557
 
558
+ **Action: invalidate**
559
+
560
+ Set `valid_to` on one or more edges without deleting them. Preserves history for temporal queries.
561
+
562
+ ```
563
+ knowledge_graph with action "invalidate", source "projects/backend.md", target "decisions/use-jwt.md"
564
+ knowledge_graph with action "invalidate", source "projects/backend.md", target "decisions/use-jwt.md", valid_to "2026-03-15"
565
+ ```
566
+
496
567
  **Action: traverse**
497
568
 
498
- BFS traversal from a starting entry. Returns a graph of connected entries.
569
+ Directed BFS traversal from a starting entry. Returns a graph of connected entries.
499
570
 
500
571
  ```
501
572
  knowledge_graph with action "traverse", entry "projects/backend.md"
502
573
  knowledge_graph with action "traverse", entry "projects/backend.md", depth 3
574
+ knowledge_graph with action "traverse", entry "code:src/auth.ts::login", direction "inbound", rel_type "calls"
575
+ knowledge_graph with action "traverse", entry "projects/backend.md", as_of "2026-01-01"
576
+ ```
577
+
578
+ **Action: bulk_link**
579
+
580
+ Batch-create edges in a single transaction. Used by `knowledge-ingest` for code graphs (hundreds to thousands of edges per ingest).
581
+
582
+ ```
583
+ knowledge_graph with action "bulk_link", edges [
584
+ { "source": "code:src/a.ts", "target": "code:src/b.ts", "rel_type": "imports", "origin": "tree-sitter" },
585
+ ...
586
+ ]
587
+ ```
588
+
589
+ **Action: unlink_by_origin**
590
+
591
+ Delete every edge matching a specific `origin` tag. Used to clear stale code-graph edges before a re-ingest.
592
+
593
+ ```
594
+ knowledge_graph with action "unlink_by_origin", origin "tree-sitter"
503
595
  ```
504
596
 
505
597
  ---
@@ -678,7 +770,11 @@ Knowledge entries are Markdown files with optional YAML frontmatter:
678
770
 
679
771
  ```markdown
680
772
  ---
773
+ title: JWT Authentication
681
774
  tags: [auth, security, jwt]
775
+ updated: 2026-04-18
776
+ confidence: extracted
777
+ evergreen: true
682
778
  ---
683
779
 
684
780
  # JWT Authentication
@@ -686,6 +782,17 @@ tags: [auth, security, jwt]
686
782
  We use JWT with refresh tokens for stateless authentication...
687
783
  ```
688
784
 
785
+ **Recognised frontmatter fields:**
786
+
787
+ | Field | Type | Meaning |
788
+ | ------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
789
+ | `title` | string | Display title; derived from filename when omitted. |
790
+ | `tags` | string[] | Inline array form, e.g. `[auth, security]`. Filterable via `knowledge(action="list", tag=…)`. |
791
+ | `updated` | string (date) | Human-readable last-edited date. |
792
+ | `confidence` | string | `extracted` (user-written, 1.0× rank) or `inferred` (auto-distilled / auto-promoted, 0.85× rank). |
793
+ | `confidence_score` | number | Optional 0–1 float carrying a finer-grained model certainty for distilled content. |
794
+ | `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. |
795
+
689
796
  ### Categories
690
797
 
691
798
  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.0",
4
4
  "description": "Cross-session memory and recall for AI agents — git-synced knowledge base, knowledge graph, confidence scoring, hybrid semantic+TF-IDF search, auto-distillation with secrets scrubbing",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -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",
@@ -0,0 +1,230 @@
1
+ #!/usr/bin/env node
2
+
3
+ // =============================================================================
4
+ // agent-knowledge UserPromptSubmit hook — first-prompt knowledge injection
5
+ //
6
+ // When the user sends the FIRST real prompt of a session, run the prompt text
7
+ // through knowledge_search and inject the top-K hits as additionalContext
8
+ // before the model sees the prompt. Complements the SessionStart wakeup
9
+ // (which is query-agnostic) by pulling in entries that are directly relevant
10
+ // to whatever the user is about to ask.
11
+ //
12
+ // Gates (all must pass to fire):
13
+ // - AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT != 0 / false / off
14
+ // - Prompt is >= 10 chars
15
+ // - Prompt does not start with `/` (skip slash commands)
16
+ // - No marker file exists yet for this session id
17
+ //
18
+ // Fires once per session. Subsequent prompts see only the wakeup pack and
19
+ // whatever they search for themselves. A marker file at
20
+ // `{dataDir}/.first-prompt-seen/<session_id>` records "already fired".
21
+ //
22
+ // Envs:
23
+ // AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT (default "1") — set "0" to disable
24
+ // AGENT_KNOWLEDGE_FIRSTPROMPT_BUDGET (default "600") — max chars/4 tokens
25
+ // AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS (default "4") — cap on rendered hits
26
+ // KNOWLEDGE_MEMORY_DIR — resolves memory dir (same as core)
27
+ //
28
+ // Fail-open: every error path prints `{}` so the host never blocks on this
29
+ // hook. Log-only stderr for diagnostics.
30
+ // =============================================================================
31
+
32
+ import fs from 'fs';
33
+ import path from 'path';
34
+ import { dirname, resolve } from 'path';
35
+ import { fileURLToPath } from 'url';
36
+ import { homedir } from 'os';
37
+
38
+ const __filename = fileURLToPath(import.meta.url);
39
+ const __dirname = dirname(__filename);
40
+
41
+ function emit(additionalContext) {
42
+ const payload = additionalContext
43
+ ? {
44
+ hookSpecificOutput: {
45
+ hookEventName: 'UserPromptSubmit',
46
+ additionalContext,
47
+ },
48
+ }
49
+ : {};
50
+ process.stdout.write(JSON.stringify(payload) + '\n');
51
+ process.exit(0);
52
+ }
53
+
54
+ function warn(msg) {
55
+ process.stderr.write(`[knowledge firstprompt] ${msg}\n`);
56
+ }
57
+
58
+ function isEnabled() {
59
+ const raw = (process.env.AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT ?? '1').trim().toLowerCase();
60
+ return raw !== '0' && raw !== 'false' && raw !== 'off';
61
+ }
62
+
63
+ function tokenBudget() {
64
+ const raw = process.env.AGENT_KNOWLEDGE_FIRSTPROMPT_BUDGET ?? '600';
65
+ const n = Number.parseInt(raw, 10);
66
+ if (Number.isFinite(n) && n >= 100 && n <= 8000) return n;
67
+ return 600;
68
+ }
69
+
70
+ function maxHits() {
71
+ const raw = process.env.AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS ?? '4';
72
+ const n = Number.parseInt(raw, 10);
73
+ if (Number.isFinite(n) && n >= 1 && n <= 20) return n;
74
+ return 4;
75
+ }
76
+
77
+ function memoryDir() {
78
+ return process.env.KNOWLEDGE_MEMORY_DIR || path.join(homedir(), 'agent-knowledge');
79
+ }
80
+
81
+ function dataDir() {
82
+ if (process.env.KNOWLEDGE_DATA_DIR) return process.env.KNOWLEDGE_DATA_DIR;
83
+ if (process.platform === 'win32') {
84
+ return path.join(
85
+ process.env.APPDATA || path.join(homedir(), 'AppData', 'Roaming'),
86
+ 'knowledge',
87
+ );
88
+ }
89
+ return path.join(process.env.XDG_CONFIG_HOME || path.join(homedir(), '.config'), 'knowledge');
90
+ }
91
+
92
+ async function readStdin() {
93
+ return new Promise((resolveP) => {
94
+ let data = '';
95
+ if (process.stdin.isTTY) return resolveP('');
96
+ process.stdin.setEncoding('utf-8');
97
+ process.stdin.on('data', (chunk) => (data += chunk));
98
+ process.stdin.on('end', () => resolveP(data));
99
+ setTimeout(() => resolveP(data), 1500);
100
+ });
101
+ }
102
+
103
+ function markerPath(sessionId) {
104
+ return path.join(dataDir(), '.first-prompt-seen', sessionId);
105
+ }
106
+
107
+ function hasFired(sessionId) {
108
+ try {
109
+ return fs.existsSync(markerPath(sessionId));
110
+ } catch {
111
+ return false;
112
+ }
113
+ }
114
+
115
+ function recordFired(sessionId) {
116
+ try {
117
+ const file = markerPath(sessionId);
118
+ fs.mkdirSync(path.dirname(file), { recursive: true });
119
+ fs.writeFileSync(file, new Date().toISOString(), 'utf-8');
120
+ } catch (err) {
121
+ warn(`marker write failed: ${err?.message || err}`);
122
+ }
123
+ }
124
+
125
+ function isSkippablePrompt(prompt) {
126
+ const trimmed = (prompt ?? '').trim();
127
+ if (trimmed.length < 10) return true;
128
+ if (trimmed.startsWith('/')) return true;
129
+ if (trimmed.startsWith('!')) return true;
130
+ return false;
131
+ }
132
+
133
+ async function loadSearch() {
134
+ const distSearch = resolve(__dirname, '..', '..', 'dist', 'knowledge', 'search.js');
135
+ if (!fs.existsSync(distSearch)) {
136
+ warn(`dist not built: ${distSearch} (run \`npm run build\`)`);
137
+ return null;
138
+ }
139
+ try {
140
+ const mod = await import(`file://${distSearch.replace(/\\/g, '/')}`);
141
+ if (typeof mod.searchKnowledge !== 'function') {
142
+ warn('searchKnowledge not exported');
143
+ return null;
144
+ }
145
+ return mod.searchKnowledge;
146
+ } catch (err) {
147
+ warn(`import failed: ${err?.message || err}`);
148
+ return null;
149
+ }
150
+ }
151
+
152
+ function renderHits(hits, budgetChars) {
153
+ if (!hits || hits.length === 0) return null;
154
+
155
+ const header =
156
+ '## Knowledge — top hits for your first prompt\n' +
157
+ '\n' +
158
+ '_Injected automatically by agent-knowledge. Query these entries with `knowledge` (action=read, path=…) before deciding whether to issue a wider `knowledge_search`._\n' +
159
+ '\n';
160
+
161
+ let used = header.length;
162
+ const lines = [];
163
+ for (const hit of hits) {
164
+ const title = hit.entry?.title || hit.entry?.path || '(untitled)';
165
+ const pathStr = hit.entry?.path ?? '';
166
+ const score = typeof hit.score === 'number' ? hit.score.toFixed(2) : '?';
167
+ const excerpt = (hit.excerpt ?? '').replace(/\s+/g, ' ').trim().slice(0, 220);
168
+ const line = `- **${title}** (\`${pathStr}\`, score ${score}) — ${excerpt}`;
169
+ if (used + line.length + 1 > budgetChars) break;
170
+ lines.push(line);
171
+ used += line.length + 1;
172
+ }
173
+ if (lines.length === 0) return null;
174
+
175
+ return header + lines.join('\n') + '\n';
176
+ }
177
+
178
+ async function main() {
179
+ if (!isEnabled()) return emit(null);
180
+
181
+ const raw = await readStdin();
182
+ let payload = {};
183
+ if (raw) {
184
+ try {
185
+ payload = JSON.parse(raw);
186
+ } catch {
187
+ /* ignore — host may not pipe JSON */
188
+ }
189
+ }
190
+
191
+ const sessionId = payload.session_id || process.env.CLAUDE_SESSION_ID;
192
+ const prompt = payload.prompt;
193
+
194
+ if (!sessionId || typeof prompt !== 'string') return emit(null);
195
+ if (hasFired(sessionId)) return emit(null);
196
+
197
+ // IMPORTANT: don't burn the marker on skip-gates. If the user starts with
198
+ // `/clear`, `!bash`, or "hi", we want the NEXT real prompt to still get
199
+ // injection. Same for missing-dist / missing-memoryDir: those are setup
200
+ // states that might be fixed before the agent's next turn. Only burn the
201
+ // marker once a real search has actually run against a real KB.
202
+ if (isSkippablePrompt(prompt)) return emit(null);
203
+
204
+ const searchFn = await loadSearch();
205
+ if (!searchFn) return emit(null);
206
+
207
+ const dir = memoryDir();
208
+ if (!fs.existsSync(dir)) return emit(null);
209
+
210
+ let hits;
211
+ try {
212
+ hits = searchFn(dir, prompt.trim(), { maxResults: maxHits(), mmr: true });
213
+ } catch (err) {
214
+ warn(`search failed: ${err?.message || err}`);
215
+ recordFired(sessionId);
216
+ return emit(null);
217
+ }
218
+
219
+ recordFired(sessionId);
220
+
221
+ const budgetChars = tokenBudget() * 4;
222
+ const rendered = renderHits(hits, budgetChars);
223
+ if (!rendered) return emit(null);
224
+ emit(rendered);
225
+ }
226
+
227
+ main().catch((err) => {
228
+ warn(err?.message || String(err));
229
+ emit(null);
230
+ });