agent-knowledge 1.7.3 → 1.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/.mcp.json +1 -1
- package/CHANGELOG.md +43 -0
- package/README.md +43 -18
- package/agent-desk-plugin.json +1 -1
- package/dist/knowledge/promote.d.ts +145 -0
- package/dist/knowledge/promote.d.ts.map +1 -0
- package/dist/knowledge/promote.js +517 -0
- package/dist/knowledge/promote.js.map +1 -0
- package/dist/knowledge/scoring.d.ts +6 -2
- package/dist/knowledge/scoring.d.ts.map +1 -1
- package/dist/knowledge/scoring.js +7 -3
- package/dist/knowledge/scoring.js.map +1 -1
- package/dist/knowledge/search.d.ts +32 -5
- package/dist/knowledge/search.d.ts.map +1 -1
- package/dist/knowledge/search.js +60 -10
- package/dist/knowledge/search.js.map +1 -1
- package/dist/knowledge/store.d.ts +6 -0
- package/dist/knowledge/store.d.ts.map +1 -1
- package/dist/knowledge/store.js +10 -0
- package/dist/knowledge/store.js.map +1 -1
- package/dist/search/mmr.d.ts +54 -0
- package/dist/search/mmr.d.ts.map +1 -0
- package/dist/search/mmr.js +138 -0
- package/dist/search/mmr.js.map +1 -0
- package/dist/server.d.ts +307 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +336 -301
- package/dist/server.js.map +1 -1
- package/dist/sessions/indexer.d.ts.map +1 -1
- package/dist/sessions/indexer.js +13 -11
- package/dist/sessions/indexer.js.map +1 -1
- package/dist/tool-handlers.d.ts +10 -3
- package/dist/tool-handlers.d.ts.map +1 -1
- package/dist/tool-handlers.js +56 -17
- package/dist/tool-handlers.js.map +1 -1
- package/docs/ARCHITECTURE.md +31 -6
- package/docs/SETUP.md +20 -8
- package/docs/USER-MANUAL.md +146 -39
- package/docs/hooks.md +81 -21
- package/package.json +4 -1
- package/scripts/hooks/first-prompt-inject.mjs +230 -0
- package/scripts/hooks/precompact-flush.mjs +89 -60
- package/scripts/hooks/session-start.js +73 -9
package/docs/USER-MANUAL.md
CHANGED
|
@@ -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
|
|
303
|
-
|
|
|
304
|
-
| `query`
|
|
305
|
-
| `scope`
|
|
306
|
-
| `project`
|
|
307
|
-
| `role`
|
|
308
|
-
| `max_results`
|
|
309
|
-
| `ranked`
|
|
310
|
-
| `semantic`
|
|
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
|
|
403
|
+
Admin operations for configuration, index stats, embedding management, and the v1.8 scored promoter.
|
|
393
404
|
|
|
394
405
|
**Parameters:**
|
|
395
406
|
|
|
396
|
-
| Name
|
|
397
|
-
|
|
|
398
|
-
| `action`
|
|
399
|
-
| `git_url`
|
|
400
|
-
| `memory_dir`
|
|
401
|
-
| `auto_distill`
|
|
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-
|
|
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
|
|
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
|
|
447
|
-
|
|
|
448
|
-
| `action`
|
|
449
|
-
| `source`
|
|
450
|
-
| `target`
|
|
451
|
-
| `entry`
|
|
452
|
-
| `rel_type`
|
|
453
|
-
| `strength`
|
|
454
|
-
| `depth`
|
|
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
|
|
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.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
|
+
});
|