# How the Algorithm Self-Upgrade Loop Functions in Personal AI Infrastructure (PAI)

> Discover how the algorithm self-upgrade loop in Personal AI Infrastructure creates versioned patches, rebuilding the system for enhanced autonomous execution and continuous improvement.

- Repository: [Daniel Miessler 🛡️/Personal_AI_Infrastructure](https://github.com/danielmiessler/personal_ai_infrastructure)
- Tags: internals
- Published: 2026-02-16

---

**The algorithm self-upgrade loop in PAI operates as a closed feedback cycle where autonomous execution generates structured reflections, which are mined to produce versioned algorithm patches that rebuild the system for subsequent runs.**

Personal AI Infrastructure (PAI) by danielmiessler implements a continuous **algorithm self-upgrade loop** that enables the system to refine its own decision-making rules without manual code edits. This autonomous cycle captures execution insights, identifies systemic weaknesses, and generates concrete upgrade proposals that patch the algorithm specification before the next loop begins.

## The Seven-Stage Self-Upgrade Cycle

The self-upgrade loop consists of seven distinct stages that transition from active execution to persistent state management, reflection capture, and automated improvement generation.

### Stage 1: Autonomous Algorithm Execution

The cycle begins when the user initiates a loop session via the CLI tool defined in [`Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts). The command creates a persistent `LoopAlgorithmState` JSON file and runs iterative agents against a Product Requirements Document (PRD) until all criteria pass or the maximum iteration limit is reached.

```bash
algorithm -m loop -p ~/.claude/MEMORY/WORK/auth/PRD-20260207-auth.md -n 20 -a 4

```

This invocation creates a session state at `MEMORY/STATE/algorithms/{sessionId}.json` and runs up to 20 iterations with 4 parallel agents.

### Stage 2: Persistent State Management

Between iterations, the [`algorithm-state.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/algorithm-state.ts) hook manages the `LoopAlgorithmState`, tracking `state.loopIteration`, `state.loopHistory`, and detecting **re-work** scenarios where a new run targets an existing PRD. When re-work is detected, the system archives the previous cycle to preserve historical context.

The same module provides `sweepStaleActive()` to clean abandoned sessions, ensuring the state store does not accumulate orphaned entries.

### Stage 3: Reflection Capture and Structured Logging

At the conclusion of every loop, the `AlgorithmEnrichment` stop-handler invokes `algorithmEnd(sessionId, context)` defined in [`Releases/v3.0/.claude/hooks/handlers/AlgorithmEnrichment.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/hooks/handlers/AlgorithmEnrichment.ts). This function appends a structured reflection line to `MEMORY/LEARNING/REFLECTIONS/algorithm-reflections.jsonl`.

Each reflection entry contains three diagnostic questions:
- **Q1:** Execution mistakes or failures encountered
- **Q2:** Algorithm-level fixes required
- **Q3:** Fundamental gaps in the current approach

The JSONL line also records sentiment scores, budget consumption, and failure counts to weight future upgrade priorities.

### Stage 4: Mining Reflections for Upgrade Candidates

The **MineReflections** workflow ([`Releases/v3.0/.claude/skills/PAIUpgrade/Workflows/MineReflections.md`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAIUpgrade/Workflows/MineReflections.md)) processes the accumulated `algorithm-reflections.jsonl` file. It extracts recurring themes from Q1-Q3 answers, weights them by negative signals (low sentiment, over-budget runs, high failure counts), and returns a prioritized list of **upgrade candidates** representing systemic weaknesses.

### Stage 5: Self-Upgrade Proposal Generation

The **AlgorithmUpgrade** workflow ([`Releases/v3.0/.claude/skills/PAIUpgrade/Workflows/AlgorithmUpgrade.md`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAIUpgrade/Workflows/AlgorithmUpgrade.md)) triggers when the user invokes the phrase "algorithm upgrade" or automatically as Thread 3 of the generic Upgrade workflow. This workflow cross-references each upgrade candidate against the current algorithm specification located at `skills/PAI/Components/Algorithm/v{VERSION}.md`.

It generates **concrete diff-style proposals** targeting specific sections of the spec, suggests version bumps (patch, minor, or none), and presents the changes for user review.

### Stage 6: Automated Application and Rebuild

Upon user approval, the **RebuildPAI** tool ([`Releases/v3.0/.claude/skills/PAI/Tools/RebuildPAI.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAI/Tools/RebuildPAI.ts)) applies the generated diff to the algorithm specification file. It writes the updated content to `skills/PAI/Components/Algorithm/v{X.Y.Z}.md`, bumps the `LATEST` version pointer, and regenerates all compiled PAI assets.

The next loop execution automatically loads the improved spec, completing the closed feedback cycle.

### Stage 7: Dashboard Monitoring and State Sweeping

Throughout the cycle, the PAI dashboard reads the `LoopAlgorithmState` JSON files to display live execution progress, iteration counts, and success criteria status. Concurrently, the `sweepStaleActive` routine periodically cleans stale active sessions to prevent state pollution.

## Key Source Files and Their Responsibilities

