crewly 1.0.0

package/dist/backend/backend/src/services/memory/learning-accumulation.service.js

@@ -0,0 +1,336 @@
+/**
+ * Learning Accumulation Service
+ *
+ * Manages persistent learning files at two levels:
+ * - **Project-level:** `{projectPath}/.crewly/learning/what_worked.md` and `what_failed.md`
+ * - **Global-level:** `~/.crewly/learning/cross_project_insights.md`
+ *
+ * Learning entries are appended as timestamped markdown sections so agents can
+ * review past successes, failures, and cross-project insights when starting
+ * new tasks or resuming work.
+ *
+ * @module services/memory/learning-accumulation.service
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import { ensureDir } from '../../utils/file-io.utils.js';
+import { MEMORY_CONSTANTS, CREWLY_CONSTANTS } from '../../constants.js';
+import { LoggerService } from '../core/logger.service.js';
+/**
+ * Header written to a new `what_worked.md` file upon first success recording
+ */
+const WHAT_WORKED_HEADER = '# What Worked\n\nSuccessful patterns, approaches, and solutions.\n\n';
+/**
+ * Header written to a new `what_failed.md` file upon first failure recording
+ */
+const WHAT_FAILED_HEADER = '# What Failed\n\nFailed approaches, pitfalls, and things to avoid.\n\n';
+/**
+ * Header written to a new `cross_project_insights.md` file upon first insight recording
+ */
+const CROSS_PROJECT_INSIGHTS_HEADER = '# Cross-Project Insights\n\nLearnings that apply across multiple projects.\n\n';
+/**
+ * Service for accumulating learning entries into markdown files
+ *
+ * Follows the singleton pattern for consistent state management.
+ * Entries are appended atomically using `fs.appendFile` so concurrent
+ * writes from different agents do not corrupt the file.
+ *
+ * @example
+ * ```typescript
+ * const learningService = LearningAccumulationService.getInstance();
+ * await learningService.recordSuccess(
+ *   '/home/user/my-project',
+ *   'dev-001',
+ *   'developer',
+ *   'Parallel test execution reduced CI time by 40%',
+ *   'Applied to Jest with --maxWorkers=4'
+ * );
+ * ```
+ */
+export class LearningAccumulationService {
+    static instance = null;
+    logger = LoggerService.getInstance().createComponentLogger('LearningAccumulationService');
+    /**
+     * Private constructor to enforce singleton usage
+     */
+    constructor() {
+        // Intentionally empty -- all state is derived from the file system
+    }
+    /**
+     * Gets the singleton instance of LearningAccumulationService
+     *
+     * @returns The singleton LearningAccumulationService instance
+     */
+    static getInstance() {
+        if (!LearningAccumulationService.instance) {
+            LearningAccumulationService.instance = new LearningAccumulationService();
+        }
+        return LearningAccumulationService.instance;
+    }
+    /**
+     * Clears the singleton instance (useful for testing)
+     */
+    static clearInstance() {
+        LearningAccumulationService.instance = null;
+    }
+    // ========================= PRIVATE HELPERS =========================
+    /**
+     * Returns the absolute path to a project's learning directory
+     *
+     * @param projectPath - Absolute path to the project root
+     * @returns Absolute path to `{projectPath}/.crewly/learning`
+     */
+    getLearningDir(projectPath) {
+        return path.join(projectPath, CREWLY_CONSTANTS.PATHS.CREWLY_HOME, MEMORY_CONSTANTS.PATHS.LEARNING_DIR);
+    }
+    /**
+     * Returns the absolute path to the global learning directory
+     *
+     * @returns Absolute path to `~/.crewly/learning`
+     */
+    getGlobalLearningDir() {
+        return path.join(os.homedir(), CREWLY_CONSTANTS.PATHS.CREWLY_HOME, MEMORY_CONSTANTS.PATHS.GLOBAL_LEARNING_DIR);
+    }
+    /**
+     * Reads a file and returns its content, or null if the file does not exist
+     *
+     * Permission errors and other unexpected I/O failures are propagated.
+     *
+     * @param filePath - Absolute path to the file
+     * @returns File content as a string, or null when the file is missing
+     */
+    async safeReadFile(filePath) {
+        try {
+            return await fs.readFile(filePath, 'utf-8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Formats a learning entry as a markdown section
+     *
+     * The resulting block uses a level-3 heading with an ISO timestamp,
+     * followed by the description and optional context, terminated by
+     * a horizontal rule separator.
+     *
+     * @param agentId - Identifier of the agent that produced the learning
+     * @param role - Role of the agent (e.g. 'developer', 'qa')
+     * @param description - Human-readable description of the learning
+     * @param context - Optional additional context or notes
+     * @returns Formatted markdown entry string
+     *
+     * @example
+     * ```typescript
+     * const entry = this.formatEntry('dev-001', 'developer', 'Tests pass faster with parallelism');
+     * // ### [2026-02-09T12:00:00.000Z] developer / dev-001
+     * // Tests pass faster with parallelism
+     * // Context: None
+     * //
+     * // ---
+     * ```
+     */
+    formatEntry(agentId, role, description, context) {
+        const timestamp = new Date().toISOString();
+        return (`### [${timestamp}] ${role} / ${agentId}\n` +
+            `${description}\n` +
+            `Context: ${context || 'None'}\n` +
+            '\n---\n\n');
+    }
+    /**
+     * Ensures a learning file exists, creating it with the provided header if missing
+     *
+     * @param filePath - Absolute path to the markdown file
+     * @param header - Header content to write when creating the file
+     */
+    async ensureFileWithHeader(filePath, header) {
+        const existing = await this.safeReadFile(filePath);
+        if (existing === null) {
+            await fs.writeFile(filePath, header, 'utf-8');
+        }
+    }
+    // ========================= PUBLIC INTERFACE =========================
+    /**
+     * Records a successful pattern, approach, or solution to the project's
+     * `what_worked.md` learning file
+     *
+     * If the learning directory or file does not exist it is created automatically.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @param agentId - Identifier of the agent recording the success
+     * @param role - Role of the agent (e.g. 'developer', 'qa')
+     * @param description - Human-readable description of what worked
+     * @param context - Optional additional context or notes
+     *
+     * @example
+     * ```typescript
+     * await learningService.recordSuccess(
+     *   '/home/user/my-project',
+     *   'dev-001',
+     *   'developer',
+     *   'Using database transactions for batch inserts prevented partial writes',
+     *   'PostgreSQL with pg-promise library'
+     * );
+     * ```
+     */
+    async recordSuccess(projectPath, agentId, role, description, context) {
+        const learningDir = this.getLearningDir(projectPath);
+        await ensureDir(learningDir);
+        const filePath = path.join(learningDir, MEMORY_CONSTANTS.PATHS.WHAT_WORKED_FILE);
+        await this.ensureFileWithHeader(filePath, WHAT_WORKED_HEADER);
+        const entry = this.formatEntry(agentId, role, description, context);
+        await fs.appendFile(filePath, entry, 'utf-8');
+        this.logger.info('Recorded success learning', { projectPath, agentId, role });
+    }
+    /**
+     * Records a failed approach, pitfall, or mistake to the project's
+     * `what_failed.md` learning file
+     *
+     * If the learning directory or file does not exist it is created automatically.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @param agentId - Identifier of the agent recording the failure
+     * @param role - Role of the agent (e.g. 'developer', 'qa')
+     * @param description - Human-readable description of what failed
+     * @param context - Optional additional context or notes
+     *
+     * @example
+     * ```typescript
+     * await learningService.recordFailure(
+     *   '/home/user/my-project',
+     *   'qa-001',
+     *   'qa',
+     *   'Snapshot tests broke on every UI change, causing CI churn',
+     *   'Replaced with visual regression tests'
+     * );
+     * ```
+     */
+    async recordFailure(projectPath, agentId, role, description, context) {
+        const learningDir = this.getLearningDir(projectPath);
+        await ensureDir(learningDir);
+        const filePath = path.join(learningDir, MEMORY_CONSTANTS.PATHS.WHAT_FAILED_FILE);
+        await this.ensureFileWithHeader(filePath, WHAT_FAILED_HEADER);
+        const entry = this.formatEntry(agentId, role, description, context);
+        await fs.appendFile(filePath, entry, 'utf-8');
+        this.logger.info('Recorded failure learning', { projectPath, agentId, role });
+    }
+    /**
+     * Records a cross-project insight to the global
+     * `~/.crewly/learning/cross_project_insights.md` file
+     *
+     * Cross-project insights capture learnings that are not specific to a
+     * single project and can inform agent behaviour across the entire workspace.
+     *
+     * @param agentId - Identifier of the agent recording the insight
+     * @param role - Role of the agent (e.g. 'developer', 'qa')
+     * @param description - Human-readable description of the insight
+     * @param context - Optional additional context or notes
+     *
+     * @example
+     * ```typescript
+     * await learningService.recordCrossProjectInsight(
+     *   'dev-002',
+     *   'developer',
+     *   'TypeScript strict mode catches 30% more bugs at compile time',
+     *   'Observed across 4 projects in Q1 2026'
+     * );
+     * ```
+     */
+    async recordCrossProjectInsight(agentId, role, description, context) {
+        const globalDir = this.getGlobalLearningDir();
+        await ensureDir(globalDir);
+        const filePath = path.join(globalDir, MEMORY_CONSTANTS.PATHS.CROSS_PROJECT_INSIGHTS);
+        await this.ensureFileWithHeader(filePath, CROSS_PROJECT_INSIGHTS_HEADER);
+        const entry = this.formatEntry(agentId, role, description, context);
+        await fs.appendFile(filePath, entry, 'utf-8');
+        this.logger.info('Recorded cross-project insight', { agentId, role });
+    }
+    /**
+     * Reads the project's `what_worked.md` learning file
+     *
+     * When `tailChars` is specified only the last N characters of the file
+     * are returned, which is useful for startup briefing prompts that need
+     * only the most recent entries.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @param tailChars - Optional maximum number of trailing characters to return
+     * @returns File content (or tail thereof), or null if the file does not exist
+     *
+     * @example
+     * ```typescript
+     * // Get full file
+     * const all = await learningService.getSuccesses('/home/user/project');
+     *
+     * // Get last 2000 chars for a briefing
+     * const recent = await learningService.getSuccesses('/home/user/project', 2000);
+     * ```
+     */
+    async getSuccesses(projectPath, tailChars) {
+        const filePath = path.join(this.getLearningDir(projectPath), MEMORY_CONSTANTS.PATHS.WHAT_WORKED_FILE);
+        const content = await this.safeReadFile(filePath);
+        if (content === null) {
+            return null;
+        }
+        if (tailChars !== undefined && content.length > tailChars) {
+            return content.slice(-tailChars);
+        }
+        return content;
+    }
+    /**
+     * Reads the project's `what_failed.md` learning file
+     *
+     * When `tailChars` is specified only the last N characters of the file
+     * are returned, which is useful for startup briefing prompts that need
+     * only the most recent entries.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @param tailChars - Optional maximum number of trailing characters to return
+     * @returns File content (or tail thereof), or null if the file does not exist
+     *
+     * @example
+     * ```typescript
+     * const failures = await learningService.getFailures('/home/user/project', 1500);
+     * ```
+     */
+    async getFailures(projectPath, tailChars) {
+        const filePath = path.join(this.getLearningDir(projectPath), MEMORY_CONSTANTS.PATHS.WHAT_FAILED_FILE);
+        const content = await this.safeReadFile(filePath);
+        if (content === null) {
+            return null;
+        }
+        if (tailChars !== undefined && content.length > tailChars) {
+            return content.slice(-tailChars);
+        }
+        return content;
+    }
+    /**
+     * Reads the global `cross_project_insights.md` learning file
+     *
+     * When `tailChars` is specified only the last N characters of the file
+     * are returned, which is useful for startup briefing prompts.
+     *
+     * @param tailChars - Optional maximum number of trailing characters to return
+     * @returns File content (or tail thereof), or null if the file does not exist
+     *
+     * @example
+     * ```typescript
+     * const insights = await learningService.getCrossProjectInsights(3000);
+     * ```
+     */
+    async getCrossProjectInsights(tailChars) {
+        const filePath = path.join(this.getGlobalLearningDir(), MEMORY_CONSTANTS.PATHS.CROSS_PROJECT_INSIGHTS);
+        const content = await this.safeReadFile(filePath);
+        if (content === null) {
+            return null;
+        }
+        if (tailChars !== undefined && content.length > tailChars) {
+            return content.slice(-tailChars);
+        }
+        return content;
+    }
+}
+//# sourceMappingURL=learning-accumulation.service.js.map

package/dist/backend/backend/src/services/memory/learning-accumulation.service.js.map

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

package/dist/backend/backend/src/services/memory/memory.service.d.ts

@@ -0,0 +1,306 @@
+/**
+ * Memory Service Coordinator
+ *
+ * Provides a unified interface for both agent-level and project-level memory services.
+ * Handles cross-cutting concerns like logging, validation, and combined context generation.
+ *
+ * @module services/memory/memory.service
+ */
+import { IAgentMemoryService } from './agent-memory.service.js';
+import { IProjectMemoryService } from './project-memory.service.js';
+import type { KnowledgeDocumentSummary } from '../../types/knowledge.types.js';
+import type { PatternCategory, GotchaSeverity } from '../../types/memory.types.js';
+/**
+ * Categories for the unified remember operation
+ */
+export type RememberCategory = 'fact' | 'pattern' | 'decision' | 'gotcha' | 'preference' | 'relationship';
+/**
+ * Scope for memory operations
+ */
+export type MemoryScope = 'agent' | 'project' | 'both';
+/**
+ * Parameters for the remember operation
+ */
+export interface RememberParams {
+    /** Agent identifier */
+    agentId: string;
+    /** Project path (required for project scope) */
+    projectPath?: string;
+    /** Content to remember */
+    content: string;
+    /** Category of memory */
+    category: RememberCategory;
+    /** Scope: agent or project */
+    scope: 'agent' | 'project';
+    /** Additional metadata */
+    metadata?: {
+        /** Task ID where this was learned */
+        taskId?: string;
+        /** Title for patterns/decisions/gotchas */
+        title?: string;
+        /** Pattern category */
+        patternCategory?: PatternCategory;
+        /** Code example */
+        example?: string;
+        /** Related files */
+        files?: string[];
+        /** Rationale for decisions */
+        rationale?: string;
+        /** Alternatives considered for decisions */
+        alternatives?: string[];
+        /** Areas affected by decisions */
+        affectedAreas?: string[];
+        /** Solution for gotchas */
+        solution?: string;
+        /** Severity for gotchas */
+        severity?: GotchaSeverity;
+        /** Relationship type */
+        relationshipType?: 'depends-on' | 'uses' | 'extends' | 'implements' | 'calls' | 'imported-by';
+        /** Target component for relationships */
+        targetComponent?: string;
+    };
+}
+/**
+ * Parameters for the recall operation
+ */
+export interface RecallParams {
+    /** Agent identifier */
+    agentId: string;
+    /** Project path (required for project/both scope) */
+    projectPath?: string;
+    /** Context/query for finding relevant memories */
+    context: string;
+    /** Scope: agent, project, or both */
+    scope: MemoryScope;
+    /** Maximum number of results */
+    limit?: number;
+}
+/**
+ * Result of a recall operation
+ */
+export interface RecallResult {
+    /** Memories from agent level */
+    agentMemories: string[];
+    /** Memories from project level */
+    projectMemories: string[];
+    /** Combined formatted result */
+    combined: string;
+    /** Matching knowledge documents (optional, from knowledge base search) */
+    knowledgeDocuments?: KnowledgeDocumentSummary[];
+}
+/**
+ * Parameters for recording a learning
+ */
+export interface LearningParams {
+    /** Agent identifier */
+    agentId: string;
+    /** Agent's role */
+    agentRole: string;
+    /** Project path */
+    projectPath: string;
+    /** The learning content */
+    learning: string;
+    /** Related task/ticket ID */
+    relatedTask?: string;
+    /** Related file paths */
+    relatedFiles?: string[];
+}
+/**
+ * Interface for the unified Memory Service
+ */
+export interface IMemoryService {
+    remember(params: RememberParams): Promise<string>;
+    recall(params: RecallParams): Promise<RecallResult>;
+    getFullContext(agentId: string, projectPath: string): Promise<string>;
+    recordLearning(params: LearningParams): Promise<void>;
+    initializeForSession(agentId: string, role: string, projectPath: string): Promise<void>;
+    getAgentMemoryService(): IAgentMemoryService;
+    getProjectMemoryService(): IProjectMemoryService;
+}
+/**
+ * Unified Memory Service Coordinator
+ *
+ * Provides a single entry point for all memory operations, coordinating
+ * between agent-level and project-level memory services.
+ *
+ * @example
+ * ```typescript
+ * const memoryService = MemoryService.getInstance();
+ *
+ * // Initialize for a session
+ * await memoryService.initializeForSession('dev-001', 'developer', '/path/to/project');
+ *
+ * // Remember something
+ * await memoryService.remember({
+ *   agentId: 'dev-001',
+ *   projectPath: '/path/to/project',
+ *   content: 'Always use async/await instead of callbacks',
+ *   category: 'pattern',
+ *   scope: 'project',
+ *   metadata: { title: 'Async Pattern' }
+ * });
+ *
+ * // Get full context for prompts
+ * const context = await memoryService.getFullContext('dev-001', '/path/to/project');
+ * ```
+ */
+export declare class MemoryService implements IMemoryService {
+    private static instance;
+    private readonly agentMemory;
+    private readonly projectMemory;
+    private readonly logger;
+    /**
+     * Creates a new MemoryService instance
+     */
+    private constructor();
+    /**
+     * Gets the singleton instance of MemoryService
+     *
+     * @returns The singleton MemoryService instance
+     */
+    static getInstance(): MemoryService;
+    /**
+     * Clears the singleton instance (useful for testing)
+     */
+    static clearInstance(): void;
+    /**
+     * Gets the underlying AgentMemoryService
+     *
+     * @returns The AgentMemoryService instance
+     */
+    getAgentMemoryService(): IAgentMemoryService;
+    /**
+     * Gets the underlying ProjectMemoryService
+     *
+     * @returns The ProjectMemoryService instance
+     */
+    getProjectMemoryService(): IProjectMemoryService;
+    /**
+     * Maps RememberCategory to RoleKnowledgeCategory for agent memory
+     */
+    private mapToKnowledgeCategory;
+    /**
+     * Parses a preference string into AgentPreferences
+     */
+    private parsePreference;
+    /**
+     * Checks if a learning is role-relevant (should be stored in agent memory)
+     */
+    private isRoleRelevant;
+    /**
+     * Filters memories by relevance to a context
+     */
+    private filterRelevant;
+    /**
+     * Formats search results into strings
+     */
+    private formatSearchResults;
+    /**
+     * Combines agent and project memories into a formatted string
+     */
+    private combineMemories;
+    /**
+     * Unified remember operation - stores content in appropriate memory
+     *
+     * @param params - Remember parameters
+     * @returns ID of the stored memory entry
+     *
+     * @example
+     * ```typescript
+     * // Remember a pattern for the project
+     * await memoryService.remember({
+     *   agentId: 'dev-001',
+     *   projectPath: '/path/to/project',
+     *   content: 'Use error wrapper for all API endpoints',
+     *   category: 'pattern',
+     *   scope: 'project',
+     *   metadata: {
+     *     title: 'API Error Handling',
+     *     patternCategory: 'api',
+     *     example: 'handleApiError(handler)'
+     *   }
+     * });
+     * ```
+     */
+    remember(params: RememberParams): Promise<string>;
+    /**
+     * Stores memory at agent level
+     */
+    private rememberForAgent;
+    /**
+     * Stores memory at project level
+     */
+    private rememberForProject;
+    /**
+     * Unified recall operation - retrieves relevant memories
+     *
+     * @param params - Recall parameters
+     * @returns Recall results from appropriate scopes
+     *
+     * @example
+     * ```typescript
+     * const memories = await memoryService.recall({
+     *   agentId: 'dev-001',
+     *   projectPath: '/path/to/project',
+     *   context: 'error handling in API endpoints',
+     *   scope: 'both',
+     *   limit: 10
+     * });
+     * console.log(memories.combined);
+     * ```
+     */
+    recall(params: RecallParams): Promise<RecallResult>;
+    /**
+     * Searches knowledge documents across global and project scopes.
+     *
+     * @param context - Search query text
+     * @param projectPath - Optional project path for project-scoped search
+     * @returns Combined and deduplicated knowledge document summaries
+     */
+    private searchKnowledgeDocuments;
+    /**
+     * Generates combined context from both agent and project memory
+     *
+     * @param agentId - Agent identifier
+     * @param projectPath - Project path
+     * @returns Combined context string for prompt injection
+     */
+    getFullContext(agentId: string, projectPath: string): Promise<string>;
+    /**
+     * Records a learning to both project learnings and potentially agent memory
+     *
+     * @param params - Learning parameters
+     */
+    recordLearning(params: LearningParams): Promise<void>;
+    /**
+     * Initializes memory for a new session
+     *
+     * @param agentId - Agent identifier
+     * @param role - Agent's role
+     * @param projectPath - Project path
+     */
+    initializeForSession(agentId: string, role: string, projectPath: string): Promise<void>;
+    /**
+     * Recalls knowledge from all agents that have worked on a project
+     *
+     * Reads the project's agents-index.json, then searches each agent's role
+     * knowledge for entries relevant to the given context. Results are merged,
+     * deduplicated, and sorted by relevance.
+     *
+     * @param projectPath - Absolute path to the project
+     * @param context - Search context for relevance filtering
+     * @param limit - Maximum number of results (default 20)
+     * @returns Array of formatted memory strings from all agents
+     *
+     * @example
+     * ```typescript
+     * const teamKnowledge = await memoryService.recallFromAllAgents(
+     *   '/projects/app',
+     *   'authentication middleware',
+     *   15,
+     * );
+     * ```
+     */
+    recallFromAllAgents(projectPath: string, context: string, limit?: number): Promise<string[]>;
+}
+//# sourceMappingURL=memory.service.d.ts.map

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

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