agent-knowledge 1.8.0 → 1.9.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 (71) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/CHANGELOG.md +95 -0
  3. package/README.md +67 -22
  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/embeddings/factory.js +1 -1
  9. package/dist/embeddings/factory.js.map +1 -1
  10. package/dist/embeddings/local.js +1 -1
  11. package/dist/embeddings/local.js.map +1 -1
  12. package/dist/embeddings/types.d.ts.map +1 -1
  13. package/dist/embeddings/types.js +8 -6
  14. package/dist/embeddings/types.js.map +1 -1
  15. package/dist/index.js +1 -1
  16. package/dist/index.js.map +1 -1
  17. package/dist/knowledge/analyze.d.ts +18 -0
  18. package/dist/knowledge/analyze.d.ts.map +1 -1
  19. package/dist/knowledge/analyze.js +22 -0
  20. package/dist/knowledge/analyze.js.map +1 -1
  21. package/dist/knowledge/freshness.d.ts +99 -0
  22. package/dist/knowledge/freshness.d.ts.map +1 -0
  23. package/dist/knowledge/freshness.js +303 -0
  24. package/dist/knowledge/freshness.js.map +1 -0
  25. package/dist/knowledge/promote.d.ts.map +1 -1
  26. package/dist/knowledge/promote.js +32 -17
  27. package/dist/knowledge/promote.js.map +1 -1
  28. package/dist/knowledge/query-log.d.ts +88 -0
  29. package/dist/knowledge/query-log.d.ts.map +1 -0
  30. package/dist/knowledge/query-log.js +207 -0
  31. package/dist/knowledge/query-log.js.map +1 -0
  32. package/dist/knowledge/scoring.d.ts +16 -0
  33. package/dist/knowledge/scoring.d.ts.map +1 -1
  34. package/dist/knowledge/scoring.js +44 -0
  35. package/dist/knowledge/scoring.js.map +1 -1
  36. package/dist/knowledge/search.d.ts +24 -0
  37. package/dist/knowledge/search.d.ts.map +1 -1
  38. package/dist/knowledge/search.js +28 -0
  39. package/dist/knowledge/search.js.map +1 -1
  40. package/dist/knowledge/store.d.ts +6 -0
  41. package/dist/knowledge/store.d.ts.map +1 -1
  42. package/dist/knowledge/store.js +8 -0
  43. package/dist/knowledge/store.js.map +1 -1
  44. package/dist/server.d.ts +27 -0
  45. package/dist/server.d.ts.map +1 -1
  46. package/dist/server.js +47 -5
  47. package/dist/server.js.map +1 -1
  48. package/dist/tool-handlers.d.ts.map +1 -1
  49. package/dist/tool-handlers.js +94 -4
  50. package/dist/tool-handlers.js.map +1 -1
  51. package/dist/types.d.ts.map +1 -1
  52. package/dist/types.js +11 -9
  53. package/dist/types.js.map +1 -1
  54. package/dist/ui/app.js +271 -1
  55. package/dist/ui/render-knowledge.js +3 -3
  56. package/dist/ui/styles.css +209 -0
  57. package/dist/wakeup.d.ts +59 -14
  58. package/dist/wakeup.d.ts.map +1 -1
  59. package/dist/wakeup.js +406 -43
  60. package/dist/wakeup.js.map +1 -1
  61. package/docs/ARCHITECTURE.md +15 -3
  62. package/docs/DASHBOARD.md +6 -0
  63. package/docs/SETUP.md +38 -38
  64. package/docs/USER-MANUAL.md +79 -40
  65. package/docs/hooks.md +7 -7
  66. package/package.json +1 -1
  67. package/scripts/hooks/first-prompt-inject.mjs +3 -3
  68. package/scripts/hooks/precompact-distill.mjs +1 -1
  69. package/scripts/hooks/precompact-flush.mjs +1 -1
  70. package/scripts/hooks/sessionend-distill.mjs +1 -1
  71. package/scripts/setup.js +1 -1
@@ -230,7 +230,19 @@ finalScore = baseRelevance * 0.5^(daysSinceLastAccess / 90) * maturityMultiplier
230
230
  | `established` | 5-19 | 1.0x |
231
231
  | `proven` | 20+ | 1.5x |
232
232
 
