pi-reflect

Iterative self-improvement for pi coding agents.

Define a target — how your agent should behave, what it should remember, who it should be — and reflect iterates toward it. Each run reads recent conversations and reference material, compares the agent's actual behavior against the target, and makes surgical edits to close the gap.

define the target → reflect reads evidence → edits the file → the agent gets closer.

Works on any markdown file: behavioral rules (AGENTS.md), long-term memory (MEMORY.md), personality (SOUL.md), or anything else.

Install

pi install git:github.com/jo-inc/pi-reflect

Requires pi with an LLM API key configured. Each run makes one LLM call (~$0.05–0.15 with Sonnet).

Usage

/reflect ./AGENTS.md        # run reflection on a file
/reflect                    # use saved default target
/reflect-config             # show configured targets
/reflect-history            # show recent runs
/reflect-stats              # correction rate trend + rule recidivism
/reflect-backfill           # bootstrap stats for all historical sessions

First run asks if you want to save the target. After that, just /reflect.

How it works

1. Collects evidence: conversation transcripts, daily logs, reference files — from any combination of sources
2. Sends the evidence + the target file + a prompt describing the desired end state to an LLM
3. The LLM identifies gaps between actual behavior and the target, proposes surgical edits
4. Edits are applied with safety checks: backs up the original, skips ambiguous matches, rejects suspiciously large deletions, auto-commits to git if the target is in a repo

Every edit is versioned — reflect auto-commits to git after applying changes, so you get a full history of how each file evolved. git log AGENTS.md shows every correction the agent absorbed. git diff HEAD~5 SOUL.md shows how the personality sharpened over the last 5 runs.

Over time, the file converges: corrections get absorbed as rules, memory accumulates durable facts, personality sharpens from generic to specific. The agent stops needing the same corrections.

Data sources

Each target has two input channels — transcripts (what happened) and context (reference material). Both accept an array of sources:

All sources support {lookbackDays} interpolation and per-source maxBytes caps. File sources are automatically pruned to only include files within the lookbackDays window (matched by date in filename).

{
  "targets": [{
    "path": "/data/me/MEMORY.md",
    "model": "anthropic/claude-sonnet-4-5",
    "lookbackDays": 1,
    "transcripts": [
      { "type": "command", "label": "conversations", "command": "curl -s http://localhost:3001/conversation/recent?days={lookbackDays}", "maxBytes": 400000 }
    ],
    "context": [
      { "type": "files", "label": "daily logs", "paths": ["/data/me/daily/*.md"], "maxBytes": 50000 },
      { "type": "files", "label": "notes", "paths": ["/data/me/notes/*.md"], "maxBytes": 50000 }
    ],
    "prompt": "..."
  }]
}

For the common case of local pi sessions, just use transcriptSource:

{ "transcriptSource": { "type": "pi-sessions" } }

Prompts define the target

Each target has an optional prompt field that tells reflect what to optimize for. The same engine drives very different behaviors depending on the prompt:

Prompts use {fileName}, {targetContent}, {transcripts}, and {context} as placeholders:

{
  "prompt": "You are evolving an AI identity file ({fileName})...\n\n## Current\n{targetContent}\n\n## Conversations\n{transcripts}\n\n## Reference\n{context}"
}

If no prompt is set, the default targets behavioral corrections (the original use case).

Impact Metrics

/reflect-stats tracks whether reflection is working:

• Correction Rate — corrections / sessions per run, plotted over time. Trending down = the agent is converging.

• Rule Recidivism — which sections get edited repeatedly. A rule strengthened 3+ times isn't sticking. Sections edited once and never again are resolved.

/reflect-backfill bootstraps stats from historical sessions (dry-run, no file edits).

Configuration

~/.pi/agent/reflect.json:

{
  "targets": [{
    "path": "/path/to/AGENTS.md",
    "model": "anthropic/claude-sonnet-4-5",
    "lookbackDays": 1,
    "maxSessionBytes": 614400,
    "backupDir": "~/.pi/agent/reflect-backups",
    "transcriptSource": { "type": "pi-sessions" }
  }]
}

Related

• pi-mem — Memory system for pi agents. Manages MEMORY.md, daily logs, notes, and scratchpad with context injection and keyword search. Pairs naturally with pi-reflect.

Scheduling

pi -p --no-session "/reflect /path/to/AGENTS.md"

Works with cron, launchd, or any scheduler. Ask your pi to set it up for you — there's a setup guide for agents.

Development

git clone https://github.com/jo-inc/pi-reflect && cd pi-reflect
npm install && npm test   # 137 tests
pi -e ./extensions/index.ts   # test locally without installing

License

MIT

Pi Ecosystem