线程安全内存服务器

基于SQLite的高性能线程安全并发内存服务器,专为Claude AI、LLMs和多智能体系统设计,提供ACID事务支持和WAL模式。

  • by Daichi-Kudo
  • JavaScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 Daichi-Kudo/mcp-memory-sqlite

使用说明

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秒超时后保持写锁。

解决:

  1. 检查孤立进程
  2. 确保 MEMORY_DB_PATH 指向本地文件系统(不是网络驱动器)
  3. 如果需要,增加超时时间(联系维护人员进行自定义构建)

“找不到模块”错误

解决方案: 使用 npx 而不是直接路径:

{
  "command": "npx",
  "args": ["@pepk/mcp-memory-sqlite"]
}

多个克劳德桌面窗口冲突

解决方案: 每个窗口都可以安全地使用相同的数据库——WAL模式会自动处理并发性。

安全

数据库文件权限

SQLite数据库包含所有内存数据。设置限制权限:

chmod 600 ~/.claude/memory.db
chmod 700 ~/.claude

敏感数据警告

此包不加密静态数据。请勿存储:

  • API密钥或令牌
  • 密码
  • 需要加密的个人身份信息(PII)

从服务器内存迁移

此程序包与API兼容 @modelcontextprotocol/server-memory.简单地说:

  1. 安装此软件包
  2. 更新MCP配置以使用 @pepk/mcp-memory-sqlite
  3. 集 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有限责任公司