@nexusm/sdk 3.0.0 → 4.0.0

package/README.md

@@ -165,10 +165,13 @@ const graph = await nexus.knowledge.query({
 
 | Method | Description |
 |--------|-------------|
-| `createEntity(data)` | Create a new entity in the knowledge graph |
-| `listEntities(params?)` | List entities with optional filtering |
+| `listEntities(params)` | List entities for a user (`user_id` required) |
 | `query(request)` | BFS graph traversal from a named entity |
-| `extract(request)` | Extract entities and relationships from text |
+| `extract(request)` | Extract entities and relationships from text (also how entities are created) |
+
+> v3.0.0: `createEntity()` was removed — the backend has no
+> `POST /knowledge/entities` route (the SDK method 404'd at runtime).
+> Entities are created via `extract()`.
 
 ### Activity Service
 
@@ -202,14 +205,14 @@ Tenant profile and usage management. Identity is derived from the API key.
 const tenant = await nexus.tenants.me();
 console.log(tenant.name, tenant.tier);
 
-const usage = await nexus.tenants.usage();
-console.log('Memories:', usage.memories_count);
+const usage = await nexus.tenants.usage('week');
+console.log(`API calls: ${usage.api_calls} (${usage.success_rate}% ok)`);
 ```
 
 | Method | Description |
 |--------|-------------|
-| `me()` | Retrieve the current tenant profile |
-| `usage()` | Retrieve resource usage statistics |
+| `me()` | Retrieve the current tenant profile (flat counts + `quota_remaining`) |
+| `usage(period?)` | Usage statistics for `'day'` (default) / `'week'` / `'month'` — 13-field `UsageStats` |
 
 ## Error Handling
 

package/dist/index.d.mts

@@ -802,13 +802,26 @@ declare class ContextService extends BaseService {
 type MemoryType = 'episodic' | 'semantic' | 'procedural';
 /**
  * A memory record stored in the Nexus platform.
- * Represents a single piece of user knowledge managed by Mem0.
+ *
+ * Mirrors backend `MemoryResponse` (schemas/memory.py, 14 fields).
+ *
+ * v4.0.0 (memory-conversation-contract-reconciliation): adds the
+ * compound-identifier trio (`memory_id` / `tenant_id` / `agent_id`) and the
+ * US-035 temporal-validity window (`valid_from` / `valid_until` /
+ * `valid_until_source`) — all emitted by the backend but previously missing
+ * from this type (readers got `undefined`).
  */
 interface Memory {
+    /** Compound memory ID ("tenant::user::uuid") — needed for multi-tenant ops */
+    memory_id: string;
     /** Unique memory identifier (UUID) */
     id: string;
+    /** Tenant identifier */
+    tenant_id: string;
     /** User ID that owns this memory */
     user_id: string;
+    /** Originating agent (null when not agent-written) */
+    agent_id?: string | null;
     /** Memory content text */
     content: string;
     /** Classification of the memory */
@@ -816,7 +829,13 @@ interface Memory {
     /** Additional metadata key-value pairs */
     metadata?: Record<string, unknown>;
     /** Relevance score (present in search results) */
-    score?: number;
+    score?: number | null;
+    /** Start of the temporal validity window (inclusive; server-managed) */
+    valid_from?: string | null;
+    /** End of the temporal validity window (exclusive; null = permanent) */
+    valid_until?: string | null;
+    /** Provenance of valid_until (permanent / extracted / sdk_provided / ...) */
+    valid_until_source?: string | null;
     /** Timestamp when the memory was created (ISO 8601) */
     created_at: string;
     /** Timestamp when the memory was last updated (ISO 8601) */
@@ -1097,10 +1116,17 @@ declare class MemoryService extends BaseService {
 /**
  * @nexusm/sdk - Conversation Types
  *
- * Type definitions for the Conversation Service powered by Zep OSS.
+ * Type definitions for the Conversation Service.
  * Manages conversation history, messages, and auto-generated summaries.
  *
- * Based on Nexus API v2.0 OpenAPI specification.
+ * v4.0.0 BREAKING (memory-conversation-contract-reconciliation, 2026-06-11):
+ * canonical = backend Pydantic response models (`schemas/conversation.py`)
+ * serialized wire names. The previous shapes were drifted: nested
+ * `{data, pagination}` containers never existed on the wire (backend lists
+ * are FLAT), the conversation identifier wire key is `conversation_id` (the
+ * old `session_id` was a phantom), `ConversationDetail` described a response
+ * no endpoint emits, and `ConversationSummary` declared phantom
+ * `key_points`/`generated_at` while missing the real count fields.
  */
 /** Valid message roles in a conversation */
 type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
@@ -1108,17 +1134,29 @@ type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
 type ConversationStatus = 'active' | 'archived' | 'deleted';
 /**
  * A conversation session between a user and an AI agent.
- * Managed by Zep OSS for temporal graph and auto-summary.
+ *
+ * GET /conversations/{conversation_id} — mirrors backend
+ * `ConversationResponse` (11 fields, flat).
+ *
+ * v4.0.0 BREAKING: `session_id` → `conversation_id` (the real wire key —
+ * backend field `compound_session_id` serializes via alias); adds
+ * `tenant_id` / `agent_id` / `status` (previously missing).
  */
 interface Conversation {
     /** Unique conversation identifier (UUID) */
     id: string;
+    /** Compound session ID ("tenant::user::session") — the wire key */
+    conversation_id: string;
+    /** Tenant identifier */
+    tenant_id: string;
     /** User ID that owns this conversation */
     user_id: string;
-    /** Session identifier for the conversation */
-    session_id?: string;
+    /** Originating agent (null when not agent-created) */
+    agent_id?: string | null;
+    /** Conversation status (e.g. active / archived) */
+    status: string;
     /** Auto-generated conversation summary */
-    summary?: string;
+    summary?: string | null;
     /** Total number of messages in the conversation */
     message_count: number;
     /** Additional metadata key-value pairs */
@@ -1141,20 +1179,28 @@ interface ConversationCreate {
     /** Additional metadata key-value pairs */
     metadata?: Record<string, unknown>;
 }
-/**
- * Conversation with its messages included.
- * Returned when include_messages=true.
- */
-interface ConversationDetail extends Conversation {
-    /** Messages in the conversation */
-    messages: Message[];
-}
 /**
  * A single message within a conversation.
+ *
+ * Mirrors backend `MessageResponse` (11 fields).
+ *
+ * v4.0.0 BREAKING: adds `message_id` / `conversation_id` /
+ * `conversation_compound_id` / `tenant_id` / `user_id` correlation fields
+ * (previously missing from the SDK type while present on the wire).
  */
 interface Message {
     /** Unique message identifier (UUID) */
     id: string;
+    /** Compound message ID */
+    message_id: string;
+    /** Owning conversation UUID (NOT the compound id — see conversation_compound_id) */
+    conversation_id: string;
+    /** Owning conversation compound ID ("tenant::user::session") */
+    conversation_compound_id: string;
+    /** Tenant identifier */
+    tenant_id: string;
+    /** User identifier */
+    user_id: string;
     /** Message role (user, assistant, system, or tool) */
     role: MessageRole;
     /** Message content text */
@@ -1162,7 +1208,7 @@ interface Message {
     /** Additional metadata key-value pairs */
     metadata?: Record<string, unknown>;
     /** Message sequence number within the conversation */
-    sequence?: number;
+    sequence: number;
     /** Timestamp when the message was created (ISO 8601) */
     created_at: string;
 }
@@ -1182,49 +1228,67 @@ interface MessageCreate {
 /**
  * Paginated list of conversations.
  *
- * GET /conversations?user_id=...
+ * GET /conversations?user_id=... — mirrors backend
+ * `ConversationListResponse` (FLAT container).
+ *
+ * v4.0.0 BREAKING: was nested `{data, pagination:{total, limit, offset,
+ * has_more}}` — that shape never existed on the wire.
  */
 interface ConversationList {
     /** Array of conversation records */
-    data: Conversation[];
-    /** Pagination metadata */
-    pagination: {
-        /** Total number of conversations */
-        total: number;
-        /** Current page size limit */
-        limit: number;
-        /** Current offset */
-        offset: number;
-        /** Whether more results exist */
-        has_more: boolean;
-    };
+    conversations: Conversation[];
+    /** Total number of conversations */
+    total_count: number;
+    /** Current page size limit */
+    limit: number;
+    /** Current offset */
+    offset: number;
+    /** Whether more results exist */
+    has_next: boolean;
 }
 /**
  * Paginated list of messages within a conversation.
  *
- * GET /conversations/:conversation_id/messages
+ * GET /conversations/:conversation_id/messages — mirrors backend
+ * `MessageListResponse` (FLAT container).
+ *
+ * v4.0.0 BREAKING: was `{data, has_more}` — missing
+ * total_count/limit/offset and using a phantom container key.
  */
 interface MessageList {
     /** Array of message records */
-    data: Message[];
-    /** Whether more messages exist before the current page */
-    has_more: boolean;
+    messages: Message[];
+    /** Total number of messages */
+    total_count: number;
+    /** Current page size limit */
+    limit: number;
+    /** Current offset */
+    offset: number;
+    /** Whether more messages exist */
+    has_next: boolean;
 }
 /**
  * Auto-generated summary of a conversation.
- * Generated by Zep OSS temporal graph analysis.
  *
- * GET /conversations/:conversation_id/summary
+ * GET /conversations/:conversation_id/summary — mirrors backend
+ * `SummaryResponse` (5 fields).
+ *
+ * v4.0.0 BREAKING: the previous shape declared phantom `key_points[]` /
+ * `generated_at`; the backend emits message counts + `created_at`. The wire
+ * id key is `conversation_id` (unified 2026-06-11 — the endpoint previously
+ * emitted `compound_session_id`, an internal third id variant).
  */
 interface ConversationSummary {
-    /** Conversation identifier (UUID) */
+    /** Compound conversation ID (same key as Conversation.conversation_id) */
     conversation_id: string;
-    /** Generated summary text */
-    summary?: string;
-    /** Key points extracted from the conversation */
-    key_points?: string[];
-    /** Timestamp when the summary was generated (ISO 8601) */
-    generated_at: string;
+    /** Generated summary text (null until first summary) */
+    summary?: string | null;
+    /** Number of messages already folded into the summary */
+    summary_message_count: number;
+    /** Total number of messages in the conversation */
+    message_count: number;
+    /** Timestamp when the conversation was created (ISO 8601) */
+    created_at: string;
 }
 
 /**
@@ -1301,13 +1365,17 @@ declare class ConversationService extends BaseService {
      */
     list(params?: ConversationListParams, options?: RequestOptions): Promise<ConversationList>;
     /**
-     * Retrieve a conversation with its messages included.
+     * Retrieve a conversation.
+     *
+     * v4.0.0 BREAKING: returns `Conversation` — the backend response has no
+     * `messages` array (the previous `ConversationDetail` shape was a
+     * phantom). Fetch messages via {@link getMessages}.
      *
-     * @param conversationId - UUID of the conversation to retrieve.
-     * @returns Conversation detail including the full message list.
+     * @param conversationId - Compound conversation ID to retrieve.
+     * @returns The conversation record.
      * @throws {ApiError} 404 if the conversation does not exist.
      */
-    get(conversationId: string, options?: RequestOptions): Promise<ConversationDetail>;
+    get(conversationId: string, options?: RequestOptions): Promise<Conversation>;
     /**
      * Add a message to an existing conversation.
      *
@@ -1758,6 +1826,8 @@ interface TenantQuotas {
     max_memories?: number;
     /** Maximum number of conversations allowed */
     max_conversations?: number;
+    /** Maximum number of knowledge graph nodes allowed */
+    max_graph_nodes?: number;
     /** Maximum API calls per day */
     max_api_calls_per_day?: number;
     /** Forward-compatible: any additional quota dimensions */
@@ -2571,4 +2641,4 @@ declare const apiKeyCreateSchema: z.ZodObject<{
     expires_in_days?: number | undefined;
 }>;
 
-export { type Activity, type ActivityProcessingStatus, ActivityService, type ActivityStats, type ActivityStatusResponse, type ActivityStreamRequest, type ActivityStreamResponse, type ActivityType, ApiError, type ApiErrorDetail, type ApiKey, type ApiKeyCreate, type ApiKeyCreated, type ApiResponse, AuthenticationError, type CacheConfig, type CompoundId, ConfigurationError, type ContextDepth, type ContextDepthPreset, type ContextGraphEntity, type ContextLayer, type ContextRequest, type ContextRetrieveResponse, ContextService, type Conversation, type ConversationCreate, type ConversationDetail, type ConversationList, type ConversationListParams, type ConversationMessage, ConversationService, type ConversationStatus, type ConversationSummary, DEFAULT_CONFIG, DEPTH_PRESETS, type EntityListParams, type EntityListResponse, type ErrorReportRequest, type ErrorReportResponse, ErrorService, type ErrorSeverity, type ErrorType, type ExtractionRequest, type ExtractionResult, type FeedbackItemRequest, type FeedbackListItem, type FeedbackListParams, type FeedbackListResponse, type FeedbackResponse, FeedbackService, type FeedbackSubmitRequest, type GraphPath, type GraphPathEntity, type GraphPathRelationship, type GraphQueryRequest, type GraphQueryResponse, type HealthResponse, type HealthStatus, InputValidationError, type JournalEntry, type JournalResponse, type KnowledgeEntity, type KnowledgeRelationship, KnowledgeService, type Memory, type MemoryCreate, type MemoryJournalParams, type MemoryList, type MemoryListParams, type MemorySearch, type MemorySearchResult, MemoryService, type MemoryType, type MemoryUpdate, type Message, type MessageCreate, type MessageList, type MessageListParams, type MessageRole, NetworkError, NexusClient, type NexusConfig, NexusError, NotFoundError, type OfflineConfig, OfflineQueue, type PaginatedResponse, type Pagination, type ProfileMemory, type QueuedRequest, RateLimitError, type RequestOptions, type ResolvedCacheConfig, type ResolvedConfig, type ResolvedRetryConfig, type RetryConfig, type SearchResult, type ServiceStatus, type SortOrder, type Tenant, type TenantQuotas, TenantService, type TenantTier, TimeoutError, type UsageStats, ValidationError, apiKeyCreateSchema, contextRequestSchema, conversationCreateSchema, extractionRequestSchema, graphQueryRequestSchema, memoryCreateSchema, memorySearchSchema, memoryUpdateSchema, messageCreateSchema, resolveConfig };
+export { type Activity, type ActivityProcessingStatus, ActivityService, type ActivityStats, type ActivityStatusResponse, type ActivityStreamRequest, type ActivityStreamResponse, type ActivityType, ApiError, type ApiErrorDetail, type ApiKey, type ApiKeyCreate, type ApiKeyCreated, type ApiResponse, AuthenticationError, type CacheConfig, type CompoundId, ConfigurationError, type ContextDepth, type ContextDepthPreset, type ContextGraphEntity, type ContextLayer, type ContextRequest, type ContextRetrieveResponse, ContextService, type Conversation, type ConversationCreate, type ConversationList, type ConversationListParams, type ConversationMessage, ConversationService, type ConversationStatus, type ConversationSummary, DEFAULT_CONFIG, DEPTH_PRESETS, type EntityListParams, type EntityListResponse, type ErrorReportRequest, type ErrorReportResponse, ErrorService, type ErrorSeverity, type ErrorType, type ExtractionRequest, type ExtractionResult, type FeedbackItemRequest, type FeedbackListItem, type FeedbackListParams, type FeedbackListResponse, type FeedbackResponse, FeedbackService, type FeedbackSubmitRequest, type GraphPath, type GraphPathEntity, type GraphPathRelationship, type GraphQueryRequest, type GraphQueryResponse, type HealthResponse, type HealthStatus, InputValidationError, type JournalEntry, type JournalResponse, type KnowledgeEntity, type KnowledgeRelationship, KnowledgeService, type Memory, type MemoryCreate, type MemoryJournalParams, type MemoryList, type MemoryListParams, type MemorySearch, type MemorySearchResult, MemoryService, type MemoryType, type MemoryUpdate, type Message, type MessageCreate, type MessageList, type MessageListParams, type MessageRole, NetworkError, NexusClient, type NexusConfig, NexusError, NotFoundError, type OfflineConfig, OfflineQueue, type PaginatedResponse, type Pagination, type ProfileMemory, type QueuedRequest, RateLimitError, type RequestOptions, type ResolvedCacheConfig, type ResolvedConfig, type ResolvedRetryConfig, type RetryConfig, type SearchResult, type ServiceStatus, type SortOrder, type Tenant, type TenantQuotas, TenantService, type TenantTier, TimeoutError, type UsageStats, ValidationError, apiKeyCreateSchema, contextRequestSchema, conversationCreateSchema, extractionRequestSchema, graphQueryRequestSchema, memoryCreateSchema, memorySearchSchema, memoryUpdateSchema, messageCreateSchema, resolveConfig };

package/dist/index.d.ts

@@ -802,13 +802,26 @@ declare class ContextService extends BaseService {
 type MemoryType = 'episodic' | 'semantic' | 'procedural';
 /**
  * A memory record stored in the Nexus platform.
- * Represents a single piece of user knowledge managed by Mem0.
+ *
+ * Mirrors backend `MemoryResponse` (schemas/memory.py, 14 fields).
+ *
+ * v4.0.0 (memory-conversation-contract-reconciliation): adds the
+ * compound-identifier trio (`memory_id` / `tenant_id` / `agent_id`) and the
+ * US-035 temporal-validity window (`valid_from` / `valid_until` /
+ * `valid_until_source`) — all emitted by the backend but previously missing
+ * from this type (readers got `undefined`).
  */
 interface Memory {
+    /** Compound memory ID ("tenant::user::uuid") — needed for multi-tenant ops */
+    memory_id: string;
     /** Unique memory identifier (UUID) */
     id: string;
+    /** Tenant identifier */
+    tenant_id: string;
     /** User ID that owns this memory */
     user_id: string;
+    /** Originating agent (null when not agent-written) */
+    agent_id?: string | null;
     /** Memory content text */
     content: string;
     /** Classification of the memory */
@@ -816,7 +829,13 @@ interface Memory {
     /** Additional metadata key-value pairs */
     metadata?: Record<string, unknown>;
     /** Relevance score (present in search results) */
-    score?: number;
+    score?: number | null;
+    /** Start of the temporal validity window (inclusive; server-managed) */
+    valid_from?: string | null;
+    /** End of the temporal validity window (exclusive; null = permanent) */
+    valid_until?: string | null;
+    /** Provenance of valid_until (permanent / extracted / sdk_provided / ...) */
+    valid_until_source?: string | null;
     /** Timestamp when the memory was created (ISO 8601) */
     created_at: string;
     /** Timestamp when the memory was last updated (ISO 8601) */
@@ -1097,10 +1116,17 @@ declare class MemoryService extends BaseService {
 /**
  * @nexusm/sdk - Conversation Types
  *
- * Type definitions for the Conversation Service powered by Zep OSS.
+ * Type definitions for the Conversation Service.
  * Manages conversation history, messages, and auto-generated summaries.
  *
- * Based on Nexus API v2.0 OpenAPI specification.
+ * v4.0.0 BREAKING (memory-conversation-contract-reconciliation, 2026-06-11):
+ * canonical = backend Pydantic response models (`schemas/conversation.py`)
+ * serialized wire names. The previous shapes were drifted: nested
+ * `{data, pagination}` containers never existed on the wire (backend lists
+ * are FLAT), the conversation identifier wire key is `conversation_id` (the
+ * old `session_id` was a phantom), `ConversationDetail` described a response
+ * no endpoint emits, and `ConversationSummary` declared phantom
+ * `key_points`/`generated_at` while missing the real count fields.
  */
 /** Valid message roles in a conversation */
 type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
@@ -1108,17 +1134,29 @@ type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
 type ConversationStatus = 'active' | 'archived' | 'deleted';
 /**
  * A conversation session between a user and an AI agent.
- * Managed by Zep OSS for temporal graph and auto-summary.
+ *
+ * GET /conversations/{conversation_id} — mirrors backend
+ * `ConversationResponse` (11 fields, flat).
+ *
+ * v4.0.0 BREAKING: `session_id` → `conversation_id` (the real wire key —
+ * backend field `compound_session_id` serializes via alias); adds
+ * `tenant_id` / `agent_id` / `status` (previously missing).
  */
 interface Conversation {
     /** Unique conversation identifier (UUID) */
     id: string;
+    /** Compound session ID ("tenant::user::session") — the wire key */
+    conversation_id: string;
+    /** Tenant identifier */
+    tenant_id: string;
     /** User ID that owns this conversation */
     user_id: string;
-    /** Session identifier for the conversation */
-    session_id?: string;
+    /** Originating agent (null when not agent-created) */
+    agent_id?: string | null;
+    /** Conversation status (e.g. active / archived) */
+    status: string;
     /** Auto-generated conversation summary */
-    summary?: string;
+    summary?: string | null;
     /** Total number of messages in the conversation */
     message_count: number;
     /** Additional metadata key-value pairs */
@@ -1141,20 +1179,28 @@ interface ConversationCreate {
     /** Additional metadata key-value pairs */
     metadata?: Record<string, unknown>;
 }
-/**
- * Conversation with its messages included.
- * Returned when include_messages=true.
- */
-interface ConversationDetail extends Conversation {
-    /** Messages in the conversation */
-    messages: Message[];
-}
 /**
  * A single message within a conversation.
+ *
+ * Mirrors backend `MessageResponse` (11 fields).
+ *
+ * v4.0.0 BREAKING: adds `message_id` / `conversation_id` /
+ * `conversation_compound_id` / `tenant_id` / `user_id` correlation fields
+ * (previously missing from the SDK type while present on the wire).
  */
 interface Message {
     /** Unique message identifier (UUID) */
     id: string;
+    /** Compound message ID */
+    message_id: string;
+    /** Owning conversation UUID (NOT the compound id — see conversation_compound_id) */
+    conversation_id: string;
+    /** Owning conversation compound ID ("tenant::user::session") */
+    conversation_compound_id: string;
+    /** Tenant identifier */
+    tenant_id: string;
+    /** User identifier */
+    user_id: string;
     /** Message role (user, assistant, system, or tool) */
     role: MessageRole;
     /** Message content text */
@@ -1162,7 +1208,7 @@ interface Message {
     /** Additional metadata key-value pairs */
     metadata?: Record<string, unknown>;
     /** Message sequence number within the conversation */
-    sequence?: number;
+    sequence: number;
     /** Timestamp when the message was created (ISO 8601) */
     created_at: string;
 }
@@ -1182,49 +1228,67 @@ interface MessageCreate {
 /**
  * Paginated list of conversations.
  *
- * GET /conversations?user_id=...
+ * GET /conversations?user_id=... — mirrors backend
+ * `ConversationListResponse` (FLAT container).
+ *
+ * v4.0.0 BREAKING: was nested `{data, pagination:{total, limit, offset,
+ * has_more}}` — that shape never existed on the wire.
  */
 interface ConversationList {
     /** Array of conversation records */
-    data: Conversation[];
-    /** Pagination metadata */
-    pagination: {
-        /** Total number of conversations */
-        total: number;
-        /** Current page size limit */
-        limit: number;
-        /** Current offset */
-        offset: number;
-        /** Whether more results exist */
-        has_more: boolean;
-    };
+    conversations: Conversation[];
+    /** Total number of conversations */
+    total_count: number;
+    /** Current page size limit */
+    limit: number;
+    /** Current offset */
+    offset: number;
+    /** Whether more results exist */
+    has_next: boolean;
 }
 /**
  * Paginated list of messages within a conversation.
  *
- * GET /conversations/:conversation_id/messages
+ * GET /conversations/:conversation_id/messages — mirrors backend
+ * `MessageListResponse` (FLAT container).
+ *
+ * v4.0.0 BREAKING: was `{data, has_more}` — missing
+ * total_count/limit/offset and using a phantom container key.
  */
 interface MessageList {
     /** Array of message records */
-    data: Message[];
-    /** Whether more messages exist before the current page */
-    has_more: boolean;
+    messages: Message[];
+    /** Total number of messages */
+    total_count: number;
+    /** Current page size limit */
+    limit: number;
+    /** Current offset */
+    offset: number;
+    /** Whether more messages exist */
+    has_next: boolean;
 }
 /**
  * Auto-generated summary of a conversation.
- * Generated by Zep OSS temporal graph analysis.
  *
- * GET /conversations/:conversation_id/summary
+ * GET /conversations/:conversation_id/summary — mirrors backend
+ * `SummaryResponse` (5 fields).
+ *
+ * v4.0.0 BREAKING: the previous shape declared phantom `key_points[]` /
+ * `generated_at`; the backend emits message counts + `created_at`. The wire
+ * id key is `conversation_id` (unified 2026-06-11 — the endpoint previously
+ * emitted `compound_session_id`, an internal third id variant).
  */
 interface ConversationSummary {
-    /** Conversation identifier (UUID) */
+    /** Compound conversation ID (same key as Conversation.conversation_id) */
     conversation_id: string;
-    /** Generated summary text */
-    summary?: string;
-    /** Key points extracted from the conversation */
-    key_points?: string[];
-    /** Timestamp when the summary was generated (ISO 8601) */
-    generated_at: string;
+    /** Generated summary text (null until first summary) */
+    summary?: string | null;
+    /** Number of messages already folded into the summary */
+    summary_message_count: number;
+    /** Total number of messages in the conversation */
+    message_count: number;
+    /** Timestamp when the conversation was created (ISO 8601) */
+    created_at: string;
 }
 
 /**
@@ -1301,13 +1365,17 @@ declare class ConversationService extends BaseService {
      */
     list(params?: ConversationListParams, options?: RequestOptions): Promise<ConversationList>;
     /**
-     * Retrieve a conversation with its messages included.
+     * Retrieve a conversation.
+     *
+     * v4.0.0 BREAKING: returns `Conversation` — the backend response has no
+     * `messages` array (the previous `ConversationDetail` shape was a
+     * phantom). Fetch messages via {@link getMessages}.
      *
-     * @param conversationId - UUID of the conversation to retrieve.
-     * @returns Conversation detail including the full message list.
+     * @param conversationId - Compound conversation ID to retrieve.
+     * @returns The conversation record.
      * @throws {ApiError} 404 if the conversation does not exist.
      */
-    get(conversationId: string, options?: RequestOptions): Promise<ConversationDetail>;
+    get(conversationId: string, options?: RequestOptions): Promise<Conversation>;
     /**
      * Add a message to an existing conversation.
      *
@@ -1758,6 +1826,8 @@ interface TenantQuotas {
     max_memories?: number;
     /** Maximum number of conversations allowed */
     max_conversations?: number;
+    /** Maximum number of knowledge graph nodes allowed */
+    max_graph_nodes?: number;
     /** Maximum API calls per day */
     max_api_calls_per_day?: number;
     /** Forward-compatible: any additional quota dimensions */
@@ -2571,4 +2641,4 @@ declare const apiKeyCreateSchema: z.ZodObject<{
     expires_in_days?: number | undefined;
 }>;
 
-export { type Activity, type ActivityProcessingStatus, ActivityService, type ActivityStats, type ActivityStatusResponse, type ActivityStreamRequest, type ActivityStreamResponse, type ActivityType, ApiError, type ApiErrorDetail, type ApiKey, type ApiKeyCreate, type ApiKeyCreated, type ApiResponse, AuthenticationError, type CacheConfig, type CompoundId, ConfigurationError, type ContextDepth, type ContextDepthPreset, type ContextGraphEntity, type ContextLayer, type ContextRequest, type ContextRetrieveResponse, ContextService, type Conversation, type ConversationCreate, type ConversationDetail, type ConversationList, type ConversationListParams, type ConversationMessage, ConversationService, type ConversationStatus, type ConversationSummary, DEFAULT_CONFIG, DEPTH_PRESETS, type EntityListParams, type EntityListResponse, type ErrorReportRequest, type ErrorReportResponse, ErrorService, type ErrorSeverity, type ErrorType, type ExtractionRequest, type ExtractionResult, type FeedbackItemRequest, type FeedbackListItem, type FeedbackListParams, type FeedbackListResponse, type FeedbackResponse, FeedbackService, type FeedbackSubmitRequest, type GraphPath, type GraphPathEntity, type GraphPathRelationship, type GraphQueryRequest, type GraphQueryResponse, type HealthResponse, type HealthStatus, InputValidationError, type JournalEntry, type JournalResponse, type KnowledgeEntity, type KnowledgeRelationship, KnowledgeService, type Memory, type MemoryCreate, type MemoryJournalParams, type MemoryList, type MemoryListParams, type MemorySearch, type MemorySearchResult, MemoryService, type MemoryType, type MemoryUpdate, type Message, type MessageCreate, type MessageList, type MessageListParams, type MessageRole, NetworkError, NexusClient, type NexusConfig, NexusError, NotFoundError, type OfflineConfig, OfflineQueue, type PaginatedResponse, type Pagination, type ProfileMemory, type QueuedRequest, RateLimitError, type RequestOptions, type ResolvedCacheConfig, type ResolvedConfig, type ResolvedRetryConfig, type RetryConfig, type SearchResult, type ServiceStatus, type SortOrder, type Tenant, type TenantQuotas, TenantService, type TenantTier, TimeoutError, type UsageStats, ValidationError, apiKeyCreateSchema, contextRequestSchema, conversationCreateSchema, extractionRequestSchema, graphQueryRequestSchema, memoryCreateSchema, memorySearchSchema, memoryUpdateSchema, messageCreateSchema, resolveConfig };
+export { type Activity, type ActivityProcessingStatus, ActivityService, type ActivityStats, type ActivityStatusResponse, type ActivityStreamRequest, type ActivityStreamResponse, type ActivityType, ApiError, type ApiErrorDetail, type ApiKey, type ApiKeyCreate, type ApiKeyCreated, type ApiResponse, AuthenticationError, type CacheConfig, type CompoundId, ConfigurationError, type ContextDepth, type ContextDepthPreset, type ContextGraphEntity, type ContextLayer, type ContextRequest, type ContextRetrieveResponse, ContextService, type Conversation, type ConversationCreate, type ConversationList, type ConversationListParams, type ConversationMessage, ConversationService, type ConversationStatus, type ConversationSummary, DEFAULT_CONFIG, DEPTH_PRESETS, type EntityListParams, type EntityListResponse, type ErrorReportRequest, type ErrorReportResponse, ErrorService, type ErrorSeverity, type ErrorType, type ExtractionRequest, type ExtractionResult, type FeedbackItemRequest, type FeedbackListItem, type FeedbackListParams, type FeedbackListResponse, type FeedbackResponse, FeedbackService, type FeedbackSubmitRequest, type GraphPath, type GraphPathEntity, type GraphPathRelationship, type GraphQueryRequest, type GraphQueryResponse, type HealthResponse, type HealthStatus, InputValidationError, type JournalEntry, type JournalResponse, type KnowledgeEntity, type KnowledgeRelationship, KnowledgeService, type Memory, type MemoryCreate, type MemoryJournalParams, type MemoryList, type MemoryListParams, type MemorySearch, type MemorySearchResult, MemoryService, type MemoryType, type MemoryUpdate, type Message, type MessageCreate, type MessageList, type MessageListParams, type MessageRole, NetworkError, NexusClient, type NexusConfig, NexusError, NotFoundError, type OfflineConfig, OfflineQueue, type PaginatedResponse, type Pagination, type ProfileMemory, type QueuedRequest, RateLimitError, type RequestOptions, type ResolvedCacheConfig, type ResolvedConfig, type ResolvedRetryConfig, type RetryConfig, type SearchResult, type ServiceStatus, type SortOrder, type Tenant, type TenantQuotas, TenantService, type TenantTier, TimeoutError, type UsageStats, ValidationError, apiKeyCreateSchema, contextRequestSchema, conversationCreateSchema, extractionRequestSchema, graphQueryRequestSchema, memoryCreateSchema, memorySearchSchema, memoryUpdateSchema, messageCreateSchema, resolveConfig };

package/dist/index.js

@@ -1123,10 +1123,14 @@ var ConversationService = class extends BaseService {
     return this.http.get("/conversations", params, options?.signal);
   }
   /**
-   * Retrieve a conversation with its messages included.
+   * Retrieve a conversation.
    *
-   * @param conversationId - UUID of the conversation to retrieve.
-   * @returns Conversation detail including the full message list.
+   * v4.0.0 BREAKING: returns `Conversation` — the backend response has no
+   * `messages` array (the previous `ConversationDetail` shape was a
+   * phantom). Fetch messages via {@link getMessages}.
+   *
+   * @param conversationId - Compound conversation ID to retrieve.
+   * @returns The conversation record.
    * @throws {ApiError} 404 if the conversation does not exist.
    */
   async get(conversationId, options) {