agent-knowledge 1.0.0 → 1.0.4
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 +77 -77
- package/LICENSE +21 -21
- package/README.md +191 -191
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/knowledge/git.d.ts.map +1 -1
- package/dist/knowledge/git.js +91 -86
- package/dist/knowledge/git.js.map +1 -1
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js.map +1 -1
- package/dist/ui/app.js +38 -114
- package/dist/ui/index.html +21 -65
- package/dist/ui/styles.css +3 -2
- package/dist/vectorstore/store.d.ts.map +1 -1
- package/dist/vectorstore/store.js +32 -32
- package/dist/vectorstore/store.js.map +1 -1
- package/docs/ARCHITECTURE.md +244 -244
- package/docs/DASHBOARD.md +133 -133
- package/docs/SETUP.md +178 -178
- package/package.json +1 -1
- package/scripts/copy-ui.js +6 -6
- package/dist/ui/ui/app.js +0 -811
- package/dist/ui/ui/index.html +0 -300
- package/dist/ui/ui/styles.css +0 -1154
package/CHANGELOG.md
CHANGED
|
@@ -1,77 +1,77 @@
|
|
|
1
|
-
# Changelog
|
|
2
|
-
|
|
3
|
-
## 1.0.0 (2026-03-26)
|
|
4
|
-
|
|
5
|
-
Initial release.
|
|
6
|
-
|
|
7
|
-
### MCP Tools (12)
|
|
8
|
-
|
|
9
|
-
**Knowledge (5):** `knowledge_list`, `knowledge_read`, `knowledge_write`, `knowledge_delete`, `knowledge_sync`
|
|
10
|
-
|
|
11
|
-
**Sessions (5):** `knowledge_sessions`, `knowledge_search`, `knowledge_get`, `knowledge_summary`, `knowledge_recall`
|
|
12
|
-
|
|
13
|
-
**Admin (2):** `knowledge_index_status`, `knowledge_config`
|
|
14
|
-
|
|
15
|
-
### Search Engine
|
|
16
|
-
|
|
17
|
-
- Hybrid semantic + TF-IDF search with configurable alpha blending
|
|
18
|
-
- Recency decay weighting (newer sessions rank higher)
|
|
19
|
-
- Fuzzy matching via Levenshtein distance
|
|
20
|
-
- 6 recall scopes: errors, plans, configs, tools, files, decisions
|
|
21
|
-
- Role-based filtering (all, user, assistant)
|
|
22
|
-
- Regex mode for pattern-based searches
|
|
23
|
-
|
|
24
|
-
### Embeddings & Vector Store
|
|
25
|
-
|
|
26
|
-
- SQLite vector store with sqlite-vec for cosine similarity
|
|
27
|
-
- 4 embedding providers: local (Hugging Face), OpenAI, Claude/Voyage, Gemini
|
|
28
|
-
- Background indexer runs on server startup
|
|
29
|
-
- Automatic provider switching with dimension migration
|
|
30
|
-
|
|
31
|
-
### Knowledge Base
|
|
32
|
-
|
|
33
|
-
- Git-synced markdown vault at `~/claude-memory/`
|
|
34
|
-
- 5 categories: projects, people, decisions, workflows, notes
|
|
35
|
-
- YAML frontmatter for metadata (title, tags, updated)
|
|
36
|
-
- Auto git commit + push on writes, pull on reads
|
|
37
|
-
- Configurable git URL via `knowledge_config` tool or `KNOWLEDGE_GIT_URL` env var
|
|
38
|
-
- New repos auto-scaffolded with README, .gitignore, and category dirs
|
|
39
|
-
|
|
40
|
-
### Auto-Distillation
|
|
41
|
-
|
|
42
|
-
- Automatic extraction of session insights into knowledge base
|
|
43
|
-
- Project name normalization (worktrees, swarms merged into parent)
|
|
44
|
-
- Secrets scrubbing: API keys, tokens, passwords, JWTs, private keys redacted
|
|
45
|
-
- System noise stripped (XML tags, task notifications)
|
|
46
|
-
- Absolute paths normalized to `~/`
|
|
47
|
-
- Defense-in-depth audit blocks writes with surviving sensitive content
|
|
48
|
-
|
|
49
|
-
### Persistent Configuration
|
|
50
|
-
|
|
51
|
-
- `knowledge_config` tool for runtime setup (no restart needed)
|
|
52
|
-
- Config stored at XDG/AppData location (tool-agnostic)
|
|
53
|
-
- Priority: env vars > persisted config > defaults
|
|
54
|
-
|
|
55
|
-
### Web Dashboard
|
|
56
|
-
|
|
57
|
-
- http://localhost:3423, auto-starts with MCP server
|
|
58
|
-
- 5 tabs: Knowledge, Search, Sessions, Recall, Embeddings
|
|
59
|
-
- MD3 design language matching agent-comm and agent-tasks
|
|
60
|
-
- Light/dark theme with localStorage persistence
|
|
61
|
-
- Side panel (560px, resizable) with markdown rendering
|
|
62
|
-
- Live reload via file watcher + WebSocket
|
|
63
|
-
- Semantic search toggle with score breakdown
|
|
64
|
-
|
|
65
|
-
### Performance
|
|
66
|
-
|
|
67
|
-
- Session file mtime cache (re-parses only changed files)
|
|
68
|
-
- Global TF-IDF index cache with 60s TTL
|
|
69
|
-
- Background embedding indexer (non-blocking)
|
|
70
|
-
|
|
71
|
-
### Infrastructure
|
|
72
|
-
|
|
73
|
-
- REST API: 10 endpoints (knowledge, sessions, search, recall, index-status, health)
|
|
74
|
-
- WebSocket server for real-time dashboard updates
|
|
75
|
-
- 280 tests passing (vitest)
|
|
76
|
-
- TypeScript strict mode, ES modules
|
|
77
|
-
- GitHub Actions CI (Node 20/22 matrix, npm publish on tags)
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 1.0.0 (2026-03-26)
|
|
4
|
+
|
|
5
|
+
Initial release.
|
|
6
|
+
|
|
7
|
+
### MCP Tools (12)
|
|
8
|
+
|
|
9
|
+
**Knowledge (5):** `knowledge_list`, `knowledge_read`, `knowledge_write`, `knowledge_delete`, `knowledge_sync`
|
|
10
|
+
|
|
11
|
+
**Sessions (5):** `knowledge_sessions`, `knowledge_search`, `knowledge_get`, `knowledge_summary`, `knowledge_recall`
|
|
12
|
+
|
|
13
|
+
**Admin (2):** `knowledge_index_status`, `knowledge_config`
|
|
14
|
+
|
|
15
|
+
### Search Engine
|
|
16
|
+
|
|
17
|
+
- Hybrid semantic + TF-IDF search with configurable alpha blending
|
|
18
|
+
- Recency decay weighting (newer sessions rank higher)
|
|
19
|
+
- Fuzzy matching via Levenshtein distance
|
|
20
|
+
- 6 recall scopes: errors, plans, configs, tools, files, decisions
|
|
21
|
+
- Role-based filtering (all, user, assistant)
|
|
22
|
+
- Regex mode for pattern-based searches
|
|
23
|
+
|
|
24
|
+
### Embeddings & Vector Store
|
|
25
|
+
|
|
26
|
+
- SQLite vector store with sqlite-vec for cosine similarity
|
|
27
|
+
- 4 embedding providers: local (Hugging Face), OpenAI, Claude/Voyage, Gemini
|
|
28
|
+
- Background indexer runs on server startup
|
|
29
|
+
- Automatic provider switching with dimension migration
|
|
30
|
+
|
|
31
|
+
### Knowledge Base
|
|
32
|
+
|
|
33
|
+
- Git-synced markdown vault at `~/claude-memory/`
|
|
34
|
+
- 5 categories: projects, people, decisions, workflows, notes
|
|
35
|
+
- YAML frontmatter for metadata (title, tags, updated)
|
|
36
|
+
- Auto git commit + push on writes, pull on reads
|
|
37
|
+
- Configurable git URL via `knowledge_config` tool or `KNOWLEDGE_GIT_URL` env var
|
|
38
|
+
- New repos auto-scaffolded with README, .gitignore, and category dirs
|
|
39
|
+
|
|
40
|
+
### Auto-Distillation
|
|
41
|
+
|
|
42
|
+
- Automatic extraction of session insights into knowledge base
|
|
43
|
+
- Project name normalization (worktrees, swarms merged into parent)
|
|
44
|
+
- Secrets scrubbing: API keys, tokens, passwords, JWTs, private keys redacted
|
|
45
|
+
- System noise stripped (XML tags, task notifications)
|
|
46
|
+
- Absolute paths normalized to `~/`
|
|
47
|
+
- Defense-in-depth audit blocks writes with surviving sensitive content
|
|
48
|
+
|
|
49
|
+
### Persistent Configuration
|
|
50
|
+
|
|
51
|
+
- `knowledge_config` tool for runtime setup (no restart needed)
|
|
52
|
+
- Config stored at XDG/AppData location (tool-agnostic)
|
|
53
|
+
- Priority: env vars > persisted config > defaults
|
|
54
|
+
|
|
55
|
+
### Web Dashboard
|
|
56
|
+
|
|
57
|
+
- http://localhost:3423, auto-starts with MCP server
|
|
58
|
+
- 5 tabs: Knowledge, Search, Sessions, Recall, Embeddings
|
|
59
|
+
- MD3 design language matching agent-comm and agent-tasks
|
|
60
|
+
- Light/dark theme with localStorage persistence
|
|
61
|
+
- Side panel (560px, resizable) with markdown rendering
|
|
62
|
+
- Live reload via file watcher + WebSocket
|
|
63
|
+
- Semantic search toggle with score breakdown
|
|
64
|
+
|
|
65
|
+
### Performance
|
|
66
|
+
|
|
67
|
+
- Session file mtime cache (re-parses only changed files)
|
|
68
|
+
- Global TF-IDF index cache with 60s TTL
|
|
69
|
+
- Background embedding indexer (non-blocking)
|
|
70
|
+
|
|
71
|
+
### Infrastructure
|
|
72
|
+
|
|
73
|
+
- REST API: 10 endpoints (knowledge, sessions, search, recall, index-status, health)
|
|
74
|
+
- WebSocket server for real-time dashboard updates
|
|
75
|
+
- 280 tests passing (vitest)
|
|
76
|
+
- TypeScript strict mode, ES modules
|
|
77
|
+
- GitHub Actions CI (Node 20/22 matrix, npm publish on tags)
|
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 keshrath
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 keshrath
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,191 +1,191 @@
|
|
|
1
|
-
# agent-knowledge
|
|
2
|
-
|
|
3
|
-
[](LICENSE)
|
|
4
|
-
[](https://nodejs.org)
|
|
5
|
-
[]()
|
|
6
|
-
[]()
|
|
7
|
-
|
|
8
|
-
**Cross-session memory and recall for AI agents** -- git-synced knowledge base, hybrid semantic+TF-IDF search, auto-distillation with secrets scrubbing.
|
|
9
|
-
|
|
10
|
-
<table>
|
|
11
|
-
<tr>
|
|
12
|
-
<td><img src="docs/assets/knowledge-light.png" alt="Knowledge Base (light)" width="480"></td>
|
|
13
|
-
<td><img src="docs/assets/search-light.png" alt="Session Search" width="480"></td>
|
|
14
|
-
</tr>
|
|
15
|
-
<tr>
|
|
16
|
-
<td align="center"><em>Knowledge base with category filtering</em></td>
|
|
17
|
-
<td align="center"><em>TF-IDF ranked session search</em></td>
|
|
18
|
-
</tr>
|
|
19
|
-
</table>
|
|
20
|
-
|
|
21
|
-
## Why
|
|
22
|
-
|
|
23
|
-
Claude Code sessions are ephemeral. When a session ends, everything it learned -- architecture decisions, debugging insights, project context -- is gone. The next session starts from scratch.
|
|
24
|
-
|
|
25
|
-
**agent-knowledge** solves this with two complementary systems:
|
|
26
|
-
|
|
27
|
-
1. **Knowledge Base** -- a git-synced markdown vault of structured entries (decisions, workflows, project context) that persists across sessions and machines.
|
|
28
|
-
2. **Session Search** -- TF-IDF ranked full-text search across JSONL session transcripts, so agents can recall what happened before.
|
|
29
|
-
|
|
30
|
-
## Features
|
|
31
|
-
|
|
32
|
-
- **Hybrid search** -- semantic vector similarity blended with TF-IDF keyword ranking
|
|
33
|
-
- **Git-synced knowledge base** -- markdown vault with YAML frontmatter, auto commit and push on writes
|
|
34
|
-
- **Auto-distillation** -- session insights automatically extracted and pushed to git with secrets scrubbing
|
|
35
|
-
- **Embeddings** -- local (Hugging Face), OpenAI, Claude/Voyage, or Gemini providers
|
|
36
|
-
- **Fuzzy matching** -- typo-tolerant search using Levenshtein distance
|
|
37
|
-
- **6 search scopes** -- errors, plans, configs, tools, files, decisions
|
|
38
|
-
- **Configurable git URL** -- `knowledge_config` tool for runtime setup, persisted at XDG/AppData location
|
|
39
|
-
- **Cross-machine persistence** -- knowledge syncs via git, sessions read from local JSONL
|
|
40
|
-
- **Real-time dashboard** -- browse, search, and manage at `localhost:3423`
|
|
41
|
-
- **Secrets scrubbing** -- API keys, tokens, passwords, private keys automatically redacted before git push
|
|
42
|
-
|
|
43
|
-
## Quick Start
|
|
44
|
-
|
|
45
|
-
```bash
|
|
46
|
-
git clone https://github.com/keshrath/agent-knowledge.git
|
|
47
|
-
cd agent-knowledge
|
|
48
|
-
npm install && npm run build
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
### Configure in Claude Code
|
|
52
|
-
|
|
53
|
-
```bash
|
|
54
|
-
claude mcp add agent-knowledge -s user \
|
|
55
|
-
-e KNOWLEDGE_MEMORY_DIR="$HOME/claude-memory" \
|
|
56
|
-
-- node /path/to/agent-knowledge/dist/index.js
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
Or add to `settings.json` permissions:
|
|
60
|
-
|
|
61
|
-
```json
|
|
62
|
-
{
|
|
63
|
-
"permissions": {
|
|
64
|
-
"allow": ["mcp__agent-knowledge__*"]
|
|
65
|
-
}
|
|
66
|
-
}
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
Dashboard: **http://localhost:3423** (auto-starts with MCP server)
|
|
70
|
-
|
|
71
|
-
## MCP Tools
|
|
72
|
-
|
|
73
|
-
### Knowledge Base
|
|
74
|
-
|
|
75
|
-
| Tool | Description | Parameters |
|
|
76
|
-
| ------------------ | ----------------------------------- | ------------------------------------------------ |
|
|
77
|
-
| `knowledge_list` | List entries by category and/or tag | `category?`, `tag?` |
|
|
78
|
-
| `knowledge_read` | Read a specific entry | `path` (required) |
|
|
79
|
-
| `knowledge_write` | Create/update entry (auto git sync) | `category`, `filename`, `content` (all required) |
|
|
80
|
-
| `knowledge_delete` | Delete an entry (auto git sync) | `path` (required) |
|
|
81
|
-
| `knowledge_sync` | Manual git pull + push | -- |
|
|
82
|
-
|
|
83
|
-
### Session Search
|
|
84
|
-
|
|
85
|
-
| Tool | Description | Parameters |
|
|
86
|
-
| -------------------- | --------------------------------------- | ------------------------------------------------------------------ |
|
|
87
|
-
| `knowledge_sessions` | List sessions with metadata | `project?` |
|
|
88
|
-
| `knowledge_search` | TF-IDF ranked search across transcripts | `query` (required), `project?`, `role?`, `max_results?`, `ranked?` |
|
|
89
|
-
| `knowledge_get` | Retrieve full session conversation | `session_id` (required), `project?`, `include_tools?`, `tail?` |
|
|
90
|
-
| `knowledge_summary` | Session summary (topics, tools, files) | `session_id` (required), `project?` |
|
|
91
|
-
| `knowledge_recall` | Scoped search across sessions | `scope` (required), `query` (required), `project?`, `max_results?` |
|
|
92
|
-
|
|
93
|
-
### Admin
|
|
94
|
-
|
|
95
|
-
| Tool | Description | Parameters |
|
|
96
|
-
| ------------------------ | ---------------------------- | ------------------------------------------ |
|
|
97
|
-
| `knowledge_index_status` | Vector store statistics | -- |
|
|
98
|
-
| `knowledge_config` | View or update configuration | `git_url?`, `memory_dir?`, `auto_distill?` |
|
|
99
|
-
|
|
100
|
-
## REST API
|
|
101
|
-
|
|
102
|
-
| Method | Endpoint | Description |
|
|
103
|
-
| ------ | --------------------------------------- | ------------------------ |
|
|
104
|
-
| GET | `/api/knowledge` | List knowledge entries |
|
|
105
|
-
| GET | `/api/knowledge/search?q=` | Search knowledge base |
|
|
106
|
-
| GET | `/api/knowledge/:path` | Read a specific entry |
|
|
107
|
-
| GET | `/api/sessions` | List sessions |
|
|
108
|
-
| GET | `/api/sessions/search?q=&role=&ranked=` | Search sessions (TF-IDF) |
|
|
109
|
-
| GET | `/api/sessions/recall?scope=&q=` | Scoped recall |
|
|
110
|
-
| GET | `/api/sessions/:id` | Read a session |
|
|
111
|
-
| GET | `/api/sessions/:id/summary` | Session summary |
|
|
112
|
-
| GET | `/health` | Health check |
|
|
113
|
-
|
|
114
|
-
## Architecture
|
|
115
|
-
|
|
116
|
-
```mermaid
|
|
117
|
-
graph LR
|
|
118
|
-
subgraph Storage
|
|
119
|
-
KB[(Knowledge Base<br/>~/claude-memory<br/>Git Repository)]
|
|
120
|
-
SF[(Session Files<br/>~/.claude/projects<br/>JSONL Logs)]
|
|
121
|
-
end
|
|
122
|
-
|
|
123
|
-
subgraph agent-knowledge
|
|
124
|
-
KM[Knowledge Module<br/>store / search / git]
|
|
125
|
-
SE[Search Engine<br/>TF-IDF + Fuzzy]
|
|
126
|
-
DS[Dashboard<br/>:3423]
|
|
127
|
-
MCP[MCP Server<br/>stdio]
|
|
128
|
-
end
|
|
129
|
-
|
|
130
|
-
subgraph Clients
|
|
131
|
-
CC[Claude Code Sessions]
|
|
132
|
-
WB[Web Browser]
|
|
133
|
-
end
|
|
134
|
-
|
|
135
|
-
KB <-->|git pull/push| KM
|
|
136
|
-
SF -->|parse JSONL| SE
|
|
137
|
-
KM --> MCP
|
|
138
|
-
SE --> MCP
|
|
139
|
-
KM --> DS
|
|
140
|
-
SE --> DS
|
|
141
|
-
MCP --> CC
|
|
142
|
-
DS --> WB
|
|
143
|
-
```
|
|
144
|
-
|
|
145
|
-
## Search Capabilities
|
|
146
|
-
|
|
147
|
-
**TF-IDF Ranking** -- results scored by term frequency-inverse document frequency. Rare terms boost relevance. Global index cached for 60 seconds.
|
|
148
|
-
|
|
149
|
-
**Fuzzy Matching** -- Levenshtein edit distance with sliding window. Configurable threshold (default 0.7).
|
|
150
|
-
|
|
151
|
-
**Scoped Recall** via `knowledge_recall`:
|
|
152
|
-
|
|
153
|
-
| Scope | Matches |
|
|
154
|
-
| ----------- | ----------------------------------------- |
|
|
155
|
-
| `errors` | Stack traces, exceptions, failed commands |
|
|
156
|
-
| `plans` | Architecture, TODOs, implementation steps |
|
|
157
|
-
| `configs` | Settings, env vars, configuration files |
|
|
158
|
-
| `tools` | MCP tool calls, CLI commands |
|
|
159
|
-
| `files` | File paths, modifications |
|
|
160
|
-
| `decisions` | Trade-offs, rationale, choices |
|
|
161
|
-
|
|
162
|
-
## Testing
|
|
163
|
-
|
|
164
|
-
```bash
|
|
165
|
-
npm test # Run all 280 tests
|
|
166
|
-
npm run test:watch # Watch mode
|
|
167
|
-
npm run lint # Type-check (tsc --noEmit)
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
## Environment Variables
|
|
171
|
-
|
|
172
|
-
| Variable | Default | Description |
|
|
173
|
-
| ------------------------------ | ----------------- | ---------------------------------------------------------------- |
|
|
174
|
-
| `KNOWLEDGE_MEMORY_DIR` | `~/claude-memory` | Path to git-synced knowledge base |
|
|
175
|
-
| `KNOWLEDGE_GIT_URL` | -- | Git remote URL (auto-clones if dir missing) |
|
|
176
|
-
| `KNOWLEDGE_AUTO_DISTILL` | `true` | Auto-distill session insights to knowledge base |
|
|
177
|
-
| `KNOWLEDGE_EMBEDDING_PROVIDER` | `local` | Embedding provider: `local`, `openai`, `claude`, `gemini` |
|
|
178
|
-
| `KNOWLEDGE_EMBEDDING_ALPHA` | `0.3` | TF-IDF vs semantic blend weight (0=pure semantic, 1=pure TF-IDF) |
|
|
179
|
-
| `CLAUDE_DIR` | `~/.claude` | Directory containing session transcripts (JSONL files) |
|
|
180
|
-
| `KNOWLEDGE_PORT` | `3423` | Dashboard HTTP port |
|
|
181
|
-
|
|
182
|
-
## Documentation
|
|
183
|
-
|
|
184
|
-
- [Setup Guide](docs/SETUP.md)
|
|
185
|
-
- [Architecture](docs/ARCHITECTURE.md)
|
|
186
|
-
- [Dashboard](docs/DASHBOARD.md)
|
|
187
|
-
- [Changelog](CHANGELOG.md)
|
|
188
|
-
|
|
189
|
-
## License
|
|
190
|
-
|
|
191
|
-
[MIT](LICENSE)
|
|
1
|
+
# agent-knowledge
|
|
2
|
+
|
|
3
|
+
[](LICENSE)
|
|
4
|
+
[](https://nodejs.org)
|
|
5
|
+
[]()
|
|
6
|
+
[]()
|
|
7
|
+
|
|
8
|
+
**Cross-session memory and recall for AI agents** -- git-synced knowledge base, hybrid semantic+TF-IDF search, auto-distillation with secrets scrubbing.
|
|
9
|
+
|
|
10
|
+
<table>
|
|
11
|
+
<tr>
|
|
12
|
+
<td><img src="docs/assets/knowledge-light.png" alt="Knowledge Base (light)" width="480"></td>
|
|
13
|
+
<td><img src="docs/assets/search-light.png" alt="Session Search" width="480"></td>
|
|
14
|
+
</tr>
|
|
15
|
+
<tr>
|
|
16
|
+
<td align="center"><em>Knowledge base with category filtering</em></td>
|
|
17
|
+
<td align="center"><em>TF-IDF ranked session search</em></td>
|
|
18
|
+
</tr>
|
|
19
|
+
</table>
|
|
20
|
+
|
|
21
|
+
## Why
|
|
22
|
+
|
|
23
|
+
Claude Code sessions are ephemeral. When a session ends, everything it learned -- architecture decisions, debugging insights, project context -- is gone. The next session starts from scratch.
|
|
24
|
+
|
|
25
|
+
**agent-knowledge** solves this with two complementary systems:
|
|
26
|
+
|
|
27
|
+
1. **Knowledge Base** -- a git-synced markdown vault of structured entries (decisions, workflows, project context) that persists across sessions and machines.
|
|
28
|
+
2. **Session Search** -- TF-IDF ranked full-text search across JSONL session transcripts, so agents can recall what happened before.
|
|
29
|
+
|
|
30
|
+
## Features
|
|
31
|
+
|
|
32
|
+
- **Hybrid search** -- semantic vector similarity blended with TF-IDF keyword ranking
|
|
33
|
+
- **Git-synced knowledge base** -- markdown vault with YAML frontmatter, auto commit and push on writes
|
|
34
|
+
- **Auto-distillation** -- session insights automatically extracted and pushed to git with secrets scrubbing
|
|
35
|
+
- **Embeddings** -- local (Hugging Face), OpenAI, Claude/Voyage, or Gemini providers
|
|
36
|
+
- **Fuzzy matching** -- typo-tolerant search using Levenshtein distance
|
|
37
|
+
- **6 search scopes** -- errors, plans, configs, tools, files, decisions
|
|
38
|
+
- **Configurable git URL** -- `knowledge_config` tool for runtime setup, persisted at XDG/AppData location
|
|
39
|
+
- **Cross-machine persistence** -- knowledge syncs via git, sessions read from local JSONL
|
|
40
|
+
- **Real-time dashboard** -- browse, search, and manage at `localhost:3423`
|
|
41
|
+
- **Secrets scrubbing** -- API keys, tokens, passwords, private keys automatically redacted before git push
|
|
42
|
+
|
|
43
|
+
## Quick Start
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
git clone https://github.com/keshrath/agent-knowledge.git
|
|
47
|
+
cd agent-knowledge
|
|
48
|
+
npm install && npm run build
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### Configure in Claude Code
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
claude mcp add agent-knowledge -s user \
|
|
55
|
+
-e KNOWLEDGE_MEMORY_DIR="$HOME/claude-memory" \
|
|
56
|
+
-- node /path/to/agent-knowledge/dist/index.js
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Or add to `settings.json` permissions:
|
|
60
|
+
|
|
61
|
+
```json
|
|
62
|
+
{
|
|
63
|
+
"permissions": {
|
|
64
|
+
"allow": ["mcp__agent-knowledge__*"]
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Dashboard: **http://localhost:3423** (auto-starts with MCP server)
|
|
70
|
+
|
|
71
|
+
## MCP Tools
|
|
72
|
+
|
|
73
|
+
### Knowledge Base
|
|
74
|
+
|
|
75
|
+
| Tool | Description | Parameters |
|
|
76
|
+
| ------------------ | ----------------------------------- | ------------------------------------------------ |
|
|
77
|
+
| `knowledge_list` | List entries by category and/or tag | `category?`, `tag?` |
|
|
78
|
+
| `knowledge_read` | Read a specific entry | `path` (required) |
|
|
79
|
+
| `knowledge_write` | Create/update entry (auto git sync) | `category`, `filename`, `content` (all required) |
|
|
80
|
+
| `knowledge_delete` | Delete an entry (auto git sync) | `path` (required) |
|
|
81
|
+
| `knowledge_sync` | Manual git pull + push | -- |
|
|
82
|
+
|
|
83
|
+
### Session Search
|
|
84
|
+
|
|
85
|
+
| Tool | Description | Parameters |
|
|
86
|
+
| -------------------- | --------------------------------------- | ------------------------------------------------------------------ |
|
|
87
|
+
| `knowledge_sessions` | List sessions with metadata | `project?` |
|
|
88
|
+
| `knowledge_search` | TF-IDF ranked search across transcripts | `query` (required), `project?`, `role?`, `max_results?`, `ranked?` |
|
|
89
|
+
| `knowledge_get` | Retrieve full session conversation | `session_id` (required), `project?`, `include_tools?`, `tail?` |
|
|
90
|
+
| `knowledge_summary` | Session summary (topics, tools, files) | `session_id` (required), `project?` |
|
|
91
|
+
| `knowledge_recall` | Scoped search across sessions | `scope` (required), `query` (required), `project?`, `max_results?` |
|
|
92
|
+
|
|
93
|
+
### Admin
|
|
94
|
+
|
|
95
|
+
| Tool | Description | Parameters |
|
|
96
|
+
| ------------------------ | ---------------------------- | ------------------------------------------ |
|
|
97
|
+
| `knowledge_index_status` | Vector store statistics | -- |
|
|
98
|
+
| `knowledge_config` | View or update configuration | `git_url?`, `memory_dir?`, `auto_distill?` |
|
|
99
|
+
|
|
100
|
+
## REST API
|
|
101
|
+
|
|
102
|
+
| Method | Endpoint | Description |
|
|
103
|
+
| ------ | --------------------------------------- | ------------------------ |
|
|
104
|
+
| GET | `/api/knowledge` | List knowledge entries |
|
|
105
|
+
| GET | `/api/knowledge/search?q=` | Search knowledge base |
|
|
106
|
+
| GET | `/api/knowledge/:path` | Read a specific entry |
|
|
107
|
+
| GET | `/api/sessions` | List sessions |
|
|
108
|
+
| GET | `/api/sessions/search?q=&role=&ranked=` | Search sessions (TF-IDF) |
|
|
109
|
+
| GET | `/api/sessions/recall?scope=&q=` | Scoped recall |
|
|
110
|
+
| GET | `/api/sessions/:id` | Read a session |
|
|
111
|
+
| GET | `/api/sessions/:id/summary` | Session summary |
|
|
112
|
+
| GET | `/health` | Health check |
|
|
113
|
+
|
|
114
|
+
## Architecture
|
|
115
|
+
|
|
116
|
+
```mermaid
|
|
117
|
+
graph LR
|
|
118
|
+
subgraph Storage
|
|
119
|
+
KB[(Knowledge Base<br/>~/claude-memory<br/>Git Repository)]
|
|
120
|
+
SF[(Session Files<br/>~/.claude/projects<br/>JSONL Logs)]
|
|
121
|
+
end
|
|
122
|
+
|
|
123
|
+
subgraph agent-knowledge
|
|
124
|
+
KM[Knowledge Module<br/>store / search / git]
|
|
125
|
+
SE[Search Engine<br/>TF-IDF + Fuzzy]
|
|
126
|
+
DS[Dashboard<br/>:3423]
|
|
127
|
+
MCP[MCP Server<br/>stdio]
|
|
128
|
+
end
|
|
129
|
+
|
|
130
|
+
subgraph Clients
|
|
131
|
+
CC[Claude Code Sessions]
|
|
132
|
+
WB[Web Browser]
|
|
133
|
+
end
|
|
134
|
+
|
|
135
|
+
KB <-->|git pull/push| KM
|
|
136
|
+
SF -->|parse JSONL| SE
|
|
137
|
+
KM --> MCP
|
|
138
|
+
SE --> MCP
|
|
139
|
+
KM --> DS
|
|
140
|
+
SE --> DS
|
|
141
|
+
MCP --> CC
|
|
142
|
+
DS --> WB
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
## Search Capabilities
|
|
146
|
+
|
|
147
|
+
**TF-IDF Ranking** -- results scored by term frequency-inverse document frequency. Rare terms boost relevance. Global index cached for 60 seconds.
|
|
148
|
+
|
|
149
|
+
**Fuzzy Matching** -- Levenshtein edit distance with sliding window. Configurable threshold (default 0.7).
|
|
150
|
+
|
|
151
|
+
**Scoped Recall** via `knowledge_recall`:
|
|
152
|
+
|
|
153
|
+
| Scope | Matches |
|
|
154
|
+
| ----------- | ----------------------------------------- |
|
|
155
|
+
| `errors` | Stack traces, exceptions, failed commands |
|
|
156
|
+
| `plans` | Architecture, TODOs, implementation steps |
|
|
157
|
+
| `configs` | Settings, env vars, configuration files |
|
|
158
|
+
| `tools` | MCP tool calls, CLI commands |
|
|
159
|
+
| `files` | File paths, modifications |
|
|
160
|
+
| `decisions` | Trade-offs, rationale, choices |
|
|
161
|
+
|
|
162
|
+
## Testing
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
npm test # Run all 280 tests
|
|
166
|
+
npm run test:watch # Watch mode
|
|
167
|
+
npm run lint # Type-check (tsc --noEmit)
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
## Environment Variables
|
|
171
|
+
|
|
172
|
+
| Variable | Default | Description |
|
|
173
|
+
| ------------------------------ | ----------------- | ---------------------------------------------------------------- |
|
|
174
|
+
| `KNOWLEDGE_MEMORY_DIR` | `~/claude-memory` | Path to git-synced knowledge base |
|
|
175
|
+
| `KNOWLEDGE_GIT_URL` | -- | Git remote URL (auto-clones if dir missing) |
|
|
176
|
+
| `KNOWLEDGE_AUTO_DISTILL` | `true` | Auto-distill session insights to knowledge base |
|
|
177
|
+
| `KNOWLEDGE_EMBEDDING_PROVIDER` | `local` | Embedding provider: `local`, `openai`, `claude`, `gemini` |
|
|
178
|
+
| `KNOWLEDGE_EMBEDDING_ALPHA` | `0.3` | TF-IDF vs semantic blend weight (0=pure semantic, 1=pure TF-IDF) |
|
|
179
|
+
| `CLAUDE_DIR` | `~/.claude` | Directory containing session transcripts (JSONL files) |
|
|
180
|
+
| `KNOWLEDGE_PORT` | `3423` | Dashboard HTTP port |
|
|
181
|
+
|
|
182
|
+
## Documentation
|
|
183
|
+
|
|
184
|
+
- [Setup Guide](docs/SETUP.md)
|
|
185
|
+
- [Architecture](docs/ARCHITECTURE.md)
|
|
186
|
+
- [Dashboard](docs/DASHBOARD.md)
|
|
187
|
+
- [Changelog](CHANGELOG.md)
|
|
188
|
+
|
|
189
|
+
## License
|
|
190
|
+
|
|
191
|
+
[MIT](LICENSE)
|
package/dist/index.js
CHANGED
|
@@ -2,7 +2,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
|
|
|
2
2
|
import { createServer } from './server.js';
|
|
3
3
|
import { startDashboard } from './dashboard.js';
|
|
4
4
|
async function main() {
|
|
5
|
-
const port = parseInt(process.env.
|
|
5
|
+
const port = parseInt(process.env.KNOWLEDGE_PORT || '3423', 10);
|
|
6
6
|
try {
|
|
7
7
|
await startDashboard(port);
|
|
8
8
|
process.stderr.write(`Dashboard: http://localhost:${port}\n`);
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,MAAM,EAAE,EAAE,CAAC,CAAC;IAEhE,IAAI,CAAC;QACH,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;QAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,+BAA+B,IAAI,IAAI,CAAC,CAAC;IAChE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uCAAuC,GAAG,IAAI,CAAC,CAAC;IACvE,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../src/knowledge/git.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAsBD;;GAEG;AACH,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAO7D;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAmBjF;AAED;;GAEG;AACH,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,CAIxF;AAkHD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,
|
|
1
|
+
{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../src/knowledge/git.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAsBD;;GAEG;AACH,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAO7D;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAmBjF;AAED;;GAEG;AACH,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,CAIxF;AAkHD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAoDlE"}
|