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.
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +95 -0
- package/README.md +67 -22
- package/agent-desk-plugin.json +1 -1
- package/dist/dashboard.d.ts.map +1 -1
- package/dist/dashboard.js +28 -1
- package/dist/dashboard.js.map +1 -1
- package/dist/embeddings/factory.js +1 -1
- package/dist/embeddings/factory.js.map +1 -1
- package/dist/embeddings/local.js +1 -1
- package/dist/embeddings/local.js.map +1 -1
- package/dist/embeddings/types.d.ts.map +1 -1
- package/dist/embeddings/types.js +8 -6
- package/dist/embeddings/types.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/knowledge/analyze.d.ts +18 -0
- package/dist/knowledge/analyze.d.ts.map +1 -1
- package/dist/knowledge/analyze.js +22 -0
- package/dist/knowledge/analyze.js.map +1 -1
- package/dist/knowledge/freshness.d.ts +99 -0
- package/dist/knowledge/freshness.d.ts.map +1 -0
- package/dist/knowledge/freshness.js +303 -0
- package/dist/knowledge/freshness.js.map +1 -0
- package/dist/knowledge/promote.d.ts.map +1 -1
- package/dist/knowledge/promote.js +32 -17
- package/dist/knowledge/promote.js.map +1 -1
- package/dist/knowledge/query-log.d.ts +88 -0
- package/dist/knowledge/query-log.d.ts.map +1 -0
- package/dist/knowledge/query-log.js +207 -0
- package/dist/knowledge/query-log.js.map +1 -0
- package/dist/knowledge/scoring.d.ts +16 -0
- package/dist/knowledge/scoring.d.ts.map +1 -1
- package/dist/knowledge/scoring.js +44 -0
- package/dist/knowledge/scoring.js.map +1 -1
- package/dist/knowledge/search.d.ts +24 -0
- package/dist/knowledge/search.d.ts.map +1 -1
- package/dist/knowledge/search.js +28 -0
- 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 +8 -0
- package/dist/knowledge/store.js.map +1 -1
- package/dist/server.d.ts +27 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +47 -5
- package/dist/server.js.map +1 -1
- package/dist/tool-handlers.d.ts.map +1 -1
- package/dist/tool-handlers.js +94 -4
- package/dist/tool-handlers.js.map +1 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +11 -9
- package/dist/types.js.map +1 -1
- package/dist/ui/app.js +271 -1
- package/dist/ui/render-knowledge.js +3 -3
- package/dist/ui/styles.css +209 -0
- package/dist/wakeup.d.ts +59 -14
- package/dist/wakeup.d.ts.map +1 -1
- package/dist/wakeup.js +406 -43
- package/dist/wakeup.js.map +1 -1
- package/docs/ARCHITECTURE.md +15 -3
- package/docs/DASHBOARD.md +6 -0
- package/docs/SETUP.md +38 -38
- package/docs/USER-MANUAL.md +79 -40
- package/docs/hooks.md +7 -7
- package/package.json +1 -1
- package/scripts/hooks/first-prompt-inject.mjs +3 -3
- package/scripts/hooks/precompact-distill.mjs +1 -1
- package/scripts/hooks/precompact-flush.mjs +1 -1
- package/scripts/hooks/sessionend-distill.mjs +1 -1
- package/scripts/setup.js +1 -1
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -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" }
|
|
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
|
|
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** --
|
|
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
|
|
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
|
-
"
|
|
114
|
-
"
|
|
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
|
-
"
|
|
133
|
-
"
|
|
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
|
-
"
|
|
152
|
-
"
|
|
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
|
|
423
|
-
|
|
|
424
|
-
| `
|
|
425
|
-
| `
|
|
426
|
-
| `
|
|
427
|
-
| `OPENCODE_DATA_DIR`
|
|
428
|
-
| `
|
|
429
|
-
| `
|
|
430
|
-
| `
|
|
431
|
-
| `
|
|
432
|
-
| `
|
|
433
|
-
| `
|
|
434
|
-
| `
|
|
435
|
-
| `
|
|
436
|
-
| `
|
|
437
|
-
| `
|
|
438
|
-
| `
|
|
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
|
|
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:
|
|
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 | `$
|
|
487
|
-
| **Cursor** | JSONL | `~/.cursor/projects/*/agent-transcripts/` | `
|
|
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 `
|
|
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
|
|
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
|
|
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 `
|
|
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
|
|
package/docs/USER-MANUAL.md
CHANGED
|
@@ -95,14 +95,14 @@ npx agent-knowledge
|
|
|
95
95
|
|
|
96
96
|
### Environment Variables
|
|
97
97
|
|
|
98
|
-
| Variable
|
|
99
|
-
|
|
|
100
|
-
| `
|
|
101
|
-
| `
|
|
102
|
-
| `
|
|
103
|
-
| `
|
|
104
|
-
| `
|
|
105
|
-
| `
|
|
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 `
|
|
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
|
|
216
|
-
|
|
|
217
|
-
| `action`
|
|
218
|
-
| `category`
|
|
219
|
-
| `tag`
|
|
220
|
-
| `path`
|
|
221
|
-
| `filename`
|
|
222
|
-
| `content`
|
|
223
|
-
| `token_budget`
|
|
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
|
|
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
|
-
|
|
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 }
|
|
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`
|
|
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
|
|
606
|
-
|
|
|
607
|
-
| `action`
|
|
608
|
-
| `category`
|
|
609
|
-
| `threshold`
|
|
610
|
-
| `max_entries`
|
|
611
|
-
| `top_n`
|
|
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 | `$
|
|
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 `
|
|
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 `
|
|
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 `
|
|
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 `
|
|
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 `
|
|
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 `
|
|
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
|
-
| `
|
|
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
|
-
| `
|
|
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
|
-
`~/
|
|
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
|
|
97
|
-
|
|
|
98
|
-
| `
|
|
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
|
-
`~/
|
|
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.
|
|
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
|
-
//
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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: ~/
|
|
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
|
`);
|