Skip to content

Commit fff8bed

Browse files
daichi-pepkdaichi-pepk
committed
Initial release: SQLite-based MCP memory server
- SQLite with WAL mode for concurrent access - Drop-in replacement for @modelcontextprotocol/server-memory - ACID transactions for data integrity - 5-second busy timeout for lock contention - Knowledge Graph API (entities, relations, observations)
0 parents  commit fff8bed

8 files changed

Lines changed: 875 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Dependencies
2+
node_modules/
3+
4+
# Build output
5+
dist/
6+
7+
# IDE
8+
.idea/
9+
.vscode/
10+
*.swp
11+
*.swo
12+
13+
# OS
14+
.DS_Store
15+
Thumbs.db
16+
17+
# Database files (for testing)
18+
*.db
19+
*.db-wal
20+
*.db-shm
21+
22+
# Logs
23+
*.log
24+
npm-debug.log*
25+
26+
# Environment
27+
.env
28+
.env.local
29+
30+
# Package manager
31+
package-lock.json
32+
yarn.lock
33+
pnpm-lock.yaml

‎.npmignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Source files
2+
src/
3+
4+
# TypeScript config
5+
tsconfig.json
6+
7+
# Development files
8+
*.db
9+
*.db-wal
10+
*.db-shm
11+
.gitignore
12+
.git/
13+
14+
# IDE
15+
.idea/
16+
.vscode/
17+
18+
# OS
19+
.DS_Store
20+
Thumbs.db

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Daichi Kudo
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.

