# sqlew

![sqlew_logo](assets/sqlew-logo.png)

[![npm version](https://img.shields.io/npm/v/sqlew.svg)](https://www.npmjs.com/package/sqlew)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

> **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](https://modelcontextprotocol.io/) (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

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

```bash
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):

```bash
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](https://github.com/sqlew-io/sqlew-plugin) Cursor hooks** — MCP (`npx @sqlew/pg`) alone is not enough. Details: [Cursor Cloud Agents](docs/CONFIGURATION.md#cursor-cloud-agents). Other slim installs: `@sqlew/mysql`, `@sqlew/sqlite`. Package matrix: [SCOPED_PACKAGES.md](docs/SCOPED_PACKAGES.md).

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

```bash
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` (often under `node-v137-win32-x64` on Node 24 / Windows). That is **not** a missing Node 24 prebuild — the prebuild exists, but npm never ran `prebuild-install`. Re-run the command above to repair an existing install. `@sqlew/pg` and `@sqlew/mysql` do not need this flag.

**Windows + Cursor plugin MCP (`plugin-sqlew-sqlew`)** using global `sqlew` on Node 24: if MCP shows “Connection closed”, reinstall with `--allow-scripts=better-sqlite3`, or switch the MCP command to Node 22 LTS, or use Postgres instead (`npx -y @sqlew/pg` + `SQLEW_DATABASE_URL` / Neon). See [Troubleshooting](#troubleshooting-sqlite-native-addon).

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:**

```bash
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:**

```bash
claude plugin remove sqlew
```

#### Codex CLI (Plugin)

**Install:**

```bash
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](docs/HOOKS_GUIDE.md).

**Uninstall:**

```bash
codex plugin remove sqlew
```

#### Grok Build (Plugin)

**Install:**

```bash
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](docs/HOOKS_GUIDE.md).

**Uninstall:**

```bash
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:**

```bash
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](docs/HERMES_HOOKS.md) for wire-protocol details and manual `config.yaml` setup.

**Uninstall:**

```bash
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](docs/HARNESS_COMPATIBILITY.md) for the minimum version). omp uses an in-process **Extension** (`.omp-plugin/`), not Claude-style shell hooks.

**Install:**

```bash
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](docs/HOOKS_GUIDE.md#oh-my-pi-omp).

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](docs/HARNESS_COMPATIBILITY.md#other-harness--what-is-this-column).

Add to `.mcp.json` in your project root:

```json
{
    "mcpServers": {
        "sqlew": {
            "command": "sqlew"
        }
    }
}
```

The database (`~/.config/sqlew/sqlew-shared.db`) and config are auto-created on first run. See [Shared Database](docs/SHARED_DATABASE.md) 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](docs/HARNESS_COMPATIBILITY.md) and [Hooks Guide](docs/HOOKS_GUIDE.md).

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

| Feature | Claude | Codex | Grok | Hermes | omp |
|---------|:------:|:-----:|:----:|:------:|:---:|
| MCP tools | ✓ | ✓ | ✓ | ✓ | ✓ |
| Session context injection | ✓ | △ | — | ✓ | ✓ |
| Research → ADR (plan-less) | ✓ | △ | △ | ◎ | ✓ |
| Plan-to-ADR (auto) | ✓ | △ | △ | ✓ | ✓ |
| Plan mode hook enforcement | ✓ | △ | ◎ | ✓ | ✓ |

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

Full matrix (hooks, **Other harness** column, fallbacks): **[Harness Compatibility](docs/HARNESS_COMPATIBILITY.md)**

## For Teams (sqlew.io)

Connect to [sqlew.io](https://sqlew.io) for team-shared decisions:

**Step 1: Get your API key**

Visit [sqlew.io](https://sqlew.io) and save your API key:

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

**Step 2: Configure each project**

```toml
# .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 | Fewer full-tree "confirm the architecture" passes; 60-75% vs dumping Markdown ADRs into context |

## 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

| Guide | Description |
|-------|-------------|
| [ADR Concepts](docs/ADR_CONCEPTS.md) | Architecture Decision Records explained |
| [Configuration](docs/CONFIGURATION.md) | Config file setup, database options |
| [Harness Compatibility](docs/HARNESS_COMPATIBILITY.md) | Feature × harness matrix (MCP, hooks, session context, Plan-to-ADR) |
| [Hooks Guide](docs/HOOKS_GUIDE.md) | Claude Code, Codex, Grok Build, Hermes, and oh-my-pi (omp) integration |
| [Hermes Hooks Guide](docs/HERMES_HOOKS.md) | Hermes-specific setup and wire-protocol notes |
| [Cross Database](docs/CROSS_DATABASE.md) | Multi-database support |
| [CLI Usage](docs/CLI_USAGE.md) | Database migration, export/import |
| [Scoped packages](docs/SCOPED_PACKAGES.md) | `@sqlew/*` matrix, Cloud install, npm release via GitHub Actions |

### Upgrade Guides

- [Migrating to SaaS](docs/MIGRATION_TO_SAAS.md) — 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](docs/SHARED_DATABASE.md).

## Troubleshooting: SQLite native addon

Symptom: Cursor MCP `plugin-sqlew-sqlew` closes immediately; stderr / logs mention:

`.../better-sqlite3/lib/binding/node-v137-win32-x64/better_sqlite3.node` → `Could not locate the bindings file`.

| Option | Command / change |
|--------|------------------|
| **Repair global `sqlew` (preferred on local Windows)** | `npm install -g --allow-scripts=better-sqlite3 sqlew` |
| **Use Node 22 LTS** | `nvm use 22` (or install 22), then reinstall with the flag above |
| **Skip SQLite** | MCP command `npx` args `["-y","@sqlew/pg"]` + `SQLEW_DATABASE_URL` / `DATABASE_URL` (Neon/Postgres) |

Node 24 (ABI 137) **does** have win32-x64 prebuilds in better-sqlite3 12.1+. The usual failure is npm 12 skipping the install script, not a missing binary.

## Support

Support development via [GitHub Sponsors](https://github.com/sponsors/sqlew-io).

## Version

Current version: **5.3.0**

See [CHANGELOG.md](CHANGELOG.md) for release history.

**What's New in v5.3.0:**

- **Hermes support** — Plan-to-ADR via [sqlew-plugin](https://github.com/sqlew-io/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](LICENSE) for details.

## Links

- [npm package](https://www.npmjs.com/package/sqlew)
- [GitHub](https://github.com/sqlew-io/sqlew)
- [Issues](https://github.com/sqlew-io/sqlew/issues)
- [Model Context Protocol](https://modelcontextprotocol.io/)

---

Built with [MCP SDK](https://github.com/modelcontextprotocol/sdk), [better-sqlite3](https://github.com/WiseLibs/better-sqlite3), and TypeScript.