SQL Efficient Workflow - MCP server for efficient context sharing between Claude Code sub-agents
sqlew is a Model Context Protocol (MCP) server that gives AI agents organizational memory across sessions.
The Problem: Without sqlew, every Claude session starts with zero context. You must re-explain decisions, agents can reintroduce bugs, and there's no way to track WHY decisions were made.
The Solution: sqlew lets agents remember decisions, query past context, prevent regressions with constraints, and coordinate via messaging and tasks.
Example: Session 1 records "API v1 deprecated". Session 2 (days later) queries and automatically uses v2.
Traditional code tells you WHAT and HOW. sqlew adds WHY:
- Decisions → WHY it was changed
- Constraints → WHY it must work this way
60-75% token reduction in multi-session projects through structured data storage and selective querying.
- 6 Specialized Tools: decisions, tasks, files, constraints, stats, config
- Metadata-Driven: Tag, layer, scope, and version everything
- Decision Context: Document WHY with rationale, alternatives, and trade-offs
- Task Dependencies: Blocking relationships with circular detection
- Auto-File Tracking: Zero-token task management via file watching
- Smart Review Detection: Quality-based auto-transition to
waiting_review - Auto-Stale Detection: Tasks auto-transition when idle
- Weekend-Aware Cleanup: Smart retention during weekends
- Batch Operations: Process up to 50 items atomically
See docs/TASK_OVERVIEW.md and docs/DECISION_CONTEXT.md for details.
- Node.js 18.0.0 or higher
- npm or npx
Recommended (npx):
npx sqlewOr install per project:
npm install sqlewNote: Global install (npm install -g) is not recommended because sqlew requires an independent database per project. Each project should maintain its own context database in .sqlew/sqlew.db.
Edit claude_desktop_config.json:
{
"mcpServers": {
"sqlew": {
"command": "npx",
"args": ["sqlew"]
}
}
}Restart Claude Desktop. Done!
Custom database path: Add path as argument: "args": ["sqlew", "/path/to/db.db"]
Default location: .sqlew/sqlew.db
Create .sqlew/config.toml for persistent settings:
[database]
path = ".sqlew/custom.db"
[autodelete]
ignore_weekend = true
message_hours = 48Priority: CLI args > config.toml > database defaults
See docs/CONFIGURATION.md for all options and validation rules.
All tools require an action parameter. Example:
// Store a decision
{action: "set", key: "auth_method", value: "JWT", layer: "business", tags: ["security"]}
// Query later
{action: "get", key: "auth_method"}For detailed examples, see docs/TOOL_REFERENCE.md.
sqlew provides three specialized agents for efficient multi-agent coordination in Claude Code:
| Agent | Purpose | Token Cost | Use When |
|---|---|---|---|
| Scrum Master | Multi-agent coordination, task management, sprint planning | 12KB/conversation | Coordinating complex features, managing dependencies, tracking progress |
| Researcher | Query decisions, analyze patterns, investigate context | 14KB/conversation | Understanding past decisions, onboarding new members, sprint retrospectives |
| Architect | Document decisions, enforce constraints, maintain standards | 20KB/conversation | Making architectural choices, establishing rules, validating compliance |
By default, all three specialized agents are automatically installed to your project's .claude/agents/ directory on first run.
To disable specific agents, create .sqlew/config.toml:
[agents]
scrum_master = true # Coordination specialist (12KB)
researcher = false # Disable this agent
architect = true # Documentation specialist (20KB)Note: Set an agent to false in the config file to prevent it from being installed.
Usage: Invoke agents with the @ prefix: @sqlew-scrum-master, @sqlew-researcher, @sqlew-architect
Recommendation: Use all three agents together - they're complementary specialists (46KB total).
Token Optimization (if needed): Disable unused agents in config. Savings: Scrum + Architect = 32KB (30%) | Scrum only = 12KB (74%)
See docs/SPECIALIZED_AGENTS.md for complete installation guide, usage examples, and customization.
| Tool | Purpose | Example Use |
|---|---|---|
| decision | Record choices | "We chose PostgreSQL" |
| task | Track work | "Implement feature X" |
| file | Track changes | "Modified auth.ts" |
| constraint | Define rules | "API must be <100ms" |
| stats | Database metrics | Get layer summary |
| config | Retention settings | Auto-cleanup config |
Each tool supports action: "help" for full documentation and action: "example" for comprehensive usage examples.
All tools support:
action: "help"- Parameter reference and descriptionsaction: "example"- Usage scenarios and examples
Essential Guides:
- Tool Selection - Decision tree, when to use each tool
- Workflows - Multi-step examples, multi-agent coordination
- Tool Reference - Parameters, batch operations, templates
- Best Practices - Common errors, troubleshooting
Task System:
- Task Overview - Lifecycle, status transitions
- Task Actions - All actions with examples
- Task Dependencies - Blocking relationships
- Task Linking - Link to decisions/constraints/files
- Task Migration - Migrate from decision-based tracking
Advanced Features:
- Decision Context - Rich decision documentation
- Auto File Tracking - Zero-token task management
- Acceptance Criteria - All check types
Reference:
- Shared Concepts - Layer definitions, enum values
- Configuration - Config file setup, all options
- Architecture - Technical architecture
- Configuration Guide - TOML config file setup
- Building from Source - Setup instructions
- Migration Guides - Version upgrade guides
- Multi-Agent Coordination: Orchestrators create tasks, agents send status updates
- Breaking Change Management: Record deprecations and add architectural constraints
- Decision Context: Document rationale, alternatives considered, and trade-offs
- Session Continuity: Save progress in Session 1, resume in Session 2
See docs/WORKFLOWS.md for detailed multi-step examples.
- Query speed: 2-50ms
- Concurrent agents: 5+ simultaneous
- Storage efficiency: ~140 bytes per decision
- Token savings: 60-75% in typical projects
Support development via GitHub Sponsors - One-time or monthly options available.
Current version: 3.6.5 See CHANGELOG.md for release history.
AGPLv3 - Free to use. Open-source required when embedding or modifying. See LICENSE for details.
- Issues: GitHub Issues
- Docs: docs/ directory
Built with Model Context Protocol SDK, better-sqlite3, and TypeScript.
Author: sin5ddd