# nlqdb — analytical memory for AI agents

**Category:** 🗄️ Databases  
**Repository:** https://github.com/nlqdb/nlqdb  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/nlqdb-analytical-memory-for-ai-agents

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

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "nlqdb-analytical-memory-for-ai-agents": {
    "command": "npx",
    "args": ["-y","nlqdb-analytical-memory-for-ai-agents"]
  }
}
```

## Documentation & README

# nlqdb — analytical memory for AI agents

> *Memory your agent can query, not just recall — a real database it reaches over MCP.*

Connect nlqdb to Claude, Cursor, Codex, or any MCP host. Your agent writes
typed rows as it learns, then asks questions in plain English — `GROUP BY`,
`JOIN`, aggregate over what it remembered. A vector store returns the top-k
similar chunks; nlqdb runs the query that a similarity index structurally can't.
The LLM never emits SQL: it returns a typed plan, our compiler emits the
parameterised statement, and you see the exact SQL every time.

**It's also a natural-language database for any app.** 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, [**give your agent memory**](https://docs.nlqdb.com/agent-memory/)
with one browser-OAuth approval; headless hosts skip the browser with
`npx -y @nlqdb/mcp` (`0.1.1`) and an `sk_mcp_*` MCP key
([MCP setup](https://docs.nlqdb.com/mcp/)). `@nlqdb/sdk` (`0.3.0`) and
`@nlqdb/mcp` (`0.1.1`) are both published and importable from npm.

The 60-second walkthrough — plain HTML, CLI, and ten framework wrappers —
lives at [`docs.nlqdb.com`](https://docs.nlqdb.com). Start with the
[HTML tutorial](https://docs.nlqdb.com/tutorials/html/) or the
[CLI tutorial](https://docs.nlqdb.com/tutorials/cli/).

You don't generate an API key separately: describe your database at
[nlqdb.com](https://nlqdb.com/?utm_source=github), and the chat hands you a
`<nlq-data>` snippet with the key already inlined.

## Examples

[`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`](./docs/decisions/GLOBAL-025-north-star.md)):

- **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, refuse rather than guess when confidence is low.
- **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](./LICENSE): 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.

Paid plans aren't live yet. The full model strategy is in
[`GLOBAL-026`](./docs/decisions/GLOBAL-026-llm-strategy-byollm-hosted-premium.md).

## Surfaces at a glance

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

Full integration matrix in [`docs/progress.md`](./docs/progress.md).

## Packages on npm

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

<!-- BEGIN:packages -->
| Package | Version | What it is | Source |
|---|---|---|---|
| [`@nlqdb/cli`](https://www.npmjs.com/package/@nlqdb/cli) | [![@nlqdb/cli](https://img.shields.io/npm/v/@nlqdb/cli?label=npm&color=cb3837)](https://www.npmjs.com/package/@nlqdb/cli) | Shim that installs the nlq CLI binary for the host platform. | [`packages/cli-shim`](./packages/cli-shim) |
| [`@nlqdb/mcp`](https://www.npmjs.com/package/@nlqdb/mcp) | [![@nlqdb/mcp](https://img.shields.io/npm/v/@nlqdb/mcp?label=npm&color=cb3837)](https://www.npmjs.com/package/@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`](./packages/mcp) |
| [`@nlqdb/sdk`](https://www.npmjs.com/package/@nlqdb/sdk) | [![@nlqdb/sdk](https://img.shields.io/npm/v/@nlqdb/sdk?label=npm&color=cb3837)](https://www.npmjs.com/package/@nlqdb/sdk) | Typed HTTP client for the nlqdb /v1 API — works in browsers, Node, Bun, Workers. | [`packages/sdk`](./packages/sdk) |
<!-- END:packages -->

## Roadmap

The two sections below are the **live focus**; the numbered phases after
them are the engine roadmap. Canonical plan + exit gates:
[`docs/phase-plan.md`](./docs/phase-plan.md). Legend:
**✓ shipped · ~ in progress · ◯ planned**.

### Now — analytical agent memory (the wedge)

Memory your agent can `GROUP BY`: real Postgres tables per memory type,
plain-English analytics over what it remembered — not top-k recall.

- ✓ `agent_memory_v1` preset — entities / facts / episodes, one command,
  live for every account
- ✓ `nlqdb_remember` — deterministic write path (MCP tool + API + SDK + CLI)
- ✓ Per-agent / per-end-user / per-thread isolation — hard RLS gates,
  fail-closed
- ~ TTL retention — sweep built; cron wiring pending
- ✓ `/agents` landing + honest competitor capability matrix
- ✓ Claude Code plugin — `/plugin marketplace add nlqdb/nlqdb` installs the
  server + both memory skills in one step
- ~ **Dogfood gate** — nlqdb's own ops running on nlqdb memory through the
  public MCP surface; the public launch fires when its five criteria are
  green
- ◯ Public memory dashboard on `/agents`
- ◯ One-click repo→memory import (paste a GitHub URL)
- ◯ Goal packs — per-niche memory recipes (support-bot resolution ledger,
  research-agent source ledger, …)

### Next — the expert-knowledge marketplace ("Become AI")

Non-technical professionals turn their expertise into structured,
queryable knowledge that AI agents pay to use. Decisions locked, built in
parallel with the wedge
([`docs/features/expert-knowledge-platform/`](./docs/features/expert-knowledge-platform/FEATURE.md)).

- ◯ Interview authoring — answer questions about your craft, get queryable
  rows (pilot: language tutor)
- ~ Cross-tenant read grants — mint/list/revoke control plane live;
  fail-closed read enforcement + per-query metering pending
- ◯ One catalog — free packs + paid expert knowledge DBs
- ~ Trust hardening — buyer queries schema-only end-to-end: knowledge-DB
  asks now skip narration by default (returned rows never reach an LLM);
  granted-path skip + no-training interview-provider pin pending

### 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 (refuse-on-low-confidence) — 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@0.1.1` 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 verbs;
  published and importable from the registry (`0.3.0`)
- ~ Framework wrappers + native Swift package — built + CI-tested; npm /
  SPM publish pending
- ✓ Quality-eval harness (BIRD + Spider 2.0, manual on-demand) — the
  free-vs-frontier accuracy delta is the headline 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)

