Skip to main content
Glama

nlqdb — analytical memory for AI agents

Server Details

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

Ownership verified
Status
Healthy
Last Tested
Transport
Streamable HTTP
URL
Repository
nlqdb/nlqdb
GitHub Stars
1
Server Listing
nlqdb
Tool DescriptionsA

Average 4.5/5 across 6 of 6 tools scored.

Server CoherenceA
Disambiguation4/5

The toolset is mostly well-separated: connect, list/describe, remember, and read/query serve clear roles. The main overlap is between nlqdb_read and nlqdb_query, both of which are natural-language query tools; their read-only vs. general-purpose safety distinction is described, but it can still cause some selection ambiguity.

Naming Consistency4/5

All tools share the nlqdb_ prefix, lowercase snake_case, and a verb-first style, which makes the set feel coherent. The main inconsistency is that some names include an object, like list_databases or connect_database, while others like describe, read, and query do not.

Tool Count5/5

Six tools is a well-scoped size for this domain: connecting, inspecting, listing, querying, read-only querying, and writing memory each have a clear role. No tool feels redundant, and none is missing a needed counterpart at the tool-count level.

Completeness4/5

The server covers the core memory lifecycle: connect databases, describe/list them, query them, safely read them, and write typed memory rows. There are minor gaps around explicit disconnect/forget/delete affordances, though destructive queries with confirmation can cover much of that behavior.

Available Tools

6 tools
nlqdb_connect_databaseConnect an existing database so the agent can query it in EnglishAInspect

