sqlew

Design decisions, remembered by SQL — an MCP server for AI agents

What is sqlew?

The Problem

Every AI coding session starts from scratch. Your agent doesn't remember that you chose PostgreSQL over MongoDB last week, or that the team agreed on a specific API versioning strategy. Without persistent memory, agents repeat mistakes, contradict earlier decisions, and waste tokens re-discovering context.

The Solution

sqlew stores your architectural decisions in a structured SQL database. When a new session starts, the AI agent queries past decisions in milliseconds — not by reading through scattered Markdown files, but through efficient SQL lookups with metadata, tags, and similarity detection.

┌─────────────────────────────────────────────────────────────┐
│  Before sqlew                 │  After sqlew                │
│───────────────────────────────│─────────────────────────────│
│  Session 1: "Use PostgreSQL"  │  Session 1: "Use PostgreSQL"│
│  Session 2: "Use MongoDB?"    │    → decision recorded      │
│  Session 3: "Use PostgreSQL"  │  Session 2: query → got it  │
│  (same debate, every time)    │  Session 3: query → got it  │
│                               │    (instant recall)         │
└─────────────────────────────────────────────────────────────┘

sqlew is built on the Model Context Protocol (MCP), so it works with any MCP-compatible AI coding tool.

This software does not send any data to external networks. We NEVER collect any data or usage statistics.

Quick Start

1. Install

npm install -g sqlew

2. Setup

Choose the setup that matches your environment:

Claude Code (Plugin)

claude plugin marketplace add sqlew-io/sqlew-plugin
claude plugin install sqlew

The plugin automatically configures MCP server, Skills (Plan Mode guidance), and Hooks (automatic decision capture).

Codex CLI

See sqlew-codex for Codex CLI integration.

Manual

Add to .mcp.json in your project root:

{
    "mcpServers": {
        "sqlew": {
            "command": "sqlew"
        }
    }
}

The database (~/.config/sqlew/sqlew-shared.db) and config are auto-created on first run. See Shared Database for details.

3. Just use Plan Mode!

That's it. Every time you create a plan and get user approval, your architectural decisions are automatically recorded.

No special commands needed — just plan your work normally, and sqlew captures the decisions in the background.

Features

• Structured Records — Decisions stored as relational data with metadata, tags, layers, and version history
• Fast Queries — 2-50ms retrieval via SQL, even with thousands of decisions
• Duplicate Detection — Three-tier similarity scoring (0-100) prevents redundant decisions
• Constraint Tracking — Architectural rules and principles as first-class entities
• Auto-Capture — Hooks automatically record decisions from Plan Mode (Claude Code plugin)
• Multi-Database — SQLite (default), PostgreSQL, MySQL/MariaDB, or Cloud
• Git Worktree Ready — Each worktree shares the same context database

For Teams (sqlew.io)

Connect to sqlew.io for team-shared decisions:

Step 1: Get your API key

Visit sqlew.io and save your API key:

# ~/.config/sqlew/.sqlew.env (shared across all projects)
SQLEW_API_KEY=your-api-key

Step 2: Configure each project

# .sqlew/config.toml
[database]
type = "cloud"

[project]
name = "your-project-name"

Benefits:

• All team members share the same decision database
• Works seamlessly with Git worktree workflows
• No local database setup required

Performance

| Metric | Value | |--------|-------| | Query speed | 2-50ms | | Concurrent agents | 5+ simultaneous | | Storage efficiency | ~140 bytes/decision | | Token savings | 60-75% vs Markdown ADRs |

Use Cases

• Architecture Evolution — Document major decisions with full context and alternatives considered
• Pattern Standardization — Establish coding patterns as constraints, enforce via AI code generation
• Cross-Session Continuity — AI maintains context across days/weeks without re-reading docs
• Multi-Agent Coordination — Multiple AI agents share architectural understanding
• Onboarding Acceleration — New AI sessions instantly understand project history

Documentation

| Guide | Description | |-------|-------------| | ADR Concepts | Architecture Decision Records explained | | Configuration | Config file setup, database options | | Hooks Guide | Claude Code Hooks integration | | Cross Database | Multi-database support | | CLI Usage | Database migration, export/import |

Upgrade Guides

• Migrating to SaaS — Export local data to sqlew.io cloud

MCP Tools

7 action-based tools: decision, constraint, suggest, help, example, use_case, queue

All tools support action: "help" for documentation.

Support

Support development via GitHub Sponsors.

Version

Current version: 5.0.8

See CHANGELOG.md for release history.

What's New in v5.0.8:

• PR ADR enforcement — PreToolUse Hook blocks gh pr create without ADR markers, file-grouped format
• Codex CLI support — Works beyond Claude Code via sqlew-codex
• Plugin-first architecture — Simplified setup via sqlew-plugin
• Cloud backend — Connect to sqlew.io for team-shared decisions

License

Apache License 2.0 — Free for commercial and personal use. See LICENSE for details.

Links

• npm package
• GitHub
• Issues
• Model Context Protocol

Built with MCP SDK, better-sqlite3, and TypeScript.