nlqdb — analytical memory for AI agents

com.nlqdbPublished by nlqdb.comOfficial publisherv0.1.1Updated Oct 24, 2026

Analytical memory for AI agents: a real Postgres queried in plain English over MCP. One command.

VerifiedStreamable HTTPWeb executableDatabasesData & AnalyticsAI & ML

Overview

AI-generated overview

Hosted MCP server that lets an AI agent query a real Postgres or D1 database in plain English, with the generated SQL returned.

What you can do
  • Ask questions of a connected Postgres or Cloudflare D1 database in natural language, with nlqdb inferring schema and writing the SQL
  • Run and insert through the hosted HTTP API surfaces the same service exposes
  • Create a database by name or goal and then talk to it in plain English
  • Receive the executed SQL and a confidence signal alongside each answer
  • Attach to an existing database so the service can propose, apply and measure changes
When to use it
Useful when an agent needs to aggregate, join or group over real business data rather than recall notes, and you want natural-language SQL without building a backend. Suited to early adopters who can tolerate imperfect answers and check the returned SQL.
Requirements
Remote endpoint at mcp.nlqdb.com over streamable HTTP with OAuth approval in a browser. Headless hosts instead run the local npm package with an sk_mcp_* MCP key. A Postgres or Cloudflare D1 database and an nlqdb account are needed; the free tier uses built-in open models, and paid plans or your own LLM key are optional.
Before you install
The service connects to your database and can write: it proposes changes, applies approved ones and can revert them, and the API includes insert and run endpoints. Natural-language to SQL accuracy is still below the project's public bar, so answers can be wrong; check the SQL and confidence. Queries and data go to a third-party hosted service, and API keys appear inline in client snippets.

Installation

In SourceWeft

  1. Open nlqdb — analytical memory for AI agents in the dashboard and add it to a workspace.
  2. Connect the required credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/com.nlqdb%2Fnlqdb/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.

{
  "mcpServers": {
    "nlqdb-analytical-memory-for-ai-agents": {
      "type": "http",
      "url": "https://mcp.nlqdb.com/mcp"
    }
  }
}

README

nlqdb — your autonomous DBA.

nlqdb attaches to the Postgres or Cloudflare D1 database you already run, proposes the changes it needs, applies the ones you approve, measures them, and reverts any that regress.

Why it exists: the mission — encapsulate the trial-and-error journey every company walks to a good database infrastructure.

Where it is going (docs/END_GOAL.md): paste a connection string — on nlqdb.com, with the CLI, through the SDK, or from your coding agent over MCP — and the first proposals arrive within minutes, each with its expected effect, cost and inverse. Apply is one click; nlqdb then measures p95 on the same queries and keeps the change or reverts it, never on your app's request path. That loop is being built (Roadmap); what is live today is the hosted product below.

No backend to build. You write HTML; each component asks for what it wants in plain English; nlqdb infers the schema, writes the SQL, runs it, and renders the result. There is no backend for you to build.

Two actions. That's the whole product:

  1. Create a database — one word: a name (or a goal).
  2. Talk to it in plain English.
html
<script src="https://elements.nlqdb.com/v1.js" type="module"></script>
<nlq-data  goal="the 5 newest orders, with customer and item"  api-key="pk_live_xxx"  template="table"  refresh="10s"></nlq-data>

That's the entire backend for a live order list — no API to write, no schema to define, no JSON to parse. Engine choice (Postgres / Mongo / Redis / DuckDB / pgvector / …), schema inference, indexing, backups, and auto-migration between engines based on your real workload are background concerns you never have to see.

Status — early, open

nlqdb is early and built in the open, but fully public — no gate, no invite code. The marketing site, the /v1/ask pipeline, the <nlq-data> / <nlq-action> elements, the chat app, the TypeScript SDK, the hosted MCP server, and the nlq CLI are all live in some form (see the surface table below). Natural-language → SQL accuracy is still climbing toward our public bar (BIRD ≥ 0.65, Spider 2.0 ≥ 0.75 on the free model chain), so answers can be wrong — every response carries a confidence signal and the SQL it ran.

Use it

Connecting an agent over MCP? On Claude Code, one marketplace add wires the hosted server and both memory skills in a single step:

/plugin marketplace add nlqdb/nlqdb/plugin install nlqdb-memory@nlqdb

