@askjo/pi-reflect 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pradeep Elankumaran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="logo-dark.png" width="300">
+    <img src="logo.png" alt="pi-reflect" width="300">
+  </picture>
+</p>
+
+# pi-reflect
+
+Iterative self-improvement for [pi](https://github.com/badlogic/pi-mono) 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
+
+```bash
+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:
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `files` | Glob patterns or file paths, pruned by date and size | Daily logs, notes, other markdown files |
+| `command` | Shell command, stdout captured | API calls, database queries, custom scripts |
+| `url` | HTTP GET, response body captured | REST endpoints, health checks |
+
+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).
+
+```json
+{
+  "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`:
+
+```json
+{ "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:
+
+| Target | Prompt goal | What reflect does |
+|--------|------------|-------------------|
+| `AGENTS.md` | Behavioral correctness | Strengthens violated rules, adds rules for recurring patterns |
+| `MEMORY.md` | Factual completeness | Extracts durable facts from conversations, removes stale entries |
+| `SOUL.md` | Identity convergence | Sharpens personality from generic to specific based on interaction patterns |
+
+Prompts use `{fileName}`, `{targetContent}`, `{transcripts}`, and `{context}` as placeholders:
+
+```json
+{
+  "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`:
+
+```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" }
+  }]
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `path` | *(required)* | Target markdown file to iterate on |
+| `model` | *(required)* | LLM to use (e.g. `anthropic/claude-sonnet-4-5`) |
+| `lookbackDays` | `1` | How far back to look for evidence |
+| `maxSessionBytes` | `614400` | Max transcript bytes per run |
+| `transcripts` | — | Array of `ContextSource` for transcript data |
+| `transcriptSource` | `pi-sessions` | Legacy single source (use `transcripts` for multiple) |
+| `context` | — | Array of `ContextSource` for reference material |
+| `prompt` | *(default)* | Custom prompt with `{fileName}`, `{targetContent}`, `{transcripts}`, `{context}` |
+| `backupDir` | `~/.pi/agent/reflect-backups` | Where to store pre-edit backups |
+
+## Related
+
+- **[pi-mem](https://github.com/jo-inc/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
+
+```bash
+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](SETUP.md).
+
+## Development
+
+```bash
+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

package/SETUP.md

@@ -0,0 +1,168 @@
+# pi-reflect Setup Guide
+
+This guide is for you, the coding agent. When a user asks you to "set up reflect", "schedule reflect daily", or "configure pi-reflect", follow these instructions.
+
+## Step 1: Install
+
+Run this command:
+
+```bash
+pi install git:github.com/jo-inc/pi-reflect
+```
+
+Then reload extensions:
+
+```
+/reload
+```
+
+## Step 2: Find the target file
+
+The user wants to reflect on a behavioral markdown file — usually `AGENTS.md`, `CLAUDE.md`, `RULES.md`, or similar. Check the current project root and `~/.pi/agent/` for candidates:
+
+```bash
+ls AGENTS.md CLAUDE.md RULES.md .cursorrules .github/copilot-instructions.md 2>/dev/null
+ls ~/.pi/agent/AGENTS.md 2>/dev/null
+```
+
+If nothing exists, ask the user which file they want to improve. If they don't have one yet, suggest creating an `AGENTS.md` in their project root with a few starter rules.
+
+## Step 3: Test it
+
+Run reflect once to verify it works:
+
+```
+/reflect /absolute/path/to/AGENTS.md
+```
+
+It will ask if the user wants to save the target. Say yes. This creates `~/.pi/agent/reflect.json`.
+
+## Step 4: Schedule daily runs (optional)
+
+If the user wants automatic daily reflection, set up a scheduler. Reflect runs headless via:
+
+```bash
+pi -p --no-session "/reflect"
+```
+
+This uses the saved target from step 3.
+
+### macOS (launchd)
+
+Find the pi binary path:
+
+```bash
+which pi
+```
+
+Write the plist — replace `/path/to/pi` with the actual path:
+
+```bash
+cat > ~/Library/LaunchAgents/com.pi.reflect.plist << 'EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.pi.reflect</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>PI_PATH</string>
+        <string>-p</string>
+        <string>--no-session</string>
+        <string>/reflect</string>
+    </array>
+    <key>StartCalendarInterval</key>
+    <dict>
+        <key>Hour</key>
+        <integer>8</integer>
+        <key>Minute</key>
+        <integer>0</integer>
+    </dict>
+    <key>StandardOutPath</key>
+    <string>/tmp/pi-reflect.log</string>
+    <key>StandardErrorPath</key>
+    <string>/tmp/pi-reflect.log</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin</string>
+        <key>HOME</key>
+        <string>HOME_DIR</string>
+    </dict>
+</dict>
+</plist>
+EOF
+```
+
+Replace `PI_PATH` and `HOME_DIR` with the actual values using sed:
+
+```bash
+PI_BINARY=$(which pi)
+sed -i '' "s|PI_PATH|$PI_BINARY|g" ~/Library/LaunchAgents/com.pi.reflect.plist
+sed -i '' "s|HOME_DIR|$HOME|g" ~/Library/LaunchAgents/com.pi.reflect.plist
+```
+
+Load it:
+
+```bash
+launchctl load ~/Library/LaunchAgents/com.pi.reflect.plist
+```
+
+### Linux (cron)
+
+```bash
+PI_BINARY=$(which pi)
+(crontab -l 2>/dev/null; echo "0 8 * * * $PI_BINARY -p --no-session \"/reflect\" >> /tmp/pi-reflect.log 2>&1") | crontab -
+```
+
+## Step 5: Verify scheduling
+
+For macOS:
+
+```bash
+launchctl list | grep pi.reflect
+```
+
+For Linux:
+
+```bash
+crontab -l | grep reflect
+```
+
+Tell the user: reflect is configured. It will run daily at 8am, analyze yesterday's sessions, and update their file. Backups are in `~/.pi/agent/reflect-backups/`. They can check results with `/reflect-history` or `cat /tmp/pi-reflect.log`.
+
+## Configuration reference
+
+`~/.pi/agent/reflect.json`:
+
+```json
+{
+  "targets": [{
+    "path": "/absolute/path/to/AGENTS.md",
+    "model": "anthropic/claude-sonnet-4-5",
+    "lookbackDays": 1,
+    "maxSessionBytes": 614400,
+    "backupDir": "~/.pi/agent/reflect-backups",
+    "transcriptSource": { "type": "pi-sessions" }
+  }]
+}
+```
+
+- **path**: Absolute path to the target file.
+- **model**: Any `provider/model-id` the user has an API key for in pi. Default: `anthropic/claude-sonnet-4-5`.
+- **lookbackDays**: How many days of sessions to analyze. Default: `1`.
+- **maxSessionBytes**: Context budget for transcripts. Default: `614400` (~600KB).
+- **backupDir**: Where backups go before edits. Default: `~/.pi/agent/reflect-backups`.
+- **transcriptSource**: `{ "type": "pi-sessions" }` reads pi's session JSONL files. `{ "type": "command", "command": "script {lookbackDays}" }` runs a custom command instead.
+
+Multiple targets are supported — add more objects to the `targets` array.
+
+## Troubleshooting
+
+- **"No API key for model"**: The user needs to configure an API key for the model in pi. Run `/model` to check available models.
+- **"No substantive sessions found"**: No sessions with 3+ exchanges found in the lookback period. Try increasing `lookbackDays`.
+- **"Target file too small"**: The file must be at least 100 bytes. It needs some existing rules for reflect to work with.
+- **Edits skipped**: Reflect logs the reason for each skip (ambiguous match, text not found, already exists). This is a safety feature, not a bug.
+- **launchd not running**: Check `launchctl list | grep pi.reflect`. If missing, `launchctl load` the plist. Check `/tmp/pi-reflect.log` for errors. Common issue: PATH doesn't include the directory where `pi` and `node` are installed.