@igniter-js/agents 0.1.0

package/dist/index-CX4IgrRt.d.mts

@@ -0,0 +1,2181 @@
+import { LanguageModel } from 'ai';
+
+/**
+ * @fileoverview Memory-related type definitions for the IgniterAgent library.
+ * This module contains all types, interfaces, and configurations for agent memory management.
+ *
+ * @description
+ * The memory system in IgniterAgent provides:
+ * - **Working Memory**: Persistent learned facts and context that agents maintain across conversations
+ * - **Conversation History**: Message storage for analytics, retrieval, and cross-session context
+ * - **Chat Sessions**: Metadata management for organizing conversations
+ * - **Auto-generation**: Automatic title and suggestion generation for enhanced UX
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   IgniterAgentMemoryProvider,
+ *   IgniterAgentMemoryConfig
+ * } from '@igniter-js/agents';
+ *
+ * // Implement a custom memory provider
+ * const customProvider: IgniterAgentMemoryProvider = {
+ *   getWorkingMemory: async ({ scope, identifier }) => {
+ *     // Fetch from your database
+ *     return { content: '...', updatedAt: new Date() };
+ *   },
+ *   updateWorkingMemory: async ({ scope, identifier, content }) => {
+ *     // Save to your database
+ *   }
+ * };
+ *
+ * // Configure memory for your agent
+ * const memoryConfig: IgniterAgentMemoryConfig = {
+ *   provider: customProvider,
+ *   working: { enabled: true, scope: 'chat' },
+ *   history: { enabled: true, limit: 100 },
+ *   chats: { enabled: true }
+ * };
+ * ```
+ *
+ * @module types/memory
+ * @packageDocumentation
+ */
+
+/**
+ * Type alias for UI messages compatible with Vercel AI SDK.
+ *
+ * @description
+ * This type serves as a placeholder for the UIMessage type from the Vercel AI SDK.
+ * Users can override this type when calling `getMessages<T>()` to use their own
+ * message type that matches their application's needs.
+ *
+ * @remarks
+ * The default `any` type allows flexibility when integrating with different
+ * frontend frameworks or message formats. For type safety, consider creating
+ * your own message interface that matches your UI requirements.
+ *
+ * @example
+ * ```typescript
+ * // Using with default type
+ * const messages = await provider.getMessages({ chatId: '123' });
+ *
+ * // Using with custom type
+ * interface CustomMessage {
+ *   id: string;
+ *   role: 'user' | 'assistant';
+ *   content: string;
+ *   timestamp: Date;
+ * }
+ * const typedMessages = await provider.getMessages<CustomMessage>({ chatId: '123' });
+ * ```
+ *
+ * @see {@link https://sdk.vercel.ai/docs/reference/ai-sdk-ui/use-chat | Vercel AI SDK useChat}
+ * @public
+ */
+type IgniterAgentUIMessage = unknown;
+/**
+ * Defines the role of a message in a conversation.
+ *
+ * @description
+ * Standard roles used in chat-based AI applications:
+ * - `user`: Messages from the human user
+ * - `assistant`: Messages from the AI agent
+ * - `system`: System-level instructions or context
+ *
+ * @public
+ */
+type IgniterAgentMessageRole = "user" | "assistant" | "system";
+/**
+ * Defines the scope at which memory is stored and retrieved.
+ *
+ * @description
+ * Memory scope determines the isolation level for stored data:
+ *
+ * - **`chat`** (Recommended): Memory is scoped per conversation/chat session.
+ *   Each chat has its own isolated memory that doesn't affect other chats.
+ *   Best for most use cases where context should be conversation-specific.
+ *
+ * - **`user`**: Memory is scoped per user across all their chats.
+ *   Useful for storing persistent user preferences or learned facts that
+ *   should carry over between different conversations.
+ *
+ * @example
+ * ```typescript
+ * // Chat-scoped memory: Each conversation is independent
+ * const chatMemory: IgniterAgentMemoryScope = 'chat';
+ *
+ * // User-scoped memory: Shared across all user's conversations
+ * const userMemory: IgniterAgentMemoryScope = 'user';
+ * ```
+ *
+ * @public
+ */
+type IgniterAgentMemoryScope = "chat" | "user";
+/**
+ * Represents persistent working memory that agents maintain.
+ *
+ * @description
+ * Working memory stores learned facts, preferences, and context that the agent
+ * accumulates over time. Unlike conversation history, working memory is a
+ * curated, summarized representation of important information.
+ *
+ * @property content - The textual content of the working memory
+ * @property updatedAt - Timestamp of the last update
+ *
+ * @example
+ * ```typescript
+ * const workingMemory: IgniterAgentWorkingMemory = {
+ *   content: `
+ *     ## User Preferences
+ *     - Prefers TypeScript over JavaScript
+ *     - Uses Vim keybindings
+ *     - Works on React projects primarily
+ *
+ *     ## Project Context
+ *     - Current project: E-commerce platform
+ *     - Tech stack: Next.js, Prisma, PostgreSQL
+ *   `,
+ *   updatedAt: new Date('2024-01-15T10:30:00Z')
+ * };
+ * ```
+ *
+ * @see {@link IgniterAgentWorkingMemoryConfig} for configuration options
+ * @public
+ */
+interface IgniterAgentWorkingMemory {
+    /**
+     * The textual content of the working memory.
+     *
+     * @description
+     * This is typically formatted as structured text (e.g., Markdown) containing
+     * organized information the agent has learned. The format is flexible and
+     * can be customized via the `template` configuration option.
+     */
+    content: string;
+    /**
+     * Timestamp of when the working memory was last updated.
+     *
+     * @description
+     * Used for tracking staleness and implementing cache invalidation strategies.
+     */
+    updatedAt: Date;
+}
+/**
+ * Represents a single message in a conversation history.
+ *
+ * @description
+ * Conversation messages are used for analytics, retrieval-augmented generation (RAG),
+ * and cross-session context. This is different from the real-time messages array
+ * passed to the agent, which comes directly from the frontend.
+ *
+ * @remarks
+ * The `content` field can be either a string or a parsed JSON object to support
+ * multimodal content (text, images, tool calls, etc.).
+ *
+ * @example
+ * ```typescript
+ * // Simple text message
+ * const textMessage: IgniterAgentConversationMessage = {
+ *   chatId: 'chat_123',
+ *   userId: 'user_456',
+ *   role: 'user',
+ *   content: 'How do I implement authentication in Next.js?',
+ *   timestamp: new Date()
+ * };
+ *
+ * // Multimodal message with structured content
+ * const multimodalMessage: IgniterAgentConversationMessage = {
+ *   chatId: 'chat_123',
+ *   role: 'assistant',
+ *   content: {
+ *     type: 'text',
+ *     text: 'Here is how to implement authentication...',
+ *     toolCalls: [{ name: 'searchDocs', result: '...' }]
+ *   },
+ *   timestamp: new Date()
+ * };
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentConversationMessage {
+    /**
+     * Unique identifier for the chat session this message belongs to.
+     *
+     * @description
+     * Used to group messages by conversation for retrieval and analytics.
+     */
+    chatId: string;
+    /**
+     * Optional identifier for the user who sent/received this message.
+     *
+     * @description
+     * Useful for multi-user applications or when implementing user-scoped
+     * memory and analytics.
+     */
+    userId?: string;
+    /**
+     * The role of the message sender.
+     *
+     * @see {@link IgniterAgentMessageRole}
+     */
+    role: IgniterAgentMessageRole;
+    /**
+     * The content of the message.
+     *
+     * @description
+     * Can be a simple string for text messages, or a complex object
+     * for multimodal content including images, tool calls, etc.
+     */
+    content: string | unknown;
+    /**
+     * When the message was created.
+     *
+     * @description
+     * Used for ordering messages and implementing time-based queries.
+     */
+    timestamp: Date;
+}
+/**
+ * Represents metadata for a chat session.
+ *
+ * @description
+ * Chat sessions provide organizational structure for conversations.
+ * They track metadata like titles, timestamps, and message counts
+ * without storing the actual message content.
+ *
+ * @example
+ * ```typescript
+ * const session: IgniterAgentChatSession = {
+ *   chatId: 'chat_abc123',
+ *   userId: 'user_xyz789',
+ *   title: 'Next.js Authentication Discussion',
+ *   createdAt: new Date('2024-01-15T09:00:00Z'),
+ *   updatedAt: new Date('2024-01-15T10:30:00Z'),
+ *   messageCount: 24
+ * };
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentChatSession {
+    /**
+     * Unique identifier for the chat session.
+     *
+     * @description
+     * This ID is used to reference the chat in all related operations
+     * like retrieving messages, updating titles, or deleting the chat.
+     */
+    chatId: string;
+    /**
+     * Optional identifier for the user who owns this chat.
+     *
+     * @description
+     * Used for filtering chats by user and implementing access control.
+     */
+    userId?: string;
+    /**
+     * Human-readable title for the chat.
+     *
+     * @description
+     * Can be automatically generated from the first message or set manually.
+     * Used in chat lists and navigation.
+     */
+    title?: string;
+    /**
+     * When the chat session was created.
+     */
+    createdAt: Date;
+    /**
+     * When the chat session was last updated.
+     *
+     * @description
+     * Updated whenever a new message is added to the chat.
+     */
+    updatedAt: Date;
+    /**
+     * Total number of messages in this chat.
+     *
+     * @description
+     * Useful for displaying chat statistics without loading all messages.
+     */
+    messageCount: number;
+}
+/**
+ * Configuration for automatic chat title generation.
+ *
+ * @description
+ * When enabled, the system automatically generates descriptive titles
+ * for new chat sessions based on the initial conversation content.
+ *
+ * @example
+ * ```typescript
+ * const titleConfig: IgniterAgentGenerateTitleConfig = {
+ *   enabled: true,
+ *   model: openai('gpt-4'),
+ *   instructions: `
+ *     Generate a concise, descriptive title (max 50 chars)
+ *     based on the conversation topic.
+ *   `
+ * };
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentGenerateTitleConfig {
+    /**
+     * Whether automatic title generation is enabled.
+     *
+     * @defaultValue false
+     */
+    enabled: boolean;
+    /**
+     * The language model to use for title generation.
+     *
+     * @description
+     * If not specified, falls back to the agent's default model.
+     * Consider using a smaller, faster model for title generation.
+     */
+    model?: LanguageModel;
+    /**
+     * Custom instructions for the title generation prompt.
+     *
+     * @description
+     * Override the default title generation prompt with custom instructions.
+     * Useful for enforcing specific title formats or styles.
+     */
+    instructions?: string;
+}
+/**
+ * Configuration for automatic prompt suggestions generation.
+ *
+ * @description
+ * When enabled, the system generates follow-up prompt suggestions
+ * after the assistant responds. These suggestions help guide users
+ * toward productive next steps in the conversation.
+ *
+ * @example
+ * ```typescript
+ * const suggestionsConfig: IgniterAgentGenerateSuggestionsConfig = {
+ *   enabled: true,
+ *   model: openai('gpt-3.5-turbo'),
+ *   limit: 3,
+ *   minResponseLength: 100,
+ *   contextWindow: 2,
+ *   instructions: `
+ *     Generate helpful follow-up questions that dive deeper
+ *     into the topic or explore related areas.
+ *   `
+ * };
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentGenerateSuggestionsConfig {
+    /**
+     * Whether automatic suggestion generation is enabled.
+     *
+     * @defaultValue false
+     */
+    enabled: boolean;
+    /**
+     * The language model to use for suggestion generation.
+     *
+     * @description
+     * If not specified, falls back to the agent's default model.
+     * Consider using a smaller, faster model for suggestions.
+     */
+    model?: LanguageModel;
+    /**
+     * Custom instructions for the suggestion generation prompt.
+     *
+     * @description
+     * Override the default suggestion prompt with custom instructions.
+     * Useful for generating domain-specific or styled suggestions.
+     */
+    instructions?: string;
+    /**
+     * Maximum number of suggestions to generate.
+     *
+     * @description
+     * Limits the number of follow-up prompts returned.
+     *
+     * @defaultValue 5
+     */
+    limit?: number;
+    /**
+     * Minimum assistant response length to trigger suggestion generation.
+     *
+     * @description
+     * Suggestions are only generated when the assistant's response
+     * exceeds this character count. Short responses (like confirmations)
+     * typically don't need follow-up suggestions.
+     *
+     * @defaultValue 100
+     */
+    minResponseLength?: number;
+    /**
+     * Number of recent message exchanges to use as context.
+     *
+     * @description
+     * Determines how many previous user-assistant exchanges are included
+     * when generating suggestions. Higher values provide more context
+     * but increase token usage.
+     *
+     * @defaultValue 1
+     */
+    contextWindow?: number;
+}
+/**
+ * Configuration for working memory features.
+ *
+ * @description
+ * Controls how the agent manages persistent learned facts and context.
+ *
+ * @example
+ * ```typescript
+ * const workingConfig: IgniterAgentWorkingMemoryConfig = {
+ *   enabled: true,
+ *   scope: 'chat',
+ *   template: `
+ *     ## Learned Facts
+ *     {{facts}}
+ *
+ *     ## User Preferences
+ *     {{preferences}}
+ *   `
+ * };
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentWorkingMemoryConfig {
+    /**
+     * Whether working memory is enabled.
+     *
+     * @description
+     * When enabled, the agent will store and retrieve persistent context.
+     */
+    enabled: boolean;
+    /**
+     * The scope at which working memory is stored.
+     *
+     * @see {@link IgniterAgentMemoryScope}
+     */
+    scope: IgniterAgentMemoryScope;
+    /**
+     * Optional template for formatting working memory content.
+     *
+     * @description
+     * Defines the structure of how working memory is organized and stored.
+     * Supports template variables that can be replaced at runtime.
+     */
+    template?: string;
+}
+/**
+ * Configuration for conversation history features.
+ *
+ * @description
+ * Controls how the agent stores and retrieves conversation messages.
+ * Note that history storage is separate from the real-time messages
+ * passed to the agent from the frontend.
+ *
+ * @example
+ * ```typescript
+ * const historyConfig: IgniterAgentHistoryConfig = {
+ *   enabled: true,
+ *   limit: 50  // Load last 50 messages for context
+ * };
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentHistoryConfig {
+    /**
+     * Whether conversation history storage is enabled.
+     *
+     * @description
+     * When enabled, messages are persisted for analytics and retrieval.
+     */
+    enabled: boolean;
+    /**
+     * Maximum number of messages to load from history.
+     *
+     * @description
+     * Limits how many historical messages are retrieved when building context.
+     * Lower values reduce token usage but may lose important context.
+     */
+    limit?: number;
+}
+/**
+ * Configuration for chat session management features.
+ *
+ * @description
+ * Controls chat session metadata, title generation, and suggestions.
+ *
+ * @example
+ * ```typescript
+ * const chatsConfig: IgniterAgentChatsConfig = {
+ *   enabled: true,
+ *   generateTitle: {
+ *     enabled: true,
+ *     model: openai('gpt-3.5-turbo')
+ *   },
+ *   generateSuggestions: {
+ *     enabled: true,
+ *     limit: 3
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentChatsConfig {
+    /**
+     * Whether chat session management is enabled.
+     */
+    enabled: boolean;
+    /**
+     * Configuration for automatic title generation.
+     *
+     * @see {@link IgniterAgentGenerateTitleConfig}
+     */
+    generateTitle?: IgniterAgentGenerateTitleConfig;
+    /**
+     * Configuration for automatic suggestion generation.
+     *
+     * @see {@link IgniterAgentGenerateSuggestionsConfig}
+     */
+    generateSuggestions?: IgniterAgentGenerateSuggestionsConfig;
+}
+/**
+ * Parameters for working memory operations.
+ *
+ * @description
+ * Used when getting or updating working memory through the provider.
+ *
+ * @typeParam TScope - The memory scope type
+ * @typeParam TIdentifier - The identifier type
+ *
+ * @public
+ */
+interface IgniterAgentWorkingMemoryParams<TScope extends string = string, TIdentifier extends string = string> {
+    /**
+     * The scope at which to access memory.
+     *
+     * @see {@link IgniterAgentMemoryScope}
+     */
+    scope: TScope;
+    /**
+     * The unique identifier for the memory (e.g., chatId or userId).
+     */
+    identifier: TIdentifier;
+}
+/**
+ * Parameters for updating working memory.
+ *
+ * @typeParam TScope - The memory scope type
+ * @typeParam TIdentifier - The identifier type
+ *
+ * @public
+ */
+interface IgniterAgentUpdateWorkingMemoryParams<TScope extends string = string, TIdentifier extends string = string> extends IgniterAgentWorkingMemoryParams<TScope, TIdentifier> {
+    /**
+     * The new content to store in working memory.
+     */
+    content: string;
+}
+/**
+ * Parameters for retrieving messages from history.
+ *
+ * @public
+ */
+interface IgniterAgentGetMessagesParams {
+    /**
+     * The chat session ID to retrieve messages from.
+     */
+    chatId: string;
+    /**
+     * Optional user ID to filter messages.
+     */
+    userId?: string;
+    /**
+     * Maximum number of messages to retrieve.
+     */
+    limit?: number;
+}
+/**
+ * Parameters for retrieving chat sessions.
+ *
+ * @public
+ */
+interface IgniterAgentGetChatsParams {
+    /**
+     * Optional user ID to filter chats.
+     */
+    userId?: string;
+    /**
+     * Optional search query to filter chats by title.
+     */
+    search?: string;
+    /**
+     * Maximum number of chats to retrieve.
+     */
+    limit?: number;
+}
+/**
+ * Memory Provider Interface for implementing custom storage backends.
+ *
+ * @description
+ * This interface defines the contract for any storage backend that can be used
+ * with the IgniterAgent memory system. Implement this interface to create
+ * custom providers for Redis, PostgreSQL, MongoDB, or any other storage solution.
+ *
+ * The interface has two required methods for working memory, and several
+ * optional methods for extended functionality like conversation history
+ * and chat session management.
+ *
+ * @typeParam TScope - The memory scope type (defaults to string)
+ * @typeParam TIdentifier - The identifier type (defaults to string)
+ *
+ * @example
+ * ```typescript
+ * import { IgniterAgentMemoryProvider } from '@igniter-js/agents';
+ * import { Redis } from 'ioredis';
+ *
+ * class RedisMemoryProvider implements IgniterAgentMemoryProvider {
+ *   private redis: Redis;
+ *
+ *   constructor(redis: Redis) {
+ *     this.redis = redis;
+ *   }
+ *
+ *   async getWorkingMemory({ scope, identifier }) {
+ *     const key = `memory:${scope}:${identifier}`;
+ *     const data = await this.redis.get(key);
+ *     if (!data) return null;
+ *
+ *     const parsed = JSON.parse(data);
+ *     return {
+ *       content: parsed.content,
+ *       updatedAt: new Date(parsed.updatedAt)
+ *     };
+ *   }
+ *
+ *   async updateWorkingMemory({ scope, identifier, content }) {
+ *     const key = `memory:${scope}:${identifier}`;
+ *     await this.redis.set(key, JSON.stringify({
+ *       content,
+ *       updatedAt: new Date().toISOString()
+ *     }));
+ *   }
+ *
+ *   // Implement optional methods as needed...
+ * }
+ * ```
+ *
+ * @see {@link IgniterAgentWorkingMemory} for the working memory structure
+ * @see {@link IgniterAgentConversationMessage} for message structure
+ * @see {@link IgniterAgentChatSession} for chat session structure
+ *
+ * @public
+ */
+interface IgniterAgentMemoryProvider<TScope extends string = string, TIdentifier extends string = string> {
+    /**
+     * Retrieves persistent working memory for the given scope and identifier.
+     *
+     * @description
+     * Fetches the accumulated working memory content. Returns null if no
+     * memory exists yet for the given scope/identifier combination.
+     *
+     * @param params - The scope and identifier to retrieve memory for
+     * @returns The working memory object, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const memory = await provider.getWorkingMemory({
+     *   scope: 'chat',
+     *   identifier: 'chat_123'
+     * });
+     *
+     * if (memory) {
+     *   console.log('Last updated:', memory.updatedAt);
+     *   console.log('Content:', memory.content);
+     * }
+     * ```
+     */
+    getWorkingMemory(params: IgniterAgentWorkingMemoryParams<TScope, TIdentifier>): Promise<IgniterAgentWorkingMemory | null>;
+    /**
+     * Updates persistent working memory for the given scope and identifier.
+     *
+     * @description
+     * Stores or updates the working memory content. This should create
+     * a new entry if one doesn't exist, or update the existing entry.
+     *
+     * @param params - The scope, identifier, and new content
+     *
+     * @example
+     * ```typescript
+     * await provider.updateWorkingMemory({
+     *   scope: 'chat',
+     *   identifier: 'chat_123',
+     *   content: `
+     *     ## Learned Facts
+     *     - User prefers TypeScript
+     *     - Working on a Next.js project
+     *   `
+     * });
+     * ```
+     */
+    updateWorkingMemory(params: IgniterAgentUpdateWorkingMemoryParams<TScope, TIdentifier>): Promise<void>;
+    /**
+     * Saves a message to the conversation history.
+     *
+     * @description
+     * Persists a single conversation message for analytics and retrieval.
+     * This is separate from the real-time messages array and is used for
+     * long-term storage and cross-session context.
+     *
+     * @remarks
+     * This method is optional. If not implemented, conversation history
+     * features will be unavailable.
+     *
+     * @param message - The message to save
+     *
+     * @example
+     * ```typescript
+     * await provider.saveMessage?.({
+     *   chatId: 'chat_123',
+     *   userId: 'user_456',
+     *   role: 'user',
+     *   content: 'How do I deploy to Vercel?',
+     *   timestamp: new Date()
+     * });
+     * ```
+     */
+    saveMessage?(message: IgniterAgentConversationMessage): Promise<void>;
+    /**
+     * Retrieves recent messages from conversation history.
+     *
+     * @description
+     * Fetches messages for a given chat, optionally filtered by user
+     * and limited to a specific count. Returns messages in UIMessage
+     * format compatible with the Vercel AI SDK.
+     *
+     * @remarks
+     * This method is optional. If not implemented, message retrieval
+     * features will be unavailable.
+     *
+     * @typeParam T - The message type to return (defaults to UIMessage)
+     * @param params - Query parameters for message retrieval
+     * @returns Array of messages in the specified format
+     *
+     * @example
+     * ```typescript
+     * // Get last 50 messages
+     * const messages = await provider.getMessages?.({
+     *   chatId: 'chat_123',
+     *   limit: 50
+     * });
+     *
+     * // Get with custom type
+     * interface MyMessage { id: string; text: string; }
+     * const typed = await provider.getMessages?.<MyMessage>({ chatId: '123' });
+     * ```
+     */
+    getMessages?<T = IgniterAgentUIMessage>(params: IgniterAgentGetMessagesParams): Promise<T[]>;
+    /**
+     * Saves or updates a chat session.
+     *
+     * @description
+     * Creates a new chat session or updates an existing one.
+     * Used for organizing conversations and tracking metadata.
+     *
+     * @remarks
+     * This method is optional. If not implemented, chat session
+     * management features will be unavailable.
+     *
+     * @param chat - The chat session to save
+     *
+     * @example
+     * ```typescript
+     * await provider.saveChat?.({
+     *   chatId: 'chat_123',
+     *   userId: 'user_456',
+     *   title: 'Vercel Deployment Help',
+     *   createdAt: new Date(),
+     *   updatedAt: new Date(),
+     *   messageCount: 1
+     * });
+     * ```
+     */
+    saveChat?(chat: IgniterAgentChatSession): Promise<void>;
+    /**
+     * Retrieves chat sessions for a user.
+     *
+     * @description
+     * Fetches a list of chat sessions, optionally filtered by user
+     * and/or search query. Returns all chats if no userId is provided.
+     *
+     * @remarks
+     * This method is optional. If not implemented, chat listing
+     * features will be unavailable.
+     *
+     * @param params - Query parameters for chat retrieval
+     * @returns Array of chat sessions matching the criteria
+     *
+     * @example
+     * ```typescript
+     * // Get all chats for a user
+     * const userChats = await provider.getChats?.({
+     *   userId: 'user_456',
+     *   limit: 20
+     * });
+     *
+     * // Search chats by title
+     * const searchResults = await provider.getChats?.({
+     *   userId: 'user_456',
+     *   search: 'deployment',
+     *   limit: 10
+     * });
+     * ```
+     */
+    getChats?(params: IgniterAgentGetChatsParams): Promise<IgniterAgentChatSession[]>;
+    /**
+     * Retrieves a specific chat session by ID.
+     *
+     * @description
+     * Fetches a single chat session's metadata by its unique identifier.
+     *
+     * @remarks
+     * This method is optional. If not implemented, single chat retrieval
+     * will be unavailable.
+     *
+     * @param chatId - The unique chat session ID
+     * @returns The chat session, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const chat = await provider.getChat?.('chat_123');
+     * if (chat) {
+     *   console.log('Title:', chat.title);
+     *   console.log('Messages:', chat.messageCount);
+     * }
+     * ```
+     */
+    getChat?(chatId: string): Promise<IgniterAgentChatSession | null>;
+    /**
+     * Updates the title of a chat session.
+     *
+     * @description
+     * Changes the title of an existing chat session. Useful for
+     * user-initiated title changes or auto-generated title updates.
+     *
+     * @remarks
+     * This method is optional. If not implemented, title updates
+     * will be unavailable.
+     *
+     * @param chatId - The unique chat session ID
+     * @param title - The new title for the chat
+     *
+     * @example
+     * ```typescript
+     * await provider.updateChatTitle?.(
+     *   'chat_123',
+     *   'Updated: Vercel & AWS Deployment Guide'
+     * );
+     * ```
+     */
+    updateChatTitle?(chatId: string, title: string): Promise<void>;
+    /**
+     * Deletes a chat session and all its associated messages.
+     *
+     * @description
+     * Permanently removes a chat session and all related data.
+     * This operation should be irreversible.
+     *
+     * @remarks
+     * This method is optional. If not implemented, chat deletion
+     * will be unavailable.
+     *
+     * @param chatId - The unique chat session ID to delete
+     *
+     * @example
+     * ```typescript
+     * // Delete a chat and all its messages
+     * await provider.deleteChat?.('chat_123');
+     * ```
+     */
+    deleteChat?(chatId: string): Promise<void>;
+}
+/**
+ * Complete memory configuration for an IgniterAgent.
+ *
+ * @description
+ * This is the main configuration object for setting up memory features
+ * in an agent. It combines provider configuration with feature-specific
+ * settings for working memory, history, and chat management.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   IgniterAgentMemoryConfig,
+ *   IgniterAgentMemoryProvider
+ * } from '@igniter-js/agents';
+ *
+ * const memoryConfig: IgniterAgentMemoryConfig = {
+ *   // Required: Storage provider implementation
+ *   provider: myRedisProvider,
+ *
+ *   // Optional: Working memory configuration
+ *   working: {
+ *     enabled: true,
+ *     scope: 'chat',
+ *     template: '## Context\n{{content}}'
+ *   },
+ *
+ *   // Optional: Conversation history
+ *   history: {
+ *     enabled: true,
+ *     limit: 100
+ *   },
+ *
+ *   // Optional: Chat session management
+ *   chats: {
+ *     enabled: true,
+ *     generateTitle: {
+ *       enabled: true,
+ *       model: openai('gpt-3.5-turbo')
+ *     },
+ *     generateSuggestions: {
+ *       enabled: true,
+ *       limit: 3,
+ *       minResponseLength: 100
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link IgniterAgentMemoryProvider} for implementing custom providers
+ * @see {@link IgniterAgentWorkingMemoryConfig} for working memory options
+ * @see {@link IgniterAgentHistoryConfig} for history options
+ * @see {@link IgniterAgentChatsConfig} for chat management options
+ *
+ * @public
+ */
+interface IgniterAgentMemoryConfig {
+    /**
+     * The storage provider implementation.
+     *
+     * @description
+     * Must implement the {@link IgniterAgentMemoryProvider} interface.
+     * This is the only required field in the configuration.
+     *
+     * @see {@link IgniterAgentMemoryProvider}
+     */
+    provider: IgniterAgentMemoryProvider;
+    /**
+     * Configuration for working memory (learned facts).
+     *
+     * @description
+     * Controls how the agent stores and retrieves persistent context
+     * across conversations.
+     *
+     * @see {@link IgniterAgentWorkingMemoryConfig}
+     */
+    working?: IgniterAgentWorkingMemoryConfig;
+    /**
+     * Configuration for conversation history.
+     *
+     * @description
+     * Controls message persistence for analytics and retrieval.
+     * Note that the agent still receives messages from the frontend;
+     * this is for additional persistence and cross-session context.
+     *
+     * @see {@link IgniterAgentHistoryConfig}
+     */
+    history?: IgniterAgentHistoryConfig;
+    /**
+     * Configuration for chat session management.
+     *
+     * @description
+     * Controls chat metadata, title generation, and prompt suggestions.
+     *
+     * @see {@link IgniterAgentChatsConfig}
+     */
+    chats?: IgniterAgentChatsConfig;
+}
+/**
+ * Runtime interface exposed by IgniterAgent for memory operations.
+ *
+ * @public
+ */
+interface IgniterAgentMemoryRuntime {
+    getWorkingMemory(params: IgniterAgentWorkingMemoryParams): Promise<IgniterAgentWorkingMemory | null>;
+    updateWorkingMemory(params: IgniterAgentUpdateWorkingMemoryParams): Promise<void>;
+    saveMessage(message: IgniterAgentConversationMessage): Promise<void>;
+    getMessages<T = IgniterAgentUIMessage>(params: IgniterAgentGetMessagesParams): Promise<T[]>;
+    saveChat(chat: IgniterAgentChatSession): Promise<void>;
+    getChats(params: IgniterAgentGetChatsParams): Promise<IgniterAgentChatSession[]>;
+    getChat(chatId: string): Promise<IgniterAgentChatSession | null>;
+    updateChatTitle(chatId: string, title: string): Promise<void>;
+    deleteChat(chatId: string): Promise<void>;
+}
+
+/**
+ * @fileoverview Type definitions for IgniterAgent memory adapters.
+ * This module contains interfaces for implementing storage backends.
+ *
+ * @module types/adapter
+ * @packageDocumentation
+ */
+
+/**
+ * Base options for adapter configuration.
+ *
+ * @description
+ * Common configuration options shared by all adapter implementations.
+ *
+ * @example
+ * ```typescript
+ * const baseOptions: IgniterAgentAdapterOptions = {
+ *   namespace: 'myapp',
+ * };
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentAdapterOptions {
+    /**
+     * Optional namespace prefix for all keys.
+     *
+     * @description
+     * Useful for multi-tenant applications or to avoid key collisions.
+     * The namespace is prepended to all storage keys.
+     *
+     * @example
+     * ```typescript
+     * // With namespace 'myapp', keys become:
+     * // 'myapp:memory:chat:123'
+     * // 'myapp:messages:chat:123'
+     * ```
+     */
+    namespace?: string;
+}
+/**
+ * Configuration options for the in-memory adapter.
+ *
+ * @description
+ * The in-memory adapter stores all data in JavaScript Maps.
+ * Useful for development, testing, or short-lived applications.
+ *
+ * @remarks
+ * Data is lost when the process restarts. For production use,
+ * consider using a persistent adapter like Redis or PostgreSQL.
+ *
+ * @example
+ * ```typescript
+ * const options: IgniterAgentInMemoryAdapterOptions = {
+ *   namespace: 'test',
+ *   debug: true,
+ *   maxMessages: 1000,
+ *   maxChats: 100
+ * };
+ *
+ * const adapter = new IgniterAgentInMemoryAdapter(options);
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentInMemoryAdapterOptions extends IgniterAgentAdapterOptions {
+    /**
+     * Maximum number of messages to store per chat.
+     *
+     * @description
+     * Limits memory usage by capping the number of messages.
+     * Oldest messages are removed when the limit is exceeded.
+     *
+     * @defaultValue 1000
+     */
+    maxMessages?: number;
+    /**
+     * Maximum number of chat sessions to store.
+     *
+     * @description
+     * Limits memory usage by capping the number of chats.
+     * Oldest chats are removed when the limit is exceeded.
+     *
+     * @defaultValue 100
+     */
+    maxChats?: number;
+}
+/**
+ * Configuration options for the Redis adapter.
+ *
+ * @description
+ * The Redis adapter provides persistent, high-performance storage
+ * suitable for production deployments.
+ *
+ * @example
+ * ```typescript
+ * import Redis from 'ioredis';
+ *
+ * const redis = new Redis({
+ *   host: 'localhost',
+ *   port: 6379
+ * });
+ *
+ * const options: IgniterAgentRedisAdapterOptions = {
+ *   client: redis,
+ *   namespace: 'igniter',
+ *   ttl: 86400 * 30, // 30 days
+ *   debug: false
+ * };
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentRedisAdapterOptions extends IgniterAgentAdapterOptions {
+    /**
+     * Redis client instance.
+     *
+     * @description
+     * An initialized Redis client (e.g., from ioredis or redis package).
+     * The adapter expects the client to be already connected.
+     */
+    client: unknown;
+    /**
+     * Time-to-live for stored data in seconds.
+     *
+     * @description
+     * Sets an expiration time for all stored data. Useful for
+     * automatic cleanup of old conversations.
+     *
+     * @defaultValue undefined (no expiration)
+     */
+    ttl?: number;
+    /**
+     * Redis key prefix.
+     *
+     * @description
+     * All keys are prefixed with this value. If not specified,
+     * falls back to the namespace option.
+     *
+     * @defaultValue 'igniter:agent'
+     */
+    keyPrefix?: string;
+}
+/**
+ * Abstract base class interface for memory adapters.
+ *
+ * @description
+ * Defines the contract that all memory adapters must implement.
+ * Extends the MemoryProvider interface with additional lifecycle methods.
+ *
+ * @typeParam TOptions - The adapter-specific options type
+ *
+ * @example
+ * ```typescript
+ * class CustomAdapter implements IgniterAgentMemoryAdapter<CustomAdapterOptions> {
+ *   private options: CustomAdapterOptions;
+ *
+ *   constructor(options: CustomAdapterOptions) {
+ *     this.options = options;
+ *   }
+ *
+ *   async connect(): Promise<void> {
+ *     // Initialize connection
+ *   }
+ *
+ *   async disconnect(): Promise<void> {
+ *     // Cleanup
+ *   }
+ *
+ *   // ... implement MemoryProvider methods
+ * }
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentMemoryAdapter<TOptions extends IgniterAgentAdapterOptions = IgniterAgentAdapterOptions> extends IgniterAgentMemoryProvider {
+    /**
+     * The adapter configuration options.
+     */
+    readonly options: TOptions;
+    /**
+     * Establishes connection to the storage backend.
+     *
+     * @description
+     * Called during adapter initialization. For adapters that
+     * maintain persistent connections (e.g., Redis), this establishes
+     * the connection. For in-memory adapters, this may be a no-op.
+     *
+     * @throws {IgniterAgentAdapterConnectionError} If connection fails
+     *
+     * @example
+     * ```typescript
+     * const adapter = new RedisAdapter(options);
+     * await adapter.connect();
+     * console.log('Connected to Redis');
+     * ```
+     */
+    connect?(): Promise<void>;
+    /**
+     * Closes connection to the storage backend.
+     *
+     * @description
+     * Called during cleanup. Should release all resources and
+     * close any open connections.
+     *
+     * @example
+     * ```typescript
+     * await adapter.disconnect();
+     * console.log('Disconnected from Redis');
+     * ```
+     */
+    disconnect?(): Promise<void>;
+    /**
+     * Checks if the adapter is connected and ready.
+     *
+     * @description
+     * Returns true if the adapter is ready to handle operations.
+     *
+     * @returns Whether the adapter is connected
+     */
+    isConnected?(): boolean;
+    /**
+     * Clears all data from the adapter.
+     *
+     * @description
+     * Removes all stored data. Use with caution in production.
+     * Primarily useful for testing and development.
+     *
+     * @example
+     * ```typescript
+     * // Clear all test data
+     * await adapter.clear();
+     * ```
+     */
+    clear?(): Promise<void>;
+}
+/**
+ * Factory function type for creating memory adapters.
+ *
+ * @description
+ * Used for dependency injection and adapter configuration.
+ *
+ * @typeParam TOptions - The adapter options type
+ * @typeParam TAdapter - The adapter type returned
+ *
+ * @example
+ * ```typescript
+ * const createRedisAdapter: IgniterAgentAdapterFactory<
+ *   IgniterAgentRedisAdapterOptions,
+ *   RedisAdapter
+ * > = (options) => {
+ *   return new RedisAdapter(options);
+ * };
+ * ```
+ *
+ * @public
+ */
+type IgniterAgentAdapterFactory<TOptions extends IgniterAgentAdapterOptions = IgniterAgentAdapterOptions, TAdapter extends IgniterAgentMemoryAdapter<TOptions> = IgniterAgentMemoryAdapter<TOptions>> = (options: TOptions) => TAdapter;
+/**
+ * Result of a batch operation.
+ *
+ * @description
+ * Used when performing operations that affect multiple records.
+ *
+ * @example
+ * ```typescript
+ * const result: IgniterAgentAdapterBatchResult = {
+ *   success: true,
+ *   affected: 42,
+ *   errors: []
+ * };
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentAdapterBatchResult {
+    /**
+     * Whether the batch operation completed successfully.
+     */
+    success: boolean;
+    /**
+     * Number of records affected by the operation.
+     */
+    affected: number;
+    /**
+     * Any errors that occurred during the batch operation.
+     */
+    errors: Error[];
+}
+/**
+ * Statistics about adapter storage usage.
+ *
+ * @description
+ * Provides insight into the adapter's current state and usage.
+ *
+ * @example
+ * ```typescript
+ * const stats = await adapter.getStats();
+ * console.log(`Storing ${stats.messageCount} messages`);
+ * console.log(`Across ${stats.chatCount} chats`);
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentAdapterStats {
+    /**
+     * Total number of working memory entries.
+     */
+    workingMemoryCount: number;
+    /**
+     * Total number of stored messages.
+     */
+    messageCount: number;
+    /**
+     * Total number of chat sessions.
+     */
+    chatCount: number;
+    /**
+     * Storage size in bytes (if available).
+     */
+    storageBytes?: number;
+    /**
+     * When the stats were collected.
+     */
+    timestamp: Date;
+}
+
+/**
+ * @fileoverview In-memory adapter for IgniterAgent memory storage.
+ * This module provides a simple in-memory implementation of the memory provider.
+ *
+ * @description
+ * The IgniterAgentInMemoryAdapter stores all data in JavaScript Maps,
+ * making it ideal for:
+ * - Development and testing
+ * - Short-lived applications
+ * - Prototyping
+ * - Demos
+ *
+ * **Important:** Data is lost when the process restarts. For production use,
+ * consider using a persistent adapter like Redis or PostgreSQL.
+ *
+ * @example
+ * ```typescript
+ * import { IgniterAgentInMemoryAdapter } from '@igniter-js/agents/adapters';
+ *
+ * // Create adapter
+ * const adapter = new IgniterAgentInMemoryAdapter({
+ *   namespace: 'myapp',
+ *   debug: true
+ * });
+ *
+ * // Use with memory config
+ * const memoryConfig: IgniterAgentMemoryConfig = {
+ *   provider: adapter,
+ *   working: { enabled: true, scope: 'chat' },
+ *   history: { enabled: true, limit: 100 }
+ * };
+ * ```
+ *
+ * @module adapters/memory
+ * @packageDocumentation
+ */
+
+/**
+ * In-memory implementation of the IgniterAgent memory provider.
+ *
+ * @description
+ * Stores all memory data in JavaScript Maps. Provides a complete implementation
+ * of the memory provider interface for development and testing purposes.
+ *
+ * **Features:**
+ * - Full implementation of all memory provider methods
+ * - Optional message/chat limits to control memory usage
+ * - Debug logging
+ * - Namespace support for multi-tenant applications
+ *
+ * **Limitations:**
+ * - Data is not persisted across process restarts
+ * - Not suitable for production with high availability requirements
+ * - No horizontal scaling support
+ *
+ * @example
+ * ```typescript
+ * import { IgniterAgentInMemoryAdapter } from '@igniter-js/agents/adapters';
+ *
+ * const adapter = new IgniterAgentInMemoryAdapter({
+ *   namespace: 'test',
+ *   debug: process.env.NODE_ENV === 'development',
+ *   maxMessages: 500,
+ *   maxChats: 50
+ * });
+ *
+ * // Store working memory
+ * await adapter.updateWorkingMemory({
+ *   scope: 'chat',
+ *   identifier: 'chat_123',
+ *   content: 'User prefers TypeScript'
+ * });
+ *
+ * // Retrieve working memory
+ * const memory = await adapter.getWorkingMemory({
+ *   scope: 'chat',
+ *   identifier: 'chat_123'
+ * });
+ *
+ * console.log(memory?.content); // 'User prefers TypeScript'
+ * ```
+ *
+ * @public
+ */
+declare class IgniterAgentInMemoryAdapter implements IgniterAgentMemoryAdapter<IgniterAgentInMemoryAdapterOptions> {
+    /**
+     * The adapter configuration options.
+     */
+    readonly options: Required<IgniterAgentInMemoryAdapterOptions>;
+    /**
+     * Storage for working memory.
+     * Key format: `{namespace}:{scope}:{identifier}`
+     * @internal
+     */
+    private readonly _workingMemory;
+    /**
+     * Storage for conversation messages.
+     * Key format: `{namespace}:{chatId}`
+     * @internal
+     */
+    private readonly _messages;
+    /**
+     * Storage for chat sessions.
+     * Key format: `{namespace}:{chatId}`
+     * @internal
+     */
+    private readonly _chats;
+    /**
+     * Creates a new IgniterAgentInMemoryAdapter.
+     *
+     * @param options - Adapter configuration
+     *
+     * @example
+     * ```typescript
+     * const adapter = new IgniterAgentInMemoryAdapter({
+     *   namespace: 'myapp',
+     *   maxMessages: 1000,
+     *   maxChats: 100
+     * });
+     * ```
+     */
+    constructor(options?: IgniterAgentInMemoryAdapterOptions);
+    /**
+     * Factory method to create a new adapter instance.
+     * @param options - Adapter configuration
+     * @returns A new IgniterAgentInMemoryAdapter instance
+     *
+     * @example
+     * ```typescript
+     * const adapter = IgniterAgentInMemoryAdapter.create({
+     *   namespace: 'test',
+     * });
+     * ```
+     */
+    static create(options?: IgniterAgentInMemoryAdapterOptions): IgniterAgentInMemoryAdapter;
+    /**
+     * Generates a storage key with namespace prefix.
+     * @internal
+     */
+    private _key;
+    /**
+     * Connects to the storage backend (no-op for in-memory).
+     *
+     * @description
+     * In-memory adapter doesn't require connection setup.
+     * This method exists for interface compatibility.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects from the storage backend (no-op for in-memory).
+     *
+     * @description
+     * In-memory adapter doesn't require disconnection.
+     * This method exists for interface compatibility.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Checks if the adapter is connected.
+     *
+     * @returns Always true for in-memory adapter
+     */
+    isConnected(): boolean;
+    /**
+     * Clears all stored data.
+     *
+     * @description
+     * Removes all working memory, messages, and chat sessions.
+     * Use with caution.
+     *
+     * @example
+     * ```typescript
+     * // Clear all data (useful for testing)
+     * await adapter.clear();
+     * ```
+     */
+    clear(): Promise<void>;
+    /**
+     * Gets working memory for a scope and identifier.
+     *
+     * @param params - The scope and identifier
+     * @returns The working memory or null if not found
+     *
+     * @example
+     * ```typescript
+     * const memory = await adapter.getWorkingMemory({
+     *   scope: 'chat',
+     *   identifier: 'chat_123'
+     * });
+     *
+     * if (memory) {
+     *   console.log('Content:', memory.content);
+     *   console.log('Updated:', memory.updatedAt);
+     * }
+     * ```
+     */
+    getWorkingMemory(params: IgniterAgentWorkingMemoryParams): Promise<IgniterAgentWorkingMemory | null>;
+    /**
+     * Updates working memory for a scope and identifier.
+     *
+     * @param params - The scope, identifier, and new content
+     *
+     * @example
+     * ```typescript
+     * await adapter.updateWorkingMemory({
+     *   scope: 'chat',
+     *   identifier: 'chat_123',
+     *   content: `
+     *     ## User Preferences
+     *     - Prefers TypeScript
+     *     - Uses VS Code
+     *   `
+     * });
+     * ```
+     */
+    updateWorkingMemory(params: IgniterAgentUpdateWorkingMemoryParams): Promise<void>;
+    /**
+     * Saves a message to the conversation history.
+     *
+     * @param message - The message to save
+     *
+     * @example
+     * ```typescript
+     * await adapter.saveMessage({
+     *   chatId: 'chat_123',
+     *   userId: 'user_456',
+     *   role: 'user',
+     *   content: 'How do I use TypeScript?',
+     *   timestamp: new Date()
+     * });
+     * ```
+     */
+    saveMessage(message: IgniterAgentConversationMessage): Promise<void>;
+    /**
+     * Gets messages from the conversation history.
+     *
+     * @typeParam T - The message type to return
+     * @param params - Query parameters
+     * @returns Array of messages
+     *
+     * @example
+     * ```typescript
+     * const messages = await adapter.getMessages({
+     *   chatId: 'chat_123',
+     *   limit: 50
+     * });
+     *
+     * for (const msg of messages) {
+     *   console.log(`[${msg.role}]: ${msg.content}`);
+     * }
+     * ```
+     */
+    getMessages<T = unknown>(params: IgniterAgentGetMessagesParams): Promise<T[]>;
+    /**
+     * Saves or updates a chat session.
+     *
+     * @param chat - The chat session to save
+     *
+     * @example
+     * ```typescript
+     * await adapter.saveChat({
+     *   chatId: 'chat_123',
+     *   userId: 'user_456',
+     *   title: 'TypeScript Help',
+     *   createdAt: new Date(),
+     *   updatedAt: new Date(),
+     *   messageCount: 0
+     * });
+     * ```
+     */
+    saveChat(chat: IgniterAgentChatSession): Promise<void>;
+    /**
+     * Gets chat sessions matching the query parameters.
+     *
+     * @param params - Query parameters
+     * @returns Array of chat sessions
+     *
+     * @example
+     * ```typescript
+     * const chats = await adapter.getChats({
+     *   userId: 'user_456',
+     *   search: 'typescript',
+     *   limit: 10
+     * });
+     *
+     * for (const chat of chats) {
+     *   console.log(`${chat.title} (${chat.messageCount} messages)`);
+     * }
+     * ```
+     */
+    getChats(params: IgniterAgentGetChatsParams): Promise<IgniterAgentChatSession[]>;
+    /**
+     * Gets a specific chat session by ID.
+     *
+     * @param chatId - The chat ID
+     * @returns The chat session or null if not found
+     *
+     * @example
+     * ```typescript
+     * const chat = await adapter.getChat('chat_123');
+     *
+     * if (chat) {
+     *   console.log('Title:', chat.title);
+     *   console.log('Messages:', chat.messageCount);
+     * }
+     * ```
+     */
+    getChat(chatId: string): Promise<IgniterAgentChatSession | null>;
+    /**
+     * Updates the title of a chat session.
+     *
+     * @param chatId - The chat ID
+     * @param title - The new title
+     *
+     * @example
+     * ```typescript
+     * await adapter.updateChatTitle('chat_123', 'New Title');
+     * ```
+     */
+    updateChatTitle(chatId: string, title: string): Promise<void>;
+    /**
+     * Deletes a chat session and its messages.
+     *
+     * @param chatId - The chat ID to delete
+     *
+     * @example
+     * ```typescript
+     * await adapter.deleteChat('chat_123');
+     * ```
+     */
+    deleteChat(chatId: string): Promise<void>;
+    /**
+     * Gets storage statistics.
+     *
+     * @returns Current storage stats
+     *
+     * @example
+     * ```typescript
+     * const stats = await adapter.getStats();
+     * console.log(`Storing ${stats.messageCount} messages`);
+     * console.log(`Across ${stats.chatCount} chats`);
+     * ```
+     */
+    getStats(): Promise<IgniterAgentAdapterStats>;
+}
+
+/**
+ * @fileoverview JSON file-based adapter for IgniterAgent memory storage.
+ * This module provides a simple file-based implementation of the memory provider.
+ *
+ * @description
+ * The IgniterAgentJSONFileAdapter stores all data in JSON files on the local filesystem,
+ * making it ideal for:
+ * - Development and testing
+ * - Single-machine deployments
+ * - Offline-first applications
+ * - Simple persistence without external databases
+ *
+ * **Directory Structure:**
+ * ```
+ * {dataDir}/
+ *   ├── working-memory.json     # All working memory entries
+ *   ├── chats.json              # All chat sessions
+ *   └── messages/
+ *       ├── {chatId}.json       # Messages for specific chat
+ *       └── ...
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { IgniterAgentJSONFileAdapter } from '@igniter-js/agents/adapters';
+ *
+ * // Create adapter
+ * const adapter = new IgniterAgentJSONFileAdapter({
+ *   dataDir: './data/agent-memory',
+ *   namespace: 'myapp',
+ *   autoSync: true
+ * });
+ *
+ * // Use with memory config
+ * const memoryConfig: IgniterAgentMemoryConfig = {
+ *   provider: adapter,
+ *   working: { enabled: true, scope: 'chat' },
+ *   history: { enabled: true, limit: 100 }
+ * };
+ * ```
+ *
+ * @module adapters/json-file
+ * @packageDocumentation
+ */
+
+/**
+ * Options for IgniterAgentJSONFileAdapter.
+ *
+ * @public
+ */
+interface IgniterAgentJSONFileAdapterOptions {
+    /**
+     * Directory path where JSON files will be stored.
+     * Will be created if it doesn't exist.
+     *
+     * @default './igniter-agent-memory'
+     */
+    dataDir?: string;
+    /**
+     * Namespace prefix for keys in the JSON files.
+     * Allows storing data for multiple apps/instances in the same directory.
+     *
+     * @default 'igniter'
+     */
+    namespace?: string;
+    /**
+     * Whether to automatically sync changes to disk.
+     * If false, call `sync()` manually after modifications.
+     *
+     * @default true
+     */
+    autoSync?: boolean;
+    /**
+     * Whether to enable debug logging.
+     *
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Maximum number of messages to store per chat.
+     * Older messages are removed when limit is exceeded.
+     *
+     * @default 1000
+     */
+    maxMessages?: number;
+    /**
+     * Maximum number of chat sessions to store.
+     * Older chats are removed when limit is exceeded.
+     *
+     * @default 100
+     */
+    maxChats?: number;
+}
+/**
+ * File-based (JSON) implementation of the IgniterAgent memory provider.
+ *
+ * @description
+ * Stores all memory data in JSON files on the local filesystem. Provides a complete
+ * implementation of the memory provider interface for development and testing purposes.
+ *
+ * **Features:**
+ * - Full implementation of all memory provider methods
+ * - Persistent storage across process restarts
+ * - Namespace support for multi-tenant applications
+ * - Optional automatic file synchronization
+ * - Message/chat limits to control storage
+ * - Debug logging
+ *
+ * **Limitations:**
+ * - Not suitable for concurrent access from multiple processes
+ * - Performance degrades with large numbers of messages/chats
+ * - Not suitable for high-frequency writes
+ *
+ * **File Format:**
+ * All data is stored in JSON format with ISO 8601 timestamps.
+ *
+ * @example
+ * ```typescript
+ * import { IgniterAgentJSONFileAdapter } from '@igniter-js/agents/adapters';
+ *
+ * const adapter = new IgniterAgentJSONFileAdapter({
+ *   dataDir: './memory',
+ *   namespace: 'myapp',
+ *   debug: true
+ * });
+ *
+ * // Connect to initialize directories
+ * await adapter.connect();
+ *
+ * // Store working memory
+ * await adapter.updateWorkingMemory({
+ *   scope: 'chat',
+ *   identifier: 'chat_123',
+ *   content: 'User prefers TypeScript'
+ * });
+ *
+ * // Retrieve working memory
+ * const memory = await adapter.getWorkingMemory({
+ *   scope: 'chat',
+ *   identifier: 'chat_123'
+ * });
+ *
+ * console.log(memory?.content); // 'User prefers TypeScript'
+ * ```
+ *
+ * @public
+ */
+declare class IgniterAgentJSONFileAdapter implements IgniterAgentMemoryAdapter<IgniterAgentJSONFileAdapterOptions> {
+    /**
+     * The adapter configuration options.
+     */
+    readonly options: Required<IgniterAgentJSONFileAdapterOptions>;
+    /**
+     * Whether the adapter is currently connected and ready to use.
+     * @internal
+     */
+    private _connected;
+    /**
+     * In-memory cache of working memory entries.
+     * @internal
+     */
+    private _workingMemoryCache;
+    /**
+     * In-memory cache of messages.
+     * @internal
+     */
+    private _messagesCache;
+    /**
+     * In-memory cache of chat sessions.
+     * @internal
+     */
+    private _chatsCache;
+    /**
+     * Creates a new IgniterAgentJSONFileAdapter.
+     *
+     * @param options - Adapter configuration
+     *
+     * @example
+     * ```typescript
+     * const adapter = new IgniterAgentJSONFileAdapter({
+     *   dataDir: './memory',
+     *   namespace: 'myapp'
+     * });
+     * ```
+     */
+    constructor(options?: IgniterAgentJSONFileAdapterOptions);
+    /**
+     * Factory method to create a new adapter instance.
+     * @param options - Adapter configuration
+     * @returns A new IgniterAgentJSONFileAdapter instance
+     *
+     * @example
+     * ```typescript
+     * const adapter = IgniterAgentJSONFileAdapter.create({
+     *   dataDir: './data',
+     * });
+     * ```
+     */
+    static create(options?: IgniterAgentJSONFileAdapterOptions): IgniterAgentJSONFileAdapter;
+    /**
+     * Logs debug messages if debug mode is enabled.
+     * @internal
+     */
+    private _log;
+    /**
+     * Gets the path for the working memory JSON file.
+     * @internal
+     */
+    private _getWorkingMemoryPath;
+    /**
+     * Gets the path for the chats JSON file.
+     * @internal
+     */
+    private _getChatsPath;
+    /**
+     * Gets the directory for message files.
+     * @internal
+     */
+    private _getMessagesDir;
+    /**
+     * Gets the path for a specific chat's messages JSON file.
+     * @internal
+     */
+    private _getMessagesPath;
+    /**
+     * Generates a cache key with namespace prefix.
+     * @internal
+     */
+    private _key;
+    /**
+     * Loads working memory from disk.
+     * @internal
+     */
+    private _loadWorkingMemory;
+    /**
+     * Loads chats from disk.
+     * @internal
+     */
+    private _loadChats;
+    /**
+     * Loads a specific chat's messages from disk.
+     * @internal
+     */
+    private _loadMessages;
+    /**
+     * Saves working memory to disk.
+     * @internal
+     */
+    private _saveWorkingMemory;
+    /**
+     * Saves chats to disk.
+     * @internal
+     */
+    private _saveChats;
+    /**
+     * Saves messages for a specific chat to disk.
+     * @internal
+     */
+    private _saveMessages;
+    /**
+     * Connects to the storage backend and loads data from disk.
+     *
+     * @description
+     * Creates necessary directories and loads all data into memory cache.
+     * Must be called before using the adapter.
+     *
+     * @throws {Error} If directory creation fails
+     *
+     * @example
+     * ```typescript
+     * const adapter = new IgniterAgentJSONFileAdapter();
+     * await adapter.connect();
+     * ```
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects from the storage backend.
+     *
+     * @description
+     * Syncs any pending changes to disk before disconnecting.
+     *
+     * @example
+     * ```typescript
+     * await adapter.disconnect();
+     * ```
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Checks if the adapter is connected and ready to use.
+     *
+     * @returns True if connected, false otherwise
+     */
+    isConnected(): boolean;
+    /**
+     * Manually syncs all in-memory data to disk.
+     *
+     * @description
+     * Called automatically if autoSync is enabled. Can be called manually
+     * to ensure data is persisted to disk.
+     *
+     * @example
+     * ```typescript
+     * await adapter.updateWorkingMemory({ ... });
+     * await adapter.sync(); // Ensure written to disk
+     * ```
+     */
+    sync(): Promise<void>;
+    /**
+     * Clears all stored data from disk and memory.
+     *
+     * @description
+     * Removes all working memory, messages, and chat sessions.
+     * Use with caution.
+     *
+     * @example
+     * ```typescript
+     * await adapter.clear();
+     * ```
+     */
+    clear(): Promise<void>;
+    /**
+     * Gets working memory for a scope and identifier.
+     *
+     * @param params - The scope and identifier
+     * @returns The working memory or null if not found
+     *
+     * @example
+     * ```typescript
+     * const memory = await adapter.getWorkingMemory({
+     *   scope: 'chat',
+     *   identifier: 'chat_123'
+     * });
+     *
+     * if (memory) {
+     *   console.log('Content:', memory.content);
+     * }
+     * ```
+     */
+    getWorkingMemory(params: IgniterAgentWorkingMemoryParams): Promise<IgniterAgentWorkingMemory | null>;
+    /**
+     * Updates working memory for a scope and identifier.
+     *
+     * @param params - The scope, identifier, and new content
+     *
+     * @example
+     * ```typescript
+     * await adapter.updateWorkingMemory({
+     *   scope: 'chat',
+     *   identifier: 'chat_123',
+     *   content: 'User prefers TypeScript'
+     * });
+     * ```
+     */
+    updateWorkingMemory(params: IgniterAgentUpdateWorkingMemoryParams): Promise<void>;
+    /**
+     * Saves a message to the conversation history.
+     *
+     * @param message - The message to save
+     *
+     * @example
+     * ```typescript
+     * await adapter.saveMessage({
+     *   chatId: 'chat_123',
+     *   userId: 'user_456',
+     *   role: 'user',
+     *   content: 'How do I use TypeScript?',
+     *   timestamp: new Date()
+     * });
+     * ```
+     */
+    saveMessage(message: IgniterAgentConversationMessage): Promise<void>;
+    /**
+     * Gets messages from the conversation history.
+     *
+     * @typeParam T - The message type to return
+     * @param params - Query parameters
+     * @returns Array of messages
+     *
+     * @example
+     * ```typescript
+     * const messages = await adapter.getMessages({
+     *   chatId: 'chat_123',
+     *   limit: 50
+     * });
+     *
+     * for (const msg of messages) {
+     *   console.log(`[${msg.role}]: ${msg.content}`);
+     * }
+     * ```
+     */
+    getMessages<T = unknown>(params: IgniterAgentGetMessagesParams): Promise<T[]>;
+    /**
+     * Saves or updates a chat session.
+     *
+     * @param chat - The chat session to save
+     *
+     * @example
+     * ```typescript
+     * await adapter.saveChat({
+     *   chatId: 'chat_123',
+     *   userId: 'user_456',
+     *   title: 'TypeScript Help',
+     *   createdAt: new Date(),
+     *   updatedAt: new Date(),
+     *   messageCount: 0
+     * });
+     * ```
+     */
+    saveChat(chat: IgniterAgentChatSession): Promise<void>;
+    /**
+     * Gets chat sessions matching the query parameters.
+     *
+     * @param params - Query parameters
+     * @returns Array of chat sessions
+     *
+     * @example
+     * ```typescript
+     * const chats = await adapter.getChats({
+     *   userId: 'user_456',
+     *   search: 'typescript',
+     *   limit: 10
+     * });
+     *
+     * for (const chat of chats) {
+     *   console.log(`${chat.title} (${chat.messageCount} messages)`);
+     * }
+     * ```
+     */
+    getChats(params: IgniterAgentGetChatsParams): Promise<IgniterAgentChatSession[]>;
+    /**
+     * Gets a specific chat session by ID.
+     *
+     * @param chatId - The chat ID
+     * @returns The chat session or null if not found
+     *
+     * @example
+     * ```typescript
+     * const chat = await adapter.getChat('chat_123');
+     *
+     * if (chat) {
+     *   console.log('Title:', chat.title);
+     * }
+     * ```
+     */
+    getChat(chatId: string): Promise<IgniterAgentChatSession | null>;
+    /**
+     * Updates the title of a chat session.
+     *
+     * @param chatId - The chat ID
+     * @param title - The new title
+     *
+     * @example
+     * ```typescript
+     * await adapter.updateChatTitle('chat_123', 'New Title');
+     * ```
+     */
+    updateChatTitle(chatId: string, title: string): Promise<void>;
+    /**
+     * Deletes a chat session and its messages.
+     *
+     * @param chatId - The chat ID to delete
+     *
+     * @example
+     * ```typescript
+     * await adapter.deleteChat('chat_123');
+     * ```
+     */
+    deleteChat(chatId: string): Promise<void>;
+    /**
+     * Gets storage statistics.
+     *
+     * @returns Current storage stats
+     *
+     * @example
+     * ```typescript
+     * const stats = await adapter.getStats();
+     * console.log(`Storing ${stats.messageCount} messages`);
+     * console.log(`Across ${stats.chatCount} chats`);
+     * ```
+     */
+    getStats(): Promise<IgniterAgentAdapterStats>;
+}
+
+export { type IgniterAgentAdapterStats as A, type IgniterAgentMemoryConfig as I, type IgniterAgentMemoryRuntime as a, type IgniterAgentWorkingMemoryParams as b, type IgniterAgentWorkingMemory as c, type IgniterAgentUpdateWorkingMemoryParams as d, type IgniterAgentConversationMessage as e, type IgniterAgentUIMessage as f, type IgniterAgentGetMessagesParams as g, type IgniterAgentChatSession as h, type IgniterAgentGetChatsParams as i, IgniterAgentInMemoryAdapter as j, type IgniterAgentJSONFileAdapterOptions as k, IgniterAgentJSONFileAdapter as l, type IgniterAgentMessageRole as m, type IgniterAgentMemoryScope as n, type IgniterAgentGenerateTitleConfig as o, type IgniterAgentGenerateSuggestionsConfig as p, type IgniterAgentWorkingMemoryConfig as q, type IgniterAgentHistoryConfig as r, type IgniterAgentChatsConfig as s, type IgniterAgentMemoryProvider as t, type IgniterAgentAdapterOptions as u, type IgniterAgentInMemoryAdapterOptions as v, type IgniterAgentRedisAdapterOptions as w, type IgniterAgentMemoryAdapter as x, type IgniterAgentAdapterFactory as y, type IgniterAgentAdapterBatchResult as z };