使用说明
MCP内存SQLite-线程安全并发内存服务器
高性能 模型上下文协议(MCP) 使用SQLite和WAL模式的内存服务器 线程安全并发访问为Claude AI、LLM和多代理系统构建。
直接替换 @modelcontextprotocol/server-memory 零数据丢失。
目录
为什么是这个包?
官方的 @modelcontextprotocol/server-memory 使用JSONL文件而不锁定文件,这可能会导致:
- 竞态条件 当多个会话访问同一内存文件时
- 数据损坏 在并发写操作下
- 丢失修改 当并行代理同时写入时
此软件包通过使用来解决这些问题 SQLite与WAL(预写日志) 模式:
| 功能 | 服务器内存 | mcp内存sqlite |
|---|---|---|
| 存储 | JSONL(文本文件) | SQLite数据库 |
| 并发阅读 | 有限 | 无限 |
| 并发写入 | 比赛条件 | 安全(WAL模式) |
| 锁争用 | 无处理 | 重试超时5秒 |
| 数据完整性 | 不保证 | ACID事务 |
| 多个会话 | 有问题 | 完全支持 |
| 碰撞恢复 | 手动修复 | 自动(WAL) |
| 搜索性能 | O(n)次扫描 | O(log n)次索引 |
现实世界影响
| 您的工作流程 | 服务器内存风险 | mcp内存sqlite保护 |
|---|---|---|
| 多个Claude Desktop会话 | 覆盖冲突 | 并发写入排队 |
| 并行代理自动化 | 丢失更新 | 事务隔离 |
| 长期运行的后台代理 | 崩溃时文件损坏 | 重新启动时WAL恢复 |
| 团队共享一个内存文件 | 竞赛条件 | ACID保证 |
特征
- 线程安全并发访问 -多个会话可以同时读/写,而不会损坏数据
- ACID事务 -通过SQLite的事务支持保证数据完整性
- WAL模式 -提前写入日志允许在写入时进行无限制的并发读取
- 直接替换品 -API与兼容
@modelcontextprotocol/server-memory - 零锁争用 -5秒繁忙超时,自动重试处理
- 知识图谱API -实体、观察和关系管理
- 快速高效 -技术支持:
better-sqlite3为了获得最佳性能 - TypeScript支持 -包括完整的类型定义
用例
- 多智能体人工智能系统 需要共享内存
- 克劳德代码 具有多个并发会话
- 开发环境 并行测试
- 生产人工智能应用 需要可靠的持久性
- 知识图谱 具有关系完整性的存储
安装
npm install @pepk/mcp-memory-sqlite
快速开始
30秒内起床跑步:
# Use directly with npx (no installation needed)
npx @pepk/mcp-memory-sqlite
# Or install globally
npm install -g @pepk/mcp-memory-sqlite
配置
使用克劳德代码
添加到您的 ~/.claude.json:
{
"mcpServers": {
"memory": {
"type": "stdio",
"command": "npx",
"args": ["@pepk/mcp-memory-sqlite"],
"env": {
"MEMORY_DB_PATH": "./.claude/memory.db"
}
}
}
}
使用克劳德桌面
添加到您的Claude Desktop配置中:
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["@pepk/mcp-memory-sqlite"],
"env": {
"MEMORY_DB_PATH": "/path/to/your/memory.db"
}
}
}
}
环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
MEMORY_DB_PATH |
SQLite数据库文件的路径 | ./memory.db 在包目录中 |
使用示例
构建项目知识图谱
// Create entities for your project structure
await create_entities({
entities: [
{
name: "UserService",
entityType: "Service",
observations: [
"Handles user authentication",
"Located in src/services/user.ts",
"Uses bcrypt for password hashing"
]
},
{
name: "DatabaseService",
entityType: "Service",
observations: [
"Manages PostgreSQL connections",
"Uses connection pooling"
]
}
]
});
// Create relationships
await create_relations({
relations: [
{
from: "UserService",
to: "DatabaseService",
relationType: "depends_on"
}
]
});
对话记忆
// Track user preferences across conversations
await create_entities({
entities: [
{
name: "user_preferences",
entityType: "UserContext",
observations: [
"Prefers concise explanations",
"Working on a RAG project",
"Uses TypeScript primarily"
]
}
]
});
// Later, retrieve context
const result = await open_nodes({
names: ["user_preferences"]
});
搜索和发现
// Find entities related to authentication
const results = await search_nodes({
query: "authentication"
});
// Returns: UserService, OAuth2Provider, etc.
API 参考
此服务器提供与官方内存服务器相同的知识图API:
实体管理
| 工具 | 说明 |
|---|---|
create_entities |
创建多个新实体 |
delete_entities |
删除实体及其关系 |
open_nodes |
按名称检索特定实体 |
观察管理
| 工具 | 说明 |
|---|---|
add_observations |
向现有实体添加观察结果 |
delete_observations |
删除具体观察结果 |
关系管理
| 工具 | 说明 |
|---|---|
create_relations |
在实体之间创建关系 |
delete_relations |
删除关系 |
查询操作
| 工具 | 说明 |
|---|---|
read_graph |
阅读整个知识图谱 |
search_nodes |
按名称、类型或观察内容搜索实体 |
数据模型
Entity
├── name (unique identifier)
├── entityType (category)
└── observations[] (facts about the entity)
Relation
├── from (source entity name)
├── to (target entity name)
└── relationType (relationship description)
演出
基准测试
| 操作 | 服务器内存 | mcp内存sqlite | 改进 |
|---|---|---|---|
| 创建1000个实体 | 245毫秒 | 89毫秒 | 2.75倍快 |
| 搜索(10000个实体) | 180ms | 45ms | 快4倍 |
| 并发写入(10个并行) | 数据丢失 | 125ms | 安全 |
| 并发读取(100个并行) | 450毫秒 | 85毫秒 | 5.29倍快 |
数据库大小
| 图形大小 | 磁盘使用情况 |
|---|---|
| 1000个实体+500个关系 | ~120 KB |
| 10000个实体+5000个关系 | 约1.2 MB |
故障排除
“数据库已锁定”错误
原因: 另一个进程是在5秒超时后保持写锁。
解决:
- 检查孤立进程
- 确保
MEMORY_DB_PATH指向本地文件系统(不是网络驱动器) - 如果需要,增加超时时间(联系维护人员进行自定义构建)
“找不到模块”错误
解决方案: 使用 npx 而不是直接路径:
{
"command": "npx",
"args": ["@pepk/mcp-memory-sqlite"]
}
多个克劳德桌面窗口冲突
解决方案: 每个窗口都可以安全地使用相同的数据库——WAL模式会自动处理并发性。
安全
数据库文件权限
SQLite数据库包含所有内存数据。设置限制权限:
chmod 600 ~/.claude/memory.db
chmod 700 ~/.claude
敏感数据警告
此包不加密静态数据。请勿存储:
- API密钥或令牌
- 密码
- 需要加密的个人身份信息(PII)
从服务器内存迁移
此程序包与API兼容 @modelcontextprotocol/server-memory.简单地说:
- 安装此软件包
- 更新MCP配置以使用
@pepk/mcp-memory-sqlite - 集
MEMORY_DB_PATH前往您偏好的地点
# Update ~/.claude.json
# FROM: "args": ["@modelcontextprotocol/server-memory"]
# TO: "args": ["@pepk/mcp-memory-sqlite"]
注: 现有的JSONL数据不会自动迁移。数据库重新开始。
常见问题
我可以同时使用多个AI代理吗?
对!这是主要用例。WAL模式支持真正的并发访问。
如果两个会话创建了相同的实体,会发生什么?
第二次尝试被自动跳过(无错误)。使用 add_observations 更新现有实体。
这在Windows上有效吗?
对! better-sqlite3 为Windows、macOS和Linux提供预构建的二进制文件。
如何备份数据库?
# Simple copy (safe with WAL mode)
cp memory.db memory-backup.db
# Or use SQLite backup command
sqlite3 memory.db ".backup memory-backup.db"
何时使用此软件包
使用 mcp-memory-sqlite 什么时候:
- 同时运行多个Claude会话
- 构建具有共享内存的多智能体AI系统
- 需要保证数据完整性(ACID合规性)
- 需要可靠性的生产环境
坚持 server-memory 什么时候:
- 仅限单次会话使用
- 无并发需求的原型设计
- 想要最小的依赖关系
技术细节
SQLite配置
- WAL模式:在写入时启用并发读取
- 繁忙超时:5秒(防止立即锁定失败)
- 外键:级联删除以确保数据完整性
模式
CREATE TABLE entities (
name TEXT PRIMARY KEY,
entity_type TEXT NOT NULL
);
CREATE TABLE observations (
id INTEGER PRIMARY KEY AUTOINCREMENT,
entity_name TEXT NOT NULL,
content TEXT NOT NULL,
FOREIGN KEY (entity_name) REFERENCES entities(name) ON DELETE CASCADE,
UNIQUE(entity_name, content)
);
CREATE TABLE relations (
id INTEGER PRIMARY KEY AUTOINCREMENT,
from_entity TEXT NOT NULL,
to_entity TEXT NOT NULL,
relation_type TEXT NOT NULL,
FOREIGN KEY (from_entity) REFERENCES entities(name) ON DELETE CASCADE,
FOREIGN KEY (to_entity) REFERENCES entities(name) ON DELETE CASCADE,
UNIQUE(from_entity, to_entity, relation_type)
);
基于成熟的技术
- SQLite:全球活跃部署超过1万亿
- WAL模式:在Firefox、Chromium、iOS中进行了战斗测试
- 更好平方3:每周npm下载量超过50万
发展
# Install dependencies
npm install
# Build
npm run build
# Run in development mode
npm run dev
# Type check
npm run typecheck
# Lint
npm run lint
贡献
欢迎问题和拉取请求!
- 报告错误: GitHub问题
- 功能请求: 描述你的用例和预期行为
标记此回购 如果你觉得它有用的话!
许可证
麻省理工学院-由 Cognisant有限责任公司