9thlevelsoftware/legion/memory-manager

Path: .planning/memory/OUTCOMES.md
Created: on first store operation (not during project initialization)

# Memory — Outcome Log
 
Records agent performance and task outcomes for cross-session learning.
Managed by memory-manager skill. Do not edit manually unless pruning old records.
 
## Records
 
| ID | Date | Branch | Phase | Plan | Agent | Task Type | Outcome | Importance | Tags | Summary |
|----|------|--------|-------|------|-------|-----------|---------|------------|------|---------|
| O-001 | 2026-03-01 | main | 5 | 05-01 | testing-qa-verification-specialist | quality-review | success | 3 | review, testing, workflow | Review-loop skill approved in 2 cycles |
| O-002 | 2026-03-01 | main | 5 | 05-02 | autonomous | workflow | success | 2 | review, command, status | /legion:review command implemented |

Store Outcome:
 
Step 1: Check memory directory
  - If .planning/memory/ does not exist: create it with mkdir -p
  - If .planning/memory/OUTCOMES.md does not exist: create it with the header template from Section 2
 
Step 2: Determine next ID
  - Read OUTCOMES.md
  - Count rows in the Records table (exclude header row)
  - Next ID = O-{count + 1}, zero-padded to 3 digits
 
Step 3: Calculate importance
  - Start with base score from the Importance Scoring table in Section 2
  - Apply adjustment modifiers
  - Cap at 5
 
Step 4: Validate and resolve task_type
  - task_type MUST be populated for every outcome record (never leave blank)
  - Apply the following inference chain in order:
    1. Primary: use the task_type passed by the execution-tracker
       (the tracker derives this from the plan's task descriptions)
    2. Fallback 1: if task_type is missing or empty, look up the executing agent's
       entry in CATALOG.md (skills/agent-registry/CATALOG.md) and use the FIRST
       value from the agent's Task Types column
    3. Fallback 2: if the agent is "autonomous" or not found in CATALOG.md,
       use "general"
  - Valid task_types: any tag listed in the Task Types column of CATALOG.md
    (e.g., "frontend", "backend", "quality-review", "workflow", "branding",
    "ci-cd", "user-research", "content-strategy", "sprint-planning")
  - The fallback value "general" is always valid even though it does not
    appear in CATALOG.md
 
  Examples:
    - execution-tracker passes task_type="frontend" → use "frontend"
    - execution-tracker passes no task_type, agent is engineering-backend-architect
      → look up CATALOG.md → first Task Type is "backend" → use "backend"
    - execution-tracker passes no task_type, agent is "autonomous"
      → no CATALOG.md entry → use "general"
 
Step 5: Build the record
  - Date: current date (YYYY-MM-DD)
  - Phase: from the current phase context
  - Plan: from the plan ID being tracked
  - Agent: agent ID that executed the plan, or "autonomous"
  - Task Type: resolved in Step 4 (guaranteed non-empty)
  - Outcome: success / partial / failed (from plan execution result)
  - Importance: calculated in Step 3
  - Tags: phase slug, agent division, task-related keywords
  - Summary: one-line description of the outcome
 
Step 6: Append the record
  - Read current OUTCOMES.md
  - Append the new row to the Records table
  - Write updated OUTCOMES.md
 
Step 7: Verify
  - Confirm the new record appears in OUTCOMES.md
  - Confirm Task Type column is non-empty in the new record
  - If write failed: output the record as text to the user (never lose data)

Recall Outcomes:
 
Input:
  - query_tags: list of tags to filter by (optional, matches any)
  - agent_id: specific agent to filter by (optional)
  - task_type: specific task type to filter by (optional)
  - limit: max records to return (default: 20)
 
Step 1: Check memory exists
  - If .planning/memory/OUTCOMES.md does not exist: return empty results
  - Do NOT create the file on recall — only store creates it
 
Step 2: Read and parse OUTCOMES.md
  - Parse the Records table into individual records
  - If parse fails (malformed table): log warning, return empty results
 
Step 3: Filter
  - If query_tags provided: keep records where any tag matches any query_tag
  - If agent_id provided: keep records where Agent matches agent_id
  - If task_type provided: keep records where Task Type matches task_type
  - Multiple filters are AND-combined
 
Step 4: Apply decay scoring
  - For each record, calculate:
    days_old = (current_date - record_date) in days
    recency_weight:
      - days_old <= 7:  1.0
      - days_old <= 30: 0.7
      - days_old <= 90: 0.4
      - days_old > 90:  0.1
    decay_score = importance × recency_weight
 
Step 5: Exclude low-signal records
  - Remove records where decay_score < 0.2
 
Step 6: Sort and limit
  - Sort by decay_score descending
  - Return top {limit} records
 
Step 7: Pruning suggestion (informational only)
  - If total record count exceeds 200:
    Output note: "OUTCOMES.md has {count} records. Run `/legion:learn --prune`
    to archive old entries, or enable `memory.auto_prune` in settings.json."
  - If `memory.auto_prune` is true in settings.json, pruning runs automatically
    after store operations when the threshold is exceeded (see Section 7.5).

Recall Agent Scores:
 
Input:
  - task_types: list of task type tags from the current plan analysis
 
Step 1: Check memory exists
  - If .planning/memory/OUTCOMES.md does not exist: return empty map
 
Step 2: Recall all outcomes matching task_types
  - Use general recall with query_tags = task_types
 
Step 3: Group by agent_id
  - For each unique agent in the filtered results:
    - total_tasks = count of records for this agent
    - successes = count where outcome = "success"
    - failures = count where outcome = "failed"
    - success_rate = successes / total_tasks
    - avg_importance = mean of importance values
    - avg_recency_weight = mean of recency_weight values
 
Step 4: Calculate memory score per agent
  - memory_score = (success_rate × 3.0) + (avg_importance × 0.5)
  - Apply recency: memory_score = memory_score × avg_recency_weight
  - Clamp to range [0, 5]
 
Step 5: Return agent_id → memory_score mapping
  - Only include agents with total_tasks >= 2 (avoid one-off noise)
  - Sort by memory_score descending

Recall Archetype Scores:
 
Input:
  - task_types: list of task type tags to include (optional; if empty, all task types)
 
Step 1: Check memory exists
  - If .planning/memory/OUTCOMES.md does not exist: return empty map
 
Step 2: Read and parse all outcomes
  - Parse the Records table from OUTCOMES.md
  - If task_types provided: filter to records where Task Type matches any value in task_types
  - If task_types empty: use all records