crewly 1.0.7 → 1.0.8

package/dist/cli/backend/src/services/memory/agent-memory.service.d.ts

@@ -0,0 +1,259 @@
+/**
+ * Agent Memory Service
+ *
+ * Manages agent-level persistent memory stored in ~/.crewly/agents/{agentId}/
+ * Provides storage for role knowledge, preferences, and performance metrics.
+ *
+ * @module services/memory/agent-memory.service
+ */
+import { AgentMemory, AgentPreferences, RoleKnowledgeEntry, PerformanceMetrics, type RoleKnowledgeCategory } from '../../types/memory.types.js';
+/**
+ * Metrics recorded when a task is completed
+ */
+export interface TaskCompletionMetrics {
+    /** Number of iterations to complete the task */
+    iterations: number;
+    /** Whether quality gates passed on first try */
+    qualityGatePassed: boolean;
+    /** Time to complete in minutes */
+    completionTimeMinutes?: number;
+    /** Type of task (e.g., 'bug-fix', 'feature', 'refactor') */
+    taskType?: string;
+}
+/**
+ * Interface for the Agent Memory Service
+ */
+export interface IAgentMemoryService {
+    initializeAgent(agentId: string, role: string): Promise<void>;
+    addRoleKnowledge(agentId: string, entry: Omit<RoleKnowledgeEntry, 'id' | 'createdAt'>): Promise<string>;
+    getRoleKnowledge(agentId: string, category?: RoleKnowledgeCategory): Promise<RoleKnowledgeEntry[]>;
+    reinforceKnowledge(agentId: string, entryId: string): Promise<void>;
+    updatePreferences(agentId: string, preferences: Partial<AgentPreferences>): Promise<void>;
+    getPreferences(agentId: string): Promise<AgentPreferences>;
+    recordTaskCompletion(agentId: string, metrics: TaskCompletionMetrics): Promise<void>;
+    recordError(agentId: string, errorPattern: string, resolution?: string): Promise<void>;
+    getPerformanceMetrics(agentId: string): Promise<PerformanceMetrics>;
+    generateAgentContext(agentId: string): Promise<string>;
+    pruneStaleEntries(agentId: string, olderThanDays: number): Promise<number>;
+    getAgentMemory(agentId: string): Promise<AgentMemory | null>;
+}
+/**
+ * Service for managing agent-level persistent memory
+ *
+ * Follows singleton pattern for consistent state management.
+ * Uses atomic file writes to prevent data corruption.
+ *
+ * @example
+ * ```typescript
+ * const memoryService = AgentMemoryService.getInstance();
+ * await memoryService.initializeAgent('dev-001', 'developer');
+ * await memoryService.addRoleKnowledge('dev-001', {
+ *   category: 'best-practice',
+ *   content: 'Always run tests before committing',
+ *   confidence: 0.5
+ * });
+ * ```
+ */
+export declare class AgentMemoryService implements IAgentMemoryService {
+    private static instance;
+    private static instanceHome;
+    private readonly basePath;
+    private readonly logger;
+    private readonly memoryCache;
+    private readonly CACHE_TTL_MS;
+    /**
+     * Creates a new AgentMemoryService instance
+     *
+     * @param crewlyHome - Optional custom path for crewly home directory
+     */
+    constructor(crewlyHome?: string);
+    /**
+     * Gets the singleton instance of AgentMemoryService
+     *
+     * @param crewlyHome - Optional custom path for crewly home directory
+     * @returns The singleton AgentMemoryService instance
+     */
+    static getInstance(crewlyHome?: string): AgentMemoryService;
+    /**
+     * Clears the singleton instance (useful for testing)
+     */
+    static clearInstance(): void;
+    /**
+     * Ensures the base agents directory exists
+     */
+    private ensureBaseDirectory;
+    /**
+     * Gets the path to an agent's memory directory
+     *
+     * @param agentId - The agent's unique identifier
+     * @returns Absolute path to the agent's memory directory
+     */
+    private getAgentPath;
+    /**
+     * Gets the path to a specific memory file for an agent
+     *
+     * @param agentId - The agent's unique identifier
+     * @param fileName - The memory file name
+     * @returns Absolute path to the memory file
+     */
+    private getFilePath;
+    /**
+     * Ensures an agent's directory structure exists
+     *
+     * @param agentId - The agent's unique identifier
+     */
+    private ensureAgentDirectory;
+    /**
+     * Invalidates the cache for an agent
+     *
+     * @param agentId - The agent's unique identifier
+     */
+    private invalidateCache;
+    /**
+     * Gets cached agent memory or loads from disk
+     *
+     * @param agentId - The agent's unique identifier
+     * @returns Agent memory or null if not found
+     */
+    private getCachedMemory;
+    /**
+     * Loads agent memory from disk
+     *
+     * @param agentId - The agent's unique identifier
+     * @returns Agent memory or null if not initialized
+     */
+    private loadAgentMemory;
+    /**
+     * Saves agent memory to disk
+     *
+     * @param agentId - The agent's unique identifier
+     * @param memory - Memory data to save
+     */
+    private saveAgentMemory;
+    /**
+     * Finds a similar existing knowledge entry to avoid duplicates
+     *
+     * @param knowledge - Existing knowledge entries
+     * @param content - Content to check for similarity
+     * @returns Matching entry or undefined
+     */
+    private findSimilarEntry;
+    /**
+     * Formats agent preferences for context output
+     *
+     * @param preferences - Agent preferences to format
+     * @returns Formatted string
+     */
+    private formatPreferences;
+    /**
+     * Initializes memory storage for a new agent
+     *
+     * @param agentId - Unique identifier for the agent
+     * @param role - Agent's role (e.g., 'developer', 'qa', 'pm')
+     *
+     * @example
+     * ```typescript
+     * await memoryService.initializeAgent('frontend-dev-001', 'frontend-developer');
+     * ```
+     */
+    initializeAgent(agentId: string, role: string): Promise<void>;
+    /**
+     * Adds a new role knowledge entry
+     *
+     * If similar content already exists, reinforces the existing entry instead.
+     *
+     * @param agentId - Agent's unique identifier
+     * @param entry - Knowledge entry (without id and createdAt)
+     * @returns ID of the created or reinforced entry
+     *
+     * @example
+     * ```typescript
+     * const entryId = await memoryService.addRoleKnowledge('dev-001', {
+     *   category: 'best-practice',
+     *   content: 'Always validate user input before processing',
+     *   confidence: 0.6,
+     *   learnedFrom: 'TICKET-456'
+     * });
+     * ```
+     */
+    addRoleKnowledge(agentId: string, entry: Omit<RoleKnowledgeEntry, 'id' | 'createdAt'>): Promise<string>;
+    /**
+     * Gets role knowledge entries, optionally filtered by category
+     *
+     * @param agentId - Agent's unique identifier
+     * @param category - Optional category filter
+     * @returns Array of knowledge entries sorted by confidence (descending)
+     */
+    getRoleKnowledge(agentId: string, category?: RoleKnowledgeCategory): Promise<RoleKnowledgeEntry[]>;
+    /**
+     * Reinforces a knowledge entry by increasing its confidence
+     *
+     * @param agentId - Agent's unique identifier
+     * @param entryId - ID of the entry to reinforce
+     */
+    reinforceKnowledge(agentId: string, entryId: string): Promise<void>;
+    /**
+     * Updates agent preferences (partial update supported)
+     *
+     * @param agentId - Agent's unique identifier
+     * @param preferences - Partial preferences to update
+     */
+    updatePreferences(agentId: string, preferences: Partial<AgentPreferences>): Promise<void>;
+    /**
+     * Gets the current agent preferences
+     *
+     * @param agentId - Agent's unique identifier
+     * @returns Agent preferences or defaults
+     */
+    getPreferences(agentId: string): Promise<AgentPreferences>;
+    /**
+     * Records a task completion and updates performance metrics
+     *
+     * @param agentId - Agent's unique identifier
+     * @param metrics - Task completion metrics
+     */
+    recordTaskCompletion(agentId: string, metrics: TaskCompletionMetrics): Promise<void>;
+    /**
+     * Records an error pattern encountered by the agent
+     *
+     * @param agentId - Agent's unique identifier
+     * @param errorPattern - Description of the error pattern
+     * @param resolution - Optional known resolution
+     */
+    recordError(agentId: string, errorPattern: string, resolution?: string): Promise<void>;
+    /**
+     * Gets the current performance metrics for an agent
+     *
+     * @param agentId - Agent's unique identifier
+     * @returns Performance metrics
+     */
+    getPerformanceMetrics(agentId: string): Promise<PerformanceMetrics>;
+    /**
+     * Generates a context string for prompt injection
+     *
+     * Compiles relevant agent memories, preferences, and performance data
+     * into a formatted string suitable for inclusion in agent prompts.
+     *
+     * @param agentId - Agent's unique identifier
+     * @returns Formatted context string
+     */
+    generateAgentContext(agentId: string): Promise<string>;
+    /**
+     * Prunes stale entries older than specified days
+     *
+     * Removes low-confidence entries that haven't been used recently.
+     *
+     * @param agentId - Agent's unique identifier
+     * @param olderThanDays - Number of days threshold
+     * @returns Number of entries removed
+     */
+    pruneStaleEntries(agentId: string, olderThanDays: number): Promise<number>;
+    /**
+     * Gets the complete agent memory object
+     *
+     * @param agentId - Agent's unique identifier
+     * @returns Full agent memory or null if not initialized
+     */
+    getAgentMemory(agentId: string): Promise<AgentMemory | null>;
+}
+//# sourceMappingURL=agent-memory.service.d.ts.map

package/dist/cli/backend/src/services/memory/agent-memory.service.d.ts.map

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