agent-knowledge 1.3.7 → 1.3.8
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/docs/USER-MANUAL.md +798 -0
- package/package.json +1 -1
|
@@ -0,0 +1,798 @@
|
|
|
1
|
+
# agent-knowledge User Manual
|
|
2
|
+
|
|
3
|
+
## Table of Contents
|
|
4
|
+
|
|
5
|
+
1. [Overview](#1-overview)
|
|
6
|
+
2. [Installation](#2-installation)
|
|
7
|
+
3. [Configuration](#3-configuration)
|
|
8
|
+
4. [Dashboard Guide](#4-dashboard-guide)
|
|
9
|
+
5. [MCP Tools Reference](#5-mcp-tools-reference)
|
|
10
|
+
6. [REST API Reference](#6-rest-api-reference)
|
|
11
|
+
7. [Knowledge Base Management](#7-knowledge-base-management)
|
|
12
|
+
8. [Session Search](#8-session-search)
|
|
13
|
+
9. [Troubleshooting](#9-troubleshooting)
|
|
14
|
+
10. [FAQ](#10-faq)
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## 1. Overview
|
|
19
|
+
|
|
20
|
+
### What agent-knowledge Does
|
|
21
|
+
|
|
22
|
+
agent-knowledge is an MCP (Model Context Protocol) server that provides cross-session memory and recall for AI coding agents. It combines a git-synced knowledge base with session search, knowledge graphs, and hybrid semantic+TF-IDF search:
|
|
23
|
+
|
|
24
|
+
- **Knowledge base** -- Markdown files with YAML frontmatter stored in a git repository. Categories: `projects`, `people`, `decisions`, `workflows`, `notes`.
|
|
25
|
+
- **Git sync** -- automatic pull before reads, push after writes. Knowledge persists across machines.
|
|
26
|
+
- **Hybrid search** -- combines semantic vector similarity (via embeddings) with TF-IDF scoring for accurate retrieval.
|
|
27
|
+
- **Session search** -- search across past AI coding sessions from Claude Code, Cursor, and OpenCode.
|
|
28
|
+
- **Scoped recall** -- targeted search within domains: `errors`, `plans`, `configs`, `tools`, `files`, `decisions`.
|
|
29
|
+
- **Knowledge graph** -- typed edges between entries (8 relationship types) with BFS traversal.
|
|
30
|
+
- **Confidence scoring** -- entries gain maturity (`candidate` > `established` > `proven`) based on access frequency.
|
|
31
|
+
- **Auto-linking** -- new entries are automatically linked to similar existing entries via cosine similarity.
|
|
32
|
+
- **Duplicate detection** -- warns when writing entries that are similar to existing ones.
|
|
33
|
+
- **Session distillation** -- past sessions are auto-distilled into knowledge entries on server startup.
|
|
34
|
+
- **Real-time dashboard** -- web UI showing knowledge entries, sessions, and search results.
|
|
35
|
+
|
|
36
|
+
### Architecture
|
|
37
|
+
|
|
38
|
+
agent-knowledge has two entry points:
|
|
39
|
+
|
|
40
|
+
| Entry Point | File | Purpose |
|
|
41
|
+
| ---------------- | ---------------- | ----------------------------------------------------------------------------------------- |
|
|
42
|
+
| MCP stdio server | `dist/index.js` | Communicates with the AI agent via JSON-RPC over stdin/stdout. Auto-starts the dashboard. |
|
|
43
|
+
| HTTP server | `dist/server.js` | Standalone dashboard + REST API + WebSocket. |
|
|
44
|
+
|
|
45
|
+
Internally:
|
|
46
|
+
|
|
47
|
+
```
|
|
48
|
+
knowledge/ Store (Markdown CRUD), search (TF-IDF), git sync, distillation, graph, scoring, consolidation, reflection
|
|
49
|
+
sessions/ Parser (multi-format), indexer, search, scopes, summary, adapters (Claude Code, Cursor, OpenCode)
|
|
50
|
+
search/ TF-IDF engine, fuzzy matching, excerpt generation
|
|
51
|
+
embeddings/ Provider registry (Claude/Voyage, OpenAI, Gemini, local fallback)
|
|
52
|
+
vectorstore/ SQLite-backed vector storage with cosine similarity, document chunking
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
No framework dependencies. Pure Node.js + TypeScript.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## 2. Installation
|
|
60
|
+
|
|
61
|
+
### Prerequisites
|
|
62
|
+
|
|
63
|
+
- **Node.js 20.11.0 or later**
|
|
64
|
+
- **npm** (comes with Node.js)
|
|
65
|
+
- **Git** (for knowledge base sync)
|
|
66
|
+
|
|
67
|
+
### From npm
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
npm install -g agent-knowledge
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### From Source
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
git clone https://github.com/keshrath/agent-knowledge.git
|
|
77
|
+
cd agent-knowledge
|
|
78
|
+
npm install
|
|
79
|
+
npm run build
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### npx (No Installation)
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
npx agent-knowledge
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## 3. Configuration
|
|
91
|
+
|
|
92
|
+
### Environment Variables
|
|
93
|
+
|
|
94
|
+
| Variable | Default | Description |
|
|
95
|
+
| ------------------------ | ------------------- | ---------------------------------------------- |
|
|
96
|
+
| `KNOWLEDGE_PORT` | `3423` | Dashboard HTTP/WebSocket port |
|
|
97
|
+
| `KNOWLEDGE_DATA_DIR` | `~/.claude` | Base directory for Claude Code session data |
|
|
98
|
+
| `KNOWLEDGE_GIT_URL` | (none) | Git remote URL for knowledge base sync |
|
|
99
|
+
| `KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Local knowledge base directory |
|
|
100
|
+
| `KNOWLEDGE_AUTO_DISTILL` | `true` | Enable/disable session auto-distillation |
|
|
101
|
+
| `EXTRA_SESSION_ROOTS` | (none) | Comma-separated additional session directories |
|
|
102
|
+
|
|
103
|
+
### Claude Code Setup
|
|
104
|
+
|
|
105
|
+
Add to `~/.claude.json`:
|
|
106
|
+
|
|
107
|
+
```json
|
|
108
|
+
{
|
|
109
|
+
"mcpServers": {
|
|
110
|
+
"agent-knowledge": {
|
|
111
|
+
"command": "npx",
|
|
112
|
+
"args": ["agent-knowledge"]
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
The dashboard auto-starts at http://localhost:3423.
|
|
119
|
+
|
|
120
|
+
### Permissions (settings.json)
|
|
121
|
+
|
|
122
|
+
```json
|
|
123
|
+
{
|
|
124
|
+
"permissions": {
|
|
125
|
+
"allow": ["mcp__agent-knowledge__*"]
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### Persisted Configuration
|
|
131
|
+
|
|
132
|
+
Configuration can also be set via the `knowledge_admin` tool with `action: "config"`. Persisted config is stored at a tool-agnostic location and environment variables override persisted settings.
|
|
133
|
+
|
|
134
|
+
```
|
|
135
|
+
knowledge_admin with action "config", git_url "https://github.com/user/memory.git"
|
|
136
|
+
knowledge_admin with action "config", memory_dir "/custom/path/knowledge"
|
|
137
|
+
knowledge_admin with action "config", auto_distill false
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
142
|
+
## 4. Dashboard Guide
|
|
143
|
+
|
|
144
|
+
### Accessing the Dashboard
|
|
145
|
+
|
|
146
|
+
The dashboard is available at **http://localhost:3423** (or the port configured via `KNOWLEDGE_PORT`).
|
|
147
|
+
|
|
148
|
+
### Knowledge Tab
|
|
149
|
+
|
|
150
|
+
Shows all knowledge base entries organized by category. Each entry card displays:
|
|
151
|
+
|
|
152
|
+
- **Title** extracted from the Markdown content or filename.
|
|
153
|
+
- **Category** badge (`projects`, `people`, `decisions`, `workflows`, `notes`).
|
|
154
|
+
- **Tags** from YAML frontmatter.
|
|
155
|
+
- **Maturity** level (`candidate`, `established`, `proven`).
|
|
156
|
+
- **Access count** -- how many times the entry has been read.
|
|
157
|
+
- **Last accessed** timestamp.
|
|
158
|
+
|
|
159
|
+
Click an entry to view its full Markdown content, related entries (from the knowledge graph), and score data.
|
|
160
|
+
|
|
161
|
+
### Sessions Tab
|
|
162
|
+
|
|
163
|
+
Lists discovered sessions from all configured sources (Claude Code, Cursor, OpenCode). Each session shows:
|
|
164
|
+
|
|
165
|
+
- **Session ID** (UUID).
|
|
166
|
+
- **Project** name.
|
|
167
|
+
- **Message count** and duration.
|
|
168
|
+
- **Last modified** timestamp.
|
|
169
|
+
|
|
170
|
+
Click a session to view its messages.
|
|
171
|
+
|
|
172
|
+
### Search
|
|
173
|
+
|
|
174
|
+
The search bar performs hybrid search across both knowledge entries and sessions. Results are ranked by relevance combining TF-IDF and semantic similarity scores.
|
|
175
|
+
|
|
176
|
+
### Stats
|
|
177
|
+
|
|
178
|
+
Displays vector store statistics: total entries, knowledge entries, session entries, database size, embedding provider, and dimensions.
|
|
179
|
+
|
|
180
|
+
### Theme Toggle
|
|
181
|
+
|
|
182
|
+
Dark and light themes available. Preference saved in `localStorage`.
|
|
183
|
+
|
|
184
|
+
### Real-Time Updates
|
|
185
|
+
|
|
186
|
+
The dashboard connects via WebSocket. On connect, it receives the full state snapshot. A file watcher monitors the UI directory for hot-reload during development. The state snapshot is cached for 30 seconds to avoid expensive disk and database scans.
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## 5. MCP Tools Reference
|
|
191
|
+
|
|
192
|
+
agent-knowledge exposes 6 MCP tools, each with multiple actions.
|
|
193
|
+
|
|
194
|
+
### knowledge
|
|
195
|
+
|
|
196
|
+
Knowledge base CRUD and git sync.
|
|
197
|
+
|
|
198
|
+
**Actions:** `list`, `read`, `write`, `delete`, `sync`
|
|
199
|
+
|
|
200
|
+
**Parameters:**
|
|
201
|
+
|
|
202
|
+
| Name | Type | Required | Description |
|
|
203
|
+
| ---------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
204
|
+
| `action` | string | Yes | One of: `list`, `read`, `write`, `delete`, `sync` |
|
|
205
|
+
| `category` | string | No | [list] Filter by category; [write] Target directory. One of: `projects`, `people`, `decisions`, `workflows`, `notes` |
|
|
206
|
+
| `tag` | string | No | [list] Filter by tag |
|
|
207
|
+
| `path` | string | No | [read/delete] Relative path, e.g. `projects/my-project.md` |
|
|
208
|
+
| `filename` | string | No | [write] Filename with or without .md extension |
|
|
209
|
+
| `content` | string | No | [write] Full Markdown content (max 1MB) |
|
|
210
|
+
|
|
211
|
+
**Action: list**
|
|
212
|
+
|
|
213
|
+
Browse knowledge entries, optionally filtered by category or tag.
|
|
214
|
+
|
|
215
|
+
```
|
|
216
|
+
knowledge with action "list"
|
|
217
|
+
knowledge with action "list", category "projects"
|
|
218
|
+
knowledge with action "list", tag "architecture"
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
**Action: read**
|
|
222
|
+
|
|
223
|
+
Read an entry's content. Records an access for scoring. Returns content, score data, and related entries from the knowledge graph.
|
|
224
|
+
|
|
225
|
+
```
|
|
226
|
+
knowledge with action "read", path "projects/my-project.md"
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
**Action: write**
|
|
230
|
+
|
|
231
|
+
Create or update an entry. Auto-syncs to git (pull before write, push after). Auto-links to similar entries via vector search. Warns about potential duplicates.
|
|
232
|
+
|
|
233
|
+
```
|
|
234
|
+
knowledge with action "write", category "decisions", filename "use-jwt.md", content "---\ntags: [auth, security]\n---\n# Decision: Use JWT\n\nWe chose JWT over session cookies because..."
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
**Response includes:**
|
|
238
|
+
|
|
239
|
+
- `path`: Where the file was written.
|
|
240
|
+
- `git`: Push result.
|
|
241
|
+
- `autoLinked`: Similar entries that were auto-linked (cosine > 0.7).
|
|
242
|
+
- `similarEntries`: Potential duplicates found.
|
|
243
|
+
|
|
244
|
+
**Action: delete**
|
|
245
|
+
|
|
246
|
+
Remove an entry and sync to git.
|
|
247
|
+
|
|
248
|
+
```
|
|
249
|
+
knowledge with action "delete", path "notes/old-note.md"
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
**Action: sync**
|
|
253
|
+
|
|
254
|
+
Manual git pull + push.
|
|
255
|
+
|
|
256
|
+
```
|
|
257
|
+
knowledge with action "sync"
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
---
|
|
261
|
+
|
|
262
|
+
### knowledge_search
|
|
263
|
+
|
|
264
|
+
Search across sessions and knowledge entries. Supports general search and scoped recall.
|
|
265
|
+
|
|
266
|
+
**Parameters:**
|
|
267
|
+
|
|
268
|
+
| Name | Type | Required | Description |
|
|
269
|
+
| ------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
270
|
+
| `query` | string | Yes | Search query -- supports keywords and phrases |
|
|
271
|
+
| `scope` | string | No | Search scope: `errors`, `plans`, `configs`, `tools`, `files`, `decisions`, `all`. When provided, performs scoped recall in sessions only. |
|
|
272
|
+
| `project` | string | No | Restrict to sessions from this project |
|
|
273
|
+
| `role` | string | No | Filter by message role: `user`, `assistant`, `all` (default: all, ignored when scope is set) |
|
|
274
|
+
| `max_results` | number | No | Maximum results (default: 20) |
|
|
275
|
+
| `ranked` | boolean | No | Use TF-IDF ranking (default: true, ignored when scope is set) |
|
|
276
|
+
| `semantic` | boolean | No | Blend semantic similarity with TF-IDF (default: true) |
|
|
277
|
+
|
|
278
|
+
**General search** (no scope):
|
|
279
|
+
|
|
280
|
+
```
|
|
281
|
+
knowledge_search with query "authentication error handling"
|
|
282
|
+
knowledge_search with query "database migration", project "backend"
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
Returns both session matches and knowledge base matches.
|
|
286
|
+
|
|
287
|
+
**Scoped recall** (with scope):
|
|
288
|
+
|
|
289
|
+
```
|
|
290
|
+
knowledge_search with query "ECONNREFUSED", scope "errors"
|
|
291
|
+
knowledge_search with query "microservices", scope "plans"
|
|
292
|
+
knowledge_search with query "DATABASE_URL", scope "configs"
|
|
293
|
+
knowledge_search with query "comm_register", scope "tools"
|
|
294
|
+
knowledge_search with query "src/auth.ts", scope "files"
|
|
295
|
+
knowledge_search with query "JWT vs sessions", scope "decisions"
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
Scope descriptions:
|
|
299
|
+
|
|
300
|
+
| Scope | What it searches |
|
|
301
|
+
| ----------- | -------------------------------------------------- |
|
|
302
|
+
| `errors` | Stack traces, error messages, debugging sessions |
|
|
303
|
+
| `plans` | Architecture discussions, TODOs, planning messages |
|
|
304
|
+
| `configs` | Settings, environment variables, configuration |
|
|
305
|
+
| `tools` | MCP tool calls, tool results |
|
|
306
|
+
| `files` | File paths, code references |
|
|
307
|
+
| `decisions` | Trade-offs, choices, "chose X over Y" |
|
|
308
|
+
| `all` | No filter (same as general search within sessions) |
|
|
309
|
+
|
|
310
|
+
---
|
|
311
|
+
|
|
312
|
+
### knowledge_session
|
|
313
|
+
|
|
314
|
+
Session operations.
|
|
315
|
+
|
|
316
|
+
**Parameters:**
|
|
317
|
+
|
|
318
|
+
| Name | Type | Required | Description |
|
|
319
|
+
| --------------- | ------- | -------- | ---------------------------------------------------------------- |
|
|
320
|
+
| `action` | string | Yes | One of: `list`, `get`, `summary` |
|
|
321
|
+
| `session_id` | string | Varies | Session UUID (required for `get`, `summary`) |
|
|
322
|
+
| `project` | string | No | Filter by project name (substring match) |
|
|
323
|
+
| `include_tools` | boolean | No | [get] Include tool_use and tool_result messages (default: false) |
|
|
324
|
+
| `tail` | number | No | [get] Only return the last N messages |
|
|
325
|
+
| `limit` | number | No | [list] Max sessions (default: 20, max: 500) |
|
|
326
|
+
| `offset` | number | No | [list] Skip first N sessions (default: 0) |
|
|
327
|
+
|
|
328
|
+
**Action: list**
|
|
329
|
+
|
|
330
|
+
Browse sessions, optionally filtered by project.
|
|
331
|
+
|
|
332
|
+
```
|
|
333
|
+
knowledge_session with action "list"
|
|
334
|
+
knowledge_session with action "list", project "backend", limit 50
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
**Action: get**
|
|
338
|
+
|
|
339
|
+
Retrieve full conversation messages for a session.
|
|
340
|
+
|
|
341
|
+
```
|
|
342
|
+
knowledge_session with action "get", session_id "abc-123-def"
|
|
343
|
+
knowledge_session with action "get", session_id "abc-123-def", include_tools true, tail 20
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
**Action: summary**
|
|
347
|
+
|
|
348
|
+
Get a quick overview of a session (topics, file paths, message counts).
|
|
349
|
+
|
|
350
|
+
```
|
|
351
|
+
knowledge_session with action "summary", session_id "abc-123-def"
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
---
|
|
355
|
+
|
|
356
|
+
### knowledge_admin
|
|
357
|
+
|
|
358
|
+
Admin operations for configuration, index stats, and embedding management.
|
|
359
|
+
|
|
360
|
+
**Parameters:**
|
|
361
|
+
|
|
362
|
+
| Name | Type | Required | Description |
|
|
363
|
+
| -------------- | ------- | -------- | -------------------------------------------------------- |
|
|
364
|
+
| `action` | string | Yes | One of: `status`, `config`, `rebuild_embeddings` |
|
|
365
|
+
| `git_url` | string | No | [config] Git remote URL (empty string to remove) |
|
|
366
|
+
| `memory_dir` | string | No | [config] Local knowledge base directory (empty to reset) |
|
|
367
|
+
| `auto_distill` | boolean | No | [config] Enable/disable session distillation |
|
|
368
|
+
|
|
369
|
+
**Action: status**
|
|
370
|
+
|
|
371
|
+
View vector store statistics.
|
|
372
|
+
|
|
373
|
+
```
|
|
374
|
+
knowledge_admin with action "status"
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
Returns total entries, knowledge entries, session entries, unique sessions, database size, provider name, and dimensions.
|
|
378
|
+
|
|
379
|
+
**Action: config**
|
|
380
|
+
|
|
381
|
+
View or update configuration. Without update params, returns current config.
|
|
382
|
+
|
|
383
|
+
```
|
|
384
|
+
# View config
|
|
385
|
+
knowledge_admin with action "config"
|
|
386
|
+
|
|
387
|
+
# Update git URL
|
|
388
|
+
knowledge_admin with action "config", git_url "https://github.com/user/memory.git"
|
|
389
|
+
|
|
390
|
+
# Disable auto-distillation
|
|
391
|
+
knowledge_admin with action "config", auto_distill false
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
**Action: rebuild_embeddings**
|
|
395
|
+
|
|
396
|
+
Re-embed all knowledge entries. Useful when switching embedding providers.
|
|
397
|
+
|
|
398
|
+
```
|
|
399
|
+
knowledge_admin with action "rebuild_embeddings"
|
|
400
|
+
```
|
|
401
|
+
|
|
402
|
+
Wipes existing vectors, re-creates the store with the current provider's dimensions, and re-embeds all entries. Returns processed/failed counts.
|
|
403
|
+
|
|
404
|
+
---
|
|
405
|
+
|
|
406
|
+
### knowledge_graph
|
|
407
|
+
|
|
408
|
+
Knowledge graph operations for creating and traversing relationships between entries.
|
|
409
|
+
|
|
410
|
+
**Parameters:**
|
|
411
|
+
|
|
412
|
+
| Name | Type | Required | Description |
|
|
413
|
+
| ---------- | ------ | -------- | ---------------------------------------------------------------------- |
|
|
414
|
+
| `action` | string | Yes | One of: `link`, `unlink`, `list`, `traverse` |
|
|
415
|
+
| `source` | string | Varies | [link/unlink] Source entry path |
|
|
416
|
+
| `target` | string | Varies | [link/unlink] Target entry path |
|
|
417
|
+
| `entry` | string | No | [list] Filter by entry path; [traverse] BFS start node |
|
|
418
|
+
| `rel_type` | string | Varies | Relationship type (required for link, optional filter for unlink/list) |
|
|
419
|
+
| `strength` | number | No | [link] Edge strength 0-1 (default: 0.5) |
|
|
420
|
+
| `depth` | number | No | [traverse] Max traversal depth in hops (default: 2) |
|
|
421
|
+
|
|
422
|
+
**Relationship types:**
|
|
423
|
+
|
|
424
|
+
| Type | Description |
|
|
425
|
+
| ---------------- | ------------------------------------ |
|
|
426
|
+
| `related_to` | General association |
|
|
427
|
+
| `supersedes` | Entry replaces another |
|
|
428
|
+
| `depends_on` | Entry depends on another |
|
|
429
|
+
| `contradicts` | Entries have conflicting information |
|
|
430
|
+
| `specializes` | Entry is a specific case of another |
|
|
431
|
+
| `part_of` | Entry is a component of another |
|
|
432
|
+
| `alternative_to` | Entry is an alternative to another |
|
|
433
|
+
| `builds_on` | Entry extends or builds on another |
|
|
434
|
+
|
|
435
|
+
**Action: link**
|
|
436
|
+
|
|
437
|
+
Create an edge between two entries.
|
|
438
|
+
|
|
439
|
+
```
|
|
440
|
+
knowledge_graph with action "link", source "projects/backend.md", target "decisions/use-jwt.md", rel_type "depends_on", strength 0.8
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
**Action: unlink**
|
|
444
|
+
|
|
445
|
+
Remove an edge.
|
|
446
|
+
|
|
447
|
+
```
|
|
448
|
+
knowledge_graph with action "unlink", source "projects/backend.md", target "decisions/use-jwt.md"
|
|
449
|
+
knowledge_graph with action "unlink", source "projects/backend.md", target "decisions/use-jwt.md", rel_type "depends_on"
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
**Action: list**
|
|
453
|
+
|
|
454
|
+
List edges, optionally filtered by entry or relationship type.
|
|
455
|
+
|
|
456
|
+
```
|
|
457
|
+
knowledge_graph with action "list"
|
|
458
|
+
knowledge_graph with action "list", entry "projects/backend.md"
|
|
459
|
+
knowledge_graph with action "list", rel_type "depends_on"
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
**Action: traverse**
|
|
463
|
+
|
|
464
|
+
BFS traversal from a starting entry. Returns a graph of connected entries.
|
|
465
|
+
|
|
466
|
+
```
|
|
467
|
+
knowledge_graph with action "traverse", entry "projects/backend.md"
|
|
468
|
+
knowledge_graph with action "traverse", entry "projects/backend.md", depth 3
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
---
|
|
472
|
+
|
|
473
|
+
### knowledge_analyze
|
|
474
|
+
|
|
475
|
+
Analysis tools for knowledge base maintenance.
|
|
476
|
+
|
|
477
|
+
**Parameters:**
|
|
478
|
+
|
|
479
|
+
| Name | Type | Required | Description |
|
|
480
|
+
| ------------- | ------ | -------- | ---------------------------------------------------------- |
|
|
481
|
+
| `action` | string | Yes | One of: `consolidate`, `reflect` |
|
|
482
|
+
| `category` | string | No | Scan only this category (omit for all) |
|
|
483
|
+
| `threshold` | number | No | [consolidate] Similarity threshold 0-1 (default: 0.5) |
|
|
484
|
+
| `max_entries` | number | No | [reflect] Max unconnected entries to include (default: 20) |
|
|
485
|
+
|
|
486
|
+
**Action: consolidate**
|
|
487
|
+
|
|
488
|
+
Find near-duplicate entries using TF-IDF similarity.
|
|
489
|
+
|
|
490
|
+
```
|
|
491
|
+
knowledge_analyze with action "consolidate"
|
|
492
|
+
knowledge_analyze with action "consolidate", category "projects", threshold 0.7
|
|
493
|
+
```
|
|
494
|
+
|
|
495
|
+
Returns clusters of similar entries that may be candidates for merging.
|
|
496
|
+
|
|
497
|
+
**Action: reflect**
|
|
498
|
+
|
|
499
|
+
Find entries with no graph connections and generate a structured prompt for linking them.
|
|
500
|
+
|
|
501
|
+
```
|
|
502
|
+
knowledge_analyze with action "reflect"
|
|
503
|
+
knowledge_analyze with action "reflect", category "decisions", max_entries 10
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
Returns unconnected entries and suggested relationships to investigate.
|
|
507
|
+
|
|
508
|
+
---
|
|
509
|
+
|
|
510
|
+
## 6. REST API Reference
|
|
511
|
+
|
|
512
|
+
The REST API is served by the dashboard. All responses include CORS headers. Rate limited: 100 requests/minute general, 20 requests/minute for search/analyze endpoints.
|
|
513
|
+
|
|
514
|
+
### Health
|
|
515
|
+
|
|
516
|
+
```
|
|
517
|
+
GET /health Status, version, uptime, knowledge entry count
|
|
518
|
+
```
|
|
519
|
+
|
|
520
|
+
### Knowledge Entries
|
|
521
|
+
|
|
522
|
+
```
|
|
523
|
+
GET /api/knowledge List entries (?category=&tag=)
|
|
524
|
+
GET /api/knowledge/:path Read entry content (enriched with score data)
|
|
525
|
+
GET /api/knowledge/:path/links Get graph edges for an entry
|
|
526
|
+
GET /api/knowledge/search Search entries (?q=&category=&max_results=)
|
|
527
|
+
GET /api/knowledge/consolidate Find duplicates (?category=&threshold=)
|
|
528
|
+
GET /api/knowledge/reflect Find unconnected entries (?category=&max_entries=)
|
|
529
|
+
```
|
|
530
|
+
|
|
531
|
+
### Sessions
|
|
532
|
+
|
|
533
|
+
```
|
|
534
|
+
GET /api/sessions List sessions (?project=&limit=&offset=)
|
|
535
|
+
GET /api/sessions/:id Get session messages (?project=&include_tools=&tail=)
|
|
536
|
+
GET /api/sessions/:id/summary Get session summary (?project=)
|
|
537
|
+
GET /api/sessions/search Search sessions (?q=&role=&max_results=&ranked=&project=&semantic=)
|
|
538
|
+
GET /api/sessions/recall Scoped recall (?scope=&q=&max_results=&project=)
|
|
539
|
+
```
|
|
540
|
+
|
|
541
|
+
### Index Status
|
|
542
|
+
|
|
543
|
+
```
|
|
544
|
+
GET /api/index-status Vector store statistics
|
|
545
|
+
```
|
|
546
|
+
|
|
547
|
+
### Example Requests
|
|
548
|
+
|
|
549
|
+
```bash
|
|
550
|
+
# Health check
|
|
551
|
+
curl http://localhost:3423/health
|
|
552
|
+
|
|
553
|
+
# List all knowledge entries
|
|
554
|
+
curl http://localhost:3423/api/knowledge
|
|
555
|
+
|
|
556
|
+
# Read a specific entry
|
|
557
|
+
curl http://localhost:3423/api/knowledge/projects/backend.md
|
|
558
|
+
|
|
559
|
+
# Search knowledge
|
|
560
|
+
curl "http://localhost:3423/api/knowledge/search?q=authentication&max_results=5"
|
|
561
|
+
|
|
562
|
+
# Search sessions
|
|
563
|
+
curl "http://localhost:3423/api/sessions/search?q=deploy+error&role=assistant&max_results=10"
|
|
564
|
+
|
|
565
|
+
# Scoped recall
|
|
566
|
+
curl "http://localhost:3423/api/sessions/recall?scope=errors&q=ECONNREFUSED"
|
|
567
|
+
|
|
568
|
+
# List sessions for a project
|
|
569
|
+
curl "http://localhost:3423/api/sessions?project=backend&limit=20"
|
|
570
|
+
```
|
|
571
|
+
|
|
572
|
+
---
|
|
573
|
+
|
|
574
|
+
## 7. Knowledge Base Management
|
|
575
|
+
|
|
576
|
+
### Entry Format
|
|
577
|
+
|
|
578
|
+
Knowledge entries are Markdown files with optional YAML frontmatter:
|
|
579
|
+
|
|
580
|
+
```markdown
|
|
581
|
+
---
|
|
582
|
+
tags: [auth, security, jwt]
|
|
583
|
+
---
|
|
584
|
+
|
|
585
|
+
# JWT Authentication
|
|
586
|
+
|
|
587
|
+
We use JWT with refresh tokens for stateless authentication...
|
|
588
|
+
```
|
|
589
|
+
|
|
590
|
+
### Categories
|
|
591
|
+
|
|
592
|
+
Entries are organized into categories (directories):
|
|
593
|
+
|
|
594
|
+
| Category | Purpose |
|
|
595
|
+
| ----------- | ---------------------------------------- |
|
|
596
|
+
| `projects` | Project context, architecture, team info |
|
|
597
|
+
| `people` | Team members, contacts, roles |
|
|
598
|
+
| `decisions` | Architecture decisions, trade-offs |
|
|
599
|
+
| `workflows` | Processes, CI/CD, deployment procedures |
|
|
600
|
+
| `notes` | General notes, observations |
|
|
601
|
+
|
|
602
|
+
### Git Sync
|
|
603
|
+
|
|
604
|
+
The knowledge base is optionally backed by a git repository. When configured:
|
|
605
|
+
|
|
606
|
+
- `knowledge(action: "read")` does a `git pull` before reading.
|
|
607
|
+
- `knowledge(action: "write")` does a `git pull` before writing, then `git push` after.
|
|
608
|
+
- `knowledge(action: "sync")` does a manual pull + push.
|
|
609
|
+
|
|
610
|
+
Configure the git remote:
|
|
611
|
+
|
|
612
|
+
```
|
|
613
|
+
knowledge_admin with action "config", git_url "https://github.com/user/memory.git"
|
|
614
|
+
```
|
|
615
|
+
|
|
616
|
+
### Scoring and Maturity
|
|
617
|
+
|
|
618
|
+
Entries have a confidence score that increases with access:
|
|
619
|
+
|
|
620
|
+
| Maturity | Description |
|
|
621
|
+
| ------------- | -------------------------------------- |
|
|
622
|
+
| `candidate` | New entry, not yet validated |
|
|
623
|
+
| `established` | Accessed multiple times, gaining trust |
|
|
624
|
+
| `proven` | Frequently accessed, high confidence |
|
|
625
|
+
|
|
626
|
+
Scores include a decay factor -- entries not accessed recently receive lower rankings in search results. The decay is based on time since last access.
|
|
627
|
+
|
|
628
|
+
### Auto-Linking
|
|
629
|
+
|
|
630
|
+
When writing a new entry, agent-knowledge automatically:
|
|
631
|
+
|
|
632
|
+
1. Generates embeddings for the content.
|
|
633
|
+
2. Searches for similar existing entries via vector similarity.
|
|
634
|
+
3. Creates `related_to` edges for entries with cosine similarity > 0.7 (up to 3 links).
|
|
635
|
+
|
|
636
|
+
Auto-linked entries appear in the write response.
|
|
637
|
+
|
|
638
|
+
### Duplicate Detection
|
|
639
|
+
|
|
640
|
+
On write, TF-IDF similarity is checked against existing entries. If similar entries are found, a `similarEntries` warning is included in the response. This helps avoid knowledge fragmentation.
|
|
641
|
+
|
|
642
|
+
### Session Distillation
|
|
643
|
+
|
|
644
|
+
On server startup (when `auto_distill` is enabled), past sessions are automatically scanned and distilled into knowledge entries. The distillation process:
|
|
645
|
+
|
|
646
|
+
1. Parses session files from all configured sources.
|
|
647
|
+
2. Extracts key insights, decisions, and patterns.
|
|
648
|
+
3. Scrubs secrets (API keys, tokens, passwords) from the content.
|
|
649
|
+
4. Writes distilled entries to the `projects/` category.
|
|
650
|
+
|
|
651
|
+
---
|
|
652
|
+
|
|
653
|
+
## 8. Session Search
|
|
654
|
+
|
|
655
|
+
### Supported Sources
|
|
656
|
+
|
|
657
|
+
Sessions are auto-discovered from installed AI coding tools:
|
|
658
|
+
|
|
659
|
+
| Tool | Location |
|
|
660
|
+
| ----------- | ------------------------------------------------- |
|
|
661
|
+
| Claude Code | `$KNOWLEDGE_DATA_DIR/projects/` (JSONL files) |
|
|
662
|
+
| Cursor | `~/.cursor/projects/*/agent-transcripts/` (JSONL) |
|
|
663
|
+
| OpenCode | `~/.local/share/opencode/opencode.db` (SQLite) |
|
|
664
|
+
|
|
665
|
+
Additional roots can be added via `EXTRA_SESSION_ROOTS` (comma-separated paths).
|
|
666
|
+
|
|
667
|
+
### Search Modes
|
|
668
|
+
|
|
669
|
+
**General search** finds matches across all sessions and knowledge entries:
|
|
670
|
+
|
|
671
|
+
```
|
|
672
|
+
knowledge_search with query "authentication"
|
|
673
|
+
```
|
|
674
|
+
|
|
675
|
+
**Scoped recall** targets specific domains within sessions:
|
|
676
|
+
|
|
677
|
+
```
|
|
678
|
+
knowledge_search with query "ECONNREFUSED", scope "errors"
|
|
679
|
+
```
|
|
680
|
+
|
|
681
|
+
### Ranking
|
|
682
|
+
|
|
683
|
+
Results are ranked using a hybrid approach:
|
|
684
|
+
|
|
685
|
+
1. **TF-IDF**: Term frequency-inverse document frequency scoring.
|
|
686
|
+
2. **Semantic**: Cosine similarity between query and document embeddings (when available).
|
|
687
|
+
3. **Combined**: Weighted blend of both scores (configurable via `embeddingAlpha` in config).
|
|
688
|
+
|
|
689
|
+
Set `semantic: false` to use pure TF-IDF, or `ranked: false` for regex-based matching.
|
|
690
|
+
|
|
691
|
+
### Embedding Providers
|
|
692
|
+
|
|
693
|
+
Semantic search requires an embedding provider. Supported providers (auto-detected):
|
|
694
|
+
|
|
695
|
+
| Provider | Environment Variable |
|
|
696
|
+
| ------------- | ---------------------- |
|
|
697
|
+
| Claude/Voyage | `ANTHROPIC_API_KEY` |
|
|
698
|
+
| OpenAI | `OPENAI_API_KEY` |
|
|
699
|
+
| Gemini | `GOOGLE_API_KEY` |
|
|
700
|
+
| Local | (fallback, no API key) |
|
|
701
|
+
|
|
702
|
+
If no provider is available, search falls back to pure TF-IDF.
|
|
703
|
+
|
|
704
|
+
---
|
|
705
|
+
|
|
706
|
+
## 9. Troubleshooting
|
|
707
|
+
|
|
708
|
+
### Dashboard Won't Start
|
|
709
|
+
|
|
710
|
+
**Symptom:** Port 3423 already in use.
|
|
711
|
+
|
|
712
|
+
**Solutions:**
|
|
713
|
+
|
|
714
|
+
1. Set `KNOWLEDGE_PORT=3424` in the MCP config env.
|
|
715
|
+
2. Multiple MCP instances share the same database. Only one serves the dashboard.
|
|
716
|
+
|
|
717
|
+
### Search Returns No Results
|
|
718
|
+
|
|
719
|
+
**Causes and solutions:**
|
|
720
|
+
|
|
721
|
+
- **No sessions found**: Check that `KNOWLEDGE_DATA_DIR` points to the correct directory. Verify session files exist.
|
|
722
|
+
- **Embeddings not available**: Semantic search requires an API key. Check the embedding provider configuration.
|
|
723
|
+
- **Index not built**: Background indexing runs 5 seconds after startup. Wait for it to complete. Check stderr for `[knowledge] Background index` messages.
|
|
724
|
+
|
|
725
|
+
### Git Sync Fails
|
|
726
|
+
|
|
727
|
+
**Symptom:** Push or pull errors.
|
|
728
|
+
|
|
729
|
+
**Solutions:**
|
|
730
|
+
|
|
731
|
+
- Verify the git remote URL is correct and accessible.
|
|
732
|
+
- Ensure git credentials are configured (SSH keys or credential helper).
|
|
733
|
+
- Git operations have a 30-second timeout to prevent hangs.
|
|
734
|
+
- Run `knowledge(action: "sync")` manually to diagnose.
|
|
735
|
+
|
|
736
|
+
### Vector Store Issues
|
|
737
|
+
|
|
738
|
+
**Symptom:** Large database file, slow searches, or embedding errors.
|
|
739
|
+
|
|
740
|
+
**Solutions:**
|
|
741
|
+
|
|
742
|
+
- The vector store uses SQLite and can grow large with many sessions. Check size via `knowledge_admin(action: "status")`.
|
|
743
|
+
- If the embedding provider changes, rebuild embeddings: `knowledge_admin(action: "rebuild_embeddings")`.
|
|
744
|
+
- If the database is corrupted, delete `knowledge-vectors.db` and associated WAL files. Embeddings will be rebuilt on next startup.
|
|
745
|
+
|
|
746
|
+
### Memory Directory Not Found
|
|
747
|
+
|
|
748
|
+
**Symptom:** Errors about missing knowledge base directory.
|
|
749
|
+
|
|
750
|
+
**Solutions:**
|
|
751
|
+
|
|
752
|
+
- The default directory is `~/agent-knowledge/`. Create it manually or let the git clone create it.
|
|
753
|
+
- Override via `KNOWLEDGE_MEMORY_DIR` or `knowledge_admin(action: "config", memory_dir: "/path")`.
|
|
754
|
+
|
|
755
|
+
---
|
|
756
|
+
|
|
757
|
+
## 10. FAQ
|
|
758
|
+
|
|
759
|
+
### Can I use this with Cursor/OpenCode?
|
|
760
|
+
|
|
761
|
+
Yes. agent-knowledge is a standard MCP server. It also auto-discovers sessions from Cursor and OpenCode installations, so you can search across all your AI coding sessions regardless of which tool created them.
|
|
762
|
+
|
|
763
|
+
### Where are knowledge entries stored?
|
|
764
|
+
|
|
765
|
+
In `~/agent-knowledge/` by default (configurable via `KNOWLEDGE_MEMORY_DIR`). Entries are plain Markdown files with YAML frontmatter, organized in category subdirectories.
|
|
766
|
+
|
|
767
|
+
### How does git sync work?
|
|
768
|
+
|
|
769
|
+
When a git URL is configured, the knowledge directory is a git repository. Reads trigger `git pull`, writes trigger `git pull` + `git push`. This keeps the knowledge base synchronized across machines.
|
|
770
|
+
|
|
771
|
+
### What happens without an embedding provider?
|
|
772
|
+
|
|
773
|
+
Search falls back to pure TF-IDF (keyword-based). Semantic features (vector similarity, auto-linking) are disabled. The system still works well for exact and fuzzy keyword matching.
|
|
774
|
+
|
|
775
|
+
### How do I add support for another AI tool's sessions?
|
|
776
|
+
|
|
777
|
+
Implement the `SessionAdapter` interface in `src/sessions/adapters/`. The adapter registry auto-detects new adapters on startup. Each adapter defines how to find and parse session files for a specific tool.
|
|
778
|
+
|
|
779
|
+
### Can I share knowledge across machines?
|
|
780
|
+
|
|
781
|
+
Yes. Configure a git remote via `knowledge_admin(action: "config", git_url: "...")`. All writes are automatically pushed to the remote. On startup and before reads, the latest changes are pulled.
|
|
782
|
+
|
|
783
|
+
### How large can the vector store get?
|
|
784
|
+
|
|
785
|
+
The vector store grows with the number of indexed entries (knowledge + sessions). Each entry generates multiple chunks with embedding vectors. The `knowledge_admin(action: "status")` tool shows the current database size and entry counts.
|
|
786
|
+
|
|
787
|
+
### What is the difference between knowledge_search and knowledge_session?
|
|
788
|
+
|
|
789
|
+
- `knowledge_search` is for finding information: it searches across both sessions and knowledge entries, ranking results by relevance.
|
|
790
|
+
- `knowledge_session` is for browsing sessions: listing them, reading their messages, or getting summaries.
|
|
791
|
+
|
|
792
|
+
### How are secrets scrubbed during distillation?
|
|
793
|
+
|
|
794
|
+
The distillation process applies regex patterns to detect and remove common secret formats (API keys, tokens, passwords, connection strings) before writing knowledge entries. This prevents accidental persistence of sensitive data.
|
|
795
|
+
|
|
796
|
+
### Can I disable auto-distillation?
|
|
797
|
+
|
|
798
|
+
Yes. Set `KNOWLEDGE_AUTO_DISTILL=false` as an environment variable, or use `knowledge_admin(action: "config", auto_distill: false)`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agent-knowledge",
|
|
3
|
-
"version": "1.3.
|
|
3
|
+
"version": "1.3.8",
|
|
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",
|