@agenticc/storage-memory 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AI Agent Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# @ai-agent/storage-memory
+
+In-memory storage adapter for the AI Agent framework. This package provides simple, fast storage for conversation sessions and messages, suitable for development, testing, and simple applications.
+
+## Installation
+
+```bash
+npm install @ai-agent/storage-memory
+```
+
+## Usage
+
+### Session Management
+
+```typescript
+import { Agent } from '@ai-agent/core';
+import { SessionManager } from '@ai-agent/storage-memory';
+
+// Create agent
+const agent = new Agent(config);
+
+// Create session manager
+const sessionManager = new SessionManager();
+
+// Create a new session
+const sessionId = sessionManager.createSession({
+  metadata: { userId: '123' }
+});
+
+// Process a message
+const userMessage = 'Hello, agent!';
+sessionManager.addUserMessage(sessionId, userMessage);
+
+const response = await agent.chat(userMessage, {
+  sessionId,
+  history: sessionManager.getHistory(sessionId)
+});
+
+// Store the response
+sessionManager.addAssistantMessage(sessionId, response);
+```
+
+### Message Storage
+
+```typescript
+import { MessageStore } from '@ai-agent/storage-memory';
+
+// Create message store
+const messageStore = new MessageStore();
+
+// Store messages
+messageStore.storeUserMessage(sessionId, 'Hello!');
+const response = await agent.chat('Hello!', { sessionId });
+messageStore.storeAssistantMessage(sessionId, response);
+
+// Query messages
+const history = messageStore.getSessionHistory(sessionId);
+const recentMessages = messageStore.queryMessages({
+  sessionId,
+  limit: 10,
+  order: 'desc'
+});
+
+// Query tool calls
+const toolCalls = messageStore.queryToolCalls({
+  sessionId,
+  toolName: 'search',
+  success: true
+});
+```
+
+## Features
+
+- **Fast**: All data stored in memory for instant access
+- **Simple**: No database setup required
+- **Flexible**: Rich query API for messages and tool calls
+- **Type-safe**: Full TypeScript support
+
+## Limitations
+
+- **Not persistent**: Data is lost when the process exits
+- **Memory-bound**: Not suitable for large-scale applications
+- **Single-process**: Cannot share data across multiple processes
+
+For production applications, consider:
+- `@ai-agent/storage-prisma` - SQL database support
+- `@ai-agent/storage-mongodb` - MongoDB support
+- `@ai-agent/storage-redis` - Redis support
+
+## API Reference
+
+### SessionManager
+
+Manages conversation sessions with message history.
+
+#### Methods
+
+- `createSession(options?)` - Create a new session
+- `getSession(sessionId)` - Get session by ID
+- `getOrCreateSession(sessionId, options?)` - Get or create session
+- `hasSession(sessionId)` - Check if session exists
+- `querySessions(options?)` - Query sessions with filters
+- `getHistory(sessionId)` - Get conversation history
+- `addUserMessage(sessionId, content, metadata?)` - Add user message
+- `addAssistantMessage(sessionId, response, metadata?)` - Add assistant message
+- `addSystemMessage(sessionId, content)` - Add system message
+- `closeSession(sessionId)` - Mark session as inactive
+- `deleteSession(sessionId)` - Delete session
+- `clearSession(sessionId)` - Clear all messages in session
+- `updateMetadata(sessionId, metadata)` - Update session metadata
+
+### MessageStore
+
+Provides persistent storage for messages with rich query capabilities.
+
+#### Methods
+
+- `storeUserMessage(sessionId, content, metadata?)` - Store user message
+- `storeAssistantMessage(sessionId, response, metadata?)` - Store assistant message
+- `storeSystemMessage(sessionId, content)` - Store system message
+- `getMessage(messageId)` - Get message by ID
+- `queryMessages(options?)` - Query messages with filters
+- `getSessionHistory(sessionId)` - Get conversation history
+- `queryToolCalls(options?)` - Query tool calls with filters
+- `getToolCallsForMessage(messageId)` - Get tool calls for a message
+- `deleteMessage(messageId)` - Delete a message
+- `deleteSessionMessages(sessionId)` - Delete all messages in session
+- `getMessageCount(sessionId)` - Get message count for session
+- `getTotalMessageCount()` - Get total message count
+- `getTotalToolCallCount()` - Get total tool call count
+- `clear()` - Clear all data
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @ai-agent/storage-memory
+ *
+ * In-memory storage adapter for AI Agent framework.
+ * Suitable for development, testing, and simple applications.
+ *
+ * For production use, consider @ai-agent/storage-prisma or @ai-agent/storage-mongodb.
+ */
+export { SessionManager, createSessionManager, type Session, type Message, type CreateSessionOptions, type SessionQueryOptions, } from './session.js';
+export { MessageStore, createMessageStore, type StoredMessage, type StoredSession, type MessageQueryOptions, type ToolCallQueryOptions, type StoredToolCall, } from './message-store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,KAAK,OAAO,EACZ,KAAK,OAAO,EACZ,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,GACzB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,cAAc,GACpB,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * @ai-agent/storage-memory
+ *
+ * In-memory storage adapter for AI Agent framework.
+ * Suitable for development, testing, and simple applications.
+ *
+ * For production use, consider @ai-agent/storage-prisma or @ai-agent/storage-mongodb.
+ */
+// Session Management
+export { SessionManager, createSessionManager, } from './session.js';
+// Message Storage
+export { MessageStore, createMessageStore, } from './message-store.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,qBAAqB;AACrB,OAAO,EACL,cAAc,EACd,oBAAoB,GAKrB,MAAM,cAAc,CAAC;AAEtB,kBAAkB;AAClB,OAAO,EACL,YAAY,EACZ,kBAAkB,GAMnB,MAAM,oBAAoB,CAAC"}

