shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

mcp-sqlew

sqlew是一个MCP服务器，为AI代理提供跨会话的共享SQL上下文存储库，通过记录决策原因和约束规则来防止上下文丢失和重复工作，实现高效的团队知识管理和代码一致性。

article

README

🚀 sqlew

sqlew 是一个模型上下文协议（MCP）服务器，为 AI 代理提供跨会话的、基于 SQL 的共享上下文存储库，避免 AI 每次会话都从零开始，有效解决 AI 编码中的上下文缺失问题。

sqlew_logo

npm version License: AGPL v3

🚀 快速开始

安装

要求

  • Node.js 20.0.0 或更高版本
  • npm 或 npx

快速安装

在项目根目录的 .mcp.json 文件中添加以下内容：

{
  "mcpServers": {
    "sqlew": {
      "command": "npx",
      "args": ["sqlew"]
    }
  }
}

建议初始化后重启 Claude：首次运行时，sqlew 会初始化数据库、安装自定义代理和斜杠命令，但此时代理和命令不会加载。因此，请退出 Claude 并再次启动。

基本使用

你无需手动调用该工具，建议通过提示调用：

read sqlew usecases, and plan implementation of feature X using sqlew.

或者调用专用代理：

/sqw-plan implementation of feature X .

专用代理能更高效地使用 sqlew。

注意：/sqlew 命令取代了之前的多命令系统（/sqw-plan、/sqw-scrum 等）。现在所有功能都可通过统一的 /sqlew 界面使用，且能自动检测意图。

高级用法：直接访问 MCP 工具

高级用户仍可直接调用 MCP 工具。具体工具如下： | 工具 | 用途 | 示例用法 | |------|---------|------------| | decision | 记录选择和原因 | "We chose PostgreSQL" | | constraint | 定义规则 | "DO NOT use raw SQL, use ORM" | | task | 跟踪工作 | "Implement feature X" | | file | 跟踪更改 | "Modified auth.ts" | | stats | 数据库指标 | Get layer summary | | suggest | 查找相似决策（v3.9.0） | Duplicate detection, pattern search |

✨ 主要特性

解决 AI 编码痛点

现有问题

每个 Claude 会话都从零上下文开始，你必须重新解释决策，代理可能会重新引入错误，且无法跟踪决策的原因。虽然可以使用 Markdown 文件记录，但对于大规模项目和长期维护，会产生大量文档，导致 AI 系统中的上下文腐烂，性能下降。

sqlew 的解决方案

sqlew 通过使用关系数据库为 AI 构建高效的外部上下文存储库：

  • 记录决策背后的推理过程
  • 支持查询过去的上下文
  • 通过约束防止反模式
  • 通过任务管理消除重复工作

决策与约束存储库层

sqlew 最初旨在减少多个 AI 代理之间的重复工作和不一致行为，将上下文集中在共享的 SQL 数据库中。现代版本的 sqlew 将决策和约束历史视为一流数据：

  • 数据库架构围绕决策和约束进行优化，而非通用笔记
  • 三层 重复检测和建议系统 帮助你重用现有的决策/约束，避免创建几乎相同的内容
  • 移除或简化了旧的、未使用的功能，专注于长期上下文和一致性

核心优势

🧠 组织记忆

传统的代码分析（如 git）告诉你 做了什么，而 sqlew 在此基础上增加了 为什么 和 如何做：

  • 决策 → 为什么进行更改
  • 约束 → 应该如何编写
  • 任务 → 需要做什么

⚡ 令牌效率

在多会话项目中，通过结构化数据存储和选择性查询，减少 60 - 75% 的令牌使用。

🎯 开发工作流程的关键优势

  • 🧠 跨会话的上下文持久性：无需重新解释决策，会话可无缝延续，团队成员可快速了解过去的决策。
  • 🛡️ 防止上下文腐烂和不一致：定义架构约束，跟踪决策演变。
  • 🎯 实现一致、高质量的代码：防止 AI 重新引入已修复的错误，确保代码符合团队风格，提供上下文感知的建议，记录决策的原因。
  • 📊 透明的 AI 工作跟踪：了解任务依赖关系，自动更新任务状态，查看 AI 的工作进度。
  • ⚡ 效率和可靠性：减少令牌使用，降低上下文腐烂风险，经过实际项目测试。

📦 安装指南

要求

  • Node.js 20.0.0 或更高版本
  • npm 或 npx

快速安装

在项目根目录的 .mcp.json 文件中添加以下内容：

{
  "mcpServers": {
    "sqlew": {
      "command": "npx",
      "args": ["sqlew"]
    }
  }
}

建议初始化后重启 Claude：首次运行时，sqlew 会初始化数据库、安装自定义代理和斜杠命令，但此时代理和命令不会加载。因此，请退出 Claude 并再次启动。

注意事项

  • 不建议全局安装：因为 sqlew 每个项目需要独立的设置，每个项目应在 .sqlew/sqlew.db 中维护自己的上下文数据库。
  • 自定义数据库路径：可通过添加路径作为参数："args": ["sqlew", "/path/to/db.db"]
  • 默认位置：.sqlew/sqlew.db
  • 不支持 Junie AI：Junie AI 在 MCP 服务器配置中不能使用相对路径，这使其与 sqlew 的基于项目的数据库模型不兼容。每个项目需要在 .sqlew/sqlew.db 有自己独立的数据库，但 Junie AI 的全局 MCP 配置无法处理每个项目的数据库路径。

