sqlew

Design intent on tap — stop agents from re-auditing the whole repo every turn

What is sqlew?

The Problem

Strong coding agents no longer "forget" the stack between sessions the way older models did. They treat the codebase as ground truth — and that is good for correctness.

The new failure mode is cost and thrash:

• Specs, plans, and ADRs already say why a choice was made

• The agent still re-opens large swaths of source "just to be sure"

• Rejected alternatives and non-local constraints are expensive (or impossible) to re-derive from code alone

• Every turn pays the same investigation tax; multi-agent and multi-day work multiplies it

Code answers what is implemented. It is a poor, high-token index for why we chose it, what we forbade, and what we already rejected.

The Solution

sqlew is an MCP server that stores architectural decisions and constraints in a SQL database — with rationale, tags, layers, and rejected alternatives. Agents query intent first (suggest, session context, targeted decision / constraint lookups) instead of re-deriving design context from a full-tree read every turn.

┌──────────────────────────────────────────────────────────────────────┐
│  Without sqlew                         │  With sqlew                 │
│────────────────────────────────────────│─────────────────────────────│
│  Plan/spec: "use Postgres, no Mongo"   │  Research/write → ADR draft │
│  Next turn: re-read half the repo      │  (or Plan approved → ADR)   │
│  "just to confirm the architecture"    │  Next turn: suggest/query   │
│  Tokens burned; same audit next agent  │  → intent in milliseconds   │
└──────────────────────────────────────────────────────────────────────┘

sqlew does not replace reading code for implementation detail. It replaces ritual whole-repo archaeology for design intent with structured recall:

1. Capture — Plan Mode is not required. Research + Write hooks draft ADRs automatically; Plan Mode capture still works as before (sqlew-plugin)

2. Recall — Session start injects recent context (where the harness supports it); Post hooks on Grep / WebSearch / WebFetch inject related ADRs via suggest

3. Enforce — Constraints stay first-class rules; duplicate/similarity checks stop circular re-decisions

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.

Related MCP server: Memory MCP

Quick Start

1. Install

Local / full (default) — all RDB drivers (SQLite, PostgreSQL, MySQL). Unchanged:

npm install -g sqlew
# same capability under the scoped name:
npm install -g @sqlew/full

Cursor Cloud / ephemeral VMs — prefer PostgreSQL-only (no native SQLite addon):

npx @sqlew/pg
# or: npm install -g @sqlew/pg

Wire a remote DB with SQLEW_DATABASE_URL / DATABASE_URL in Environment Secrets. Project name usually comes from the git remote basename; set SQLEW_PROJECT_NAME only when sharing one DB across repos. Plan-less auto ADR needs sqlew-plugin Cursor hooks — MCP (npx @sqlew/pg) alone is not enough. Details: Cursor Cloud Agents. Other slim installs: @sqlew/mysql, @sqlew/sqlite. Package matrix: SCOPED_PACKAGES.md.

npm 12+ (bundled with Node 24.19+) blocks dependency install scripts by default. The full/@sqlew/sqlite installs need better-sqlite3 to download or compile its native addon, so allow that script:

npm install -g --allow-scripts=better-sqlite3 sqlew

Without the flag, sqlew installs but exits on first run with Could not locate the bindings file. Re-run the command above to repair an existing install. @sqlew/pg and @sqlew/mysql do not need this flag.

npm 11 and earlier still run install scripts by default; npm install -g sqlew is enough there.

2. Setup

Choose the setup that matches your environment. Each client has its own install and uninstall steps.

Claude Code (Plugin)

Install:

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

Configures MCP server, Skills (Plan Mode guidance), and Hooks (research suggest inject, Write enqueue / Stop flush, Plan-to-ADR).

Uninstall:

claude plugin remove sqlew

Codex CLI (Plugin)

Install:

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.

Do not duplicate skills in ~/.codex/skills/ or add [mcp_servers.sqlew] to config.toml when using the plugin. See Hooks Guide.

Uninstall:

codex plugin remove sqlew

Grok Build (Plugin)

Install:

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

Configures MCP server, Skills (plan mode guidance), and Hooks (plan-less save enqueue, Plan-to-ADR on exit_plan_mode).

Do not duplicate hooks in ~/.grok/hooks/ or add [mcp_servers.sqlew] to ~/.grok/config.toml. See Hooks Guide.

Uninstall:

grok plugin remove sqlew

Hermes (Plugin)

Requires sqlew >= 5.3.0. Hermes uses a separate plugin bundle (.hermes-plugin/), not the Claude/Codex plugin manifest.

Install:

hermes plugins install sqlew-io/sqlew-plugin/.hermes-plugin
hermes plugins enable sqlew

Merges MCP + shell hooks into ~/.hermes/config.yaml and copies planning skills to ~/.hermes/skills/. See Hermes Hooks Guide for wire-protocol details and manual config.yaml setup.

