Pi와 Hindsight를 연결하는 메모리 전용 확장입니다. Hindsight를 기억 지식의 정본으로 사용하고, Pi에는 Scope 식별·안전한 전달·활용 안내·전송 신뢰성·진단을 담당하는 얇은 통합 계층을 둡니다.
기존 pi-hermes-memory를 그대로 이식하거나 축소 복제하는 것이 아닙니다. 기억 추출·통합·요약을 위한 별도 Hermes 모델이나 이중 기억 관리 계층을 유지하지 않습니다.
| 역할 | 담당 |
|---|---|
| 대화에서 기억할 사실 추출·통합·보관 | Hindsight Retain 및 내부 처리 |
| 시작할 때 참고할 핵심 메모 생성·갱신 | Hindsight Mental Model |
| 현재 질문에 필요한 구체적인 기억 검색 | Hindsight Recall |
| 여러 기억을 종합하는 분석 | Hindsight Reflect — 현재 Scope 안에서 필요 시 확인 없이 호출 |
| Scope 선택, 기억 조회·전달, 활용 안내 | Pi 확장 |
| 대화 보존 요청의 재시도와 완료 확인 | Pi 확장의 영속 outbox |
| 실제 전달한 기억과 Pi 대화의 연결 보존 | 로컬 evidence.sqlite |
| 대화 원문과 세션 이력 | 기존 Pi 세션 저장소 |
완료된 Pi 대화
→ 영속 outbox
→ Hindsight Retain → 기억 추출·통합·보관
Hindsight Mental Model + 요청마다 자동 Recall
→ 현재 Scope의 참고자료 구성
→ Pi에 전달
전달 증거 + 기존 Pi 세션 연결
→ evidence.sqlite
Mental Model은 기존 USER.md·MEMORY.md가 맡던 사용자 성향·현재 유효한 규칙·프로젝트 전제 등의 핵심 메모를 미리 제공하는 역할을 대신합니다. 로컬 파일을 계속 읽는 구조는 아니며, Hindsight의 생성·갱신 기능을 사용합니다.
Mental Model 하나에 모든 기억을 담지는 않습니다.
- Mental Model: 작업 전에 알아야 할 압축된 핵심 메모입니다.
- Recall: 핵심 메모에서 빠진 세부 기억이나 현재 질문에 필요한 기억을 찾습니다. 정상적인 사용자 요청마다 자동 조회하며, 모델이 필요할 때 추가 검색할 수도 있습니다. 응답에 포함된 맥락·발생 시각·문서/청크 출처를 보존하고, 전달 예산과 안전 검사는 기록 단위로 적용합니다.
- Reflect: 단순 검색이 아니라 기억을 종합하는 별도 기능입니다. 에이전트가 필요할 때 현재 Scope 안에서 별도 사용자 확인 없이 호출합니다. 매 요청마다 자동 실행하는 것은 아닙니다.
Reflect는 서버 생성 모델의 처리 시간을 고려해 일반 조회와 별도의 reflectTimeoutMs를 사용합니다. 기본값은 120,000ms, 설정 가능한 최대값은 300,000ms이며, 일반 조회·상태 확인 등의 timeoutMs는 늘리지 않습니다. 사용자가 취소하면 긴 제한을 기다리지 않고 중단합니다. Reflect 결과에는 백엔드가 제공한 근거 ID도 포함하지만, 근거가 없는 응답에 ID를 만들어 넣지는 않습니다.
시작 메모의 수동 갱신도 현재 Scope 안에서 추가 확인 없이 요청할 수 있습니다. 갱신 요청 접수는 완료가 아닙니다. 응답의 operationId를 hindsight_memory의 status에 전달하면 startupOperation.state로 작업 상태를 확인할 수 있으며, 재시작 후에도 같은 ID로 조회할 수 있습니다. 현재 Scope에 연결된 모델의 작업만 조회하며 다른 Scope의 작업이나 원본 작업 payload는 노출하지 않습니다.
핵심 메모가 없거나 오래되어 전달하지 못해도 Recall은 독립적으로 동작합니다. 갱신 시각은 백엔드 메타데이터이며, 모든 사실·정정·삭제가 반영되었다는 보장은 아닙니다.
Recall은 기존 통합에서도 사용했습니다. 변화의 핵심은 검색의 신규 도입이 아니라 기억의 지식 처리 책임을 Hindsight에 일원화한 것입니다. Hindsight의 모든 API나 옵션을 노출한다는 뜻은 아닙니다.
- Project는 관리상의 묶음, Scope는 기억의 격리 경계입니다.
- 조회·보존에는 현재 Scope의 정확한 태그를 사용합니다. 같은 Project라는 이유로 다른 Scope의 기억을 합치지 않습니다.
- 공통 Scope와 Scope 간 검색은 지원하지 않습니다. 핵심 메모도 전역 사용자 프로필이 아니라 현재 Scope의 기억입니다.
- 등록되지 않은 위치는 동의를 거쳐 등록합니다. 동의를 받을 수 없는 실행 환경이나 등록 거부 시에는 임의 등록하거나 Hindsight에 접속하지 않습니다.
- 기억은 참고자료이지 현재 작업의 지시나 권한이 아닙니다. 현재 사용자 요청과 안전 규칙이 우선하며, 과거 제안·승인·이력을 현재 정책으로 자동 간주하지 않습니다.
자동 조회한 기억은 사용자 요청마다 한 번 준비하고, 해당 사용자 메시지 뒤에 숨겨진 Pi 메시지로 추가합니다. 같은 요청의 도구 호출이 이어져도 기억 메시지를 맨 뒤로 옮기거나 이전 기억을 삭제·교체하지 않습니다. 새 요청의 기억은 새 위치에 추가해 기존 요청의 프리픽스를 보존합니다.
기억 스냅샷은 기존 Pi 세션 이력에 저장되므로 재시작·재개 후에도 같은 위치에서 복원됩니다. 압축과 분기는 Pi의 세션 처리를 따르며, 압축된 과거 기억을 별도로 다시 주입하지 않습니다. 과거 스냅샷은 당시의 참고자료이지 현재 지시나 승인으로 간주하면 안 됩니다.
이 스냅샷에는 전달한 기억 본문이 포함됩니다. evidence.sqlite의 보관 기간·용량 상한은 Pi 세션 파일에는 적용되지 않으므로, 세션 파일의 보관·공유에도 주의해야 합니다.
확장 파일을 갱신해도 실행 중인 Pi의 핸들러는 자동 교체되지 않습니다. 기존 세션은 응답과 압축이 끝난 뒤 입력창에서 /reload를 실행해야 합니다. 대화를 새로 만들 필요는 없으며, 도구·모델·문맥 압축이나 서버 상태에 따른 캐시 미스까지 방지하는 것은 아닙니다.
증거 저장을 활성화하면 설정된 디렉터리의 evidence.sqlite에 요청별 상태, 실제 전달한 기억의 본문, 기존 Pi 세션의 메시지 연결 등을 보존합니다. Scope·요청 인덱스와 SQLite WAL을 사용하며, 목록 메타데이터와 전달본문을 분리해 조회합니다.
이 저장소는 진단용 기록이지 또 하나의 기억 지식 저장소가 아닙니다. 대화 원문을 중복 저장하거나 증거를 Hindsight 지식으로 자동 재주입하지 않습니다.
- 준비한 기억, Pi 문맥에 연결한 기억, provider payload에서 확인한 기억을 구분합니다.
- payload에서 확인했다는 것이 네트워크 수신이나 답변의 올바른 활용을 증명하지는 않습니다.
- 자동 품질 채점이나 정기 품질 보고 기능은 없습니다. 의심 사례는 전달본문과 실제 Pi 대화를 대조해 검색 누락·전달 제외·답변 미준수를 구분해야 합니다.
- 기록 실패 시 대화는 계속되며, UI 경고와
hindsight_memory의status에서 진단할 수 있습니다.
전달본문에는 민감한 기억이 포함될 수 있습니다. 저장소는 소유자 전용 권한으로 보호하고 보관 기간·용량 상한을 적용하지만, 비밀정보 차단은 모든 민감정보를 탐지하는 보장이 아닙니다. 용량 상한 때문에 설정한 기간보다 짧게 보관될 수 있습니다.
기존 JSONL 증거는 커서 기반으로 이어서 이관하고 원본을 자동 삭제하지 않습니다. 보존한 원본의 용량도 예산에 포함하므로, 공간이 부족하면 원본을 임의 삭제하거나 상한을 확대하는 대신 실패를 알립니다.
구버전 확장을 제거하는 것과 레거시 데이터 폴더를 삭제하는 것은 별개입니다. 현재 설정의 catalogPath나 Pi의 스킬 검색 경로가 기존 폴더를 참조할 수 있습니다. 참조를 확인하고 필요한 데이터·스킬을 안전하게 옮기기 전에는 이름만 보고 폴더를 삭제하면 안 됩니다.
Project·Scope ID, 정확한 태그, 카탈로그, 자격 증명, 스킬과 복구용 데이터는 확장 교체와 별도로 보존해야 합니다. 스킬 관리는 이 메모리 확장의 기능 범위에 포함되지 않습니다.