sqlew

SQL高效工作流 - MCP服务器，用于Claude Code子代理之间的高效上下文共享

sqlew是什么？

sqlew 是一个模型上下文协议（MCP）服务器，它提供了AI代理在会话之间组织记忆的功能。

面临的问题

没有sqlew的情况下，每个Claude会话都从零上下文开始。您必须重新解释决策，代理可能会重新引入错误，并且无法追踪为什么做出这些决策。

虽然可以使用Markdown文件来记录信息，但在大规模项目或长期维护记录中，这会产生大量的文档。这已经成为一个问题，因为它会导致AI系统中的上下文退化，从而导致性能下降。

解决方案

sqlew通过使用关系数据库构建高效的外部记忆。

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

示例：

• 第一次会话记录“API v1已弃用”。
• 几天后的第二次会话查询并自动使用v2。

本软件不会向外部网络发送任何数据。我们绝不会收集任何数据或使用统计信息。请完全安全地使用它。

为什么要使用sqlew？

🧠 组织记忆

传统的代码分析如git告诉您做了什么，sqlew添加了为什么和如何：

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

⚡ 令牌效率

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

🎯 主要特性

• 5种专用工具：决策、任务、文件、约束、统计
• 运行时重连：自动数据库连接恢复，采用指数退避策略
• 参数验证：检测拼写错误，标记必填/选填项，错误消息更简洁（70-85%）
• 元数据驱动：标记、层、范围和版本一切
• 决策上下文：记录为什么，包括理由、替代方案和权衡
• 任务依赖：循环检测的阻塞关系
• 自动文件跟踪：通过文件监控实现零令牌任务管理
• 智能审查检测：基于质量自动过渡到等待审查
• 自动过期检测：任务在空闲时自动过渡
• 周末感知清理：智能保留期间的周末
• 批处理操作：原子处理最多50个项目

详情见 docs/TASK_OVERVIEW.md 和 docs/DECISION_CONTEXT.md。

🔖 类Kanban的AI冲刺

安装

要求

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

快速安装

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

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

建议初始化后重启claude

第一次运行时，sqlew会安装自定义代理并初始化数据库。自定义代理在此时不会加载。请退出claude一次，然后再次启动claude。

现在可以使用了！

⚠️ 注意：不推荐全局安装（npm install -g），因为sqlew需要每个项目的独立设置。每个项目应在.sqlew/sqlew.db中维护自己的上下文数据库。

自定义数据库路径：作为参数添加路径："args": ["sqlew", "/path/to/db.db"] 默认位置：.sqlew/sqlew.db

JetBrains Junie AI

⚠️ 不支持：Junie AI不能在MCP服务器配置中使用相对路径，这使得它与sqlew的基于项目的数据库模型不兼容。每个项目都需要在.sqlew/sqlew.db中拥有自己的隔离数据库，但Junie AI的全局MCP配置无法处理每个项目的数据库路径。

配置

数据库支持

sqlew支持多种数据库后端以适应不同的部署场景：

数据库	使用场景	状态
SQLite	开发、小型项目	✅ 默认
MySQL 8.0 / MariaDB 10+	生产、共享环境	✅ 支持
PostgreSQL 12+	生产、企业	✅ v3.8.0+

可选配置文件

首次运行时，.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 > 数据库默认值

详情见 docs/CONFIGURATION.md 中的所有选项和验证规则。

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参数。

快速入门

安装它，启动claude，退出claude并再次启动。

基本使用

您永远不需要手动调用它，我建议通过提示调用此工具。

阅读sqlew用例，计划使用sqlew实现功能X。

或者调用专用代理

计划使用@agent-scrum-master实现功能X。

专用代理更有效地使用sqlew。

专用代理

sqlew提供三种专用代理，用于Claude Code中高效多代理协调：

代理	目的	令牌成本	使用时机
Scrum Master	多代理协调、任务管理、冲刺规划	12KB/对话	协调复杂功能、管理依赖、跟踪进度
Researcher	查询决策、分析模式、调查上下文	14KB/对话	理解过去决策、新成员入职、冲刺回顾
Architect	记录决策、执行约束、维持标准	20KB/对话	制定架构选择、建立规则、验证合规性

详细安装

默认情况下，所有三个专用代理都会自动安装 到您的项目的.claude/agents/目录中。

要禁用特定代理，请创建 .sqlew/config.toml：

[agents]
scrum_master = true   # 协调专家（12KB）
researcher = false    # 禁用此代理
architect = true      # 文档专家（20KB）

注意：在配置文件中将代理设为false以防止其安装。

使用：通过@前缀调用代理：@sqlew-scrum-master，@sqlew-researcher，@sqlew-architect

建议：一起使用所有三个代理——它们是互补的专家（总计46KB）。

令牌优化（如有必要）：在配置中禁用未使用的代理。 节省：Scrum + Architect = 32KB（30%）| Scrum仅 = 12KB（74%）

详情见 docs/SPECIALIZED_AGENTS.md 中的完整安装指南、使用示例和定制。

可用工具

工具	目的	示例用途
decision	记录选择和原因	“我们选择了PostgreSQL”
constraint	定义规则	“不得使用原始SQL，使用ORM”
task	跟踪工作	“实现功能X”
file	跟踪更改	“修改auth.ts”
stats	数据库指标	获取层摘要

文档

每个工具都支持 action: "help" 以获取完整文档和 action: "example" 以获取全面使用示例。

并且 action: "use_case" 显示如何在实际场景中使用该工具。

按需文档

所有工具都支持：

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

对于AI代理

重要指南：

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

任务系统：

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

高级功能：

• 决策上下文 - 丰富的决策文档
• 自动文件跟踪 - 零令牌任务管理
• 验收标准 - 所有检查类型

参考：

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

对于开发者

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

使用案例

• 多代理协调：编排器创建任务，代理发送状态更新
• 重大变更管理：记录弃用并添加架构约束
• 决策上下文：记录理由，考虑的替代方案和权衡
• 会话连续性：保存第1次会话的进度，第2次会话继续

详情见 docs/WORKFLOWS.md 中的详细多步骤示例。

性能

• 查询速度：2-50ms
• 并发代理：5+ 同时
• 存储效率：~140字节/决策
• 令牌节省：典型项目中节省60-75%

支持

通过 GitHub Sponsors 支持开发 - 提供一次性或每月选项。

版本

当前版本：3.7.4 查看 CHANGELOG.md 中的发布历史。

许可证

AGPLv3 - 免费使用。嵌入或修改时需要开源。详情见 LICENSE。

链接

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

支持与文档

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

致谢

使用 Model Context Protocol SDK，better-sqlite3 和 TypeScript 构建。

作者：sin5ddd