agent-knowledge 1.1.5 → 1.1.7
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/CHANGELOG.md +123 -5
- package/README.md +86 -24
- package/dist/dashboard.d.ts +1 -0
- package/dist/dashboard.d.ts.map +1 -1
- package/dist/dashboard.js +145 -19
- package/dist/dashboard.js.map +1 -1
- package/dist/embeddings/anthropic.d.ts.map +1 -1
- package/dist/embeddings/anthropic.js +2 -1
- package/dist/embeddings/anthropic.js.map +1 -1
- package/dist/embeddings/gemini.d.ts.map +1 -1
- package/dist/embeddings/gemini.js +2 -1
- package/dist/embeddings/gemini.js.map +1 -1
- package/dist/embeddings/local.d.ts.map +1 -1
- package/dist/embeddings/local.js +3 -0
- package/dist/embeddings/local.js.map +1 -1
- package/dist/knowledge/consolidate.d.ts +46 -0
- package/dist/knowledge/consolidate.d.ts.map +1 -0
- package/dist/knowledge/consolidate.js +164 -0
- package/dist/knowledge/consolidate.js.map +1 -0
- package/dist/knowledge/distill.d.ts.map +1 -1
- package/dist/knowledge/distill.js +4 -2
- package/dist/knowledge/distill.js.map +1 -1
- package/dist/knowledge/graph.d.ts +64 -0
- package/dist/knowledge/graph.d.ts.map +1 -0
- package/dist/knowledge/graph.js +214 -0
- package/dist/knowledge/graph.js.map +1 -0
- package/dist/knowledge/reflect.d.ts +33 -0
- package/dist/knowledge/reflect.d.ts.map +1 -0
- package/dist/knowledge/reflect.js +115 -0
- package/dist/knowledge/reflect.js.map +1 -0
- package/dist/knowledge/scoring.d.ts +57 -0
- package/dist/knowledge/scoring.d.ts.map +1 -0
- package/dist/knowledge/scoring.js +194 -0
- package/dist/knowledge/scoring.js.map +1 -0
- package/dist/knowledge/search.d.ts.map +1 -1
- package/dist/knowledge/search.js +15 -2
- package/dist/knowledge/search.js.map +1 -1
- package/dist/knowledge/store.d.ts.map +1 -1
- package/dist/knowledge/store.js +4 -3
- package/dist/knowledge/store.js.map +1 -1
- package/dist/search/excerpt.d.ts.map +1 -1
- package/dist/search/excerpt.js +2 -1
- package/dist/search/excerpt.js.map +1 -1
- package/dist/search/tfidf.d.ts +1 -0
- package/dist/search/tfidf.d.ts.map +1 -1
- package/dist/search/tfidf.js +38 -3
- package/dist/search/tfidf.js.map +1 -1
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +125 -382
- package/dist/server.js.map +1 -1
- package/dist/sessions/parser.d.ts.map +1 -1
- package/dist/sessions/parser.js +44 -69
- package/dist/sessions/parser.js.map +1 -1
- package/dist/sessions/search.js +17 -3
- package/dist/sessions/search.js.map +1 -1
- package/dist/sessions/summary.d.ts.map +1 -1
- package/dist/sessions/summary.js +26 -16
- package/dist/sessions/summary.js.map +1 -1
- package/dist/tool-handlers.d.ts +41 -0
- package/dist/tool-handlers.d.ts.map +1 -0
- package/dist/tool-handlers.js +440 -0
- package/dist/tool-handlers.js.map +1 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +6 -4
- package/dist/types.js.map +1 -1
- package/dist/ui/app.js +201 -691
- package/dist/ui/index.html +29 -0
- package/dist/ui/render-knowledge.js +233 -0
- package/dist/ui/render-panel.js +350 -0
- package/dist/ui/render-search.js +109 -0
- package/dist/ui/render-sessions.js +234 -0
- package/dist/ui/styles.css +261 -0
- package/dist/ui/ui-utils.js +196 -0
- package/dist/vectorstore/store.d.ts +25 -44
- package/dist/vectorstore/store.d.ts.map +1 -1
- package/dist/vectorstore/store.js +167 -167
- package/dist/vectorstore/store.js.map +1 -1
- package/docs/ARCHITECTURE.md +94 -1
- package/docs/DASHBOARD.md +26 -13
- package/docs/SETUP.md +74 -23
- package/package.json +2 -2
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -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
|
|
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
|
-
|
|
23
|
+