Uninstall:

hermes plugins remove sqlew

If you merged hooks manually before using the plugin, also remove mcp_servers.sqlew and sqlew hooks: entries from ~/.hermes/config.yaml. Skills under ~/.hermes/skills/sqlew-* are not removed automatically.

oh-my-pi / omp (Extension)

Requires sqlew with the sqlew/hooks export (see Harness Compatibility for the minimum version). omp uses an in-process Extension (.omp-plugin/), not Claude-style shell hooks.

Install:

npm i -g --allow-scripts=better-sqlite3 sqlew   # see Install above (npm 12+)
omp --extension /path/to/sqlew-plugin/.omp-plugin
# or:
omp plugin install /path/to/sqlew-plugin/.omp-plugin

Session context via before_agent_start; Plan-to-ADR when you approve via xd://propose / /xdev/propose. Plans live as session-local local://*-plan.md (no project .sqlew/plans/ copy by default). See Hooks Guide.

MCP still comes from the project .mcp.json (Extension does not re-register MCP when already present).

Other harness (MCP only)

MCP server only — no sqlew-plugin hooks or skills (Cursor, Claude Desktop, custom clients, …). See Harness Compatibility.

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. Capture decisions (Plan Mode optional)

Plan Mode is no longer required for ADR / suggest. With sqlew-plugin hooks:

1. Research — Post hooks on Grep / WebSearch / WebFetch (and equivalents) inject related context via suggest

2. Write — first implementation Write enqueues a draft ADR to .sqlew/queue/pending.json (no DB write yet)

3. Stop / flush — on-stop or QueueWatcher upserts the queue into the database

Plan Mode still works as before — create a plan, get approval, and Plan-to-ADR records 📌 / 🚫 blocks automatically.

Hermes exception: Hermes cannot drive this automatic research→ADR trigger via Hooks. Create a Skill with /learn, for example: 「調査開始時にsqlewを使ってサジェストを取得し、実装前にADRをsqlewで記録することを義務付けて」

See Harness Compatibility and Hooks Guide.

Features

• Structured Records — Decisions stored as relational data with metadata, tags, layers, and version history

• Fast Queries — 2-50ms SQL recall for design intent; avoid multi-file repo archaeology every turn

• Duplicate Detection — Three-tier similarity scoring (0-100) prevents redundant decisions

• Constraint Tracking — Architectural rules and principles as first-class entities

• Auto-Capture (plan-less) — Research Post hooks inject related ADRs; Write enqueues drafts; Stop / flush upserts to DB

• Auto-Capture (Plan Mode) — Hooks/Extension still record decisions from Plan Mode (Claude Code, Codex, Grok Build, Hermes, and oh-my-pi via sqlew-plugin)

• Session Context Injection — Recent decisions and active constraints injected at session start (Claude Code, Hermes, omp, Codex partial; not Grok Build — see matrix)

• Multi-Database — SQLite (default), PostgreSQL, MySQL/MariaDB, or Cloud

• Git Worktree Ready — Each worktree shares the same context database

Harness compatibility

Not every feature works the same on every client. Grok Build uses passive hooks (no stdout injection), so session context and plan-mode hook enforcement are skill-based only (◎). oh-my-pi (omp) uses an in-process Extension (sqlew/hooks) rather than shell hooks — the summary rows below are full (✓). Hermes lacks Post-hook context inject for research→ADR — use a Skill (/learn); Plan-to-ADR via plan files still works.

✓ full · △ partial · ◎ skills only · ✎ manual MCP · — not available

Full matrix (hooks, Other harness column, fallbacks): Harness Compatibility

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

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 — Agents reuse recorded intent across days without re-auditing the tree for why

• Multi-Agent Coordination — Multiple AI agents share architectural understanding

• Onboarding Acceleration — New sessions/agents load decisions and constraints first, then read only the code paths that matter

Documentation

Upgrade Guides

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

MCP Tools

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

All tools support action: "help" for documentation. The project tool targets a project per call for desktop AI agents (Claude Desktop, Hermes Desktop) — see Shared Database.

Support

Support development via GitHub Sponsors.

Version

Current version: 5.3.0

See CHANGELOG.md for release history.

What's New in v5.3.0:

• Hermes support — Plan-to-ADR via sqlew-plugin .hermes-plugin bundle (hermes plugins install sqlew-io/sqlew-plugin/.hermes-plugin)

• Hook normalization — Hermes pre_tool_call / pre_llm_call payloads mapped to canonical Claude-shaped events and tools

• Every-turn plan guidance — on-prompt injects FULL/SHORT context via Hermes pre_llm_call ({"context":"..."})

• .hermes/plans/ — Plan files written by the Hermes plan skill are tracked for decision extraction

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.