@nexusm/sdk 1.3.0

package/dist/index.d.mts

@@ -0,0 +1,2572 @@
+import { AxiosResponse } from 'axios';
+import { ZodError, z } from 'zod';
+
+/**
+ * @nexusm/sdk - Common Types
+ *
+ * Shared type definitions used across all Nexus SDK modules.
+ * Based on Nexus API v2.0 OpenAPI specification.
+ */
+/**
+ * Configuration for offline request queuing.
+ * When enabled, requests made while offline are queued and replayed on reconnect.
+ */
+interface OfflineConfig {
+    /** Whether offline queuing is enabled. */
+    enabled: boolean;
+    /**
+     * Maximum number of requests to buffer while offline.
+     * @default 100
+     */
+    maxQueueSize?: number;
+}
+/**
+ * Compound ID used for multi-tenant isolation.
+ * Format: `tenant_id::user_id`
+ */
+type CompoundId = `${string}::${string}`;
+/** Sort order for list queries */
+type SortOrder = 'asc' | 'desc';
+/**
+ * Pagination metadata returned with list responses.
+ * Follows the Nexus API pagination contract.
+ */
+interface Pagination {
+    /** Total number of items across all pages */
+    total: number;
+    /** Number of items per page */
+    limit: number;
+    /** Current offset from the beginning */
+    offset: number;
+    /** Whether more items exist beyond the current page */
+    has_more: boolean;
+}
+/**
+ * Generic paginated response wrapper.
+ * Used for all list endpoints that support pagination.
+ *
+ * @typeParam T - The type of items in the data array
+ */
+interface PaginatedResponse<T> {
+    /** Array of items for the current page */
+    data: T[];
+    /** Pagination metadata */
+    pagination: Pagination;
+}
+/**
+ * Generic API response wrapper.
+ * Used for endpoints that return a single resource or operation result.
+ *
+ * @typeParam T - The type of the response data
+ */
+interface ApiResponse<T> {
+    /** Response payload */
+    data: T;
+    /** Optional metadata about the response */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Structured error detail returned by the Nexus API.
+ */
+interface ApiErrorDetail {
+    /** Machine-readable error code (e.g., "VALIDATION_ERROR", "UNAUTHORIZED") */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Additional error context */
+    details?: Record<string, unknown>;
+}
+/** Service health status */
+type HealthStatus = 'healthy' | 'degraded' | 'unhealthy';
+/** Individual service availability */
+type ServiceStatus = 'up' | 'down';
+/**
+ * Health check response from the `/health` endpoint.
+ */
+interface HealthResponse {
+    /** Overall platform health status */
+    status: HealthStatus;
+    /** Platform version string */
+    version: string;
+    /** Timestamp of the health check */
+    timestamp: string;
+    /** Status of individual backing services */
+    services: {
+        database: ServiceStatus;
+        ollama: ServiceStatus;
+    };
+}
+
+/**
+ * @module config
+ * @description Configuration management for the Nexus SDK.
+ *
+ * Provides sensible defaults, deep-merges user overrides, and exposes a
+ * fully-resolved configuration object where every field is guaranteed to
+ * be present.
+ */
+
+/** Cache layer configuration. */
+interface CacheConfig {
+    /** Maximum number of entries in the LRU cache. */
+    max?: number;
+    /** Time-to-live for cached entries, in **seconds**. */
+    ttl?: number;
+}
+/** Automatic retry configuration with exponential back-off. */
+interface RetryConfig {
+    /** Maximum number of retry attempts (excluding the initial request). */
+    maxRetries?: number;
+    /** Delay before the first retry, in **milliseconds**. */
+    initialDelay?: number;
+    /** Upper bound for the retry delay, in **milliseconds**. */
+    maxDelay?: number;
+    /** Multiplier applied to the delay after each attempt. */
+    backoffFactor?: number;
+}
+/**
+ * User-facing SDK configuration.
+ *
+ * Only `apiKey` is strictly required; every other field falls back to a
+ * sensible default (see {@link DEFAULT_CONFIG}).
+ */
+interface NexusConfig {
+    /** API key used for authentication. */
+    apiKey: string;
+    /**
+     * Tenant identifier for multi-tenant isolation.
+     * When provided, it is sent as the `X-Tenant-ID` header on every request.
+     */
+    tenantId?: string;
+    /** Base URL of the Nexus API (without trailing slash). */
+    baseUrl?: string;
+    /** Request timeout in **milliseconds**. */
+    timeout?: number;
+    /** LRU cache settings. Pass `false` to disable caching entirely. */
+    cache?: CacheConfig | false;
+    /** Retry behaviour. Pass `false` to disable retries entirely. */
+    retry?: RetryConfig | false;
+    /** Offline queue configuration. */
+    offline?: OfflineConfig;
+    /**
+     * Automatically report HTTP 4xx/5xx errors to the Nexus error tracking API.
+     * Defaults to `false`. When enabled, failed API responses are submitted to
+     * `POST /v1/errors` in the background (fire-and-forget).
+     */
+    autoErrorReport?: boolean;
+}
+/** Fully-resolved cache configuration (all fields required). */
+interface ResolvedCacheConfig {
+    /** Maximum number of entries in the LRU cache. */
+    max: number;
+    /** Time-to-live for cached entries, in **seconds**. */
+    ttl: number;
+}
+/** Fully-resolved retry configuration (all fields required). */
+interface ResolvedRetryConfig {
+    /** Maximum number of retry attempts. */
+    maxRetries: number;
+    /** Delay before the first retry, in **milliseconds**. */
+    initialDelay: number;
+    /** Upper bound for the retry delay, in **milliseconds**. */
+    maxDelay: number;
+    /** Multiplier applied to the delay after each attempt. */
+    backoffFactor: number;
+}
+/**
+ * Fully-resolved SDK configuration.
+ *
+ * Every field is guaranteed to be present after calling
+ * {@link resolveConfig}.
+ */
+interface ResolvedConfig {
+    /** API key used for authentication. */
+    apiKey: string;
+    /** Tenant identifier (may be `undefined` if not provided). */
+    tenantId?: string;
+    /** Base URL of the Nexus API (without trailing slash). */
+    baseUrl: string;
+    /** Request timeout in **milliseconds**. */
+    timeout: number;
+    /** Resolved cache settings, or `false` if caching is disabled. */
+    cache: ResolvedCacheConfig | false;
+    /** Resolved retry settings, or `false` if retries are disabled. */
+    retry: ResolvedRetryConfig | false;
+    /** Offline queue configuration (undefined if not provided). */
+    offline?: OfflineConfig;
+    /** Whether to auto-report HTTP 4xx/5xx errors. */
+    autoErrorReport: boolean;
+}
+/**
+ * Default SDK configuration values.
+ *
+ * These are used as the base when merging user-provided overrides.
+ */
+declare const DEFAULT_CONFIG: {
+    readonly baseUrl: "http://localhost:8001/v1";
+    readonly timeout: 30000;
+    readonly cache: ResolvedCacheConfig;
+    readonly retry: ResolvedRetryConfig;
+};
+/**
+ * Deep-merge user configuration with defaults and return a fully-resolved
+ * configuration object.
+ *
+ * @param userConfig - Partial configuration provided by the SDK consumer.
+ * @returns A {@link ResolvedConfig} with every field populated.
+ *
+ * @throws {Error} If `apiKey` is missing or empty.
+ *
+ * @example
+ * ```typescript
+ * const resolved = resolveConfig({
+ *   apiKey: 'sk-...',
+ *   timeout: 5000,
+ *   retry: { maxRetries: 5 },
+ * });
+ *
+ * resolved.timeout;            // 5000
+ * resolved.retry.maxRetries;   // 5
+ * resolved.retry.initialDelay; // 1000 (default)
+ * ```
+ */
+declare function resolveConfig(userConfig: NexusConfig): ResolvedConfig;
+
+/**
+ * @module http/queue
+ * @description Offline request queue for the Nexus SDK.
+ *
+ * When the network is unavailable, requests can be enqueued and later
+ * flushed (replayed) once connectivity is restored. Each enqueued request
+ * returns a `Promise` so callers can `await` the eventual result
+ * transparently.
+ */
+/**
+ * A request that has been queued for later execution.
+ *
+ * The `resolve` and `reject` callbacks are wired to the `Promise` returned
+ * by {@link OfflineQueue.enqueue}, allowing the original caller to `await`
+ * the result even though the actual HTTP call is deferred.
+ */
+interface QueuedRequest {
+    /** Unique identifier for this queued request. */
+    id: string;
+    /** HTTP method (e.g. `GET`, `POST`, `PUT`, `DELETE`). */
+    method: string;
+    /** URL path relative to the base URL. */
+    path: string;
+    /** Optional request body. */
+    data?: unknown;
+    /** Resolve the caller's deferred promise with the response. */
+    resolve: (value: unknown) => void;
+    /** Reject the caller's deferred promise with an error. */
+    reject: (error: unknown) => void;
+    /** Unix timestamp (ms) when the request was enqueued. */
+    timestamp: number;
+}
+/**
+ * Queues HTTP requests while the client is offline and replays them
+ * when connectivity is restored.
+ *
+ * Each call to {@link enqueue} returns a `Promise` that resolves (or
+ * rejects) only after the request has been successfully flushed via
+ * {@link flush}. This allows consuming code to `await` the result as
+ * if the request were executed immediately.
+ *
+ * @example
+ * ```typescript
+ * const queue = new OfflineQueue(50);
+ *
+ * // While offline -- the promise won't settle until flush()
+ * const pending = queue.enqueue({ method: 'POST', path: '/memory/add', data: { text: 'hello' } });
+ *
+ * // Later, when online again
+ * await queue.flush(async (req) => httpClient.post(req.path, req.data));
+ *
+ * // Now `pending` has resolved with the server response
+ * const result = await pending;
+ * ```
+ */
+declare class OfflineQueue {
+    /** Internal FIFO queue of deferred requests. */
+    private readonly queue;
+    /** Maximum number of requests the queue will hold. */
+    private readonly maxSize;
+    /** Guard flag to prevent concurrent flush operations. */
+    private processing;
+    /** Auto-incrementing counter used to generate unique request IDs. */
+    private idCounter;
+    /**
+     * Create a new offline queue.
+     *
+     * @param maxSize - Maximum number of requests to buffer. When the queue
+     *                  is full, subsequent {@link enqueue} calls will reject
+     *                  immediately. Defaults to `100`.
+     */
+    constructor(maxSize?: number);
+    /**
+     * Add a request to the queue.
+     *
+     * The returned `Promise` settles only when the request is eventually
+     * executed during a {@link flush} call.
+     *
+     * @param request - The request descriptor (method, path, and optional data).
+     * @returns A `Promise` that resolves with the executor's return value
+     *          once the request is flushed, or rejects if the queue is full
+     *          or the executor fails.
+     *
+     * @throws {NexusError} If the queue has reached its maximum capacity.
+     */
+    enqueue<T = unknown>(request: Omit<QueuedRequest, 'id' | 'resolve' | 'reject' | 'timestamp'>): Promise<T>;
+    /**
+     * Process all queued requests in FIFO order.
+     *
+     * Each request is passed to the provided `executor` function. On success
+     * the caller's deferred promise is resolved; on failure it is rejected.
+     *
+     * Requests are processed sequentially to preserve ordering guarantees.
+     * If a flush is already in progress, subsequent calls are silently ignored.
+     *
+     * @param executor - An async function that performs the actual HTTP call
+     *                   for a given queued request and returns the response.
+     *
+     * @example
+     * ```typescript
+     * await queue.flush(async (req) => {
+     *   return httpClient.request(req.method, req.path, req.data);
+     * });
+     * ```
+     */
+    flush(executor: (req: QueuedRequest) => Promise<unknown>): Promise<void>;
+    /**
+     * The number of requests currently waiting in the queue.
+     */
+    get size(): number;
+    /**
+     * Remove all pending requests from the queue.
+     *
+     * Every deferred promise is rejected with a cancellation error so that
+     * callers are not left hanging indefinitely.
+     */
+    clear(): void;
+}
+
+/**
+ * @module http/client
+ * @description Low-level HTTP client for the Nexus SDK.
+ *
+ * Wraps an Axios instance with automatic authentication headers,
+ * request/response interceptors, and error normalisation so that
+ * every failure surfaces as a typed {@link NexusError} subclass.
+ */
+
+/**
+ * HTTP client that communicates with the Nexus API.
+ *
+ * All service-level modules (Memory, Conversation, Knowledge, Context)
+ * delegate their network calls to a shared `HttpClient` instance, which
+ * guarantees consistent authentication, timeout handling, and error
+ * mapping across the entire SDK surface.
+ *
+ * @example
+ * ```typescript
+ * import { resolveConfig } from '../config';
+ * import { HttpClient } from './client';
+ *
+ * const config = resolveConfig({ apiKey: 'nx_test_abc123' });
+ * const http = new HttpClient(config);
+ *
+ * const memories = await http.get<Memory[]>('/memory/search', { query: 'hello' });
+ * ```
+ */
+declare class HttpClient {
+    /** Underlying Axios instance. */
+    private readonly axios;
+    /** Fully-resolved SDK configuration snapshot. */
+    private readonly config;
+    /** LRU cache for read requests. */
+    private readonly cache;
+    /** Retry manager for transient failures. */
+    private readonly retry;
+    /** Offline request queue (only created when offline config is provided). */
+    private readonly offlineQueue?;
+    /** Whether the client is currently considered online. */
+    private _isOnline;
+    /**
+     * Optional callback to auto-report API errors to POST /v1/errors.
+     * Set by NexusClient after ErrorService is initialized.
+     * @internal
+     */
+    onApiError?: (statusCode: number, method: string, url: string, detail: string) => void;
+    /**
+     * Create a new HTTP client.
+     *
+     * @param config - Fully-resolved SDK configuration (see {@link resolveConfig}).
+     */
+    constructor(config: ResolvedConfig);
+    /**
+     * Set the online/offline status of the client.
+     *
+     * When transitioning from offline to online, the queued requests are
+     * automatically flushed.
+     *
+     * @param online - `true` if the client is online, `false` if offline.
+     */
+    setOnline(online: boolean): void;
+    /**
+     * Access the offline queue instance (if offline mode is enabled).
+     */
+    get queue(): OfflineQueue | undefined;
+    /**
+     * Send a GET request.
+     *
+     * @typeParam T - Expected shape of the response body.
+     * @param path   - URL path relative to the base URL (e.g. `/memory/search`).
+     * @param params - Optional query parameters.
+     * @param signal - Optional {@link AbortSignal} to cancel the request.
+     * @returns The parsed response body.
+     */
+    get<T>(path: string, params?: Record<string, unknown>, signal?: AbortSignal): Promise<T>;
+    /**
+     * Send a POST request.
+     *
+     * @typeParam T - Expected shape of the response body.
+     * @param path   - URL path relative to the base URL.
+     * @param data   - Optional request body.
+     * @param signal - Optional {@link AbortSignal} to cancel the request.
+     * @returns The parsed response body.
+     */
+    post<T>(path: string, data?: unknown, signal?: AbortSignal): Promise<T>;
+    /**
+     * Send a PUT request.
+     *
+     * @typeParam T - Expected shape of the response body.
+     * @param path   - URL path relative to the base URL.
+     * @param data   - Optional request body.
+     * @param signal - Optional {@link AbortSignal} to cancel the request.
+     * @returns The parsed response body.
+     */
+    put<T>(path: string, data?: unknown, signal?: AbortSignal): Promise<T>;
+    /**
+     * Send a PATCH request.
+     *
+     * @typeParam T - Expected shape of the response body.
+     * @param path   - URL path relative to the base URL.
+     * @param data   - Optional request body.
+     * @param signal - Optional {@link AbortSignal} to cancel the request.
+     * @returns The parsed response body.
+     */
+    patch<T>(path: string, data?: unknown, signal?: AbortSignal): Promise<T>;
+    /**
+     * Send a DELETE request.
+     *
+     * @typeParam T - Expected shape of the response body.
+     * @param path   - URL path relative to the base URL.
+     * @param signal - Optional {@link AbortSignal} to cancel the request.
+     * @returns The parsed response body.
+     */
+    delete<T>(path: string, signal?: AbortSignal): Promise<T>;
+    /**
+     * Attach the request interceptor.
+     *
+     * Responsibilities:
+     * - Set `X-API-Key` authentication header.
+     * - Set `X-Tenant-ID` header when a tenant identifier is configured.
+     * - Ensure `Content-Type` is `application/json`.
+     */
+    private setupRequestInterceptor;
+    /**
+     * Attach the response interceptor.
+     *
+     * Successful responses pass through unchanged. Errors are normalised
+     * into the appropriate {@link NexusError} subclass:
+     *
+     * | Condition              | Error class        |
+     * |------------------------|--------------------|
+     * | Request cancelled      | *(re-thrown as-is)*|
+     * | Timeout (`ECONNABORTED`, `ETIMEDOUT`) | {@link TimeoutError}  |
+     * | No response received   | {@link NetworkError}  |
+     * | HTTP 4xx / 5xx         | {@link ApiError} (or subclass) |
+     */
+    private setupResponseInterceptor;
+}
+
+/**
+ * @module services/base
+ * @description Abstract base class for all Nexus service modules.
+ *
+ * Every service (Context, Memory, Conversation, Knowledge) extends this
+ * class to gain access to the shared {@link HttpClient} instance, which
+ * handles authentication, error normalisation, and timeout management.
+ */
+
+/**
+ * Options that can be passed to any service method.
+ */
+interface RequestOptions {
+    /** Optional AbortSignal to cancel the request. */
+    signal?: AbortSignal;
+}
+/**
+ * Abstract base class that all Nexus service classes extend.
+ *
+ * Provides a protected reference to the SDK's {@link HttpClient} so that
+ * subclasses can issue HTTP requests without managing connection details.
+ *
+ * @example
+ * ```typescript
+ * class MyService extends BaseService {
+ *   async ping(): Promise<string> {
+ *     return this.http.get<string>('/ping');
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseService {
+    /** Shared HTTP client instance configured with API key and tenant headers. */
+    protected readonly http: HttpClient;
+    /**
+     * @param http - Fully-configured {@link HttpClient} instance.
+     */
+    constructor(http: HttpClient);
+}
+
+/**
+ * @nexusm/sdk - Context Types
+ *
+ * Type definitions for the Context Service - the core aggregated context
+ * retrieval API used in Chat main flows.
+ *
+ * v2.0 DX Enhanced temporal-anchored multi-layer retrieval.
+ *
+ * Based on Nexus API v2.0 OpenAPI specification.
+ */
+/**
+ * Available context retrieval layers for multi-layer parallel retrieval.
+ * - "recent": Time-anchored activities from the activity stream
+ * - "semantic": Vector similarity search against memory store (Mem0)
+ * - "graph": Knowledge graph traversal (Fast GraphRAG)
+ */
+type ContextLayer = 'recent' | 'semantic' | 'graph';
+/**
+ * Convenience depth levels for context retrieval.
+ *
+ * | Level | Profile | History | Graph | Layers            |
+ * |-------|---------|---------|-------|-------------------|
+ * | L0    | 1 mem   | off     | off   | []                |
+ * | L1    | 3 mems  | off     | off   | []                |
+ * | L2    | 10 mems | off     | off   | ["semantic"]      |
+ * | L3    | 20 mems | on      | on    | ["semantic","graph"] |
+ *
+ * Use with the `depth` parameter on {@link ContextRequest}.
+ * Explicit fields always override the preset values.
+ */
+type ContextDepth = 'L0' | 'L1' | 'L2' | 'L3';
+/** @internal Partial ContextRequest overrides applied for each depth preset. */
+type ContextDepthPreset = Pick<ContextRequest, 'include_profile' | 'profile_limit' | 'include_history' | 'include_graph' | 'layers'>;
+/**
+ * Preset field overrides for each {@link ContextDepth} level.
+ * Applied before user-supplied options so explicit values always win.
+ */
+declare const DEPTH_PRESETS: Record<ContextDepth, ContextDepthPreset>;
+/**
+ * Request payload for the v2.0 DX Enhanced context retrieval endpoint.
+ * Supports multi-layer parallel retrieval with temporal anchoring (US-014).
+ *
+ * POST /context/retrieve
+ *
+ * The optional `depth` field is a client-side convenience shorthand.
+ * It is resolved to concrete field values before the request is sent to the
+ * backend, so it never appears in the wire payload.
+ */
+interface ContextRequest {
+    /**
+     * Convenience depth preset. When set, applies a predefined combination of
+     * `include_profile`, `profile_limit`, `include_history`, `include_graph`,
+     * and `layers`. Any field you supply explicitly overrides the preset value.
+     *
+     * @see {@link DEPTH_PRESETS} for exact values per level.
+     */
+    depth?: ContextDepth;
+    /** User ID within the tenant (Nexus auto-prefixes tenant ID) */
+    user_id: string;
+    /** Optional semantic query text (used for the semantic layer) */
+    query?: string;
+    /**
+     * Context layers to retrieve in parallel.
+     * @default ["semantic", "graph"]
+     */
+    layers?: ContextLayer[];
+    /**
+     * Time window for the recent layer in hours.
+     * @default 4
+     */
+    recent_hours?: number;
+    /**
+     * Maximum number of recent activities to return.
+     * @default 10
+     */
+    recent_limit?: number;
+    /**
+     * Whether to include memory profile (semantic layer).
+     * @default true
+     */
+    include_profile?: boolean;
+    /**
+     * Maximum number of profile memories to return.
+     * @default 5
+     */
+    profile_limit?: number;
+    /**
+     * Whether to include conversation history.
+     * @default true
+     */
+    include_history?: boolean;
+    /**
+     * Maximum number of conversation history messages to return.
+     * @default 10
+     */
+    history_limit?: number;
+    /**
+     * Whether to include knowledge graph entities (graph layer).
+     * @default true
+     */
+    include_graph?: boolean;
+    /**
+     * Maximum number of knowledge graph entities to return.
+     * @default 5
+     */
+    graph_limit?: number;
+    /**
+     * Optional point-in-time anchor for temporal-aware retrieval.
+     * RFC 3339 datetime **with timezone offset** (e.g.
+     * `"2026-01-01T00:00:00+00:00"` or `"2026-01-01T00:00:00Z"`).
+     * When set, layers that support temporal anchoring (semantic, recent)
+     * scope their retrieval to facts known to the system at that
+     * timestamp — useful for replaying past states (debugging,
+     * compliance) or running deterministic evaluations against
+     * a historical snapshot.
+     *
+     * Naive datetimes (no timezone) are rejected client-side by the
+     * zod schema to prevent silent UTC vs local-time mismatches at
+     * the ingest boundary.
+     *
+     * @since 1.3.0 (US-037 Wave 1 TASK-005)
+     */
+    as_of?: string;
+}
+/**
+ * A single memory item within the context profile.
+ * Sourced from Mem0 memory store.
+ */
+interface ContextMemory {
+    /** Unique memory identifier (UUID) */
+    id: string;
+    /** Memory content text */
+    content: string;
+    /** Type of memory */
+    memory_type: 'episodic' | 'semantic' | 'procedural';
+    /** Relevance score from similarity search */
+    score?: number;
+    /** Timestamp when the memory was created (ISO 8601) */
+    created_at: string;
+}
+/**
+ * User profile memories section of the context response.
+ * Contains memories retrieved from Mem0.
+ */
+interface ContextProfile {
+    /** List of relevant memories */
+    memories: ContextMemory[];
+    /** Total number of memories the user has */
+    total_count: number;
+}
+/** A single message within conversation history. */
+interface ContextMessage {
+    /** Message role */
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    /** Message content text */
+    content: string;
+    /** Timestamp when the message was created (ISO 8601) */
+    created_at: string;
+}
+/**
+ * Conversation history section of the context response.
+ * Sourced from Zep conversation store.
+ */
+interface ContextHistory {
+    /** List of recent messages */
+    messages: ContextMessage[];
+    /** Auto-generated conversation summary (if available) */
+    summary?: string;
+    /** Session identifier */
+    session_id?: string;
+}
+/** Entity ownership type in the knowledge graph */
+type OwnerType = 'agent' | 'user';
+/**
+ * A knowledge entity within the graph context.
+ * Sourced from Fast GraphRAG.
+ */
+interface ContextEntity {
+    /** Unique entity identifier (UUID) */
+    id: string;
+    /** Entity display name */
+    name: string;
+    /** Entity type classification (e.g., Person, Organization) */
+    entity_type: string;
+    /** Entity description */
+    description?: string;
+    /** Additional entity properties */
+    properties?: Record<string, unknown>;
+    /** Ownership type: agent=public knowledge, user=private social graph */
+    owner_type?: OwnerType;
+}
+/** A relationship between two entities in the knowledge graph. */
+interface ContextRelation {
+    /** Source entity name */
+    source: string;
+    /** Relationship type label */
+    relation: string;
+    /** Target entity name */
+    target: string;
+    /** Relationship weight/strength */
+    weight?: number;
+}
+/**
+ * Knowledge graph section of the context response.
+ * Sourced from Fast GraphRAG.
+ */
+interface ContextGraph {
+    /** List of relevant entities */
+    entities: ContextEntity[];
+    /** List of relationships between entities */
+    relations: ContextRelation[];
+}
+/**
+ * Retrieval performance metadata.
+ * Provides timing information for each retrieval layer.
+ */
+interface ContextMeta {
+    /** Total retrieval time in milliseconds */
+    took_ms: number;
+    /** Memory retrieval time in milliseconds */
+    memory_took_ms?: number;
+    /** History retrieval time in milliseconds */
+    history_took_ms?: number;
+    /** Graph retrieval time in milliseconds */
+    graph_took_ms?: number;
+    /** Original query text */
+    query?: string;
+}
+/**
+ * Aggregated context response from the retrieve endpoint.
+ * Contains parallel-fetched results from all requested layers.
+ */
+interface ContextRetrieveResponse {
+    /** User profile memories from Mem0 */
+    profile?: ContextProfile;
+    /** Conversation history from Zep */
+    history?: ContextHistory;
+    /** Knowledge graph data from GraphRAG */
+    graph?: ContextGraph;
+    /** Retrieval performance metadata */
+    meta?: ContextMeta;
+}
+
+/**
+ * @module services/context
+ * @description Context Service - Aggregated context retrieval for Chat main flows.
+ *
+ * The Context Service is the primary entry point for AI agents to fetch
+ * all relevant user context in a single call. It orchestrates parallel
+ * retrieval across Memory (Mem0), Conversation (Zep), and Knowledge
+ * (GraphRAG) layers.
+ *
+ * Based on Nexus API v2.0 - POST /context/retrieve
+ */
+
+/**
+ * Service for aggregated context retrieval.
+ *
+ * This is the core API surface for Chat main flows. A single call to
+ * {@link ContextService.retrieve} fetches user profile memories,
+ * conversation history, and knowledge graph data in parallel.
+ *
+ * @example
+ * ```typescript
+ * const nexus = new NexusClient({ apiKey: 'nx_test_abc123' });
+ *
+ * const context = await nexus.context.retrieve({
+ *   user_id: 'user_42',
+ *   query: 'What did we discuss about the project?',
+ *   layers: ['recent', 'semantic', 'graph'],
+ * });
+ *
+ * console.log(context.profile?.memories);
+ * console.log(context.history?.messages);
+ * console.log(context.graph?.entities);
+ * ```
+ */
+declare class ContextService extends BaseService {
+    /**
+     * Retrieve aggregated context for a user across multiple layers.
+     *
+     * Performs v2.0 three-layer parallel retrieval:
+     * - **recent**: Time-anchored activities from the activity stream
+     * - **semantic**: Vector similarity search against Mem0 memory store
+     * - **graph**: Knowledge graph traversal via Fast GraphRAG
+     *
+     * @param request - Context retrieval parameters including user_id, query, and layer configuration.
+     * @returns Aggregated context containing profile, history, graph, and performance metadata.
+     */
+    retrieve(request: ContextRequest, options?: RequestOptions): Promise<ContextRetrieveResponse>;
+}
+
+/**
+ * @nexusm/sdk - Memory Types
+ *
+ * Type definitions for the Memory Service powered by Mem0.
+ * Supports episodic, semantic, and procedural memory types
+ * with vector similarity search.
+ *
+ * Based on Nexus API v2.0 OpenAPI specification.
+ */
+/** Classification of memory types stored in Mem0 */
+type MemoryType = 'episodic' | 'semantic' | 'procedural';
+/**
+ * A memory record stored in the Nexus platform.
+ * Represents a single piece of user knowledge managed by Mem0.
+ */
+interface Memory {
+    /** Unique memory identifier (UUID) */
+    id: string;
+    /** User ID that owns this memory */
+    user_id: string;
+    /** Memory content text */
+    content: string;
+    /** Classification of the memory */
+    memory_type: MemoryType;
+    /** Additional metadata key-value pairs */
+    metadata?: Record<string, unknown>;
+    /** Relevance score (present in search results) */
+    score?: number;
+    /** Timestamp when the memory was created (ISO 8601) */
+    created_at: string;
+    /** Timestamp when the memory was last updated (ISO 8601) */
+    updated_at: string;
+}
+/**
+ * Request payload for creating a new memory.
+ *
+ * POST /memories
+ */
+interface MemoryCreate {
+    /** User ID to associate the memory with */
+    user_id: string;
+    /** Memory content text (1-10000 characters) */
+    content: string;
+    /**
+     * Classification of the memory.
+     * @default "episodic"
+     */
+    memory_type?: MemoryType;
+    /** Additional metadata key-value pairs */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Request payload for updating an existing memory.
+ *
+ * PATCH /memories/:memory_id
+ */
+interface MemoryUpdate {
+    /** Updated memory content text */
+    content?: string;
+    /** Updated memory type classification */
+    memory_type?: MemoryType;
+    /** Updated metadata (replaces existing metadata) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Request payload for semantic memory search.
+ *
+ * POST /memories/search
+ */
+interface MemorySearch {
+    /** User ID to search within */
+    user_id: string;
+    /** Semantic search query text */
+    query: string;
+    /** Filter by memory type */
+    memory_type?: MemoryType;
+    /**
+     * Maximum number of results to return.
+     * @default 10
+     * @minimum 1
+     * @maximum 50
+     */
+    limit?: number;
+    /**
+     * Minimum similarity score threshold.
+     * @default 0.7
+     * @minimum 0
+     * @maximum 1
+     */
+    threshold?: number;
+}
+/**
+ * Response from a semantic memory search operation.
+ */
+interface MemorySearchResult {
+    /** Array of matching memories (with score populated) */
+    results: Memory[];
+    /** Original search query */
+    query: string;
+    /** Search execution time in milliseconds */
+    took_ms: number;
+}
+/**
+ * Paginated list of memories.
+ *
+ * GET /memories?user_id=...
+ */
+interface MemoryList {
+    /** Array of memory records */
+    data: Memory[];
+    /** Pagination metadata */
+    pagination: {
+        /** Total number of memories */
+        total: number;
+        /** Current page size limit */
+        limit: number;
+        /** Current offset */
+        offset: number;
+        /** Whether more results exist */
+        has_more: boolean;
+    };
+}
+/**
+ * A single journal entry representing a memory on a specific date.
+ * Used in the Memory Journal view (US-015).
+ */
+interface JournalEntry {
+    /** Date key in YYYY-MM-DD format */
+    date: string;
+    /** Memories created on this date */
+    memories: Memory[];
+    /** Number of memories on this date */
+    count: number;
+}
+/**
+ * Response from the memory journal endpoint.
+ * Groups memories by date for chronological review.
+ *
+ * GET /memories/journal
+ */
+interface JournalResponse {
+    /** User ID for the journal */
+    user_id: string;
+    /** Start date of the journal range (ISO 8601 date) */
+    start_date: string;
+    /** End date of the journal range (ISO 8601 date) */
+    end_date: string;
+    /** Memories grouped by date (key: YYYY-MM-DD, value: Memory[]) */
+    entries: Record<string, Memory[]>;
+    /** Total number of days with memories */
+    total_days: number;
+    /** Total number of memories in the range */
+    total_memories: number;
+}
+
+/**
+ * @module services/memories
+ * @description Memory Service - Long-term memory management with semantic retrieval.
+ *
+ * Wraps the Nexus Memory API powered by Mem0. Supports CRUD operations
+ * on episodic, semantic, and procedural memories, vector similarity
+ * search, and the Memory Journal view (US-015).
+ *
+ * Based on Nexus API v2.0 - /memories endpoints
+ */
+
+/**
+ * Parameters for listing memories with optional filtering and pagination.
+ */
+interface MemoryListParams {
+    /** Filter memories by user ID */
+    user_id?: string;
+    /** Filter by memory type classification */
+    memory_type?: MemoryType;
+    /** Maximum number of results per page */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+/**
+ * Parameters for the Memory Journal view (US-015).
+ */
+interface MemoryJournalParams {
+    /** Response format: markdown for display, json for programmatic use */
+    format?: 'markdown' | 'json';
+    /** Start date filter (ISO 8601 date, e.g. "2026-01-01") */
+    start_date?: string;
+    /** End date filter (ISO 8601 date, e.g. "2026-01-31") */
+    end_date?: string;
+    /** Filter journal entries by user ID */
+    user_id?: string;
+}
+/**
+ * Service for managing long-term memories via Mem0.
+ *
+ * Provides full CRUD operations, semantic search, and the chronological
+ * Memory Journal view for reviewing memories over time.
+ *
+ * @example
+ * ```typescript
+ * const nexus = new NexusClient({ apiKey: 'nx_test_abc123' });
+ *
+ * // Create a memory
+ * const memory = await nexus.memories.create({
+ *   user_id: 'user_42',
+ *   content: 'User prefers dark mode',
+ *   memory_type: 'semantic',
+ * });
+ *
+ * // Semantic search
+ * const results = await nexus.memories.search({
+ *   user_id: 'user_42',
+ *   query: 'UI preferences',
+ * });
+ * ```
+ */
+declare class MemoryService extends BaseService {
+    /**
+     * Create a new memory record.
+     *
+     * @param data - Memory creation payload including user_id, content, and optional type/metadata.
+     * @returns The newly created memory with generated ID and timestamps.
+     */
+    create(data: MemoryCreate, options?: RequestOptions): Promise<Memory>;
+    /**
+     * List memories with optional filtering and pagination.
+     *
+     * @param params - Optional filters for user_id, memory_type, and pagination controls.
+     * @returns Paginated list of memory records.
+     */
+    list(params?: MemoryListParams, options?: RequestOptions): Promise<MemoryList>;
+    /**
+     * Retrieve a single memory by its ID.
+     *
+     * @param memoryId - UUID of the memory to retrieve.
+     * @returns The memory record.
+     * @throws {ApiError} 404 if the memory does not exist.
+     */
+    get(memoryId: string, options?: RequestOptions): Promise<Memory>;
+    /**
+     * Update an existing memory record.
+     *
+     * Supports partial updates -- only the provided fields are modified.
+     *
+     * @param memoryId - UUID of the memory to update.
+     * @param data - Fields to update (content, memory_type, metadata).
+     * @returns The updated memory record.
+     * @throws {ApiError} 404 if the memory does not exist.
+     */
+    update(memoryId: string, data: MemoryUpdate, options?: RequestOptions): Promise<Memory>;
+    /**
+     * Delete a memory record.
+     *
+     * @param memoryId - UUID of the memory to delete.
+     * @throws {ApiError} 404 if the memory does not exist.
+     */
+    delete(memoryId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Perform semantic similarity search across memories.
+     *
+     * Uses Mem0's vector search to find memories relevant to the query text.
+     * Results are ranked by similarity score and filtered by optional thresholds.
+     *
+     * @param request - Search parameters including user_id, query, and optional filters.
+     * @returns Search results with scored memories and timing metadata.
+     */
+    search(request: MemorySearch, options?: RequestOptions): Promise<MemorySearchResult>;
+    /**
+     * Retrieve the Memory Journal view (US-015).
+     *
+     * Groups memories chronologically by date for review. Supports both
+     * markdown (human-readable) and JSON (programmatic) output formats.
+     *
+     * @param params - Optional filters for format, date range, and user_id.
+     * @returns Journal response with memories grouped by date.
+     */
+    journal(params?: MemoryJournalParams, options?: RequestOptions): Promise<JournalResponse>;
+}
+
+/**
+ * @nexusm/sdk - Conversation Types
+ *
+ * Type definitions for the Conversation Service powered by Zep OSS.
+ * Manages conversation history, messages, and auto-generated summaries.
+ *
+ * Based on Nexus API v2.0 OpenAPI specification.
+ */
+/** Valid message roles in a conversation */
+type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
+/** Conversation status */
+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.
+ */
+interface Conversation {
+    /** Unique conversation identifier (UUID) */
+    id: string;
+    /** User ID that owns this conversation */
+    user_id: string;
+    /** Session identifier for the conversation */
+    session_id?: string;
+    /** Auto-generated conversation summary */
+    summary?: string;
+    /** Total number of messages in the conversation */
+    message_count: number;
+    /** Additional metadata key-value pairs */
+    metadata?: Record<string, unknown>;
+    /** Timestamp when the conversation was created (ISO 8601) */
+    created_at: string;
+    /** Timestamp when the conversation was last updated (ISO 8601) */
+    updated_at: string;
+}
+/**
+ * Request payload for creating a new conversation.
+ *
+ * POST /conversations
+ */
+interface ConversationCreate {
+    /** User ID to associate the conversation with */
+    user_id: string;
+    /** Custom session ID (auto-generated if not provided) */
+    session_id?: string;
+    /** 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.
+ */
+interface Message {
+    /** Unique message identifier (UUID) */
+    id: string;
+    /** Message role (user, assistant, system, or tool) */
+    role: MessageRole;
+    /** Message content text */
+    content: string;
+    /** Additional metadata key-value pairs */
+    metadata?: Record<string, unknown>;
+    /** Message sequence number within the conversation */
+    sequence?: number;
+    /** Timestamp when the message was created (ISO 8601) */
+    created_at: string;
+}
+/**
+ * Request payload for adding a message to a conversation.
+ *
+ * POST /conversations/:conversation_id/messages
+ */
+interface MessageCreate {
+    /** Message role */
+    role: MessageRole;
+    /** Message content text (1-50000 characters) */
+    content: string;
+    /** Additional metadata key-value pairs */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Paginated list of conversations.
+ *
+ * GET /conversations?user_id=...
+ */
+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;
+    };
+}
+/**
+ * Paginated list of messages within a conversation.
+ *
+ * GET /conversations/:conversation_id/messages
+ */
+interface MessageList {
+    /** Array of message records */
+    data: Message[];
+    /** Whether more messages exist before the current page */
+    has_more: boolean;
+}
+/**
+ * Auto-generated summary of a conversation.
+ * Generated by Zep OSS temporal graph analysis.
+ *
+ * GET /conversations/:conversation_id/summary
+ */
+interface ConversationSummary {
+    /** Conversation identifier (UUID) */
+    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;
+}
+
+/**
+ * @module services/conversations
+ * @description Conversation Service - Conversation history and auto-summary management.
+ *
+ * Wraps the Nexus Conversation API powered by Zep OSS. Supports
+ * conversation lifecycle management, message operations, and
+ * auto-generated summaries via temporal graph analysis.
+ *
+ * Based on Nexus API v2.0 - /conversations endpoints
+ */
+
+/**
+ * Parameters for listing conversations with optional filtering and pagination.
+ */
+interface ConversationListParams {
+    /** Filter conversations by user ID */
+    user_id?: string;
+    /** Maximum number of results per page */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+/**
+ * Parameters for listing messages within a conversation.
+ */
+interface MessageListParams {
+    /** Maximum number of messages to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+/**
+ * Service for managing conversations and messages via Zep OSS.
+ *
+ * Provides conversation lifecycle management (create, list, get, delete),
+ * message operations (add, list), and access to auto-generated summaries
+ * produced by Zep's temporal graph analysis.
+ *
+ * @example
+ * ```typescript
+ * const nexus = new NexusClient({ apiKey: 'nx_test_abc123' });
+ *
+ * // Create a conversation
+ * const conv = await nexus.conversations.create({
+ *   user_id: 'user_42',
+ *   metadata: { topic: 'project planning' },
+ * });
+ *
+ * // Add a message
+ * await nexus.conversations.addMessage(conv.id, {
+ *   role: 'user',
+ *   content: 'Let us discuss the roadmap.',
+ * });
+ *
+ * // Get auto-generated summary
+ * const summary = await nexus.conversations.getSummary(conv.id);
+ * ```
+ */
+declare class ConversationService extends BaseService {
+    /**
+     * Create a new conversation session.
+     *
+     * @param data - Conversation creation payload including user_id and optional metadata.
+     * @returns The newly created conversation with generated ID and timestamps.
+     */
+    create(data: ConversationCreate, options?: RequestOptions): Promise<Conversation>;
+    /**
+     * List conversations with optional filtering and pagination.
+     *
+     * @param params - Optional filters for user_id and pagination controls.
+     * @returns Paginated list of conversation records.
+     */
+    list(params?: ConversationListParams, options?: RequestOptions): Promise<ConversationList>;
+    /**
+     * Retrieve a conversation with its messages included.
+     *
+     * @param conversationId - UUID of the conversation to retrieve.
+     * @returns Conversation detail including the full message list.
+     * @throws {ApiError} 404 if the conversation does not exist.
+     */
+    get(conversationId: string, options?: RequestOptions): Promise<ConversationDetail>;
+    /**
+     * Add a message to an existing conversation.
+     *
+     * The message is appended to the conversation's message sequence.
+     * Zep will asynchronously update the conversation summary after
+     * new messages are added.
+     *
+     * @param conversationId - UUID of the target conversation.
+     * @param message - Message payload including role and content.
+     * @returns The newly created message with generated ID and sequence number.
+     * @throws {ApiError} 404 if the conversation does not exist.
+     */
+    addMessage(conversationId: string, message: MessageCreate, options?: RequestOptions): Promise<Message>;
+    /**
+     * List messages within a conversation with optional pagination.
+     *
+     * Messages are returned in chronological order (oldest first).
+     *
+     * @param conversationId - UUID of the conversation.
+     * @param params - Optional pagination controls (limit, offset).
+     * @returns Paginated list of messages.
+     * @throws {ApiError} 404 if the conversation does not exist.
+     */
+    getMessages(conversationId: string, params?: MessageListParams, options?: RequestOptions): Promise<MessageList>;
+    /**
+     * Retrieve the auto-generated summary of a conversation.
+     *
+     * Summaries are produced by Zep OSS temporal graph analysis and
+     * include key points extracted from the conversation history.
+     *
+     * @param conversationId - UUID of the conversation.
+     * @returns The conversation summary with key points and generation timestamp.
+     * @throws {ApiError} 404 if the conversation does not exist.
+     */
+    getSummary(conversationId: string, options?: RequestOptions): Promise<ConversationSummary>;
+    /**
+     * Delete a conversation and all its messages.
+     *
+     * This operation is irreversible. The conversation, all associated
+     * messages, and the generated summary will be permanently removed.
+     *
+     * @param conversationId - UUID of the conversation to delete.
+     * @throws {ApiError} 404 if the conversation does not exist.
+     */
+    delete(conversationId: string, options?: RequestOptions): Promise<void>;
+}
+
+/**
+ * @nexusm/sdk - Knowledge Types
+ *
+ * Type definitions for the Knowledge Service powered by Fast GraphRAG.
+ * Supports entity extraction, relationship mapping, and graph traversal queries.
+ *
+ * Based on Nexus API v2.0 OpenAPI specification.
+ */
+/**
+ * A knowledge entity in the graph.
+ * Represents a named concept, person, organization, or other entity.
+ */
+interface KnowledgeEntity {
+    /** Unique entity identifier */
+    entity_id: string;
+    /** Entity display name */
+    name: string;
+    /** Entity type classification (e.g., Person, Organization, Concept) */
+    entity_type: string;
+    /** Entity description */
+    description?: string;
+    /** Additional entity properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * A relationship between two knowledge entities.
+ * Follows the Triplex format: (Subject, Relation, Object).
+ */
+interface KnowledgeRelationship {
+    /** Source entity name (Subject) */
+    source: string;
+    /** Target entity name (Object) */
+    target: string;
+    /** Relationship type label (Relation) */
+    relationship_type: string;
+    /** Additional relationship properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Request payload for extracting entities and relationships from text.
+ *
+ * POST /knowledge/extract
+ */
+interface ExtractionRequest {
+    /** Text to extract entities from (1-10000 characters) */
+    text: string;
+    /** Agent ID for public/shared knowledge (mutually exclusive with owner_user_id) */
+    agent_id?: string;
+    /** User ID for private knowledge/social graph (mutually exclusive with agent_id) */
+    owner_user_id?: string;
+}
+/**
+ * Response from entity extraction operation.
+ */
+interface ExtractionResult {
+    /** Extracted entities */
+    entities: KnowledgeEntity[];
+    /** Extracted relationships in Triplex format */
+    relationships: KnowledgeRelationship[];
+    /** Number of new entities created */
+    entities_created: number;
+    /** Number of new relationships created */
+    relationships_created: number;
+}
+/**
+ * Paginated list of knowledge entities.
+ *
+ * GET /knowledge/entities?user_id=...
+ */
+interface EntityListResponse {
+    /** Array of entity records */
+    entities: KnowledgeEntity[];
+    /** Total number of entities */
+    total_count: number;
+    /** Current page size limit */
+    limit: number;
+    /** Current offset */
+    offset: number;
+    /** Whether more results exist */
+    has_next: boolean;
+}
+/**
+ * Request payload for querying the knowledge graph.
+ * Uses BFS traversal from a starting entity.
+ *
+ * POST /knowledge/query
+ */
+interface GraphQueryRequest {
+    /** Starting entity name for graph traversal */
+    entity_name: string;
+    /**
+     * Maximum traversal depth from the starting entity.
+     * @default 1
+     * @minimum 1
+     * @maximum 3
+     */
+    depth?: number;
+    /** Filter by specific relationship types (optional) */
+    relationship_types?: string[];
+}
+/** Entity reference within a graph path */
+interface GraphPathEntity {
+    /** Entity identifier */
+    entity_id: string;
+    /** Entity display name */
+    name: string;
+    /** Entity type classification */
+    type: string;
+}
+/** Relationship reference within a graph path */
+interface GraphPathRelationship {
+    /** Relationship identifier */
+    relationship_id: string;
+    /** Relationship type label */
+    type: string;
+}
+/** A single traversal path in the graph query result */
+interface GraphPath {
+    /** Depth of this path from the starting entity */
+    depth: number;
+    /** Entities along this path */
+    entities: GraphPathEntity[];
+    /** Relationships along this path */
+    relationships: GraphPathRelationship[];
+}
+/**
+ * Response from a graph query operation.
+ */
+interface GraphQueryResponse {
+    /** The starting entity (null if not found) */
+    start_entity: GraphPathEntity | null;
+    /** Traversal paths from the starting entity */
+    paths: GraphPath[];
+    /** Total number of paths found */
+    total_paths: number;
+}
+
+/**
+ * @module services/knowledge
+ * @description Knowledge Service - Knowledge graph construction and query.
+ *
+ * Wraps the Nexus Knowledge API powered by Fast GraphRAG. Supports
+ * entity management, graph traversal queries (BFS), and automatic
+ * entity/relationship extraction from unstructured text.
+ *
+ * Based on Nexus API v2.0 - /knowledge endpoints
+ */
+
+/**
+ * Request payload for creating a new knowledge entity.
+ *
+ * POST /knowledge/entities
+ */
+interface EntityCreate {
+    /** Entity display name */
+    name: string;
+    /** Entity type classification (e.g., Person, Organization, Concept) */
+    entity_type: string;
+    /** Entity description */
+    description?: string;
+    /** Additional entity properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Parameters for listing knowledge entities with optional filtering.
+ */
+interface EntityListParams {
+    /** Filter entities by user ID (owner) */
+    user_id?: string;
+    /** Filter by entity type classification */
+    entity_type?: string;
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+/**
+ * Service for managing the knowledge graph via Fast GraphRAG.
+ *
+ * Provides entity CRUD, BFS graph traversal queries, and automatic
+ * entity/relationship extraction from unstructured text. Supports
+ * both public (agent-owned) and private (user-owned) knowledge.
+ *
+ * @example
+ * ```typescript
+ * const nexus = new NexusClient({ apiKey: 'nx_test_abc123' });
+ *
+ * // Extract entities from text
+ * const extraction = await nexus.knowledge.extract({
+ *   text: 'Alice works at Acme Corp on the Phoenix project.',
+ *   owner_user_id: 'user_42',
+ * });
+ *
+ * // Query the graph
+ * const graph = await nexus.knowledge.query({
+ *   entity_name: 'Alice',
+ *   depth: 2,
+ * });
+ *
+ * console.log(graph.paths);
+ * ```
+ */
+declare class KnowledgeService extends BaseService {
+    /**
+     * Create a new knowledge entity in the graph.
+     *
+     * @param data - Entity creation payload including name, type, and optional description/properties.
+     * @returns The newly created entity with generated entity_id.
+     */
+    createEntity(data: EntityCreate, options?: RequestOptions): Promise<KnowledgeEntity>;
+    /**
+     * List knowledge entities with optional filtering.
+     *
+     * @param params - Optional filters for user_id, entity_type, and pagination controls.
+     * @returns Paginated list of knowledge entities.
+     */
+    listEntities(params?: EntityListParams, options?: RequestOptions): Promise<EntityListResponse>;
+    /**
+     * Query the knowledge graph using BFS traversal.
+     *
+     * Starts from a named entity and traverses outward up to the specified
+     * depth, collecting all reachable entities and relationships along
+     * the traversal paths.
+     *
+     * @param request - Graph query parameters including starting entity name, depth, and optional relationship type filters.
+     * @returns Graph query response with the start entity, traversal paths, and total path count.
+     */
+    query(request: GraphQueryRequest, options?: RequestOptions): Promise<GraphQueryResponse>;
+    /**
+     * Extract entities and relationships from unstructured text.
+     *
+     * Uses Fast GraphRAG's NLP pipeline to identify named entities and
+     * their relationships in Triplex format (Subject, Relation, Object).
+     * Extracted items are automatically persisted to the knowledge graph.
+     *
+     * @param request - Extraction request including the source text and ownership (agent_id or owner_user_id).
+     * @returns Extraction result with lists of created entities and relationships.
+     */
+    extract(request: ExtractionRequest, options?: RequestOptions): Promise<ExtractionResult>;
+}
+
+/**
+ * @nexusm/sdk - Activity Types
+ *
+ * Type definitions for the Activity Service (US-013 DX Enhancement).
+ * Supports passive activity stream ingestion from AI Agents,
+ * which are asynchronously converted into semantic memories.
+ *
+ * Based on Nexus API v2.0 OpenAPI specification.
+ */
+/**
+ * Supported activity action types for the activity stream.
+ * AI Agents report these actions to build passive memory.
+ */
+type ActivityType = 'edit_file' | 'run_test' | 'api_call' | 'user_message' | 'agent_action' | 'read_file' | 'delete_file' | 'create_file' | 'commit' | 'command_run' | 'other';
+/**
+ * A single activity event reported by an AI Agent.
+ */
+interface Activity {
+    /** Activity action type */
+    action: ActivityType;
+    /** Timestamp when the activity occurred (ISO 8601) */
+    timestamp?: string;
+    /** Optional session identifier for activity grouping */
+    session_id?: string;
+    /** Additional activity context (file path, test name, etc.) */
+    activity_data?: Record<string, unknown>;
+}
+/**
+ * Request payload for batch activity stream ingestion.
+ * Accepts up to 1000 activities per request.
+ *
+ * POST /activities/stream
+ */
+interface ActivityStreamRequest {
+    /** Agent identifier reporting the activities */
+    agent_id: string;
+    /** Batch of activity events (1-1000 items) */
+    activities: Activity[];
+}
+/**
+ * Response from activity stream ingestion.
+ */
+interface ActivityStreamResponse {
+    /** Number of activities accepted for processing */
+    accepted: number;
+    /** Number of activities immediately processed */
+    processed: number;
+    /** Number of activities queued for background processing */
+    queued: number;
+    /** Request ID for tracking processing status */
+    request_id: string;
+}
+/** Processing status of a batch activity request */
+type ActivityProcessingStatus = 'pending' | 'processing' | 'completed' | 'failed';
+/**
+ * Status of a previously submitted activity stream request.
+ *
+ * GET /activities/status/:request_id
+ */
+interface ActivityStatusResponse {
+    /** Request ID from the original stream submission */
+    request_id: string;
+    /** Current processing status */
+    status: ActivityProcessingStatus;
+    /** Number of activities accepted */
+    accepted: number;
+    /** Number of activities processed so far */
+    processed: number;
+    /** Number of activities still queued */
+    queued: number;
+}
+/**
+ * Activity statistics for the current tenant.
+ *
+ * GET /activities/stats
+ */
+interface ActivityStats {
+    /** Tenant identifier */
+    tenant_id: string;
+    /** Total number of activities ingested */
+    total_activities: number;
+    /** Number of activities that have been processed */
+    processed_activities: number;
+    /** Number of activities pending processing */
+    pending_activities: number;
+    /** Number of activities in the last 24 hours */
+    recent_activities_24h: number;
+}
+
+/**
+ * @module services/activities
+ * @description Activity stream service for passive memory ingestion.
+ *
+ * AI Agents report their actions (file edits, test runs, API calls, etc.)
+ * through the activity stream. These activities are asynchronously converted
+ * into semantic memories by the Nexus backend (Arq workers).
+ *
+ * @see {@link https://docs.nexus.10cg.pub/api/activities | Activity API Reference}
+ */
+
+/**
+ * Service for ingesting activity streams from AI Agents.
+ *
+ * Activities are the primary mechanism for **passive memory** collection:
+ * agents report what they do, and Nexus converts those actions into
+ * searchable, contextual memories in the background.
+ *
+ * @example
+ * ```typescript
+ * const nexus = new NexusClient({ apiKey: 'nx_live_...' });
+ *
+ * // Log a single activity
+ * await nexus.activities.log({
+ *   action: 'edit_file',
+ *   activity_data: { path: 'src/index.ts', lines_changed: 42 },
+ * });
+ *
+ * // Batch-ingest multiple activities
+ * await nexus.activities.stream({
+ *   agent_id: 'cursor-agent',
+ *   activities: [
+ *     { action: 'read_file', activity_data: { path: 'README.md' } },
+ *     { action: 'edit_file', activity_data: { path: 'src/app.ts' } },
+ *   ],
+ * });
+ * ```
+ */
+declare class ActivityService extends BaseService {
+    /**
+     * Batch-ingest an activity stream.
+     *
+     * Accepts up to 1000 activities per request. Activities are queued for
+     * asynchronous processing by Arq workers on the Nexus backend.
+     *
+     * @param request - The activity stream payload containing agent ID and activities.
+     * @returns Processing summary with accepted / processed / queued counts.
+     */
+    stream(request: ActivityStreamRequest, options?: RequestOptions): Promise<ActivityStreamResponse>;
+    /**
+     * Convenience method to log a single activity.
+     *
+     * Wraps {@link stream} for the common case of reporting one event at a time.
+     *
+     * @param activity  - The activity event to record.
+     * @param agentId   - Agent identifier (defaults to `'default'`).
+     * @returns Processing summary with accepted / processed / queued counts.
+     */
+    log(activity: Activity, agentId?: string, options?: RequestOptions): Promise<ActivityStreamResponse>;
+}
+
+/**
+ * @nexusm/sdk - Tenant Types
+ *
+ * Type definitions for the Tenant management service.
+ * Supports multi-tenant isolation, API key management,
+ * quota tracking, and usage statistics.
+ *
+ * Based on Nexus API v2.0 OpenAPI specification.
+ */
+/** Available tenant subscription tiers */
+type TenantTier = 'free' | 'starter' | 'pro' | 'enterprise';
+/** API Key permission scopes */
+type ApiKeyScope = 'read' | 'write' | 'admin';
+/**
+ * Tenant quotas configuration defining resource limits.
+ */
+interface TenantQuotas {
+    /** Maximum number of memories allowed */
+    max_memories?: number;
+    /** Maximum number of conversations allowed */
+    max_conversations?: number;
+    /** Maximum API calls per day */
+    max_api_calls_per_day?: number;
+}
+/**
+ * Current resource usage counts for a tenant.
+ */
+interface TenantUsage {
+    /** Current number of memories stored */
+    memories_count?: number;
+    /** Current number of conversations */
+    conversations_count?: number;
+    /** API calls made today */
+    api_calls_today?: number;
+}
+/**
+ * A tenant (organization) on the Nexus platform.
+ * Each tenant has isolated data and configurable quotas.
+ *
+ * GET /tenants/me
+ */
+interface Tenant {
+    /** Unique tenant identifier (UUID) */
+    id: string;
+    /** Tenant display name */
+    name: string;
+    /** Subscription tier */
+    tier: TenantTier;
+    /** Resource quotas */
+    quotas?: TenantQuotas;
+    /** Current resource usage */
+    usage?: TenantUsage;
+    /** Timestamp when the tenant was created (ISO 8601) */
+    created_at: string;
+}
+/**
+ * An API key for authenticating with the Nexus platform.
+ * The full key value is only returned once at creation time.
+ *
+ * GET /tenants/me/api-keys
+ */
+interface ApiKey {
+    /** Unique API key identifier (UUID) */
+    id: string;
+    /** API key prefix for identification (e.g., "nx_live_...abc123") */
+    key_prefix: string;
+    /** Human-readable name for the API key */
+    name: string;
+    /** Permission scopes granted to this key */
+    scopes: ApiKeyScope[];
+    /** Expiration timestamp (null = never expires) (ISO 8601) */
+    expires_at?: string | null;
+    /** Last time this key was used (ISO 8601) */
+    last_used_at?: string | null;
+    /** Timestamp when the key was created (ISO 8601) */
+    created_at: string;
+}
+/**
+ * Request payload for creating a new API key.
+ *
+ * POST /tenants/me/api-keys
+ */
+interface ApiKeyCreate {
+    /** Human-readable name for the API key (1-100 characters) */
+    name: string;
+    /**
+     * Permission scopes for the key.
+     * @default ["read", "write"]
+     */
+    scopes?: ApiKeyScope[];
+    /**
+     * Number of days until the key expires.
+     * Omit for a key that never expires.
+     * @minimum 1
+     * @maximum 365
+     */
+    expires_days?: number;
+}
+/**
+ * Response from creating a new API key.
+ * Contains the full key value which is only shown once.
+ */
+interface ApiKeyCreated extends ApiKey {
+    /**
+     * Full API key value.
+     * Format: nx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+     * WARNING: This value is only returned once at creation time.
+     */
+    key: string;
+}
+/**
+ * Usage statistics for a tenant over a specific time period.
+ *
+ * GET /tenants/me/usage
+ */
+interface UsageStats {
+    /** Time period for the statistics */
+    period: 'day' | 'week' | 'month';
+    /** Total API calls in the period */
+    api_calls: number;
+    /** Total tokens consumed */
+    tokens_used?: number;
+    /** Number of memories created in the period */
+    memories_created?: number;
+    /** Number of conversations created in the period */
+    conversations_created?: number;
+}
+
+/**
+ * @module services/tenants
+ * @description Tenant management service for the Nexus platform.
+ *
+ * Provides access to the current tenant's profile, quota configuration,
+ * and usage statistics. Tenant identity is derived from the API key
+ * used to authenticate requests.
+ *
+ * @see {@link https://docs.nexus.10cg.pub/api/tenants | Tenant API Reference}
+ */
+
+/**
+ * Service for managing the current tenant's profile and usage.
+ *
+ * The tenant is automatically identified by the API key provided
+ * to the {@link NexusClient}. All methods operate on the
+ * authenticated tenant's data.
+ *
+ * @example
+ * ```typescript
+ * const nexus = new NexusClient({ apiKey: 'nx_live_...' });
+ *
+ * // Get tenant profile
+ * const tenant = await nexus.tenants.me();
+ * console.log(`Tenant: ${tenant.name} (${tenant.tier})`);
+ *
+ * // Check resource usage
+ * const usage = await nexus.tenants.usage();
+ * console.log(`Memories: ${usage.memories_count}`);
+ * ```
+ */
+declare class TenantService extends BaseService {
+    /**
+     * Retrieve the current tenant's profile.
+     *
+     * Returns the tenant record associated with the API key,
+     * including name, tier, quotas, and current usage snapshot.
+     *
+     * @returns The authenticated tenant's profile.
+     */
+    me(options?: RequestOptions): Promise<Tenant>;
+    /**
+     * Retrieve the current tenant's resource usage statistics.
+     *
+     * Returns counts for memories, conversations, and today's API calls.
+     * Useful for monitoring quota consumption and building dashboards.
+     *
+     * @returns Current resource usage for the authenticated tenant.
+     */
+    usage(options?: RequestOptions): Promise<TenantUsage>;
+    /**
+     * List all API keys for the current tenant.
+     *
+     * @returns Array of API key records (without full key values).
+     */
+    listApiKeys(options?: RequestOptions): Promise<ApiKey[]>;
+    /**
+     * Create a new API key for the current tenant.
+     *
+     * @param data - API key creation parameters (name, scopes, expiry).
+     * @returns The newly created API key, including the full key value (shown only once).
+     */
+    createApiKey(data: ApiKeyCreate, options?: RequestOptions): Promise<ApiKeyCreated>;
+    /**
+     * Revoke (delete) an API key.
+     *
+     * @param id - The UUID of the API key to revoke.
+     */
+    revokeApiKey(id: string, options?: RequestOptions): Promise<void>;
+}
+
+/**
+ * @module types/feedback
+ * @description Feedback Service type definitions.
+ *
+ * Mirrors the Nexus API v5.0 Feedback Loop schema:
+ * - PUT /v1/feedback/{retrieve_id}  — submit rating + item-level feedback
+ * - GET /v1/feedback                — list feedback records
+ */
+/**
+ * Per-memory-item feedback within a single feedback submission.
+ */
+interface FeedbackItemRequest {
+    /** The memory that is being rated. */
+    memory_id: string;
+    /** Whether the memory item was useful in the retrieved context. */
+    useful: boolean;
+    /** Optional free-text explanation. */
+    reason?: string;
+}
+/**
+ * Request body for PUT /v1/feedback/{retrieve_id}.
+ */
+interface FeedbackSubmitRequest {
+    /** Overall quality rating for the context retrieval, 1 (poor) – 5 (excellent). */
+    rating: number;
+    /** Optional per-item ratings for individual memories in the response. */
+    item_feedback?: FeedbackItemRequest[];
+    /** Free-text description of expected information that was missing. */
+    expected_missing?: string;
+    /** Arbitrary caller-supplied context data stored alongside the feedback. */
+    context?: Record<string, unknown>;
+}
+/**
+ * Response from PUT /v1/feedback/{retrieve_id} (HTTP 202 Accepted).
+ */
+interface FeedbackResponse {
+    /** Unique identifier for the created feedback record. */
+    feedback_id: string;
+    /** The retrieve_id the feedback is associated with. */
+    retrieve_id: string;
+    /** Processing status — always "accepted" on success. */
+    status: string;
+    /** ISO 8601 timestamp of when the feedback was recorded. */
+    created_at: string;
+}
+/**
+ * A single feedback record returned by GET /v1/feedback.
+ */
+interface FeedbackListItem {
+    /** Unique identifier for this feedback record. */
+    feedback_id: string;
+    /** The retrieve_id the feedback is associated with. */
+    retrieve_id: string;
+    /** The user who submitted the feedback. */
+    user_id: string;
+    /** Overall quality rating (1–5), or null if not provided. */
+    rating: number | null;
+    /** Free-text description of expected missing information, if provided. */
+    expected_missing: string | null;
+    /** Diagnosis type assigned by the quality scoring pipeline, if any. */
+    diagnosis_type: string | null;
+    /** Caller-supplied context data stored with the feedback. */
+    context_data: Record<string, unknown>;
+    /** ISO 8601 timestamp of when the feedback was recorded. */
+    created_at: string;
+}
+/**
+ * Response from GET /v1/feedback (HTTP 200).
+ */
+interface FeedbackListResponse {
+    /** The feedback records for the requested page. */
+    feedbacks: FeedbackListItem[];
+    /** Total number of feedback records matching the query (for pagination). */
+    total_count: number;
+    /** Maximum number of records per page as applied by the backend. */
+    limit: number;
+    /** Zero-based offset of the first record in this page. */
+    offset: number;
+}
+
+/**
+ * @module services/feedback
+ * @description Feedback Service — submit and query context-retrieval feedback.
+ *
+ * Wraps the Nexus Feedback Loop API (v5.0):
+ * - PUT /v1/feedback/{retrieve_id}  — submit an explicit rating (L2 signal)
+ * - GET /v1/feedback                — list feedback records for reporting
+ *
+ * The `retrieve_id` in each submission links back to a prior
+ * `/context/retrieve` response, enabling the quality scoring pipeline to
+ * correlate explicit feedback with L0 telemetry.
+ *
+ * @example
+ * ```typescript
+ * const nexus = new NexusClient({ apiKey: 'nx_test_abc123' });
+ *
+ * // Submit feedback after a context retrieval
+ * const result = await nexus.feedback.submit('retrieve-uuid', {
+ *   rating: 4,
+ *   item_feedback: [{ memory_id: 'mem-uuid', useful: true }],
+ * });
+ *
+ * // List recent feedback
+ * const list = await nexus.feedback.list({ user_id: 'user_42', limit: 20 });
+ * ```
+ */
+
+/**
+ * Query parameters for listing feedback records.
+ */
+interface FeedbackListParams {
+    /** Filter feedback records by user ID. */
+    user_id?: string;
+    /** Maximum number of records to return. */
+    limit?: number;
+    /** Zero-based offset for pagination. */
+    offset?: number;
+}
+/**
+ * Service for submitting and querying context-retrieval feedback.
+ *
+ * Exposes the Nexus Feedback Loop v5.0 endpoints. Feedback submissions
+ * are processed asynchronously by the QualityScoreWorker and feed into
+ * memory re-ranking.
+ */
+declare class FeedbackService extends BaseService {
+    /**
+     * Submit explicit feedback for a prior context retrieval (L2 signal).
+     *
+     * The backend accepts the submission immediately (HTTP 202) and processes
+     * quality scoring asynchronously via QualityScoreWorker.
+     *
+     * @param retrieveId - The `retrieve_id` returned by `/context/retrieve`.
+     * @param data       - Rating and optional per-item feedback.
+     * @param options    - Optional request options (e.g. AbortSignal).
+     * @returns The created feedback record metadata.
+     */
+    submit(retrieveId: string, data: FeedbackSubmitRequest, options?: RequestOptions): Promise<FeedbackResponse>;
+    /**
+     * List feedback records with optional filtering and pagination.
+     *
+     * @param params  - Optional filters: `user_id`, `limit`, `offset`.
+     * @param options - Optional request options (e.g. AbortSignal).
+     * @returns Paginated list of feedback records.
+     */
+    list(params?: FeedbackListParams, options?: RequestOptions): Promise<FeedbackListResponse>;
+}
+
+/**
+ * @module types/error
+ * @description Type definitions for the Error Reporting API (US-031).
+ */
+/** Error type classification. */
+type ErrorType = 'api_error' | 'data_inconsistency' | 'performance' | 'other';
+/** Severity level of the error. */
+type ErrorSeverity = 'critical' | 'major' | 'minor';
+/** Request body for POST /v1/errors. */
+interface ErrorReportRequest {
+    /** Type of error being reported. */
+    error_type: ErrorType;
+    /** Severity level of the error. */
+    severity: ErrorSeverity;
+    /** Detailed description of the error. */
+    description: string;
+    /** Optional: associated retrieve request ID. */
+    retrieve_id?: string;
+    /** SDK auto-collected request context. */
+    request_context?: Record<string, unknown>;
+    /** Steps to reproduce the error. */
+    reproduction_steps?: string;
+    /** Environment information (PII will be filtered server-side). */
+    environment?: Record<string, unknown>;
+}
+/** Response from POST /v1/errors. */
+interface ErrorReportResponse {
+    /** Error report ID. */
+    id: string;
+    /** Deduplication fingerprint. */
+    fingerprint: string;
+    /** Number of times this error has been reported. */
+    occurrence_count: number;
+    /** Whether this is a new error vs an existing one incremented. */
+    is_new: boolean;
+    /** When the error was first reported. */
+    created_at: string;
+}
+
+/**
+ * @module services/errors
+ * @description Error Reporting Service — submit structured error reports.
+ *
+ * Wraps the Nexus Error Reporting API (US-031):
+ * - POST /v1/errors — submit a structured error/bug report
+ *
+ * Errors are automatically deduplicated server-side by fingerprint
+ * (SHA256 of error_type + endpoint + status_code).
+ *
+ * @example
+ * ```typescript
+ * const nexus = new NexusClient({ apiKey: 'nx_test_abc123' });
+ *
+ * // Manual error report
+ * const report = await nexus.errors.submit({
+ *   error_type: 'api_error',
+ *   severity: 'major',
+ *   description: 'Context retrieval returned empty despite known data',
+ *   retrieve_id: 'uuid-from-retrieve-call',
+ * });
+ * ```
+ */
+
+/**
+ * Service for submitting structured error reports.
+ *
+ * Reports are deduplicated server-side: repeated submissions with the
+ * same fingerprint increment `occurrence_count` instead of creating
+ * new records.
+ */
+declare class ErrorService extends BaseService {
+    /**
+     * Submit a structured error report.
+     *
+     * @param data    - Error report payload.
+     * @param options - Optional request options (e.g. AbortSignal).
+     * @returns The created or updated error report metadata.
+     */
+    submit(data: ErrorReportRequest, options?: RequestOptions): Promise<ErrorReportResponse>;
+}
+
+/**
+ * @module client
+ * @description Main entry point for the Nexus SDK.
+ *
+ * The {@link NexusClient} class is the single object that SDK consumers
+ * instantiate.  It resolves configuration, creates a shared HTTP transport,
+ * and exposes every domain service as a readonly property.
+ */
+
+/**
+ * Nexus AI Cognitive Services SDK client.
+ *
+ * Create a single instance and use the service properties to interact
+ * with the Nexus platform.
+ *
+ * @example
+ * ```typescript
+ * const nexus = new NexusClient({
+ *   apiKey: process.env.NEXUS_API_KEY!,
+ * });
+ *
+ * // Aggregated context retrieval (Chat main flow)
+ * const ctx = await nexus.context.retrieve({
+ *   user_id: 'user123',
+ *   query: '用户偏好',
+ * });
+ *
+ * // Memory search
+ * const memories = await nexus.memories.search({
+ *   user_id: 'user123',
+ *   query: 'favourite colour',
+ * });
+ * ```
+ */
+declare class NexusClient {
+    /** Aggregated context retrieval (Chat main flow). */
+    readonly context: ContextService;
+    /** Memory CRUD, search, and journal. */
+    readonly memories: MemoryService;
+    /** Conversation lifecycle and messages. */
+    readonly conversations: ConversationService;
+    /** Knowledge graph entities and queries. */
+    readonly knowledge: KnowledgeService;
+    /** Activity stream ingestion for passive memory. */
+    readonly activities: ActivityService;
+    /** Tenant profile and usage management. */
+    readonly tenants: TenantService;
+    /** Feedback loop — submit ratings and query feedback records (v5.0). */
+    readonly feedback: FeedbackService;
+    /** Error reporting — submit structured error reports (US-031). */
+    readonly errors: ErrorService;
+    /** @internal Shared HTTP transport. */
+    private readonly http;
+    /**
+     * Create a new Nexus SDK client.
+     *
+     * @param config - SDK configuration. Only `apiKey` is required; all other
+     *   fields fall back to sensible defaults (see {@link resolveConfig}).
+     *
+     * @throws {Error} If `apiKey` is missing or empty.
+     */
+    constructor(config: NexusConfig);
+    /**
+     * Access the offline queue instance (if offline mode is enabled).
+     */
+    get queue(): OfflineQueue | undefined;
+    /**
+     * Set the online/offline status of the client.
+     *
+     * When transitioning from offline to online, queued requests are
+     * automatically flushed.
+     */
+    setOnline(online: boolean): void;
+}
+
+/**
+ * @module errors/base
+ * @description Base error classes for the Nexus SDK.
+ */
+/**
+ * Base error class for all Nexus SDK errors.
+ *
+ * All SDK-specific errors extend this class, providing a consistent
+ * `code` field for programmatic error handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.context.retrieve({ ... });
+ * } catch (err) {
+ *   if (err instanceof NexusError) {
+ *     console.error(`[${err.code}] ${err.message}`);
+ *   }
+ * }
+ * ```
+ */
+declare class NexusError extends Error {
+    /** Machine-readable error code (e.g. `NEXUS_API_ERROR`). */
+    readonly code: string;
+    /** The original error that caused this error, if any. */
+    readonly cause?: Error;
+    constructor(message: string, code: string, cause?: Error);
+}
+/**
+ * Thrown when the SDK is configured with invalid options.
+ *
+ * @example
+ * ```typescript
+ * // Missing required `apiKey`
+ * new NexusClient({}) // throws ConfigurationError
+ * ```
+ */
+declare class ConfigurationError extends NexusError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Thrown when a network-level failure occurs (timeout, DNS, connection refused, etc.).
+ */
+declare class NetworkError extends NexusError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Thrown when an operation exceeds its configured timeout.
+ */
+declare class TimeoutError extends NexusError {
+    constructor(message: string, cause?: Error);
+}
+
+/**
+ * @module errors/api
+ * @description API-level error classes mapped to HTTP status codes.
+ */
+
+/**
+ * Represents an error returned by the Nexus HTTP API.
+ *
+ * Use the static factory `ApiError.fromResponse()` to construct the most
+ * specific subclass based on the HTTP status code.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.memory.search({ ... });
+ * } catch (err) {
+ *   if (err instanceof ApiError) {
+ *     console.error(`HTTP ${err.statusCode}: ${err.message}`);
+ *   }
+ * }
+ * ```
+ */
+declare class ApiError extends NexusError {
+    /** HTTP status code returned by the server. */
+    readonly statusCode: number;
+    /** Raw response body, if available. */
+    readonly response?: unknown;
+    constructor(message: string, statusCode: number, response?: unknown, code?: string);
+    /**
+     * Create the most specific `ApiError` subclass from an Axios response.
+     *
+     * | Status | Error class            |
+     * |--------|------------------------|
+     * | 400    | `ValidationError`      |
+     * | 401    | `AuthenticationError`  |
+     * | 404    | `NotFoundError`        |
+     * | 429    | `RateLimitError`       |
+     * | other  | `ApiError`             |
+     */
+    static fromResponse(response: AxiosResponse): ApiError;
+}
+/**
+ * HTTP 401 -- the request lacks valid authentication credentials.
+ */
+declare class AuthenticationError extends ApiError {
+    constructor(message: string, response?: unknown);
+}
+/**
+ * HTTP 429 -- the client has sent too many requests in a given time window.
+ *
+ * When the server provides a `Retry-After` header, it is exposed via
+ * {@link RateLimitError.retryAfter} (in seconds).
+ */
+declare class RateLimitError extends ApiError {
+    /** Seconds to wait before retrying, parsed from the `Retry-After` header. */
+    readonly retryAfter?: number;
+    constructor(message: string, retryAfter?: number, response?: unknown);
+}
+/**
+ * HTTP 400 -- the request body or query parameters failed validation.
+ *
+ * When the server returns field-level errors they are available via
+ * {@link ValidationError.details}.
+ */
+declare class ValidationError extends ApiError {
+    /** Per-field validation error messages, if provided by the server. */
+    readonly details?: Record<string, string[]>;
+    constructor(message: string, details?: Record<string, string[]>, response?: unknown);
+}
+/**
+ * HTTP 404 -- the requested resource does not exist.
+ */
+declare class NotFoundError extends ApiError {
+    constructor(message: string, response?: unknown);
+}
+
+/**
+ * Thrown when client-side input validation fails (zod schema).
+ * Distinct from the API ValidationError (HTTP 400).
+ */
+declare class InputValidationError extends NexusError {
+    readonly fieldErrors: Record<string, string[]>;
+    constructor(zodError: ZodError);
+}
+
+declare const contextRequestSchema: z.ZodObject<{
+    user_id: z.ZodString;
+    query: z.ZodOptional<z.ZodString>;
+    layers: z.ZodOptional<z.ZodArray<z.ZodEnum<["recent", "semantic", "graph"]>, "many">>;
+    recent_hours: z.ZodOptional<z.ZodNumber>;
+    recent_limit: z.ZodOptional<z.ZodNumber>;
+    include_profile: z.ZodOptional<z.ZodBoolean>;
+    profile_limit: z.ZodOptional<z.ZodNumber>;
+    include_history: z.ZodOptional<z.ZodBoolean>;
+    history_limit: z.ZodOptional<z.ZodNumber>;
+    include_graph: z.ZodOptional<z.ZodBoolean>;
+    graph_limit: z.ZodOptional<z.ZodNumber>;
+    as_of: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    user_id: string;
+    include_profile?: boolean | undefined;
+    profile_limit?: number | undefined;
+    include_history?: boolean | undefined;
+    include_graph?: boolean | undefined;
+    layers?: ("recent" | "semantic" | "graph")[] | undefined;
+    query?: string | undefined;
+    recent_hours?: number | undefined;
+    recent_limit?: number | undefined;
+    history_limit?: number | undefined;
+    graph_limit?: number | undefined;
+    as_of?: string | undefined;
+}, {
+    user_id: string;
+    include_profile?: boolean | undefined;
+    profile_limit?: number | undefined;
+    include_history?: boolean | undefined;
+    include_graph?: boolean | undefined;
+    layers?: ("recent" | "semantic" | "graph")[] | undefined;
+    query?: string | undefined;
+    recent_hours?: number | undefined;
+    recent_limit?: number | undefined;
+    history_limit?: number | undefined;
+    graph_limit?: number | undefined;
+    as_of?: string | undefined;
+}>;
+
+declare const memoryCreateSchema: z.ZodObject<{
+    user_id: z.ZodString;
+    content: z.ZodString;
+    memory_type: z.ZodOptional<z.ZodEnum<["episodic", "semantic", "procedural"]>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    user_id: string;
+    content: string;
+    memory_type?: "semantic" | "episodic" | "procedural" | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    user_id: string;
+    content: string;
+    memory_type?: "semantic" | "episodic" | "procedural" | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+declare const memoryUpdateSchema: z.ZodObject<{
+    content: z.ZodOptional<z.ZodString>;
+    memory_type: z.ZodOptional<z.ZodEnum<["episodic", "semantic", "procedural"]>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    content?: string | undefined;
+    memory_type?: "semantic" | "episodic" | "procedural" | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    content?: string | undefined;
+    memory_type?: "semantic" | "episodic" | "procedural" | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+declare const memorySearchSchema: z.ZodObject<{
+    user_id: z.ZodString;
+    query: z.ZodString;
+    memory_type: z.ZodOptional<z.ZodEnum<["episodic", "semantic", "procedural"]>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    threshold: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    user_id: string;
+    query: string;
+    memory_type?: "semantic" | "episodic" | "procedural" | undefined;
+    limit?: number | undefined;
+    threshold?: number | undefined;
+}, {
+    user_id: string;
+    query: string;
+    memory_type?: "semantic" | "episodic" | "procedural" | undefined;
+    limit?: number | undefined;
+    threshold?: number | undefined;
+}>;
+
+declare const conversationCreateSchema: z.ZodObject<{
+    user_id: z.ZodString;
+    session_id: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    user_id: string;
+    metadata?: Record<string, unknown> | undefined;
+    session_id?: string | undefined;
+}, {
+    user_id: string;
+    metadata?: Record<string, unknown> | undefined;
+    session_id?: string | undefined;
+}>;
+declare const messageCreateSchema: z.ZodObject<{
+    role: z.ZodEnum<["user", "assistant", "system", "tool"]>;
+    content: z.ZodString;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    role: "user" | "assistant" | "system" | "tool";
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    content: string;
+    role: "user" | "assistant" | "system" | "tool";
+    metadata?: Record<string, unknown> | undefined;
+}>;
+
+declare const entityCreateSchema: z.ZodObject<{
+    name: z.ZodString;
+    entity_type: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    entity_type: string;
+    description?: string | undefined;
+    properties?: Record<string, unknown> | undefined;
+}, {
+    name: string;
+    entity_type: string;
+    description?: string | undefined;
+    properties?: Record<string, unknown> | undefined;
+}>;
+declare const graphQueryRequestSchema: z.ZodObject<{
+    entity_name: z.ZodString;
+    depth: z.ZodOptional<z.ZodNumber>;
+    relationship_types: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    entity_name: string;
+    depth?: number | undefined;
+    relationship_types?: string[] | undefined;
+}, {
+    entity_name: string;
+    depth?: number | undefined;
+    relationship_types?: string[] | undefined;
+}>;
+declare const extractionRequestSchema: z.ZodObject<{
+    text: z.ZodString;
+    agent_id: z.ZodOptional<z.ZodString>;
+    owner_user_id: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    agent_id?: string | undefined;
+    owner_user_id?: string | undefined;
+}, {
+    text: string;
+    agent_id?: string | undefined;
+    owner_user_id?: string | undefined;
+}>;
+
+declare const apiKeyCreateSchema: z.ZodObject<{
+    name: z.ZodString;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodEnum<["read", "write", "admin"]>, "many">>;
+    expires_days: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    scopes?: ("read" | "write" | "admin")[] | undefined;
+    expires_days?: number | undefined;
+}, {
+    name: string;
+    scopes?: ("read" | "write" | "admin")[] | undefined;
+    expires_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 ApiKeyScope, type ApiResponse, AuthenticationError, type CacheConfig, type CompoundId, ConfigurationError, type ContextDepth, type ContextDepthPreset, type ContextEntity, type ContextGraph, type ContextHistory, type ContextLayer, type ContextMemory, type ContextMessage, type ContextMeta, type ContextProfile, type ContextRelation, type ContextRequest, type ContextRetrieveResponse, ContextService, type Conversation, type ConversationCreate, type ConversationDetail, type ConversationList, type ConversationListParams, ConversationService, type ConversationStatus, type ConversationSummary, DEFAULT_CONFIG, DEPTH_PRESETS, type EntityCreate, 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 OwnerType, type PaginatedResponse, type Pagination, type QueuedRequest, RateLimitError, type RequestOptions, type ResolvedCacheConfig, type ResolvedConfig, type ResolvedRetryConfig, type RetryConfig, type ServiceStatus, type SortOrder, type Tenant, type TenantQuotas, TenantService, type TenantTier, type TenantUsage, TimeoutError, type UsageStats, ValidationError, apiKeyCreateSchema, contextRequestSchema, conversationCreateSchema, entityCreateSchema, extractionRequestSchema, graphQueryRequestSchema, memoryCreateSchema, memorySearchSchema, memoryUpdateSchema, messageCreateSchema, resolveConfig };