pi 코딩 에이전트 (coding agents)를 위한 반복적 자기 개선 (Iterative self-improvement).

에이전트가 어떻게 행동해야 하는지, 무엇을 기억해야 하는지, 어떤 존재여야 하는지와 같은 목표 (target)를 정의하면, reflect가 이를 향해 반복적으로 개선해 나갑니다. 각 실행 단계에서는 최근 대화 내용과 참조 자료를 읽고, 에이전트의 실제 행동을 목표와 비교하여, 그 격차를 줄이기 위한 정밀한 편집 (surgical edits)을 수행합니다.

목표 정의 → reflect가 증거 읽기 → 파일 편집 → 에이전트가 목표에 근접.

모든 마크다운 (markdown) 파일에서 작동합니다: 행동 규칙 (AGENTS.md), 장기 기억 (MEMORY.md), 성격 (SOUL.md), 또는 그 외 무엇이든 가능합니다.

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

LLM API 키가 설정된 pi가 필요합니다. 각 실행 시 한 번의 LLM 호출이 발생합니다 (Sonnet 사용 시 약 $0.05–0.15).

/reflect ./AGENTS.md # 파일에 대해 reflection 실행
/reflect # 저장된 기본 목표 사용
/reflect-config # 설정된 목표 표시
...

첫 실행 시 목표를 저장할지 묻습니다. 그 이후에는 단순히 /reflect만 입력하면 됩니다.

• 증거 수집: 대화 기록 (transcripts), 일일 로그, 참조 파일 등 다양한 소스의 조합으로부터 증거를 수집합니다.
• LLM에 증거 + 목표 파일 + 원하는 최종 상태를 설명하는 프롬프트 (prompt)를 전송합니다.
• LLM은 실제 행동과 목표 사이의 격차를 식별하고, 정밀한 편집을 제안합니다.
• 편집은 안전 점검과 함께 적용됩니다: 원본을 백업하고, 모호한 일치는 건너뛰며, 의심스러울 정도로 큰 삭제는 거부하고, 목표가 리포지토리 (repo)에 있는 경우 git에 자동으로 커밋 (auto-commit) 합니다.

모든 편집은 버전 관리됩니다 — reflect는 변경 사항을 적용한 후 git에 자동으로 커밋하므로, 각 파일이 어떻게 진화했는지 전체 이력을 확인할 수 있습니다. git log AGENTS.md를 통해 에이전트가 흡수한 모든 교정 사항을 볼 수 있으며, git diff HEAD~5 SOUL.md를 통해 지난 5번의 실행 동안 성격이 어떻게 날카로워졌는지 확인할 수 있습니다.

시간이 지남에 따라 파일은 수렴합니다: 교정 사항은 규칙으로 흡수되고, 기억은 지속적인 사실로 축적되며, 성격은 일반적인 형태에서 구체적인 형태로 정교해집니다. 에이전트는 더 이상 동일한 교정을 필요로 하지 않게 됩니다.

각 목표에는 두 가지 입력 채널이 있습니다 — transcripts (발생한 일) 및 context (문맥)

(참조 자료 (reference material)). 두 채널 모두 소스 배열을 허용합니다:

모든 소스는 {lookbackDays} 보간(interpolation) 및 소스별 maxBytes 제한을 지원합니다. 파일 소스는 (파일명의 날짜를 기준으로 일치하는) lookbackDays 윈도우 내의 파일만 포함하도록 자동으로 가지치기(pruned)됩니다.

{
"targets": [{
"path": "/data/me/MEMORY.md",
...

로컬 pi 세션의 일반적인 경우에는 transcriptSource만 사용하면 됩니다:

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

각 타겟에는 reflect가 무엇을 최적화할지를 알려주는 선택적 prompt 필드가 있습니다. 동일한 엔진이라도 프롬프트에 따라 매우 다른 동작을 수행합니다:

프롬프트는 {fileName}, {targetContent}, {transcripts}, {context}를 플레이스홀더(placeholder)로 사용합니다:

{
"prompt": "당신은 AI 정체성 파일({fileName})을 진화시키고 있습니다...\n\n## 현재 상태\n{targetContent}\n\n## 대화 내용\n{transcripts}\n\n## 참조 자료\n{context}"
}

프롬프트가 설정되지 않으면, 기본적으로 행동 교정(원래의 사용 사례)을 목표로 합니다.

/reflect-stats는 reflection이 제대로 작동하고 있는지 추적합니다:

• 교정률 (Correction Rate)—corrections / sessions

실행당 수치를 계산하여 시간에 따라 그래프로 나타냅니다. 추세가 하향 곡선을 그리면 에이전트가 수렴(converging)하고 있음을 의미합니다.

• 규칙 재발 (Rule Recidivism)— 어떤 섹션이 반복적으로 수정되는지를 나타냅니다. 3회 이상 강화된 규칙은 제대로 정착되지 않은 것입니다. 한 번 수정된 후 다시 수정되지 않은 섹션은 해결된 것입니다.

/reflect-backfill

과거 세션으로부터 통계 데이터를 부트스트랩(bootstraps)합니다 (드라이 런(dry-run) 방식으로, 파일 수정은 수행하지 않음).

~/.pi/agent/reflect.json

:

{
"targets": [{
"path": "/path/to/AGENTS.md",
...

pi-mem— pi 에이전트를 위한 메모리 (Memory) 시스템입니다. 컨텍스트 주입 (context injection) 및 키워드 검색을 통해 MEMORY.md, 일일 로그, 노트, 스크래치패드 (scratchpad)를 관리합니다. pi-reflect와 자연스럽게 결합됩니다.

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

cron, launchd 또는 모든 스케줄러와 함께 작동합니다. 당신의 pi에게 설정을 요청하세요 — 에이전트를 위한 설정 가이드가 있습니다.

git clone https://github.com/jo-inc/pi-reflect && cd pi-reflect
npm install && npm test # 137개 테스트
pi -e ./extensions/index.ts # 설치 없이 로컬에서 테스트

MIT

| 패키지 (Package) | 설명 (Description) |
|---|---||
| pi-mem | 코딩 에이전트를 위한 지속 가능한 마크다운 메모리 |
| ... || pi-skill-posthog | pi 에이전트를 위한 PostHog 분석 스킬 |