memory-pulse-mcp-server 0.1.0 → 0.1.3
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 +412 -31
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,65 +1,446 @@
|
|
|
1
1
|
# Memory Pulse MCP Server
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://github.com/jiahuidegit/memory-mcp-server)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
[](https://nodejs.org/)
|
|
6
|
+
[](https://www.npmjs.com/package/memory-pulse-mcp-server)
|
|
7
|
+
[](https://www.npmjs.com/package/memory-pulse-mcp-server)
|
|
4
8
|
|
|
5
|
-
|
|
9
|
+
**A precise, structured AI context memory system. MCP Server designed for Claude Code.**
|
|
10
|
+
|
|
11
|
+
> **If you find this project helpful, please give it a star on [GitHub](https://github.com/jiahuidegit/memory-mcp-server)!** Your support helps us improve!
|
|
12
|
+
|
|
13
|
+
[English](https://github.com/jiahuidegit/memory-mcp-server#readme) | [中文](https://github.com/jiahuidegit/memory-mcp-server/blob/main/README_CN.md)
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Why Memory Pulse?
|
|
18
|
+
|
|
19
|
+
### The Problem with Existing AI Memory Solutions
|
|
20
|
+
|
|
21
|
+
| Problem | Traditional Solutions | Memory Pulse |
|
|
22
|
+
|---------|----------------------|--------------|
|
|
23
|
+
| **Information Loss** | Vector compression loses details | Complete context preservation |
|
|
24
|
+
| **Imprecise Retrieval** | Semantic-only search misses exact matches | Multi-level: Exact → Full-text → Semantic |
|
|
25
|
+
| **Decision Gap** | Stores conclusions, not reasoning | Structured: Problem → Analysis → Options → Decision |
|
|
26
|
+
| **Context Fragmentation** | Scattered, unrelated memories | Relationship chains & timeline tracking |
|
|
27
|
+
|
|
28
|
+
### Comparison with Other Memory Systems
|
|
29
|
+
|
|
30
|
+
| Feature | Memory Pulse | mem0 | Zep | LangChain Memory |
|
|
31
|
+
|---------|-------------|------|-----|------------------|
|
|
32
|
+
| **Storage** | Full context (no compression) | Vector embeddings | Vector + Graph | Vector embeddings |
|
|
33
|
+
| **Retrieval Strategy** | L1 Exact → L2 Full-text → L3 Semantic | Semantic only | Semantic + Temporal | Semantic only |
|
|
34
|
+
| **Decision Tracking** | Forced structured fields | - | - | - |
|
|
35
|
+
| **Relationship Graph** | Built-in | - | Built-in | - |
|
|
36
|
+
| **Timeline View** | Built-in | - | Built-in | - |
|
|
37
|
+
| **MCP Native** | Yes | - | - | - |
|
|
38
|
+
| **Local-first** | SQLite | Cloud-dependent | Cloud-dependent | Varies |
|
|
39
|
+
| **Zero Config** | Yes | - | - | - |
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## Features
|
|
44
|
+
|
|
45
|
+
- **Complete Context Preservation** - No compression, no information loss
|
|
46
|
+
- **Multi-level Retrieval** - L1 Exact match → L2 Full-text search → L3 Semantic search
|
|
47
|
+
- **Structured Memory Types** - Decision / Solution / Session / Code / Error / Config
|
|
48
|
+
- **Relationship Chains** - Track how memories relate and evolve
|
|
49
|
+
- **Timeline View** - See memory evolution over time
|
|
50
|
+
- **Forced Structure** - AI must provide complete context (no lazy summaries)
|
|
51
|
+
- **Local-first** - SQLite storage, your data stays with you
|
|
52
|
+
- **Zero Config** - Works out of the box
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## Quick Start
|
|
57
|
+
|
|
58
|
+
### Option 1: Run with npx (Recommended)
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
npx memory-pulse-mcp-server
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### Option 2: Global Installation
|
|
6
65
|
|
|
7
66
|
```bash
|
|
8
67
|
npm install -g memory-pulse-mcp-server
|
|
68
|
+
memory-pulse-mcp
|
|
9
69
|
```
|
|
10
70
|
|
|
11
|
-
|
|
71
|
+
### Option 3: Build from Source
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
git clone https://github.com/jiahuidegit/memory-mcp-server.git
|
|
75
|
+
cd memory-mcp-server
|
|
76
|
+
pnpm install
|
|
77
|
+
pnpm build
|
|
78
|
+
```
|
|
12
79
|
|
|
13
|
-
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## Update to Latest Version
|
|
83
|
+
|
|
84
|
+
### If using npx (Recommended)
|
|
85
|
+
|
|
86
|
+
npx automatically uses the latest version, just restart your MCP client.
|
|
87
|
+
|
|
88
|
+
### If globally installed
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
npm update -g memory-pulse-mcp-server
|
|
92
|
+
# Or reinstall
|
|
93
|
+
npm install -g memory-pulse-mcp-server@latest
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### Check current version
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
npm list -g memory-pulse-mcp-server
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## MCP Client Configuration
|
|
105
|
+
|
|
106
|
+
### Claude Code
|
|
107
|
+
|
|
108
|
+
Create `.mcp.json` in your project directory:
|
|
14
109
|
|
|
15
110
|
```json
|
|
16
111
|
{
|
|
17
112
|
"mcpServers": {
|
|
18
113
|
"memory-pulse": {
|
|
19
|
-
"command": "
|
|
20
|
-
"args": []
|
|
114
|
+
"command": "npx",
|
|
115
|
+
"args": ["-y", "memory-pulse-mcp-server"]
|
|
21
116
|
}
|
|
22
117
|
}
|
|
23
118
|
}
|
|
24
119
|
```
|
|
25
120
|
|
|
26
|
-
|
|
121
|
+
Or global configuration at `~/.claude/mcp.json`:
|
|
122
|
+
|
|
123
|
+
```json
|
|
124
|
+
{
|
|
125
|
+
"mcpServers": {
|
|
126
|
+
"memory-pulse": {
|
|
127
|
+
"command": "npx",
|
|
128
|
+
"args": ["-y", "memory-pulse-mcp-server"]
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
```
|
|
27
133
|
|
|
28
|
-
|
|
29
|
-
|------|------|
|
|
30
|
-
| `mpulse_store` | 智能存储记忆，AI 自动分类和结构化 |
|
|
31
|
-
| `mpulse_store_decision` | 存储架构决策（强制字段，防止 AI 偷懒） |
|
|
32
|
-
| `mpulse_store_solution` | 存储问题解决方案 |
|
|
33
|
-
| `mpulse_store_session` | 存储会话总结（会话结束时调用） |
|
|
34
|
-
| `mpulse_recall` | 检索记忆（多策略：精确、全文、语义） |
|
|
35
|
-
| `mpulse_timeline` | 查看项目的时间线视图 |
|
|
36
|
-
| `mpulse_relations` | 查询记忆的关系链 |
|
|
134
|
+
### Claude Desktop
|
|
37
135
|
|
|
38
|
-
|
|
136
|
+
Edit the configuration file:
|
|
39
137
|
|
|
40
|
-
|
|
138
|
+
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
139
|
+
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
41
140
|
|
|
141
|
+
```json
|
|
142
|
+
{
|
|
143
|
+
"mcpServers": {
|
|
144
|
+
"memory-pulse": {
|
|
145
|
+
"command": "npx",
|
|
146
|
+
"args": ["-y", "memory-pulse-mcp-server"]
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
}
|
|
42
150
|
```
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
151
|
+
|
|
152
|
+
Restart the client after configuration.
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## Environment Variables
|
|
157
|
+
|
|
158
|
+
| Variable | Description | Default |
|
|
159
|
+
|----------|-------------|---------|
|
|
160
|
+
| `MEMORY_STORAGE` | Storage type: `sqlite` or `postgresql` | `sqlite` |
|
|
161
|
+
| `MEMORY_DB_PATH` | SQLite database file path | `./memory.db` |
|
|
162
|
+
| `DATABASE_URL` | PostgreSQL connection string (required for postgresql) | - |
|
|
163
|
+
|
|
164
|
+
### SQLite Storage (Default)
|
|
165
|
+
|
|
166
|
+
Zero configuration, works out of the box:
|
|
167
|
+
|
|
168
|
+
```json
|
|
169
|
+
{
|
|
170
|
+
"mcpServers": {
|
|
171
|
+
"memory-pulse": {
|
|
172
|
+
"command": "npx",
|
|
173
|
+
"args": ["-y", "memory-pulse-mcp-server"]
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
}
|
|
48
177
|
```
|
|
49
178
|
|
|
50
|
-
###
|
|
179
|
+
### Custom SQLite Path
|
|
51
180
|
|
|
181
|
+
```json
|
|
182
|
+
{
|
|
183
|
+
"mcpServers": {
|
|
184
|
+
"memory-pulse": {
|
|
185
|
+
"command": "npx",
|
|
186
|
+
"args": ["-y", "memory-pulse-mcp-server"],
|
|
187
|
+
"env": {
|
|
188
|
+
"MEMORY_DB_PATH": "/path/to/your/memory.db"
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
}
|
|
52
193
|
```
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
194
|
+
|
|
195
|
+
### PostgreSQL Storage
|
|
196
|
+
|
|
197
|
+
For production deployments or team usage:
|
|
198
|
+
|
|
199
|
+
```json
|
|
200
|
+
{
|
|
201
|
+
"mcpServers": {
|
|
202
|
+
"memory-pulse": {
|
|
203
|
+
"command": "npx",
|
|
204
|
+
"args": ["-y", "memory-pulse-mcp-server"],
|
|
205
|
+
"env": {
|
|
206
|
+
"MEMORY_STORAGE": "postgresql",
|
|
207
|
+
"DATABASE_URL": "postgresql://user:password@localhost:5432/memory_pulse"
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
}
|
|
57
212
|
```
|
|
58
213
|
|
|
59
|
-
|
|
214
|
+
> **Note**: PostgreSQL storage requires `@prisma/client`. Install it manually if needed:
|
|
215
|
+
> ```bash
|
|
216
|
+
> npm install @prisma/client
|
|
217
|
+
> ```
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
## MCP Tools
|
|
222
|
+
|
|
223
|
+
### Memory Storage
|
|
224
|
+
|
|
225
|
+
| Tool | Description |
|
|
226
|
+
|------|-------------|
|
|
227
|
+
| `mpulse_store` | Smart memory storage with auto-classification |
|
|
228
|
+
| `mpulse_store_decision` | Store architectural decisions (forced complete fields) |
|
|
229
|
+
| `mpulse_store_solution` | Store problem solutions (problem → root cause → solution) |
|
|
230
|
+
| `mpulse_store_session` | Store session summaries (call at session end) |
|
|
231
|
+
|
|
232
|
+
### Memory Retrieval
|
|
233
|
+
|
|
234
|
+
| Tool | Description |
|
|
235
|
+
|------|-------------|
|
|
236
|
+
| `mpulse_recall` | Multi-strategy memory retrieval |
|
|
237
|
+
| `mpulse_timeline` | View project timeline |
|
|
238
|
+
| `mpulse_relations` | Query memory relationship chains |
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
## Usage Examples
|
|
243
|
+
|
|
244
|
+
### Store a Decision
|
|
245
|
+
|
|
246
|
+
When you make an architectural decision, AI calls `mpulse_store_decision`:
|
|
60
247
|
|
|
61
|
-
|
|
248
|
+
```
|
|
249
|
+
User: Let's use Zustand for state management instead of Redux
|
|
250
|
+
|
|
251
|
+
AI: [calls mpulse_store_decision]
|
|
252
|
+
{
|
|
253
|
+
"question": "Which state management solution to use?",
|
|
254
|
+
"options": [
|
|
255
|
+
{ "name": "Redux", "pros": ["Mature ecosystem", "DevTools"], "cons": ["Boilerplate heavy"] },
|
|
256
|
+
{ "name": "Zustand", "pros": ["Lightweight", "TypeScript friendly"], "cons": ["Smaller ecosystem"] }
|
|
257
|
+
],
|
|
258
|
+
"chosen": "Zustand",
|
|
259
|
+
"reason": "Project is medium-sized, prioritizing development efficiency. Zustand has lower learning curve.",
|
|
260
|
+
"projectId": "my-app"
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
Decision stored with ID: mem_xxx
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
### Store a Solution
|
|
267
|
+
|
|
268
|
+
When you solve a problem, AI calls `mpulse_store_solution`:
|
|
269
|
+
|
|
270
|
+
```
|
|
271
|
+
User: Fixed the memory leak in useEffect
|
|
272
|
+
|
|
273
|
+
AI: [calls mpulse_store_solution]
|
|
274
|
+
{
|
|
275
|
+
"problem": "Memory leak warning in React component",
|
|
276
|
+
"rootCause": "Async operation continues after component unmount",
|
|
277
|
+
"solution": "Added cleanup function in useEffect to cancel pending requests",
|
|
278
|
+
"projectId": "my-app"
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
Solution stored with ID: mem_xxx
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
### Recall Memories
|
|
285
|
+
|
|
286
|
+
When you need context from previous sessions:
|
|
287
|
+
|
|
288
|
+
```
|
|
289
|
+
User: What did we decide about state management?
|
|
290
|
+
|
|
291
|
+
AI: [calls mpulse_recall]
|
|
292
|
+
{
|
|
293
|
+
"query": "state management",
|
|
294
|
+
"projectId": "my-app",
|
|
295
|
+
"strategy": "fulltext"
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
Found: Decision from 2 days ago - Chose Zustand because...
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
### View Timeline
|
|
302
|
+
|
|
303
|
+
```
|
|
304
|
+
User: Show me what we worked on this week
|
|
305
|
+
|
|
306
|
+
AI: [calls mpulse_timeline]
|
|
307
|
+
{
|
|
308
|
+
"projectId": "my-app",
|
|
309
|
+
"limit": 20
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
Timeline:
|
|
313
|
+
- Jan 15: Decision - State management (Zustand)
|
|
314
|
+
- Jan 15: Solution - Memory leak fix
|
|
315
|
+
- Jan 14: Decision - API architecture (REST vs GraphQL)
|
|
316
|
+
...
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
### Query Relationships
|
|
320
|
+
|
|
321
|
+
```
|
|
322
|
+
User: What decisions are related to our API design?
|
|
323
|
+
|
|
324
|
+
AI: [calls mpulse_relations]
|
|
325
|
+
{
|
|
326
|
+
"memoryId": "mem_api_decision",
|
|
327
|
+
"depth": 2
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
Relationships:
|
|
331
|
+
- mem_api_decision (Decision: REST API)
|
|
332
|
+
├── mem_auth_solution (Solution: JWT implementation)
|
|
333
|
+
└── mem_error_handling (Decision: Error response format)
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
---
|
|
337
|
+
|
|
338
|
+
## Retrieval Algorithm
|
|
339
|
+
|
|
340
|
+
Memory Pulse uses a **3-level cascade retrieval strategy**:
|
|
341
|
+
|
|
342
|
+
```
|
|
343
|
+
┌─────────────────────────────────────────────────────┐
|
|
344
|
+
│ User Query │
|
|
345
|
+
└─────────────────────┬───────────────────────────────┘
|
|
346
|
+
▼
|
|
347
|
+
┌─────────────────────────────────────────────────────┐
|
|
348
|
+
│ L1: Exact Match (< 10ms) │
|
|
349
|
+
│ - projectId + type + keywords index │
|
|
350
|
+
│ - Returns if matches ≥ 5 │
|
|
351
|
+
└─────────────────────┬───────────────────────────────┘
|
|
352
|
+
▼ (if insufficient)
|
|
353
|
+
┌─────────────────────────────────────────────────────┐
|
|
354
|
+
│ L2: Full-text Search (< 100ms) │
|
|
355
|
+
│ - SQLite FTS5 / PostgreSQL full-text │
|
|
356
|
+
│ - Chinese + English tokenization │
|
|
357
|
+
│ - Returns if matches ≥ 3 │
|
|
358
|
+
└─────────────────────┬───────────────────────────────┘
|
|
359
|
+
▼ (if insufficient)
|
|
360
|
+
┌─────────────────────────────────────────────────────┐
|
|
361
|
+
│ L3: Semantic Search (< 500ms) │
|
|
362
|
+
│ - Embedding similarity (optional) │
|
|
363
|
+
│ - Fallback for fuzzy queries │
|
|
364
|
+
└─────────────────────────────────────────────────────┘
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
**Why this approach?**
|
|
368
|
+
|
|
369
|
+
- **Precision first**: Exact matches are faster and more accurate
|
|
370
|
+
- **Graceful degradation**: Falls back to broader search when needed
|
|
371
|
+
- **No false positives**: Semantic search is last resort, not default
|
|
372
|
+
|
|
373
|
+
---
|
|
374
|
+
|
|
375
|
+
## Memory Types
|
|
376
|
+
|
|
377
|
+
| Type | Use Case | Required Fields |
|
|
378
|
+
|------|----------|-----------------|
|
|
379
|
+
| `decision` | Architectural choices | question, options, chosen, reason |
|
|
380
|
+
| `solution` | Problem fixes | problem, rootCause, solution |
|
|
381
|
+
| `session` | Session summaries | summary, decisions, nextSteps |
|
|
382
|
+
| `code` | Code implementations | content, artifacts |
|
|
383
|
+
| `error` | Error records | content, stackTrace |
|
|
384
|
+
| `config` | Configuration info | content, settings |
|
|
385
|
+
|
|
386
|
+
---
|
|
387
|
+
|
|
388
|
+
## Security & Privacy
|
|
389
|
+
|
|
390
|
+
1. **Local-first** - All data stored locally in SQLite, no cloud dependency
|
|
391
|
+
2. **Your Data** - Database file is yours, backup/migrate anytime
|
|
392
|
+
3. **No Telemetry** - Zero data collection or phone-home
|
|
393
|
+
4. **Project Isolation** - Memories isolated by projectId
|
|
394
|
+
|
|
395
|
+
---
|
|
396
|
+
|
|
397
|
+
## Roadmap
|
|
398
|
+
|
|
399
|
+
- [x] MCP Server core functionality
|
|
400
|
+
- [x] SQLite local storage
|
|
401
|
+
- [x] PostgreSQL cloud support
|
|
402
|
+
- [x] Multi-level retrieval (Exact + Full-text)
|
|
403
|
+
- [x] Decision/Solution/Session structured storage
|
|
404
|
+
- [ ] Web Dashboard for visualization
|
|
405
|
+
- [ ] CLI tool for manual operations
|
|
406
|
+
- [ ] Semantic search (Embedding)
|
|
407
|
+
- [ ] Team collaboration features
|
|
408
|
+
|
|
409
|
+
---
|
|
410
|
+
|
|
411
|
+
## Star History
|
|
412
|
+
|
|
413
|
+
<a href="https://star-history.com/#jiahuidegit/memory-mcp-server&Date">
|
|
414
|
+
<picture>
|
|
415
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=jiahuidegit/memory-mcp-server&type=Date&theme=dark" />
|
|
416
|
+
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=jiahuidegit/memory-mcp-server&type=Date" />
|
|
417
|
+
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=jiahuidegit/memory-mcp-server&type=Date" />
|
|
418
|
+
</picture>
|
|
419
|
+
</a>
|
|
420
|
+
|
|
421
|
+
---
|
|
422
|
+
|
|
423
|
+
## Contributing
|
|
424
|
+
|
|
425
|
+
Issues and Pull Requests are welcome!
|
|
426
|
+
|
|
427
|
+
```bash
|
|
428
|
+
# Development
|
|
429
|
+
git clone https://github.com/jiahuidegit/memory-mcp-server.git
|
|
430
|
+
cd memory-mcp-server
|
|
431
|
+
pnpm install
|
|
432
|
+
pnpm build
|
|
433
|
+
pnpm test
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
---
|
|
62
437
|
|
|
63
438
|
## License
|
|
64
439
|
|
|
65
|
-
MIT
|
|
440
|
+
This project is licensed under the [MIT License](LICENSE).
|
|
441
|
+
|
|
442
|
+
---
|
|
443
|
+
|
|
444
|
+
**If you find this project helpful, please give it a star!**
|
|
445
|
+
|
|
446
|
+
**Feel free to open issues for questions or submit PRs for improvements!**
|