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 (Plugin)

codex plugin marketplace add sqlew-io/sqlew-plugin
codex plugin install sqlew --source sqlew-plugin

After install, open /hooks in Codex and trust the bundled sqlew hooks. Enable Plan Mode with collaboration_modes = true under [features] in your Codex config. The plugin configures MCP server, Skills (plan mode guidance), and Hooks (plan enforcement, PR ADR guard, decision extraction). See Hooks Guide for caveats (do not duplicate skills in ~/.codex/skills/ or add [mcp_servers.sqlew] to config.toml).

Grok Build (Plugin)

npm install -g sqlew
grok plugin install sqlew-io/sqlew-plugin --trust
grok plugin update

The plugin configures MCP server, Skills (plan mode guidance), and Hooks (automatic decision capture on exit_plan_mode). See Hooks Guide for setup details and caveats (do not duplicate hooks in ~/.grok/hooks/ or config.toml).

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, Codex, and Grok Build via sqlew-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, Codex, and Grok Build 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.2.0

See CHANGELOG.md for release history.

What's New in v5.2.0:

• Grok Build support — Plan-to-ADR via sqlew-plugin (grok plugin install sqlew-io/sqlew-plugin --trust)
• Grok plan.md injection — Decision/Constraint template appended on enter_plan_mode
• Hook normalization — Single CLI hook handlers work under both Claude Code and Grok Build

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.