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

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. 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.

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 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. 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) 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) 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) 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	CLI driver for loop and interactive modes; creates LoopAlgorithmState	View on GitHub
Releases/v3.0/.claude/hooks/lib/algorithm-state.ts	Central state store, re-work detection, stale session sweeping	View on GitHub
Releases/v3.0/.claude/hooks/handlers/AlgorithmEnrichment.ts	End-of-run reflection capture and JSONL logging	View on GitHub
Releases/v3.0/.claude/skills/PAIUpgrade/Workflows/MineReflections.md	Mining reflection logs for upgrade candidates	View on GitHub
Releases/v3.0/.claude/skills/PAIUpgrade/Workflows/AlgorithmUpgrade.md	Generating diff-style upgrade proposals	View on GitHub
Releases/v3.0/.claude/skills/PAI/Tools/RebuildPAI.ts	Applying patches and rebuilding compiled assets	View on GitHub

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:

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:

pai upgrade algorithm

This resolves to Workflows/AlgorithmUpgrade.md, which internally invokes 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:

// 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 patches the specification:

// 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}