sqlew

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

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.

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.

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.

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

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

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

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

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.

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

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.

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.

• 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

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

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

• 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

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

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 development via GitHub Sponsors.

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

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

• npm package
• GitHub
• Issues
• Model Context Protocol

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