agent-knowledge 1.1.6 → 1.3.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 (81) hide show
  1. package/CHANGELOG.md +115 -5
  2. package/README.md +86 -24
  3. package/dist/dashboard.d.ts +1 -0
  4. package/dist/dashboard.d.ts.map +1 -1
  5. package/dist/dashboard.js +145 -19
  6. package/dist/dashboard.js.map +1 -1
  7. package/dist/embeddings/anthropic.d.ts.map +1 -1
  8. package/dist/embeddings/anthropic.js +2 -1
  9. package/dist/embeddings/anthropic.js.map +1 -1
  10. package/dist/embeddings/gemini.d.ts.map +1 -1
  11. package/dist/embeddings/gemini.js +2 -1
  12. package/dist/embeddings/gemini.js.map +1 -1
  13. package/dist/embeddings/local.d.ts.map +1 -1
  14. package/dist/embeddings/local.js +3 -0
  15. package/dist/embeddings/local.js.map +1 -1
  16. package/dist/knowledge/consolidate.d.ts +46 -0
  17. package/dist/knowledge/consolidate.d.ts.map +1 -0
  18. package/dist/knowledge/consolidate.js +164 -0
  19. package/dist/knowledge/consolidate.js.map +1 -0
  20. package/dist/knowledge/distill.d.ts.map +1 -1
  21. package/dist/knowledge/distill.js +4 -2
  22. package/dist/knowledge/distill.js.map +1 -1
  23. package/dist/knowledge/graph.d.ts +64 -0
  24. package/dist/knowledge/graph.d.ts.map +1 -0
  25. package/dist/knowledge/graph.js +214 -0
  26. package/dist/knowledge/graph.js.map +1 -0
  27. package/dist/knowledge/reflect.d.ts +33 -0
  28. package/dist/knowledge/reflect.d.ts.map +1 -0
  29. package/dist/knowledge/reflect.js +115 -0
  30. package/dist/knowledge/reflect.js.map +1 -0
  31. package/dist/knowledge/scoring.d.ts +57 -0
  32. package/dist/knowledge/scoring.d.ts.map +1 -0
  33. package/dist/knowledge/scoring.js +194 -0
  34. package/dist/knowledge/scoring.js.map +1 -0
  35. package/dist/knowledge/search.d.ts.map +1 -1
  36. package/dist/knowledge/search.js +15 -2
  37. package/dist/knowledge/search.js.map +1 -1
  38. package/dist/knowledge/store.d.ts.map +1 -1
  39. package/dist/knowledge/store.js +4 -3
  40. package/dist/knowledge/store.js.map +1 -1
  41. package/dist/search/excerpt.d.ts.map +1 -1
  42. package/dist/search/excerpt.js +2 -1
  43. package/dist/search/excerpt.js.map +1 -1
  44. package/dist/search/tfidf.d.ts +1 -0
  45. package/dist/search/tfidf.d.ts.map +1 -1
  46. package/dist/search/tfidf.js +38 -3
  47. package/dist/search/tfidf.js.map +1 -1
  48. package/dist/server.d.ts.map +1 -1
  49. package/dist/server.js +117 -381
  50. package/dist/server.js.map +1 -1
  51. package/dist/sessions/parser.d.ts.map +1 -1
  52. package/dist/sessions/parser.js +12 -10
  53. package/dist/sessions/parser.js.map +1 -1
  54. package/dist/sessions/search.js +17 -3
  55. package/dist/sessions/search.js.map +1 -1
  56. package/dist/sessions/summary.d.ts.map +1 -1
  57. package/dist/sessions/summary.js +6 -3
  58. package/dist/sessions/summary.js.map +1 -1
  59. package/dist/tool-handlers.d.ts +42 -0
  60. package/dist/tool-handlers.d.ts.map +1 -0
  61. package/dist/tool-handlers.js +425 -0
  62. package/dist/tool-handlers.js.map +1 -0
  63. package/dist/types.d.ts.map +1 -1
  64. package/dist/types.js +6 -4
  65. package/dist/types.js.map +1 -1
  66. package/dist/ui/app.js +94 -723
  67. package/dist/ui/index.html +29 -0
  68. package/dist/ui/render-knowledge.js +233 -0
  69. package/dist/ui/render-panel.js +350 -0
  70. package/dist/ui/render-search.js +109 -0
  71. package/dist/ui/render-sessions.js +234 -0
  72. package/dist/ui/styles.css +261 -0
  73. package/dist/ui/ui-utils.js +196 -0
  74. package/dist/vectorstore/store.d.ts +25 -44
  75. package/dist/vectorstore/store.d.ts.map +1 -1
  76. package/dist/vectorstore/store.js +167 -167
  77. package/dist/vectorstore/store.js.map +1 -1
  78. package/docs/ARCHITECTURE.md +94 -1
  79. package/docs/DASHBOARD.md +26 -13
  80. package/docs/SETUP.md +17 -3
  81. package/package.json +2 -2
