aiwg/agentic/code/addons/agent-loop/schemas/cross-task-memory.yaml

Deployment tool and support utility for AI context. Copies agents, skills, commands, rules, and behaviors into the paths each AI platform reads (Claude Code, Codex, Copilot, Cursor, Warp, OpenClaw, and 6 more) so one source of truth works across 10 platfo

# 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"