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