mcp-sqlew

🚀 sqlew

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

🚀 快速开始

安装

要求

• 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 代理的文档

基础指南

• 工具选择 - 决策树，何时使用每个工具
• 工作流程 - 多步骤示例，多代理协调
• 工具参考 - 参数、批量操作、模板
• 最佳实践 - 常见错误、故障排除

任务系统

• 任务概述 - 生命周期、状态转换
• 任务操作 - 所有操作及示例
• 任务依赖 - 阻塞关系
• 任务链接 - 链接到决策/约束/文件
• 任务迁移 - 从基于决策的跟踪迁移

高级功能

• 决策智能 - 三层重复检测（v3.9.0）
• 决策上下文 - 丰富的决策文档
• 自动文件跟踪 - 零令牌任务管理
• 验收标准 - 所有检查类型

参考文档

• 共享概念 - 层定义、枚举值
• 配置 - 配置文件设置，所有选项
• 架构 - 技术架构

高级用法文档

• 配置指南 - TOML 配置文件设置
• CLI 模式概述 - 数据库迁移、导出/导入命令
• 从源代码构建 - 设置说明
• 迁移指南 - 版本升级指南

🔧 技术细节

技术特性

• 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。

链接

• npm 包
• GitHub 仓库
• 模型上下文协议

支持与文档

• 问题反馈：GitHub Issues
• 文档：docs/ 目录

致谢

本项目基于 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，以确保代理和命令正常加载。