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/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,123 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.3.1 (2026-03-30)
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
|
|
7
|
+
- **DRY constants** — `CATEGORIES` now defined once in `knowledge/store.ts`, imported by `tool-handlers.ts` and `server.ts`
|
|
8
|
+
- **Type-safe session parsing** — extracted `extractText()` helper in `parser.ts`, replacing 3 repeated unsafe `as unknown[]` cast blocks with a single type-guarded function
|
|
9
|
+
- **Stale doc fix** — CLAUDE.md `knowledge_sync` → `knowledge(action: 'sync')`
|
|
10
|
+
|
|
11
|
+
## 1.3.0 (2026-03-29)
|
|
12
|
+
|
|
13
|
+
### Further Tool Consolidation (11 → 6)
|
|
14
|
+
|
|
15
|
+
Reduced MCP tool count from 11 to 6 by merging remaining individual tools into action-based interfaces.
|
|
16
|
+
|
|
17
|
+
- **`knowledge`** (was 5 tools: `knowledge_list`, `knowledge_read`, `knowledge_write`, `knowledge_delete`, `knowledge_sync`) — actions: `list`, `read`, `write`, `delete`, `sync`
|
|
18
|
+
- **`knowledge_search`** now handles scoped recall too — when `scope` is provided (errors, plans, configs, tools, files, decisions), behaves as the former `knowledge_recall`
|
|
19
|
+
|
|
20
|
+
### MCP Tools (6)
|
|
21
|
+
|
|
22
|
+
**Knowledge (1):** `knowledge` (actions: list, read, write, delete, sync)
|
|
23
|
+
|
|
24
|
+
**Search (1):** `knowledge_search` (general search + scoped recall via `scope` param)
|
|
25
|
+
|
|
26
|
+
**Sessions (1):** `knowledge_session` (actions: list, get, summary)
|
|
27
|
+
|
|
28
|
+
**Knowledge Graph (1):** `knowledge_graph` (actions: link, unlink, list, traverse)
|
|
29
|
+
|
|
30
|
+
**Analysis (1):** `knowledge_analyze` (actions: consolidate, reflect)
|
|
31
|
+
|
|
32
|
+
**Admin (1):** `knowledge_admin` (actions: status, config)
|
|
33
|
+
|
|
34
|
+
## 1.3.0 (2026-03-29)
|
|
35
|
+
|
|
36
|
+
### Tool Consolidation (18 → 11)
|
|
37
|
+
|
|
38
|
+
Reduced MCP tool count from 18 to 11 by merging related tools into action-based interfaces. All functionality is preserved — tools are routed by the `action` parameter.
|
|
39
|
+
|
|
40
|
+
- **`knowledge_graph`** (was 4 tools: `knowledge_link`, `knowledge_unlink`, `knowledge_links`, `knowledge_graph`) — actions: `link`, `unlink`, `list`, `traverse`
|
|
41
|
+
- **`knowledge_session`** (was 3 tools: `knowledge_sessions`, `knowledge_get`, `knowledge_summary`) — actions: `list`, `get`, `summary`
|
|
42
|
+
- **`knowledge_analyze`** (was 2 tools: `knowledge_consolidate`, `knowledge_reflect`) — actions: `consolidate`, `reflect`
|
|
43
|
+
- **`knowledge_admin`** (was 2 tools: `knowledge_index_status`, `knowledge_config`) — actions: `status`, `config`
|
|
44
|
+
|
|
45
|
+
### MCP Tools (11)
|
|
46
|
+
|
|
47
|
+
**Knowledge (5):** `knowledge_list`, `knowledge_read`, `knowledge_write`, `knowledge_delete`, `knowledge_sync`
|
|
48
|
+
|
|
49
|
+
**Knowledge Graph (1):** `knowledge_graph` (actions: link, unlink, list, traverse)
|
|
50
|
+
|
|
51
|
+
**Sessions (3):** `knowledge_session` (actions: list, get, summary), `knowledge_search`, `knowledge_recall`
|
|
52
|
+
|
|
53
|
+
**Analysis (1):** `knowledge_analyze` (actions: consolidate, reflect)
|
|
54
|
+
|
|
55
|
+
**Admin (1):** `knowledge_admin` (actions: status, config)
|
|
56
|
+
|
|
57
|
+
## 1.3.0 (2026-03-29)
|
|
58
|
+
|
|
59
|
+
### Memory Consolidation / Dedup
|
|
60
|
+
|
|
61
|
+
`knowledge_write` now checks for near-duplicate entries using TF-IDF similarity after writing. If any existing entry exceeds a 0.6 similarity threshold, a warning is included in the response with paths and scores.
|
|
62
|
+
|
|
63
|
+
- **`knowledge_analyze(action: "consolidate")`** — scans entries in a category (or all), groups near-duplicates into clusters using TF-IDF similarity > 0.5 (configurable), returns clusters with pairwise similarity scores. Read-only analysis.
|
|
64
|
+
- **Dashboard**: "Duplicates" button in Knowledge tab header triggers consolidation scan. Entries in duplicate clusters show a warning icon. Clicking opens a panel with cluster details and similarity scores.
|
|
65
|
+
|
|
66
|
+
### Reflection Cycle
|
|
67
|
+
|
|
68
|
+
- **`knowledge_analyze(action: "reflect")`** — finds knowledge entries with zero graph edges and prepares a structured prompt for the agent's LLM to identify new connections. Returns unconnected entries with content summaries, connected entries as potential link targets, and a ready-to-use prompt.
|
|
69
|
+
- Does NOT call an LLM itself — the agent processes the prompt and calls `knowledge_graph(action: "link")` based on the analysis.
|
|
70
|
+
- **Dashboard**: "Reflect" button in Knowledge tab header shows unconnected entries in a panel with summaries and suggested instructions.
|
|
71
|
+
|
|
72
|
+
### MCP Tools (11)
|
|
73
|
+
|
|
74
|
+
**Knowledge (5):** `knowledge_list`, `knowledge_read`, `knowledge_write`, `knowledge_delete`, `knowledge_sync`
|
|
75
|
+
|
|
76
|
+
**Knowledge Graph (1):** `knowledge_graph` (actions: link, unlink, list, traverse)
|
|
77
|
+
|
|
78
|
+
**Sessions (3):** `knowledge_session` (actions: list, get, summary), `knowledge_search`, `knowledge_recall`
|
|
79
|
+
|
|
80
|
+
**Analysis (1):** `knowledge_analyze` (actions: consolidate, reflect)
|
|
81
|
+
|
|
82
|
+
**Admin (1):** `knowledge_admin` (actions: status, config)
|
|
83
|
+
|
|
84
|
+
## 1.2.0 (2026-03-29)
|
|
85
|
+
|
|
86
|
+
### Knowledge Graph
|
|
87
|
+
|
|
88
|
+
New relationship layer for connecting knowledge entries. Edges are stored in a dedicated `edges` SQLite table with 8 typed relationships: `related_to`, `supersedes`, `depends_on`, `contradicts`, `specializes`, `part_of`, `alternative_to`, `builds_on`.
|
|
89
|
+
|
|
90
|
+
- **`knowledge_graph(action: "link")`** — create or update a weighted edge between two entries
|
|
91
|
+
- **`knowledge_graph(action: "unlink")`** — remove edges (optionally filtered by relationship type)
|
|
92
|
+
- **`knowledge_graph(action: "list")`** — list edges for an entry or relationship type
|
|
93
|
+
- **`knowledge_graph(action: "traverse")`** — BFS traversal from a starting entry to configurable depth
|
|
94
|
+
- **`knowledge_read`** now shows related entries alongside content
|
|
95
|
+
|
|
96
|
+
### Confidence & Decay Scoring
|
|
97
|
+
|
|
98
|
+
New `entry_scores` SQLite table tracks access frequency and recency. Search results are ranked using:
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
finalScore = baseRelevance * 0.5^(daysSinceLastAccess / 90) * maturityMultiplier
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
- **Auto-promotion**: entries mature from candidate (0.5x) to established (1.0x) at 5 accesses, then to proven (1.5x) at 20 accesses
|
|
105
|
+
- Frequently accessed entries rise in rankings; stale entries decay over time
|
|
106
|
+
|
|
107
|
+
### Auto-linking on Write
|
|
108
|
+
|
|
109
|
+
`knowledge_write` now automatically finds the top-3 most similar existing entries via cosine similarity and creates `related_to` edges for any pair scoring above 0.7. This builds the knowledge graph organically as entries are added.
|
|
110
|
+
|
|
111
|
+
### MCP Tools (11)
|
|
112
|
+
|
|
113
|
+
**Knowledge (5):** `knowledge_list`, `knowledge_read`, `knowledge_write`, `knowledge_delete`, `knowledge_sync`
|
|
114
|
+
|
|
115
|
+
**Knowledge Graph (1):** `knowledge_graph` (actions: link, unlink, list, traverse)
|
|
116
|
+
|
|
117
|
+
**Sessions (3):** `knowledge_session` (actions: list, get, summary), `knowledge_search`, `knowledge_recall`
|
|
118
|
+
|
|
119
|
+
**Admin (1):** `knowledge_admin` (actions: status, config)
|
|
120
|
+
|
|
3
121
|
## 1.1.1 (2026-03-28)
|
|
4
122
|
|
|
5
123
|
### Bug Fixes
|
|
@@ -42,13 +160,13 @@ Removed Claude Code-specific language throughout. agent-knowledge is now fully c
|
|
|
42
160
|
|
|
43
161
|
Initial release.
|
|
44
162
|
|
|
45
|
-
### MCP Tools (
|
|
163
|
+
### MCP Tools (11)
|
|
46
164
|
|
|
47
165
|
**Knowledge (5):** `knowledge_list`, `knowledge_read`, `knowledge_write`, `knowledge_delete`, `knowledge_sync`
|
|
48
166
|
|
|
49
|
-
**Sessions (
|
|
167
|
+
**Sessions (3):** `knowledge_session` (actions: list, get, summary), `knowledge_search`, `knowledge_recall`
|
|
50
168
|
|
|
51
|
-
**Admin (
|
|
169
|
+
**Admin (1):** `knowledge_admin` (actions: status, config)
|
|
52
170
|
|
|
53
171
|
### Search Engine
|
|
54
172
|
|
|
@@ -72,7 +190,7 @@ Initial release.
|
|
|
72
190
|
- 5 categories: projects, people, decisions, workflows, notes
|
|
73
191
|
- YAML frontmatter for metadata (title, tags, updated)
|
|
74
192
|
- Auto git commit + push on writes, pull on reads
|
|
75
|
-
- Configurable git URL via `
|
|
193
|
+
- Configurable git URL via `knowledge_admin(action: "config")` tool or `KNOWLEDGE_GIT_URL` env var
|
|
76
194
|
- New repos auto-scaffolded with README, .gitignore, and category dirs
|
|
77
195
|
|
|
78
196
|
### Auto-Distillation
|
|
@@ -86,7 +204,7 @@ Initial release.
|
|
|
86
204
|
|
|
87
205
|
### Persistent Configuration
|
|
88
206
|
|
|
89
|
-
- `
|
|
207
|
+
- `knowledge_admin(action: "config")` for runtime setup (no restart needed)
|
|
90
208
|
- Config stored at XDG/AppData location (tool-agnostic)
|
|
91
209
|
- Priority: env vars > persisted config > defaults
|
|
92
210
|
|
package/README.md
CHANGED
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
[](LICENSE)
|
|
4
4
|
[](https://nodejs.org)
|
|
5
|
-
[]()
|
|
6
|
+
[]()
|
|
7
7
|
|
|
8
8
|
**Cross-session memory and recall for AI coding assistants** -- works with Claude Code, Cursor, OpenCode, Cline, Continue.dev, and Aider out of the box. Git-synced knowledge base, hybrid semantic+TF-IDF search, auto-distillation with secrets scrubbing.
|
|
9
9
|
|
|
@@ -52,10 +52,16 @@ No configuration needed. Additional session roots can be added via the `EXTRA_SE
|
|
|
52
52
|
- **Embeddings** -- local (Hugging Face), OpenAI, Claude/Voyage, or Gemini providers
|
|
53
53
|
- **Fuzzy matching** -- typo-tolerant search using Levenshtein distance
|
|
54
54
|
- **6 search scopes** -- errors, plans, configs, tools, files, decisions
|
|
55
|
-
- **
|
|
55
|
+
- **6 MCP tools** -- consolidated action-based interface (knowledge, knowledge_search, knowledge_session, knowledge_graph, knowledge_analyze, knowledge_admin)
|
|
56
|
+
- **Configurable git URL** -- `knowledge_admin(action: "config")` for runtime setup, persisted at XDG/AppData location
|
|
56
57
|
- **Cross-machine persistence** -- knowledge syncs via git, sessions read from local storage of each tool
|
|
57
58
|
- **Real-time dashboard** -- browse, search, and manage at `localhost:3423`
|
|
58
59
|
- **Secrets scrubbing** -- API keys, tokens, passwords, private keys automatically redacted before git push
|
|
60
|
+
- **Knowledge graph** -- relationship edges between entries (related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on) with BFS traversal
|
|
61
|
+
- **Confidence/decay scoring** -- entries scored by access frequency and recency; auto-promotion from candidate to established to proven
|
|
62
|
+
- **Memory consolidation** -- TF-IDF duplicate detection on write (warns of similar entries) plus `knowledge_analyze(action: "consolidate")` for batch dedup scanning
|
|
63
|
+
- **Reflection cycle** -- `knowledge_analyze(action: "reflect")` surfaces unconnected entries and generates structured prompts for the agent to identify new graph connections
|
|
64
|
+
- **Auto-linking on write** -- new entries automatically linked to top-3 similar existing entries when cosine similarity > 0.7
|
|
59
65
|
|
|
60
66
|
## Quick Start
|
|
61
67
|
|
|
@@ -87,34 +93,59 @@ claude mcp add agent-knowledge -s user \
|
|
|
87
93
|
|
|
88
94
|
Dashboard: **http://localhost:3423** (auto-starts with MCP server)
|
|
89
95
|
|
|
90
|
-
## MCP Tools
|
|
96
|
+
## MCP Tools (6)
|
|
91
97
|
|
|
92
98
|
### Knowledge Base
|
|
93
99
|
|
|
94
|
-
| Tool
|
|
95
|
-
|
|
|
96
|
-
| `
|
|
97
|
-
| `
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
100
|
+
| Tool | Action | Description | Parameters |
|
|
101
|
+
| ----------- | -------- | ----------------------------------- | ------------------------------------------------ |
|
|
102
|
+
| `knowledge` | `list` | List entries by category and/or tag | `category?`, `tag?` |
|
|
103
|
+
| | `read` | Read a specific entry | `path` (required) |
|
|
104
|
+
| | `write` | Create/update entry (auto git sync) | `category`, `filename`, `content` (all required) |
|
|
105
|
+
| | `delete` | Delete an entry (auto git sync) | `path` (required) |
|
|
106
|
+
| | `sync` | Manual git pull + push | -- |
|
|
101
107
|
|
|
102
|
-
###
|
|
108
|
+
### Search
|
|
103
109
|
|
|
104
|
-
| Tool
|
|
105
|
-
|
|
|
106
|
-
| `
|
|
107
|
-
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
110
|
+
| Tool | Description | Parameters |
|
|
111
|
+
| ------------------ | ----------------------------------------------- | ------------------------------------------------------- |
|
|
112
|
+
| `knowledge_search` | Hybrid semantic + TF-IDF search across sessions | `query`, `project?`, `role?`, `max_results?`, `ranked?` |
|
|
113
|
+
| | Scoped recall (when `scope` is provided) | `query`, `scope`, `project?`, `max_results?` |
|
|
114
|
+
|
|
115
|
+
Scopes: `errors`, `plans`, `configs`, `tools`, `files`, `decisions`, `all`.
|
|
116
|
+
|
|
117
|
+
### Sessions
|
|
118
|
+
|
|
119
|
+
| Tool | Action | Description | Parameters |
|
|
120
|
+
| ------------------- | --------- | -------------------------------------- | --------------------------------------------------- |
|
|
121
|
+
| `knowledge_session` | `list` | List sessions with metadata | `project?` |
|
|
122
|
+
| | `get` | Retrieve full session conversation | `session_id`, `project?`, `include_tools?`, `tail?` |
|
|
123
|
+
| | `summary` | Session summary (topics, tools, files) | `session_id`, `project?` |
|
|
124
|
+
|
|
125
|
+
### Knowledge Graph
|
|
126
|
+
|
|
127
|
+
| Tool | Action | Description | Parameters |
|
|
128
|
+
| ----------------- | ---------- | ---------------------------------- | ------------------------------------------- |
|
|
129
|
+
| `knowledge_graph` | `link` | Create/update edge between entries | `source`, `target`, `rel_type`, `strength?` |
|
|
130
|
+
| | `unlink` | Remove edges between entries | `source`, `target`, `rel_type?` |
|
|
131
|
+
| | `list` | List edges | `entry?`, `rel_type?` |
|
|
132
|
+
| | `traverse` | BFS traversal from an entry | `entry`, `depth?` |
|
|
133
|
+
|
|
134
|
+
Relationship types: `related_to`, `supersedes`, `depends_on`, `contradicts`, `specializes`, `part_of`, `alternative_to`, `builds_on`.
|
|
135
|
+
|
|
136
|
+
### Analysis
|
|
137
|
+
|
|
138
|
+
| Tool | Action | Description | Parameters |
|
|
139
|
+
| ------------------- | ------------- | ------------------------------------ | --------------------------- |
|
|
140
|
+
| `knowledge_analyze` | `consolidate` | Find near-duplicate entries | `category?`, `threshold?` |
|
|
141
|
+
| | `reflect` | Find unconnected entries for linking | `category?`, `max_entries?` |
|
|
111
142
|
|
|
112
143
|
### Admin
|
|
113
144
|
|
|
114
|
-
| Tool
|
|
115
|
-
|
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
145
|
+
| Tool | Action | Description | Parameters |
|
|
146
|
+
| ----------------- | -------- | ---------------------------- | ------------------------------------------ |
|
|
147
|
+
| `knowledge_admin` | `status` | Vector store statistics | -- |
|
|
148
|
+
| | `config` | View or update configuration | `git_url?`, `memory_dir?`, `auto_distill?` |
|
|
118
149
|
|
|
119
150
|
## REST API
|
|
120
151
|
|
|
@@ -176,6 +207,37 @@ graph LR
|
|
|
176
207
|
DS --> WB
|
|
177
208
|
```
|
|
178
209
|
|
|
210
|
+
## Knowledge Graph
|
|
211
|
+
|
|
212
|
+
Entries can be connected via typed, weighted edges stored in a dedicated `edges` SQLite table. Eight relationship types are supported: `related_to`, `supersedes`, `depends_on`, `contradicts`, `specializes`, `part_of`, `alternative_to`, `builds_on`.
|
|
213
|
+
|
|
214
|
+
- **`knowledge_graph(action: "link")`** creates or updates an edge (with optional strength 0-1)
|
|
215
|
+
- **`knowledge_graph(action: "unlink")`** removes edges (optionally filtered by type)
|
|
216
|
+
- **`knowledge_graph(action: "list")`** lists edges for an entry or relationship type
|
|
217
|
+
- **`knowledge_graph(action: "traverse")`** performs BFS traversal from a starting entry to a configurable depth
|
|
218
|
+
|
|
219
|
+
### Auto-linking
|
|
220
|
+
|
|
221
|
+
When `knowledge_write` creates or updates an entry, it automatically finds the top-3 most similar existing entries via cosine similarity and creates `related_to` edges for any pair scoring above 0.7.
|
|
222
|
+
|
|
223
|
+
## Confidence & Decay Scoring
|
|
224
|
+
|
|
225
|
+
Each knowledge entry has a confidence score tracked in the `entry_scores` SQLite table. Search results are ranked using:
|
|
226
|
+
|
|
227
|
+
```
|
|
228
|
+
finalScore = baseRelevance * 0.5^(daysSinceLastAccess / 90) * maturityMultiplier
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
Entries mature automatically based on access count:
|
|
232
|
+
|
|
233
|
+
| Stage | Accesses | Multiplier |
|
|
234
|
+
| ------------- | -------- | ---------- |
|
|
235
|
+
| `candidate` | < 5 | 0.5x |
|
|
236
|
+
| `established` | 5-19 | 1.0x |
|
|
237
|
+
| `proven` | 20+ | 1.5x |
|
|
238
|
+
|
|
239
|
+
Frequently accessed entries rise in search rankings; stale entries decay over time.
|
|
240
|
+
|
|
179
241
|
## Search Capabilities
|
|
180
242
|
|
|
181
243
|
**TF-IDF Ranking** -- results scored by term frequency-inverse document frequency. Rare terms boost relevance. Global index cached for 60 seconds.
|
|
@@ -196,7 +258,7 @@ graph LR
|
|
|
196
258
|
## Testing
|
|
197
259
|
|
|
198
260
|
```bash
|
|
199
|
-
npm test # Run all
|
|
261
|
+
npm test # Run all 352 tests
|
|
200
262
|
npm run test:watch # Watch mode
|
|
201
263
|
npm run lint # Type-check (tsc --noEmit)
|
|
202
264
|
```
|
package/dist/dashboard.d.ts
CHANGED
package/dist/dashboard.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../src/dashboard.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;
|
|
1
|
+
{"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../src/dashboard.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAmexB,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAKlD;AAED,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAwIlE"}
|
package/dist/dashboard.js
CHANGED
|
@@ -4,6 +4,10 @@ import path from 'path';
|
|
|
4
4
|
import { WebSocketServer, WebSocket } from 'ws';
|
|
5
5
|
import { listEntries, readEntry } from './knowledge/store.js';
|
|
6
6
|
import { searchKnowledge } from './knowledge/search.js';
|
|
7
|
+
import { getEntryScoring, decayFactor, maturityMultiplier } from './knowledge/scoring.js';
|
|
8
|
+
import { getKnowledgeGraph } from './knowledge/graph.js';
|
|
9
|
+
import { consolidate } from './knowledge/consolidate.js';
|
|
10
|
+
import { reflect } from './knowledge/reflect.js';
|
|
7
11
|
import { getProjectDirs, getSessionFiles, parseSessionFile, extractMessages, getSessionMeta, } from './sessions/parser.js';
|
|
8
12
|
import { searchSessions } from './sessions/search.js';
|
|
9
13
|
import { listSessions, getSessionSummary } from './sessions/summary.js';
|
|
@@ -62,7 +66,8 @@ function serveStatic(uiDir, reqPath, res) {
|
|
|
62
66
|
try {
|
|
63
67
|
decoded = decodeURIComponent(filePath);
|
|
64
68
|
}
|
|
65
|
-
catch {
|
|
69
|
+
catch (err) {
|
|
70
|
+
console.error('[knowledge] decode URI:', err instanceof Error ? err.message : err);
|
|
66
71
|
errorResponse(res, 'Bad request', 400);
|
|
67
72
|
return;
|
|
68
73
|
}
|
|
@@ -144,7 +149,8 @@ async function handleApi(pathname, url, res) {
|
|
|
144
149
|
const stats = store.stats();
|
|
145
150
|
jsonResponse(res, stats);
|
|
146
151
|
}
|
|
147
|
-
catch {
|
|
152
|
+
catch (err) {
|
|
153
|
+
console.error('[knowledge] index-status:', err instanceof Error ? err.message : err);
|
|
148
154
|
jsonResponse(res, {
|
|
149
155
|
totalEntries: 0,
|
|
150
156
|
knowledgeEntries: 0,
|
|
@@ -165,21 +171,110 @@ async function handleApi(pathname, url, res) {
|
|
|
165
171
|
category,
|
|
166
172
|
maxResults: maxResults ? parseInt(maxResults, 10) : undefined,
|
|
167
173
|
});
|
|
168
|
-
|
|
174
|
+
try {
|
|
175
|
+
const scoring = getEntryScoring();
|
|
176
|
+
const paths = results.map((r) => r.entry.path);
|
|
177
|
+
const scores = scoring.getScores(paths);
|
|
178
|
+
const enriched = results.map((r) => {
|
|
179
|
+
const score = scores.get(r.entry.path);
|
|
180
|
+
const decay = score?.last_accessed ? decayFactor(score.last_accessed) : 1;
|
|
181
|
+
const matMult = maturityMultiplier(score?.maturity ?? 'candidate');
|
|
182
|
+
return {
|
|
183
|
+
...r,
|
|
184
|
+
maturity: score?.maturity ?? 'candidate',
|
|
185
|
+
access_count: score?.access_count ?? 0,
|
|
186
|
+
decay_factor: decay,
|
|
187
|
+
maturity_multiplier: matMult,
|
|
188
|
+
};
|
|
189
|
+
});
|
|
190
|
+
jsonResponse(res, enriched);
|
|
191
|
+
}
|
|
192
|
+
catch (err) {
|
|
193
|
+
console.error('[knowledge] search enrichment:', err instanceof Error ? err.message : err);
|
|
194
|
+
jsonResponse(res, results);
|
|
195
|
+
}
|
|
196
|
+
return true;
|
|
197
|
+
}
|
|
198
|
+
if (pathname === '/api/knowledge/consolidate') {
|
|
199
|
+
const category = url.searchParams.get('category') || undefined;
|
|
200
|
+
const thresholdParam = url.searchParams.get('threshold');
|
|
201
|
+
const threshold = thresholdParam ? parseFloat(thresholdParam) : 0.5;
|
|
202
|
+
const report = consolidate(memoryDir, category, threshold);
|
|
203
|
+
jsonResponse(res, report);
|
|
204
|
+
return true;
|
|
205
|
+
}
|
|
206
|
+
if (pathname === '/api/knowledge/reflect') {
|
|
207
|
+
const category = url.searchParams.get('category') || undefined;
|
|
208
|
+
const maxParam = url.searchParams.get('max_entries');
|
|
209
|
+
const maxEntries = maxParam ? parseInt(maxParam, 10) : 20;
|
|
210
|
+
const result = reflect(memoryDir, category, maxEntries);
|
|
211
|
+
jsonResponse(res, result);
|
|
169
212
|
return true;
|
|
170
213
|
}
|
|
171
214
|
if (pathname === '/api/knowledge') {
|
|
172
215
|
const category = url.searchParams.get('category') || undefined;
|
|
173
216
|
const tag = url.searchParams.get('tag') || undefined;
|
|
174
217
|
const entries = listEntries(memoryDir, category, tag);
|
|
175
|
-
|
|
218
|
+
// Enrich entries with score data (maturity, access_count)
|
|
219
|
+
try {
|
|
220
|
+
const scoring = getEntryScoring();
|
|
221
|
+
const paths = entries.map((e) => e.path);
|
|
222
|
+
const scores = scoring.getScores(paths);
|
|
223
|
+
const enriched = entries.map((e) => {
|
|
224
|
+
const score = scores.get(e.path);
|
|
225
|
+
return {
|
|
226
|
+
...e,
|
|
227
|
+
maturity: score?.maturity ?? 'candidate',
|
|
228
|
+
access_count: score?.access_count ?? 0,
|
|
229
|
+
last_accessed: score?.last_accessed ?? null,
|
|
230
|
+
};
|
|
231
|
+
});
|
|
232
|
+
jsonResponse(res, enriched);
|
|
233
|
+
}
|
|
234
|
+
catch (err) {
|
|
235
|
+
console.error('[knowledge] entries enrichment:', err instanceof Error ? err.message : err);
|
|
236
|
+
// Fallback: return entries without score data
|
|
237
|
+
jsonResponse(res, entries);
|
|
238
|
+
}
|
|
239
|
+
return true;
|
|
240
|
+
}
|
|
241
|
+
// Links endpoint must be matched before the generic /api/knowledge/:path
|
|
242
|
+
const linksMatch = pathname.match(/^\/api\/knowledge\/(.+)\/links$/);
|
|
243
|
+
if (linksMatch) {
|
|
244
|
+
const entryPath = decodeURIComponent(linksMatch[1]);
|
|
245
|
+
try {
|
|
246
|
+
const graph = getKnowledgeGraph();
|
|
247
|
+
const edges = graph.links(entryPath);
|
|
248
|
+
jsonResponse(res, edges);
|
|
249
|
+
}
|
|
250
|
+
catch (err) {
|
|
251
|
+
console.error('[knowledge] links:', err instanceof Error ? err.message : err);
|
|
252
|
+
jsonResponse(res, []);
|
|
253
|
+
}
|
|
176
254
|
return true;
|
|
177
255
|
}
|
|
178
256
|
if (pathname.startsWith('/api/knowledge/')) {
|
|
179
257
|
const entryPath = decodeURIComponent(pathname.slice('/api/knowledge/'.length));
|
|
180
258
|
if (entryPath) {
|
|
181
259
|
const entry = readEntry(memoryDir, entryPath);
|
|
182
|
-
|
|
260
|
+
// Enrich with score data (no recordAccess — only MCP reads count)
|
|
261
|
+
try {
|
|
262
|
+
const scoring = getEntryScoring();
|
|
263
|
+
const score = scoring.getScore(entryPath);
|
|
264
|
+
const enriched = {
|
|
265
|
+
...entry,
|
|
266
|
+
maturity: score?.maturity ?? 'candidate',
|
|
267
|
+
access_count: score?.access_count ?? 0,
|
|
268
|
+
last_accessed: score?.last_accessed ?? null,
|
|
269
|
+
decay_factor: score?.last_accessed ? decayFactor(score.last_accessed) : 1,
|
|
270
|
+
maturity_multiplier: maturityMultiplier(score?.maturity ?? 'candidate'),
|
|
271
|
+
};
|
|
272
|
+
jsonResponse(res, enriched);
|
|
273
|
+
}
|
|
274
|
+
catch (err) {
|
|
275
|
+
console.error('[knowledge] entry enrichment:', err instanceof Error ? err.message : err);
|
|
276
|
+
jsonResponse(res, entry);
|
|
277
|
+
}
|
|
183
278
|
return true;
|
|
184
279
|
}
|
|
185
280
|
}
|
|
@@ -189,10 +284,12 @@ async function handleApi(pathname, url, res) {
|
|
|
189
284
|
const maxResults = url.searchParams.get('max_results');
|
|
190
285
|
const ranked = url.searchParams.get('ranked') !== 'false';
|
|
191
286
|
const project = url.searchParams.get('project') || undefined;
|
|
287
|
+
const semantic = url.searchParams.get('semantic') === 'true';
|
|
192
288
|
const results = await searchSessions(q, {
|
|
193
289
|
role: role,
|
|
194
290
|
maxResults: maxResults ? parseInt(maxResults, 10) : 20,
|
|
195
291
|
ranked,
|
|
292
|
+
semantic,
|
|
196
293
|
project,
|
|
197
294
|
});
|
|
198
295
|
jsonResponse(res, results);
|
|
@@ -212,7 +309,15 @@ async function handleApi(pathname, url, res) {
|
|
|
212
309
|
}
|
|
213
310
|
if (pathname === '/api/sessions') {
|
|
214
311
|
const project = url.searchParams.get('project') || undefined;
|
|
215
|
-
const
|
|
312
|
+
const limitParam = url.searchParams.get('limit');
|
|
313
|
+
const offsetParam = url.searchParams.get('offset');
|
|
314
|
+
const limit = limitParam ? Math.min(parseInt(limitParam, 10), 500) : undefined;
|
|
315
|
+
const offset = offsetParam ? parseInt(offsetParam, 10) : 0;
|
|
316
|
+
let sessions = listSessions(project);
|
|
317
|
+
if (offset > 0)
|
|
318
|
+
sessions = sessions.slice(offset);
|
|
319
|
+
if (limit !== undefined)
|
|
320
|
+
sessions = sessions.slice(0, limit);
|
|
216
321
|
jsonResponse(res, sessions);
|
|
217
322
|
return true;
|
|
218
323
|
}
|
|
@@ -274,7 +379,14 @@ function wsBroadcast(data) {
|
|
|
274
379
|
}
|
|
275
380
|
}
|
|
276
381
|
}
|
|
382
|
+
// State snapshot cache — avoid rescanning disk + querying 544MB vector DB on every WS connect
|
|
383
|
+
let _stateCache = null;
|
|
384
|
+
const STATE_CACHE_TTL = 30_000; // 30 seconds
|
|
277
385
|
async function buildStateSnapshot() {
|
|
386
|
+
const now = Date.now();
|
|
387
|
+
if (_stateCache && now - _stateCache.timestamp < STATE_CACHE_TTL) {
|
|
388
|
+
return _stateCache.data;
|
|
389
|
+
}
|
|
278
390
|
const config = getConfig();
|
|
279
391
|
try {
|
|
280
392
|
const knowledge = listEntries(config.memoryDir);
|
|
@@ -283,15 +395,21 @@ async function buildStateSnapshot() {
|
|
|
283
395
|
for (const proj of projects) {
|
|
284
396
|
sessionCount += getSessionFiles(proj.path).length;
|
|
285
397
|
}
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
398
|
+
// Vector count is expensive (544MB DB) — only fetch it if cache is empty
|
|
399
|
+
let vectorCount = _stateCache
|
|
400
|
+
? (_stateCache.data.stats
|
|
401
|
+
?.vector_count ?? 0)
|
|
402
|
+
: 0;
|
|
403
|
+
if (!_stateCache) {
|
|
404
|
+
try {
|
|
405
|
+
const store = new VectorStore();
|
|
406
|
+
vectorCount = store.stats().totalEntries;
|
|
407
|
+
}
|
|
408
|
+
catch (err) {
|
|
409
|
+
console.error('[knowledge] vector store stats:', err instanceof Error ? err.message : err);
|
|
410
|
+
}
|
|
293
411
|
}
|
|
294
|
-
|
|
412
|
+
const data = {
|
|
295
413
|
type: 'state',
|
|
296
414
|
knowledge: knowledge || [],
|
|
297
415
|
stats: {
|
|
@@ -302,8 +420,11 @@ async function buildStateSnapshot() {
|
|
|
302
420
|
version: VERSION,
|
|
303
421
|
},
|
|
304
422
|
};
|
|
423
|
+
_stateCache = { data, timestamp: now };
|
|
424
|
+
return data;
|
|
305
425
|
}
|
|
306
|
-
catch {
|
|
426
|
+
catch (err) {
|
|
427
|
+
console.error('[knowledge] state snapshot:', err instanceof Error ? err.message : err);
|
|
307
428
|
return {
|
|
308
429
|
type: 'state',
|
|
309
430
|
knowledge: [],
|
|
@@ -317,9 +438,14 @@ async function buildStateSnapshot() {
|
|
|
317
438
|
};
|
|
318
439
|
}
|
|
319
440
|
}
|
|
441
|
+
// Invalidate state cache on knowledge writes
|
|
442
|
+
export function invalidateStateCache() {
|
|
443
|
+
_stateCache = null;
|
|
444
|
+
}
|
|
320
445
|
export async function notifyUpdate() {
|
|
321
446
|
if (wsClients.size === 0)
|
|
322
447
|
return;
|
|
448
|
+
invalidateStateCache(); // Force refresh on next snapshot
|
|
323
449
|
const state = await buildStateSnapshot();
|
|
324
450
|
wsBroadcast(state);
|
|
325
451
|
}
|
|
@@ -391,8 +517,8 @@ export function startDashboard(port) {
|
|
|
391
517
|
ws.send(JSON.stringify(state));
|
|
392
518
|
}
|
|
393
519
|
}
|
|
394
|
-
catch {
|
|
395
|
-
|
|
520
|
+
catch (err) {
|
|
521
|
+
console.error('[knowledge] ws init:', err instanceof Error ? err.message : err);
|
|
396
522
|
}
|
|
397
523
|
});
|
|
398
524
|
const heartbeat = setInterval(() => {
|
|
@@ -425,8 +551,8 @@ export function startDashboard(port) {
|
|
|
425
551
|
});
|
|
426
552
|
}
|
|
427
553
|
}
|
|
428
|
-
catch {
|
|
429
|
-
|
|
554
|
+
catch (err) {
|
|
555
|
+
console.error('[knowledge] file watcher:', err instanceof Error ? err.message : err);
|
|
430
556
|
}
|
|
431
557
|
server.on('close', () => {
|
|
432
558
|
clearInterval(heartbeat);
|