@aeriondyseti/vector-memory-mcp 0.8.0 โ 0.9.0-alpha.2
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/README.md +71 -375
- package/dist/package.json +73 -0
- package/dist/scripts/publish.d.ts +13 -0
- package/dist/scripts/publish.d.ts.map +1 -0
- package/dist/scripts/publish.js +56 -0
- package/dist/scripts/publish.js.map +1 -0
- package/dist/scripts/test-runner.d.ts +9 -0
- package/dist/scripts/test-runner.d.ts.map +1 -0
- package/dist/scripts/test-runner.js +83 -0
- package/dist/scripts/test-runner.js.map +1 -0
- package/dist/scripts/warmup.d.ts +8 -0
- package/dist/scripts/warmup.d.ts.map +1 -0
- package/dist/scripts/warmup.js +61 -0
- package/dist/scripts/warmup.js.map +1 -0
- package/dist/src/config/index.d.ts +24 -0
- package/dist/src/config/index.d.ts.map +1 -0
- package/dist/src/config/index.js +48 -0
- package/dist/src/config/index.js.map +1 -0
- package/dist/src/db/connection.d.ts +3 -0
- package/dist/src/db/connection.d.ts.map +1 -0
- package/dist/src/db/connection.js +10 -0
- package/dist/src/db/connection.js.map +1 -0
- package/dist/src/db/memory.repository.d.ts +13 -0
- package/dist/src/db/memory.repository.d.ts.map +1 -0
- package/dist/src/db/memory.repository.js +97 -0
- package/dist/src/db/memory.repository.js.map +1 -0
- package/dist/src/db/schema.d.ts +4 -0
- package/dist/src/db/schema.d.ts.map +1 -0
- package/dist/src/db/schema.js +12 -0
- package/dist/src/db/schema.js.map +1 -0
- package/dist/src/http/mcp-transport.d.ts +19 -0
- package/dist/src/http/mcp-transport.d.ts.map +1 -0
- package/dist/src/http/mcp-transport.js +192 -0
- package/dist/src/http/mcp-transport.js.map +1 -0
- package/dist/src/http/server.d.ts +12 -0
- package/dist/src/http/server.d.ts.map +1 -0
- package/dist/src/http/server.js +168 -0
- package/dist/src/http/server.js.map +1 -0
- package/dist/src/index.d.ts +3 -0
- package/dist/src/index.d.ts.map +1 -0
- package/dist/src/index.js +59 -0
- package/dist/src/index.js.map +1 -0
- package/dist/src/mcp/handlers.d.ts +11 -0
- package/dist/src/mcp/handlers.d.ts.map +1 -0
- package/dist/src/mcp/handlers.js +175 -0
- package/dist/src/mcp/handlers.js.map +1 -0
- package/dist/src/mcp/server.d.ts +5 -0
- package/dist/src/mcp/server.d.ts.map +1 -0
- package/dist/src/mcp/server.js +23 -0
- package/dist/src/mcp/server.js.map +1 -0
- package/dist/src/mcp/tools.d.ts +9 -0
- package/dist/src/mcp/tools.d.ts.map +1 -0
- package/dist/src/mcp/tools.js +243 -0
- package/dist/src/mcp/tools.js.map +1 -0
- package/dist/src/services/embeddings.service.d.ts +12 -0
- package/dist/src/services/embeddings.service.d.ts.map +1 -0
- package/dist/src/services/embeddings.service.js +37 -0
- package/dist/src/services/embeddings.service.js.map +1 -0
- package/dist/src/services/memory.service.d.ts +31 -0
- package/dist/src/services/memory.service.d.ts.map +1 -0
- package/dist/src/services/memory.service.js +131 -0
- package/dist/src/services/memory.service.js.map +1 -0
- package/dist/src/types/memory.d.ts +17 -0
- package/dist/src/types/memory.d.ts.map +1 -0
- package/dist/src/types/memory.js +15 -0
- package/dist/src/types/memory.js.map +1 -0
- package/package.json +15 -10
- package/scripts/test-runner.ts +25 -1
- package/src/config/index.ts +0 -75
- package/src/db/connection.ts +0 -11
- package/src/db/memory.repository.ts +0 -115
- package/src/db/schema.ts +0 -34
- package/src/http/mcp-transport.ts +0 -255
- package/src/http/server.ts +0 -190
- package/src/index.ts +0 -70
- package/src/mcp/handlers.ts +0 -248
- package/src/mcp/server.ts +0 -34
- package/src/mcp/tools.ts +0 -214
- package/src/services/embeddings.service.ts +0 -48
- package/src/services/memory.service.ts +0 -185
- package/src/types/memory.ts +0 -31
package/README.md
CHANGED
|
@@ -1,453 +1,149 @@
|
|
|
1
1
|
# Vector Memory MCP Server
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> Semantic memory storage for AI assistants. Store decisions, patterns, and context that persists across sessions.
|
|
4
4
|
|
|
5
|
-
A
|
|
6
|
-
|
|
7
|
-
**Perfect for:** Software teams maintaining architectural knowledge, developers juggling multiple projects, and anyone building with MCP-compatible AI assistants.
|
|
5
|
+
A local-first MCP server that provides vector-based memory storage. Uses local embeddings and LanceDB for fast, private semantic search.
|
|
8
6
|
|
|
9
7
|
[](https://opensource.org/licenses/MIT)
|
|
10
|
-
[](https://bun.sh/)
|
|
12
|
-
[](https://modelcontextprotocol.io)
|
|
8
|
+
[](https://www.npmjs.com/package/@aeriondyseti/vector-memory-mcp)
|
|
13
9
|
|
|
14
10
|
---
|
|
15
11
|
|
|
16
|
-
##
|
|
17
|
-
|
|
18
|
-
### ๐ **Local-First & Private**
|
|
19
|
-
- All embeddings generated locally (no cloud APIs)
|
|
20
|
-
- Data stored in local LanceDB databases
|
|
21
|
-
- Complete privacy and control over your memories
|
|
22
|
-
|
|
23
|
-
### ๐ฏ **Intelligent Semantic Search**
|
|
24
|
-
- Vector similarity with multi-factor scoring
|
|
25
|
-
- Considers relevance, recency, priority, and usage frequency
|
|
26
|
-
- Context-aware retrieval based on conversation flow
|
|
27
|
-
|
|
28
|
-
### ๐ **Smart Memory Storage**
|
|
29
|
-
- Stores memories in `~/.local/share/vector-memory-mcp/memories.db`
|
|
30
|
-
- Fast LanceDB-based storage with vector search capabilities
|
|
31
|
-
- Memories persist across sessions and projects
|
|
32
|
-
|
|
33
|
-
### โก **High Performance**
|
|
34
|
-
- Sub-100ms search latency for 1000+ memories
|
|
35
|
-
- Efficient storage (<10MB per 1000 memories)
|
|
36
|
-
- CPU-optimized local embeddings (no GPU required)
|
|
12
|
+
## Features
|
|
37
13
|
|
|
38
|
-
|
|
39
|
-
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
-
|
|
43
|
-
- Built with Bun for maximum performance
|
|
44
|
-
- Simple MCP tools for storing and searching
|
|
45
|
-
- TypeScript for type safety
|
|
14
|
+
- **Local & Private** - All embeddings generated locally, data stored in local LanceDB
|
|
15
|
+
- **Semantic Search** - Vector similarity search with configurable scoring
|
|
16
|
+
- **Batch Operations** - Store, update, delete, and retrieve multiple memories at once
|
|
17
|
+
- **Session Handoffs** - Save and restore project context between sessions
|
|
18
|
+
- **MCP Native** - Standard protocol, works with any MCP-compatible client
|
|
46
19
|
|
|
47
20
|
---
|
|
48
21
|
|
|
49
|
-
##
|
|
22
|
+
## Quick Start
|
|
50
23
|
|
|
51
24
|
### Prerequisites
|
|
52
25
|
|
|
53
|
-
- [Bun](https://bun.sh/) 1.0+
|
|
54
|
-
- An MCP-compatible client
|
|
55
|
-
|
|
56
|
-
> **Note:** This server requires Bun to run.
|
|
26
|
+
- [Bun](https://bun.sh/) 1.0+ (recommended) or [Node.js](https://nodejs.org/) 20+
|
|
27
|
+
- An MCP-compatible client (Claude Code, Claude Desktop, etc.)
|
|
57
28
|
|
|
58
|
-
###
|
|
29
|
+
### Install
|
|
59
30
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
**Install:**
|
|
31
|
+
**With Bun (recommended):**
|
|
63
32
|
```bash
|
|
64
33
|
bun install -g @aeriondyseti/vector-memory-mcp
|
|
65
34
|
```
|
|
66
35
|
|
|
67
|
-
|
|
36
|
+
**With npm/Node.js:**
|
|
37
|
+
```bash
|
|
38
|
+
npm install -g @aeriondyseti/vector-memory-mcp
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
> First install downloads ML models (~90MB). This may take a minute.
|
|
42
|
+
|
|
43
|
+
### Configure
|
|
44
|
+
|
|
45
|
+
Add to your MCP client config (e.g., `~/.claude/settings.json`):
|
|
68
46
|
|
|
69
|
-
**
|
|
47
|
+
**With Bun:**
|
|
70
48
|
```json
|
|
71
49
|
{
|
|
72
50
|
"mcpServers": {
|
|
73
|
-
"memory": {
|
|
51
|
+
"vector-memory": {
|
|
74
52
|
"type": "stdio",
|
|
75
53
|
"command": "bunx",
|
|
76
|
-
"args": [
|
|
77
|
-
"--bun",
|
|
78
|
-
"@aeriondyseti/vector-memory-mcp"
|
|
79
|
-
],
|
|
80
|
-
"env": {}
|
|
54
|
+
"args": ["--bun", "@aeriondyseti/vector-memory-mcp"]
|
|
81
55
|
}
|
|
82
56
|
}
|
|
83
57
|
}
|
|
84
58
|
```
|
|
85
59
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
**Install:**
|
|
89
|
-
```bash
|
|
90
|
-
git clone https://github.com/AerionDyseti/vector-memory-mcp.git
|
|
91
|
-
cd vector-memory-mcp
|
|
92
|
-
bun install
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
**Configure your MCP client** (example config for clients that use `~/.claude/config.json`):
|
|
60
|
+
**With Node.js:**
|
|
96
61
|
```json
|
|
97
62
|
{
|
|
98
63
|
"mcpServers": {
|
|
99
|
-
"memory": {
|
|
100
|
-
"
|
|
101
|
-
"
|
|
64
|
+
"vector-memory": {
|
|
65
|
+
"type": "stdio",
|
|
66
|
+
"command": "npx",
|
|
67
|
+
"args": ["-y", "@aeriondyseti/vector-memory-mcp"]
|
|
102
68
|
}
|
|
103
69
|
}
|
|
104
70
|
}
|
|
105
71
|
```
|
|
106
|
-
*Replace `/absolute/path/to/` with your actual installation path.*
|
|
107
72
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
**What gets installed:**
|
|
111
|
-
- The vector-memory-mcp package and all dependencies
|
|
112
|
-
- Native binaries for ONNX Runtime (~32MB) and image processing (~10MB)
|
|
113
|
-
- ML model files automatically downloaded during installation (~90MB, cached in `~/.cache/huggingface/`)
|
|
114
|
-
- **Total first-time setup:** ~130MB of downloads
|
|
73
|
+
### Use
|
|
115
74
|
|
|
116
|
-
|
|
75
|
+
Restart your MCP client. You now have access to:
|
|
117
76
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
- `get_handoff` - Retrieve the latest handoff (includes referenced memories)
|
|
77
|
+
| Tool | Description |
|
|
78
|
+
|------|-------------|
|
|
79
|
+
| `store_memories` | Save memories (accepts array) |
|
|
80
|
+
| `search_memories` | Find relevant memories semantically |
|
|
81
|
+
| `get_memories` | Retrieve memories by ID (accepts array) |
|
|
82
|
+
| `update_memories` | Update existing memories |
|
|
83
|
+
| `delete_memories` | Remove memories (accepts array) |
|
|
84
|
+
| `store_handoff` | Save session context for later |
|
|
85
|
+
| `get_handoff` | Restore session context |
|
|
128
86
|
|
|
129
87
|
---
|
|
130
88
|
|
|
131
|
-
##
|
|
132
|
-
|
|
133
|
-
### Storing Memories
|
|
134
|
-
|
|
135
|
-
Ask your MCP client/agent to remember things for you:
|
|
89
|
+
## Usage
|
|
136
90
|
|
|
91
|
+
**Store a memory:**
|
|
137
92
|
```
|
|
138
93
|
You: "Remember that we use Drizzle ORM for database access"
|
|
139
|
-
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
Or your MCP client/agent can store memories directly:
|
|
143
|
-
```json
|
|
144
|
-
{
|
|
145
|
-
"content": "Use Drizzle ORM for type-safe database access",
|
|
146
|
-
"metadata": {
|
|
147
|
-
"tags": ["architecture", "database"],
|
|
148
|
-
"category": "tooling"
|
|
149
|
-
}
|
|
150
|
-
}
|
|
94
|
+
Assistant: [calls store_memories]
|
|
151
95
|
```
|
|
152
96
|
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
Your MCP client/agent can automatically search memories when relevant, or you can ask:
|
|
156
|
-
|
|
97
|
+
**Search memories:**
|
|
157
98
|
```
|
|
158
99
|
You: "What did we decide about the database?"
|
|
159
|
-
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
Search parameters:
|
|
163
|
-
```json
|
|
164
|
-
{
|
|
165
|
-
"query": "authentication strategy",
|
|
166
|
-
"limit": 10
|
|
167
|
-
}
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
### Managing Memories
|
|
171
|
-
|
|
172
|
-
Retrieve a specific memory:
|
|
173
|
-
```json
|
|
174
|
-
{
|
|
175
|
-
"id": "memory-id-here"
|
|
176
|
-
}
|
|
177
|
-
```
|
|
178
|
-
|
|
179
|
-
Delete a memory:
|
|
180
|
-
```json
|
|
181
|
-
{
|
|
182
|
-
"id": "memory-id-here"
|
|
183
|
-
}
|
|
100
|
+
Assistant: [calls search_memories with relevant query]
|
|
184
101
|
```
|
|
185
102
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
## ๐๏ธ Architecture
|
|
189
|
-
|
|
190
|
-
```
|
|
191
|
-
vector-memory-mcp/
|
|
192
|
-
โโโ src/
|
|
193
|
-
โ โโโ index.ts # Entry point
|
|
194
|
-
โ โโโ config/ # Configuration management
|
|
195
|
-
โ โโโ db/ # Database layer (LanceDB)
|
|
196
|
-
โ โโโ services/
|
|
197
|
-
โ โ โโโ embeddings.service.ts # Embeddings via @huggingface/transformers
|
|
198
|
-
โ โ โโโ memory.service.ts # Core memory operations
|
|
199
|
-
โ โโโ mcp/
|
|
200
|
-
โ โโโ server.ts # MCP server setup
|
|
201
|
-
โ โโโ tools.ts # MCP tool definitions
|
|
202
|
-
โ โโโ handlers.ts # Tool request handlers
|
|
203
|
-
โโโ tests/
|
|
204
|
-
โ โโโ memory.test.ts
|
|
205
|
-
โ โโโ embeddings.test.ts
|
|
206
|
-
โโโ bin/
|
|
207
|
-
โ โโโ vector-memory-mcp.js # Executable entry point
|
|
208
|
-
โโโ package.json
|
|
209
|
-
```
|
|
210
|
-
|
|
211
|
-
### Technology Stack
|
|
212
|
-
|
|
213
|
-
- **MCP Framework**: @modelcontextprotocol/sdk (official SDK)
|
|
214
|
-
- **Vector Database**: LanceDB (fast, local, vector search)
|
|
215
|
-
- **Embeddings**: [@huggingface/transformers](https://huggingface.co/docs/transformers.js) (Xenova/all-MiniLM-L6-v2, 384 dimensions)
|
|
216
|
-
- **Language**: TypeScript 5.0+
|
|
217
|
-
- **Runtime**: Bun 1.0+
|
|
218
|
-
- **Testing**: Bun test
|
|
219
|
-
|
|
220
|
-
---
|
|
221
|
-
|
|
222
|
-
## ๐จ How It Works
|
|
223
|
-
|
|
224
|
-
### 1. Memory Storage
|
|
225
|
-
|
|
226
|
-
```
|
|
227
|
-
An MCP client calls store_memories tool
|
|
228
|
-
โ
|
|
229
|
-
Content โ @huggingface/transformers โ 384d vector
|
|
230
|
-
โ
|
|
231
|
-
Store in LanceDB with metadata
|
|
232
|
-
โ
|
|
233
|
-
~/.local/share/vector-memory-mcp/memories.db
|
|
234
|
-
```
|
|
235
|
-
|
|
236
|
-
### 2. Memory Retrieval
|
|
237
|
-
|
|
103
|
+
**Session handoffs:**
|
|
238
104
|
```
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
Query โ @huggingface/transformers โ 384d vector
|
|
242
|
-
โ
|
|
243
|
-
Vector search in LanceDB
|
|
244
|
-
โ
|
|
245
|
-
Vector similarity scoring
|
|
246
|
-
โ
|
|
247
|
-
Return top N relevant memories
|
|
105
|
+
You: "Save context for next session"
|
|
106
|
+
Assistant: [calls store_handoff with summary, completed items, next steps]
|
|
248
107
|
```
|
|
249
108
|
|
|
250
109
|
---
|
|
251
110
|
|
|
252
|
-
##
|
|
111
|
+
## Configuration
|
|
253
112
|
|
|
254
|
-
|
|
113
|
+
Environment variables:
|
|
255
114
|
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
Example:
|
|
262
|
-
```bash
|
|
263
|
-
export VECTOR_MEMORY_DB_PATH="/path/to/custom/memories.db"
|
|
264
|
-
export VECTOR_MEMORY_MODEL="Xenova/all-MiniLM-L6-v2"
|
|
265
|
-
```
|
|
266
|
-
|
|
267
|
-
Or in your MCP client config:
|
|
268
|
-
```json
|
|
269
|
-
{
|
|
270
|
-
"mcpServers": {
|
|
271
|
-
"memory": {
|
|
272
|
-
"command": "vector-memory-mcp",
|
|
273
|
-
"env": {
|
|
274
|
-
"VECTOR_MEMORY_DB_PATH": "/custom/path/memories.db"
|
|
275
|
-
}
|
|
276
|
-
}
|
|
277
|
-
}
|
|
278
|
-
}
|
|
279
|
-
```
|
|
115
|
+
| Variable | Default | Description |
|
|
116
|
+
|----------|---------|-------------|
|
|
117
|
+
| `VECTOR_MEMORY_DB_PATH` | `.vector-memory/memories.db` | Database location |
|
|
118
|
+
| `VECTOR_MEMORY_MODEL` | `Xenova/all-MiniLM-L6-v2` | Embedding model |
|
|
119
|
+
| `VECTOR_MEMORY_HTTP_PORT` | `3271` | HTTP server port |
|
|
280
120
|
|
|
281
121
|
---
|
|
282
122
|
|
|
283
|
-
##
|
|
284
|
-
|
|
285
|
-
### Running Tests
|
|
123
|
+
## Development
|
|
286
124
|
|
|
287
125
|
```bash
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
# Run tests directly (skips 19 embedding tests, faster)
|
|
292
|
-
bun test
|
|
293
|
-
|
|
294
|
-
# Run with coverage
|
|
295
|
-
bun test --coverage
|
|
296
|
-
|
|
297
|
-
# Type checking
|
|
298
|
-
bun run typecheck
|
|
299
|
-
```
|
|
300
|
-
|
|
301
|
-
> **Note:** `bun run test` uses a wrapper that preloads the embedding model, running all 98 tests. `bun test` directly is faster but skips embedding-specific tests.
|
|
302
|
-
|
|
303
|
-
### Development Mode
|
|
304
|
-
|
|
305
|
-
```bash
|
|
306
|
-
# Watch mode - auto-restart on file changes
|
|
307
|
-
bun run dev
|
|
308
|
-
|
|
309
|
-
# Run directly without building
|
|
310
|
-
bun run src/index.ts
|
|
311
|
-
```
|
|
312
|
-
|
|
313
|
-
### Building
|
|
314
|
-
|
|
315
|
-
```bash
|
|
316
|
-
# Build for production
|
|
317
|
-
bun run build
|
|
126
|
+
git clone https://github.com/AerionDyseti/vector-memory-mcp.git
|
|
127
|
+
cd vector-memory-mcp
|
|
128
|
+
bun install
|
|
318
129
|
|
|
319
|
-
|
|
130
|
+
bun run test # Run all tests
|
|
131
|
+
bun run dev # Watch mode
|
|
132
|
+
bun run typecheck # Type checking
|
|
320
133
|
```
|
|
321
134
|
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
## ๐บ๏ธ Roadmap
|
|
325
|
-
|
|
326
|
-
### โ
Phase 1: Foundation (Current)
|
|
327
|
-
- โ
Core database with LanceDB
|
|
328
|
-
- โ
Embedding generation with @huggingface/transformers
|
|
329
|
-
- โ
Basic MCP tools (store, search, get, delete)
|
|
330
|
-
- โ
TypeScript implementation with Drizzle ORM
|
|
331
|
-
|
|
332
|
-
### ๐ง Phase 2: Enhanced Search & Scoring
|
|
333
|
-
- Multi-factor scoring algorithm (similarity, recency, priority, usage frequency)
|
|
334
|
-
- Configurable scoring weights
|
|
335
|
-
- Priority levels for memories
|
|
336
|
-
- Usage tracking and frequency-based ranking
|
|
337
|
-
- Metadata filtering and advanced tagging
|
|
338
|
-
|
|
339
|
-
### ๐ Phase 3: Dual-Level Memory System
|
|
340
|
-
- Project-specific memories (`.memory/db` in repo)
|
|
341
|
-
- Global memories (`~/.local/share/vector-memory-mcp/`)
|
|
342
|
-
- Automatic precedence handling (project overrides global)
|
|
343
|
-
- Project detection and context switching
|
|
344
|
-
|
|
345
|
-
### ๐ฏ Phase 4: Smart Automation
|
|
346
|
-
- Auto-detect architectural decisions
|
|
347
|
-
- Capture bug fixes and solutions automatically
|
|
348
|
-
- Generate session-end summaries
|
|
349
|
-
- Natural language trigger detection (85%+ accuracy)
|
|
350
|
-
- Continuous conversation monitoring
|
|
351
|
-
|
|
352
|
-
### ๐ฎ Phase 5: Advanced Features
|
|
353
|
-
- Memory deduplication with similarity threshold
|
|
354
|
-
- Batch operations (import/export)
|
|
355
|
-
- Markdown import/export
|
|
356
|
-
- Memory clustering and visualization
|
|
357
|
-
- Cross-project insights
|
|
358
|
-
- Multi-modal memories (images, diagrams)
|
|
359
|
-
- Session hooks for automatic context injection
|
|
360
|
-
- Multi-CLI support (Cursor, Windsurf, etc.)
|
|
361
|
-
- Smart priority suggestions
|
|
362
|
-
|
|
363
|
-
---
|
|
364
|
-
|
|
365
|
-
## ๐ค Contributing
|
|
366
|
-
|
|
367
|
-
Contributions are welcome! This project is in active development.
|
|
368
|
-
|
|
369
|
-
### Areas We'd Love Help With:
|
|
370
|
-
- Testing and bug reports
|
|
371
|
-
- Documentation improvements
|
|
372
|
-
- Performance optimizations
|
|
373
|
-
- New feature ideas
|
|
374
|
-
|
|
375
|
-
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines *(coming soon)*.
|
|
135
|
+
See [CHANGELOG.md](CHANGELOG.md) for release history and [ROADMAP.md](ROADMAP.md) for planned features.
|
|
376
136
|
|
|
377
137
|
---
|
|
378
138
|
|
|
379
|
-
##
|
|
139
|
+
## Contributing
|
|
380
140
|
|
|
381
|
-
|
|
141
|
+
Contributions welcome! See [issues](https://github.com/AerionDyseti/vector-memory-mcp/issues) for areas we'd love help with.
|
|
382
142
|
|
|
383
|
-
|
|
143
|
+
## License
|
|
384
144
|
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
- Built with [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) - Official MCP TypeScript SDK
|
|
388
|
-
- Uses [LanceDB](https://lancedb.com/) for fast, local vector search
|
|
389
|
-
- Powered by [@huggingface/transformers](https://huggingface.co/docs/transformers.js) for local embeddings
|
|
390
|
-
- Database layer via [Drizzle ORM](https://orm.drizzle.team/)
|
|
391
|
-
- Inspired by [doobidoo's mcp-memory-service](https://github.com/doobidoo/mcp-memory-service)
|
|
145
|
+
MIT - see [LICENSE](LICENSE)
|
|
392
146
|
|
|
393
147
|
---
|
|
394
148
|
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
- [Model Context Protocol](https://modelcontextprotocol.io) - Official MCP specification
|
|
398
|
-
- Any MCP-compatible client
|
|
399
|
-
- [LanceDB](https://lancedb.com/) - Fast, local vector search
|
|
400
|
-
- [Transformers.js](https://huggingface.co/docs/transformers.js) - Run transformers in JavaScript
|
|
401
|
-
|
|
402
|
-
---
|
|
403
|
-
|
|
404
|
-
## ๐ฌ Support
|
|
405
|
-
|
|
406
|
-
- **Issues**: [GitHub Issues](https://github.com/AerionDyseti/vector-memory-mcp/issues)
|
|
407
|
-
- **Discussions**: [GitHub Discussions](https://github.com/AerionDyseti/vector-memory-mcp/discussions)
|
|
408
|
-
- **Documentation**: Check the `docs/` directory
|
|
409
|
-
|
|
410
|
-
---
|
|
411
|
-
|
|
412
|
-
## โก Quick Examples
|
|
413
|
-
|
|
414
|
-
### Example 1: Storing a Decision
|
|
415
|
-
|
|
416
|
-
```
|
|
417
|
-
You: "Remember that we decided to use Drizzle ORM for type-safe database access"
|
|
418
|
-
Claude: I'll store that for you.
|
|
419
|
-
[Calls store_memories tool with content and metadata]
|
|
420
|
-
โ Memory stored successfully
|
|
421
|
-
```
|
|
422
|
-
|
|
423
|
-
### Example 2: Searching Memories
|
|
424
|
-
|
|
425
|
-
```
|
|
426
|
-
You: "What did we decide about database tooling?"
|
|
427
|
-
Claude: Let me search for that...
|
|
428
|
-
[Calls search_memories with query about database]
|
|
429
|
-
Found: "Use Drizzle ORM for type-safe database access"
|
|
430
|
-
|
|
431
|
-
Based on our previous decision, we're using Drizzle ORM...
|
|
432
|
-
```
|
|
433
|
-
|
|
434
|
-
### Example 3: Managing Memories
|
|
435
|
-
|
|
436
|
-
```
|
|
437
|
-
You: "Show me what you remember about authentication"
|
|
438
|
-
Claude: [Searches for authentication-related memories]
|
|
439
|
-
Found 3 memories:
|
|
440
|
-
1. "Use JWT tokens for API authentication"
|
|
441
|
-
2. "Store refresh tokens in httpOnly cookies"
|
|
442
|
-
3. "Implement rate limiting on auth endpoints"
|
|
443
|
-
```
|
|
444
|
-
|
|
445
|
-
---
|
|
446
|
-
|
|
447
|
-
<div align="center">
|
|
448
|
-
|
|
449
|
-
**[โฌ Back to Top](#vector-memory-mcp-server)**
|
|
450
|
-
|
|
451
|
-
Made with โค๏ธ for developers who value context continuity
|
|
452
|
-
|
|
453
|
-
</div>
|
|
149
|
+
Built with [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk), [LanceDB](https://lancedb.com/), and [Transformers.js](https://huggingface.co/docs/transformers.js)
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@aeriondyseti/vector-memory-mcp",
|
|
3
|
+
"version": "0.9.0-alpha.2",
|
|
4
|
+
"description": "A zero-configuration RAG memory server for MCP clients",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "dist/src/index.js",
|
|
7
|
+
"bin": {
|
|
8
|
+
"vector-memory-mcp": "dist/src/index.js"
|
|
9
|
+
},
|
|
10
|
+
"files": [
|
|
11
|
+
"dist",
|
|
12
|
+
"scripts",
|
|
13
|
+
"hooks",
|
|
14
|
+
"README.md",
|
|
15
|
+
"LICENSE"
|
|
16
|
+
],
|
|
17
|
+
"repository": {
|
|
18
|
+
"type": "git",
|
|
19
|
+
"url": "git+https://github.com/AerionDyseti/vector-memory-mcp.git"
|
|
20
|
+
},
|
|
21
|
+
"author": "AerionDyseti",
|
|
22
|
+
"bugs": {
|
|
23
|
+
"url": "https://github.com/AerionDyseti/vector-memory-mcp/issues"
|
|
24
|
+
},
|
|
25
|
+
"homepage": "https://github.com/AerionDyseti/vector-memory-mcp#readme",
|
|
26
|
+
"scripts": {
|
|
27
|
+
"start": "node dist/src/index.js",
|
|
28
|
+
"dev": "bun run build && node dist/src/index.js",
|
|
29
|
+
"dev:watch": "bun run build && bun --watch run src/index.ts",
|
|
30
|
+
"build": "tsc",
|
|
31
|
+
"prebuild": "rm -rf dist",
|
|
32
|
+
"typecheck": "bunx tsc --noEmit",
|
|
33
|
+
"test": "bun run scripts/test-runner.ts",
|
|
34
|
+
"test:raw": "bun test --preload ./tests/preload.ts",
|
|
35
|
+
"test:quick": "bun test",
|
|
36
|
+
"test:coverage": "bun test --preload ./tests/preload.ts --coverage",
|
|
37
|
+
"test:preload": "bun run tests/preload.ts",
|
|
38
|
+
"warmup": "node dist/scripts/warmup.js",
|
|
39
|
+
"postinstall": "node dist/scripts/warmup.js",
|
|
40
|
+
"publish:check": "bun run scripts/publish.ts --dry-run",
|
|
41
|
+
"publish:npm": "bun run scripts/publish.ts",
|
|
42
|
+
"publish:alpha": "npm publish --access public --tag alpha",
|
|
43
|
+
"prepublishOnly": "bun run build"
|
|
44
|
+
},
|
|
45
|
+
"keywords": [
|
|
46
|
+
"mcp",
|
|
47
|
+
"memory",
|
|
48
|
+
"rag",
|
|
49
|
+
"embeddings",
|
|
50
|
+
"lancedb"
|
|
51
|
+
],
|
|
52
|
+
"license": "MIT",
|
|
53
|
+
"dependencies": {
|
|
54
|
+
"@hono/node-server": "^1.19.7",
|
|
55
|
+
"@huggingface/transformers": "^3.8.0",
|
|
56
|
+
"@lancedb/lancedb": "^0.22.3",
|
|
57
|
+
"@modelcontextprotocol/sdk": "^1.0.0",
|
|
58
|
+
"arg": "^5.0.2",
|
|
59
|
+
"hono": "^4.11.3"
|
|
60
|
+
},
|
|
61
|
+
"devDependencies": {
|
|
62
|
+
"@types/bun": "latest",
|
|
63
|
+
"typescript": "^5.0.0"
|
|
64
|
+
},
|
|
65
|
+
"trustedDependencies": [
|
|
66
|
+
"onnxruntime-node",
|
|
67
|
+
"protobufjs",
|
|
68
|
+
"sharp"
|
|
69
|
+
],
|
|
70
|
+
"overrides": {
|
|
71
|
+
"onnxruntime-node": "1.23.2"
|
|
72
|
+
}
|
|
73
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
#!/usr/bin/env bun
|
|
2
|
+
/**
|
|
3
|
+
* Publish script for vector-memory-mcp
|
|
4
|
+
*
|
|
5
|
+
* Prerequisites:
|
|
6
|
+
* 1. Create a granular access token at https://www.npmjs.com/settings/tokens
|
|
7
|
+
* 2. Store it: npm config set //registry.npmjs.org/:_authToken=npm_YOUR_TOKEN
|
|
8
|
+
* Or set NPM_TOKEN environment variable
|
|
9
|
+
*
|
|
10
|
+
* Usage: bun run scripts/publish.ts [--dry-run]
|
|
11
|
+
*/
|
|
12
|
+
export {};
|
|
13
|
+
//# sourceMappingURL=publish.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"publish.d.ts","sourceRoot":"","sources":["../../scripts/publish.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG"}
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
#!/usr/bin/env bun
|
|
2
|
+
/**
|
|
3
|
+
* Publish script for vector-memory-mcp
|
|
4
|
+
*
|
|
5
|
+
* Prerequisites:
|
|
6
|
+
* 1. Create a granular access token at https://www.npmjs.com/settings/tokens
|
|
7
|
+
* 2. Store it: npm config set //registry.npmjs.org/:_authToken=npm_YOUR_TOKEN
|
|
8
|
+
* Or set NPM_TOKEN environment variable
|
|
9
|
+
*
|
|
10
|
+
* Usage: bun run scripts/publish.ts [--dry-run]
|
|
11
|
+
*/
|
|
12
|
+
import { $ } from "bun";
|
|
13
|
+
const dryRun = process.argv.includes("--dry-run");
|
|
14
|
+
async function main() {
|
|
15
|
+
// Check for authentication
|
|
16
|
+
console.log("๐ Checking NPM authentication...");
|
|
17
|
+
try {
|
|
18
|
+
const whoami = await $ `npm whoami`.text();
|
|
19
|
+
console.log(`โ
Authenticated as: ${whoami.trim()}`);
|
|
20
|
+
}
|
|
21
|
+
catch {
|
|
22
|
+
console.error("โ Not authenticated with NPM.");
|
|
23
|
+
console.error(" Option 1: npm login");
|
|
24
|
+
console.error(" Option 2: npm config set //registry.npmjs.org/:_authToken=npm_YOUR_TOKEN");
|
|
25
|
+
console.error(" Option 3: Set NPM_TOKEN environment variable");
|
|
26
|
+
process.exit(1);
|
|
27
|
+
}
|
|
28
|
+
// Run tests
|
|
29
|
+
console.log("๐งช Running tests...");
|
|
30
|
+
const testResult = await $ `bun run test`.quiet();
|
|
31
|
+
if (testResult.exitCode !== 0) {
|
|
32
|
+
console.error("โ Tests failed. Aborting publish.");
|
|
33
|
+
process.exit(1);
|
|
34
|
+
}
|
|
35
|
+
console.log("โ
Tests passed");
|
|
36
|
+
// Build
|
|
37
|
+
console.log("๐จ Building...");
|
|
38
|
+
await $ `bun run build`;
|
|
39
|
+
console.log("โ
Build complete");
|
|
40
|
+
// Get version info
|
|
41
|
+
const pkg = await Bun.file("package.json").json();
|
|
42
|
+
console.log(`\n๐ฆ Publishing ${pkg.name}@${pkg.version}...`);
|
|
43
|
+
if (dryRun) {
|
|
44
|
+
console.log("๐ Dry run - would publish:");
|
|
45
|
+
await $ `npm publish --dry-run`;
|
|
46
|
+
}
|
|
47
|
+
else {
|
|
48
|
+
await $ `npm publish --access public`;
|
|
49
|
+
console.log(`\nโ
Published ${pkg.name}@${pkg.version}`);
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
main().catch((err) => {
|
|
53
|
+
console.error("โ Publish failed:", err.message);
|
|
54
|
+
process.exit(1);
|
|
55
|
+
});
|
|
56
|
+
//# sourceMappingURL=publish.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"publish.js","sourceRoot":"","sources":["../../scripts/publish.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAElD,KAAK,UAAU,IAAI;IACjB,2BAA2B;IAC3B,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;IACjD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,CAAC,CAAA,YAAY,CAAC,IAAI,EAAE,CAAC;QAC1C,OAAO,CAAC,GAAG,CAAC,uBAAuB,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;QAC/C,OAAO,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;QACxC,OAAO,CAAC,KAAK,CAAC,6EAA6E,CAAC,CAAC;QAC7F,OAAO,CAAC,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACjE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,YAAY;IACZ,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IACnC,MAAM,UAAU,GAAG,MAAM,CAAC,CAAA,cAAc,CAAC,KAAK,EAAE,CAAC;IACjD,IAAI,UAAU,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACnD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAE9B,QAAQ;IACR,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC9B,MAAM,CAAC,CAAA,eAAe,CAAC;IACvB,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAEhC,mBAAmB;IACnB,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,IAAI,EAAE,CAAC;IAClD,OAAO,CAAC,GAAG,CAAC,mBAAmB,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC;IAE7D,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;QAC3C,MAAM,CAAC,CAAA,uBAAuB,CAAC;IACjC,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,CAAA,6BAA6B,CAAC;QACrC,OAAO,CAAC,GAAG,CAAC,iBAAiB,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,mBAAmB,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
|