@whenmoon-afk/memory-mcp 2.2.1 → 2.3.0
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 +53 -447
- package/dist/index.js +32 -2
- package/dist/index.js.map +1 -1
- package/install.js +0 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,502 +1,108 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Memory MCP
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@whenmoon-afk/memory-mcp)
|
|
4
4
|
[](https://opensource.org/licenses/MIT)
|
|
5
|
-
[](https://nodejs.org/)
|
|
6
5
|
|
|
7
|
-
|
|
8
|
-
A lightweight, **zero-cloud**, **token-efficient** Model Context Protocol (MCP) server that gives your AI **durable, searchable, and context-aware memory** - entirely under your control.
|
|
6
|
+
Local, persistent memory for Claude Desktop and MCP-compatible AI assistants.
|
|
9
7
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
Works with **Claude Desktop**, **Cursor**, **Windsurf**, or any MCP client.
|
|
13
|
-
|
|
14
|
-
📦 **Now available on npm**: Install with `npx @whenmoon-afk/memory-mcp`
|
|
15
|
-
|
|
16
|
-
---
|
|
17
|
-
|
|
18
|
-
## Why Local Memory?
|
|
19
|
-
|
|
20
|
-
| You Control | Cloud Services |
|
|
21
|
-
|-----------|----------------|
|
|
22
|
-
| Data never leaves your machine | Sent to remote servers |
|
|
23
|
-
| Portable `.db` file | Locked in proprietary storage |
|
|
24
|
-
| Full audit & backup | Opaque retention policies |
|
|
25
|
-
| Zero recurring cost | Subscription required |
|
|
26
|
-
|
|
27
|
-
---
|
|
28
|
-
|
|
29
|
-
## Features
|
|
30
|
-
|
|
31
|
-
| Feature | Benefit |
|
|
32
|
-
|-------|--------|
|
|
33
|
-
| **Dual-Response Pattern** | Returns *all* matches (compact index) + full *details* within token budget |
|
|
34
|
-
| **Token Budgeting** | Auto-respects `max_tokens` (~30% index, ~70% details) |
|
|
35
|
-
| **Hybrid Relevance Scoring** | 40% relevance, 30% importance, 20% recency, 10% frequency |
|
|
36
|
-
| **Auto-Summarization** | Generates ≤20-word natural-language summaries |
|
|
37
|
-
| **Entity Extraction** | Detects people, tools, concepts, preferences |
|
|
38
|
-
| **FTS5 Full-Text Search** | Sub-10ms queries, Unicode, stemming — no embeddings |
|
|
39
|
-
| **Provenance Tracking** | Full audit trail: source, timestamp, updates |
|
|
40
|
-
| **Soft Deletes** | Memories preserved for debugging/rollback |
|
|
41
|
-
| **Single-File DB** | `memory.db` — copy, backup, move freely |
|
|
42
|
-
|
|
43
|
-
---
|
|
8
|
+
A lightweight MCP server that gives your AI durable, searchable memory — entirely on your machine. Built with TypeScript, SQLite + FTS5, and minimal dependencies.
|
|
44
9
|
|
|
45
10
|
## Installation
|
|
46
11
|
|
|
47
|
-
|
|
48
|
-
- Node.js ≥ 18
|
|
49
|
-
- An **MCP-compatible client** (Claude Desktop, Cursor, Windsurf, etc.)
|
|
12
|
+
Requires Node.js 18+
|
|
50
13
|
|
|
51
|
-
|
|
14
|
+
Run this command to automatically configure Claude Desktop:
|
|
52
15
|
|
|
53
|
-
**Automatic installation** (configures Claude Desktop for you):
|
|
54
16
|
```bash
|
|
55
17
|
npx @whenmoon-afk/memory-mcp
|
|
56
18
|
```
|
|
57
19
|
|
|
58
|
-
This will automatically:
|
|
59
|
-
- Detect your operating system (macOS/Windows/Linux)
|
|
60
|
-
- Add the memory server to your Claude Desktop configuration
|
|
61
|
-
- Create a backup of your existing config
|
|
62
|
-
- Configure the correct command format for your platform
|
|
63
|
-
|
|
64
|
-
After installation, **restart Claude Desktop completely** (quit and reopen).
|
|
65
|
-
|
|
66
|
-
**Or install globally**:
|
|
67
|
-
```bash
|
|
68
|
-
npm install -g @whenmoon-afk/memory-mcp
|
|
69
|
-
memory-mcp
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
### Option 2: From Source
|
|
73
|
-
|
|
74
|
-
For development or customization:
|
|
75
|
-
```bash
|
|
76
|
-
git clone https://github.com/WhenMoon-afk/claude-memory-mcp.git
|
|
77
|
-
cd claude-memory-mcp
|
|
78
|
-
npm install
|
|
79
|
-
npm run build
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
> Output: `dist/index.js` — your memory server.
|
|
83
|
-
|
|
84
|
-
---
|
|
85
|
-
|
|
86
|
-
### Claude Code Installation
|
|
87
|
-
|
|
88
|
-
For users of Claude Code (terminal-based Claude), use the `claude mcp add` command:
|
|
89
|
-
|
|
90
|
-
**Global Memory (user-wide, persists across all projects):**
|
|
91
|
-
```bash
|
|
92
|
-
claude mcp add memory -s user -- npx -y @whenmoon-afk/memory-mcp
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
**Per-Project Memory (project-specific, stored in project directory):**
|
|
96
|
-
```bash
|
|
97
|
-
claude mcp add memory -s local -e MEMORY_DB_PATH=./memory.db -- npx -y @whenmoon-afk/memory-mcp
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
**Verify installation:**
|
|
101
|
-
```bash
|
|
102
|
-
claude mcp list
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
> **Tip:** Use `--scope user` for personal knowledge that spans projects. Use `--scope local` with `MEMORY_DB_PATH=./memory.db` for codebase-specific context that stays with the repository.
|
|
106
|
-
|
|
107
|
-
---
|
|
108
|
-
|
|
109
|
-
## Docker Deployment
|
|
110
|
-
|
|
111
|
-
Run the Memory MCP server in a containerized environment with persistent storage.
|
|
112
|
-
|
|
113
|
-
### Prerequisites
|
|
114
|
-
- Docker installed ([Get Docker](https://docs.docker.com/get-docker/))
|
|
115
|
-
- Docker Compose (included with Docker Desktop)
|
|
116
|
-
|
|
117
|
-
### Quick Start with Docker Compose
|
|
118
|
-
|
|
119
|
-
**1. Clone the repository:**
|
|
120
|
-
```bash
|
|
121
|
-
git clone https://github.com/WhenMoon-afk/claude-memory-mcp.git
|
|
122
|
-
cd claude-memory-mcp
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
**2. Start the container:**
|
|
126
|
-
```bash
|
|
127
|
-
docker-compose up -d
|
|
128
|
-
```
|
|
129
|
-
|
|
130
20
|
This will:
|
|
131
|
-
-
|
|
132
|
-
-
|
|
133
|
-
-
|
|
134
|
-
|
|
135
|
-
**3. View logs:**
|
|
136
|
-
```bash
|
|
137
|
-
docker-compose logs -f memory-mcp
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
**4. Stop the container:**
|
|
141
|
-
```bash
|
|
142
|
-
docker-compose down
|
|
143
|
-
```
|
|
144
|
-
|
|
145
|
-
### Manual Docker Build
|
|
146
|
-
|
|
147
|
-
**Build the image:**
|
|
148
|
-
```bash
|
|
149
|
-
docker build -t memory-mcp:latest .
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
**Run the container:**
|
|
153
|
-
```bash
|
|
154
|
-
# Create data directory
|
|
155
|
-
mkdir -p ./data
|
|
156
|
-
|
|
157
|
-
# Run container with volume mount
|
|
158
|
-
docker run -d \
|
|
159
|
-
--name memory-mcp \
|
|
160
|
-
-v "$(pwd)/data:/data" \
|
|
161
|
-
-e MEMORY_DB_PATH=/data/memory.db \
|
|
162
|
-
-e DEFAULT_TTL_DAYS=90 \
|
|
163
|
-
memory-mcp:latest
|
|
164
|
-
```
|
|
165
|
-
|
|
166
|
-
**Interact with the running container:**
|
|
167
|
-
```bash
|
|
168
|
-
# View logs
|
|
169
|
-
docker logs -f memory-mcp
|
|
170
|
-
|
|
171
|
-
# Execute commands inside container
|
|
172
|
-
docker exec -it memory-mcp /bin/bash
|
|
173
|
-
|
|
174
|
-
# Stop container
|
|
175
|
-
docker stop memory-mcp
|
|
176
|
-
|
|
177
|
-
# Remove container
|
|
178
|
-
docker rm memory-mcp
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
### Volume Persistence
|
|
182
|
-
|
|
183
|
-
The database is stored in a Docker volume mapped to `./data/` on your host:
|
|
184
|
-
|
|
185
|
-
| Location | Path |
|
|
186
|
-
|----------|------|
|
|
187
|
-
| **Host** | `./data/memory.db` |
|
|
188
|
-
| **Container** | `/data/memory.db` |
|
|
189
|
-
|
|
190
|
-
**To backup your database:**
|
|
191
|
-
```bash
|
|
192
|
-
cp ./data/memory.db ./memory-backup-$(date +%Y%m%d).db
|
|
193
|
-
```
|
|
21
|
+
- Detect your OS (macOS/Windows/Linux)
|
|
22
|
+
- Configure Claude Desktop with the memory server
|
|
23
|
+
- Create backup of existing config
|
|
24
|
+
- Set up platform-appropriate database location
|
|
194
25
|
|
|
195
|
-
|
|
196
|
-
```bash
|
|
197
|
-
cp ./memory-backup-20250105.db ./data/memory.db
|
|
198
|
-
docker-compose restart
|
|
199
|
-
```
|
|
200
|
-
|
|
201
|
-
### Environment Variables (Docker)
|
|
202
|
-
|
|
203
|
-
Configure via `docker-compose.yml` or `-e` flags:
|
|
204
|
-
|
|
205
|
-
| Variable | Default | Description |
|
|
206
|
-
|----------|---------|-------------|
|
|
207
|
-
| `MEMORY_DB_PATH` | `/data/memory.db` | Database file location inside container |
|
|
208
|
-
| `DEFAULT_TTL_DAYS` | `90` | Default memory expiration (days) |
|
|
209
|
-
| `MEMORY_DB_DRIVER` | `better-sqlite3` | Database driver (better-sqlite3 or sqljs) |
|
|
210
|
-
| `NODE_ENV` | `production` | Node environment |
|
|
26
|
+
After installation, restart Claude Desktop completely.
|
|
211
27
|
|
|
212
|
-
|
|
28
|
+
## Database Location
|
|
213
29
|
|
|
214
|
-
|
|
215
|
-
- **Native Dependencies**: Uses multi-stage build to compile better-sqlite3 native bindings
|
|
216
|
-
- **Resource Limits**: Default docker-compose.yml sets 512MB memory limit (adjustable)
|
|
217
|
-
- **Auto-restart**: Container restarts automatically unless explicitly stopped
|
|
30
|
+
Memories are stored locally:
|
|
218
31
|
|
|
219
|
-
|
|
32
|
+
- **macOS**: `~/.claude-memories/memory.db`
|
|
33
|
+
- **Windows**: `%APPDATA%/claude-memories/memory.db`
|
|
34
|
+
- **Linux**: `~/.local/share/claude-memories/memory.db`
|
|
220
35
|
|
|
221
|
-
|
|
36
|
+
The database is a single portable SQLite file. Back it up by copying the file.
|
|
222
37
|
|
|
223
|
-
|
|
224
|
-
- **For production**: Consider using a container orchestration platform (Kubernetes, ECS, etc.)
|
|
38
|
+
## Tools
|
|
225
39
|
|
|
226
|
-
|
|
40
|
+
| Tool | Description |
|
|
41
|
+
|------|-------------|
|
|
42
|
+
| `memory_store` | Store a memory with auto-summarization and entity extraction |
|
|
43
|
+
| `memory_recall` | Search memories with token-aware loading |
|
|
44
|
+
| `memory_forget` | Soft-delete a memory (preserves audit trail) |
|
|
227
45
|
|
|
228
|
-
|
|
46
|
+
## Features
|
|
229
47
|
|
|
230
|
-
|
|
48
|
+
- FTS5 full-text search (fast, no embeddings needed)
|
|
49
|
+
- Token budgeting for context-aware responses
|
|
50
|
+
- Automatic entity extraction and summarization
|
|
51
|
+
- Soft deletes with provenance tracking
|
|
52
|
+
- Hybrid relevance scoring (recency + importance + frequency)
|
|
231
53
|
|
|
232
|
-
|
|
54
|
+
## Manual Configuration
|
|
233
55
|
|
|
234
|
-
|
|
235
|
-
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
236
|
-
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
237
|
-
- Linux: `~/.config/Claude/claude_desktop_config.json`
|
|
56
|
+
If auto-setup doesn't work, add to your Claude Desktop config:
|
|
238
57
|
|
|
239
|
-
**
|
|
58
|
+
**Config locations:**
|
|
59
|
+
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
60
|
+
- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
|
|
61
|
+
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
|
|
240
62
|
|
|
241
|
-
|
|
63
|
+
Add this to your config (the installer does this automatically):
|
|
242
64
|
|
|
243
|
-
### Manual Configuration (macOS/Linux)
|
|
244
|
-
```json
|
|
245
|
-
{
|
|
246
|
-
"mcpServers": {
|
|
247
|
-
"memory": {
|
|
248
|
-
"command": "npx",
|
|
249
|
-
"args": ["-y", "@whenmoon-afk/memory-mcp"],
|
|
250
|
-
"env": {
|
|
251
|
-
"MEMORY_DB_PATH": "./memory.db"
|
|
252
|
-
}
|
|
253
|
-
}
|
|
254
|
-
}
|
|
255
|
-
}
|
|
256
|
-
```
|
|
257
|
-
|
|
258
|
-
### Manual Configuration (Windows)
|
|
259
|
-
|
|
260
|
-
**Windows requires the `cmd /c` wrapper** to execute npx properly:
|
|
261
|
-
|
|
262
|
-
```json
|
|
263
|
-
{
|
|
264
|
-
"mcpServers": {
|
|
265
|
-
"memory": {
|
|
266
|
-
"command": "cmd",
|
|
267
|
-
"args": ["/c", "npx", "-y", "@whenmoon-afk/memory-mcp"],
|
|
268
|
-
"env": {
|
|
269
|
-
"MEMORY_DB_PATH": "./memory.db"
|
|
270
|
-
}
|
|
271
|
-
}
|
|
272
|
-
}
|
|
273
|
-
}
|
|
274
|
-
```
|
|
275
|
-
|
|
276
|
-
### Using Global Install
|
|
277
|
-
```json
|
|
278
|
-
{
|
|
279
|
-
"mcpServers": {
|
|
280
|
-
"memory": {
|
|
281
|
-
"command": "memory-mcp",
|
|
282
|
-
"env": {
|
|
283
|
-
"MEMORY_DB_PATH": "./memory.db"
|
|
284
|
-
}
|
|
285
|
-
}
|
|
286
|
-
}
|
|
287
|
-
}
|
|
288
|
-
```
|
|
289
|
-
|
|
290
|
-
### From Source
|
|
291
65
|
```json
|
|
292
66
|
{
|
|
293
67
|
"mcpServers": {
|
|
294
68
|
"memory": {
|
|
295
69
|
"command": "node",
|
|
296
|
-
"args": ["/
|
|
70
|
+
"args": ["/path/to/node_modules/@whenmoon-afk/memory-mcp/dist/index.js"],
|
|
297
71
|
"env": {
|
|
298
|
-
"MEMORY_DB_PATH": "
|
|
72
|
+
"MEMORY_DB_PATH": "/path/to/.claude-memories/memory.db"
|
|
299
73
|
}
|
|
300
74
|
}
|
|
301
75
|
}
|
|
302
76
|
}
|
|
303
77
|
```
|
|
304
78
|
|
|
305
|
-
> Restart or reload MCP servers.
|
|
306
|
-
|
|
307
|
-
---
|
|
308
|
-
|
|
309
|
-
## MCP Tools
|
|
310
|
-
|
|
311
|
-
| Tool | Input | Description |
|
|
312
|
-
|------|-------|-----------|
|
|
313
|
-
| `memory_store` | `{ content, type, importance?, entities?, ttl_days?, provenance? }` | Store or update memory with auto-summary |
|
|
314
|
-
| `memory_recall` | `{ query, type?, entities?, limit?, max_tokens? }` | Search memories with token-aware loading |
|
|
315
|
-
| `memory_forget` | `{ id, reason? }` | Soft-delete memory (preserves provenance) |
|
|
316
|
-
|
|
317
|
-
---
|
|
318
|
-
|
|
319
|
-
### Store a Preference
|
|
320
|
-
|
|
321
|
-
```json
|
|
322
|
-
{
|
|
323
|
-
"tool": "memory_store",
|
|
324
|
-
"input": {
|
|
325
|
-
"content": "User works best in focused 90-minute blocks with 15-minute breaks.",
|
|
326
|
-
"type": "fact",
|
|
327
|
-
"importance": 8
|
|
328
|
-
}
|
|
329
|
-
}
|
|
330
|
-
```
|
|
331
|
-
|
|
332
|
-
→ Auto-creates:
|
|
333
|
-
- Summary: `"User follows 90/15 focused work cycles."`
|
|
334
|
-
- Entities: `focused work`, `90-minute blocks`
|
|
335
|
-
- Provenance: current session
|
|
336
|
-
|
|
337
|
-
---
|
|
338
|
-
|
|
339
|
-
### Smart Recall (Dual-Response)
|
|
340
|
-
|
|
341
|
-
```json
|
|
342
|
-
{
|
|
343
|
-
"tool": "memory_recall",
|
|
344
|
-
"input": {
|
|
345
|
-
"query": "work habits",
|
|
346
|
-
"max_tokens": 1200
|
|
347
|
-
}
|
|
348
|
-
}
|
|
349
|
-
```
|
|
350
|
-
|
|
351
|
-
**Response**:
|
|
352
|
-
```json
|
|
353
|
-
{
|
|
354
|
-
"index": [
|
|
355
|
-
{ "id": "mem_8b1", "summary": "User follows 90/15 focused work cycles.", "score": 96 },
|
|
356
|
-
{ "id": "mem_2c9", "summary": "User avoids meetings before 10 AM.", "score": 88 }
|
|
357
|
-
],
|
|
358
|
-
"details": [
|
|
359
|
-
{
|
|
360
|
-
"id": "mem_8b1",
|
|
361
|
-
"content": "User works best in focused 90-minute blocks with 15-minute breaks.",
|
|
362
|
-
"entities": ["focused work", "90-minute blocks"],
|
|
363
|
-
"provenance": { "source": "chat_2025-11-03", "created_at": "2025-11-03T14:10Z" }
|
|
364
|
-
}
|
|
365
|
-
],
|
|
366
|
-
"meta": {
|
|
367
|
-
"tokens_used": 698,
|
|
368
|
-
"total_matches": 2,
|
|
369
|
-
"truncated": false
|
|
370
|
-
}
|
|
371
|
-
}
|
|
372
|
-
```
|
|
373
|
-
|
|
374
|
-
Your AI **knows what it knows** — and can ask for more.
|
|
375
|
-
|
|
376
|
-
---
|
|
377
|
-
|
|
378
|
-
### Forget a Memory
|
|
379
|
-
|
|
380
|
-
```json
|
|
381
|
-
{
|
|
382
|
-
"tool": "memory_forget",
|
|
383
|
-
"input": {
|
|
384
|
-
"id": "mem_8b1",
|
|
385
|
-
"reason": "Information no longer relevant"
|
|
386
|
-
}
|
|
387
|
-
}
|
|
388
|
-
```
|
|
389
|
-
|
|
390
|
-
**Response**:
|
|
391
|
-
```json
|
|
392
|
-
{
|
|
393
|
-
"success": true,
|
|
394
|
-
"memory_id": "mem_8b1",
|
|
395
|
-
"message": "Memory soft-deleted successfully. Reason: Information no longer relevant"
|
|
396
|
-
}
|
|
397
|
-
```
|
|
398
|
-
|
|
399
|
-
> Soft-deleted memories are **preserved** in the database with full provenance trail. They won't appear in searches but remain recoverable.
|
|
400
|
-
|
|
401
|
-
---
|
|
402
|
-
|
|
403
|
-
## Dual-Response Pattern
|
|
404
|
-
|
|
405
|
-
```
|
|
406
|
-
[index] → All matching summaries (~20 tokens each)
|
|
407
|
-
[details] → Full content of top memories (budget-capped)
|
|
408
|
-
[meta] → tokens_used, total_matches, truncated
|
|
409
|
-
```
|
|
410
|
-
|
|
411
|
-
- **Index**: Always included → *discovery*
|
|
412
|
-
- **Details**: Budget-safe → *precision*
|
|
413
|
-
- **Follow-up**: Use `ids: [...]` to expand
|
|
414
|
-
|
|
415
|
-
---
|
|
416
|
-
|
|
417
|
-
## Database & Portability
|
|
418
|
-
|
|
419
|
-
- **File**: `memory.db` (SQLite) — path via `MEMORY_DB_PATH`
|
|
420
|
-
- **Portable**: Copy to USB, cloud sync, or new machine
|
|
421
|
-
- **Backup**: Just copy the file
|
|
422
|
-
- **Tip**: For extra security, store `memory.db` on a **VeraCrypt Encrypted USB drive** (adds friction, but maximum control).
|
|
423
|
-
|
|
424
|
-
---
|
|
425
|
-
|
|
426
|
-
## Dependencies
|
|
427
|
-
|
|
428
|
-
This project uses minimal runtime dependencies to keep the package lightweight:
|
|
429
|
-
|
|
430
|
-
| Dependency | Version | Purpose |
|
|
431
|
-
|-----------|---------|---------|
|
|
432
|
-
| `@modelcontextprotocol/sdk` | ^1.0.4 | Official MCP protocol implementation |
|
|
433
|
-
| `better-sqlite3` | ^11.0.0 | Fast, native SQLite3 bindings with FTS5 support |
|
|
434
|
-
|
|
435
|
-
**Why these dependencies?**
|
|
436
|
-
- **MCP SDK**: Required for implementing the Model Context Protocol standard
|
|
437
|
-
- **better-sqlite3**: Native performance for full-text search and database operations, essential for memory recall speed
|
|
438
|
-
|
|
439
|
-
All other dependencies are dev-only (TypeScript, testing, linting).
|
|
440
|
-
|
|
441
|
-
---
|
|
442
|
-
|
|
443
79
|
## Environment Variables
|
|
444
80
|
|
|
445
81
|
| Variable | Default | Description |
|
|
446
82
|
|----------|---------|-------------|
|
|
447
|
-
| `MEMORY_DB_PATH` | Platform-specific
|
|
448
|
-
| `
|
|
449
|
-
| `DEFAULT_TTL_DAYS` | `90` | Default time-to-live for memories (days) |
|
|
83
|
+
| `MEMORY_DB_PATH` | Platform-specific | Database file location |
|
|
84
|
+
| `DEFAULT_TTL_DAYS` | `90` | Default memory expiration |
|
|
450
85
|
|
|
451
|
-
|
|
452
|
-
- **macOS:** `~/.claude-memories/memory.db`
|
|
453
|
-
- **Windows:** `%APPDATA%\claude-memories\memory.db`
|
|
454
|
-
- **Linux:** `~/.local/share/claude-memories/memory.db`
|
|
86
|
+
## Troubleshooting
|
|
455
87
|
|
|
456
|
-
|
|
88
|
+
**Tools not appearing in Claude Desktop?**
|
|
457
89
|
|
|
458
|
-
|
|
90
|
+
1. Restart Claude Desktop completely (quit and reopen)
|
|
91
|
+
2. Verify config file syntax is valid JSON
|
|
92
|
+
3. Check that Node.js 18+ is installed: `node --version`
|
|
93
|
+
4. Re-run installer: `npx @whenmoon-afk/memory-mcp`
|
|
459
94
|
|
|
460
|
-
|
|
461
|
-
Data is stored in a plain SQLite file (`memory.db`).
|
|
462
|
-
For sensitive data, use OS-level encryption (FileVault, BitLocker).
|
|
463
|
-
|
|
464
|
-
---
|
|
465
|
-
|
|
466
|
-
## Best Practices
|
|
467
|
-
|
|
468
|
-
1. **Start with `max_tokens: 1000`** — adjust per model and task.
|
|
469
|
-
2. **Filter by `type`** to reduce noise and improve relevance.
|
|
470
|
-
3. **Use entity filtering** to narrow searches to specific topics.
|
|
471
|
-
4. **Reference provenance**: Track source and context for audit trails.
|
|
472
|
-
5. **Backup `memory.db`** regularly — it's just a file!
|
|
473
|
-
|
|
474
|
-
---
|
|
475
|
-
|
|
476
|
-
## Quick Links
|
|
477
|
-
|
|
478
|
-
- 📦 **NPM Package**: https://www.npmjs.com/package/@whenmoon-afk/memory-mcp
|
|
479
|
-
- 🐙 **GitHub Repository**: https://github.com/WhenMoon-afk/claude-memory-mcp
|
|
480
|
-
- 🐛 **Report Issues**: https://github.com/WhenMoon-afk/claude-memory-mcp/issues
|
|
481
|
-
- 📖 **MCP Documentation**: https://modelcontextprotocol.io
|
|
482
|
-
|
|
483
|
-
---
|
|
95
|
+
## Dependencies
|
|
484
96
|
|
|
485
|
-
|
|
97
|
+
- `@modelcontextprotocol/sdk` - MCP protocol implementation
|
|
98
|
+
- `better-sqlite3` - Fast native SQLite with FTS5
|
|
486
99
|
|
|
487
|
-
|
|
488
|
-
- Report bugs or request features via [GitHub Issues](https://github.com/WhenMoon-afk/claude-memory-mcp/issues)
|
|
489
|
-
- Submit pull requests for improvements
|
|
490
|
-
- Share your use cases and feedback
|
|
100
|
+
## Links
|
|
491
101
|
|
|
492
|
-
|
|
102
|
+
- **npm**: https://www.npmjs.com/package/@whenmoon-afk/memory-mcp
|
|
103
|
+
- **GitHub**: https://github.com/WhenMoon-afk/claude-memory-mcp
|
|
104
|
+
- **Issues**: https://github.com/WhenMoon-afk/claude-memory-mcp/issues
|
|
493
105
|
|
|
494
106
|
## License
|
|
495
107
|
|
|
496
|
-
MIT
|
|
497
|
-
|
|
498
|
-
**Copyright (c) 2025 WhenMoon-afk**
|
|
499
|
-
|
|
500
|
-
---
|
|
501
|
-
|
|
502
|
-
**Built with ❤️ for the MCP community**
|
|
108
|
+
MIT
|
package/dist/index.js
CHANGED
|
@@ -3,6 +3,9 @@
|
|
|
3
3
|
* Memory MCP v2.0 - Smart monolith MCP server
|
|
4
4
|
* Brain-inspired memory system with smart context loading
|
|
5
5
|
*/
|
|
6
|
+
import { homedir, platform } from 'os';
|
|
7
|
+
import { join, dirname } from 'path';
|
|
8
|
+
import { existsSync, mkdirSync } from 'fs';
|
|
6
9
|
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
|
|
7
10
|
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
8
11
|
import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
|
|
@@ -10,11 +13,38 @@ import { getDatabase, closeDatabase } from './database/connection.js';
|
|
|
10
13
|
import { memoryStore } from './tools/memory-store.js';
|
|
11
14
|
import { memoryRecall } from './tools/memory-recall.js';
|
|
12
15
|
import { memoryForget } from './tools/memory-forget.js';
|
|
16
|
+
/**
|
|
17
|
+
* Get platform-specific default database path
|
|
18
|
+
* Ensures consistent location across Claude Desktop, Claude Code, and other clients
|
|
19
|
+
*/
|
|
20
|
+
function getDefaultDbPath() {
|
|
21
|
+
const plat = platform();
|
|
22
|
+
let dbPath;
|
|
23
|
+
if (plat === 'darwin') {
|
|
24
|
+
// macOS: ~/.claude-memories/memory.db
|
|
25
|
+
dbPath = join(homedir(), '.claude-memories', 'memory.db');
|
|
26
|
+
}
|
|
27
|
+
else if (plat === 'win32') {
|
|
28
|
+
// Windows: %APPDATA%/claude-memories/memory.db
|
|
29
|
+
dbPath = join(process.env['APPDATA'] || join(homedir(), 'AppData', 'Roaming'), 'claude-memories', 'memory.db');
|
|
30
|
+
}
|
|
31
|
+
else {
|
|
32
|
+
// Linux/other: XDG compliant ~/.local/share/claude-memories/memory.db
|
|
33
|
+
const xdgData = process.env['XDG_DATA_HOME'] || join(homedir(), '.local', 'share');
|
|
34
|
+
dbPath = join(xdgData, 'claude-memories', 'memory.db');
|
|
35
|
+
}
|
|
36
|
+
// Ensure directory exists
|
|
37
|
+
const dbDir = dirname(dbPath);
|
|
38
|
+
if (!existsSync(dbDir)) {
|
|
39
|
+
mkdirSync(dbDir, { recursive: true });
|
|
40
|
+
}
|
|
41
|
+
return dbPath;
|
|
42
|
+
}
|
|
13
43
|
/**
|
|
14
44
|
* Configuration from environment or defaults
|
|
15
45
|
*/
|
|
16
46
|
const config = {
|
|
17
|
-
databasePath: process.env['MEMORY_DB_PATH'] ||
|
|
47
|
+
databasePath: process.env['MEMORY_DB_PATH'] || getDefaultDbPath(),
|
|
18
48
|
defaultTTLDays: parseInt(process.env['DEFAULT_TTL_DAYS'] || '90'),
|
|
19
49
|
databaseDriver: process.env['MEMORY_DB_DRIVER'] || 'better-sqlite3',
|
|
20
50
|
};
|
|
@@ -23,7 +53,7 @@ const config = {
|
|
|
23
53
|
*/
|
|
24
54
|
const server = new Server({
|
|
25
55
|
name: '@whenmoon-afk/memory-mcp',
|
|
26
|
-
version: '2.
|
|
56
|
+
version: '2.3.0',
|
|
27
57
|
}, {
|
|
28
58
|
capabilities: {
|
|
29
59
|
tools: {},
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,SAAS,EACT,QAAQ,GACT,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAGxD;;GAEG;AACH,MAAM,MAAM,GAAG;IACb,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
package/install.js
CHANGED
|
File without changes
|
package/package.json
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@whenmoon-afk/memory-mcp",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.3.0",
|
|
4
4
|
"description": "Brain-inspired memory for AI agents - MCP server",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
7
7
|
"bin": {
|
|
8
|
-
"memory-mcp": "
|
|
8
|
+
"memory-mcp": "install.js"
|
|
9
9
|
},
|
|
10
10
|
"files": [
|
|
11
11
|
"dist/",
|