### 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
- ◯ SSO (SAML / OIDC), audit-log export, per-org quotas
- ◯ EU data residency, VPC peering, SOC 2

## Develop locally

```bash
git clone git@github.com:nlqdb/nlqdb.git && cd nlqdb
scripts/bootstrap-dev.sh   # installs everything, pulls Ollama models, seeds .envrc
scripts/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`](./docs/history/infrastructure-setup.md#8-dev-toolchain).

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 preview
gh workflow run e2e-cli.yml                   # Go testscript, hermetic
gh workflow run e2e-sdk.yml                   # vitest + cassettes, hermetic
gh workflow run e2e-mcp.yml                   # InMemoryTransport protocol tests, hermetic
gh workflow run e2e-examples.yml              # Playwright across HTML/Next/Astro/Nuxt/SvelteKit
gh 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 `tsc`s 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/features/e2e-coverage/FEATURE.md).

## Docs & reference

- [`docs/architecture.md`](./docs/architecture.md) — system design (auth,
  pricing, the $0 stack, model selection, hosted db.create, hello-world).
- [`docs/phase-plan.md`](./docs/phase-plan.md) — canonical phase plan and
  exit gates.
- [`docs/decisions.md`](./docs/decisions.md) — cross-cutting `GLOBAL-NNN`
  decisions; per-feature records live under
  [`docs/features/`](./docs/features).
- [`docs/performance.md`](./docs/performance.md) — SLOs, latency budgets,
  span/metric catalog.
- [`docs/competitors.md`](./docs/competitors.md) — competitive landscape.

## Community & legal

- [CONTRIBUTING.md](./CONTRIBUTING.md) — dev setup, branch naming, commits, CLA flow.
- [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) — Contributor Covenant 2.1. Reports to `conduct@nlqdb.com`.
- [SECURITY.md](./SECURITY.md) — vulnerability disclosure (`security@nlqdb.com`). 90-day fix target.
- [SUPPORT.md](./SUPPORT.md) — where to ask questions and what we don't (yet) offer.
- [CLA.md](./CLA.md) — Contributor License Agreement, signed once via the bot on your first PR.
- [TRADEMARKS.md](./TRADEMARKS.md) — what you can and can't do with the nlqdb name and logo.
- [SUBPROCESSORS.md](./SUBPROCESSORS.md) — third-party services that may process personal data on our behalf.
- [IMPRESSUM.md](./IMPRESSUM.md) — Swiss UWG-mandated operator disclosures.
- Privacy policy and terms of service: [nlqdb.com/privacy](https://nlqdb.com/privacy) · [nlqdb.com/terms](https://nlqdb.com/terms).

## License

[FSL-1.1-ALv2](./LICENSE) — 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](./TRADEMARKS.md) for usage guidelines.