‎README.md‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
# MCP Memory SQLite
2+
3+
A high-performance [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) memory server using SQLite with WAL mode for concurrent access.
4+
5+
**Drop-in replacement for `@modelcontextprotocol/server-memory` with better concurrency support.**
6+
7+
## Why This Package?
8+
9+
The official `@modelcontextprotocol/server-memory` uses JSONL files without file locking, which can lead to:
10+
11+
- **Race conditions** when multiple sessions access the same memory file
12+
- **Data corruption** under concurrent write operations
13+
- **Lost updates** when parallel agents write simultaneously
14+
15+
This package solves these issues by using **SQLite with WAL (Write-Ahead Logging)** mode:
16+
17+
| Feature | server-memory | mcp-memory-sqlite |
18+
|---------|---------------|-------------------|
19+
| Storage | JSONL (text file) | SQLite database |
20+
| Concurrent reads | Limited | Unlimited |
21+
| Concurrent writes | Race conditions | Safe (WAL mode) |
22+
| Lock contention | No handling | 5s timeout with retry |
23+
| Data integrity | No guarantees | ACID transactions |
24+
| Multiple sessions | Problematic | Fully supported |
25+
26+
## Installation
27+
28+
```bash
29+
npm install @daichi-kudo/mcp-memory-sqlite
30+
```
31+
32+
## Usage
33+
34+
### With Claude Code
35+
36+
Add to your `~/.claude.json`:
37+
38+
```json
39+
{
40+
"mcpServers": {
41+
"memory": {
42+
"type": "stdio",
43+
"command": "npx",
44+
"args": ["@daichi-kudo/mcp-memory-sqlite"],
45+
"env": {
46+
"MEMORY_DB_PATH": "./.claude/memory.db"
47+
}
48+
}
49+
}
50+
}
51+
```
52+
53+
### With Claude Desktop
54+
55+
Add to your Claude Desktop configuration:
56+
57+
```json
58+
{
59+
"mcpServers": {
60+
"memory": {
61+
"command": "npx",
62+
"args": ["@daichi-kudo/mcp-memory-sqlite"],
63+
"env": {
64+
"MEMORY_DB_PATH": "/path/to/your/memory.db"
65+
}
66+
}
67+
}
68+
}
69+
```
70+
71+
### Environment Variables
72+
73+
| Variable | Description | Default |
74+
|----------|-------------|---------|
75+
| `MEMORY_DB_PATH` | Path to SQLite database file | `./memory.db` in package directory |
76+
77+
## Available Tools
78+
79+
This server provides the same Knowledge Graph API as the official memory server:
80+
81+
### Entity Management
82+
83+
- **`create_entities`** - Create multiple new entities
84+
- **`delete_entities`** - Delete entities and their relations
85+
- **`open_nodes`** - Retrieve specific entities by name
86+
87+
### Observation Management
88+
89+
- **`add_observations`** - Add observations to existing entities
90+
- **`delete_observations`** - Remove specific observations
91+
92+
### Relation Management
93+
94+
- **`create_relations`** - Create relations between entities
95+
- **`delete_relations`** - Remove relations
96+
97+
### Query Operations
98+
99+
- **`read_graph`** - Read the entire knowledge graph
100+
- **`search_nodes`** - Search entities by name, type, or observation content
101+
102+
## Data Model
103+
104+
```
105+
Entity
106+
├── name (unique identifier)
107+
├── entityType (category)
108+
└── observations[] (facts about the entity)
109+
110+
Relation
111+
├── from (source entity name)
112+
├── to (target entity name)
113+
└── relationType (relationship description)
114+
```
115+
116+
### Example
117+
118+
```typescript
119+
// Create entities
120+
await create_entities({
121+
entities: [
122+
{
123+
name: "TypeScript",
124+
entityType: "Language",
125+
observations: [
126+
"Superset of JavaScript",
127+
"Adds static typing"
128+
]
129+
}
130+
]
131+
});
132+
133+
// Create relations
134+
await create_relations({
135+
relations: [
136+
{
137+
from: "TypeScript",
138+
to: "JavaScript",
139+
relationType: "compiles_to"
140+
}
141+
]
142+
});
143+
144+
// Search
145+
await search_nodes({ query: "typing" });
146+
```
147+
148+
## Technical Details
149+
150+
### SQLite Configuration
151+
152+
- **WAL Mode**: Enables concurrent reads while writing
153+
- **Busy Timeout**: 5 seconds (prevents immediate lock failures)
154+
- **Foreign Keys**: Cascade deletes for data integrity
155+
156+
### Schema
157+
158+
```sql
159+
CREATE TABLE entities (
160+
name TEXT PRIMARY KEY,
161+
entity_type TEXT NOT NULL
162+
);
163+
164+
CREATE TABLE observations (
165+
id INTEGER PRIMARY KEY AUTOINCREMENT,
166+
entity_name TEXT NOT NULL,
167+
content TEXT NOT NULL,
168+
FOREIGN KEY (entity_name) REFERENCES entities(name) ON DELETE CASCADE,
169+
UNIQUE(entity_name, content)
170+
);
171+
172+
CREATE TABLE relations (
173+
id INTEGER PRIMARY KEY AUTOINCREMENT,
174+
from_entity TEXT NOT NULL,
175+
to_entity TEXT NOT NULL,
176+
relation_type TEXT NOT NULL,
177+
FOREIGN KEY (from_entity) REFERENCES entities(name) ON DELETE CASCADE,
178+
FOREIGN KEY (to_entity) REFERENCES entities(name) ON DELETE CASCADE,
179+
UNIQUE(from_entity, to_entity, relation_type)
180+
);
181+
```
182+
183+
## Migration from server-memory
184+
185+
This package is API-compatible with `@modelcontextprotocol/server-memory`. Simply:
186+
187+
1. Install this package
188+
2. Update your MCP configuration to use `@daichi-kudo/mcp-memory-sqlite`
189+
3. Set `MEMORY_DB_PATH` to your preferred location
190+
191+
Note: This package uses SQLite instead of JSONL, so existing JSONL data won't be automatically migrated.
192+
193+
## Development
194+
195+
```bash
196+
# Install dependencies
197+
npm install
198+
199+
# Build
200+
npm run build
201+
202+
# Run in development mode
203+
npm run dev
204+
```
205+
206+
## License
207+
208+
MIT
209+
210+
## Contributing
211+
212+
Issues and pull requests are welcome at [GitHub](https://github.com/Daichi-Kudo/mcp-memory-sqlite).

‎package.json‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
{
2+
"name": "@daichi-kudo/mcp-memory-sqlite",
3+
"version": "1.0.0",
4+
"description": "A high-performance MCP memory server using SQLite with WAL mode for concurrent access. Drop-in replacement for @modelcontextprotocol/server-memory with better concurrency support.",
5+
"type": "module",
6+
"main": "dist/index.js",
7+
"types": "dist/index.d.ts",
8+
"bin": {
9+
"mcp-memory-sqlite": "dist/index.js"
10+
},
11+
"files": [
12+
"dist",
13+
"README.md",
14+
"LICENSE"
15+
],
16+
"scripts": {
17+
"build": "tsc",
18+
"start": "node dist/index.js",
19+
"dev": "tsx src/index.ts",
20+
"prepublishOnly": "npm run build"
21+
},
22+
"keywords": [
23+
"mcp",
24+
"model-context-protocol",
25+
"memory",
26+
"sqlite",
27+
"knowledge-graph",
28+
"claude",
29+
"anthropic",
30+
"ai-agent",
31+
"concurrent",
32+
"wal"
33+
],
34+
"author": "Daichi Kudo",
35+
"license": "MIT",
36+
"repository": {
37+
"type": "git",
38+
"url": "git+https://github.com/Daichi-Kudo/mcp-memory-sqlite.git"
39+
},
40+
"homepage": "https://github.com/Daichi-Kudo/mcp-memory-sqlite#readme",
41+
"bugs": {
42+
"url": "https://github.com/Daichi-Kudo/mcp-memory-sqlite/issues"
43+
},
44+
"dependencies": {
45+
"@modelcontextprotocol/sdk": "^1.0.0",
46+
"better-sqlite3": "^11.0.0",
47+
"zod": "^3.23.8"
48+
},
49+
"devDependencies": {
50+
"@types/better-sqlite3": "^7.6.11",
51+
"@types/node": "^22.0.0",
52+
"tsx": "^4.19.0",
53+
"typescript": "^5.6.0"
54+
},
55+
"engines": {
56+
"node": ">=20"
57+
}
58+
}

0 commit comments

Comments
 (0)