MCP Sqlew

🚀 sqlew

An MCP server that gives AI agents a shared SQL - backed context repository, ensuring you never start from zero context again.

🚀 Quick Start

The easiest way to use sqlew is through the /sqlew command. Just type /sqlew in Claude Code with natural language input.

Most Common Uses

# Show status and get suggestions
/sqlew

# Record a decision
/sqlew record we use PostgreSQL 15 for production database

# Search past decisions
/sqlew search why we chose Knex for migrations

# List remaining tasks
/sqlew show remaining tasks

# Plan a new feature (breakdown into tasks)
/sqlew plan implementing user authentication

The /sqlew command automatically detects your intent (search, record, list, execute, task creation) and invokes the appropriate MCP tools.

To start using sqlew, install it, launch claude, exit claude, and then launch Claude again. You'll never need to call it manually. It's recommended to call this tool via prompt:

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

Or invoke Specialized Agent:

/sqw - plan implementation of feature X.

Specialized Agents use sqlew more efficiently.

Note: The /sqlew command supersedes the previous multi - command system (/sqw - plan, /sqw - scrum, etc.). All functionality is now available through the unified /sqlew interface with automatic intent detection.

Advanced: Direct MCP Tool Access

Power users can still call MCP tools directly. See [Available Tools](#available - tools) section below.

Available Tools

✨ Features

Concerns About AI Coding

Every Claude session starts with zero context. You must re - explain decisions, agents can re - introduce bugs, and there's no way to track WHY decisions were made. Using Markdown files to keep records is possible, but maintaining records for large - scale projects and long - term maintenance generates an enormous volume of documentation, leading to context rotting in AI systems and performance deterioration.

sqlew's Solution

sqlew builds an efficient external context repository for AI by using relational databases:

• Records the reasoning behind decisions
• Enables querying past context
• Prevents anti - patterns through constraints
• Eliminates duplicate work via task management

Concept: Decision & Constraint Repository Layer

sqlew originally aimed to reduce duplicated work and inconsistent behavior across multiple AI agents. It centralizes context in a shared SQL database. The most valuable part of this shared context is the history of Decisions and Constraints:

• Decisions capture why a change or design choice was made (trade - offs, rejected options, rationale).
• Constraints capture how things should be done (coding rules, architecture boundaries, performance requirements).

Modern versions of sqlew treat this decision & constraint history as first - class data:

• The database schema is optimized around Decisions and Constraints instead of generic notes.
• A three - tier duplicate detection and suggestion system helps you reuse existing Decisions/Constraints instead of creating nearly identical ones.
• Legacy, unused features have been removed or simplified to keep the focus on long - term context and consistency.

In practice, sqlew acts as a Decision & Constraint repository layer for your AI tools, allowing agents to query past decisions, existing rules, and how similar situations were handled.

Why Use sqlew?

🧠 Organizational Memory

Traditional code analysis like git tells you WHAT is done, while sqlew adds WHY and HOW:

• Decisions → WHY it was changed
• Constraints → HOW should it be written
• Tasks → WHAT needs to be done

⚡ Token Efficiency

Achieve a 60 - 75% token reduction in multi - session projects through structured data storage and selective querying.

🎯 Key Benefits for Your Development Workflow

• 🧠 Context Persistence Across Sessions:
  • No more re - explaining decisions. AI remembers decisions from weeks ago.
  • Ensure session continuity, allowing you to pick up exactly where you left off.
  • Facilitate team knowledge sharing, enabling new team members or AI sessions to instantly understand past decisions.
• 🛡️ Prevents Context Rotting & Inconsistency:
  • Define architectural constraints once, and AI will follow them forever.
  • Track version history to see how decisions evolved.
• 🎯 Enables Consistent, High - Quality Code:
  • Prevent bugs by documenting "what didn't work".
  • Enforce coding patterns to ensure AI writes code matching your team's style.
  • Provide context - aware suggestions to avoid redundant work.
  • Document the rationale behind every decision to prevent cargo - cult programming.
• 📊 Transparent AI Work Tracking:
  • Manage task dependencies, ensuring AI knows the order of task completion.
  • Automatically update tasks when AI edits tracked files.
  • Gain clear visibility into AI's work progress.
• ⚡ Efficiency & Reliability:
  • Reduce token usage by 60 - 75% through structured data storage.
  • Minimize context rot.
  • Be production - ready with 100% test passing rate.

🔖Kanban - style AI Scrum

 (This visualizer is not included in this package)

📦 Installation

Requirements

• Node.js 20.0.0 or higher
• npm or npx

Quick Install

Add the following lines to .mcp.json in your project's root:

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

Recommend to restart claude after initialize The first time, sqlew initializes the database, installs custom agents and slash commands. But agents and commands are not loaded at this time. So, please exit claude once and restart it again.

Notes

• ⚠️Note: Global install (npm install -g) is not recommended because sqlew requires an independent settings per project. Each project should maintain its own context database in .sqlew/sqlew.db.
• Custom database path: Add path as argument: "args": ["sqlew", "/path/to/db.db"]
• Default location: .sqlew/sqlew.db
• ⚠️ Not Supported: Junie AI cannot use relative paths in MCP server configurations, which makes it incompatible with sqlew's project - based database model. Each project requires its own isolated database at .sqlew/sqlew.db, but Junie AI's global MCP configuration cannot handle per - project database paths.

📚 Documentation

On - Demand Documentation

All tools support:

• action: "help" - Parameter reference and descriptions
• action: "example" - Usage scenarios and examples
• action: "use_case" - Real - world usage examples

For AI Agents

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 Intelligence - Three - tier duplicate detection (v3.9.0)
• 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

Advanced Usage

• Configuration Guide - TOML config file setup
• CLI Mode Overview - Database migration, export/import commands
• Building from Source - Setup instructions
• Migration Guides - Version upgrade guides

Use Cases

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

Performance

• Query speed: 2 - 50ms
• Concurrent agents: 5+ simultaneous
• Storage efficiency: ~140 bytes per decision
• Token savings: 60 - 75% in typical projects

Support

Support development via GitHub Sponsors - One - time or monthly options available.

Version

Current version: 4.0.2 See CHANGELOG.md for release history.

What's New in v4.0.2:

• Unified CLI Entry Point - npx sqlew db:export works directly (no npm install required)
• Cross - DB Migration via JSON Only - SQL dump no longer supports cross - database conversion
• Node.js 20+ Required - Updated minimum version requirement

What's New in v4.0.0:

• Schema Refactoring - Unified v4_ table prefix, agent system completely removed
• Clean Schema - No legacy columns, optimized for Decision & Constraint repository
• Improved Migration System - Reorganized v3/v4 directories

See docs/DECISION_INTELLIGENCE.md for details on the suggest tool.

📄 License

AGPLv3 - Free to use. Open - source required when embedding or modifying. See LICENSE for details.

Links

• npm package
• GitHub repository
• Model Context Protocol

Support & Documentation

• Issues: GitHub Issues
• Docs: docs/ directory

Acknowledgments

Built with Model Context Protocol SDK, better - sqlite3, and TypeScript.

Author: sin5ddd