💻 使用示例

基础用法

你无需手动调用该工具，建议通过提示调用：

read sqlew usecases, and plan implementation of feature X using sqlew.

或者调用专用代理：

/sqw-plan implementation of feature X .

专用代理能更高效地使用 sqlew。

高级用法

/sqlew 命令的常见用法

# 显示状态并获取建议
/sqlew

# 记录决策
/sqlew record we use PostgreSQL 15 for production database

# 搜索过去的决策
/sqlew search why we chose Knex for migrations

# 列出剩余任务
/sqlew show remaining tasks

# 规划新功能（分解为任务）
/sqlew plan implementing user authentication

/sqlew 命令会自动检测你的意图（搜索、记录、列出、执行、创建任务）并调用相应的 MCP 工具。

📚 详细文档

按需文档

所有工具支持以下操作：

  • action: "help" - 参数参考和描述
  • action: "example" - 使用场景和示例
  • action: "use_case" - 实际使用示例

针对 AI 代理的文档

基础指南

任务系统

高级功能

参考文档

高级用法文档

🔧 技术细节

技术特性

  • 6 个专用 MCP 工具（决策、任务、文件、约束、统计、建议）
  • 智能相似度评分（0 - 100 分算法）
  • 运行时重新连接
  • 参数验证
  • 元数据驱动的组织

性能指标

  • 查询速度：2 - 50ms
  • 并发代理：5 个以上同时运行
  • 存储效率：每个决策约 140 字节
  • 令牌节省：典型项目中节省 60 - 75%

数据库支持

sqlew 支持多种数据库后端，适用于不同的部署场景： | 数据库 | 使用场景 | 状态 | |----------|----------------------------------------------|-------------| | SQLite | 个人或小型项目 | ✅ 默认 | | MySQL 8.0 / MariaDB 10+ | 生产环境、共享环境、远程工作 | ✅ 支持 | | PostgreSQL 12+ | 生产环境、共享环境、远程工作 | ✅ 支持 |

当然，它也适用于 Docker 关系数据库实例。

配置文件

首次运行时，会创建 .sqlew/config.toml 文件用于持久设置：

SQLite（默认）

[database]
path = ".sqlew/custom.db"

[autodelete]
ignore_weekend = true
message_hours = 48

PostgreSQL

[database]
type = "postgres"

[database.connection]
host = "localhost"
port = 5432
database = "sqlew_db"

[database.auth]
type = "direct"
user = "sqlew_user"
password = "secret"

MySQL/MariaDB

[database]
type = "mysql"

[database.connection]
host = "localhost"
port = 3306
database = "sqlew_db"

[database.auth]
type = "direct"
user = "sqlew_user"
password = "secret"

同时会创建 .sqlew/config.example.toml 文件供参考。

设置优先级：CLI 参数 > config.toml > 数据库默认值。

CLI 配置（推荐）

配置仅通过 .sqlew/config.toml 文件和 CLI 参数 管理。为简化起见，已移除 MCP config 工具。

仅使用 CLI 配置的原因

  • 无偏差：单一事实来源（配置文件）
  • 版本控制：将配置提交到 git，与团队共享
  • 清晰的文档：配置文件记录项目要求
  • 类型安全：TOML 验证在启动时捕获错误

常见 CLI 参数

# 自定义数据库路径
npx sqlew /path/to/database.db

# 自动删除设置
npx sqlew --autodelete-message-hours=48
npx sqlew --autodelete-file-history-days=30
npx sqlew --autodelete-ignore-weekend

# 自定义配置文件
npx sqlew --config-path=.sqlew/custom.toml

对于持久设置，建议编辑 .sqlew/config.toml 文件，而非使用 CLI 参数。

📄 许可证

本软件采用 AGPLv3 许可证，可免费使用。嵌入或修改时需开源。详情请见 LICENSE。

链接

支持与文档

致谢

本项目基于 Model Context Protocol SDK、better-sqlite3 和 TypeScript 构建。

作者：sin5ddd

版本

当前版本：4.0.2 发布历史请见 CHANGELOG.md。

v4.0.2 新增功能

  • 统一 CLI 入口点 - npx sqlew db:export 可直接使用（无需 npm install）
  • 仅通过 JSON 进行跨数据库迁移 - SQL 转储不再支持跨数据库转换
  • 需要 Node.js 20+ - 更新了最低版本要求

v4.0.0 新增功能

  • 架构重构 - 统一的 v4_ 表前缀，完全移除代理系统
  • 简洁架构 - 无遗留列，针对决策和约束存储库进行优化
  • 改进的迁移系统 - 重新组织 v3/v4 目录

建议参考 docs/DECISION_INTELLIGENCE.md 了解建议工具的详细信息。

⚠️ 重要提示

全局安装 (npm install -g) 不推荐，因为 sqlew 每个项目需要独立的设置。每个项目应在 .sqlew/sqlew.db 中维护自己的上下文数据库。Junie AI 不能使用相对路径在 MCP 服务器配置中，与 sqlew 的基于项目的数据库模型不兼容。

💡 使用建议

对于持久设置，建议编辑 .sqlew/config.toml 文件，而非使用 CLI 参数。建议初始化后重启 Claude，以确保代理和命令正常加载。

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端