package/dist/message-store.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Message Store
+ *
+ * Provides persistent storage for conversation messages.
+ * Supports storing user messages, agent responses, and tool call records.
+ *
+ * _Requirements: 9.2_
+ */
+import type { Message, Session } from './session.js';
+interface ToolCallRecord {
+    toolName: string;
+    arguments: Record<string, unknown>;
+    result: {
+        success: boolean;
+        content: string;
+        data?: unknown;
+    };
+}
+type ExecuteResponse = {
+    type: 'execute';
+    message: string;
+    data?: unknown;
+    toolCalls?: ToolCallRecord[];
+};
+type GenericAgentResponse = {
+    type: string;
+    message?: string;
+    data?: unknown;
+    toolCalls?: ToolCallRecord[];
+};
+type AgentResponse = ExecuteResponse | GenericAgentResponse;
+/**
+ * Stored message with additional persistence metadata
+ */
+export interface StoredMessage extends Message {
+    /** Session ID this message belongs to */
+    sessionId: string;
+    /** Whether the message has been persisted */
+    persisted: boolean;
+    /** Persistence timestamp */
+    persistedAt?: Date;
+}
+/**
+ * Stored session with persistence metadata
+ */
+export interface StoredSession extends Session {
+    /** Whether the session has been persisted */
+    persisted: boolean;
+    /** Persistence timestamp */
+    persistedAt?: Date;
+}
+/**
+ * Message query options
+ */
+export interface MessageQueryOptions {
+    /** Filter by session ID */
+    sessionId?: string;
+    /** Filter by role */
+    role?: 'user' | 'assistant' | 'system';
+    /** Filter by response type (for assistant messages) */
+    responseType?: string;
+    /** Filter by timestamp (after) */
+    after?: Date;
+    /** Filter by timestamp (before) */
+    before?: Date;
+    /** Include tool calls in results */
+    includeToolCalls?: boolean;
+    /** Maximum number of messages to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Sort order */
+    order?: 'asc' | 'desc';
+}
+/**
+ * Tool call query options
+ */
+export interface ToolCallQueryOptions {
+    /** Filter by session ID */
+    sessionId?: string;
+    /** Filter by tool name */
+    toolName?: string;
+    /** Filter by success status */
+    success?: boolean;
+    /** Filter by timestamp (after) */
+    after?: Date;
+    /** Filter by timestamp (before) */
+    before?: Date;
+    /** Maximum number of results */
+    limit?: number;
+}
+/**
+ * Stored tool call record with additional metadata
+ */
+export interface StoredToolCall extends ToolCallRecord {
+    /** Unique ID for this tool call */
+    id: string;
+    /** Session ID */
+    sessionId: string;
+    /** Message ID this tool call belongs to */
+    messageId: string;
+    /** Timestamp of the tool call */
+    timestamp: Date;
+}
+/**
+ * Message Store
+ *
+ * In-memory message store with support for persistence hooks.
+ * Can be extended with database persistence by implementing the
+ * MessagePersistence interface.
+ */
+export declare class MessageStore {
+    private messages;
+    private sessions;
+    private toolCalls;
+    private messagesBySession;
+    private toolCallsBySession;
+    private toolCallsByMessage;
+    /**
+     * Store a user message
+     *
+     * @param sessionId - Session ID
+     * @param content - Message content
+     * @param metadata - Optional metadata
+     * @returns The stored message
+     */
+    storeUserMessage(sessionId: string, content: string, metadata?: Record<string, unknown>): StoredMessage;
+    /**
+     * Store an assistant message with agent response
+     *
+     * @param sessionId - Session ID
+     * @param response - Agent response
+     * @param metadata - Optional metadata
+     * @returns The stored message
+     */
+    storeAssistantMessage(sessionId: string, response: AgentResponse, metadata?: Record<string, unknown>): StoredMessage;
+    /**
+     * Store a system message
+     *
+     * @param sessionId - Session ID
+     * @param content - Message content
+     * @returns The stored message
+     */
+    storeSystemMessage(sessionId: string, content: string): StoredMessage;
+    /**
+     * Store tool call records
+     *
+     * @param sessionId - Session ID
+     * @param messageId - Message ID
+     * @param toolCalls - Tool call records
+     */
+    private storeToolCalls;
+    /**
+     * Get a message by ID
+     *
+     * @param messageId - Message ID
+     * @returns The message or undefined
+     */
+    getMessage(messageId: string): StoredMessage | undefined;
+    /**
+     * Query messages with filters
+     *
+     * @param options - Query options
+     * @returns Array of matching messages
+     */
+    queryMessages(options?: MessageQueryOptions): StoredMessage[];
+    /**
+     * Get conversation history for a session
+     * Messages are returned in chronological order
+     *
+     * @param sessionId - Session ID
+     * @returns Array of messages ordered by timestamp
+     */
+    getSessionHistory(sessionId: string): StoredMessage[];
+    /**
+     * Query tool calls with filters
+     *
+     * @param options - Query options
+     * @returns Array of matching tool calls
+     */
+    queryToolCalls(options?: ToolCallQueryOptions): StoredToolCall[];
+    /**
+     * Get tool calls for a specific message
+     *
+     * @param messageId - Message ID
+     * @returns Array of tool calls
+     */
+    getToolCallsForMessage(messageId: string): StoredToolCall[];
+    /**
+     * Get a session by ID
+     *
+     * @param sessionId - Session ID
+     * @returns The session or undefined
+     */
+    getSession(sessionId: string): StoredSession | undefined;
+    /**
+     * Get all sessions
+     *
+     * @returns Array of all sessions
+     */
+    getAllSessions(): StoredSession[];
+    /**
+     * Delete a message
+     *
+     * @param messageId - Message ID
+     * @returns True if deleted
+     */
+    deleteMessage(messageId: string): boolean;
+    /**
+     * Delete all messages in a session
+     *
+     * @param sessionId - Session ID
+     * @returns Number of messages deleted
+     */
+    deleteSessionMessages(sessionId: string): number;
+    /**
+     * Get message count for a session
+     *
+     * @param sessionId - Session ID
+     * @returns Number of messages
+     */
+    getMessageCount(sessionId: string): number;
+    /**
+     * Get total message count across all sessions
+     *
+     * @returns Total number of messages
+     */
+    getTotalMessageCount(): number;
+    /**
+     * Get total tool call count
+     *
+     * @returns Total number of tool calls
+     */
+    getTotalToolCallCount(): number;
+    /**
+     * Clear all data
+     */
+    clear(): void;
+    /**
+     * Ensure a session exists
+     */
+    private ensureSession;
+    /**
+     * Add a message to storage
+     */
+    private addMessage;
+}
+/**
+ * Create a new MessageStore instance
+ */
+export declare function createMessageStore(): MessageStore;
+export {};
+//# sourceMappingURL=message-store.d.ts.map

package/dist/message-store.d.ts.map

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