> ## Documentation Index
> Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Post-Run Learning and Reflection Pipeline

<details>
  <summary>Relevant source files</summary>

  The following files were used as context for generating this wiki page:

  * apps/web/src/App.test.tsx
  * apps/web/src/App.tsx
  * apps/web/src/console/sections/MemorySection.tsx
  * apps/web/src/console/useConsoleAppState.tsx
  * apps/web/src/consoleApi.test.ts
  * apps/web/src/consoleApi.ts
  * crates/palyra-common/src/runtime\_contracts.rs
  * crates/palyra-daemon/src/application/learning.rs
  * crates/palyra-daemon/src/application/provider\_input.rs
  * crates/palyra-daemon/src/application/run\_stream/tape.rs
  * crates/palyra-daemon/src/application/session\_compaction.rs
  * crates/palyra-daemon/src/auxiliary\_executor.rs
  * crates/palyra-daemon/src/background\_queue.rs
  * crates/palyra-daemon/src/objective\_judge.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/acp.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/chat.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/memory.rs
</details>

The Post-Run Learning and Reflection Pipeline is a subsystem within Palyra responsible for distilling transient agent interactions into durable knowledge, preferences, and skills. It operates as an asynchronous background process that analyzes completed runs to generate `LearningCandidate` objects, which are then audited and applied to the user's long-term memory or workspace.

## Reflection Architecture and Data Flow

The pipeline is triggered upon the completion of an agent run. It uses a sampling heuristic to determine if a run warrants reflection and then dispatches a background task to the `BackgroundQueue`.

### Implementation Flow

