{"_id":"@askjo/pi-reflect","_rev":"3-436c01cd2186897c41ddef56cd68344c","name":"@askjo/pi-reflect","dist-tags":{"latest":"1.2.0"},"versions":{"1.0.0":{"name":"@askjo/pi-reflect","version":"1.0.0","keywords":["pi-package","pi-extension","pi","coding-agent","self-improvement","agents-md","behavioral-rules","reflection"],"author":{"name":"Pradeep Elankumaran","email":"pradeepe@gmail.com"},"license":"MIT","_id":"@askjo/pi-reflect@1.0.0","maintainers":[{"name":"askjo","email":"oss+jo@askjo.ai"}],"homepage":"https://github.com/jo-inc/pi-reflect#readme","bugs":{"url":"https://github.com/jo-inc/pi-reflect/issues"},"pi":{"image":"https://raw.githubusercontent.com/jo-inc/pi-reflect/main/logo.png","extensions":["./extensions/index.ts"]},"dist":{"shasum":"d838bf6cfe21f5ce792be049a391d93dfad8be09","tarball":"https://registry.npmjs.org/@askjo/pi-reflect/-/pi-reflect-1.0.0.tgz","fileCount":17,"integrity":"sha512-pwaRNn2y1f769DJ7Yw57SQqNRAN7t0UROdTahXECF58hYbAYWh6eODE48cv6BOOe8jWUdn35QqY9CjrDw1tYhw==","signatures":[{"sig":"MEYCIQCyQAMjtkLHNzw8t9JpZy8fTUo2Vn4EJh7LUgWPxdWwIwIhAKasCjaVK+iacGBgPvq76OQ6Y3L8qoG4yD/gZ9QIW7FM","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":14735812},"type":"module","gitHead":"906e3c6e1fe180c836e5e2d0ebb84480beed7139","scripts":{"test":"node --import tsx --test tests/*.test.ts"},"_npmUser":{"name":"askjo","email":"oss+jo@askjo.ai"},"repository":{"url":"git+https://github.com/jo-inc/pi-reflect.git","type":"git"},"_npmVersion":"11.9.0","description":"Self-improving behavioral files for pi coding agents. Analyzes session transcripts for correction patterns and makes surgical edits to prevent recurrence.","directories":{},"_nodeVersion":"24.10.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","@types/node":"^22.0.0"},"peerDependencies":{"@mariozechner/pi-ai":"*","@mariozechner/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-reflect_1.0.0_1771450249925_0.676240088280204","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@askjo/pi-reflect","version":"1.1.0","keywords":["pi-package","pi-extension","pi","coding-agent","self-improvement","agents-md","behavioral-rules","reflection"],"author":{"name":"Pradeep Elankumaran","email":"pradeepe@gmail.com"},"license":"MIT","_id":"@askjo/pi-reflect@1.1.0","maintainers":[{"name":"askjo","email":"oss+jo@askjo.ai"}],"homepage":"https://github.com/jo-inc/pi-reflect#readme","bugs":{"url":"https://github.com/jo-inc/pi-reflect/issues"},"pi":{"image":"https://raw.githubusercontent.com/jo-inc/pi-reflect/main/logo.png","extensions":["./extensions/index.ts"]},"dist":{"shasum":"7f98a5b4061cd94999779f2b2e9c9ba7a849dc20","tarball":"https://registry.npmjs.org/@askjo/pi-reflect/-/pi-reflect-1.1.0.tgz","fileCount":18,"integrity":"sha512-Hzk47qBwSGk0TongeLNmseI70KAN6D/+mayMYI+43lLdeu9JdDVXtma+ORiz3lHn3IOk35mWFxCdKB0EDNJKfQ==","signatures":[{"sig":"MEQCIHmkS5bloXW1Ly/hcw5wml8oqjG0R6asETjR1oX32qYDAiAYtABf3F8aqNOc2eGebvJH2hDBk7S3BEovN1Z3cJDB9g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":14764096},"type":"module","gitHead":"f822c2e52c44b3ee6a7b8a6f1e1fbaf301b7ba2f","scripts":{"test":"node --import tsx --test tests/*.test.ts"},"_npmUser":{"name":"askjo","email":"oss+jo@askjo.ai"},"repository":{"url":"git+https://github.com/jo-inc/pi-reflect.git","type":"git"},"_npmVersion":"11.9.0","description":"Self-improving behavioral files for pi coding agents. Analyzes session transcripts for correction patterns and makes surgical edits to prevent recurrence.","directories":{},"_nodeVersion":"24.10.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","@types/node":"^22.0.0"},"peerDependencies":{"@mariozechner/pi-ai":"*","@mariozechner/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-reflect_1.1.0_1771870181416_0.7321631925499426","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@askjo/pi-reflect","version":"1.2.0","description":"Self-improving behavioral files for pi coding agents. Analyzes session transcripts for correction patterns and makes surgical edits to prevent recurrence.","keywords":["pi-package","pi-extension","pi","coding-agent","self-improvement","agents-md","behavioral-rules","reflection"],"license":"MIT","author":{"name":"Pradeep Elankumaran","email":"pradeepe@gmail.com"},"repository":{"type":"git","url":"git+https://github.com/jo-inc/pi-reflect.git"},"bugs":{"url":"https://github.com/jo-inc/pi-reflect/issues"},"homepage":"https://github.com/jo-inc/pi-reflect#readme","type":"module","scripts":{"test":"node --import tsx --test tests/*.test.ts"},"pi":{"extensions":["./extensions/index.ts"],"image":"https://raw.githubusercontent.com/jo-inc/pi-reflect/main/logo.png"},"publishConfig":{"access":"public"},"peerDependencies":{"@mariozechner/pi-coding-agent":"*","@mariozechner/pi-ai":"*"},"devDependencies":{"tsx":"^4.19.0","@types/node":"^22.0.0"},"gitHead":"33a72886c8d5882b8b89a4a0ace1bb8d35403ef2","_id":"@askjo/pi-reflect@1.2.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-QwgfzCyT4y9BpzlkuDlPn/2NYnDp/4CkpfhYXvxd3rjQ4+XVxyEg+8ZMguATO3m2xWr3Ivyw+pZBugtXPlPuCA==","shasum":"a55189f978266caf58863d979b85b0d3882b00c4","tarball":"https://registry.npmjs.org/@askjo/pi-reflect/-/pi-reflect-1.2.0.tgz","fileCount":23,"unpackedSize":14800477,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@askjo%2fpi-reflect@1.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBvXwG3I/7xYhb5CX1Iv+mbEIO1ecCWY44xO+36IZtnfAiEA9BOe3immIS2ivSxZcqocpB3tdXaO/c+DWK54D9xkHTQ="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:4fdbe687-b887-41ff-bce3-8d99079625c1"}},"directories":{},"maintainers":[{"name":"askjo","email":"oss+jo@askjo.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-reflect_1.2.0_1784655095115_0.29332970230109123"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-18T21:30:49.789Z","modified":"2026-07-21T17:31:35.888Z","1.0.0":"2026-02-18T21:30:50.619Z","1.1.0":"2026-02-23T18:09:41.955Z","1.2.0":"2026-07-21T17:31:35.562Z"},"bugs":{"url":"https://github.com/jo-inc/pi-reflect/issues"},"author":{"name":"Pradeep Elankumaran","email":"pradeepe@gmail.com"},"license":"MIT","homepage":"https://github.com/jo-inc/pi-reflect#readme","keywords":["pi-package","pi-extension","pi","coding-agent","self-improvement","agents-md","behavioral-rules","reflection"],"repository":{"type":"git","url":"git+https://github.com/jo-inc/pi-reflect.git"},"description":"Self-improving behavioral files for pi coding agents. Analyzes session transcripts for correction patterns and makes surgical edits to prevent recurrence.","maintainers":[{"name":"askjo","email":"oss+jo@askjo.ai"}],"readme":"

\n \"License:\n \"GitHub\n

\n

\n \n \n \"pi-reflect\"\n \n

\n\n# pi-reflect\n\nIterative self-improvement for [pi](https://github.com/badlogic/pi-mono) coding agents.\n\nDefine 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.\n\n**define the target → reflect reads evidence → edits the file → the agent gets closer.**\n\nWorks on any markdown file: behavioral rules (`AGENTS.md`), long-term memory (`MEMORY.md`), personality (`SOUL.md`), or anything else.\n\n## Install\n\n```bash\npi install git:github.com/jo-inc/pi-reflect\n```\n\nRequires pi with an LLM API key configured. Each run makes one LLM call (~$0.05–0.15 with Sonnet).\n\n## Usage\n\n```\n/reflect ./AGENTS.md # run reflection on a file\n/reflect # use saved default target\n/reflect-config # show configured targets\n/reflect-history # show recent runs\n/reflect-stats # correction rate trend + rule recidivism\n/reflect-backfill # bootstrap stats for all historical sessions\n```\n\nFirst run asks if you want to save the target. After that, just `/reflect`.\n\n## How it works\n\n1. Collects evidence: conversation transcripts, daily logs, reference files — from any combination of sources\n2. Sends the evidence + the target file + a prompt describing the desired end state to an LLM\n3. The LLM identifies gaps between actual behavior and the target, proposes surgical edits\n4. 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\n\nEvery 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.\n\nOver 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.\n\n## Data sources\n\nEach target has two input channels — `transcripts` (what happened) and `context` (reference material). Both accept an array of sources:\n\n| Type | Description | Example |\n|------|-------------|---------|\n| `files` | Glob patterns or file paths, pruned by date and size | Daily logs, notes, other markdown files |\n| `command` | Shell command, stdout captured | API calls, database queries, custom scripts |\n| `url` | HTTP GET, response body captured | REST endpoints, health checks |\n\nAll 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).\n\n```json\n{\n \"targets\": [{\n \"path\": \"/data/me/MEMORY.md\",\n \"model\": \"anthropic/claude-sonnet-4-5\",\n \"lookbackDays\": 1,\n \"transcripts\": [\n { \"type\": \"command\", \"label\": \"conversations\", \"command\": \"curl -s http://localhost:3001/conversation/recent?days={lookbackDays}\", \"maxBytes\": 400000 }\n ],\n \"context\": [\n { \"type\": \"files\", \"label\": \"daily logs\", \"paths\": [\"/data/me/daily/*.md\"], \"maxBytes\": 50000 },\n { \"type\": \"files\", \"label\": \"notes\", \"paths\": [\"/data/me/notes/*.md\"], \"maxBytes\": 50000 }\n ],\n \"prompt\": \"...\"\n }]\n}\n```\n\nFor the common case of local pi sessions, just use `transcriptSource`:\n\n```json\n{ \"transcriptSource\": { \"type\": \"pi-sessions\" } }\n```\n\n## Prompts define the target\n\nEach target has an optional `prompt` field that tells reflect *what to optimize for*. The same engine drives very different behaviors depending on the prompt:\n\n| Target | Prompt goal | What reflect does |\n|--------|------------|-------------------|\n| `AGENTS.md` | Behavioral correctness | Strengthens violated rules, adds rules for recurring patterns |\n| `MEMORY.md` | Factual completeness | Extracts durable facts from conversations, removes stale entries |\n| `SOUL.md` | Identity convergence | Sharpens personality from generic to specific based on interaction patterns |\n\nPrompts use `{fileName}`, `{targetContent}`, `{transcripts}`, and `{context}` as placeholders:\n\n```json\n{\n \"prompt\": \"You are evolving an AI identity file ({fileName})...\\n\\n## Current\\n{targetContent}\\n\\n## Conversations\\n{transcripts}\\n\\n## Reference\\n{context}\"\n}\n```\n\nIf no prompt is set, the default targets behavioral corrections (the original use case).\n\n## Impact Metrics\n\n`/reflect-stats` tracks whether reflection is working:\n\n- **Correction Rate** — `corrections / sessions` per run, plotted over time. Trending down = the agent is converging.\n\n- **Rule Recidivism** — which sections get edited repeatedly. A rule strengthened 3+ times isn't sticking. Sections edited once and never again are resolved.\n\n`/reflect-backfill` bootstraps stats from historical sessions (dry-run, no file edits).\n\n## Configuration\n\n`~/.pi/agent/reflect.json`:\n\n```json\n{\n \"targets\": [{\n \"path\": \"/path/to/AGENTS.md\",\n \"model\": \"anthropic/claude-sonnet-4-5\",\n \"lookbackDays\": 1,\n \"maxSessionBytes\": 614400,\n \"backupDir\": \"~/.pi/agent/reflect-backups\",\n \"transcriptSource\": { \"type\": \"pi-sessions\" }\n }]\n}\n```\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| `path` | *(required)* | Target markdown file to iterate on |\n| `model` | *(required)* | LLM to use (e.g. `anthropic/claude-sonnet-4-5`) |\n| `lookbackDays` | `1` | How far back to look for evidence |\n| `maxSessionBytes` | `614400` | Max transcript bytes per run |\n| `transcripts` | — | Array of `ContextSource` for transcript data |\n| `transcriptSource` | `pi-sessions` | Legacy single source (use `transcripts` for multiple) |\n| `context` | — | Array of `ContextSource` for reference material |\n| `prompt` | *(default)* | Custom prompt with `{fileName}`, `{targetContent}`, `{transcripts}`, `{context}` |\n| `backupDir` | `~/.pi/agent/reflect-backups` | Where to store pre-edit backups |\n\n## Related\n\n- **[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.\n\n## Scheduling\n\n```bash\npi -p --no-session \"/reflect /path/to/AGENTS.md\"\n```\n\nWorks with cron, launchd, or any scheduler. Ask your pi to set it up for you — there's a [setup guide for agents](SETUP.md).\n\n## Development\n\n```bash\ngit clone https://github.com/jo-inc/pi-reflect && cd pi-reflect\nnpm install && npm test # 137 tests\npi -e ./extensions/index.ts # test locally without installing\n```\n\n## License\n\nMIT\n\n## Pi Ecosystem\n\n| Package | Description |\n|---------|-------------|\n| [pi-mem](https://github.com/jo-inc/pi-mem) | Persistent markdown memory for coding agents |\n| [pi-boss](https://github.com/skyfallsin/pi-boss) | Multi-agent orchestration via tmux |\n| [pi-room](https://github.com/skyfallsin/pi-room) | Multi-agent awareness and coordination |\n| [pi-vertex-anthropic](https://github.com/skyfallsin/pi-vertex-anthropic) | Claude via Google Cloud Vertex AI |\n| [pi-skill-posthog](https://github.com/skyfallsin/pi-skill-posthog) | PostHog analytics skill for pi agents |\n","readmeFilename":"README.md"}