Pi-hindsight

pi-hindsight 🧠
Pi coding agent를 위한 자기 학습 확장 기능.

Hermes Agent의 자기 개선 루프에서 영감을 받았습니다. 매 턴이 끝난 후 백그라운드에서 Pi를 포크하여 무슨 일이 있었는지 검토하고 패턴을 저장합니다. 각 작업 전에 관련 패턴을 주입하여 Pi를 더 많이 사용할수록 더 나아지게 만듭니다.

빠른 데모
$ pi "Refactor this React component to use hooks"
-> Pi works on the task normally
(after turn ends, forked Pi reviews in background)

$ pi "Refactor this other component too"
-> [before_agent_start] Hindsight injects:
"[80%] Completed refactoring task by running tests first"
Pi sees past learnings and applies them automatically

$ /hindsight (check what's been learned)
-> Hindsight (3 total: 0 user, 3 learned)
1. [80%] Completed refactoring task by running tests first
2. [70%] Used useEffect cleanup to prevent memory leaks
3. [60%] Caught error: TypeError: Cannot read property 'map'

작동 방식
You: pi "Refactor the auth module"
->
+-- [before_agent_start] Hindsight injects relevant patterns from MEMORY.md + USER.md
+-- Agent works on task, can call learn_pattern / recall tools
+-- [turn_end] Forked Pi reviews each turn in background (user sees nothing)
-> Calls learn_pattern if it finds something worth remembering
-> Patterns saved to ~/.pi/agent/extensions/hindsight/MEMORY.md
-> User preferences saved to USER.md
+-- [agent_end] Final review to catch anything missed
-> Shows notification: "💾 Self-improvement review: Learned: ..."

설치
요구 사항

Node.js 18+
Pi coding agent v0.48+ (npm: @earendil-works/pi-coding-agent )

설치
# From GitHub (recommended)
pi install git:github.com/runchr-works/pi-hindsight

# From local checkout
cd pi-hindsight
npm install && npm run build
pi install /path/to/pi-hindsight
확인
pi -e pi-hindsight --version # should show no errors
/hindsight # should show "No patterns yet"
제거
pi remove pi-hindsight
# Or if installed from git:
pi remove git:github.com/runchr-works/pi-hindsight
저장소
Hermes Agent와 일치하는 2계층 메모리:

파일
용도
관리 주체

MEMORY.md
LLM이 학습한 패턴 (신뢰도 다양)
자동 성찰, learn_pattern 도구

USER.md
사용자가 명시한 선호도 (신뢰도 1.0, 영구)
/hindsight prefer 명령

위치: ~/.pi/agent/extensions/hindsight/

파일은 \u00a7 (단락 표시)로 구분된 항목이 있는 일반 마크다운이며, 아무 편집기로나 편집할 수 있습니다:

\u00a7 hint_abc123
type: effective-strategy
confidence: 0.8
tags: [refactoring, testing]
created: 2026-07-05T00:30:00Z
source: Refactored auth module
---
Run tests first, then refactor, then verify with tests again.

도구 (에이전트 호출 가능)
hindsight가 설치되면 이 도구들을 Pi가 사용할 수 있게 됩니다. 에이전트는
세션 중에 이들을 호출하여 명시적으로 패턴을 학습하거나 회상할 수 있습니다.

도구
설명

learn_pattern
에이전트가 작업 중 발견한 패턴을 저장합니다. 사용자 선호도에는 type=preference를 사용하세요 (USER.md로 라우팅됨)

recall
현재 작업과 관련된 과거 패턴을 조회합니다

명령어

명령어
설명

/hindsight
모든 패턴 나열 (사용자 선호도에는 [USER] 배지 표시)

/hindsight stats
유형별 패턴 통계 + 파일 개수

/hindsight path
MEMORY.md 및 USER.md 파일 경로 표시

/hindsight clear
MEMORY.md만 지움 (USER.md는 그대로 유지)

/hindsight prefer <text>
직접 사용자 선호도를 USER.md에 저장

/hindsight config
현재 성찰 설정 표시

/hindsight config set-provider <name>
성찰에 사용할 provider 설정

/hindsight config set-model <model>
성찰에 사용할 모델 설정

/hindsight config toggle
자동 성찰 활성화/비활성화

/forget <id-or-number>
두 파일 중 하나에서 특정 패턴 제거

설정
성찰 provider/모델
기본적으로 백그라운드 성찰은 현재 Pi 세션과 동일한 provider/모델을 사용합니다.
비용을 줄이기 위해 더 저렴한 모델을 설정할 수 있습니다:

/hindsight config set-provider openai
/hindsight config set-model gpt-4o-mini
/hindsight config set-model anthropic/claude-3-haiku

설정은 ~/.pi/agent/extensions/hindsight/config.json 에 저장됩니다:

{
"provider" : " openai " ,
"model" : " gpt-4o-mini " ,
"autoReflect" : true ,
"minConfidence" : 0.3
}
자동 성찰 비활성화
자동 백그라운드 검토 없이 도구( learn_pattern , recall )를 수동으로만
사용하고 싶다면:

/hindsight config toggle

비용 고려 사항
매 턴마다 성찰을 위한 백그라운드 pi.exec() 호출이 발생합니다. 즉:

턴당 추가 LLM 호출 1회 ("ok" 같은 사소한 턴은 건너뜀)
포크된 Pi는 --no-builtin-tools 를 사용하므로 learn_pattern / recall 만 사용 가능
권장: 성찰에 저렴한 모델 설정 ( gpt-4o-mini , claude-3-haiku )
성찰은 턴당 약 1-3초 추가 (포크 + LLM 호출)

프라이버시

모든 패턴은 ~/.pi/agent/extensions/hindsight/ 에 로컬로 저장됩니다
Pi에 이미 사용 중인 LLM provider 외에는 어디에도 데이터가 전송되지 않습니다
성찰 포크는 기존 Pi provider와 API 키를 사용합니다
언제든지 모든 패턴을 검사하고 삭제할 수 있습니다

아키텍처 vs Hermes Agent
Hermes Agent pi-hindsight
=============== =====================
background_review.py -> pi.exec("pi -p reflection --no-builtin-tools")
(fork agent + daemon) (fork Pi in non-interactive mode)
MEMORY.md + USER.md -> MEMORY.md + USER.md (\u00a7 markdown)
learn_prompt.py -> learn_pattern tool (agent-initiated)
build_system_prompt() -> before_agent_start systemPrompt injection

v0.1과의 주요 차이점

JSON 저장 -> 마크다운 MEMORY.md + USER.md (사람이 읽기 쉽고, git 친화적)
휴리스틱 if/else 학습 -> 포크된 Pi를 통한 LLM 기반 성찰
세션 종료 시에만 검토 -> 턴별 검토 (Hermes 스타일)
잘린 컨텍스트 -> 전체 대화 컨텍스트
콜드 캐시 -> 웜 캐시를 위해 시스템 프롬프트 접두사 재사용
보이는 sendUserMessage -> 보이지 않는 pi.exec() 백그라운드 포크
도구 지원 없음 -> 에이전트용 learn_pattern / recall 도구
설정 없음 -> 성찰을 위한 구성 가능한 provider/모델

문제 해결

문제
해결책

패턴이 학습되지 않음
/hindsight config 를 확인하고 autoReflect 가 ON인지 확인

성찰이 느리게 느껴짐
/hindsight config set-model 로 더 저렴한 모델 설정

"Command not found"
Pi 버전 확인: pi --version (v0.48+ 필요)

MEMORY.md를 찾을 수 없음
첫 세션에서 자동으로 생성됨

라이선스
MIT