On any other MCP host, connect your agent with one browser-OAuth approval; headless hosts skip the browser with npx -y @nlqdb/mcp and an sk_mcp_* MCP key (MCP setup). @nlqdb/sdk and @nlqdb/mcp are both published and importable from npm.

The 60-second walkthrough — plain HTML, CLI, and ten framework wrappers — lives at docs.nlqdb.com. Start with the HTML tutorial or the CLI tutorial.

You don't generate an API key separately: describe your database at nlqdb.com, and the chat hands you a <nlq-data> snippet with the key already inlined.

Examples

examples/ — minimal scaffolds in plain HTML, Next.js, Nuxt, SvelteKit, Astro, plus a CLI-only walkthrough. Each is the smallest valid integration around one <nlq-data> element or one CLI session.

What makes it different

Four things every release has to move, none allowed to regress (GLOBAL-025):

  • Engine quality — natural-language → SQL accuracy (measured continuously on BIRD + Spider 2.0 + an internal eval), plus the multi-engine layer that moves your data to the right engine for your workload.
  • Onboarding — landing to first answer in under a minute, no card, no config.
  • UX — see the diff before any write, see the SQL behind every answer, and on low confidence get a one-click clarify — a guided turn, never a dead-end, and never a silent guess.
  • Performance — sub-400 ms cached, sub-1.5 s cold.

The bet: get this right on free, open models and it only gets better on frontier ones — the scaffolding compounds with whatever model is underneath.

Models & plans

  • Free forever on the built-in open-model chain — queries, embeds, and the elements, no card required.
  • Bring your own LLM key (Anthropic / OpenAI / Gemini / Grok / OpenRouter) on any tier, at no markup.
  • Hosted premium models on paid plans, when you'd rather not manage a key of your own.
  • Self-host the source — the engine, CLI, MCP server, and SDKs are source-available under FSL-1.1-ALv2: free to self-host for any non-competing use, bring your own LLM key, no per-call fees. The license auto-converts to Apache 2.0 two years after each release.

The hosted-premium model lane went live 2026-08-14. The full model strategy is in GLOBAL-026.

Surfaces at a glance