Connect an existing ClickHouse or Postgres database so the agent can query it in natural language with nlqdb_query — no migration, no schema upload. Pass the engine and a connection URL; the credential is stored sealed server-side and never echoed back. Returns the new dbId and a preview of the discovered schema.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameNoOptional display name for the connection; defaults to the database/host name.
engineYesWhich engine the existing database runs — 'clickhouse' or 'postgres'.
connection_urlYesThe full connection URL for the database, including credentials (e.g. postgres://user:pass@host:5432/db or https://host:8443?user=…). Stored sealed server-side and never echoed back.
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only provide destructiveHint=false, so the description carries the transparency burden. It adds key behavioral context: no migration or schema upload, credentials stored sealed server-side and never echoed back, and the return of a new dbId plus schema preview. This is substantive and does not contradict the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two crisp sentences that front-load the core purpose, then provide usage, security, and return information. Every phrase earns its place; no fluff or repetition of schema field names beyond necessary context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity and lack of output schema, the description covers the goal, required inputs, security behavior, and return value. It lacks explicit error-handling or network/prerequisite details, but the essential flow (connect, get dbId, query later) is clear, making it fairly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters. The description mostly reinforces existing schema details (engine and connection URL) without adding new semantic meaning. It does not explain the 'name' parameter beyond what schema provides, yielding a baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action (Connect an existing ClickHouse or Postgres database) with a clear purpose (so the agent can query it in natural language with nlqdb_query). It clearly distinguishes this tool from siblings like nlqdb_query by positioning it as the setup step that returns a dbId for later queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: use this to connect an existing database, pass engine and connection URL, and it enables subsequent nlqdb_query calls. It implies the tool should be called before querying, but it doesn't explicitly state when not to use it or name alternatives such as nlqdb_remember or nlqdb_list_databases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nlqdb_describeDescribe one memory databaseA
Read-only
Inspect

Inspect the shape of one of your agent's memory databases. Return schema metadata (slug, engine, schema name) for one database. Requires a user-scoped key (sk_live_ or sk_mcp_).

ParametersJSON Schema
NameRequiredDescriptionDefault
dbYesDatabase id or slug to describe.
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation already indicates a safe read operation, and the description adds context by specifying the exact metadata returned and the required key type. This goes beyond the annotation without contradicting it, but does not disclose potential error or edge cases.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three concise sentences, each with clear value: the operation, the return structure, and the auth prerequisite. No redundant or filler content is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema, no nested objects), the description covers all necessary aspects: purpose, return value, and prerequisites. The description fully compensates for the lack of an output schema by explicitly listing the metadata fields returned.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The single 'db' parameter is described in the schema as 'Database id or slug to describe,' and the tool description does not add any additional parameter-specific detail beyond that.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action ('Inspect the shape of one of your agent's memory databases') and specifies the return value ('schema metadata (slug, engine, schema name)'). This distinguishes it from siblings like list_databases and query, which handle listing and querying respectively.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly notes it operates on a single database, contrasting with list_databases. It also mentions the auth requirement ('Requires a user-scoped key'), though it does not explicitly name alternative tools or provide a 'when not to use' exclusion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nlqdb_list_databasesList your agent's memory databasesA
Read-only
Inspect

List the memory databases your agent can query, scoped to the authenticated user. Requires a user-scoped key (sk_live_ or sk_mcp_). Returns engine per row.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds the auth requirement (user-scoped key) and the return format ('engine per row'), which exceeds what annotations provide and helps set expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences each carry distinct value: purpose, auth requirement, and return format. The description is front-loaded with the primary action and contains no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter listing tool, the description covers all essential aspects: what is listed, scope, authentication prerequisite, and return shape. No output schema exists, so the description appropriately compensates by mentioning 'engine per row'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so schema coverage is trivially 100%. Baseline 4 applies, and the description appropriately mentions the scope and auth context without needing to explain parameter syntax.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('memory databases') with clear scoping ('scoped to the authenticated user'), making the operation unambiguous. It also distinguishes itself from siblings like query or remember, which perform different actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides useful context: the tool lists databases the agent can query and requires a user-scoped key. It does not explicitly name alternatives or when-not-to-use, but the naming and description sufficiently imply the intended use case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nlqdb_queryQuery your agent's memory in natural languageA
Destructive
Inspect

Query your agent's structured memory in natural language — a real database it can GROUP BY / JOIN / aggregate over, not just recall. Returns rows + the compiled SQL (in trace). The database is materialised on first reference — no separate create tool. Destructive plans return requires_confirm: true + a diff; re-call with confirm: true to commit.

ParametersJSON Schema
NameRequiredDescriptionDefault
qYesThe natural-language goal. Example: 'top 5 customers by revenue this year'. Name tables explicitly when you know them; avoid pronouns.
dbNoTarget database id or slug. Optional: omit to let nlqdb pick — it auto-targets your only DB (or creates one from the goal when you have none), and on multiple DBs returns ambiguous_db with candidate ids to choose from. Ignored for pk_live_ keys (already scoped to one DB).
modelNoModel preset: 'fast' pins the free built-in chain, 'best' requires a frontier model (errors model_unavailable unless the account stored a BYOLLM key or has a paid plan), omit/'auto' lets nlqdb pick.
confirmNoDestructive writes are two calls: the first (confirm absent) returns requires_confirm: true plus a diff preview; show the diff, then re-call with confirm: true to commit. Read-only queries ignore this.
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the destructiveHint annotation, the description discloses the two-step confirmation for destructive plans (requires_confirm + diff, then confirm: true), the auto-creation of the database on first reference, and the return of rows along with compiled SQL in trace. These details give the agent a clear understanding of side effects and expected output.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, each delivering unique value: purpose and capabilities, return values and auto-creation, and destructive confirmation. It is front-loaded and free of redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description adequately covers return behavior (rows + SQL trace) and critical side effects (auto-creation, destructive confirm flow). Parameter descriptions handle errors like ambiguous_db and model_unavailable. It could be slightly more explicit about result formatting, but given the tool's complexity, it is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides 100% parameter descriptions, including examples, edge cases, and enumeration. The tool description adds no further parameter semantics beyond what the schema states; even the confirm behavior is repeated verbatim from the schema. Baseline 3 is appropriate as the schema handles parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool queries the agent's structured memory in natural language, emphasizing its capability for GROUP BY/JOIN/aggregate operations. It distinguishes itself from simple recall and the sibling tools by positioning itself as a real database query interface.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for structured queries involving joins or aggregations, contrasting with 'not just recall' which hints at nlqdb_remember. It also explains the confirmation flow for destructive plans, guiding when confirm is needed. However, it does not explicitly name alternatives for listing or connecting databases, so it lacks a fully explicit when/when-not structure.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nlqdb_readRead your agent's memory in natural language (never writes)A
Read-only
Inspect

Read-only natural-language query over your agent's memory — SELECT / aggregate / JOIN over existing data. Guaranteed never to write, create, or modify: a request whose plan would change data is refused (use nlqdb_query for that), so this tool is safe to mark 'always allow' in your host. Auto-targets your only database; pass db to pick one when you have several. Returns rows + the compiled SQL in trace.

ParametersJSON Schema
NameRequiredDescriptionDefault
qYesThe natural-language question. Read-only: SELECT / aggregate / JOIN over existing data. Example: 'top 5 customers by revenue this year'. Name tables explicitly when you know them; avoid pronouns.
dbNoTarget database id or slug. Optional: omit to auto-target your only database. Unlike nlqdb_query, this tool never creates a database — with several databases and no `db` it returns ambiguous_db with candidate ids; with none it asks you to create one via nlqdb_query first.
modelNoModel preset: 'fast' pins the free built-in chain, 'best' requires a frontier model (errors model_unavailable unless the account stored a BYOLLM key or has a paid plan), omit/'auto' lets nlqdb pick.
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only mark readOnlyHint: true, but the description goes much further: it guarantees no write/create/modify, states that plan-to-change requests are refused, discloses auto-target behavior and the ambiguous_db edge case, and tells the agent it returns rows plus compiled SQL. This is rich, non-contradictory behavioral disclosure well beyond structured hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, all value-dense and front-loaded with the core purpose and safety guarantee. Each sentence delivers a distinct piece of actionable information — behavior, exception, db targeting, return format — without repetition. It is concise but not under-specified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is fully self-contained for a read-only natural-language query tool. It covers the safety contract, failure cases (ambiguous_db, no db, now database), model selection, and the exact return output (rows + compiled SQL). Given the lack of an output schema, this description effectively compensates by disclosing the return shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds meaningful semantic context: `db` can be omitted to auto-target the only database, but with several it returns candidate IDs; `model`'s 'best' presets require specific account conditions; 'unique' is the default for nlqdb to choose. This goes beyond the schema's basic parameter docs, clarifying real usage nuances.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb+resource pattern: 'Read-only natural-language query over your agent's memory — SELECT / aggregate / JOIN over existing data.' It clearly distinguishes this from sibling nlqdb_query and from a generic list/connect tool by emphasizing it never writes. The tool's intent is immediately transparent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is given: 'a request whose plan would change data is refused (use nlqdb_query for that), so this tool is safe to mark always allow.' It also explains when to pass `db` vs. auto-targeting and touches on ambiguous-database behavior. This leaves little ambiguity about when to use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nlqdb_rememberRemember something in your agent's memoryAInspect

Write a typed row into your agent's memory database — a fact to recall later, a conversation episode, or an entity (person/project/thing). Materialises directly into the agent_memory_v1 schema with no LLM in the loop, so it's deterministic. Omit db on first use and this tool will find (or provision) the agent_memory_v1 database for you and echo dbId (and db_created: true on a fresh provision) in the result — pin that id on subsequent calls. Query it back later with nlqdb_query (which can GROUP BY / aggregate over what you remembered). Set kind + tags on facts — they are the columns those aggregates group by.

ParametersJSON Schema
NameRequiredDescriptionDefault
dbNoOptional. The agent_memory_v1 database id (db_agent_memory_v1_…). Omit on first use and this tool will find (or provision) your account's memory DB automatically and return the new dbId in the result — pass that on subsequent calls. A non-memory DB is rejected with wrong_preset and the recovery is the same: omit `db` to auto-provision.
kindYesWhich memory table to write into. Prefer 'entity' for anything with a current state (a project, a person, a config) — an entity is the CURRENT SNAPSHOT and upserts on (agent+kind+name), so re-remembering refreshes it in place instead of accumulating stale rows. Use 'fact' for a statement whose truth is time-bound (a status update, an observation, an idea) — give it a ttlSeconds when it's transient. Use 'episode' for one conversation/tool turn (append-only log).
payloadYesKind-specific fields. fact: { content, kind?, tags?, source? }. episode: { role, content, tool_calls?, tokens? }. entity: { kind, canonical_name, properties? }. Write for the queries you'll ask later: fact kind + tags become GROUP BY columns — reuse a small lower_snake kind vocabulary (leaving every row on the default 'fact' makes categories unqueryable) and tag every id/topic the row touches. Entities are current snapshots: keep the state in `properties` (JSONB) and re-remember the entity to update it — an upsert on (agent, kind, canonical_name) replaces properties when provided, so re-send the whole object. Prefer updating an entity over accumulating facts about it. Supersede rather than accumulate: when a fact becomes wrong or outdated, write the corrected fact (same tags) rather than piling on — old facts fade via ttlSeconds; entities are refreshed in place. Make content one self-describing sentence, so a row reads correctly on its own in a result set.
threadIdNoOptional thread/conversation scope (facts / episodes).
endUserIdNoOptional end-user scope (facts / episodes).
ttlSecondsNoOptional TTL in seconds — sets expires_at on a fact. Expired facts stop appearing in queries (RLS filters them out) and are physically evicted opportunistically on subsequent writes, so memory forgets what it no longer needs. Set this on any fact whose relevance is time-bound (a status, an observation, a hypothesis) — a day for daily standups, a week for weekly plans, a month for quarterly context. Facts without a TTL live forever; entities never expire (update them in place instead).
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide only destructiveHint=false, so the description must cover the write behavior. It explains that writing is deterministic, materializes directly into a schema, and describes auto-provisioning of the database on first use. It also hints that facts with a TTL expire and are filtered out, and entities are upserted in place. However, it does not explicitly state that writing is not read-only beyond the annotation's implication – a small gap but overall strong transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is packed with valuable details but is somewhat lengthy. Each sentence adds meaning, though some repetition occurs (e.g., the TTL concept appears in both `payload` and `ttlSeconds` descriptions). It is front-loaded with the core purpose, making the rest readable. A bit more brevity could improve it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 6 parameters (2 required) and no output schema, the description covers all key aspects: how to start, parameter semantics, expected results (dbId, db_created), and how to query later. It lacks an explicit note on error handling beyond the wrong_preset for `db`, but overall it is sufficient for an agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, yet the description adds significant value beyond the schema. For `kind`, it explains the semantics of each enum option (snapshot vs time-bound vs append-only). For `payload`, it provides detailed structure per kind and advice on query design. For `ttlSeconds`, it describes expiration behavior and usage patterns. The description transforms raw schema fields into actionable guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool writes a typed row into the agent's memory database, listing three use cases (fact, episode, entity) and distinguishes it from siblings like nlqdb_query by specifying this is the write side. It also explains the deterministic behavior without an LLM in the loop.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance on when to omit `db` for first use, how to pin the returned `dbId`, references sibling tool nlqdb_query for reading back the data, and gives detailed instructions on choosing among kind values and whether to use entity vs fact. It also advises on superseding old facts rather than accumulating stale rows.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Frequently Asked Questions

Discussions

No comments yet. Be the first to start the discussion!

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    B
    maintenance
    An MCP server that gives AI agents direct read-only access to PostgreSQL databases, enabling natural language analytics through tools for schema exploration, querying, trend analysis, and data quality checks.
    11
    5
    MIT
  • A
    license
    A
    quality
    B
    maintenance
    A personal memory MCP server that ingests AI agent conversation logs from multiple platforms into a searchable PostgreSQL+pgvector database, enabling cross-session recall of past reasoning and decisions.
    6
    MIT
  • A
    license
    Not graded
    quality
    A
    maintenance
    Agent memory as a PostgreSQL extension: hybrid HNSW+BM25 recall, write-time provenance gates, and outcome-weighted confidence. The MCP server exposes ingest and recall tools over stdio for Claude Code, Codex CLI, and Gemini CLI.
    6
    Apache 2.0
Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.