agents-library 1.1.0

package/dist/memory/file-storage-adapter.js

@@ -0,0 +1,352 @@
+/**
+ * File Storage Adapter
+ *
+ * Provides low-level file operations for JSON and Markdown files with:
+ * - Atomic writes (write to temp → rename)
+ * - File locking with exponential backoff
+ * - Error handling with Result<T, FileError> pattern
+ * - Graceful ENOENT handling (returns null instead of error)
+ */
+import { promises as fs } from 'fs';
+import { join, dirname } from 'path';
+import { ok, err } from '../common/result.js';
+import { FileErrorType } from '../common/types.js';
+/**
+ * File Storage Adapter
+ *
+ * Manages low-level file operations with atomic writes and error handling
+ */
+export class FileStorageAdapter {
+    dataPath;
+    /**
+     * In-memory locks for file operations to prevent race conditions
+     */
+    fileLocks = new Map();
+    /**
+     * Create File Storage Adapter
+     *
+     * @param dataPath - Base directory for file storage
+     */
+    constructor(dataPath) {
+        this.dataPath = dataPath;
+    }
+    /**
+     * Read JSON file
+     *
+     * @param filePath - Path to JSON file (relative to dataPath)
+     * @returns Result with parsed JSON data or null if file doesn't exist
+     */
+    async readJSON(filePath) {
+        const fullPath = join(this.dataPath, filePath);
+        try {
+            const content = await fs.readFile(fullPath, 'utf-8');
+            const data = JSON.parse(content);
+            return ok(data);
+        }
+        catch (error) {
+            // Gracefully handle file not found
+            if (error.code === 'ENOENT') {
+                return ok(null);
+            }
+            // Handle JSON parse errors
+            if (error instanceof SyntaxError) {
+                return err({
+                    type: FileErrorType.PARSE_ERROR,
+                    message: `Failed to parse JSON from ${filePath}: ${error.message}`,
+                    filePath: fullPath,
+                });
+            }
+            // Other file system errors
+            return err({
+                type: FileErrorType.READ_ERROR,
+                message: `Failed to read file ${filePath}: ${error.message}`,
+                filePath: fullPath,
+            });
+        }
+    }
+    /**
+     * Write JSON file with atomic write pattern
+     *
+     * Atomic pattern: write to temp file → rename to final file
+     * This prevents partial writes and corruption
+     *
+     * @param filePath - Path to JSON file (relative to dataPath)
+     * @param data - Data to serialize and write
+     * @returns Result indicating success or error
+     */
+    async writeJSON(filePath, data) {
+        const fullPath = join(this.dataPath, filePath);
+        const tempPath = `${fullPath}.tmp`;
+        try {
+            // Ensure parent directory exists
+            const dirResult = await this.ensureDirectory(dirname(filePath));
+            if (!dirResult.success) {
+                return dirResult;
+            }
+            // Serialize data
+            const content = JSON.stringify(data, null, 2);
+            // Write to temp file
+            await fs.writeFile(tempPath, content, 'utf-8');
+            // Atomic rename
+            await fs.rename(tempPath, fullPath);
+            return ok(undefined);
+        }
+        catch (error) {
+            // Clean up temp file on error
+            try {
+                await fs.unlink(tempPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            return err({
+                type: FileErrorType.WRITE_ERROR,
+                message: `Failed to write JSON file ${filePath}: ${error.message}`,
+                filePath: fullPath,
+            });
+        }
+    }
+    /**
+     * Acquire lock for a file path and execute operation
+     *
+     * Ensures only one operation at a time per file path
+     *
+     * @param filePath - Path to lock
+     * @param operation - Async operation to execute while locked
+     * @returns Result of the operation
+     */
+    async withFileLock(filePath, operation) {
+        // Wait for any existing lock on this file
+        const existingLock = this.fileLocks.get(filePath);
+        if (existingLock) {
+            await existingLock;
+            // After waiting, recursively try again (in case another operation grabbed the lock)
+            return this.withFileLock(filePath, operation);
+        }
+        // Create new lock
+        let releaseLock;
+        const lockPromise = new Promise((resolve) => {
+            releaseLock = resolve;
+        });
+        this.fileLocks.set(filePath, lockPromise);
+        try {
+            // Execute operation
+            return await operation();
+        }
+        finally {
+            // Release lock
+            releaseLock();
+            this.fileLocks.delete(filePath);
+        }
+    }
+    /**
+     * Append item to JSON array file
+     *
+     * Reads existing array, appends item, writes back atomically with file locking
+     *
+     * @param filePath - Path to JSON array file
+     * @param item - Item to append
+     * @returns Result indicating success or error
+     */
+    async appendToJSONArray(filePath, item) {
+        return this.withFileLock(filePath, async () => {
+            // Read existing array
+            const result = await this.readJSON(filePath);
+            if (!result.success) {
+                return result;
+            }
+            // Initialize empty array if file doesn't exist
+            const array = result.data || [];
+            // Append item
+            array.push(item);
+            // Write back atomically
+            return this.writeJSON(filePath, array);
+        });
+    }
+    /**
+     * Trim JSON array to keep only last N items
+     *
+     * Reads array, keeps last N items, returns removed items
+     *
+     * @param filePath - Path to JSON array file
+     * @param keepLast - Number of items to keep
+     * @returns Result with removed items or error
+     */
+    async trimJSONArray(filePath, keepLast) {
+        return this.withFileLock(filePath, async () => {
+            // Read existing array
+            const result = await this.readJSON(filePath);
+            if (!result.success) {
+                return result;
+            }
+            // Return empty array if file doesn't exist
+            if (result.data === null) {
+                return ok([]);
+            }
+            const array = result.data;
+            // No trimming needed if array is small enough
+            if (array.length <= keepLast) {
+                return ok([]);
+            }
+            // Calculate split point
+            const removeCount = array.length - keepLast;
+            const removed = array.slice(0, removeCount);
+            const kept = array.slice(removeCount);
+            // Write back kept items
+            const writeResult = await this.writeJSON(filePath, kept);
+            if (!writeResult.success) {
+                return writeResult;
+            }
+            return ok(removed);
+        });
+    }
+    /**
+     * Ensure directory exists (create if needed)
+     *
+     * @param dirPath - Directory path (relative to dataPath)
+     * @returns Result indicating success or error
+     */
+    async ensureDirectory(dirPath) {
+        const fullPath = join(this.dataPath, dirPath);
+        try {
+            await fs.mkdir(fullPath, { recursive: true });
+            return ok(undefined);
+        }
+        catch (error) {
+            return err({
+                type: FileErrorType.WRITE_ERROR,
+                message: `Failed to create directory ${dirPath}: ${error.message}`,
+                filePath: fullPath,
+            });
+        }
+    }
+    /**
+     * List files in directory
+     *
+     * @param dirPath - Directory path (relative to dataPath)
+     * @returns Result with array of filenames or error
+     */
+    async listFiles(dirPath) {
+        const fullPath = join(this.dataPath, dirPath);
+        try {
+            const files = await fs.readdir(fullPath);
+            return ok(files);
+        }
+        catch (error) {
+            // Return empty array if directory doesn't exist
+            if (error.code === 'ENOENT') {
+                return ok([]);
+            }
+            return err({
+                type: FileErrorType.READ_ERROR,
+                message: `Failed to list directory ${dirPath}: ${error.message}`,
+                filePath: fullPath,
+            });
+        }
+    }
+    /**
+     * Delete file
+     *
+     * @param filePath - File path (relative to dataPath)
+     * @returns Result indicating success or error
+     */
+    async deleteFile(filePath) {
+        const fullPath = join(this.dataPath, filePath);
+        try {
+            await fs.unlink(fullPath);
+            return ok(undefined);
+        }
+        catch (error) {
+            // Succeed silently if file doesn't exist
+            if (error.code === 'ENOENT') {
+                return ok(undefined);
+            }
+            return err({
+                type: FileErrorType.WRITE_ERROR,
+                message: `Failed to delete file ${filePath}: ${error.message}`,
+                filePath: fullPath,
+            });
+        }
+    }
+    /**
+     * Read Markdown file
+     *
+     * @param filePath - Path to Markdown file (relative to dataPath)
+     * @returns Result with file content or null if file doesn't exist
+     */
+    async readMarkdown(filePath) {
+        const fullPath = join(this.dataPath, filePath);
+        try {
+            const content = await fs.readFile(fullPath, 'utf-8');
+            return ok(content);
+        }
+        catch (error) {
+            // Gracefully handle file not found
+            if (error.code === 'ENOENT') {
+                return ok(null);
+            }
+            return err({
+                type: FileErrorType.READ_ERROR,
+                message: `Failed to read Markdown file ${filePath}: ${error.message}`,
+                filePath: fullPath,
+            });
+        }
+    }
+    /**
+     * Write Markdown file with atomic write pattern
+     *
+     * @param filePath - Path to Markdown file (relative to dataPath)
+     * @param content - Markdown content to write
+     * @returns Result indicating success or error
+     */
+    async writeMarkdown(filePath, content) {
+        const fullPath = join(this.dataPath, filePath);
+        const tempPath = `${fullPath}.tmp`;
+        try {
+            // Ensure parent directory exists
+            const dirResult = await this.ensureDirectory(dirname(filePath));
+            if (!dirResult.success) {
+                return dirResult;
+            }
+            // Write to temp file
+            await fs.writeFile(tempPath, content, 'utf-8');
+            // Atomic rename
+            await fs.rename(tempPath, fullPath);
+            return ok(undefined);
+        }
+        catch (error) {
+            // Clean up temp file on error
+            try {
+                await fs.unlink(tempPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            return err({
+                type: FileErrorType.WRITE_ERROR,
+                message: `Failed to write Markdown file ${filePath}: ${error.message}`,
+                filePath: fullPath,
+            });
+        }
+    }
+    /**
+     * Append content to Markdown file
+     *
+     * @param filePath - Path to Markdown file
+     * @param content - Content to append
+     * @returns Result indicating success or error
+     */
+    async appendToMarkdown(filePath, content) {
+        // Read existing content
+        const result = await this.readMarkdown(filePath);
+        if (!result.success) {
+            return result;
+        }
+        // Concatenate with newline
+        const existing = result.data || '';
+        const updated = existing ? `${existing}\n${content}` : content;
+        // Write back atomically
+        return this.writeMarkdown(filePath, updated);
+    }
+}
+//# sourceMappingURL=file-storage-adapter.js.map

package/dist/memory/file-storage-adapter.js.map

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

package/dist/memory/memory-service.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Memory Service - Hybrid Storage Orchestration
+ *
+ * Orchestrates hybrid memory system:
+ * - Short-term: Conversation context in JSON files (FileStorageAdapter)
+ * - Long-term: Summarized history in ArcadeDB (ArcadeDBAdapter)
+ * - Private: User preferences in JSON files
+ * - Public: Shared knowledge base in JSON files
+ *
+ * Features:
+ * - Automatic archival when conversation exceeds 20 messages
+ * - LLM-based summarization before archival
+ * - Graceful degradation if ArcadeDB unavailable
+ */
+import type { Result } from '../common/result.js';
+import type { ProviderManager } from '../providers/provider-manager.js';
+/**
+ * Message in conversation history
+ */
+export interface ConversationMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    timestamp: number;
+}
+/**
+ * Conversation context with metadata
+ */
+export interface ConversationContext {
+    userId: string;
+    channelId: string;
+    messages: ConversationMessage[];
+    lastUpdated: number;
+}
+/**
+ * User preference storage
+ */
+export interface UserPreference {
+    key: string;
+    value: any;
+    updatedAt: number;
+}
+/**
+ * Knowledge base entry
+ */
+export interface KnowledgeEntry {
+    id: string;
+    topic: string;
+    content: string;
+    tags: string[];
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Archived conversation summary
+ */
+export interface ArchivedSummary {
+    userId: string;
+    channelId: string;
+    summary: string;
+    messageCount: number;
+    startTime: number;
+    endTime: number;
+}
+/**
+ * Memory Service Error
+ */
+export interface MemoryError {
+    type: 'FILE_ERROR' | 'DATABASE_ERROR' | 'PROVIDER_ERROR' | 'VALIDATION_ERROR';
+    message: string;
+    originalError?: unknown;
+}
+/**
+ * Memory Service
+ *
+ * Manages hybrid memory storage with automatic archival and graceful degradation
+ */
+export declare class MemoryService {
+    private readonly providerManager?;
+    private fileStorage;
+    private dbAdapter;
+    private isDbAvailable;
+    private readonly archiveThreshold;
+    /**
+     * Create Memory Service
+     *
+     * @param memoryDataPath - Base directory for file storage
+     * @param arcadedbUrl - ArcadeDB connection URL (optional)
+     * @param arcadedbPassword - ArcadeDB root password (optional, defaults to 'root')
+     * @param providerManager - LLM provider for summarization (optional)
+     */
+    constructor(memoryDataPath: string, arcadedbUrl?: string, arcadedbPassword?: string, providerManager?: ProviderManager | undefined);
+    /**
+     * Initialize memory service
+     *
+     * Attempts to connect to ArcadeDB, logs warning if unavailable but continues
+     *
+     * @returns Result indicating initialization success
+     */
+    initialize(): Promise<Result<void, MemoryError>>;
+    /**
+     * Store message in conversation history
+     *
+     * Appends message to short-term storage and checks if archival is needed
+     *
+     * @param userId - User identifier
+     * @param channelId - Channel/conversation identifier
+     * @param message - Message to store
+     * @returns Result indicating success or error
+     */
+    storeMessage(userId: string, channelId: string, message: ConversationMessage): Promise<Result<void, MemoryError>>;
+    /**
+     * Retrieve conversation context
+     *
+     * Reads recent messages from short-term storage
+     *
+     * @param userId - User identifier
+     * @param channelId - Channel/conversation identifier
+     * @param limit - Maximum number of messages to retrieve (default: 20)
+     * @returns Result with conversation messages or error
+     */
+    retrieveContext(userId: string, channelId: string, limit?: number): Promise<Result<ConversationMessage[], MemoryError>>;
+    /**
+     * Store user preference
+     *
+     * Saves preference to user's preference file
+     *
+     * @param userId - User identifier
+     * @param key - Preference key
+     * @param value - Preference value
+     * @returns Result indicating success or error
+     */
+    storePreference(userId: string, key: string, value: any): Promise<Result<void, MemoryError>>;
+    /**
+     * Get user preference
+     *
+     * Retrieves preference value from user's preference file
+     *
+     * @param userId - User identifier
+     * @param key - Preference key
+     * @returns Result with preference value or null if not found
+     */
+    getPreference(userId: string, key: string): Promise<Result<any | null, MemoryError>>;
+    /**
+     * Store knowledge in public knowledge base
+     *
+     * Adds entry to shared knowledge base
+     *
+     * @param entry - Knowledge entry
+     * @returns Result indicating success or error
+     */
+    storeKnowledge(entry: KnowledgeEntry): Promise<Result<void, MemoryError>>;
+    /**
+     * Get knowledge from public knowledge base
+     *
+     * Retrieves entry by ID
+     *
+     * @param id - Knowledge entry ID
+     * @returns Result with knowledge entry or null if not found
+     */
+    getKnowledge(id: string): Promise<Result<KnowledgeEntry | null, MemoryError>>;
+    /**
+     * Check if conversation exceeds archival threshold
+     *
+     * If threshold exceeded, triggers archival to long-term storage
+     *
+     * @param userId - User identifier
+     * @param channelId - Channel identifier
+     */
+    private checkArchiveThreshold;
+    /**
+     * Archive conversation to long-term storage
+     *
+     * Summarizes conversation using LLM and stores in ArcadeDB
+     * Trims short-term storage to keep only recent messages
+     *
+     * @param userId - User identifier
+     * @param channelId - Channel identifier
+     * @param messages - Messages to archive
+     */
+    private archiveToLongTerm;
+    /**
+     * Summarize conversation using LLM
+     *
+     * @param messages - Messages to summarize
+     * @returns Result with summary text
+     */
+    private summarizeConversation;
+    /**
+     * Search long-term storage
+     *
+     * Queries ArcadeDB for archived conversations matching criteria
+     *
+     * @param userId - User identifier
+     * @param searchTerm - Search term for summary content
+     * @param limit - Maximum results to return (default: 10)
+     * @returns Result with archived summaries or error
+     */
+    searchLongTerm(userId: string, searchTerm: string, limit?: number): Promise<Result<ArchivedSummary[], MemoryError>>;
+    /**
+     * Dispose of memory service
+     *
+     * Disconnects from ArcadeDB and performs cleanup
+     *
+     * @returns Result indicating success or error
+     */
+    dispose(): Promise<Result<void, MemoryError>>;
+}
+//# sourceMappingURL=memory-service.d.ts.map

package/dist/memory/memory-service.d.ts.map

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