@@ -40,13 +40,17 @@ graph TB
40
40
  ```
41
41
  src/
42
42
  index.ts Entry point — MCP stdio + dashboard auto-start
43
- server.ts 12 tool definitions, request routing, error handling
43
+ server.ts 6 tool definitions, request routing, error handling
44
44
  dashboard.ts HTTP + WebSocket server, REST API, file watcher
45
45
  types.ts KnowledgeConfig interface, getConfig()
46
46
  knowledge/
47
47
  store.ts CRUD for markdown entries with YAML frontmatter
48
48
  search.ts TF-IDF search over knowledge entries
49
49
  git.ts git pull/push/sync with execSync + timeouts
50
+ graph.ts Knowledge graph — edges table, link/unlink/BFS traversal
51
+ scoring.ts Confidence/decay scoring — entry_scores table, auto-promotion
52
+ consolidate.ts Memory consolidation — TF-IDF duplicate detection, cluster grouping
53
+ reflect.ts Reflection cycle — surfaces unconnected entries, generates prompts
50
54
  sessions/
51
55
  parser.ts Multi-format parsing with mtime cache + adapter dispatch
52
56
  search.ts TF-IDF ranked search with 60s global index cache
@@ -92,6 +96,95 @@ Wraps `execSync` for git operations with timeouts:
92
96
 
93
97
  Builds a TF-IDF index from all knowledge entries, searches with ranking, falls back to regex for exact phrases.
94
98
 
99
+ ## Knowledge Graph
100
+
101
+ ### graph.ts
102
+
103
+ Manages typed, weighted edges between knowledge entries in a dedicated `edges` SQLite table.
104
+
105
+ **Schema**:
106
+
107
+ ```sql
108
+ CREATE TABLE edges (
109
+ source TEXT NOT NULL,
110
+ target TEXT NOT NULL,
111
+ rel_type TEXT NOT NULL,
112
+ strength REAL DEFAULT 1.0,
113
+ created TEXT NOT NULL,
114
+ PRIMARY KEY (source, target, rel_type)
115
+ );
116
+ ```
117
+
118
+ **8 relationship types**: `related_to`, `supersedes`, `depends_on`, `contradicts`, `specializes`, `part_of`, `alternative_to`, `builds_on`.
119
+
120
+ **Operations**:
121
+
122
+ - **link()** — upsert an edge (INSERT OR REPLACE), validates rel_type against allowed set
123
+ - **unlink()** — delete edges, optionally filtered by rel_type
124
+ - **links()** — list edges for a given entry or rel_type
125
+ - **traverse()** — BFS from a starting entry to configurable depth, returns nodes and edges visited
126
+
127
+ All four operations are exposed via the single `knowledge_graph` tool with an `action` parameter (`link`, `unlink`, `list`, `traverse`).
128
+
129
+ **Auto-linking**: On `knowledge_write`, the top-3 most similar existing entries are found via cosine similarity against the vector store. Entries with similarity > 0.7 get automatic `related_to` edges created.
130
+
131
+ ## Confidence & Decay Scoring
132
+
133
+ ### scoring.ts
134
+
135
+ Tracks access frequency and recency for search result ranking via an `entry_scores` SQLite table.
136
+
137
+ **Schema**:
138
+
139
+ ```sql
140
+ CREATE TABLE entry_scores (
141
+ path TEXT PRIMARY KEY,
142
+ access_count INTEGER DEFAULT 0,
143
+ last_accessed TEXT NOT NULL,
144
+ maturity TEXT DEFAULT 'candidate'
145
+ );
146
+ ```
147
+
148
+ **Scoring formula**:
149
+
150
+ ```
151
+ finalScore = baseRelevance * 0.5^(daysSinceLastAccess / 90) * maturityMultiplier
152
+ ```
153
+
154
+ **Maturity auto-promotion**:
155
+
156
+ | Stage | Accesses | Multiplier |
157
+ | ------------- | -------- | ---------- |
158
+ | `candidate` | < 5 | 0.5x |
159
+ | `established` | 5-19 | 1.0x |
160
+ | `proven` | 20+ | 1.5x |
161
+
162
+ Access count increments on `knowledge_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.
163
+
164
+ ## Memory Consolidation
165
+
166
+ ### consolidate.ts
167
+
168
+ Detects near-duplicate knowledge entries using TF-IDF similarity scoring.
169
+
170
+ **`checkDuplicates()`** — called after `knowledge_write`. Builds a TF-IDF index from all entries, queries with the written content, and returns entries exceeding a configurable similarity threshold (default: 0.6). Warnings are included in the write response.
171
+
172
+ **`consolidate()`** — batch scan for `knowledge_consolidate`. Computes pairwise TF-IDF similarities for all entries in a category (or globally), groups entries above threshold (default: 0.5) into clusters using union-find, and returns clusters with representative entries and pairwise similarity scores.
173
+
174
+ ## Reflection Cycle
175
+
176
+ ### reflect.ts
177
+
178
+ Surfaces unconnected knowledge entries and prepares structured prompts for agent-driven graph enrichment.
179
+
180
+ **`reflect()`** — reads all entries, queries the knowledge graph for edges, identifies entries with zero connections, and generates a structured markdown prompt listing:
181
+
182
+ 1. Unconnected entries with titles, categories, tags, and 300-char content summaries
183
+ 2. Connected entries as potential link targets
184
+ 3. Instructions for the agent to call `knowledge_link` with suggested relationships
185
+
186
+ Does NOT call an LLM — the calling agent processes the prompt in its own context and makes `knowledge_graph(action: "link")` calls based on its analysis.
187
+
95
188
  ## Session Module