SurfaceStatusWhere
HTTP API (POST /v1/ask, POST /v1/run, POST /v1/insert)✓ shippedapps/api/src/ask/**
<nlq-data> + <nlq-action> elements✓ shipped (v0.1)packages/elements/**
@nlqdb/sdk (TypeScript)✓ shipped (incl. runSql + cross-tenant grant + pack-import runner verbs) — installable from npm; insert() and runSql params publish in 0.5.0packages/sdk/**
Framework wrappers (React / Next / Vue / Nuxt / Svelte / SvelteKit / Astro / Solid + Swift)~ built + CI-tested; npm / SPM publish pendingpackages/{react,next,…}/**
Chat app nlqdb.com/app✓ shippedapps/web/**
Hosted MCP server mcp.nlqdb.com/mcp✓ shipped (host auto-detect pending)apps/mcp/**, packages/mcp/**
Local stdio MCP server @nlqdb/mcp✓ shipped — npx -y @nlqdb/mcp with an sk_mcp_* keypackages/mcp/**
Droppable agent artifacts (AGENTS.md · Claude Code skill + plugin · Cursor rules · Codex config)✓ shipped — /plugin marketplace add nlqdb/nlqdb installs the server + skills in one stepapps/web/public/agent-artifacts/**
nlq CLI (Go)✓ shipped (core verbs; device-login pending)cli/**

Full integration matrix in docs/progress.md.

Packages on npm

Published to the public npm registry with build provenance (SK-CIPERM-003). Version badges are live from npm; the table itself is generated from the workspace by scripts/sync-readme-packages.mjs, so it lists exactly the packages that are un-gated ("private" removed) and nothing that isn't.

PackageVersionWhat it isSource
@nlqdb/cli[@nlqdb/cli]Shim that installs the nlq CLI binary for the host platform.packages/cli-shim
@nlqdb/mcp[@nlqdb/mcp]Analytical-memory MCP server for nlqdb — a real database your AI agent can GROUP BY / JOIN / aggregate over in natural language, not just recall.packages/mcp
@nlqdb/sdk[@nlqdb/sdk]Typed HTTP client for the nlqdb /v1 API — works in browsers, Node, Bun, Workers.packages/sdk

Roadmap

The section below is the live focus; the numbered phases after it are the hosted product's roadmap, kept until the GLOBAL-043 deletion series. Canonical plan + exit gates: docs/phase-plan.md. Legend: ✓ shipped · ~ in progress · ◯ planned.

This roadmap is yours to shape. Want something added, reprioritised, or dropped? Open a PR editing this section (and docs/phase-plan.md if it's engine-facing), or open an issue to float it first. Say why now — which of the four north-star pillars (engine quality, onboarding, UX, performance) it moves. New to the codebase? Point your coding agent at this repo and paste:

Read README.md and docs/phase-plan.md, then propose a roadmap change:add/change "<your idea>" under the right section in one line, with a"why now" naming which north-star pillar it moves. Open a PR with justthat edit — no code.

Setup, branch naming, and the CLA are in CONTRIBUTING.md.

Now — attach to the database you already run (GLOBAL-043)

One loop — observe → propose → apply → verify → revert — on your Postgres (Supabase, Neon, RDS) or Cloudflare D1. Plan, KPIs and exit gate: GLOBAL-043.

  • ~ /app/dba change ledger — every change with its inverse, newest first; Apply / Reject on each proposal
  • ~ Attach product on synthetic databases — observer, create_index proposal, apply → verify → auto-revert, the four doors (the web door, paste a Postgres string at /app/connect then Apply / Reject in /app/dba, the API door, POST /v1/attach / client.attach() with client.applyProposal() / rejectProposal(), the CLI door, nlq attach / nlq proposals / nlq apply / nlq reject, and the MCP door, nlqdb_connect_database / nlqdb_list_proposals / nlqdb_apply_proposal / nlqdb_reject_proposal; the web, API, CLI and stdio MCP (@nlqdb/mcp 0.4.0) doors are live; hosted mcp.nlqdb.com serves the MCP tools once its held deploy runs; verify runs on its own once an applied proposal's 72 h window has passed), tested in CI
  • ◯ Postgres spike — one index proposed, applied and measured (before/after p95) on a real-traffic database
  • ◯ D1 attach on the real rateme12 — the dogfood
  • ◯ The playbook — unused-index drops, bloat, retypes, partitioning, retention, placement

Phase 0 — Foundations ✓

Worker skeleton · KV + D1 + R2 bindings · Neon adapter + OTel · LLM router (free chain) · Better Auth (GitHub + Google + magic link) · /v1/ask end-to-end · events queue + drain · Stripe webhook · CI/CD + PR preview environments.

Phase 1 — On-ramp

A stranger lands on nlqdb.com, creates a DB in plain English, embeds it, and shares the link — in under 60 seconds, no card, no config.

  • ✓ Marketing site (Astro, live at nlqdb.com)
  • ✓ <nlq-data> + <nlq-action> elements (v0.1)
  • ✓ Sign-in — magic link + GitHub + Google
  • ✓ Chat surface — streaming three-part response (answer / data / trace), anonymous mode
  • ✓ Anonymous mode — 72h token, adopted onto your account on sign-in
  • ✓ Hosted db.create pipeline (table-card embeddings stubbed pending the pgvector slice)
  • ✓ API keys dashboard (/app/keys)
  • ◯ Hello-world tutorial polish

Phase 1.5 — Trust + telemetry

  • ✓ Diff preview on writes + visible SQL trace on every response
  • ✓ Demand-signal telemetry on every "not yet" path
  • ◯ Confidence floor (clarify-on-low-confidence — a guided turn, not a dead-end) — lands with quality-eval

Phase 2 — Distribution (agent + developer surfaces)

  • ✓ Hosted MCP server (mcp.nlqdb.com/mcp) — host auto-detect pending; local stdio @nlqdb/mcp is on npm, so npx -y @nlqdb/mcp with an sk_mcp_* key is a headless route in with no browser consent step (/agents now carries it; the per-host install panel is still OAuth-only). On Claude Code, /plugin marketplace add nlqdb/nlqdb installs the server + both memory skills in one step
  • ✓ CLI nlq (Go) — core verbs + raw-SQL escape hatch; device-login + chat REPL pending
  • ✓ @nlqdb/sdk — basic methods + runSql + cross-tenant grant + pack-import runner verbs; published and importable from the registry; insert() and runSql params publish in 0.5.0
  • ~ Framework wrappers + native Swift package — built + CI-tested; npm / SPM publish pending
  • ✓ Quality-eval harness (BIRD + Spider 2.0) — a CI regression alarm for the NL→SQL interface, not a KPI
  • ~ Bring-your-own-LLM dispatch — HTTP lane live; remaining surfaces in progress
  • ◯ CSV upload in chat
  • ~ Docs-site reference completeness — SDK + framework-wrapper guides, an enumerable error-code reference, and a build-time /llms.txt for agents now live; tutorial polish remains
  • ◯ Custom domains for embeds

Phase 3 — Multi-engine engine (the moat)

  • ◯ Workload analyzer → migration orchestrator
  • ◯ ClickHouse / DuckDB / Redis as additional engines
  • ◯ Dual-read verification
  • ✓ Hosted-premium model lane (demand-gated) — live 2026-08-14 (PREMIUM_METER_LIVE flipped)

Phase 4 — Beyond v1

  • ~ Bring-your-own Postgres / ClickHouse — connect path live end-to-end (POST /v1/db/connect + web UI, CLI, SDK, query dispatch); prod-gated on the BYO_SECRET_KEK secret. Supabase adds one-click OAuth connect over the read-only Management-API (no DSN to paste); prod-gated on the SUPABASE_OAUTH_CLIENT_ID / _SECRET secrets, with a graceful fall-back to paste when unset
  • ◯ SSO (SAML / OIDC), audit-log export, per-org quotas
  • ◯ EU data residency, VPC peering, SOC 2

Develop locally

bash
git clone [email protected]:nlqdb/nlqdb.git && cd nlqdbscripts/bootstrap-dev.sh   # installs everything, pulls Ollama models, seeds .envrcscripts/login-cloud.sh     # signs you into cloud providers that have a CLI flow

bootstrap-dev.sh stands up the whole toolchain in one shot — Bun, Node 20+, Go 1.25+, uv; Biome / gofumpt / golangci-lint / ruff; lefthook git hooks; the cloud CLIs (wrangler, flyctl, stripe, gh); a local Ollama so the LLM router works offline; and a .envrc with self-generated dev secrets. Details in docs/history/infrastructure-setup.md §8.

Day-to-day:

bash
bun run fix          # biome format + lint --write (most issues)bun run check:all    # biome + golangci-lint + ruff (what CI runs)bun run hooks:run    # run pre-commit hooks against staged files

End-to-end tests (manual trigger)

E2E coverage is persona-driven and manually triggered so cost stays inside the free-tier envelope — one workflow_dispatch workflow per surface:

bash
gh workflow run e2e-opencheck.yml             # web — live LLM, Neon branch, Workers previewgh workflow run e2e-cli.yml                   # Go testscript, hermeticgh workflow run e2e-sdk.yml                   # vitest + cassettes, hermeticgh workflow run e2e-mcp.yml                   # InMemoryTransport protocol tests, hermeticgh workflow run e2e-examples.yml              # Playwright across HTML/Next/Astro/Nuxt/SvelteKitgh workflow run e2e-examples.yml -f live=true # + staging for the curl + CLI shell smokes

Run the hermetic surfaces locally without GitHub:

bash
( cd tests/e2e/cli && go test ./... )( cd tests/e2e/sdk && bun install && bun run test )( cd tests/e2e/mcp && bun install && bun run test )( cd tests/e2e/examples && bun install && bun run install:browsers && bun run test )

Only execution is manual: tests/e2e/{sdk,mcp,examples} live outside the root workspace, so CI's typecheck-e2e job tscs them on every PR — the free backstop against a suite that compiles today and rots before the next dispatch.

Conventions, persona mapping, and cassette governance are in docs/features/e2e-coverage/FEATURE.md.

Docs & reference

Community & legal

License

FSL-1.1-ALv2 — Functional Source License, Apache 2.0 future license. Source-available for any non-competing use; auto-converts to Apache 2.0 two years after each release. (Pattern used by Sentry, Convex, and others.)

nlqdb™ is an unregistered trademark of the project's licensor. See TRADEMARKS.md for usage guidelines.

Source: README.md at commit 4139a21

Tools

0
This server asks you to sign in, so SourceWeft could not read its tools without an account and has not indexed them. What a connected account sees can depend on that account and its permissions.

Version history

1
  1. v0.1.1LatestSep 16, 2026

Score

75% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.