onbuzz 3.3.0

package/src/tools/memoryTool.js

@@ -0,0 +1,554 @@
+/**
+ * Memory Tool - Persistent memory storage for agents
+ *
+ * Purpose:
+ * - Allow agents to store, retrieve, update, and delete persistent memories
+ * - Memories persist across sessions and agent restarts
+ * - Support expiration conditions (date-based or custom conditions)
+ * - Group memories by date for organized retrieval
+ *
+ * Actions:
+ * - add: Create a new memory
+ * - update: Update an existing memory
+ * - delete: Remove a memory
+ * - list: List memories with configurable detail level
+ * - read: Load a memory's full content into context
+ * - search: Search memories by title or description
+ * - stats: Get memory statistics
+ */
+
+import { BaseTool } from './baseTool.js';
+import { getMemoryService } from '../services/memoryService.js';
+
+class MemoryTool extends BaseTool {
+  constructor(config = {}, logger = null) {
+    super(config, logger);
+
+    this.memoryService = null;
+
+    // Tool metadata
+    this.requiresProject = false;
+    this.isAsync = false;
+    this.timeout = 30000; // 30 seconds
+  }
+
+  /**
+   * Initialize memory service lazily
+   */
+  async _ensureMemoryService() {
+    if (!this.memoryService) {
+      this.memoryService = getMemoryService(this.logger);
+      await this.memoryService.initialize();
+    }
+    return this.memoryService;
+  }
+
+  /**
+   * Get tool description for LLM consumption
+   * @returns {string} Tool description
+   */
+  getDescription() {
+    return `
+Memory Tool: Store and retrieve persistent memories that survive across sessions.
+
+USAGE:
+\`\`\`json
+{
+  "toolId": "memory",
+  "action": "<action>",
+  "parameters": { ... }
+}
+\`\`\`
+
+ACTIONS:
+
+1. ADD - Create a new memory
+\`\`\`json
+{
+  "toolId": "memory",
+  "action": "add",
+  "title": "User prefers TypeScript",
+  "description": "Programming language preference",
+  "content": "The user explicitly stated they prefer TypeScript over JavaScript.",
+  "expiration": null
+}
+\`\`\`
+
+Expiration options:
+- null or omit: Never expires
+- "2025-06-01": Expires on date (ISO format)
+- "When user changes preference": Custom condition (manually removed)
+
+2. UPDATE - Modify an existing memory
+\`\`\`json
+{
+  "toolId": "memory",
+  "action": "update",
+  "id": "mem-123-abc",
+  "title": "Updated title",
+  "description": "Updated description",
+  "content": "Updated content",
+  "expiration": "2025-12-31"
+}
+\`\`\`
+
+3. DELETE - Remove a memory
+\`\`\`json
+{
+  "toolId": "memory",
+  "action": "delete",
+  "id": "mem-123-abc"
+}
+\`\`\`
+
+4. LIST - List memories (grouped by date, newest first)
+\`\`\`json
+{
+  "toolId": "memory",
+  "action": "list",
+  "level": "titles"
+}
+\`\`\`
+
+Level options:
+- "titles": ID and title only (default, recommended)
+- "descriptions": ID, title, and description
+- "full": All fields including expiration and timestamps
+
+5. READ - Load a memory's full content
+\`\`\`json
+{
+  "toolId": "memory",
+  "action": "read",
+  "id": "mem-123-abc"
+}
+\`\`\`
+
+6. SEARCH - Find memories by keyword
+\`\`\`json
+{
+  "toolId": "memory",
+  "action": "search",
+  "query": "TypeScript"
+}
+\`\`\`
+
+7. STATS - Get memory statistics
+\`\`\`json
+{
+  "toolId": "memory",
+  "action": "stats"
+}
+\`\`\`
+
+BEST PRACTICES:
+- Use memories for important facts, preferences, or decisions that should persist
+- Keep titles concise and searchable
+- Use descriptions for quick context without loading full content
+- Set expiration dates for time-sensitive information
+- Use LIST with "titles" first, then READ specific memories as needed
+- Avoid storing sensitive data (API keys, passwords) in memories
+    `;
+  }
+
+  /**
+   * Parse parameters from tool command content
+   * @param {string} content - Raw tool command content
+   * @returns {Object} Parsed parameters
+   */
+  parseParameters(content) {
+    // Already parsed as JSON by the time it reaches here
+    return content;
+  }
+
+  /**
+   * Get required parameters based on action
+   * @returns {Array<string>}
+   */
+  getRequiredParameters() {
+    return ['action'];
+  }
+
+  /**
+   * Validate parameter types
+   * @param {Object} params
+   * @returns {Object}
+   */
+  validateParameterTypes(params) {
+    const errors = [];
+
+    if (params.action && typeof params.action !== 'string') {
+      errors.push('action must be a string');
+    }
+
+    if (params.id && typeof params.id !== 'string') {
+      errors.push('id must be a string');
+    }
+
+    if (params.title && typeof params.title !== 'string') {
+      errors.push('title must be a string');
+    }
+
+    if (params.description && typeof params.description !== 'string') {
+      errors.push('description must be a string');
+    }
+
+    if (params.content && typeof params.content !== 'string') {
+      errors.push('content must be a string');
+    }
+
+    if (params.query && typeof params.query !== 'string') {
+      errors.push('query must be a string');
+    }
+
+    if (params.level && !['titles', 'descriptions', 'full'].includes(params.level)) {
+      errors.push('level must be one of: titles, descriptions, full');
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  /**
+   * Custom parameter validation
+   * @param {Object} params
+   * @returns {Object}
+   */
+  customValidateParameters(params) {
+    const errors = [];
+    const validActions = ['add', 'update', 'delete', 'list', 'read', 'search', 'stats'];
+
+    if (!params.action) {
+      errors.push('action is required');
+    } else if (!validActions.includes(params.action)) {
+      errors.push(`action must be one of: ${validActions.join(', ')}`);
+    } else {
+      // Validate action-specific requirements
+      switch (params.action) {
+        case 'add':
+          if (!params.title) errors.push('title is required for add action');
+          if (!params.content) errors.push('content is required for add action');
+          break;
+        case 'update':
+          if (!params.id) errors.push('id is required for update action');
+          break;
+        case 'delete':
+          if (!params.id) errors.push('id is required for delete action');
+          break;
+        case 'read':
+          if (!params.id) errors.push('id is required for read action');
+          break;
+        case 'search':
+          if (!params.query) errors.push('query is required for search action');
+          break;
+      }
+    }
+
+    // Length limits
+    if (params.title && params.title.length > 200) {
+      errors.push('title cannot exceed 200 characters');
+    }
+
+    if (params.description && params.description.length > 500) {
+      errors.push('description cannot exceed 500 characters');
+    }
+
+    if (params.content && params.content.length > 10000) {
+      errors.push('content cannot exceed 10000 characters');
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  /**
+   * Execute tool with parsed parameters
+   * @param {Object} params
+   * @param {Object} context
+   * @returns {Promise<Object>}
+   */
+  async execute(params, context) {
+    const { action } = params;
+    const { agentId } = context;
+
+    if (!agentId) {
+      throw new Error('Agent ID is required for memory tool');
+    }
+
+    const memoryService = await this._ensureMemoryService();
+
+    try {
+      switch (action) {
+        case 'add':
+          return await this._executeAdd(memoryService, agentId, params);
+        case 'update':
+          return await this._executeUpdate(memoryService, agentId, params);
+        case 'delete':
+          return await this._executeDelete(memoryService, agentId, params);
+        case 'list':
+          return await this._executeList(memoryService, agentId, params);
+        case 'read':
+          return await this._executeRead(memoryService, agentId, params);
+        case 'search':
+          return await this._executeSearch(memoryService, agentId, params);
+        case 'stats':
+          return await this._executeStats(memoryService, agentId);
+        default:
+          throw new Error(`Unknown action: ${action}`);
+      }
+    } catch (error) {
+      this.logger?.error(`Memory tool execution failed: ${error.message}`, {
+        agentId,
+        action,
+        error: error.stack
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Execute ADD action
+   */
+  async _executeAdd(memoryService, agentId, params) {
+    const memory = await memoryService.addMemory(agentId, {
+      title: params.title,
+      description: params.description || '',
+      content: params.content,
+      expiration: params.expiration
+    });
+
+    return {
+      success: true,
+      action: 'add',
+      memory: {
+        id: memory.id,
+        title: memory.title,
+        createdAt: memory.createdAt,
+        expiration: memory.expiration
+      },
+      message: `Memory created: "${memory.title}" (${memory.id})`
+    };
+  }
+
+  /**
+   * Execute UPDATE action
+   */
+  async _executeUpdate(memoryService, agentId, params) {
+    const updates = {};
+    if (params.title !== undefined) updates.title = params.title;
+    if (params.description !== undefined) updates.description = params.description;
+    if (params.content !== undefined) updates.content = params.content;
+    if (params.expiration !== undefined) updates.expiration = params.expiration;
+
+    const memory = await memoryService.updateMemory(agentId, params.id, updates);
+
+    if (!memory) {
+      return {
+        success: false,
+        action: 'update',
+        message: `Memory not found: ${params.id}`
+      };
+    }
+
+    return {
+      success: true,
+      action: 'update',
+      memory: {
+        id: memory.id,
+        title: memory.title,
+        updatedAt: memory.updatedAt
+      },
+      message: `Memory updated: "${memory.title}"`
+    };
+  }
+
+  /**
+   * Execute DELETE action
+   */
+  async _executeDelete(memoryService, agentId, params) {
+    const deleted = await memoryService.deleteMemory(agentId, params.id);
+
+    if (!deleted) {
+      return {
+        success: false,
+        action: 'delete',
+        message: `Memory not found: ${params.id}`
+      };
+    }
+
+    return {
+      success: true,
+      action: 'delete',
+      message: `Memory deleted: ${params.id}`
+    };
+  }
+
+  /**
+   * Execute LIST action
+   */
+  async _executeList(memoryService, agentId, params) {
+    const level = params.level || 'titles';
+    const result = await memoryService.listMemories(agentId, level);
+
+    return {
+      success: true,
+      action: 'list',
+      level,
+      totalMemories: result.count,
+      memoriesByDate: result.grouped,
+      message: result.count === 0
+        ? 'No memories found'
+        : `Found ${result.count} memories`
+    };
+  }
+
+  /**
+   * Execute READ action
+   */
+  async _executeRead(memoryService, agentId, params) {
+    const memory = await memoryService.readMemory(agentId, params.id);
+
+    if (!memory) {
+      return {
+        success: false,
+        action: 'read',
+        message: `Memory not found: ${params.id}`
+      };
+    }
+
+    return {
+      success: true,
+      action: 'read',
+      memory: {
+        id: memory.id,
+        title: memory.title,
+        description: memory.description,
+        content: memory.content,
+        createdAt: memory.createdAt,
+        updatedAt: memory.updatedAt,
+        expiration: memory.expiration,
+        accessCount: memory.accessCount
+      },
+      message: `Memory loaded: "${memory.title}"`
+    };
+  }
+
+  /**
+   * Execute SEARCH action
+   */
+  async _executeSearch(memoryService, agentId, params) {
+    const results = await memoryService.searchMemories(agentId, params.query);
+
+    return {
+      success: true,
+      action: 'search',
+      query: params.query,
+      results,
+      message: results.length === 0
+        ? `No memories found matching "${params.query}"`
+        : `Found ${results.length} memories matching "${params.query}"`
+    };
+  }
+
+  /**
+   * Execute STATS action
+   */
+  async _executeStats(memoryService, agentId) {
+    const stats = await memoryService.getMemoryStats(agentId);
+
+    return {
+      success: true,
+      action: 'stats',
+      stats,
+      message: `Memory statistics: ${stats.totalMemories} total memories, ${stats.totalAccessCount} total accesses`
+    };
+  }
+
+  /**
+   * Get supported actions
+   * @returns {Array<string>}
+   */
+  getSupportedActions() {
+    return ['add', 'update', 'delete', 'list', 'read', 'search', 'stats'];
+  }
+
+  /**
+   * Get parameter schema
+   * @returns {Object}
+   */
+  getParameterSchema() {
+    return {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['add', 'update', 'delete', 'list', 'read', 'search', 'stats'],
+          description: 'Action to perform'
+        },
+        id: {
+          type: 'string',
+          description: 'Memory ID (required for update, delete, read)'
+        },
+        title: {
+          type: 'string',
+          maxLength: 200,
+          description: 'Memory title (required for add)'
+        },
+        description: {
+          type: 'string',
+          maxLength: 500,
+          description: 'One-line description'
+        },
+        content: {
+          type: 'string',
+          maxLength: 10000,
+          description: 'Full memory content (required for add)'
+        },
+        expiration: {
+          oneOf: [
+            { type: 'null' },
+            { type: 'string' }
+          ],
+          description: 'Expiration date (ISO) or condition string'
+        },
+        level: {
+          type: 'string',
+          enum: ['titles', 'descriptions', 'full'],
+          description: 'Detail level for list action'
+        },
+        query: {
+          type: 'string',
+          description: 'Search query (required for search)'
+        }
+      },
+      required: ['action']
+    };
+  }
+
+  /**
+   * Get tool capabilities
+   * @returns {Object}
+   */
+  getCapabilities() {
+    const baseCapabilities = super.getCapabilities();
+
+    return {
+      ...baseCapabilities,
+      persistent: true,
+      actions: this.getSupportedActions(),
+      useCases: [
+        'user-preferences',
+        'project-context',
+        'important-decisions',
+        'learned-patterns',
+        'task-history'
+      ]
+    };
+  }
+}
+
+export default MemoryTool;