1. **Task Ingestion**: The `GatewayRuntimeState` identifies a terminal run state and may enqueue a reflection task [crates/palyra-daemon/src/background\_queue.rs#45-46](http://crates/palyra-daemon/src/background_queue.rs#45-46).
2. **Queue Dispatch**: The `spawn_background_queue_loop` leases `OrchestratorBackgroundTaskRecord` entries with the kind `REFLECTION_TASK_KIND` [crates/palyra-daemon/src/background\_queue.rs:45-46, 95-108]().
3. **Processing**: The function `process_post_run_reflection_task` invokes the `LearningCurator` to analyze the run tape [crates/palyra-daemon/src/background\_queue.rs#45-46](http://crates/palyra-daemon/src/background_queue.rs#45-46).
4. **Candidate Generation**: The curator produces `LearningCandidate` objects of various kinds (e.g., `preference`, `patch_skill`) [crates/palyra-daemon/src/transport/http/handlers/console/memory.rs#34-40](http://crates/palyra-daemon/src/transport/http/handlers/console/memory.rs#34-40).

### Reflection Pipeline Overview

Title: Post-Run Reflection and Learning Loop

```mermaid theme={null}
graph TD
    subgraph "Agent Run Space"
        A["AgentRunLoop"] -- "Terminal State" --> B["OrchestratorTape"]
    end

    subgraph "Background Processing (Code Entity Space)"
        B -- "Trigger" --> C["spawn_background_queue_loop()"]
        C -- "Lease Task" --> D["process_post_run_reflection_task()"]
        D -- "Analyze Tape" --> E["LearningCurator"]
    end

    subgraph "Knowledge Synthesis"
        E -- "Generate" --> F["LearningCandidate"]
        F -- "Audit" --> G["Learning Curator Audit"]
        G -- "Apply" --> H["Workspace / Memory"]
    end

    style C stroke-dasharray: 5 5
```

Sources: [crates/palyra-daemon/src/background\_queue.rs#1-14](http://crates/palyra-daemon/src/background_queue.rs#1-14), [crates/palyra-daemon/src/background\_queue.rs#95-108](http://crates/palyra-daemon/src/background_queue.rs#95-108), [crates/palyra-daemon/src/application/learning.rs#1-15](http://crates/palyra-daemon/src/application/learning.rs#1-15)

## LearningCandidate Kinds

Learning candidates represent proposed changes to the agent's behavior or knowledge base. They are categorized into specific kinds:

| Kind           | Description                                                                                   | Implementation                                                                                                                                                                               |
| :------------- | :-------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `preference`   | User-specific stylistic or operational choices (e.g., "always use Python for data analysis"). | `apply_preference_candidate` [crates/palyra-daemon/src/transport/http/handlers/console/memory.rs#34-36](http://crates/palyra-daemon/src/transport/http/handlers/console/memory.rs#34-36)     |
| `durable_fact` | Long-term information extracted from the session (e.g., project milestones).                  | `Continuity Planner` [crates/palyra-daemon/src/application/session\_compaction.rs#7-11](http://crates/palyra-daemon/src/application/session_compaction.rs#7-11)                              |
| `procedure`    | Step-by-step instructions for complex tasks discovered during the run.                        | `LearningCurator` [crates/palyra-daemon/src/transport/http/handlers/console/memory.rs#37-40](http://crates/palyra-daemon/src/transport/http/handlers/console/memory.rs#37-40)                |
| `patch_skill`  | Proposed modifications to existing `.palyra-skill` artifacts or logic.                        | `apply_patch_learning_candidate` [crates/palyra-daemon/src/transport/http/handlers/console/memory.rs#34-36](http://crates/palyra-daemon/src/transport/http/handlers/console/memory.rs#34-36) |

Sources: [crates/palyra-daemon/src/application/session\_compaction.rs#1-17](http://crates/palyra-daemon/src/application/session_compaction.rs#1-17), [crates/palyra-daemon/src/transport/http/handlers/console/memory.rs#34-40](http://crates/palyra-daemon/src/transport/http/handlers/console/memory.rs#34-40)

## Learning Curator Audit and Hygiene

Before a candidate is applied, it undergoes an audit process to ensure safety and consistency.

### Skill Invocation Hygiene

The system projects the impact of a learning candidate on future tool usage. The function `project_skill_invocation_hygiene_for_candidate` [crates/palyra-daemon/src/transport/http/handlers/console/memory.rs#36-37](http://crates/palyra-daemon/src/transport/http/handlers/console/memory.rs#36-37) analyzes if a new preference or procedure would cause the agent to violate tool security postures or egress policies.

### Conflict Detection

The `preference_procedure_conflict_report` [crates/palyra-daemon/src/transport/http/handlers/console/memory.rs#36-37](http://crates/palyra-daemon/src/transport/http/handlers/console/memory.rs#36-37) identifies contradictions between new candidates and existing curated knowledge. This uses `CONTRADICTION_PAIRS` (e.g., "enable" vs "disable") to flag candidates for manual review if they sit on opposite sides of a logic boundary [crates/palyra-daemon/src/application/session\_compaction.rs#119-127](http://crates/palyra-daemon/src/application/session_compaction.rs#119-127).

### Data Flow: Candidate Audit

Title: Learning Candidate Audit Projection

```mermaid theme={null}
graph LR
    subgraph "Natural Language Space"
        NL["'Always use local tools'"]
    end

    subgraph "Code Entity Space"
        NL --> LC["LearningCandidate"]
        LC --> PH["project_skill_invocation_hygiene_for_candidate()"]
        LC --> CR["preference_procedure_conflict_report()"]

        PH --> S["Hygiene Score"]
        CR --> R["ConflictReport"]
    end

    S & R --> J["LearningCuratorReport"]
```

Sources: [crates/palyra-daemon/src/transport/http/handlers/console/memory.rs#34-40](http://crates/palyra-daemon/src/transport/http/handlers/console/memory.rs#34-40), [crates/palyra-daemon/src/application/session\_compaction.rs#119-127](http://crates/palyra-daemon/src/application/session_compaction.rs#119-127)

## Session Compaction Integration

The learning pipeline is tightly coupled with **Durable Session Compaction**. While ephemeral pruning only affects the current prompt, compaction durably changes future prompts by writing "continuity" data into curated workspace documents [crates/palyra-daemon/src/application/session\_compaction.rs#1-17](http://crates/palyra-daemon/src/application/session_compaction.rs#1-17).

* **Continuity Planner**: Scans the condensed event range for facts and decisions [crates/palyra-daemon/src/application/session\_compaction.rs#7-11](http://crates/palyra-daemon/src/application/session_compaction.rs#7-11).
* **Confidence Threshold**: Candidates with a score below `AUTO_WRITE_CONFIDENCE_THRESHOLD` (0.82) are routed to the web console for operator review [crates/palyra-daemon/src/application/session\_compaction.rs#90-92](http://crates/palyra-daemon/src/application/session_compaction.rs#90-92).

Sources: [crates/palyra-daemon/src/application/session\_compaction.rs#1-17](http://crates/palyra-daemon/src/application/session_compaction.rs#1-17), [crates/palyra-daemon/src/application/session\_compaction.rs#90-92](http://crates/palyra-daemon/src/application/session_compaction.rs#90-92)

## Web Console Memory/Learning UI

The reflection pipeline is managed via the **Memory Section** of the Web Console.

### Implementation Details

* **React State**: Managed by `useConsoleAppState.tsx`, specifically properties like `memoryLearningCandidates` and `memoryLearningCuratorReport` [apps/web/src/console/sections/MemorySection.tsx#70-75](http://apps/web/src/console/sections/MemorySection.tsx#70-75).
* **API Interactions**: The `ConsoleApiClient` provides methods such as `reviewLearningCandidate` and `applyLearningCandidate` to transition candidates from proposed to applied states [apps/web/src/console/sections/MemorySection.tsx#110-111](http://apps/web/src/console/sections/MemorySection.tsx#110-111).
* **UI Components**: The `MemorySection.tsx` component renders tables of learning history, active preferences, and the curator's conflict reports [apps/web/src/console/sections/MemorySection.tsx#131-150](http://apps/web/src/console/sections/MemorySection.tsx#131-150).

### Status Handling

Candidates in terminal states such as `applied`, `denied`, or `conflicted` are filtered using `NON_APPLYABLE_LEARNING_PATCH_STATUSES` to prevent redundant operations [apps/web/src/console/sections/MemorySection.tsx#122-129](http://apps/web/src/console/sections/MemorySection.tsx#122-129).

Sources: [apps/web/src/console/sections/MemorySection.tsx#1-112](http://apps/web/src/console/sections/MemorySection.tsx#1-112), [apps/web/src/console/useConsoleAppState.tsx#204-210](http://apps/web/src/console/useConsoleAppState.tsx#204-210)