|
|
23
24
|
|
|
24
|
-
|
|
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/
|
|
109
|
-
| GET | `/api/
|
|
110
|
-
| GET | `/api/
|
|
111
|
-
| GET | `/api/sessions
|
|
112
|
-
| GET | `/api/sessions
|
|
113
|
-
| GET | `/
|
|
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
|
}
|
|
@@ -223,29 +234,69 @@ Combine with `AGENTS.md` instructions (see below).
|
|
|
223
234
|
|
|
224
235
|
### Cursor and Windsurf
|
|
225
236
|
|
|
226
|
-
Cursor and Windsurf don't support lifecycle hooks. Use
|
|
237
|
+
Cursor and Windsurf don't support lifecycle hooks. Use rules files instead:
|
|
238
|
+
|
|
239
|
+
| Client | Rules location |
|
|
240
|
+
| -------- | --------------------- |
|
|
241
|
+
| Cursor | `.cursor/rules/*.mdc` |
|
|
242
|
+
| Windsurf | `.windsurfrules` |
|
|
243
|
+
|
|
244
|
+
#### Cursor Rules Setup
|
|
245
|
+
|
|
246
|
+
Create `.cursor/rules/agent-mcp-stack.mdc` with "Always Apply" mode:
|
|
227
247
|
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
248
|
+
```yaml
|
|
249
|
+
---
|
|
250
|
+
description: Agent MCP stack integration
|
|
251
|
+
globs: *
|
|
252
|
+
alwaysApply: true
|
|
253
|
+
---
|
|
254
|
+
|
|
255
|
+
# Agent MCP Stack
|
|
256
|
+
|
|
257
|
+
## Default behavior in every chat
|
|
258
|
+
|
|
259
|
+
Treat `agent-comm`, `agent-knowledge`, and `agent-tasks` as default infrastructure
|
|
260
|
+
for this repository. Do not wait for the user to restate this.
|
|
261
|
+
|
|
262
|
+
At the start of each new chat/session:
|
|
232
263
|
|
|
233
|
-
|
|
264
|
+
1. Bootstrap `agent-comm` (`comm_register`, join `general`, send one-line intent, then `comm_inbox`).
|
|
265
|
+
2. Use `agent-knowledge` first for recall/session context when it can help
|
|
266
|
+
(especially prior decisions, errors, tool usage, and related sessions).
|
|
267
|
+
3. Check `agent-tasks` before creating work (`task_list`), and keep task
|
|
268
|
+
state/artifacts/comments current when work spans more than one step.
|
|
234
269
|
|
|
270
|
+
If an MCP server is unavailable, report it briefly and continue with local tools;
|
|
271
|
+
retry MCP usage after restoring connectivity.
|
|
235
272
|
```
|
|
236
|
-
You have access to agent-knowledge MCP tools — a shared knowledge base synced via git.
|
|
237
273
|
|
|
238
|
-
|
|
239
|
-
knowledge_recall, knowledge_sessions, knowledge_config, knowledge_sync
|
|
274
|
+
Optionally create `.cursor/rules/session-wrapup-knowledge.mdc` for session wrap-up:
|
|
240
275
|
|
|
241
|
-
|
|
276
|
+
```yaml
|
|
277
|
+
---
|
|
278
|
+
description: Save session learnings to knowledge base
|
|
279
|
+
globs: *
|
|
280
|
+
alwaysApply: false
|
|
281
|
+
---
|
|
282
|
+
|
|
283
|
+
# Session Wrap-up
|
|
242
284
|
|
|
243
|
-
|
|
244
|
-
Use knowledge_recall for scoped search (errors, plans, configs, tools, files, decisions).
|
|
285
|
+
Before ending a session, save non-obvious learnings to agent-knowledge:
|
|
245
286
|
|
|
246
|
-
|
|
287
|
+
1. `knowledge_search` for existing entries that overlap with this session's work.
|
|
288
|
+
2. `knowledge_write` new entries for decisions, architecture changes, or error patterns
|
|
289
|
+
that aren't already captured.
|
|
290
|
+
3. `knowledge_link` related entries together.
|
|
291
|
+
|
|
292
|
+
Categories: projects (project context), decisions (trade-offs made), workflows (processes),
|
|
293
|
+
notes (everything else).
|
|
247
294
|
```
|
|
248
295
|
|
|
296
|
+
#### Windsurf
|
|
297
|
+
|
|
298
|
+
Add equivalent instructions to `.windsurfrules` in your project root.
|
|
299
|
+
|
|
249
300
|
---
|
|
250
301
|
|
|
251
302
|
## Knowledge Base Setup
|
|
@@ -443,11 +494,11 @@ If your session data is in a non-standard location, use `EXTRA_SESSION_ROOTS` to
|
|
|
443
494
|
|
|
444
495
|
## Client Comparison
|
|
445
496
|
|
|
446
|
-
| Feature | Claude Code | Cursor
|
|
447
|
-
| -------------------- | ----------- |
|
|
448
|
-
| MCP stdio transport | Yes | Yes
|
|
449
|
-
| Session reading | Yes (JSONL) | Yes (JSONL)
|
|
450
|
-
| Lifecycle hooks | Yes (JSON) | No
|
|
451
|
-
| Session auto-distill | Yes | Yes
|
|
452
|
-
| System prompt file | CLAUDE.md | .
|
|
453
|
-
| REST API fallback | Yes | Yes
|
|
497
|
+
| Feature | Claude Code | Cursor | OpenCode | Cline | Continue.dev | Aider | Windsurf |
|
|
498
|
+
| -------------------- | ----------- | -------------------- | ------------- | ---------- | ------------ | -------------- | -------------- |
|
|
499
|
+
| MCP stdio transport | Yes | Yes | Yes | Yes | Yes | -- | Yes |
|
|
500
|
+
| Session reading | Yes (JSONL) | Yes (JSONL) | Yes (SQLite) | Yes (JSON) | Yes (JSON) | Yes (MD/JSONL) | -- |
|
|
501
|
+
| Lifecycle hooks | Yes (JSON) | No | Yes (plugins) | No | No | -- | No |
|
|
502
|
+
| Session auto-distill | Yes | Yes | Yes | Yes | Yes | Yes | -- |
|
|
503
|
+
| System prompt file | CLAUDE.md | .cursor/rules/\*.mdc | AGENTS.md | -- | -- | -- | .windsurfrules |
|
|
504
|
+
| REST API fallback | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agent-knowledge",
|
|
3
|
-
"version": "1.1.
|
|
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.1.7",
|
|
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": {
|