# Ralph Cross-Task Memory Schema
# Based on REF-021 Reflexion Research
# Issues: #154, #155

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/ralph-cross-task-memory/v1"
title: "Ralph Cross-Task Memory Schema"
description: |
  Schema for cross-task learning through semantic similarity matching
  and configurable memory capacity (Ω parameter) per REF-021 Reflexion.

type: object
required:
  - version
  - memory_config
  - cross_task_learning

properties:
  version:
    type: string
    pattern: "^\\d+\\.\\d+\\.\\d+$"
    default: "1.0.0"

  memory_config:
    $ref: "#/$defs/MemoryConfig"

  cross_task_learning:
    $ref: "#/$defs/CrossTaskConfig"

$defs:
  MemoryConfig:
    type: object
    description: "Memory capacity (Ω parameter) configuration"
    properties:
      default_capacity:
        type: integer
        default: 3
        description: "Default Ω (sliding window size)"

      presets:
        type: object
        properties:
          simple:
            type: integer
            default: 1
            description: "For simple, well-defined tasks"
          moderate:
            type: integer
            default: 3
            description: "For typical development tasks"
          complex:
            type: integer
            default: 5
            description: "For complex multi-step tasks"
          maximum:
            type: integer
            default: 10
            description: "For highly complex reasoning tasks"

      auto_scaling:
        type: object
        properties:
          enabled:
            type: boolean
            default: false
          scale_up_on:
            type: array
            items:
              type: string
            default:
              - consecutive_failures
              - low_quality_scores
          scale_down_on:
            type: array
            items:
              type: string
            default:
              - high_quality_maintained
              - fast_convergence

      storage:
        type: object
        properties:
          reflections_path:
            type: string
            default: ".aiwg/ralph/{loop_id}/reflections/"
          all_reflections_kept:
            type: boolean
            default: true
            description: "Save all reflections even if not in window"

  CrossTaskConfig:
    type: object
    description: "Cross-task learning configuration"
    properties:
      enabled:
        type: boolean
        default: true

      storage:
        type: object
        properties:
          memory_path:
            type: string
            default: ".aiwg/ralph/memory/"
          index_file:
            type: string
            default: "task-index.json"
          embeddings_path:
            type: string
            default: ".aiwg/ralph/memory/embeddings/"
          reflections_path:
            type: string
            default: ".aiwg/ralph/memory/reflections/"

      embedding:
        type: object
        properties:
          model:
            type: string
            default: "all-MiniLM-L6-v2"
          dimensions:
            type: integer
            default: 384

      retrieval:
        type: object
        properties:
          top_k:
            type: integer
            default: 3
            description: "Number of similar tasks to retrieve"
          similarity_threshold:
            type: number
            minimum: 0
            maximum: 1
            default: 0.7
          max_age_days:
            type: integer
            default: 90
            description: "Ignore tasks older than this"

      injection:
        type: object
        properties:
          inject_reflections:
            type: boolean
            default: true
          inject_summary:
            type: boolean
            default: true
          max_tokens:
            type: integer
            default: 2000
            description: "Max tokens for cross-task context"

# Task memory record schema
task_memory:
  type: object
  required:
    - task_id
    - task_description
    - timestamp
  properties:
    task_id:
      type: string
      format: uuid
    task_description:
      type: string
    task_type:
      type: string
      enum:
        - implementation
        - debugging
        - refactoring
        - testing
        - documentation
        - architecture
        - research
    timestamp:
      type: string
      format: date-time
    embedding_path:
      type: string
    outcome:
      type: string
      enum: [success, partial, failure]
    iterations:
      type: integer
    final_quality:
      type: number
    reflections:
      type: array
      items:
        $ref: "#/$defs/Reflection"
    key_learnings:
      type: array
      items:
        type: string
    tags:
      type: array
      items:
        type: string

  Reflection:
    type: object
    properties:
      iteration:
        type: integer
      content:
        type: string
      type:
        type: string
        enum:
          - error_analysis
          - strategy_change
          - success_pattern
          - constraint_discovery
      effectiveness:
        type: string
        enum: [helpful, neutral, unhelpful]

# CLI configuration schema
cli_options:
  memory_flag:
    name: "--memory"
    short: "-m"
    type: integer
    default: 3
    help: "Memory capacity (Ω): number of reflections to keep in context"
    examples:
      - command: "aiwg ralph 'Fix tests' --memory 1"
        description: "Simple task, minimal memory"
      - command: "aiwg ralph 'Refactor module' --memory 3"
        description: "Moderate task, default memory"
      - command: "aiwg ralph 'Redesign architecture' --memory 5"
        description: "Complex task, extended memory"

  cross_task_flag:
    name: "--cross-task"
    type: boolean
    default: true
    help: "Enable cross-task learning from similar past tasks"
    examples:
      - command: "aiwg ralph 'Implement auth' --cross-task"
        description: "Learn from similar past tasks"
      - command: "aiwg ralph 'Implement auth' --no-cross-task"
        description: "Disable cross-task learning"

# Agent protocol
agent_protocol:
  memory_window:
    description: "Maintain sliding window of reflections"
    steps:
      - get_memory_capacity
      - load_recent_reflections
      - trim_to_window_size
      - inject_into_context

  cross_task_retrieval:
    description: "Retrieve reflections from similar past tasks"
    triggers:
      - ralph_start
    steps:
      - extract_task_description
      - generate_embedding
      - search_similar_tasks
      - filter_by_threshold
      - load_reflections
      - summarize_if_needed
      - inject_into_context

  task_memory_update:
    description: "Store task for future cross-task learning"
    triggers:
      - ralph_complete
    steps:
      - generate_task_embedding
      - extract_key_learnings
      - store_reflections
      - update_task_index
      - prune_old_entries

  auto_scaling:
    description: "Automatically adjust memory capacity"
    triggers:
      - consecutive_failures
      - quality_threshold_breach
    steps:
      - analyze_performance
      - determine_scale_direction
      - adjust_capacity
      - log_adjustment

# Performance impact tracking
performance_tracking:
  metrics:
    - cross_task_retrieval_count
    - cross_task_success_rate
    - memory_capacity_used
    - reflection_helpfulness
    - iterations_saved

  comparison:
    description: "Track impact of cross-task learning"
    baseline: "no cross-task learning"
    treatment: "with cross-task learning"
    measures:
      - iterations_to_completion
      - final_quality_score
      - time_to_completion

# Research targets (from REF-021)
research_targets:
  memory_capacity:
    simple_tasks: 1
    moderate_tasks: 3
    complex_tasks: 5
  cross_task_benefit: "improved success rates on similar tasks"
  reflection_types:
    - error_analysis
    - strategy_adjustment
    - constraint_discovery

# Default configuration
defaults:
  memory_capacity: 3
  cross_task_enabled: true
  retrieval_top_k: 3
  similarity_threshold: 0.7

# References
references:
  research:
    - "@.aiwg/research/findings/REF-021-reflexion.md"
  implementation:
    - "#154"  # Cross-task learning
    - "#155"  # Memory capacity (Ω)
  related:
    - "@tools/ralph-external/"
    - "@.aiwg/ralph/memory/"
    - "@agentic/code/frameworks/sdlc-complete/schemas/research/semantic-retrieval.yaml"