adityamishra-hydradb · Oct 27, 2026 · Oct 27, 2026 · Oct 27, 2026
diff --git a/api-reference/v2/endpoint/list-documents.mdx b/api-reference/v2/endpoint/list-documents.mdx
@@ -76,11 +76,11 @@
 | <Field name="page_size" type="integer" /> | Items per page, from `1` to `100`. (default=`50`) |
 | <Field name="filters" type="object" /> | Structured exact-match filters. See [Filters](#filters). (default=`null`) |
 | <Field name="include_fields" type="string[] or null" /> | Field projection. Only the listed fields plus `id`, `database`, `collection` are populated. Only applies to `type=knowledge`. (default=`null`, all fields) |
 | <Field name="acl" type="string[]" /> | Principals to list as (document ACLs). Omitted, `[]`, or `["*"]` disables caller-supplied filtering. Ignored for `type=memory`. For enforced connectors, the authenticated caller is used instead; see [ACL enforcement](/essentials/v2/connectors#enforce-acl). |
 
 ### Filters
 
-- `filters` accepts the three categories below. Values must match exactly, except `source_fields.title`, which matches a case-insensitive prefix.
+- `filters` accepts the three categories below. Values must match exactly, except `source_fields.title`, which matches a normalized title prefix.
 - All filter pairs combine with AND. When `ids` is non-empty, filters apply only to those IDs.
 - Range, contains, and OR operators are not supported. For OR behavior, run separate calls and combine the results in your application.
 - A `null` filter value returns `400`.
@@ -89,8 +89,8 @@
 {
  "filters": {
    "metadata": { "department": "Finance", "region": "US" },
    "additional_metadata": { "author": "Alice Smith" },
    "source_fields": { "app_provider": "slack", "title": "standup notes" }
  }
 }
 ```
@@ -99,10 +99,23 @@
 | --- | --- | --- |
 | <Field name="metadata" type="object" /> | Context item's schema-aligned `metadata` payload | Exact matches on database metadata fields. See [Metadata and Filters](/essentials/v2/metadata#7-list-sources-with-metadata-filters). |
 | <Field name="additional_metadata" type="object" /> | Context item's `additional_metadata` payload | Exact matches on free-form metadata. No schema declaration is required. |
-| <Field name="source_fields" type="object" /> | Built-in and connector fields listed below | `title` matches a case-insensitive prefix. Pair external IDs with `app_provider`. Unsupported keys return `400`. |
+| <Field name="source_fields" type="object" /> | Built-in and connector fields listed below | `title` matches a normalized prefix. Pair external IDs with `app_provider`. Unsupported keys return `400`. |
 
 Supported source fields are `type`, `title`, `description`, `url`, `timestamp`, `app_provider`, `app_kind`, `app_external_id`, and `app_parent_id`.
 
+Title normalization applies Unicode NFKC, removes invisible marks and decoration,
+lowercases the title, collapses spaces, and trims it. HydraDB also removes all
+consecutive final extensions from `md`, `markdown`, `txt`, `pdf`, `doc`, `docx`,
+`rtf`, `odt`,
+`ppt`, `pptx`, `xls`, `xlsx`, `csv`, `tsv`, `json`, `html`, or `htm`, but only
+when text remains before it. Thus `Runbook.md` has the normalized prefix
+`runbook`. `report.pdf.md` matches `report`. Unknown extensions such as `.v2`
+remain part of the title.
+
+Source IDs and titles are separate inputs. Use `ids` for source IDs and
+`filters.source_fields.title` for title prefixes. HydraDB never guesses from the
+input format.
+
 ### Field projection
 
 When you don't need every field on every row, pass `include_fields` to keep response payloads small. Only the listed fields are populated; omitted fields should be treated as unavailable in that response. `id`, `database`, and `collection` are always returned.

diff --git a/api-reference/v2/endpoint/query.mdx b/api-reference/v2/endpoint/query.mdx
@@ -12,7 +12,7 @@

 - **`type`** picks **what** to query: `"knowledge"`, `"memory"`, or `"all"` (both, merged and re-ranked together).
 - **`query_by`** picks **how** to match: `"hybrid"` (semantic similarity and keyword matching, the default) or `"text"` (keyword matching with BM25; pair with `operator`).
 - **`mode`** controls retrieval: `"fast"` for a single pass, `"thinking"` for query expansion, reranking, and explicitly linked sources, or `"auto"` to let HydraDB choose. The default is `"auto"`, which falls back to `"thinking"` when it cannot decide.

 [Recommended configurations](/api-reference/v2/endpoint/query-overview#recommended-configurations) maps common use cases to these three settings.

@@ -315,8 +315,8 @@
 | <Field name="collection" type="string or null" /> | Single collection scope. Send the collection the content was saved in. |
 | <Field name="collections" type="string[] or object" /> | Multi-collection scope. Send a list of collection IDs for equal weighting, or an object mapping collection ID to a positive relative weight (at most one decimal place, e.g. `{"finance": 1.5, "legal": 0.8}`) to bias ranking. Up to 100 collections. Do not combine with `collection`. |
 | <Field name="query" type="string" required /> | Query terms or natural-language question. Cannot be empty. Maximum 5,000 words. |
-| <Field name="titles" type="string[]" /> | Exact source titles, matched case-insensitively. Matches any listed title, then intersects with `ids` if both are sent. |
+| <Field name="titles" type="string[]" /> | Exact normalized source titles. Normalization applies Unicode NFKC, removes invisible marks and decoration, lowercases, collapses spaces, and removes consecutive final known file extensions (`md`, `markdown`, `txt`, `pdf`, `doc`, `docx`, `rtf`, `odt`, `ppt`, `pptx`, `xls`, `xlsx`, `csv`, `tsv`, `json`, `html`, or `htm`) when text remains before them. Matches any listed title, then intersects with `ids` if both are sent. Use `ids` for source IDs and `titles` for titles; HydraDB never guesses from the input format. |
 | <Field name="acl" type="string[]" /> | Caller identities used to filter document ACLs. Omitting `acl`, sending `[]`, or sending `["*"]` disables caller-supplied filtering. For enforced connectors, the authenticated caller is used instead; see [ACL enforcement](/essentials/v2/connectors#enforce-acl). |
 | <Field name="response_format" type='"structured" or "markdown"' /> | Omit for the result object with `llm_prompt`. `"structured"` leaves out the prompt string. `"markdown"` returns the prompt string directly as `data`. |
 | <Field name="type" type='"knowledge" or "memory" or "all"' /> | What to query. `"all"` runs knowledge and memory in parallel over the same scope and merges by `relevancy_score`. (default=`"knowledge"`) |
 | <Field name="query_by" type='"hybrid" or "text"' /> | Retrieval method. See [Query methods](#decision-matrix). (default=`"hybrid"`) |
@@ -365,7 +365,7 @@
    | Method | Pipeline | Best for |
    |---|---|---|
    | `"hybrid"` *(default)* | Dense vectors + BM25 keyword | General-purpose retrieval and RAG. |
    | `"text"` | BM25 only | Exact terms, compliance lookups, phrase query. Pair with `operator`. |
  </Accordion>

  <Accordion title="Modes">

diff --git a/plugins/mcp.mdx b/plugins/mcp.mdx
@@ -13,7 +13,7 @@
    <Tabs>
      <Tab title="Claude Code">
        ```bash
        claude mcp add --transport http hydradb https://mcp.hydradb.com
        ```

        Then run `/mcp`, choose **hydradb**, and click **Authenticate**.
@@ -289,7 +289,7 @@
 | ------ | ------- | -------- |
 | `Authorization` | Your HydraDB API key as a `Bearer` token (`X-HydraDB-Api-Key` is also accepted), or an OAuth access token | Yes |
 | `X-HydraDB-Database` | Database (tenant scope). API-key requests only; ignored for an OAuth token, whose scope comes from what you approved | Yes\* |
 | `X-HydraDB-Collection` | Collection (sub-tenant). If omitted, the API uses the workspace's own collection | No |
 | `X-HydraDB-Graph-Database` | Default graph database for the Cypher tools; defaults to the request's database | No |
 | `X-HydraDB-Graph-Collection` | Default graph collection; defaults to `default` | No |

@@ -352,19 +352,19 @@
  </Tab>
 </Tabs>

 The primary endpoint is `POST /` (with `/mcp` supported as an alias); `GET /health` is an unauthenticated liveness probe.

 | Variable | Description | Default |
 | -------- | ----------- | ------- |
 | `PORT` | Port to listen on | `8080` |
 | `BIND_ADDRESS` | Interface to bind (`0.0.0.0` to accept off-host) | `127.0.0.1` |
 | `ALLOWED_HOSTS` | Extra `Host` headers to accept (comma-separated); loopback always allowed | *(loopback only)* |
 | `ALLOWED_ORIGINS` | CORS origins for browser clients (comma-separated; `*` allows any) | *(none)* |
 | `TRUST_PROXY` | Express `trust proxy` when behind a reverse proxy: a hop count, `true`, or `loopback` | *off* |

 <Warning>
  The defaults are loopback-only. When you expose the server publicly, bind
  `0.0.0.0` deliberately, set `ALLOWED_HOSTS` to your hostname, list any browser
  origins in `ALLOWED_ORIGINS`, and terminate TLS in front of it. For a shared,
  public server, leave `HYDRADB_API_KEY` unset so every caller must authenticate
  with their own key rather than sharing yours.
@@ -456,7 +456,8 @@
 | `max_results` | number | No | Chunks to return, 1 to 50 (default: `10`) |
 | `mode` | string | No | `fast` for a quick single pass, `thinking` for deeper recall with query expansion and graph traversal, or `auto` to pick per query (default: `thinking`) |
 | `graph_context` | boolean | No | Include knowledge graph relations in the results (default: `true`) |
-| `titles` | string[] | No | Restrict the search to documents whose **complete** title exactly matches any value, ignoring case |
+| `source_ids` | string[] | No | Restrict the search to these source IDs. Intersects with `titles` when both are present. |
+| `titles` | string[] | No | Restrict the search to documents whose complete normalized title matches any value. See [Filtering by document title](#filtering-by-document-title). |
 | `metadata_filters` | object | No | Exact-match metadata filters as `{key: value}` |
 | `database` | string | No | Database (tenant) scope override for this request |
 | `collection` | string | No | Collection (sub-tenant) scope override for this request |
@@ -474,15 +475,27 @@
 }
 ```
 
-- **Exact, complete titles:** `last-usage` does not match `last-usage.csv`.
-- **Case-insensitive:** `q3 roadmap.md` matches `Q3 Roadmap.md`.
-- **Several titles are ORed:** Surrounding whitespace is trimmed; punctuation such
-  as commas is part of the title.
+- **One title rule:** HydraDB applies Unicode NFKC, removes invisible marks and
+  decoration, lowercases the title, collapses spaces, and trims it.
+- **Known file extensions are optional:** HydraDB removes consecutive final
+  extensions from
+  `md`, `markdown`, `txt`, `pdf`, `doc`, `docx`, `rtf`, `odt`, `ppt`, `pptx`,
+  `xls`, `xlsx`, `csv`, `tsv`, `json`, `html`, or `htm`. Text must remain before
+  the extension. `last-usage` therefore matches `last-usage.csv`. `notes.v2` stays
+  unchanged, `.md` stays unchanged, and `report.pdf.md` matches `report`.
+- **Exact after normalization:** `q3 roadmap.md` matches `Q3 Roadmap`, but a
+  normalized prefix alone does not match in this exact-title field.
+- **Several titles are ORed:** Punctuation such as commas remains part of the title.
 - **No match returns an empty result** rather than widening to the whole corpus.
 
+Source IDs and titles are separate inputs. Use `source_ids` for source IDs and
+`titles` for document names. When both are present, HydraDB intersects the two
+scopes. HydraDB never guesses from the input format.
+
 <Note>
-Because matching ignores case, two documents whose names differ only by case
-(`Report.md` and `report.md`) are treated as the same title and both are returned.
+Two documents with the same normalized title are treated as the same title and
+both are returned. For example, `Report.md`, `report.pdf`, and `report` share one
+normalized title.
 </Note>
 
 ### hydradb_ingest