@z3rno/sdk 0.0.1 → 0.2.0

package/dist/index.d.cts

@@ -2,22 +2,74 @@ import { z } from 'zod';
 
 /**
  * Zod schemas and inferred TypeScript types for the Z3rno API.
+ *
+ * Each export is a dual: a Zod schema (used for runtime validation) and an
+ * identically-named TypeScript type (used at compile time). Request schemas
+ * validate client-side input; response schemas validate server payloads.
+ *
+ * @module models
  */
 
+/**
+ * Memory type enum.
+ *
+ * Controls how a memory is stored, indexed, and decayed.
+ *
+ * - `working` — Short-lived scratchpad memory (high decay rate).
+ * - `episodic` — Event-based memory tied to a specific interaction.
+ * - `semantic` — Long-term factual knowledge.
+ * - `procedural` — How-to or process knowledge.
+ */
 declare const MemoryType: z.ZodEnum<["working", "episodic", "semantic", "procedural"]>;
+/** Memory type: `"working"` | `"episodic"` | `"semantic"` | `"procedural"`. */
 type MemoryType = z.infer<typeof MemoryType>;
+/**
+ * Relationship type enum.
+ *
+ * Describes how two memories are related in the knowledge graph.
+ *
+ * - `derived_from` — This memory was created from another.
+ * - `contradicts` — This memory conflicts with another.
+ * - `supports` — This memory reinforces another.
+ * - `supersedes` — This memory replaces another.
+ * - `related_to` — General association.
+ * - `caused_by` — Causal relationship.
+ */
 declare const RelationshipType: z.ZodEnum<["derived_from", "contradicts", "supports", "supersedes", "related_to", "caused_by"]>;
+/** Relationship type between two memories. */
 type RelationshipType = z.infer<typeof RelationshipType>;