| File Path | Role | GitHub Link |
|-----------|------|-------------|
| [`Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts) | CLI driver for loop and interactive modes; creates `LoopAlgorithmState` | [View on GitHub](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts) |
| [`Releases/v3.0/.claude/hooks/lib/algorithm-state.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/hooks/lib/algorithm-state.ts) | Central state store, re-work detection, stale session sweeping | [View on GitHub](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/hooks/lib/algorithm-state.ts) |
| [`Releases/v3.0/.claude/hooks/handlers/AlgorithmEnrichment.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/hooks/handlers/AlgorithmEnrichment.ts) | End-of-run reflection capture and JSONL logging | [View on GitHub](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/hooks/handlers/AlgorithmEnrichment.ts) |
| [`Releases/v3.0/.claude/skills/PAIUpgrade/Workflows/MineReflections.md`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAIUpgrade/Workflows/MineReflections.md) | Mining reflection logs for upgrade candidates | [View on GitHub](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAIUpgrade/Workflows/MineReflections.md) |
| [`Releases/v3.0/.claude/skills/PAIUpgrade/Workflows/AlgorithmUpgrade.md`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAIUpgrade/Workflows/AlgorithmUpgrade.md) | Generating diff-style upgrade proposals | [View on GitHub](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAIUpgrade/Workflows/AlgorithmUpgrade.md) |
| [`Releases/v3.0/.claude/skills/PAI/Tools/RebuildPAI.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAI/Tools/RebuildPAI.ts) | Applying patches and rebuilding compiled assets | [View on GitHub](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAI/Tools/RebuildPAI.ts) |

## Practical Implementation Examples

### Initiating an Autonomous Loop Session

To start the **algorithm self-upgrade loop**, invoke the loop mode with a PRD file and iteration limits:

```bash
algorithm -m loop -p ~/.claude/MEMORY/WORK/auth/PRD-20260207-auth.md -n 20 -a 4

```

This command creates a persistent state file at `MEMORY/STATE/algorithms/{sessionId}.json` and executes up to 20 iterations using 4 parallel agents.

### Triggering the Self-Upgrade Workflow

After accumulating reflections, trigger the upgrade analysis manually or via the automated Thread 3:

```bash
pai upgrade algorithm

```

This resolves to [`Workflows/AlgorithmUpgrade.md`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Workflows/AlgorithmUpgrade.md), which internally invokes [`MineReflections.md`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/MineReflections.md) to process `MEMORY/LEARNING/REFLECTIONS/algorithm-reflections.jsonl`.

### Automatic Reflection Logging

The system automatically captures reflections at loop termination via the `AlgorithmEnrichment` handler:

```typescript
// From AlgorithmEnrichment.ts
algorithmEnd(sessionId, {
  isAlgorithmResponse: true,
  summary: transcriptSummary,
  criteria: extractedCriteria,
});

```

This appends a JSONL line containing Q1 (execution mistakes), Q2 (algorithm fixes), and Q3 (fundamental gaps) to the reflections log.

### Applying Versioned Upgrades

Once the user approves proposals, [`RebuildPAI.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/RebuildPAI.ts) patches the specification:

```typescript
// From RebuildPAI.ts
const algorithmFile = join(ALGORITHM_DIR, `${version}.md`);
writeFileSync(algorithmFile, updatedContent, "utf-8");

```

This writes the updated algorithm to `skills/PAI/Components/Algorithm/v{X.Y.Z}.md`, bumps the `LATEST` version pointer, and regenerates compiled assets for the next loop iteration.

## Summary

- The **algorithm self-upgrade loop** in PAI creates a closed feedback system where execution data automatically drives specification improvements.
- Each loop run generates structured reflections (Q1-Q3) stored in `MEMORY/LEARNING/REFLECTIONS/algorithm-reflections.jsonl`.
- The **MineReflections** workflow extracts upgrade candidates from accumulated logs, weighted by failure signals and sentiment scores.
- **AlgorithmUpgrade** generates concrete diff proposals against `skills/PAI/Components/Algorithm/v{VERSION}.md`.
- **RebuildPAI** applies approved patches, bumps semantic versions, and rebuilds assets without manual file editing.
- State persistence via `LoopAlgorithmState` JSON files enables resumable execution and re-work detection across sessions.

## Frequently Asked Questions

### What triggers the algorithm self-upgrade loop in PAI?

The loop triggers in two ways: automatically after each algorithm execution completes and writes to the reflection log, or manually when the user invokes the phrase "algorithm upgrade" or runs `pai upgrade algorithm`. The automatic path runs as Thread 3 of the generic Upgrade workflow, while the manual path allows users to force an upgrade analysis after accumulating sufficient reflection data.

### How does PAI prevent breaking changes during algorithm upgrades?

The system uses semantic versioning (patch/minor/major) and maintains explicit version files at `skills/PAI/Components/Algorithm/v{X.Y.Z}.md`. The `AlgorithmUpgrade` workflow suggests appropriate version bumps based on change severity, and the `RebuildPAI` tool archives previous versions before applying patches. Users must explicitly approve diff proposals before any file modifications occur, ensuring human oversight of structural changes to the algorithm specification.

### Where does PAI store execution reflections and what data do they contain?

Reflections append to `MEMORY/LEARNING/REFLECTIONS/algorithm-reflections.jsonl` as JSON Lines. Each entry contains three diagnostic questions (Q1: execution mistakes, Q2: algorithm-level fixes, Q3: fundamental gaps), sentiment scores, budget consumption metrics, failure counts, and session identifiers. The `AlgorithmEnrichment` handler in [`Releases/v3.0/.claude/hooks/handlers/AlgorithmEnrichment.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/hooks/handlers/AlgorithmEnrichment.ts) automatically generates these entries at loop termination.

### Can the algorithm self-upgrade loop run fully autonomously without user intervention?

While the reflection capture and mining stages run automatically, the current implementation requires user approval before applying upgrades. The `AlgorithmUpgrade` workflow generates concrete diff-style proposals, but the `RebuildPAI` tool only executes patches after explicit user acceptance. This design ensures safety by keeping humans in the loop for specification changes, though the infrastructure supports full automation if the approval gate is removed or scripted.