@hydradb/mcp 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,167 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.0] - 2026-08-14
+
+### ⚠️ Migration required if you call the old tool names
+
+The seven deprecated `hydra_db_*` tool aliases are **no longer registered by
+default**. If your `mcp.json` still calls them, add one environment variable:
+
+```json
+"env": { "HYDRADB_MCP_LEGACY_TOOLS": "1" }
+```
+
+Everything else in this release is backward compatible. This is called out first
+because a minor version bump under-signals it: the change is breaking for anyone
+who has not migrated to the canonical names.
+
+The reason is not only the ~3,500 tokens per conversation the alias manifest
+costs (44% of it). The alias names are systematically better literal matches for
+how users phrase requests than the canonical names — "search my memory" matches
+`hydra_db_search` exactly while `hydradb_query` needs a synonym step — and
+picking one costs real capability, since `hydra_db_ingest_conversation` cannot
+set `kind`, `overwrite`, `title`, `infer` or `is_markdown`.
+
+Migration table:
+
+| Deprecated | Use instead |
+|---|---|
+| `hydra_db_search` | `hydradb_query` |
+| `hydra_db_store`, `hydra_db_ingest_conversation` | `hydradb_ingest` |
+| `hydra_db_list_memories`, `hydra_db_list_sources` | `hydradb_list` |
+| `hydra_db_fetch_content` | `hydradb_inspect` |
+| `hydra_db_delete_memory` | `hydradb_delete` |
+
+### Other breaking changes
+
+- `kind` is now **required** on `hydradb_list`. It previously defaulted to
+  `memory`, so `hydradb_list({})` returned memories only and read as the complete
+  inventory — a caller asking "what does Hydra DB have?" never saw the knowledge
+  corpus that `hydradb_query` searches by default.
+- `hydradb_query` now returns a single context block instead of a summary
+  followed by full context. Every chunk body was previously sent twice.
+- `hydradb_query` defaults to `detail: "compact"`, which trims each chunk body to
+  ~600 characters and omits surrounding-context blocks. Pass `detail: "full"` for
+  the previous rendering.
+
+### Added
+
+- **`hydradb_status`** — check whether ingested sources have finished indexing.
+  Ingestion is asynchronous, so a query issued immediately after a save can
+  legitimately return nothing; this distinguishes "still indexing" from "the save
+  failed".
+- **Pagination** on `hydradb_list` (`page`, `page_size`), with the response
+  stating how much of the corpus it covered.
+- **`kind` on `hydradb_ingest`** — knowledge can now be created, not just
+  searched, listed, inspected and deleted.
+- **Bulk delete** — `hydradb_delete` accepts `ids`, reporting partial removals
+  as partial.
+- **New query parameters**: `source_ids` (search inside specific documents),
+  `metadata_filters`, `num_related_chunks`, `operator`, `mode: "auto"`,
+  `detail`.
+- **New ingest parameters**: `metadata`, `observation_date`, `overwrite`.
+- **`offset`/`limit`/`expiry_seconds`** on `hydradb_inspect`.
+- **`structuredContent`** on `hydradb_list`, `hydradb_ingest` and
+  `hydradb_delete`, alongside the existing text.
+- **Lifecycle handling** — SIGINT/SIGTERM drain in-flight tool calls before
+  closing; unhandled rejections and uncaught exceptions are logged and exit
+  non-zero.
+- **New environment variables**: `HYDRADB_TIMEOUT_SECONDS` (default 30),
+  `HYDRADB_MAX_RETRIES` (default 2), `HYDRADB_MCP_LEGACY_TOOLS` (default off).
+
+### Fixed
+
+Most of these returned a success-shaped result while losing or inventing data,
+so neither the caller nor the user learned anything had gone wrong.
+
+- **Nothing ever emitted an ID.** Query results carried no value that
+  `hydradb_inspect` or `hydradb_delete` would accept, and ingest returned a
+  preview of the caller's own text instead of the id the server assigned. Recall
+  and follow-up could not compose, and correcting a stored memory was
+  unreachable in both directions.
+- **A delete that removed nothing reported "not found or already deleted"** — a
+  cause never observed, and the reassuring one. A caller that guessed an id read
+  it as confirmation that the user's data was gone.
+- **The memory listing presented page one as the entire store.** With 4,000
+  memories stored, it answered "50 memories:" and page 2 was unreachable through
+  the MCP entirely. The source listing printed the corpus-wide total above a
+  single page.
+- **Per-item ingest failures were discarded.** The server reports which item
+  failed and why; the tool reported bare counts, so the only recovery was to
+  re-ingest everything — which, since a reused `source_id` replaces, could
+  destroy the item that had succeeded.
+- **Generated conversation ids collided.** `mcp-conversation-${Date.now()}` has
+  millisecond resolution, and with `upsert` hardcoded on, a collision silently
+  replaced the earlier conversation and reported success.
+- **`hydradb_list` ignored `source_ids` for memories** — accepted, validated, and
+  dropped in silence.
+- **Raw JSON envelopes reached the prompt.** When ingest stored the serialised
+  source record, the renderer emitted ids and tenant identifiers where the
+  content should have been.
+- **Graph relations went missing.** `source_chunk_ids` — the primary
+  chunk-to-relation mapping — was dropped by the response adapter, so relations
+  linked only that way were never rendered.
+- **`mode: "url"` could not work.** `presignedUrl` was never read, so the one
+  mode whose purpose is a download link returned "(no text content)".
+- **`hydradb_inspect` could end a session.** Binary content was inlined as
+  base64, so a 1 MB scanned PDF became roughly 350k tokens in one call. Binary is
+  now never inlined, and text output is bounded.
+- **Error bodies were unbounded and unfiltered.** A CDN or proxy error page
+  reached the caller whole. Now structured-first, capped, and scrubbed of
+  credential-shaped material.
+- **No timeout was configured**, so a failing endpoint could occupy a caller for
+  ~3 minutes; and `extra.signal` was never forwarded, so a cancelled tool call
+  left the request in flight.
+- **Failures were inconsistently flagged.** A server-*refused* delete and a
+  failed inspect returned success-shaped results, so a client branching on
+  `isError` misread them.
+- **Every untitled note was titled "MCP Memory"**, and title is the only
+  per-chunk label rendered in search results.
+- **`npm test` could pass having run zero tests** on Node 18 and 20 — `/bin/sh`
+  does not expand `**`, and CI was running a different command.
+
+### Changed
+
+- Tool descriptions now say **when** to call each tool — recall before
+  answering, save what the user reveals — with worked examples. Nothing
+  previously did, which is the difference between a memory product and a
+  note-taking tool.
+- Parameter descriptions explain the decision each informs rather than restating
+  the type.
+- All four MCP behaviour hints (`readOnlyHint`, `destructiveHint`,
+  `idempotentHint`, `openWorldHint`) are declared on every tool. `destructiveHint`
+  could not previously be set at all, and the spec defaults it to *true* for
+  non-readonly tools — so `hydradb_ingest` read as destructive.
+- Overlapping chunks whose content is wholly contained in another are suppressed,
+  and extra context is deduplicated by content rather than id.
+- `max_results` now bounds what is rendered, not just what is requested.
+- The recall renderer reads SDK types directly; the snake_case mirror and its
+  adapters are gone (−112 lines).
+- Ingest input is bounded (1M characters, 500 turns).
+- `moduleResolution` is `NodeNext`, so the SDK's `exports` subpaths resolve.
+- The `lint` CI job runs an actual linter; the publish workflow smoke-tests the
+  built package and asserts the tarball contents.
+
+## [1.1.1] - 2026-07
+
+### Fixed
+
+- `hydradb_query` no longer pins `kind: "memory"`, which had made every ingested
+  knowledge source unreachable from the MCP.
+- The server reports its real version instead of a hardcoded `1.0.0`.
+
+## [1.1.0] - 2026-07
+
+### Added
+
+- Canonical HydraDB tool vocabulary (`hydradb_*`), with the previous `hydra_db_*`
+  names kept as deprecated aliases.
+
+[1.2.0]: https://github.com/hydra-db/hydradb-mcp/releases/tag/v1.2.0
+[1.1.1]: https://github.com/hydra-db/hydradb-mcp/releases/tag/v1.1.1
+[1.1.0]: https://github.com/hydra-db/hydradb-mcp/releases/tag/v1.1.0