96
189
 
97
190
  ### Multi-Source Architecture
package/docs/DASHBOARD.md CHANGED
@@ -16,12 +16,20 @@ The dashboard runs at **http://localhost:3423** and auto-starts with the MCP ser
16
16
  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
+ - **Maturity badge**: candidate (gray), established (blue), proven (green) — based on access frequency
19
20
  - Title and tag pills
20
21
  - Last updated date
21
22
 
22
- Category filter chips at the top: All, Projects, People, Decisions, Workflows, Notes.
23
+ ![Knowledge entries with maturity badges](assets/knowledge-maturity.png)
23
24
 
24
- Click a card to open the side panel with rendered markdown content.
25
+ Category filter chips at the top: All, Projects, People, Decisions, Workflows, Notes. Search bar for filtering entries by title.
26
+
27
+ **Header action buttons:**
28
+
29
+ - **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.
30
+ - **Reflect** — finds entries with no graph connections. Opens a side panel listing unconnected entries with content summaries and instructions for creating new links.
31
+
32
+ Click a card to open the side panel with rendered markdown content, score details, and related entries.
25
33
 
26
34
  ## Search Tab
27
35
 
@@ -78,6 +86,8 @@ Results use the same format as the Search tab.
78
86
  - Width: 560px, resizable by dragging the left edge
79
87
  - Close: X button or press Escape
80
88
  - Knowledge entries: rendered as markdown via marked + DOMPurify + highlight.js
89
+ - **Related entries**: linked entries shown with colored relationship-type pills (related_to, depends_on, supersedes, etc.) — clickable to navigate
90
+ - **Score details**: maturity level, access count, decay factor, and maturity multiplier
81
91
  - Sessions: chat bubbles (user = right/accent, assistant = left/surface)
82
92
 
83
93
  ## Theming
@@ -100,17 +110,20 @@ File watcher monitors `src/ui/` for `.html`, `.css`, `.js` changes. On change, b
100
110
 
101
111
  ## REST API
102
112
 