233
- Access count increments on `knowledge { action: "read" }`. Maturity transitions happen automatically when thresholds are crossed. Search results from `knowledge_search` apply the decay formula to blend relevance with freshness and confidence.
233
+ Access count increments on every path that actually feeds a knowledge entry into the agent's context: `knowledge { action: "read" }`, the session-start `wakeup` bundle (every entry packed in bumps access), and every `knowledge_search` hit on a knowledge entry. Sessions hits don't bump. Maturity transitions happen automatically when thresholds are crossed. Search results from `knowledge_search` apply the decay formula to blend relevance with freshness and confidence.
234
+
235
+ ### freshness.ts (v1.8.1)
236
+
237
+ Automatic staleness detector. For each entry, extracts the file paths it mentions and cross-references them against `filesModified` in recent session summaries; an entry whose mentioned file was modified AFTER the entry's body mtime is a candidate.
238
+
239
+ Precision layer: extracts identifiers the entry quotes (inline backticks + fenced blocks, strict-identifier shape, ≥3 chars) and checks whether they still appear in the touched files. Confidence multiplies by `0.3` when every named symbol is still present (entry's concrete claims likely hold), linearly scales for partial matches, keeps full weight when all named symbols are missing. Entries that quote no verifiable identifiers fall through with `symbol_evidence: "not_applicable"`.
240
+
241
+ Entries with `evergreen: true` are exempt from the whole pass.
242
+
243
+ ### query-log.ts (v1.8.1)
244
+
245
+ Lightweight `query_log` table inside `knowledge-scores.db`. Every `knowledge_search` call is logged with `{query, project, results_count, created_at}`; obvious-secret patterns (API keys, JWTs, bearer tokens, `.env`-style assignments) are scrubbed via `scrubContent` before insert. `knowledge_analyze(action: "search_gaps")` groups zero-result queries by token-Jaccard similarity (default `0.35`) and returns them ranked by frequency — the strongest signal for "what entries should I write next?".
234
246
 
235
247
  ## Memory Consolidation
236
248
 
@@ -295,9 +307,9 @@ The `edges` table has an additional `origin TEXT NOT NULL DEFAULT 'manual'` colu
295
307
 
296
308
  Sessions are read from multiple AI coding tools through two mechanisms:
297
309
 
298
- 1. **Direct parsing** -- Claude Code and Cursor sessions use JSONL files read directly by `parser.ts`. Claude Code sessions come from the primary data directory (`$KNOWLEDGE_DATA_DIR/projects/`). Cursor sessions are auto-discovered from `~/.cursor/projects/*/agent-transcripts/`.
310
+ 1. **Direct parsing** -- JSONL-based hosts (Claude Code, Cursor, Codex CLI, Continue.dev) are read directly by `parser.ts`. The adapter registry probes each known host root under `~/` (`.claude/projects/`, `.cursor/projects/`, `.codex/projects/`, `.aider/…`, `.continue/projects/`) and merges them into the session index. `AGENT_KNOWLEDGE_DATA_DIR` overrides the primary root; `AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS` adds more.
299
311
 
300
- 2. **Adapter dispatch** -- Other tools (OpenCode, Cline, Continue.dev, Aider) use the pluggable adapter system in `adapters/`. When `parseSessionFile()` receives a virtual descriptor (e.g. `opencode://session:abc`), it dispatches to the matching adapter.
312
+ 2. **Adapter dispatch** -- Tools with custom storage (OpenCode SQLite, Cline VS Code global storage, Aider markdown/JSONL hybrid) go through the pluggable adapter system in `adapters/`. When `parseSessionFile()` receives a virtual descriptor (e.g. `opencode://session:abc`), it dispatches to the matching adapter.
301
313
 
302
314
  ```
303
315
  parseSessionFile(path)
package/docs/DASHBOARD.md CHANGED
@@ -17,6 +17,8 @@ Card grid of knowledge entries. Each card shows:
17
17
 
18
18
  - Category badge with color: projects (blue), people (purple), decisions (orange), workflows (green), notes (yellow)
19
19
  - **Maturity badge**: candidate (gray), established (blue), proven (green) — based on access frequency
20
+ - **Pin badge** (Material Symbols `push_pin`) when the entry has `evergreen: true` frontmatter — these entries are exempt from decay in ranking and append-only under promotion.
21
+ - **Author chip** (muted, footer row) when the entry has `author: <string>` frontmatter — surfaces who wrote or owns it.
20
22
  - Title and tag pills
21
23
  - Last updated date
22
24
 
@@ -24,6 +26,10 @@ Card grid of knowledge entries. Each card shows:
24
26
 
25
27
  Category filter chips at the top: All, Projects, People, Decisions, Workflows, Notes. Search bar for filtering entries by title.
26
28
 
29
+ **Unused filter chip** (top-right of the header): shows `Unused (N)` where `N` is the count of entries past their per-category staleness threshold. Click to filter the grid to just those entries; click again to clear. Auto-hides when the count is zero.
30
+
31
+ **By Type access chart** (between the tabs and the grid): a horizontal bar per canonical category, row-normalized so each bar fills its own track. Green share = accessed within the per-category recent window, orange = unused. Volume comparison via the right-side `accessed/unused` counts. Per-category thresholds: `projects` 180/365d, `people` 365/730d, `decisions` 90/180d, `workflows` 60/120d, `notes` 30/90d.
32
+
27
33
  **Header action buttons:**
28
34
 
29
35
  - **Duplicates** — scans all entries for near-duplicates using TF-IDF similarity. Entries in duplicate clusters get a warning icon on their card. Opens a side panel showing clusters with pairwise similarity scores. Click any entry in a cluster to view it.
package/docs/SETUP.md CHANGED
@@ -75,7 +75,7 @@ This detects Claude Code, registers the MCP server in `~/.claude.json`, wires al
75
75
 
76
76
  ```bash
77
77
  claude mcp add agent-knowledge -s user \
78
- -e KNOWLEDGE_MEMORY_DIR="$HOME/agent-knowledge" \
78
+ -e AGENT_KNOWLEDGE_MEMORY_DIR="$HOME/agent-knowledge" \
79
79
  -- node /path/to/agent-knowledge/dist/index.js
80
80
  ```
81
81
 
@@ -110,8 +110,8 @@ claude mcp list
110
110
  "type": "local",
111
111
  "command": ["node", "/absolute/path/to/agent-knowledge/dist/index.js"],
112
112
  "environment": {
113
- "KNOWLEDGE_MEMORY_DIR": "/home/you/agent-knowledge",
114
- "KNOWLEDGE_PORT": "3423"
113
+ "AGENT_KNOWLEDGE_MEMORY_DIR": "/home/you/agent-knowledge",
114
+ "AGENT_KNOWLEDGE_PORT": "3423"
115
115
  }
116
116
  }
117
117
  }
@@ -129,8 +129,8 @@ claude mcp list
129
129
  "command": "node",
130
130
  "args": ["/absolute/path/to/agent-knowledge/dist/index.js"],
131
131
  "env": {
132
- "KNOWLEDGE_MEMORY_DIR": "/home/you/agent-knowledge",
133
- "KNOWLEDGE_PORT": "3423"
132
+ "AGENT_KNOWLEDGE_MEMORY_DIR": "/home/you/agent-knowledge",
133
+ "AGENT_KNOWLEDGE_PORT": "3423"
134
134
  }
135
135
  }
136
136
  }
@@ -148,8 +148,8 @@ claude mcp list
148
148
  "command": "node",
149
149
  "args": ["/absolute/path/to/agent-knowledge/dist/index.js"],
150
150
  "env": {
151
- "KNOWLEDGE_MEMORY_DIR": "/home/you/agent-knowledge",
152
- "KNOWLEDGE_PORT": "3423"
151
+ "AGENT_KNOWLEDGE_MEMORY_DIR": "/home/you/agent-knowledge",
152
+ "AGENT_KNOWLEDGE_PORT": "3423"
153
153
  }
154
154
  }
155
155
  }
@@ -419,34 +419,34 @@ Architecture notes, deployment info, etc.
419
419
 
420
420
  ## Environment Variables
421
421
 
422
- | Variable | Default | Description |
423
- | --------------------------------------------------- | ------------------- | -------------------------------------------------------------- |
424
- | `KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Path to git-synced knowledge base |
425
- | `KNOWLEDGE_DATA_DIR` | `~/.claude` | Primary session data directory (Claude Code JSONL) |
426
- | `EXTRA_SESSION_ROOTS` | -- | Additional session directories, comma-separated |
427
- | `OPENCODE_DATA_DIR` | (platform default) | Override OpenCode data dir (default `~/.local/share/opencode`) |
428
- | `KNOWLEDGE_PORT` | `3423` | Dashboard HTTP/WebSocket port |
429
- | `KNOWLEDGE_EMBEDDING_PROVIDER` | `local` | Embedding provider (local, openai, claude, gemini) |
430
- | `KNOWLEDGE_EMBEDDING_ALPHA` | `0.5` | Blend weight for semantic vs TF-IDF search (0-1) |
431
- | `KNOWLEDGE_EMBEDDING_IDLE_TIMEOUT` | — | Idle timeout for embedding worker (ms) |
432
- | `KNOWLEDGE_EMBEDDING_THREADS` | — | Number of ONNX threads for local embeddings |
433
- | `KNOWLEDGE_EMBEDDING_MODEL` | — | Model name for embedding provider |
434
- | `KNOWLEDGE_GIT_URL` | — | Remote git URL for knowledge base sync |
435
- | `KNOWLEDGE_AUTO_DISTILL` | — | Enable auto-distillation of sessions (true/false) |
436
- | `KNOWLEDGE_OPENAI_API_KEY` / `OPENAI_API_KEY` | — | API key for OpenAI embeddings |
437
- | `KNOWLEDGE_ANTHROPIC_API_KEY` / `ANTHROPIC_API_KEY` | — | API key for Claude/Voyage embeddings |
438
- | `KNOWLEDGE_GEMINI_API_KEY` / `GEMINI_API_KEY` | — | API key for Gemini embeddings |
422
+ | Variable | Default | Description |
423
+ | --------------------------------------------------------- | ------------------- | ---------------------------------------------------------------- |
424
+ | `AGENT_KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Path to git-synced knowledge base |
425
+ | `AGENT_KNOWLEDGE_DATA_DIR` | (platform config) | Override primary host data root (adapters auto-detect otherwise) |
426
+ | `AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS` | -- | Additional session directories, comma-separated |
427
+ | `OPENCODE_DATA_DIR` | (platform default) | Override OpenCode data dir (default `~/.local/share/opencode`) |
428
+ | `AGENT_KNOWLEDGE_PORT` | `3423` | Dashboard HTTP/WebSocket port |
429
+ | `AGENT_KNOWLEDGE_EMBEDDING_PROVIDER` | `local` | Embedding provider (local, openai, claude, gemini) |
430
+ | `AGENT_KNOWLEDGE_EMBEDDING_ALPHA` | `0.5` | Blend weight for semantic vs TF-IDF search (0-1) |
431
+ | `AGENT_KNOWLEDGE_EMBEDDING_IDLE_TIMEOUT` | — | Idle timeout for embedding worker (ms) |
432
+ | `AGENT_KNOWLEDGE_EMBEDDING_THREADS` | — | Number of ONNX threads for local embeddings |
433
+ | `AGENT_KNOWLEDGE_EMBEDDING_MODEL` | — | Model name for embedding provider |
434
+ | `AGENT_KNOWLEDGE_GIT_URL` | — | Remote git URL for knowledge base sync |
435
+ | `AGENT_KNOWLEDGE_AUTO_DISTILL` | — | Enable auto-distillation of sessions (true/false) |
436
+ | `AGENT_KNOWLEDGE_OPENAI_API_KEY` / `OPENAI_API_KEY` | — | API key for OpenAI embeddings |
437
+ | `AGENT_KNOWLEDGE_ANTHROPIC_API_KEY` / `ANTHROPIC_API_KEY` | — | API key for Claude/Voyage embeddings |
438
+ | `AGENT_KNOWLEDGE_GEMINI_API_KEY` / `GEMINI_API_KEY` | — | API key for Gemini embeddings |
439
439
 
440
440
  Set in your shell profile or pass via MCP config:
441
441
 
442
442
  ```bash
443
- export KNOWLEDGE_MEMORY_DIR="$HOME/agent-knowledge"
443
+ export AGENT_KNOWLEDGE_MEMORY_DIR="$HOME/agent-knowledge"
444
444
  ```
445
445
 
446
446
  On Windows (PowerShell):
447
447
 
448
448
  ```powershell
449
- $env:KNOWLEDGE_MEMORY_DIR = "$env:USERPROFILE\agent-knowledge"
449
+ $env:AGENT_KNOWLEDGE_MEMORY_DIR = "$env:USERPROFILE\agent-knowledge"
450
450
  ```
451
451
 
452
452
  ---
@@ -481,21 +481,21 @@ cd ~/agent-knowledge && git pull && git push # Should work without prompts
481
481
 
482
482
  agent-knowledge auto-discovers sessions from all major AI coding assistants. If a tool is installed on your machine, its sessions appear automatically in search results and the dashboard Sessions tab.
483
483
 
484
- | Tool | Format | Auto-detected path | Override |
485
- | ---------------- | -------------- | --------------------------------------------------------------- | --------------------- |
486
- | **Claude Code** | JSONL | `$KNOWLEDGE_DATA_DIR/projects/` | `KNOWLEDGE_DATA_DIR` |
487
- | **Cursor** | JSONL | `~/.cursor/projects/*/agent-transcripts/` | `EXTRA_SESSION_ROOTS` |
488
- | **OpenCode** | SQLite | `~/.local/share/opencode/opencode.db` | `OPENCODE_DATA_DIR` |
489
- | **Cline** | JSON | VS Code globalStorage `saoudrizwan.claude-dev/tasks/` | -- |
490
- | **Continue.dev** | JSON | `~/.continue/sessions/` | -- |
491
- | **Aider** | Markdown/JSONL | `.aider.chat.history.md` / `.aider.llm.history` in project dirs | -- |
484
+ | Tool | Format | Auto-detected path | Override |
485
+ | ---------------- | -------------- | --------------------------------------------------------------- | ------------------------------------- |
486
+ | **Claude Code** | JSONL | `$AGENT_KNOWLEDGE_DATA_DIR/projects/` | `AGENT_KNOWLEDGE_DATA_DIR` |
487
+ | **Cursor** | JSONL | `~/.cursor/projects/*/agent-transcripts/` | `AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS` |
488
+ | **OpenCode** | SQLite | `~/.local/share/opencode/opencode.db` | `OPENCODE_DATA_DIR` |
489
+ | **Cline** | JSON | VS Code globalStorage `saoudrizwan.claude-dev/tasks/` | -- |
490
+ | **Continue.dev** | JSON | `~/.continue/sessions/` | -- |
491
+ | **Aider** | Markdown/JSONL | `.aider.chat.history.md` / `.aider.llm.history` in project dirs | -- |
492
492
 
493
493
  ### Adding extra session directories
494
494
 
495
- Use the `EXTRA_SESSION_ROOTS` environment variable to add session directories that are not auto-detected:
495
+ Use the `AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS` environment variable to add session directories that are not auto-detected:
496
496
 
497
497
  ```bash
498
- export EXTRA_SESSION_ROOTS="/path/to/custom/sessions,/another/path"
498
+ export AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS="/path/to/custom/sessions,/another/path"
499
499
  ```
500
500
 
501
501
  Each path is scanned for JSONL files or Cursor-style `agent-transcripts/` subdirectories.
@@ -518,7 +518,7 @@ netstat -ano | findstr :3423 # Windows
518
518
  lsof -i :3423 # Linux/macOS
519
519
 
520
520
  # Use a different port
521
- export KNOWLEDGE_PORT=3424
521
+ export AGENT_KNOWLEDGE_PORT=3424
522
522
  ```
523
523
 
524
524
  ### Git authentication failures
@@ -563,7 +563,7 @@ ls ~/.continue/sessions/
563
563
  ls ~/projects/*/.aider.chat.history.md
564
564
  ```
565
565
 
566
- If your session data is in a non-standard location, use `EXTRA_SESSION_ROOTS` to point to it.
566
+ If your session data is in a non-standard location, use `AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS` to point to it.
567
567
 
568
568
  ## Client Comparison
569
569
 
@@ -95,14 +95,14 @@ npx agent-knowledge
95
95
 
96
96
  ### Environment Variables
97
97
 
98
- | Variable | Default | Description |
99
- | ------------------------ | ------------------- | ---------------------------------------------- |
100
- | `KNOWLEDGE_PORT` | `3423` | Dashboard HTTP/WebSocket port |
101
- | `KNOWLEDGE_DATA_DIR` | `~/.claude` | Base directory for Claude Code session data |
102
- | `KNOWLEDGE_GIT_URL` | (none) | Git remote URL for knowledge base sync |
103
- | `KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Local knowledge base directory |
104
- | `KNOWLEDGE_AUTO_DISTILL` | `true` | Enable/disable session auto-distillation |
105
- | `EXTRA_SESSION_ROOTS` | (none) | Comma-separated additional session directories |
98
+ | Variable | Default | Description |
99
+ | ------------------------------------- | ------------------- | ----------------------------------------------- |
100
+ | `AGENT_KNOWLEDGE_PORT` | `3423` | Dashboard HTTP/WebSocket port |
101
+ | `AGENT_KNOWLEDGE_DATA_DIR` | (platform config) | Override primary host data root (auto-detected) |
102
+ | `AGENT_KNOWLEDGE_GIT_URL` | (none) | Git remote URL for knowledge base sync |
103
+ | `AGENT_KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Local knowledge base directory |
104
+ | `AGENT_KNOWLEDGE_AUTO_DISTILL` | `true` | Enable/disable session auto-distillation |
105
+ | `AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS` | (none) | Comma-separated additional session directories |
106
106
 
107
107
  ### Claude Code Setup
108
108
 
@@ -147,7 +147,7 @@ knowledge_admin with action "config", auto_distill false
147
147
 
148
148
  ### Accessing the Dashboard
149
149
 
150
- The dashboard is available at **http://localhost:3423** (or the port configured via `KNOWLEDGE_PORT`).
150
+ The dashboard is available at **http://localhost:3423** (or the port configured via `AGENT_KNOWLEDGE_PORT`).
151
151
 
152
152
  ### Knowledge Tab
153
153
 
@@ -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
@@ -862,13 +901,13 @@ On server startup (when `auto_distill` is enabled), past sessions are automatica
862
901
 
863
902
  Sessions are auto-discovered from installed AI coding tools:
864
903
 
865
- | Tool | Location |
866
- | ----------- | ------------------------------------------------- |
867
- | Claude Code | `$KNOWLEDGE_DATA_DIR/projects/` (JSONL files) |
868
- | Cursor | `~/.cursor/projects/*/agent-transcripts/` (JSONL) |
869
- | OpenCode | `~/.local/share/opencode/opencode.db` (SQLite) |
904
+ | Tool | Location |
905
+ | ----------- | --------------------------------------------------- |
906
+ | Claude Code | `$AGENT_KNOWLEDGE_DATA_DIR/projects/` (JSONL files) |
907
+ | Cursor | `~/.cursor/projects/*/agent-transcripts/` (JSONL) |
908
+ | OpenCode | `~/.local/share/opencode/opencode.db` (SQLite) |
870
909
 
871
- Additional roots can be added via `EXTRA_SESSION_ROOTS` (comma-separated paths).
910
+ Additional roots can be added via `AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS` (comma-separated paths).
872
911
 
873
912
  ### Search Modes
874
913
 
@@ -917,14 +956,14 @@ If no provider is available, search falls back to pure TF-IDF.
917
956
 
918
957
  **Solutions:**
919
958
 
920
- 1. Set `KNOWLEDGE_PORT=3424` in the MCP config env.
959
+ 1. Set `AGENT_KNOWLEDGE_PORT=3424` in the MCP config env.
921
960
  2. Multiple MCP instances share the same database. Only one serves the dashboard.
922
961
 
923
962
  ### Search Returns No Results
924
963
 
925
964
  **Causes and solutions:**
926
965
 
927
- - **No sessions found**: Check that `KNOWLEDGE_DATA_DIR` points to the correct directory. Verify session files exist.
966
+ - **No sessions found**: Check that `AGENT_KNOWLEDGE_DATA_DIR` points to the correct directory. Verify session files exist.
928
967
  - **Embeddings not available**: Semantic search requires an API key. Check the embedding provider configuration.
929
968
  - **Index not built**: Background indexing runs 5 seconds after startup. Wait for it to complete. Check stderr for `[knowledge] Background index` messages.
930
969
 
@@ -956,7 +995,7 @@ If no provider is available, search falls back to pure TF-IDF.
956
995
  **Solutions:**
957
996
 
958
997
  - The default directory is `~/agent-knowledge/`. Create it manually or let the git clone create it.
959
- - Override via `KNOWLEDGE_MEMORY_DIR` or `knowledge_admin(action: "config", memory_dir: "/path")`.
998
+ - Override via `AGENT_KNOWLEDGE_MEMORY_DIR` or `knowledge_admin(action: "config", memory_dir: "/path")`.
960
999
 
961
1000
  ---
962
1001
 
@@ -968,7 +1007,7 @@ Yes. agent-knowledge is a standard MCP server. It also auto-discovers sessions f
968
1007
 
969
1008
  ### Where are knowledge entries stored?
970
1009
 
971
- In `~/agent-knowledge/` by default (configurable via `KNOWLEDGE_MEMORY_DIR`). Entries are plain Markdown files with YAML frontmatter, organized in category subdirectories.
1010
+ In `~/agent-knowledge/` by default (configurable via `AGENT_KNOWLEDGE_MEMORY_DIR`). Entries are plain Markdown files with YAML frontmatter, organized in category subdirectories.
972
1011
 
973
1012
  ### How does git sync work?
974
1013
 
@@ -1001,4 +1040,4 @@ The distillation process applies regex patterns to detect and remove common secr
1001
1040
 
1002
1041
  ### Can I disable auto-distillation?
1003
1042
 
1004
- Yes. Set `KNOWLEDGE_AUTO_DISTILL=false` as an environment variable, or use `knowledge_admin(action: "config", auto_distill: false)`.
1043
+ Yes. Set `AGENT_KNOWLEDGE_AUTO_DISTILL=false` as an environment variable, or use `knowledge_admin(action: "config", auto_distill: false)`.
package/docs/hooks.md CHANGED
@@ -61,7 +61,7 @@ so the user's next real question still gets injection.
61
61
  | `AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT` | `1` | Set `0` / `false` / `off` to disable |
62
62
  | `AGENT_KNOWLEDGE_FIRSTPROMPT_BUDGET` | `600` | Max tokens (chars/4 estimate), clamped to `[100, 8000]` |
63
63
  | `AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS` | `4` | Max rendered entries, clamped to `[1, 20]` |
64
- | `KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Knowledge base to search |
64
+ | `AGENT_KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Knowledge base to search |
65
65
 
66
66
  ## precompact-flush.mjs
67
67
 
@@ -79,7 +79,7 @@ Called right before the host compacts the transcript. Two jobs:
79
79
 
80
80
  | Variable | Default | Description |
81
81
  | ---------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------- |
82
- | `KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Where rich summaries are written |
82
+ | `AGENT_KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Where rich summaries are written |
83
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. |
84
84
 
85
85
  ## precompact-distill.mjs
@@ -87,22 +87,22 @@ Called right before the host compacts the transcript. Two jobs:
87
87
  A simpler heuristic companion to `precompact-flush.mjs`. Reads the last
88
88
  ~200 KB of the transcript JSONL, extracts the last 10 user prompts, and
89
89
  writes them to
90
- `~/claude-memory/projects/precompact-<slug>-<session>.md`. This one does
90
+ `~/agent-knowledge/projects/precompact-<slug>-<session>.md`. This one does
91
91
  not require the library to be built, so it still works when `dist/` is
92
92
  missing. Running both is fine — they target different files.
93
93
 
94
94
  ### Environment variables
95
95
 
96
- | Variable | Default | Description |
97
- | ---------------------- | ----------------- | ------------------------------------------------- |
98
- | `KNOWLEDGE_MEMORY_DIR` | `~/claude-memory` | Where the snapshot is written (`<dir>/projects/`) |
96
+ | Variable | Default | Description |
97
+ | ---------------------------- | ------------------- | ------------------------------------------------- |
98
+ | `AGENT_KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Where the snapshot is written (`<dir>/projects/`) |
99
99
 
100
100
  ## sessionend-distill.mjs
101
101
 
102
102
  On `SessionEnd`, walks the whole transcript JSONL, counts user / assistant
103
103
  turns and `tool_use` blocks, collects the first 20 user prompts, and writes
104
104
  a markdown summary to
105
- `~/claude-memory/projects/session-<slug>-<session>.md`. Gives
105
+ `~/agent-knowledge/projects/session-<slug>-<session>.md`. Gives
106
106
  agent-knowledge a breadcrumb for later session search/recall.
107
107
 
108
108
  ## Manual configuration
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-knowledge",
3
- "version": "1.8.0",
3
+ "version": "1.9.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",
@@ -23,7 +23,7 @@
23
23
  // AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT (default "1") — set "0" to disable
24
24
  // AGENT_KNOWLEDGE_FIRSTPROMPT_BUDGET (default "600") — max chars/4 tokens
25
25
  // AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS (default "4") — cap on rendered hits
26
- // KNOWLEDGE_MEMORY_DIR — resolves memory dir (same as core)
26
+ // AGENT_KNOWLEDGE_MEMORY_DIR — resolves memory dir (same as core)
27
27
  //
28
28
  // Fail-open: every error path prints `{}` so the host never blocks on this
29
29
  // hook. Log-only stderr for diagnostics.
@@ -75,11 +75,11 @@ function maxHits() {
75
75
  }
76
76
 
77
77
  function memoryDir() {
78
- return process.env.KNOWLEDGE_MEMORY_DIR || path.join(homedir(), 'agent-knowledge');
78
+ return process.env.AGENT_KNOWLEDGE_MEMORY_DIR || path.join(homedir(), 'agent-knowledge');
79
79
  }
80
80
 
81
81
  function dataDir() {
82
- if (process.env.KNOWLEDGE_DATA_DIR) return process.env.KNOWLEDGE_DATA_DIR;
82
+ if (process.env.AGENT_KNOWLEDGE_DATA_DIR) return process.env.AGENT_KNOWLEDGE_DATA_DIR;
83
83
  if (process.platform === 'win32') {
84
84
  return path.join(
85
85
  process.env.APPDATA || path.join(homedir(), 'AppData', 'Roaming'),
@@ -23,7 +23,7 @@ process.on('uncaughtException', (err) => {
23
23
  process.exit(0);
24
24
  });
25
25
 
26
- const MEMORY_DIR = process.env.KNOWLEDGE_MEMORY_DIR || join(homedir(), 'claude-memory');
26
+ const MEMORY_DIR = process.env.AGENT_KNOWLEDGE_MEMORY_DIR || join(homedir(), 'agent-knowledge');
27
27
 
28
28
  async function main() {
29
29
  let input = '';
@@ -88,7 +88,7 @@ function slugify(input) {
88
88
  }
89
89
 
90
90
  function memoryDir() {
91
- return process.env.KNOWLEDGE_MEMORY_DIR || join(homedir(), 'agent-knowledge');
91
+ return process.env.AGENT_KNOWLEDGE_MEMORY_DIR || join(homedir(), 'agent-knowledge');
92
92
  }
93
93
 
94
94
  async function dumpSummaryToDisk({ sessionId, event, cwd, projectSlug }) {
@@ -21,7 +21,7 @@ process.on('uncaughtException', (err) => {
21
21
  process.exit(0);
22
22
  });
23
23
 
24
- const MEMORY_DIR = process.env.KNOWLEDGE_MEMORY_DIR || join(homedir(), 'claude-memory');
24
+ const MEMORY_DIR = process.env.AGENT_KNOWLEDGE_MEMORY_DIR || join(homedir(), 'agent-knowledge');
25
25
 
26
26
  async function main() {
27
27
  let input = '';
package/scripts/setup.js CHANGED
@@ -211,7 +211,7 @@ Restart Claude Code to load the new MCP server. Every session will now:
211
211
  - Dump a final session summary on exit (sessionend-distill)
212
212
 
213
213
  Dashboard: http://localhost:3423 (auto-starts on first MCP connection)
214
- Knowledge base: ~/claude-memory/ (configurable via KNOWLEDGE_MEMORY_DIR)
214
+ Knowledge base: ~/agent-knowledge/ (configurable via AGENT_KNOWLEDGE_MEMORY_DIR)
215
215
 
216
216
  See docs/hooks.md for details and docs/SETUP.md for manual configuration.
217
217
  `);