package/README.md

@@ -4,72 +4,127 @@ MCP (Model Context Protocol) server for [Hydra DB](https://hydradb.com), the sta
 
 ## Available Tools
 
-The tool names follow the canonical HydraDB vocabulary. Every previous name still
-works as a **deprecated alias** (marked as such in its description) so existing
-`mcp.json` files keep working — but new integrations should use the canonical
-names below.
+| Tool | What it does |
+|---|---|
+| `hydradb_query` | Search memories and knowledge together, with knowledge-graph context |
+| `hydradb_ingest` | Save a note, a document, or a conversation |
+| `hydradb_list` | Enumerate one family — every memory, or every knowledge source |
+| `hydradb_inspect` | Fetch one source's full content by id |
+| `hydradb_delete` | Remove one or more items by id, irreversibly |
+| `hydradb_status` | Check whether an ingested source has finished indexing |
+
+Ids flow between these: `hydradb_query` and `hydradb_list` emit them;
+`hydradb_inspect`, `hydradb_delete` and `hydradb_status` accept them.
+
+### Deprecated aliases
+
+The previous `hydra_db_*` tool names are **no longer registered by default** as
+of 1.2.0. If your `mcp.json` still calls them, set:
 
-| Canonical tool | Deprecated alias(es) |
+```
+HYDRADB_MCP_LEGACY_TOOLS=1
+```
+
+| Deprecated alias | Use instead |
 |---|---|
-| `hydradb_query` | `hydra_db_search` |
-| `hydradb_ingest` | `hydra_db_store`, `hydra_db_ingest_conversation` |
-| `hydradb_list` | `hydra_db_list_memories`, `hydra_db_list_sources` |
-| `hydradb_inspect` | `hydra_db_fetch_content` |
-| `hydradb_delete` | `hydra_db_delete_memory` |
+| `hydra_db_search` | `hydradb_query` |
+| `hydra_db_store`, `hydra_db_ingest_conversation` | `hydradb_ingest` |
+| `hydra_db_list_memories`, `hydra_db_list_sources` | `hydradb_list` |
+| `hydra_db_fetch_content` | `hydradb_inspect` |
+| `hydra_db_delete_memory` | `hydradb_delete` |
 
 ### **hydradb_query**
 
-Search through Hydra DB memories. Returns relevant chunks with graph-enriched context including entity paths and knowledge graph relations.
+Searches **both** memories and ingested knowledge sources. Returns matching
+chunks with their source id, a relevance score, and knowledge-graph context.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `query` | string | Yes | The search query to find relevant memories |
-| `max_results` | number | No | Maximum number of memory chunks to return (1-50, default: 10) |
-| `mode` | string | No | Recall mode: `fast` for quick semantic search, `thinking` for deeper personalised recall with graph traversal (default: `thinking`) |
-| `graph_context` | boolean | No | Whether to include knowledge graph relations in results (default: true) |
+| `query` | string | Yes | What you want to know, as a question or topic |
+| `kind` | string | No | `memory`, `knowledge`, or `all` (default: `all`) |
+| `max_results` | number | No | Maximum chunks to return (1-50, default: 10) |
+| `mode` | string | No | `fast`, `thinking` (default), or `auto` |
+| `detail` | string | No | `compact` (default) trims each chunk; `full` returns them whole |
+| `graph_context` | boolean | No | Include knowledge-graph relations (default: true) |
+| `operator` | string | No | `or` (default), `and`, or `phrase` for exact strings |
+| `source_ids` | array | No | Restrict the search to these sources |
+| `metadata_filters` | object | No | Exact-match filters over stored metadata |
+| `num_related_chunks` | number | No | Adjacent chunks to attach per match (0-5, default: 0) |
 
 ### **hydradb_ingest**
 
-Save information to Hydra DB memory. Hydra DB automatically extracts insights, preferences, and builds a knowledge graph from the stored content. Provide `text` to store a note/document, or `turns` to ingest a conversation.
+Saves information so it outlives the session. Provide **exactly one** of `text`
+or `turns`.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `text` | string | No\* | The information to store in memory |
-| `title` | string | No | Title for the memory entry (default: `MCP Memory`) |
-| `source_id` | string | No | Source identifier to group related memories together (e.g. session ID) |
-| `infer` | boolean | No | Whether Hydra DB should extract insights and build knowledge graph (default: true) |
-| `is_markdown` | boolean | No | Whether the text is in markdown format (default: false) |
-| `turns` | array | No\* | Conversation turns (each with a `user` and `assistant` field) to ingest instead of `text` |
-| `user_name` | string | No | Name of the user for personalisation, used with `turns` (default: `User`) |
-
-\* Provide exactly one of `text` or `turns`.
+| `text` | string | No\* | A note, fact, decision, or document body |
+| `turns` | array | No\* | Conversation turns, each with `user` and `assistant` |
+| `kind` | string | No | `memory` (default) or `knowledge` for a document |
+| `title` | string | No | Label shown in later search results — always set it |
+| `source_id` | string | No | Identifier for this entry. **Reusing one REPLACES what is stored under it** |
+| `overwrite` | boolean | No | Allow that replacement (default: true) |
+| `infer` | boolean | No | Extract insights and graph entities (default: true) |
+| `is_markdown` | boolean | No | Chunk on markdown structure (default: false) |
+| `metadata` | object | No | Key/value metadata, matchable later via `metadata_filters` |
+| `observation_date` | string | No | When the fact was true (RFC3339), vs when it was stored |
+| `user_name` | string | No | What to call the user, used with `turns` (default: `User`) |
+
+\* Passing both is an error; passing neither is an error.
+
+Ingestion is **asynchronous** — content is not searchable the instant it is
+saved. Use `hydradb_status` to confirm.
 
 ### **hydradb_list**
 
-List stored memories or ingested knowledge sources in Hydra DB.
+Enumerates one family at a time. These are separate corpora: listing memories
+tells you nothing about which knowledge sources exist.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `kind` | string | No | Which family to list: `memory` or `knowledge` (default: `memory`) |
-| `source_ids` | array | No | For `knowledge`, an array of specific source IDs to filter by. If omitted, lists all |
+| `kind` | string | **Yes** | `memory` or `knowledge` |
+| `ids` | array | No | Restrict to these ids |
+| `source_ids` | array | No | Deprecated alias for `ids` |
+| `page` | number | No | Page to return, 1-indexed (default: 1) |
+| `page_size` | number | No | Items per page (1-100) |
+
+The response reports how many of the total it showed and how to reach the rest.
 
 ### **hydradb_inspect**
 
-Fetch the full content of a specific source by its source ID.
+Fetches one source's full content by id.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `source_id` | string | Yes | The source ID to fetch content for |
-| `mode` | string | No | Fetch mode: `content` for text, `url` for presigned URL, `both` for both (default: `content`) |
+| `id` | string | Yes | The source id, from `hydradb_query` or `hydradb_list` |
+| `source_id` | string | No | Deprecated alias for `id` |
+| `mode` | string | No | `content` (default), `url` for a download link, or `both` |
+| `offset` | number | No | Character offset to read from (default: 0) |
+| `limit` | number | No | Maximum characters to return (max 20000) |
+| `expiry_seconds` | number | No | How long a `url` link stays valid |
+
+Long sources come back in slices, and binary sources are never inlined — you get
+their type and size, and `mode: "url"` returns a download link.
 
 ### **hydradb_delete**
 
-Delete a memory or knowledge source from Hydra DB by its ID. This action is irreversible.
+Removes items by id. Irreversible.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `ids` | array | No\* | The ids to delete — accepts several at once |
+| `id` | string | No\* | A single id |
+| `kind` | string | No | `memory` (default) or `knowledge` |
+
+\* Provide one of them.
+
+### **hydradb_status**
+
+Checks whether ingested sources have finished indexing.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `id` | string | Yes | The ID of the item to delete |
-| `kind` | string | No | Which family the ID belongs to: `memory` or `knowledge` (default: `memory`) |
+| `ids` | array | Yes | The source ids to check |
 
 ## Configuration
 
@@ -87,6 +142,9 @@ Delete a memory or knowledge source from Hydra DB by its ID. This action is irre
 | `HYDRADB_COLLECTION` | Collection (sub-tenant) for partitioning | `hydra-db-mcp`        |
 | `HYDRADB_BASE_URL`   | Base URL override                    | `https://api.hydradb.com` |
 | `HYDRADB_LOG_LEVEL`  | Log level: DEBUG, INFO, WARN, ERROR  | `ERROR`                   |
+| `HYDRADB_TIMEOUT_SECONDS` | Per-attempt request timeout     | `30`                      |
+| `HYDRADB_MAX_RETRIES` | Retries per request (0 disables)    | `2`                       |
+| `HYDRADB_MCP_LEGACY_TOOLS` | Register the deprecated `hydra_db_*` tools | *off* |
 
 The legacy `HYDRA_DB_*` names — `HYDRA_DB_API_KEY`, `HYDRA_DB_TENANT_ID`,
 `HYDRA_DB_SUB_TENANT_ID`, `HYDRA_DB_BASE_URL`, `HYDRA_DB_LOG_LEVEL` — remain

package/dist/adapters.d.ts

@@ -1,29 +1,39 @@
 /**
- * Adapters from the SDK's (camelCase) response payloads back into the legacy
- * snake_case shapes this server already renders.
+ * Adapters over responses the SDK does not fully type.
  *
- * These live in the MCP layer — NOT the portable wrapper — because they exist
- * only to keep `src/context.ts` (the high-value, byte-identical recall
- * renderer) and the existing tool output strings unchanged across the v1 → SDK
- * migration. The wrapper returns SDK-native `.data`; the server adapts it here.
- *
- * Note: with `skipValidation`, the SDK transforms known fields to camelCase but
- * leaves the untyped triplet innards (`relation`/`source`/`target`) as raw
- * snake_case — which is exactly what `formatTriplet` reads — so triplets pass
- * through untouched.
+ * The recall adapters that used to live here are gone: `src/context.ts` now
+ * reads the SDK payload directly, so the snake_case mirror they translated into
+ * no longer exists. What remains is the listing layer, which is a different
+ * thing entirely — see `toMemoryList` — plus the ingest result, which is read
+ * for its per-item errors.
  */
 import type { HydraDB as SDK } from "@hydradb/sdk";
-import type { AddMemoryResponse, RecallResponse } from "./types.js";
-/** SDK retrieval result → the legacy `RecallResponse` fed to `buildRecalledContext`. */
-export declare function toRecallResponse(data: SDK.SearchV2RetrievalResult): RecallResponse;
-/** SDK ingest result → the legacy `AddMemoryResponse` (success/failed counts). */
+import type { AddMemoryResponse } from "./types.js";
 export declare function toAddMemoryResponse(data: SDK.IngestionV2SourceUploadResponse): AddMemoryResponse;
 export interface MemoryListItem {
     memory_id: string;
     memory_content: string;
 }
+/**
+ * How much of the corpus a listing actually covered.
+ *
+ * The server returns this alongside every listing and both adapters used to
+ * discard it, which is what let one page be presented as the whole store.
+ */
+export interface PageInfo {
+    /** Total rows across all pages, when the server reported one. */
+    total?: number;
+    page?: number;
+    page_size?: number;
+    total_pages?: number;
+    has_next?: boolean;
+}
+export interface MemoryList {
+    memories: MemoryListItem[];
+    page: PageInfo;
+}
 /** SDK list result → memory rows. Field names vary across v2 records, so read defensively. */
-export declare function toMemoryList(data: SDK.ListV2SourceListResponse): MemoryListItem[];
+export declare function toMemoryList(data: SDK.ListV2SourceListResponse): MemoryList;
 export interface SourceListItem {
     id: string;
     title?: string;
@@ -32,6 +42,7 @@ export interface SourceListItem {
 export interface SourceList {
     sources: SourceListItem[];
     total: number;
+    page: PageInfo;
 }
 /** SDK list result → knowledge source rows + total. */
 export declare function toSourceList(data: SDK.ListV2SourceListResponse): SourceList;

package/dist/adapters.js

@@ -1,67 +1,39 @@
 /**
- * Adapters from the SDK's (camelCase) response payloads back into the legacy
- * snake_case shapes this server already renders.
+ * Adapters over responses the SDK does not fully type.
  *
- * These live in the MCP layer — NOT the portable wrapper — because they exist
- * only to keep `src/context.ts` (the high-value, byte-identical recall
- * renderer) and the existing tool output strings unchanged across the v1 → SDK
- * migration. The wrapper returns SDK-native `.data`; the server adapts it here.
+ * The recall adapters that used to live here are gone: `src/context.ts` now
+ * reads the SDK payload directly, so the snake_case mirror they translated into
+ * no longer exists. What remains is the listing layer, which is a different
+ * thing entirely — see `toMemoryList` — plus the ingest result, which is read
+ * for its per-item errors.
+ */
+/**
+ * SDK ingest result item → `MemoryResultItem`.
  *
- * Note: with `skipValidation`, the SDK transforms known fields to camelCase but
- * leaves the untyped triplet innards (`relation`/`source`/`target`) as raw
- * snake_case — which is exactly what `formatTriplet` reads — so triplets pass
- * through untouched.
+ * `results` used to be hardcoded empty in `toAddMemoryResponse`, which discarded
+ * every per-item `status`/`error`/`errorCode`/`relationsError` the server sent.
+ * The caller was left with bare counts — "1 success, 2 failed" with no reason,
+ * no code and no way to tell WHICH item failed — so its only rational recovery
+ * was to re-ingest everything, which (a reused `source_id` replaces) can destroy
+ * the item that succeeded.
  */
-function toScoredPath(path) {
-    return {
-        // Triplet innards are already raw snake_case (untyped in the SDK schema).
-        triplets: (path.triplets ?? []),
-        relevancy_score: path.relevancyScore ?? 0,
-        combined_context: path.combinedContext ?? null,
-        group_id: path.groupId ?? null,
-    };
-}
-function toVectorChunk(chunk) {
+function toMemoryResultItem(item) {
     return {
-        chunk_uuid: chunk.chunkUuid ?? "",
-        source_id: chunk.id ?? "",
-        chunk_content: chunk.chunkContent ?? "",
-        source_title: chunk.sourceTitle,
-        source_type: chunk.sourceType,
-        source_upload_time: chunk.sourceUploadTime,
-        source_last_updated_time: chunk.sourceLastUpdatedTime,
-        relevancy_score: chunk.relevancyScore ?? null,
-        document_metadata: chunk.additionalMetadata ?? null,
-        tenant_metadata: chunk.metadata ?? null,
-        extra_context_ids: chunk.extraContextIds ?? null,
-        layout: chunk.layout ?? null,
+        source_id: item.id ?? "",
+        title: item.filename ?? null,
+        status: item.status ?? "unknown",
+        // The server sends "" rather than omitting these on success; normalise to
+        // null so callers can test presence instead of emptiness.
+        error: item.error || null,
+        error_code: item.errorCode || null,
+        relations_error: item.relationsError || null,
     };
 }
-/** SDK retrieval result → the legacy `RecallResponse` fed to `buildRecalledContext`. */
-export function toRecallResponse(data) {
-    const graph = data.graphContext;
-    const additional = {};
-    for (const [id, chunk] of Object.entries(data.additionalContext ?? {})) {
-        additional[id] = toVectorChunk(chunk);
-    }
-    return {
-        chunks: (data.chunks ?? []).map(toVectorChunk),
-        graph_context: graph
-            ? {
-                query_paths: (graph.queryPaths ?? []).map(toScoredPath),
-                chunk_relations: (graph.chunkRelations ?? []).map(toScoredPath),
-                chunk_id_to_group_ids: graph.chunkIdToGroupIds ?? {},
-            }
-            : undefined,
-        additional_context: additional,
-    };
-}
-/** SDK ingest result → the legacy `AddMemoryResponse` (success/failed counts). */
 export function toAddMemoryResponse(data) {
     return {
         success: data.success ?? false,
         message: data.message ?? "",
-        results: [],
+        results: (data.results ?? []).map(toMemoryResultItem),
         success_count: data.successCount ?? 0,
         failed_count: data.failedCount ?? 0,
     };
@@ -79,23 +51,54 @@ function asRecords(value) {
         ? value
         : undefined;
 }
+function num(record, ...keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "number")
+            return value;
+    }
+    return undefined;
+}
+/**
+ * Pagination metadata, read defensively for the same reason the rows are: the
+ * SDK types this response as `{ inner?: … }` while the live API returns at top
+ * level, and neither shape is guaranteed to carry every field.
+ */
+function toPageInfo(container, rowCount) {
+    const meta = container.pagination ?? {};
+    const total = num(container, "total") ?? num(meta, "total");
+    return {
+        total: total ?? rowCount,
+        page: num(meta, "page"),
+        page_size: num(meta, "page_size", "pageSize"),
+        total_pages: num(meta, "total_pages", "totalPages"),
+        has_next: typeof meta.has_next === "boolean"
+            ? meta.has_next
+            : typeof meta.hasNext === "boolean"
+                ? meta.hasNext
+                : undefined,
+    };
+}
 /** SDK list result → memory rows. Field names vary across v2 records, so read defensively. */
 export function toMemoryList(data) {
     // Memory listings surface at top-level `user_memories` — not under an
     // `.inner` wrapper, and not under `sources` (that is the knowledge shape).
     const d = data;
+    const container = (asRecords(d.user_memories) ? d : d.inner) ?? d;
     const records = asRecords(d.user_memories) ??
         asRecords(d.inner?.user_memories) ??
         [];
-    return records.map((record) => ({
+    const memories = records.map((record) => ({
         memory_id: str(record, "memory_id", "id", "source_id") ?? "",
         memory_content: str(record, "memory_content", "content", "text", "memory", "title") ?? "",
     }));
+    return { memories, page: toPageInfo(container, memories.length) };
 }
 /** SDK list result → knowledge source rows + total. */
 export function toSourceList(data) {
     // Knowledge listings surface at top-level `sources`, not under `.inner`.
     const d = data;
+    const container = (asRecords(d.sources) ? d : d.inner) ?? d;
     const records = asRecords(d.sources) ??
         asRecords(d.inner?.sources) ??
         [];
@@ -108,6 +111,7 @@ export function toSourceList(data) {
     return {
         sources,
         total: typeof total === "number" ? total : sources.length,
+        page: toPageInfo(container, sources.length),
     };
 }
 //# sourceMappingURL=adapters.js.map

package/dist/adapters.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapters.js","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapters.js","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -12,6 +12,8 @@ export interface HydraDBConfig {
     database: string;
     collection: string;
     baseUrl?: string;
+    timeoutSeconds?: number;
+    maxRetries?: number;
 }
 export type EnvSource = Record<string, string | undefined>;
 export type WarnFn = (message: string) => void;

package/dist/config.js

@@ -50,6 +50,32 @@ export function resolveConfig(env = process.env, warn = defaultWarn) {
     const collection = readEnv(env, "HYDRADB_COLLECTION", "HYDRA_DB_SUB_TENANT_ID", warn) ??
         DEFAULT_COLLECTION;
     const baseUrl = readEnv(env, "HYDRADB_BASE_URL", "HYDRA_DB_BASE_URL", warn);
-    return { apiKey, database, collection, baseUrl };
+    // Included only when actually set, so the resolved config says what the
+    // environment said rather than carrying a row of undefined knobs.
+    const timeoutSeconds = positiveInt(env.HYDRADB_TIMEOUT_SECONDS);
+    const maxRetries = nonNegativeInt(env.HYDRADB_MAX_RETRIES);
+    return {
+        apiKey,
+        database,
+        collection,
+        baseUrl,
+        ...(timeoutSeconds != null ? { timeoutSeconds } : {}),
+        ...(maxRetries != null ? { maxRetries } : {}),
+    };
+}
+/**
+ * Numeric overrides are ignored rather than fatal when malformed.
+ *
+ * A typo'd timeout should not stop the server from starting — falling back to
+ * the built-in default keeps it running, and the alternative (exit 1 on a
+ * cosmetic env var) is worse than the misconfiguration.
+ */
+function positiveInt(raw) {
+    const value = Number(raw);
+    return raw != null && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+function nonNegativeInt(raw) {
+    const value = Number(raw);
+    return raw != null && Number.isInteger(value) && value >= 0 ? value : undefined;
 }
 //# sourceMappingURL=config.js.map