pi-mem을 사용하여 pi coding agent에 기억을 부여하는 도입 가이드 (테스트 버전)
요약
pi coding agent에 세션을 넘나드는 영구적인 기억을 부여하는 확장 기능인 pi-mem의 도입 가이드입니다. Extension API를 활용하여 컨텍스트 자동 주입과 도구 등록 메커니즘을 통해 에이전트의 연속성을 확보하는 방법을 설명합니다.
핵심 포인트
- pi의 Extension API를 사용하여 컨텍스트 주입 및 도구 등록 수행
- MEMORY.md, SCRATCHPAD.md 등 마크다운 기반의 기억 저장 방식
- pi 버전(0.75 이상)에 따른 올바른 패키지 선택의 중요성 강조
- 사용자의 취향과 작업 로그를 자동 저장하여 반복 설명 방지
배경
AI agent의 기억이 매번 사라지는 것을 방지하기 위한 pi-mem에 관한 내용입니다. 추가적인 별도 도구를 테스트해 본 내용입니다.
주의사항
pi-mem은 pi coding agent (이하 pi)에 세션을 넘나드는 기억을 부여하는 확장 기능입니다. 취향이나 결정 사항을 자동으로 기억·주입하여, 매번 같은 설명을 하지 않아도 되도록 합니다. AI로 조사하며 테스트를 진행한 내용을 간단히 정리해 보았습니다. 잘못된 내용이 포함되어 있을 가능성이 있으므로, 자기 책임하에 사용해 주시기 바랍니다.
할 수 있는 일: 취향·결정 사항의 영구 기억 (MEMORY.md), 진행 중인 태스크의 체크리스트 (SCRATCHPAD.md), 일일 로그의 자동 저장 (daily/), 기술 TIPS 정리 (notes/)
이 글이 필요한 이유: 오리지널 패키지가 pi ≥ 0.75에서 동작하지 않는 버그가 있어, 올바른 패키지를 선택하지 않으면 기억이 전혀 기능하지 않습니다. 선택부터 설정·운용까지 검증 결과에 기반하여 해설합니다.
환경
- OS: Windows 11 Pro (WSL2 Ubuntu 22.04.5 LTS)
- Node.js: v22.22.2 / npm: 10.9.7
- pi: 0.79.4
- @haha1903/pi-mem: 1.0.1
어떻게 동작하는가
pi-mem은 pi의 Extension API를 사용하여 동작합니다. AGENTS.md를 고쳐 쓰는 것이 아닙니다.
크게 두 가지 메커니즘이 있습니다:
1. 자동 컨텍스트 주입 (Automatic Context Injection) (에이전트에 대한 지시 추가)
- pi의 확장 이벤트인
on("context")에 후킹(Hook) - 세션 시작 시 MEMORY.md + SCRATCHPAD.md + 최근 2일간의 daily를 읽어들임 - 그것들을
role: "user"메시지로서 LLM과의 대화에 삽입 - 에이전트는 자동으로 "기억을 가지고 있는 상태"로 대화를 시작함 - AGENTS.md와는 별개임. AGENTS.md는 pi 본체가 읽고, pi-mem은 확장으로서 별도로 주입함
2. 도구 등록 (Tool Registration) (에이전트가 자발적으로 기억을 조작)
memory_write/memory_read/memory_search/scratchpad의 4가지 도구를registerTool로 등록 - 에이전트는 사용자의 지시에 따라 자발적으로 이것들을 호출함- 호출 결과는 모두
~/.pi/agent/memory/이하의 .md 파일에 저장됨 - 다음 세션 시작 시 1번의 메커니즘으로 자동 로드됨
즉:
AGENTS.md를 고쳐 쓰는 것도 아니고, 프롬프트 보정을 수행하는 것도 아닙 - pi의 Extension API (on("context")와 registerTool)를 사용한 정식 확장 기능으로서 동작함 - 저장 위치는 단순한 Markdown 파일이므로 인간이 직접 편집·삭제도 가능함
왜 pi-mem이 필요한가
- 매 세션마다 취향이나 결정 사항을 다시 설명해야 하는 번거로움이 사라짐
- 작업의 중간 경과가 일일 로그로 자동 저장됨
- 체크리스트로 진행 중인 태스크를 관리할 수 있음
- 모두 Markdown 파일이므로 인간도 읽고 쓸 수 있음
주의: 패키지 선택이 중요
pi-mem은 아직 개발 중인 확장 기능입니다. 이용 방법이나 운용 수법은 확립되지 않았으며, 향후 변경될 가능성이 있습니다. 이 글은 2026년 6월 시점의 검증 결과에 기반합니다.
여러 패키지가 존재하며, 선택을 잘못하면 기억이 전혀 기능하지 않습니다.
3가지 패키지 상황
| 패키지 | 상태 | 설명 |
|---|---|---|
@askjo/pi-mem (오리지널) | ⚠️ 현재 동작하지 않음 | jo-inc 제작. ★62. pi ≥ 0.75에서 버그 있음. 추후 수정될 가능성 있음 |
(포크) @haha1903/pi-mem | ✅ 잠정 권장 | 위의 포크 버전. 버그 수정판 |
pi-mem | ⚠️ 별도 계통 | LanceDB 의존의 벡터 검색(Vector Search) 버전. 용도가 다름 |
오리지널에서 버그가 발생하는 이유
현상: 오리지널 패키지를 설치해도 MEMORY.md나 SCRATCHPAD.md의 내용이 에이전트에 반영되지 않음. memory_write로 기록한 기억이 다음 세션에서 참조되지 않음.
원인: LLM으로 보내는 메시지에는 "누가 말했는지"를 나타내는 role (역할)이 있습니다. role: "system"은 "시스템으로부터의 지시"를, role: "user"는 "사용자의 발언"을 의미합니다. pi-mem은 기억 파일의 내용을 이 role로 LLM에 전송하지만, 원본(upstream)은 role: "system"을 사용하고 있습니다.
pi v0.75 이후부터 pi는 LLM에 보내기 전에 role: "system" 메시지를 조용히 폐기하도록 변경되었습니다. 즉, 원본이 보낸 기억은 LLM에 전혀 전달되지 않으며, 기록은 되었음에도 참조되지 않는 상태가 됩니다.
포크(Fork) 버전은 이를 role: "user"로 변경했습니다. 사용자 발언으로서 전송되기 때문에 LLM에 전달됩니다. 또한 사람이 읽을 수 있는 내용임을 알 수 있도록 <pi-mem-injected> 태그로 감싸서 실제 사용자 입력과 구분하고 있습니다.
영향 범위: pi-mem의 핵심 기능인 자동 컨텍스트 주입(Automatic Context Injection)이 통째로 무효화됩니다. memory_write 자체는 성공하지만, 기록된 내용이 세션 시작 시 주입되지 않기 때문에 "기억했을 텐데 기억하지 못하는" 상태가 됩니다.
// 원본 (@askjo/pi-mem) — 기억이 전달되지 않음
const messages = [...event.messages, { role: "system", content: memoryInstructions }];
// pi ≥ 0.75에서는 role: "system" 메시지가 폐기됨
...
- 이것은 버그가 아니라, pi 측의 사양 변경에 원본이 대응하지 못해 발생하는 결함입니다.
- 원본은 2026년 2월부터 업데이트가 중단된 상태입니다.
@haha1903/pi-mem은 이 한 부분만을 수정한 포크입니다. 기능 차이는 이 수정 사항뿐이며, 나머지는 동일한 코드베이스를 사용합니다.- 원본에서 수정 사항이 머지(Merge)된 단계라면 @askjo 버전으로 갈아타도 괜찮습니다.
- 단, 향후에 pi의 사양이 다시 변경될 가능성도 있으며, 그럴 경우 양쪽 모두 대응이 필요합니다.
- 2026년 6월 시점에서는 원본의 결함이 수정되지 않았으나, jo-inc 리포지토리는 활발히 업데이트되고 있어 향후 수정될 가능성도 있습니다. 도입 전에 최신 GitHub (jo-inc/pi-mem)에서
role: "system"이 수정되었는지 확인하십시오.
다른 AI의 권장 사항 주의
일부 AI가 "원본이 더 활발하고 안정적이다"라고 권장하는 경우가 있으나, 이는 소스 코드를 확인하지 않고 npm 업데이트 날짜나 스타(Star) 수만으로 판단하고 있을 가능성이 있습니다. 실제로 코드를 비교해 보면 원본은 위의 결함이 수정되지 않은 상태입니다.
설치
pi install npm:@haha1903/pi-mem
이것이 전부입니다. pi를 실행하면 자동으로 도구가 등록되며, 파일은 처음 사용할 때 생성됩니다.
디렉토리 구조
~/.pi/agent/memory/
├── MEMORY.md # 장기 기억 (취향, 결정 사항, 영구적 사실)
├── SCRATCHPAD.md # 체크리스트 (진행 중인 작업의 TODO)
...
자동으로 주입되는 것은 MEMORY.md + SCRATCHPAD.md (미완료 항목만) + 오늘 + 어제의 daily입니다. notes/는 필요할 때 검색하여 참조합니다. pi-mem의 소스 코드 내 ensureDirs()가 자동으로 생성하는 기본 구성입니다.
토큰량 기준
자동 주입되는 내용은 MEMORY.md + SCRATCHPAD.md + 최근 2일간의 daily입니다. 테스트 직후의 최소 구성은 약 1,700자(토큰 환산 시 약 2K~4K 정도, 모델에 따라 다름)였습니다. 운용이 진행됨에 따라 MEMORY.md나 daily가 늘어나면 토큰 소비도 증가하므로, MEMORY.md는 사람이 정기적으로 리뷰 및 요약하여 불필요한 항목을 삭제해 주세요.
4가지 도구
memory_write (기록하기)
| target | 쓰기 위치 | 덮어쓰기/추가 |
|---|---|---|
long_term | MEMORY.md | append 또는 overwrite |
daily | daily/YYYY-MM-DD.md | 항상 추가(append)만 가능 |
note | notes/임의의 파일명 | append 또는 overwrite |
"내 취향을 기억해줘: 일본어로 간결하게 답변"
→ target=long_term, mode=append
"오늘의 작업 메모를 남겨줘: API 리뷰를 마침"
...
소스 코드(index.ts 주석 내) 원문 예시:
- '만약 누군가 "이것을 기억해"라고 말하면, 즉시 기록하세요.'
- "다음 메모 파일들이 로드되었습니다. 중요한 정보를 영구 저장하려면 memory_write 도구를 사용하세요." - "의미 있는 상호작용 후에는 간결한 1~2문장 요약과 함께 memory_write(target='daily')를 호출하세요."
memory_read (읽기)
| target | 읽는 위치 |
|---|---|
long_term | MEMORY.md |
scratchpad | SCRATCHPAD.md |
daily | 일일 로그(날짜 지정 가능) |
note | notes/ 내의 파일 |
file | 임의의 경로 |
list | 전체 파일 목록 |
memory_search (검색)
모든 파일을 키워드로 검색합니다(대소문자 구분 없음).
"React에 대해 작성한 기록을 검색해줘"
scratchpad (체크리스트 조작)
| action | 동작 |
|---|---|
add | 항목 추가 |
done | 완료 표시(부분 일치) |
undo | 완료 표시 해제 |
clear_done | 완료된 항목 일괄 삭제 |
list | 전체 항목 표시 |
"체크리스트에 추가해줘: 리팩토링을 실행한다"
"〇〇를 완료로 해줘"
"완료된 항목들을 정리해줘"
4가지 메모 파일의 사용 구분
| 파일 | 역할 | 예시 |
|---|---|---|
| MEMORY.md | 영구적인 사실・선호도 | "한국어로 답변", "React로 개발 중" |
| ... | ||
| daily와 notes의 차이: |
- daily = 일기(그날 한 일에 대한 짧은 메모) -
- notes = 기술 TIPS(나중에 다시 볼 정리된 요약)
테스트 절차
설치 후, pi를 실행하여 다음을 시도해 보세요:
"내 선호도를 기억해줘: 한국어로 간결하게 답변하기"
→ memory_write가 발동 → MEMORY.md에 기록됨
"체크리스트에 추가해줘: pi-mem 테스트 완료"
...
AGENTS.md와의 연계 (권장)
pi에는 2개의 AGENTS.md 읽기 위치가 있습니다:
| 위치 | 스코프 | 언제 읽히는가 |
|---|---|---|
~/.pi/agent/AGENTS.md | 전역(모든 프로젝트 공통) | 매 세션 시작 시 |
프로젝트 루트/AGENTS.md | 프로젝트 고유 | 해당 프로젝트에서만 |
글로벌 AGENTS.md (모든 프로젝트 공통)
~/.pi/agent/AGENTS.md
:
# 에이전트 행동 지침
- 모든 것을 한국어로 간결하게 답변할 것
- 중요한 사실・결정・선호도는 즉시 memory_write로 기록할 것
...
포인트: 글로벌에는 언어・스타일・pi-mem의 기본 규칙만 작성합니다.
프로젝트 고유 AGENTS.md
프로젝트 루트/AGENTS.md
:
# 이 프로젝트의 규칙
- Python 3.12 + FastAPI
- 테스트는 pytest 필수
...
포인트: 프로젝트 고유의 규칙만 작성합니다. pi-mem 사용법은 글로벌에 맡깁니다.
두 AGENTS.md가 읽히는 방식
세션 시작
↓
~/.pi/agent/AGENTS.md ─────┐
...
중복해서 작성할 필요가 없습니다. 글로벌에 작성된 규칙은 모든 프로젝트에 반영됩니다.
상세한 사용법은 note에 저장하기
AGENTS.md는 매번 주입되기 때문에, 토큰 효율성 관점에서 최소화하는 것이 중요합니다. pi-mem 사용법의 자세한 내용은 notes/pi-mem-usage.md 에 저장하고, 필요할 때만 검색하여 참조합니다:
"notes/pi-mem-usage.md를 만들어줘. pi-mem 사용법을 정리해줘"
이로써 AGENTS.md는 짧게 유지하면서도, 사용법을 잊어버렸을 때는 memory_read target=note filename=pi-mem-usage.md 명령으로 호출할 수 있습니다.
설정 (옵션)
기본 설정으로 작동하지만, 필요한 경우 ~/.pi/agent/memory/.pi-mem.json 파일을 생성하세요:
{
"contextFiles": ["AGENTS.md", "SOUL.md"],
"searchDirs": ["projects"],
...
}
| 키 | 기본값 | 효과 |
|---|---|---|
contextFiles | 비어 있음 | 추가로 컨텍스트 (Context)를 주입할 파일 |
searchDirs | 비어 있음 | memory_search의 검색 대상 디렉토리 |
autocommit | false | 쓰기 시 git 자동 커밋 |
테스트 결과
pi 0.79.4 + @haha1903/pi-mem v1.0.1에서 모든 테스트 성공:
| 테스트 | 결과 |
|---|---|
| memory_write (MEMORY.md) | ✅ |
| ... |
pi-mem vs OpenViking
| pi-mem | OpenViking |
|---|---|
| 개요 | Markdown 경량 기억 |
| ... |
pi 단독으로 사용한다면 pi-mem으로 충분합니다. 대규모 코드베이스의 시맨틱 검색 (Semantic Search)이 필요한 단계에서 OpenViking을 검토하십시오.
되돌리기 절차
pi uninstall @haha1903/pi-mem
rm -rf ~/.pi/agent/memory/
요약
@haha1903/pi-mem을 사용할 것 (원본은 현재 버그가 있음. 개발 중이므로 사양 변경 가능성 있음) - 설치 명령 한 번으로 즉시 작동- MEMORY.md = 장기 기억, SCRATCHPAD.md = TODO, daily/ = 일기, notes/ = TIPS
- AGENTS.md에 최소한의 규칙을 작성하고, 상세 내용은 notes에 저장하면 토큰 효율 (Token Efficiency)이 좋습니다.
- 모든 것이 단순한 Markdown 파일이므로 직접 편집하거나 삭제하는 것이 자유롭습니다.
- pi의 확장 API (Extension API) (
on("context")+registerTool)로 작동하는 정식 확장 기능입니다. AGENTS.md를 무단으로 수정하거나 프롬프트를 보정하는 방식이 아닙니다. Claude Code 등 클라우드 의존적인 기억과 달리, 벤더 락인 (Vendor Lock-in)이 없고 블랙박스(Black Box)도 없습니다. 기억이 이상하다면 파일을 직접 열어 확인 및 수정할 수 있으므로, 조용히 수정되거나 변경되어 알아채지 못하는 문제를 방지할 수 있습니다. - 아직 완전 자동은 아님:
memory_write나memory_read가 의도대로 작동하지 않을 수 있습니다. 그럴 경우 "memory_write target=long_term 으로 기억해줘", "memory_read target=long_term 으로 확인해줘"와 같이 도구 이름과 파라미터를 명시적으로 지시하면 확실하게 작동합니다. 암묵적으로 기대하기보다 명시적으로 지정하는 것이 더 안정적입니다. - 기억이 참조되지 않을 때도 있음: MEMORY.md에 "MD 파일 작성 시 가급적 빈 줄을 만들지 않고 스크롤을 최소화하여 보기 좋게 만든다"라고 기록해 두어도, 파일 작성 시 반영되지 않는 경우가 있었습니다. AGENTS.md에 "파일 작성 및 답변 전에 MEMORY.md의 선호 사항을 반드시 반영할 것"을 추가하여 개선했지만, 기억을 읽어오는 것과 그것이 반영되는 것은 별개의 문제라는 점에 유의해야 합니다.
이번 구성(AGENTS.md 5줄 + MEMORY.md + SCRATCHPAD + daily + notes)은 현시점에서의 시도이며, 최적화되어 있지 않을 수 있습니다. 예를 들어 daily 로그의 비대화 방지 대책이나 SCRATCHPAD 운영 규칙, notes 정리 방법 등은 사용하면서 과제가 드러날 것입니다. 더 효율적인 사용법을 찾게 되면 수시로 업데이트하겠습니다. 또한, pi-mem 외에도 pi-memory-md나 jayzeng/pi-memory와 같은 유사한 확장 기능이 존재합니다. 용도에 맞춰 비교 검토하십시오.
최악의 경우 4가지 도구를 명시적으로 지정하는 예시:
- memory_write target=long_term mode=append — 장기 기억 (long-term memory)에 추가
- memory_write target=daily — 일일 로그 (daily log)에 추가
- memory_write target=note filename=xxx.md — 노트 (note)에 저장
- memory_read target=long_term — 장기 기억 (long-term memory) 읽기
- memory_search query=키워드 — 교차 검색 (cross-search)
- scratchpad action=add — 체크리스트 (checklist) 추가
Discussion
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기