+/**
+ * Schema for storing a new memory.
+ *
+ * @example
+ * ```ts
+ * const request = StoreMemoryRequest.parse({
+ *   agentId: "550e8400-e29b-41d4-a716-446655440000",
+ *   content: "User prefers dark mode",
+ *   memoryType: "semantic",
+ * });
+ * ```
+ */
 declare const StoreMemoryRequest: z.ZodObject<{
+    /** UUID of the agent that owns this memory. */
     agentId: z.ZodString;
+    /** The text content to store (1 to 100,000 characters). */
     content: z.ZodString;
+    /** Category of memory. Defaults to `"episodic"`. */
     memoryType: z.ZodDefault<z.ZodEnum<["working", "episodic", "semantic", "procedural"]>>;
+    /** Optional UUID of the user associated with this memory. */
     userId: z.ZodOptional<z.ZodString>;
+    /** Arbitrary key-value metadata attached to the memory. */
     metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** Relationships to other memories in the knowledge graph. */
     relationships: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        /** UUID of the target memory. */
         targetMemoryId: z.ZodString;
+        /** Type of relationship to the target memory. */
         relationshipType: z.ZodEnum<["derived_from", "contradicts", "supports", "supersedes", "related_to", "caused_by"]>;
+        /** Relationship strength from 0 to 1. Defaults to 1.0. */
         weight: z.ZodDefault<z.ZodNumber>;
+        /** Arbitrary metadata for the relationship edge. */
         metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strip", z.ZodTypeAny, {
         metadata: Record<string, unknown>;
@@ -30,7 +82,9 @@ declare const StoreMemoryRequest: z.ZodObject<{
         metadata?: Record<string, unknown> | undefined;
         weight?: number | undefined;
     }>, "many">>;
+    /** Time-to-live in seconds. Memory auto-deletes after this duration. */
     ttlSeconds: z.ZodOptional<z.ZodNumber>;
+    /** Importance score from 0 to 1. Influences recall ranking. */
     importance: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     agentId: string;
@@ -61,16 +115,32 @@ declare const StoreMemoryRequest: z.ZodObject<{
     ttlSeconds?: number | undefined;
     importance?: number | undefined;
 }>;
+/** Parsed type for a store-memory request. */
 type StoreMemoryRequest = z.infer<typeof StoreMemoryRequest>;
+/**
+ * Schema for a single memory object returned by the API.
+ *
+ * Used by {@link Z3rnoClient.store}, {@link Z3rnoClient.getMemory}, and
+ * {@link Z3rnoClient.updateMemory}.
+ */
 declare const MemoryResponse: z.ZodObject<{
+    /** Unique identifier for this memory. */
     id: z.ZodString;
+    /** UUID of the owning agent. */
     agent_id: z.ZodString;
+    /** Text content of the memory. */
     content: z.ZodString;
+    /** Category of the memory. */
     memory_type: z.ZodString;
+    /** Server-computed importance score (0-1). */
     importance_score: z.ZodNumber;
+    /** Number of times this memory has been recalled. */
     recall_count: z.ZodNumber;
+    /** Name of the embedding model used, if any. */
     embedding_model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /** ISO 8601 creation timestamp. */
     created_at: z.ZodString;
+    /** Arbitrary metadata attached to the memory. */
     metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
     content: string;
@@ -93,17 +163,34 @@ declare const MemoryResponse: z.ZodObject<{
     metadata?: Record<string, unknown> | undefined;
     embedding_model?: string | null | undefined;
 }>;
+/** Parsed type for a memory response. */
 type MemoryResponse = z.infer<typeof MemoryResponse>;
+/**
+ * Schema for a single item in recall results.
+ *
+ * Each item includes similarity, importance, and relevance scores
+ * computed by the server's ranking algorithm.
+ */
 declare const RecallResultItem: z.ZodObject<{
+    /** Unique identifier of the recalled memory. */
     memory_id: z.ZodString;
+    /** Text content of the memory. */
     content: z.ZodString;
+    /** Optional server-generated summary. */
     summary: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /** Category of the memory. */
     memory_type: z.ZodString;
+    /** Cosine similarity to the query (0-1). */
     similarity_score: z.ZodNumber;
+    /** Server-computed importance score (0-1). */
     importance_score: z.ZodNumber;
+    /** Combined relevance score used for ranking (0-1). */
     relevance_score: z.ZodNumber;
+    /** Number of times this memory has been recalled. */
     recall_count: z.ZodNumber;
+    /** ISO 8601 creation timestamp. */
     created_at: z.ZodString;
+    /** Arbitrary metadata attached to the memory. */
     metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
     content: string;
@@ -128,18 +215,35 @@ declare const RecallResultItem: z.ZodObject<{
     metadata?: Record<string, unknown> | undefined;
     summary?: string | null | undefined;
 }>;
+/** Parsed type for a single recall result item. */
 type RecallResultItem = z.infer<typeof RecallResultItem>;
+/**
+ * Schema for the full recall response.
+ *
+ * Contains an array of ranked results and the total count of matches.
+ */
 declare const RecallResponse: z.ZodObject<{
+    /** Ranked list of matching memories. */
     results: z.ZodArray<z.ZodObject<{
+        /** Unique identifier of the recalled memory. */
         memory_id: z.ZodString;
+        /** Text content of the memory. */
         content: z.ZodString;
+        /** Optional server-generated summary. */
         summary: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        /** Category of the memory. */
         memory_type: z.ZodString;
+        /** Cosine similarity to the query (0-1). */
         similarity_score: z.ZodNumber;
+        /** Server-computed importance score (0-1). */
         importance_score: z.ZodNumber;
+        /** Combined relevance score used for ranking (0-1). */
         relevance_score: z.ZodNumber;
+        /** Number of times this memory has been recalled. */
         recall_count: z.ZodNumber;
+        /** ISO 8601 creation timestamp. */
         created_at: z.ZodString;
+        /** Arbitrary metadata attached to the memory. */
         metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strip", z.ZodTypeAny, {
         content: string;
@@ -164,7 +268,9 @@ declare const RecallResponse: z.ZodObject<{
         metadata?: Record<string, unknown> | undefined;
         summary?: string | null | undefined;
     }>, "many">;
+    /** Total number of matches (may exceed `topK`). */
     total: z.ZodNumber;
+    /** The query that was searched, if any. */
     query: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     results: {
@@ -197,11 +303,21 @@ declare const RecallResponse: z.ZodObject<{
     total: number;
     query?: string | null | undefined;
 }>;
+/** Parsed type for a recall response. */
 type RecallResponse = z.infer<typeof RecallResponse>;
+/**
+ * Schema for the forget (delete) response.
+ *
+ * Reports how many memories were deleted and whether cascade was applied.
+ */
 declare const ForgetResponse: z.ZodObject<{
+    /** Number of memories deleted. */
     deleted_count: z.ZodNumber;
+    /** Whether a hard delete was performed. */
     hard_deleted: z.ZodBoolean;
+    /** Number of related memories deleted via cascade. */
     cascade_count: z.ZodNumber;
+    /** IDs of all deleted memories. */
     memory_ids: z.ZodArray<z.ZodString, "many">;
 }, "strip", z.ZodTypeAny, {
     deleted_count: number;
@@ -214,16 +330,31 @@ declare const ForgetResponse: z.ZodObject<{
     cascade_count: number;
     memory_ids: string[];
 }>;
+/** Parsed type for a forget response. */
 type ForgetResponse = z.infer<typeof ForgetResponse>;
+/**
+ * Schema for a single audit log entry.
+ *
+ * Audit entries record every operation performed on the agent's memories.
+ */
 declare const AuditEntry: z.ZodObject<{
+    /** Auto-incrementing audit entry ID. */
     id: z.ZodNumber;
+    /** UUID of the agent, if applicable. */
     agent_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /** UUID of the user, if applicable. */
     user_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /** Operation type (e.g., `"store"`, `"recall"`, `"forget"`). */
     operation: z.ZodString;
+    /** UUID of the affected memory, if applicable. */
     memory_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /** Memory type of the affected memory, if applicable. */
     memory_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /** Additional details about the operation. */
     details: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** IP address of the caller, if available. */
     ip_address: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /** ISO 8601 timestamp of the operation. */
     created_at: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     id: number;
@@ -246,17 +377,33 @@ declare const AuditEntry: z.ZodObject<{
     details?: Record<string, unknown> | undefined;
     ip_address?: string | null | undefined;
 }>;
+/** Parsed type for an audit entry. */
 type AuditEntry = z.infer<typeof AuditEntry>;
+/**
+ * Schema for a paginated audit log response.
+ *
+ * Supports cursor-based pagination via `page` and `page_size`.
+ */
 declare const AuditPageResponse: z.ZodObject<{
+    /** Audit entries on this page. */
     entries: z.ZodArray<z.ZodObject<{
+        /** Auto-incrementing audit entry ID. */
         id: z.ZodNumber;
+        /** UUID of the agent, if applicable. */
         agent_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        /** UUID of the user, if applicable. */
         user_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        /** Operation type (e.g., `"store"`, `"recall"`, `"forget"`). */
         operation: z.ZodString;
+        /** UUID of the affected memory, if applicable. */
         memory_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        /** Memory type of the affected memory, if applicable. */
         memory_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        /** Additional details about the operation. */
         details: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        /** IP address of the caller, if available. */
         ip_address: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        /** ISO 8601 timestamp of the operation. */
         created_at: z.ZodString;
     }, "strip", z.ZodTypeAny, {
         id: number;
@@ -279,9 +426,13 @@ declare const AuditPageResponse: z.ZodObject<{
         details?: Record<string, unknown> | undefined;
         ip_address?: string | null | undefined;
     }>, "many">;
+    /** Total number of matching audit entries. */
     total: z.ZodNumber;
+    /** Current page number (1-indexed). */
     page: z.ZodNumber;
+    /** Number of entries per page. */
     page_size: z.ZodNumber;
+    /** Whether more pages are available. */
     has_next: z.ZodBoolean;
 }, "strip", z.ZodTypeAny, {
     entries: {
@@ -316,12 +467,262 @@ declare const AuditPageResponse: z.ZodObject<{
     page_size: number;
     has_next: boolean;
 }>;
+/** Parsed type for a paginated audit response. */
 type AuditPageResponse = z.infer<typeof AuditPageResponse>;
+/**
+ * Schema for the batch store response.
+ *
+ * Returned by {@link Z3rnoClient.storeBatch} after storing multiple memories.
+ */
+declare const BatchStoreResponse: z.ZodObject<{
+    /** Array of stored memory objects. */
+    results: z.ZodArray<z.ZodObject<{
+        /** Unique identifier for this memory. */
+        id: z.ZodString;
+        /** UUID of the owning agent. */
+        agent_id: z.ZodString;
+        /** Text content of the memory. */
+        content: z.ZodString;
+        /** Category of the memory. */
+        memory_type: z.ZodString;
+        /** Server-computed importance score (0-1). */
+        importance_score: z.ZodNumber;
+        /** Number of times this memory has been recalled. */
+        recall_count: z.ZodNumber;
+        /** Name of the embedding model used, if any. */
+        embedding_model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        /** ISO 8601 creation timestamp. */
+        created_at: z.ZodString;
+        /** Arbitrary metadata attached to the memory. */
+        metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        metadata: Record<string, unknown>;
+        id: string;
+        agent_id: string;
+        memory_type: string;
+        importance_score: number;
+        recall_count: number;
+        created_at: string;
+        embedding_model?: string | null | undefined;
+    }, {
+        content: string;
+        id: string;
+        agent_id: string;
+        memory_type: string;
+        importance_score: number;
+        recall_count: number;
+        created_at: string;
+        metadata?: Record<string, unknown> | undefined;
+        embedding_model?: string | null | undefined;
+    }>, "many">;
+    /** Number of memories successfully stored. */
+    stored_count: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    results: {
+        content: string;
+        metadata: Record<string, unknown>;
+        id: string;
+        agent_id: string;
+        memory_type: string;
+        importance_score: number;
+        recall_count: number;
+        created_at: string;
+        embedding_model?: string | null | undefined;
+    }[];
+    stored_count: number;
+}, {
+    results: {
+        content: string;
+        id: string;
+        agent_id: string;
+        memory_type: string;
+        importance_score: number;
+        recall_count: number;
+        created_at: string;
+        metadata?: Record<string, unknown> | undefined;
+        embedding_model?: string | null | undefined;
+    }[];
+    stored_count: number;
+}>;
+/** Parsed type for a batch store response. */
+type BatchStoreResponse = z.infer<typeof BatchStoreResponse>;
+/**
+ * Schema for a single version of a memory (temporal versioning).
+ *
+ * Each version represents the state of a memory during a specific time range.
+ */
+declare const MemoryVersion: z.ZodObject<{
+    /** Version identifier. */
+    id: z.ZodString;
+    /** Text content at this version. */
+    content: z.ZodString;
+    /** Memory type at this version. */
+    memory_type: z.ZodString;
+    /** Importance score at this version. */
+    importance_score: z.ZodNumber;
+    /** ISO 8601 timestamp when this version became active. */
+    valid_from: z.ZodString;
+    /** ISO 8601 timestamp when this version was superseded, or null if current. */
+    valid_to: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /** Metadata at this version. */
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    metadata: Record<string, unknown>;
+    id: string;
+    memory_type: string;
+    importance_score: number;
+    valid_from: string;
+    valid_to?: string | null | undefined;
+}, {
+    content: string;
+    id: string;
+    memory_type: string;
+    importance_score: number;
+    valid_from: string;
+    metadata?: Record<string, unknown> | undefined;
+    valid_to?: string | null | undefined;
+}>;
+/** Parsed type for a memory version. */
+type MemoryVersion = z.infer<typeof MemoryVersion>;
+/**
+ * Schema for the memory history response.
+ *
+ * Contains all temporal versions of a single memory, ordered chronologically.
+ */
+declare const MemoryHistoryResponse: z.ZodObject<{
+    /** UUID of the memory. */
+    memory_id: z.ZodString;
+    /** Chronologically ordered list of versions. */
+    versions: z.ZodArray<z.ZodObject<{
+        /** Version identifier. */
+        id: z.ZodString;
+        /** Text content at this version. */
+        content: z.ZodString;
+        /** Memory type at this version. */
+        memory_type: z.ZodString;
+        /** Importance score at this version. */
+        importance_score: z.ZodNumber;
+        /** ISO 8601 timestamp when this version became active. */
+        valid_from: z.ZodString;
+        /** ISO 8601 timestamp when this version was superseded, or null if current. */
+        valid_to: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        /** Metadata at this version. */
+        metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        metadata: Record<string, unknown>;
+        id: string;
+        memory_type: string;
+        importance_score: number;
+        valid_from: string;
+        valid_to?: string | null | undefined;
+    }, {
+        content: string;
+        id: string;
+        memory_type: string;
+        importance_score: number;
+        valid_from: string;
+        metadata?: Record<string, unknown> | undefined;
+        valid_to?: string | null | undefined;
+    }>, "many">;
+    /** Total number of versions. */
+    total: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    memory_id: string;
+    total: number;
+    versions: {
+        content: string;
+        metadata: Record<string, unknown>;
+        id: string;
+        memory_type: string;
+        importance_score: number;
+        valid_from: string;
+        valid_to?: string | null | undefined;
+    }[];
+}, {
+    memory_id: string;
+    total: number;
+    versions: {
+        content: string;
+        id: string;
+        memory_type: string;
+        importance_score: number;
+        valid_from: string;
+        metadata?: Record<string, unknown> | undefined;
+        valid_to?: string | null | undefined;
+    }[];
+}>;
+/** Parsed type for a memory history response. */
+type MemoryHistoryResponse = z.infer<typeof MemoryHistoryResponse>;
+/**
+ * Schema for a session response.
+ *
+ * Sessions group related memory operations (e.g., a conversation turn).
+ */
+declare const SessionResponse: z.ZodObject<{
+    /** Unique session identifier. */
+    session_id: z.ZodString;
+    /** UUID of the agent this session belongs to. */
+    agent_id: z.ZodString;
+    /** Type of session (e.g., `"conversation"`). */
+    session_type: z.ZodString;
+    /** ISO 8601 timestamp when the session started. */
+    started_at: z.ZodString;
+    /** Arbitrary session metadata. */
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    metadata: Record<string, unknown>;
+    agent_id: string;
+    session_id: string;
+    session_type: string;
+    started_at: string;
+}, {
+    agent_id: string;
+    session_id: string;
+    session_type: string;
+    started_at: string;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+/** Parsed type for a session response. */
+type SessionResponse = z.infer<typeof SessionResponse>;
+/**
+ * Schema for the end-session response.
+ *
+ * Returned when a session is closed, including summary statistics.
+ */
+declare const EndSessionResponse: z.ZodObject<{
+    /** The session that was ended. */
+    session_id: z.ZodString;
+    /** ISO 8601 timestamp when the session ended. */
+    ended_at: z.ZodString;
+    /** Total duration of the session in seconds. */
+    duration_seconds: z.ZodNumber;
+    /** Number of memories created during the session. */
+    memory_count: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    session_id: string;
+    ended_at: string;
+    duration_seconds: number;
+    memory_count: number;
+}, {
+    session_id: string;
+    ended_at: string;
+    duration_seconds: number;
+    memory_count: number;
+}>;
+/** Parsed type for an end-session response. */
+type EndSessionResponse = z.infer<typeof EndSessionResponse>;
 
 /**
  * Z3rno TypeScript SDK client.
  *
  * Thin fetch wrapper — no database drivers, no embedding providers.
+ * Works in Node.js 18+, Deno, Bun, and modern browsers (any runtime
+ * with a global `fetch` and `AbortController`).
+ *
+ * @module client
  *
  * @example
  * ```ts
@@ -332,18 +733,176 @@ type AuditPageResponse = z.infer<typeof AuditPageResponse>;
  * ```
  */
 
+/**
+ * Configuration options for the {@link Z3rnoClient}.
+ *
+ * All fields are optional. When omitted, the client reads from environment
+ * variables (`Z3RNO_BASE_URL`, `Z3RNO_API_KEY`) or uses sensible defaults.
+ */
 interface Z3rnoClientConfig {
-    baseUrl: string;
-    apiKey: string;
+    /**
+     * Base URL of the Z3rno API.
+     *
+     * Falls back to the `Z3RNO_BASE_URL` environment variable, then
+     * to `"https://api.z3rno.dev"`.
+     */
+    baseUrl?: string;
+    /**
+     * API key for authentication.
+     *
+     * Falls back to the `Z3RNO_API_KEY` environment variable, then to
+     * an empty string (unauthenticated).
+     */
+    apiKey?: string;
+    /**
+     * Request timeout in milliseconds.
+     *
+     * @defaultValue 30000 (30 seconds)
+     */
     timeout?: number;
+    /**
+     * Maximum number of retry attempts for retryable errors (5xx, 429,
+     * network failures, timeouts).
+     *
+     * @defaultValue 3
+     */
     maxRetries?: number;
+    /**
+     * Custom fetch implementation.
+     *
+     * Defaults to `globalThis.fetch`. Override to use `undici`, `node-fetch`,
+     * or a test double.
+     *
+     * @defaultValue globalThis.fetch
+     */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Intercept outgoing requests before they are sent.
+     *
+     * Use this to add custom headers, log requests, or collect metrics.
+     * The callback receives the URL and the `RequestInit` and must return
+     * a (possibly modified) `RequestInit`.
+     */
+    onRequest?: (url: string, init: RequestInit) => RequestInit;
+    /**
+     * Intercept responses before they are processed.
+     *
+     * Use this for logging, metrics, or response transformation.
+     * The callback receives the `Response` and must return a `Response`.
+     */
+    onResponse?: (response: Response) => Response;
 }
+/**
+ * Client for the Z3rno AI agent memory API.
+ *
+ * Uses the standard Fetch API under the hood, making it compatible with
+ * Node.js 18+, Deno, Bun, and modern browsers. All responses are
+ * validated at runtime with Zod schemas.
+ *
+ * @example
+ * ```ts
+ * import { Z3rnoClient } from "@z3rno/sdk";
+ *
+ * const client = new Z3rnoClient({
+ *   baseUrl: "http://localhost:8000",
+ *   apiKey: "z3rno_sk_test_...",
+ * });
+ *
+ * // Store a memory
+ * const mem = await client.store({
+ *   agentId: "550e8400-e29b-41d4-a716-446655440000",
+ *   content: "User prefers dark mode",
+ * });
+ *
+ * // Recall relevant memories
+ * const results = await client.recall({
+ *   agentId: "550e8400-e29b-41d4-a716-446655440000",
+ *   query: "user preferences",
+ * });
+ * ```
+ */
 declare class Z3rnoClient {
     private baseUrl;
     private apiKey;
     private timeout;
-    constructor(config: Z3rnoClientConfig);
+    private maxRetries;
+    private fetchImpl;
+    private onRequest?;
+    private onResponse?;
+    /**
+     * Creates a new Z3rno client instance.
+     *
+     * @param config - Client configuration options. All fields are optional.
+     *
+     * @example
+     * ```ts
+     * // Explicit configuration
+     * const client = new Z3rnoClient({
+     *   baseUrl: "http://localhost:8000",
+     *   apiKey: "z3rno_sk_test_...",
+     *   timeout: 10000,
+     *   maxRetries: 2,
+     * });
+     *
+     * // Or rely on environment variables (Z3RNO_BASE_URL, Z3RNO_API_KEY)
+     * const client = new Z3rnoClient();
+     * ```
+     */
+    constructor(config?: Z3rnoClientConfig);
+    /**
+     * Stores a new memory for an agent.
+     *
+     * The server generates an embedding for the content and stores it in
+     * the vector database. The memory is immediately available for recall.
+     *
+     * @param request - The memory to store.
+     * @returns The stored memory, including the server-generated ID and scores.
+     * @throws {@link AuthenticationError} If the API key is invalid.
+     * @throws {@link ValidationError} If the request body is invalid.
+     * @throws {@link Z3rnoTimeoutError} If the request times out.
+     *
+     * @example
+     * ```ts
+     * const memory = await client.store({
+     *   agentId: "550e8400-e29b-41d4-a716-446655440000",
+     *   content: "User prefers dark mode",
+     *   memoryType: "semantic",
+     *   metadata: { source: "settings-page" },
+     * });
+     * console.log(memory.id); // "mem-abc123"
+     * ```
+     */
     store(request: StoreMemoryRequest): Promise<MemoryResponse>;
+    /**
+     * Recalls memories by semantic similarity to a query.
+     *
+     * Returns a ranked list of memories sorted by a combined relevance score
+     * that factors in similarity, importance, and recency.
+     *
+     * @param params - Recall parameters including the query and filters.
+     * @param params.agentId - UUID of the agent whose memories to search.
+     * @param params.query - Natural-language query for semantic search.
+     * @param params.memoryType - Filter by memory type.
+     * @param params.filters - Additional metadata filters.
+     * @param params.topK - Maximum results to return (default 10).
+     * @param params.similarityThreshold - Minimum similarity score (default 0).
+     * @returns Ranked recall results with similarity scores.
+     * @throws {@link AuthenticationError} If the API key is invalid.
+     * @throws {@link Z3rnoTimeoutError} If the request times out.
+     *
+     * @example
+     * ```ts
+     * const results = await client.recall({
+     *   agentId: "550e8400-e29b-41d4-a716-446655440000",
+     *   query: "user preferences",
+     *   topK: 5,
+     *   similarityThreshold: 0.7,
+     * });
+     * for (const item of results.results) {
+     *   console.log(`${item.content} (score: ${item.relevance_score})`);
+     * }
+     * ```
+     */
     recall(params: {
         agentId: string;
         query?: string;
@@ -352,6 +911,35 @@ declare class Z3rnoClient {
         topK?: number;
         similarityThreshold?: number;
     }): Promise<RecallResponse>;
+    /**
+     * Forgets (deletes) one or more memories.
+     *
+     * By default, performs a soft delete (marks as deleted but retains data).
+     * Set `hardDelete: true` for permanent removal. Use `cascade: true` to
+     * also delete related memories in the knowledge graph.
+     *
+     * @param params - Forget parameters.
+     * @param params.agentId - UUID of the agent that owns the memories.
+     * @param params.memoryId - UUID of a single memory to delete.
+     * @param params.memoryIds - UUIDs of multiple memories to delete.
+     * @param params.hardDelete - Permanently delete (default false).
+     * @param params.cascade - Delete related memories too (default false).
+     * @param params.reason - Reason for deletion (stored in audit log).
+     * @returns Summary of the deletion operation.
+     * @throws {@link AuthenticationError} If the API key is invalid.
+     * @throws {@link NotFoundError} If the specified memory does not exist.
+     *
+     * @example
+     * ```ts
+     * const result = await client.forget({
+     *   agentId: "550e8400-e29b-41d4-a716-446655440000",
+     *   memoryId: "mem-abc123",
+     *   hardDelete: true,
+     *   reason: "User requested data deletion",
+     * });
+     * console.log(`Deleted ${result.deleted_count} memories`);
+     * ```
+     */
     forget(params: {
         agentId: string;
         memoryId?: string;
@@ -360,37 +948,366 @@ declare class Z3rnoClient {
         cascade?: boolean;
         reason?: string;
     }): Promise<ForgetResponse>;
+    /**
+     * Retrieves a single memory by its ID.
+     *
+     * @param memoryId - The unique identifier of the memory to retrieve.
+     * @returns The full memory object.
+     * @throws {@link NotFoundError} If no memory exists with the given ID.
+     * @throws {@link AuthenticationError} If the API key is invalid.
+     *
+     * @example
+     * ```ts
+     * const memory = await client.getMemory("mem-abc123");
+     * console.log(memory.content);
+     * console.log(memory.importance_score);
+     * ```
+     */
+    getMemory(memoryId: string): Promise<MemoryResponse>;
+    /**
+     * Stores multiple memories in a single API call.
+     *
+     * More efficient than calling {@link store} in a loop. All memories are
+     * processed atomically on the server.
+     *
+     * @param memories - Array of memories to store.
+     * @returns The stored memories and a count of how many were created.
+     * @throws {@link ValidationError} If any memory in the batch is invalid.
+     * @throws {@link AuthenticationError} If the API key is invalid.
+     *
+     * @example
+     * ```ts
+     * const result = await client.storeBatch([
+     *   { agentId: "agent-1", content: "Fact one" },
+     *   { agentId: "agent-1", content: "Fact two", memoryType: "semantic" },
+     * ]);
+     * console.log(`Stored ${result.stored_count} memories`);
+     * ```
+     */
+    storeBatch(memories: StoreMemoryRequest[]): Promise<BatchStoreResponse>;
+    /**
+     * Retrieves the full version history of a memory.
+     *
+     * Z3rno uses temporal versioning — every update creates a new version
+     * rather than overwriting. This method returns all versions ordered
+     * chronologically.
+     *
+     * @param memoryId - The unique identifier of the memory.
+     * @returns All versions of the memory with validity timestamps.
+     * @throws {@link NotFoundError} If no memory exists with the given ID.
+     * @throws {@link AuthenticationError} If the API key is invalid.
+     *
+     * @example
+     * ```ts
+     * const history = await client.getMemoryHistory("mem-abc123");
+     * for (const version of history.versions) {
+     *   console.log(`${version.valid_from}: ${version.content}`);
+     * }
+     * ```
+     */
+    getMemoryHistory(memoryId: string): Promise<MemoryHistoryResponse>;
+    /**
+     * Updates an existing memory's content, metadata, or importance.
+     *
+     * Creates a new temporal version of the memory. The previous version
+     * remains accessible via {@link getMemoryHistory}.
+     *
+     * @param memoryId - The unique identifier of the memory to update.
+     * @param updates - Fields to update (only provided fields are changed).
+     * @param updates.content - New text content.
+     * @param updates.metadata - New metadata (replaces existing metadata).
+     * @param updates.importance - New importance score (0-1).
+     * @returns The updated memory object.
+     * @throws {@link NotFoundError} If no memory exists with the given ID.
+     * @throws {@link ValidationError} If the update values are invalid.
+     * @throws {@link AuthenticationError} If the API key is invalid.
+     *
+     * @example
+     * ```ts
+     * const updated = await client.updateMemory("mem-abc123", {
+     *   content: "User now prefers light mode",
+     *   importance: 0.9,
+     * });
+     * ```
+     */
+    updateMemory(memoryId: string, updates: {
+        content?: string;
+        metadata?: Record<string, unknown>;
+        importance?: number;
+    }): Promise<MemoryResponse>;
+    /**
+     * Starts a new session for grouping related memory operations.
+     *
+     * Sessions are useful for tracking conversation turns or task boundaries.
+     * Memories created during a session are automatically associated with it.
+     *
+     * @param params - Session parameters.
+     * @param params.agentId - UUID of the agent to start the session for.
+     * @param params.sessionType - Type of session (default `"conversation"`).
+     * @returns The created session with its ID and start time.
+     * @throws {@link AuthenticationError} If the API key is invalid.
+     *
+     * @example
+     * ```ts
+     * const session = await client.startSession({ agentId: "agent-1" });
+     * console.log(`Session started: ${session.session_id}`);
+     * // ... perform operations ...
+     * await client.endSession(session.session_id);
+     * ```
+     */
+    startSession(params: {
+        agentId: string;
+        sessionType?: string;
+    }): Promise<SessionResponse>;
+    /**
+     * Ends an active session.
+     *
+     * Returns summary statistics including the session duration and the
+     * number of memories created during the session.
+     *
+     * @param sessionId - The unique identifier of the session to end.
+     * @returns Session summary with duration and memory count.
+     * @throws {@link NotFoundError} If no active session exists with the given ID.
+     * @throws {@link AuthenticationError} If the API key is invalid.
+     *
+     * @example
+     * ```ts
+     * const summary = await client.endSession("sess-abc123");
+     * console.log(`Session lasted ${summary.duration_seconds}s, ${summary.memory_count} memories`);
+     * ```
+     */
+    endSession(sessionId: string): Promise<EndSessionResponse>;
+    /**
+     * Retrieves a paginated audit log of memory operations.
+     *
+     * The audit log records every store, recall, forget, and update operation
+     * performed by any agent. Useful for compliance, debugging, and analytics.
+     *
+     * @param params - Optional pagination and filter parameters.
+     * @param params.agentId - Filter by agent UUID.
+     * @param params.page - Page number (1-indexed).
+     * @param params.pageSize - Number of entries per page.
+     * @returns A page of audit log entries with pagination metadata.
+     * @throws {@link AuthenticationError} If the API key is invalid.
+     *
+     * @example
+     * ```ts
+     * const page = await client.audit({ agentId: "agent-1", page: 1, pageSize: 20 });
+     * for (const entry of page.entries) {
+     *   console.log(`${entry.created_at}: ${entry.operation} on ${entry.memory_id}`);
+     * }
+     * if (page.has_next) {
+     *   const nextPage = await client.audit({ agentId: "agent-1", page: 2 });
+     * }
+     * ```
+     */
     audit(params?: {
         agentId?: string;
         page?: number;
         pageSize?: number;
     }): Promise<AuditPageResponse>;
     private request;
+    private sleep;
     private handleResponse;
 }
 
 /**
  * Z3rno SDK error hierarchy.
+ *
+ * All errors thrown by the SDK extend {@link Z3rnoError}, which itself extends
+ * the built-in `Error` class. This lets callers catch broadly (`Z3rnoError`)
+ * or narrowly (`AuthenticationError`, `RateLimitError`, etc.).
+ *
+ * @module errors
+ */
+/**
+ * Base error class for all Z3rno SDK errors.
+ *
+ * Every error produced by the SDK is an instance of this class, so you can
+ * use a single `catch (e) { if (e instanceof Z3rnoError) ... }` guard to
+ * handle them all.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.store({ agentId: "...", content: "..." });
+ * } catch (e) {
+ *   if (e instanceof Z3rnoError) {
+ *     console.error(`Z3rno error (${e.statusCode}): ${e.message}`);
+ *   }
+ * }
+ * ```
  */
 declare class Z3rnoError extends Error {
+    /** HTTP status code returned by the server, if applicable. */
     statusCode?: number;
+    /**
+     * @param message - Human-readable description of the error.
+     * @param statusCode - HTTP status code associated with the error, if any.
+     */
     constructor(message: string, statusCode?: number);
 }
+/**
+ * Thrown when the API key is missing, invalid, or revoked (HTTP 401).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.store({ agentId: "...", content: "..." });
+ * } catch (e) {
+ *   if (e instanceof AuthenticationError) {
+ *     console.error("Check your API key");
+ *   }
+ * }
+ * ```
+ */
 declare class AuthenticationError extends Z3rnoError {
+    /**
+     * @param message - Description of the authentication failure.
+     */
     constructor(message: string);
 }
+/**
+ * Thrown when the client exceeds the API rate limit (HTTP 429).
+ *
+ * The {@link retryAfter} property indicates how many seconds to wait
+ * before retrying, as reported by the server's `Retry-After` header.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.recall({ agentId: "...", query: "..." });
+ * } catch (e) {
+ *   if (e instanceof RateLimitError) {
+ *     console.log(`Retry after ${e.retryAfter} seconds`);
+ *   }
+ * }
+ * ```
+ */
 declare class RateLimitError extends Z3rnoError {
+    /** Number of seconds to wait before retrying, per the Retry-After header. */
     retryAfter: number;
+    /**
+     * @param message - Description of the rate-limit error.
+     * @param retryAfter - Seconds to wait before retrying (defaults to 60).
+     */
     constructor(message: string, retryAfter?: number);
 }
+/**
+ * Thrown when the server rejects the request due to invalid input (HTTP 400 or 422).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.store({ agentId: "not-a-uuid", content: "" });
+ * } catch (e) {
+ *   if (e instanceof ValidationError) {
+ *     console.error(`Validation failed: ${e.message}`);
+ *   }
+ * }
+ * ```
+ */
 declare class ValidationError extends Z3rnoError {
+    /**
+     * @param message - Description of the validation failure.
+     * @param statusCode - HTTP status code (400 or 422, defaults to 400).
+     */
     constructor(message: string, statusCode?: number);
 }
+/**
+ * Thrown when the requested resource does not exist (HTTP 404).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.getMemory("non-existent-id");
+ * } catch (e) {
+ *   if (e instanceof NotFoundError) {
+ *     console.error("Memory not found");
+ *   }
+ * }
+ * ```
+ */
 declare class NotFoundError extends Z3rnoError {
+    /**
+     * @param message - Description of what was not found.
+     */
     constructor(message: string);
 }
+/**
+ * Thrown when the Z3rno API returns a server-side error (HTTP 5xx).
+ *
+ * The SDK automatically retries on 5xx errors with exponential backoff.
+ * This error is only thrown after all retries are exhausted.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.store({ agentId: "...", content: "..." });
+ * } catch (e) {
+ *   if (e instanceof ServerError) {
+ *     console.error(`Server error (${e.statusCode}): ${e.message}`);
+ *   }
+ * }
+ * ```
+ */
 declare class ServerError extends Z3rnoError {
+    /**
+     * @param message - Description of the server error.
+     * @param statusCode - HTTP status code (defaults to 500).
+     */
     constructor(message: string, statusCode?: number);
 }
+/**
+ * Thrown when a request exceeds the configured timeout duration.
+ *
+ * The SDK uses an {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortController | AbortController}
+ * to enforce timeouts. This error is thrown after all retries are exhausted.
+ *
+ * @example
+ * ```ts
+ * const client = new Z3rnoClient({ timeout: 5000 }); // 5 seconds
+ * try {
+ *   await client.recall({ agentId: "...", query: "..." });
+ * } catch (e) {
+ *   if (e instanceof Z3rnoTimeoutError) {
+ *     console.error(`Timed out after ${e.timeout}ms`);
+ *   }
+ * }
+ * ```
+ */
+declare class Z3rnoTimeoutError extends Z3rnoError {
+    /** The timeout duration in milliseconds that was exceeded. */
+    timeout: number;
+    /**
+     * @param message - Description of the timeout.
+     * @param timeout - The configured timeout value in milliseconds.
+     */
+    constructor(message: string, timeout: number);
+}
+/**
+ * Thrown when the SDK cannot establish a connection to the Z3rno API.
+ *
+ * This typically indicates a network issue, DNS failure, or the server
+ * being unreachable. The SDK retries connection errors with exponential
+ * backoff before throwing this error.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.store({ agentId: "...", content: "..." });
+ * } catch (e) {
+ *   if (e instanceof Z3rnoConnectionError) {
+ *     console.error("Cannot reach Z3rno API — check your network");
+ *   }
+ * }
+ * ```
+ */
+declare class Z3rnoConnectionError extends Z3rnoError {
+    /**
+     * @param message - Description of the connection failure.
+     */
+    constructor(message: string);
+}
 
-export { AuditEntry, AuditPageResponse, AuthenticationError, ForgetResponse, MemoryResponse, MemoryType, NotFoundError, RateLimitError, RecallResponse, RecallResultItem, RelationshipType, ServerError, StoreMemoryRequest, ValidationError, Z3rnoClient, type Z3rnoClientConfig, Z3rnoError };
+export { AuditEntry, AuditPageResponse, AuthenticationError, BatchStoreResponse, EndSessionResponse, ForgetResponse, MemoryHistoryResponse, MemoryResponse, MemoryType, MemoryVersion, NotFoundError, RateLimitError, RecallResponse, RecallResultItem, RelationshipType, ServerError, SessionResponse, StoreMemoryRequest, ValidationError, Z3rnoClient, type Z3rnoClientConfig, Z3rnoConnectionError, Z3rnoError, Z3rnoTimeoutError };