cognitive-core 0.0.2 → 0.1.2

package/src/memory/team-experience.ts

@@ -0,0 +1,604 @@
+/**
+ * Team Experience Memory - Storage for team trajectories and analysis results
+ *
+ * Stores complete team execution records (TeamTrajectory + analysis)
+ * for retrieval during future team formation and analysis.
+ * The team-level analog of ExperienceMemory.
+ */
+
+import type {
+  TeamTrajectory,
+  TeamPlaybook,
+  RolePlaybook,
+  TeamMetaObservation,
+  TeamMetaStrategy,
+} from '../types/index.js';
+import { JsonStore } from '../utils/storage.js';
+import { findTopK } from '../utils/similarity.js';
+
+/**
+ * Stored team experience — a team trajectory plus its analysis.
+ */
+export interface TeamExperience {
+  id: string;
+  teamTrajectory: TeamTrajectory;
+  analysis?: TeamAnalysisResult;
+  createdAt: Date;
+  lastAccessedAt?: Date;
+  usageCount: number;
+}
+
+/**
+ * Result from team trajectory analysis (produced by Phase 3-4 of the pipeline).
+ */
+export interface TeamAnalysisResult {
+  teamTrajectoryId: string;
+  /** Per-agent contribution assessments */
+  agentCredits: AgentCredit[];
+  /** Per-interaction value assessments */
+  interactionCredits: InteractionCredit[];
+  /** Coordination pattern analysis */
+  coordinationAssessment: CoordinationAssessment;
+  /** Per-role lessons */
+  roleLessons: RoleLessonEntry[];
+  /** Team-level lessons */
+  teamLessons: TeamLessonEntry[];
+  /** Meta-observation about team formation */
+  metaObservation: TeamMetaObservationEntry;
+  /** Metrics about the analysis process itself */
+  analysisMetrics: {
+    analysisTokens: number;
+    analysisTimeMs: number;
+    analysisToolCalls: number;
+  };
+}
+
+export interface AgentCredit {
+  agentId: string;
+  role: string;
+  contributionScore: number;
+  assessment: string;
+  roleAssessment: 'essential' | 'helpful' | 'neutral' | 'redundant';
+  /** Per-step attribution scores (from DESIGN doc) */
+  stepAttributions?: Array<{
+    stepIndex: number;
+    attribution: number; // -1 to 1
+    reasoning: string;
+  }>;
+}
+
+export interface InteractionCredit {
+  interactionId: string;
+  fromRole: string;
+  toRole: string;
+  value: 'helpful' | 'neutral' | 'harmful';
+  creditScore: number;
+  reasoning: string;
+  necessity: 'critical' | 'useful' | 'unnecessary' | 'harmful';
+  /** Interaction type (e.g., delegation, message) */
+  type?: string;
+  /** Quality of the content exchanged (0-1) */
+  contentQuality?: number;
+}
+
+export interface CoordinationAssessment {
+  quality: 'excellent' | 'good' | 'acceptable' | 'poor';
+  observedPatterns: { name: string; description: string; correlatedWithSuccess: boolean }[];
+  observedAntiPatterns: { name: string; description: string; impact: string; suggestedFix: string }[];
+  /** Comparison of expected vs actual coordination patterns */
+  patternComparison?: Array<{
+    expected: string;
+    observed: 'followed' | 'deviated' | 'absent';
+    impact: string;
+  }>;
+  /** Emergent coordination not in the original plan */
+  emergentCoordination?: Array<{
+    description: string;
+    wasHelpful: boolean;
+    shouldBeFormalized: boolean;
+  }>;
+  narrative: string;
+}
+
+export interface RoleLessonEntry {
+  role: string;
+  strengths: string[];
+  improvements: string[];
+  /** How this role interacted with other roles */
+  interactionAssessment?: Array<{
+    withRole: string;
+    interactionType: string;
+    quality: 'effective' | 'adequate' | 'poor';
+    observation: string;
+    recommendation: string;
+  }>;
+  /** Evidence from specific steps */
+  evidence?: Array<{
+    stepIndex: number;
+    description: string;
+  }>;
+}
+
+/** Subcategories for composition lessons */
+export type CompositionLessonCategory = 'role-necessity' | 'team-size' | 'topology' | 'model-selection';
+
+/** Subcategories for coordination lessons */
+export type CoordinationLessonCategory = 'delegation' | 'communication' | 'synchronization' | 'escalation';
+
+export interface TeamLessonEntry {
+  category: 'composition' | 'coordination' | 'delegation' | 'communication';
+  /** More specific subcategory */
+  subcategory?: CompositionLessonCategory | CoordinationLessonCategory;
+  lesson: string;
+  evidence: string;
+  confidence: number;
+}
+
+export interface TeamMetaObservationEntry {
+  formationEffective: boolean;
+  teamSizeAssessment: 'too-small' | 'right-sized' | 'too-large';
+  topologyAssessment: 'effective' | 'neutral' | 'hindering';
+  formationSuggestions: string[];
+  coordinationSuggestions: string[];
+}
+
+/**
+ * TeamExperienceMemory - Store and retrieve team execution experiences.
+ * Parallel to ExperienceMemory but for team-level data.
+ */
+export class TeamExperienceMemory {
+  private experienceStore: JsonStore<TeamExperience>;
+  private teamPlaybookStore: JsonStore<TeamPlaybook>;
+  private rolePlaybookStore: JsonStore<RolePlaybook>;
+  private metaObservationStore: JsonStore<TeamMetaObservation>;
+  private metaStrategyStore: JsonStore<TeamMetaStrategy>;
+  private initialized = false;
+
+  constructor(baseDir: string) {
+    this.experienceStore = new JsonStore<TeamExperience>(baseDir, 'team-experiences', {
+      autoSaveInterval: 60000,
+      pretty: true,
+    });
+    this.teamPlaybookStore = new JsonStore<TeamPlaybook>(baseDir, 'team-playbooks', {
+      autoSaveInterval: 60000,
+      pretty: true,
+    });
+    this.rolePlaybookStore = new JsonStore<RolePlaybook>(baseDir, 'role-playbooks', {
+      autoSaveInterval: 60000,
+      pretty: true,
+    });
+    this.metaObservationStore = new JsonStore<TeamMetaObservation>(baseDir, 'team-meta-observations', {
+      autoSaveInterval: 60000,
+      pretty: true,
+    });
+    this.metaStrategyStore = new JsonStore<TeamMetaStrategy>(baseDir, 'team-meta-strategies', {
+      autoSaveInterval: 60000,
+      pretty: true,
+    });
+  }
+
+  async init(): Promise<void> {
+    if (this.initialized) return;
+    await Promise.all([
+      this.experienceStore.init(),
+      this.teamPlaybookStore.init(),
+      this.rolePlaybookStore.init(),
+      this.metaObservationStore.init(),
+      this.metaStrategyStore.init(),
+    ]);
+    this.initialized = true;
+  }
+
+  // === TEAM EXPERIENCES ===
+
+  /**
+   * Store a team experience (trajectory + optional analysis).
+   */
+  async storeTeamExperience(params: {
+    teamTrajectory: TeamTrajectory;
+    analysis?: TeamAnalysisResult;
+  }): Promise<TeamExperience> {
+    await this.init();
+    const experience: TeamExperience = {
+      id: params.teamTrajectory.id,
+      teamTrajectory: params.teamTrajectory,
+      analysis: params.analysis,
+      createdAt: new Date(),
+      usageCount: 0,
+    };
+    this.experienceStore.set(experience.id, experience);
+    await this.experienceStore.save(experience.id);
+    return experience;
+  }
+
+  /**
+   * Get a team experience by ID.
+   */
+  async getTeamExperience(id: string): Promise<TeamExperience | undefined> {
+    await this.init();
+    return this.experienceStore.get(id);
+  }
+
+  /**
+   * Find team experiences similar to a given objective.
+   */
+  async findSimilarTeamExperiences(
+    query: string,
+    options?: {
+      k?: number;
+      domain?: string;
+      topology?: string;
+      successOnly?: boolean;
+    }
+  ): Promise<Array<{ experience: TeamExperience; score: number }>> {
+    await this.init();
+
+    const k = options?.k ?? 4;
+    let experiences = this.experienceStore.values();
+
+    if (options?.domain) {
+      experiences = experiences.filter((e) => e.teamTrajectory.domain === options.domain);
+    }
+    if (options?.topology) {
+      experiences = experiences.filter(
+        (e) => e.teamTrajectory.topologyType === options.topology
+      );
+    }
+    if (options?.successOnly) {
+      experiences = experiences.filter((e) => e.teamTrajectory.outcome.success);
+    }
+
+    return findTopK(
+      query,
+      experiences,
+      (e) => e.teamTrajectory.objective,
+      k
+    ).map(({ item, score }) => ({ experience: item, score }));
+  }
+
+  /**
+   * Get all team experiences.
+   */
+  async getAllTeamExperiences(): Promise<TeamExperience[]> {
+    await this.init();
+    return this.experienceStore.values();
+  }
+
+  /**
+   * Record usage of a team experience (for value-based pruning).
+   */
+  async recordTeamExperienceUsage(id: string): Promise<void> {
+    await this.init();
+    const existing = this.experienceStore.get(id);
+    if (existing) {
+      existing.usageCount++;
+      existing.lastAccessedAt = new Date();
+      this.experienceStore.set(id, existing);
+    }
+  }
+
+  /**
+   * Count team experiences.
+   */
+  async countTeamExperiences(): Promise<number> {
+    await this.init();
+    return this.experienceStore.size();
+  }
+
+  // === TEAM PLAYBOOKS ===
+
+  /**
+   * Store a team playbook.
+   */
+  async storeTeamPlaybook(playbook: TeamPlaybook): Promise<void> {
+    await this.init();
+    this.teamPlaybookStore.set(playbook.id, playbook);
+    await this.teamPlaybookStore.save(playbook.id);
+  }
+
+  /**
+   * Find matching team playbooks for a given task context.
+   */
+  async findMatchingTeamPlaybooks(options: {
+    taskType?: string;
+    domain?: string;
+    topology?: string;
+    complexity?: string;
+    k?: number;
+  }): Promise<Array<{ playbook: TeamPlaybook; score: number }>> {
+    await this.init();
+
+    const k = options.k ?? 5;
+    let playbooks = this.teamPlaybookStore.values();
+
+    // Filter by domain if specified
+    if (options.domain) {
+      playbooks = playbooks.filter((p) =>
+        p.applicability.domains.includes(options.domain!)
+      );
+    }
+
+    // Filter by topology if specified
+    if (options.topology) {
+      playbooks = playbooks.filter(
+        (p) => p.composition.topology === options.topology
+      );
+    }
+
+    // Filter by complexity if specified
+    if (options.complexity) {
+      playbooks = playbooks.filter((p) =>
+        p.applicability.complexityLevels.includes(
+          options.complexity as 'simple' | 'moderate' | 'complex' | 'epic'
+        )
+      );
+    }
+
+    // Score by task type similarity if provided
+    if (options.taskType) {
+      return findTopK(
+        options.taskType,
+        playbooks,
+        (p) => p.applicability.taskTypes.join(' '),
+        k
+      ).map(({ item, score }) => ({ playbook: item, score }));
+    }
+
+    // Return all matching, scored by confidence
+    return playbooks
+      .sort((a, b) => b.confidence - a.confidence)
+      .slice(0, k)
+      .map((p) => ({ playbook: p, score: p.confidence }));
+  }
+
+  /**
+   * Update a team playbook by adding a refinement.
+   */
+  async updateTeamPlaybook(id: string, refinement: { context: string; adjustment: string; source: 'failure' | 'success' | 'manual' }): Promise<boolean> {
+    await this.init();
+    const existing = this.teamPlaybookStore.get(id);
+    if (!existing) return false;
+    existing.evolution.refinements.push({
+      ...refinement,
+      addedAt: new Date(),
+    });
+    existing.updatedAt = new Date();
+    this.teamPlaybookStore.set(id, existing);
+    await this.teamPlaybookStore.save(id);
+    return true;
+  }
+
+  /**
+   * Update a role playbook by adding a refinement.
+   */
+  async updateRolePlaybook(id: string, refinement: { context: string; adjustment: string; source: 'failure' | 'success' | 'manual' }): Promise<boolean> {
+    await this.init();
+    const existing = this.rolePlaybookStore.get(id);
+    if (!existing) return false;
+    existing.evolution.refinements.push({
+      ...refinement,
+      addedAt: new Date(),
+    });
+    existing.updatedAt = new Date();
+    this.rolePlaybookStore.set(id, existing);
+    await this.rolePlaybookStore.save(id);
+    return true;
+  }
+
+  /**
+   * Get all team playbooks.
+   */
+  async getTeamPlaybooks(): Promise<TeamPlaybook[]> {
+    await this.init();
+    return this.teamPlaybookStore.values();
+  }
+
+  /**
+   * Count team playbooks.
+   */
+  async countTeamPlaybooks(): Promise<number> {
+    await this.init();
+    return this.teamPlaybookStore.size();
+  }
+
+  // === ROLE PLAYBOOKS ===
+
+  /**
+   * Store a role playbook.
+   */
+  async storeRolePlaybook(playbook: RolePlaybook): Promise<void> {
+    await this.init();
+    this.rolePlaybookStore.set(playbook.id, playbook);
+    await this.rolePlaybookStore.save(playbook.id);
+  }
+
+  /**
+   * Find role playbooks matching a given role + team context.
+   */
+  async findMatchingRolePlaybooks(options: {
+    role: string;
+    topology?: string;
+    taskType?: string;
+    domain?: string;
+    k?: number;
+  }): Promise<Array<{ playbook: RolePlaybook; score: number }>> {
+    await this.init();
+
+    const k = options.k ?? 3;
+    let playbooks = this.rolePlaybookStore.values();
+
+    // Filter by role
+    playbooks = playbooks.filter((p) => p.role === options.role);
+
+    // Filter by topology
+    if (options.topology) {
+      playbooks = playbooks.filter((p) =>
+        p.teamContext.topologies.includes(
+          options.topology as 'hierarchical' | 'flat' | 'wave' | 'custom'
+        )
+      );
+    }
+
+    // Filter by domain
+    if (options.domain) {
+      playbooks = playbooks.filter((p) =>
+        p.teamContext.domains.includes(options.domain!)
+      );
+    }
+
+    // Score by task type similarity if provided
+    if (options.taskType) {
+      return findTopK(
+        options.taskType,
+        playbooks,
+        (p) => p.teamContext.taskTypes.join(' '),
+        k
+      ).map(({ item, score }) => ({ playbook: item, score }));
+    }
+
+    return playbooks
+      .sort((a, b) => b.confidence - a.confidence)
+      .slice(0, k)
+      .map((p) => ({ playbook: p, score: p.confidence }));
+  }
+
+  /**
+   * Get all role playbooks.
+   */
+  async getRolePlaybooks(): Promise<RolePlaybook[]> {
+    await this.init();
+    return this.rolePlaybookStore.values();
+  }
+
+  /**
+   * Count role playbooks.
+   */
+  async countRolePlaybooks(): Promise<number> {
+    await this.init();
+    return this.rolePlaybookStore.size();
+  }
+
+  // === META-OBSERVATIONS ===
+
+  /**
+   * Record a team meta-observation.
+   */
+  async recordMetaObservation(observation: TeamMetaObservation): Promise<void> {
+    await this.init();
+    this.metaObservationStore.set(observation.id, observation);
+    await this.metaObservationStore.save(observation.id);
+  }
+
+  /**
+   * Get all team meta-observations.
+   */
+  async getMetaObservations(): Promise<TeamMetaObservation[]> {
+    await this.init();
+    return this.metaObservationStore.values();
+  }
+
+  /**
+   * Count team meta-observations.
+   */
+  async countMetaObservations(): Promise<number> {
+    await this.init();
+    return this.metaObservationStore.size();
+  }
+
+  // === META-STRATEGIES ===
+
+  /**
+   * Store a team meta-strategy.
+   */
+  async storeMetaStrategy(strategy: TeamMetaStrategy): Promise<void> {
+    await this.init();
+    this.metaStrategyStore.set(strategy.id, strategy);
+    await this.metaStrategyStore.save(strategy.id);
+  }
+
+  /**
+   * Get team meta-strategies matching given conditions.
+   */
+  async getMatchingMetaStrategies(context: {
+    domains?: string[];
+    taskCharacteristics?: string[];
+  }): Promise<TeamMetaStrategy[]> {
+    await this.init();
+    let strategies = this.metaStrategyStore.values();
+
+    if (context.domains && context.domains.length > 0) {
+      strategies = strategies.filter((s) =>
+        s.condition.domains.some((d) => context.domains!.includes(d))
+      );
+    }
+
+    return strategies;
+  }
+
+  /**
+   * Get all team meta-strategies.
+   */
+  async getMetaStrategies(): Promise<TeamMetaStrategy[]> {
+    await this.init();
+    return this.metaStrategyStore.values();
+  }
+
+  /**
+   * Count team meta-strategies.
+   */
+  async countMetaStrategies(): Promise<number> {
+    await this.init();
+    return this.metaStrategyStore.size();
+  }
+
+  // === AGGREGATE STATS ===
+
+  /**
+   * Get statistics about team memory contents.
+   */
+  async getStats(): Promise<{
+    teamExperienceCount: number;
+    teamPlaybookCount: number;
+    rolePlaybookCount: number;
+    metaObservationCount: number;
+    metaStrategyCount: number;
+  }> {
+    await this.init();
+    const [experiences, teamPlaybooks, rolePlaybooks, observations, strategies] =
+      await Promise.all([
+        this.countTeamExperiences(),
+        this.countTeamPlaybooks(),
+        this.countRolePlaybooks(),
+        this.countMetaObservations(),
+        this.countMetaStrategies(),
+      ]);
+
+    return {
+      teamExperienceCount: experiences,
+      teamPlaybookCount: teamPlaybooks,
+      rolePlaybookCount: rolePlaybooks,
+      metaObservationCount: observations,
+      metaStrategyCount: strategies,
+    };
+  }
+
+  /**
+   * Close all stores.
+   */
+  async close(): Promise<void> {
+    await Promise.all([
+      this.experienceStore.close(),
+      this.teamPlaybookStore.close(),
+      this.rolePlaybookStore.close(),
+      this.metaObservationStore.close(),
+      this.metaStrategyStore.close(),
+    ]);
+  }
+}
+
+/**
+ * Create a TeamExperienceMemory instance.
+ */
+export function createTeamExperienceMemory(baseDir: string): TeamExperienceMemory {
+  return new TeamExperienceMemory(baseDir);
+}