103
- | Method | Endpoint | Description |
104
- | ------ | --------------------------------------- | ---------------- |
105
- | GET | `/api/knowledge` | List entries |
106
- | GET | `/api/knowledge/search?q=` | Search knowledge |
107
- | GET | `/api/knowledge/:path` | Read entry |
108
- | GET | `/api/sessions` | List sessions |
109
- | GET | `/api/sessions/search?q=&role=&ranked=` | Search sessions |
110
- | GET | `/api/sessions/recall?scope=&q=` | Scoped recall |
111
- | GET | `/api/sessions/:id` | Read session |
112
- | GET | `/api/sessions/:id/summary` | Session summary |
113
- | GET | `/health` | Health check |
113
+ | Method | Endpoint | Description |
114
+ | ------ | --------------------------------------- | ---------------------------- |
115
+ | GET | `/api/knowledge` | List entries |
116
+ | GET | `/api/knowledge/search?q=` | Search knowledge |
117
+ | GET | `/api/knowledge/:path` | Read entry (with score data) |
118
+ | GET | `/api/knowledge/:path/links` | Graph edges for entry |
119
+ | GET | `/api/knowledge/consolidate?threshold=` | Duplicate cluster analysis |
120
+ | GET | `/api/knowledge/reflect?max_entries=` | Unconnected entries + prompt |
121
+ | GET | `/api/sessions` | List sessions |
122
+ | GET | `/api/sessions/search?q=&role=&ranked=` | Search sessions |
123
+ | GET | `/api/sessions/recall?scope=&q=` | Scoped recall |
124
+ | GET | `/api/sessions/:id` | Read session |
125
+ | GET | `/api/sessions/:id/summary` | Session summary |
126
+ | GET | `/health` | Health check |
114
127
 
115
128
  ## WebSocket
116
129
 
package/docs/SETUP.md CHANGED
@@ -174,9 +174,9 @@ Hooks announce the dashboard URL on session start. Support varies by client.
174
174
 
175
175
  ### Claude Code Hooks
176
176
 
177
- #### SessionStart (`scripts/hooks/session-start.js`)
177
+ #### SessionStart + SubagentStart (`scripts/hooks/session-start.js`)
178
178
 
179
- Announces the knowledge dashboard URL on session start.
179
+ Announces the knowledge dashboard URL on session start. Also fires for subagents via `SubagentStart`, ensuring spawned agents know about the knowledge base.
180
180
 
181
181
  Add to `~/.claude/settings.json`:
182
182
 
@@ -193,6 +193,17 @@ Add to `~/.claude/settings.json`:
193
193
  }
194
194
  ]
195
195
  }
196
+ ],
197
+ "SubagentStart": [
198
+ {
199
+ "hooks": [
200
+ {
201
+ "type": "command",
202
+ "command": "node \"/path/to/agent-knowledge/scripts/hooks/session-start.js\"",
203
+ "timeout": 5
204
+ }
205
+ ]
206
+ }
196
207
  ]
197
208
  }
198
209
  }
@@ -236,12 +247,15 @@ Add these instructions:
236
247
  You have access to agent-knowledge MCP tools — a shared knowledge base synced via git.
237
248
 
238
249
  Available tools: knowledge_list, knowledge_read, knowledge_write, knowledge_search,
239
- knowledge_recall, knowledge_sessions, knowledge_config, knowledge_sync
250
+ knowledge_recall, knowledge_sessions, knowledge_config, knowledge_sync,
251
+ knowledge_link, knowledge_unlink, knowledge_links, knowledge_graph
240
252
 
241
253
  Categories: projects, people, decisions, workflows, notes
242
254
 
243
255
  Use knowledge_search for semantic + keyword search across all entries.
244
256
  Use knowledge_recall for scoped search (errors, plans, configs, tools, files, decisions).
257
+ Use knowledge_link/knowledge_unlink to manage relationships between entries.
258
+ Use knowledge_graph to explore connections from any entry via BFS traversal.
245
259
 
246
260
  Dashboard: http://localhost:3423
247
261
  ```
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "agent-knowledge",
3
- "version": "1.1.6",
4
- "description": "Cross-session memory and recall for AI agents — git-synced knowledge base, hybrid semantic+TF-IDF search, auto-distillation with secrets scrubbing",
3
+ "version": "1.3.0",
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",
7
7
  "bin": {