agent-knowledge 1.8.0 → 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 (50) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/CHANGELOG.md +58 -0
  3. package/README.md +1 -1
  4. package/agent-desk-plugin.json +1 -1
  5. package/dist/dashboard.d.ts.map +1 -1
  6. package/dist/dashboard.js +28 -1
  7. package/dist/dashboard.js.map +1 -1
  8. package/dist/knowledge/analyze.d.ts +18 -0
  9. package/dist/knowledge/analyze.d.ts.map +1 -1
  10. package/dist/knowledge/analyze.js +22 -0
  11. package/dist/knowledge/analyze.js.map +1 -1
  12. package/dist/knowledge/freshness.d.ts +99 -0
  13. package/dist/knowledge/freshness.d.ts.map +1 -0
  14. package/dist/knowledge/freshness.js +303 -0
  15. package/dist/knowledge/freshness.js.map +1 -0
  16. package/dist/knowledge/promote.d.ts.map +1 -1
  17. package/dist/knowledge/promote.js +32 -17
  18. package/dist/knowledge/promote.js.map +1 -1
  19. package/dist/knowledge/query-log.d.ts +88 -0
  20. package/dist/knowledge/query-log.d.ts.map +1 -0
  21. package/dist/knowledge/query-log.js +207 -0
  22. package/dist/knowledge/query-log.js.map +1 -0
  23. package/dist/knowledge/scoring.d.ts +16 -0
  24. package/dist/knowledge/scoring.d.ts.map +1 -1
  25. package/dist/knowledge/scoring.js +44 -0
  26. package/dist/knowledge/scoring.js.map +1 -1
  27. package/dist/knowledge/search.d.ts +24 -0
  28. package/dist/knowledge/search.d.ts.map +1 -1
  29. package/dist/knowledge/search.js +28 -0
  30. package/dist/knowledge/search.js.map +1 -1
  31. package/dist/knowledge/store.d.ts +6 -0
  32. package/dist/knowledge/store.d.ts.map +1 -1
  33. package/dist/knowledge/store.js +8 -0
  34. package/dist/knowledge/store.js.map +1 -1
  35. package/dist/server.d.ts +27 -0
  36. package/dist/server.d.ts.map +1 -1
  37. package/dist/server.js +47 -5
  38. package/dist/server.js.map +1 -1
  39. package/dist/tool-handlers.d.ts.map +1 -1
  40. package/dist/tool-handlers.js +94 -4
  41. package/dist/tool-handlers.js.map +1 -1
  42. package/dist/ui/app.js +271 -1
  43. package/dist/ui/render-knowledge.js +3 -3
  44. package/dist/ui/styles.css +209 -0
  45. package/dist/wakeup.d.ts +59 -14
  46. package/dist/wakeup.d.ts.map +1 -1
  47. package/dist/wakeup.js +406 -43
  48. package/dist/wakeup.js.map +1 -1
  49. package/docs/USER-MANUAL.md +59 -20
  50. package/package.json +1 -1
@@ -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
 
@@ -602,13 +621,16 @@ Analysis tools for knowledge base maintenance.
602
621
 
603
622
  **Parameters:**
604
623
 
605
- | Name | Type | Required | Description |
606
- | ------------- | ------ | -------- | -------------------------------------------------------------------------------- |
607
- | `action` | string | Yes | One of: `consolidate`, `reflect`, `god_nodes`, `bridges`, `gaps`, `brief` |
608
- | `category` | string | No | Scan only this category (omit for all) |
609
- | `threshold` | number | No | [consolidate] Similarity threshold 0-1 (default: 0.5) |
610
- | `max_entries` | number | No | [reflect/gaps] Max entries to include (default: 20 for reflect, 30 for gaps) |
611
- | `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) |
612
634
 
613
635
  **Action: consolidate**
614
636
 
@@ -670,6 +692,23 @@ No parameters.
670
692
 
671
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.
672
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
+
673
712
  ---
674
713
 
675
714
  ## 6. REST API Reference
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-knowledge",
3
- "version": "1.8.0",
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",