MCP 服务器

sqlew

Stores architectural decisions in a SQL database for persistent AI agent memory, enabling cross-session continuity and duplicate detection.

README

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