piia-engram: 로컬 우선의 개인용 AI 정체성 레이어

AI에게 당신이 누구인지, 어떻게 일하는지, 그리고 무엇이 "좋은 것"인지 단 한 번만 알려주세요. Claude Code, Codex, Cursor, Windsurf 및 기타 MCP 호환 도구들은 동일하게 승인된 컨텍스트(Context)에서 시작할 수 있습니다. 이는 당신이 소유한 로컬 파일이며, 클라우드 계정도 필요 없고, 당신이 검사할 수 없는 숨겨진 메모리도 없습니다.

설치 · 작동 모습 보기 · 지원되는 도구 · MCP 도구 · FAQ

다음 목록에도 포함되어 있습니다: awesome-agents · Awesome-MCP-ZH · mcpservers.org · Cursor Directory · ModelScope · PulseMCP

요약(TL;DR): piia-engram은 로컬 우선(local-first)의 개인용 AI 정체성 레이어(identity layer)입니다. 이는 여러 코딩 에이전트(coding agents)가 당신에 대한 동일한 이해(당신의 선호도, 품질 기준, 학습된 교훈, 결정 사항, 프로젝트 컨텍스트)를 바탕으로 시작할 수 있도록 돕습니다. 이것은 에이전트 메모리 데이터베이스가 아니라, 당신의 도구들 위에 존재하는 사용자 소유의 레이어입니다.

왜 네이티브 메모리(native memory)를 그냥 사용하지 않나요? Claude Code, Codex, Cursor, Windsurf는 각자의 메모리와 규칙을 추가하고 있습니다. 그것들은 유용하지만, 특정 도구나 워크스페이스(workspace)에 국한됩니다. piia-engram은 이들 위에 하나의 휴대 가능한 정체성 레이어를 제공합니다. 즉, 당신이 소유한 로컬 파일, 당신이 검토하는 AI 제안 지식, 그리고 도구 간에 당신을 따라다닐 수 있는 컨텍스트입니다.

네 줄로 요약한 신뢰 모델(Trust model):

클라우드 계정 불필요: pip로 설치하여 핵심 저장소를 당신의 머신에 유지하세요.
로컬 파일: 정체성과 지식은 ~/.engram/ 아래에 JSON/Markdown 형식으로 저장됩니다.
사용자 승인: AI는 로컬에 기록합니다. 고위험 항목(자격 증명, 셸 명령, MCP 설정, 권한 규칙)은 당신의 검토를 기다리며, 저/중위험 기록은 자동으로 흡수되지만 완전히 감사 가능하고 되돌릴 수 있습니다. 모든 기록을 제한하려면 ENGRAM_APPROVAL=strict를 설정하세요.
문서화된 경계: 신뢰 모델(Trust model), 개인정보 보호(Privacy), 보안(Security)을 확인하세요.

증거를 원하시나요? Claude Code가 작성하고 Codex가 하나의 로컬 저장소를 통해 다시 읽어들이는 실시간 도구 간 연속성 증명 또는 한 번의 명령으로 재현 가능한 코드 데모를 확인해 보세요.

당신 → "이 인증 모듈을 리팩터링하는 것을 도와줘"
# piia-engram이 없는 경우: AI가 처음부터 시작함
AI → "어떤 언어인가요? 어떤 프레임워크인가요? 테스트 선호도는 무엇인가요?"
...

pip install piia-engram && engram setup

위저드(wizard)는 Claude Code, Cursor, Codex, Claude Desktop와 같은 사용자의 AI 도구들을 자동으로 감지하며, 수정할 정확한 설정 파일 목록을 나열합니다. 이후 단 한 번의 키 입력 확인을 거쳐 MCP 연결을 작성합니다(모든 쓰기 작업은 사전에 백업되며, 거부할 경우 아무것도 변경되지 않습니다). 위저드는 사용자의 아이덴티티 카드(identity card)를 미리 보여준 뒤, 설정된 도구를 재시작하도록 안내합니다. 첫 번째 대화에서는 시작 도구(startup tools) 또는 검색 도구(search tools)를 통해 승인된 컨텍스트(context)를 로드할 수 있습니다. (전체 가이드 ↓)

증거 수준(Evidence levels)은 에이전트 클라이언트 검증 런북(agent client validation runbook)을 따릅니다: L0 = 테스트되지 않음, L1 = 설치됨, L2 = 읽기/검색 관찰됨, L3 = 정적 파일 브리지(static file bridge), L4 = 클라이언트 간 연속성(cross-client continuity).

도구	통합 방식	증거 상태
Claude Code	stdio를 통한 MCP	L4 부분적 연속성 증명 (Claude Code -> Codex)
...
이것은 piia-engram 자체에 대한 사실적 주장이며, 마이너 릴리스마다 갱신됩니다.

v3.56.0 (2026-06-11)
지원되는 AI 도구	16개 (증거 수준은 클라이언트마다 다름; 지원되는 도구 및 검증 런북 참조)
...	core.py의 라인 수
1573 (파사드(facade); 도메인 로직은 이제 집중된 믹스인(mixins)에 존재함 — architecture.md 참조)
PBKDF2 반복 횟수	600,000 (OWASP 2023+ 하한선; 레거시 100k로도 여전히 복호화 가능)
암호화	지원되는 프로필 필드에 대해 선택적인 필드 수준 AES-256-GCM 제공; 로컬 파일은 기본적으로 평문 JSON/Markdown 형식
콜드 스타트(Cold-start) 시간	통상 < 100 ms (로컬 JSON 사용, 네트워크 미사용)
기본 네트워크 호출	아이덴티티 및 지식 도구에 대해 0회 — 선택적인 read_web_content 제외; 원격 텔레메트리(telemetry) 및 피드백은 별도의 명시적 옵트인(opt-in)이 필요하며 전송 횟수만 기록됨 (개인정보 보호 세부 정보 참조)

도구를 전환하거나 새로운 채팅을 시작할 때마다 당신의 AI는 당신을 잊어버립니다. piia-engram은 이 인계(handoff) 문제를 해결합니다.

새 채팅 창을 열 때마다, Claude Code에서 Codex로 전환할 때마다, AI 도구를 업데이트할 때마다, 혹은 다른 프로젝트로 이동할 때마다 당신은 다시 제로(zero) 상태로 돌아갑니다:

• 당신의 커뮤니케이션 선호도 (communication preferences) — 사라짐
• 당신의 코드 표준 및 품질 기준 (code standards and quality bar) — 잊혀짐
• 이미 학습한 실수들 — 분실됨
• 지난달에 왜 그런 아키텍처 결정 (architecture decision)을 내렸는지 — 삭제됨

이런 일이 발생하는 이유는 오늘날의 AI 메모리가 각 플랫폼 내부에 갇혀 있기 때문입니다. 그것은 당신의 것이 아니라 도구의 것입니다. 도구가 업데이트되거나, 초기화되거나, 교체되면 당신의 컨텍스트 (context)도 함께 사라집니다.

piia-engram은 어떤 AI 도구와도 독립적으로, 당신의 머신(machine)에서 살아가는 개인용 정체성 레이어 (personal identity layer)를 제공합니다. 당신은 당신이 누구인지, 어떻게 일하는지, 무엇을 배웠는지를 단 한 번만 알려주면 됩니다. MCP 호환 도구들은 동일한 승인된 컨텍스트를 읽을 수 있습니다. 새로운 채팅, 새로운 도구, 새로운 버전이 나타나도 당신의 정체성은 휴대 가능 (portable)하게 유지됩니다.

piia-engram은 에이전트 메모리 데이터베이스 (agent memory database)가 아닙니다. Mem0, Zep, Letta와 같은 도구들은 AI 에이전트를 위한 작업 컨텍스트 (task context)와 세션 히스토리 (session history)를 저장합니다. piia-engram은 한 개인으로서의 당신, 즉 당신의 정체성, 선호도, 어렵게 얻은 교훈, 그리고 주요 결정 사항들을 저장합니다. 이는 다른 레이어입니다. 작업에서 무엇이 일어났느냐가 아니라, 모든 작업 뒤에 누가 있느냐를 다룹니다.

piia-engram이 없는 경우	piia-engram이 있는 경우
새로운 채팅창 = 제로(zero) 상태에서 시작	설정된 대화가 당신의 승인된 컨텍스트를 불러올 수 있음
...

piia-engram은 여러 AI 코딩 도구를 사용하며 매번 자신을 다시 설명하는 것에 지친 개발자들을 위해 구축되었습니다.

만약 Claude Code, Codex, Cursor 사이를 전환한다면 — 당신의 코드 표준, 아키텍처 결정, 그리고 어렵게 얻은 교훈들은 매번 초기화됩니다. piia-engram은 모든 도구가 당신이 누구인지에 대한 동일한 이해로부터 시작할 수 있게 합니다.

만약 일주일에 10개 이상의 AI 채팅창을 연다면 — 각각의 창은 제로(zero) 상태에서 시작합니다. piia-engram은 각 대화가 동일하게 승인된 정체성과 지식 컨텍스트에서 시작할 수 있도록 합니다.

만약 도구 업데이트 후 선호도를 잃어버렸다면 — 당신의 정체성은 특정 플랫폼 내부가 아니라 당신의 머신에 살아있습니다. 업데이트, 초기화, 마이그레이션 (migration)은 당신의 메모리에 영향을 주지 않습니다.

기타 사용 사례 (Other use cases)

투자 분석가 (Investment analysts)
의사결정은 내려지지만 그 추론 과정은 사라집니다. piia-engram은 전체 추론 체인 (reasoning chain)을 저장하므로, 6개월 뒤에 "왜 그 건을 거절했었지?"라는 질문에 실질적인 답변을 제공하며, 당신의 분석 프레임워크 (analytical framework)가 모든 새로운 분석 과정에서도 함께 이동합니다.

시스템 아키텍트 (System architects)
아키텍처 결정에는 맥락 (context)이 필요합니다. 무엇을 선택했고, 무엇을 배제했으며, 그 이유는 무엇인지 말이죠. piia-engram은 당신이 회사나 프로젝트를 옮기더라도 함께 따라다니며, 어떤 AI 도구로도 쿼리 (query) 가능한 살아있는 아키텍처 결정 기록 (Architecture Decision Records)을 유지합니다.

백엔드 개발자 (Backend developers)
API의 특이점, 통합 시의 주의사항 (integration gotchas), 성능 트레이드오프 (performance trade-offs) 등은 보통 머릿속에만 존재하는 암묵지 (tacit knowledge)이며 이직할 때 초기화됩니다. piia-engram은 이를 모든 환경에서 지속되는 검색 가능한 라이브러리로 변환합니다.

프론트엔드 및 디자인 (Frontend and design)
디자인 철학은 AI 도구가 사용할 수 있는 방식으로 문서화되는 경우가 드뭅니다. piia-engram은 당신의 실제 표준, 실제 사용자로부터 얻은 UX 교훈, 그리고 컴포넌트 결정 뒤에 숨겨진 추론을 저장합니다. 따라서 모든 프로젝트는 이전 프로젝트가 끝난 지점에서 다시 시작할 수 있습니다.

바이브 코더 (Vibe coders)
당신은 AI와 함께 구축하며 빠르게 움직입니다. 문제는 AI가 새로운 세션을 시작할 때마다 매번 처음부터 시작한다는 점입니다. 스타일 선택이 달라지고, 패턴이 일관되지 않으며, 동일한 선호도를 반복해서 설명해야 합니다. piia-enggan은 첫 세션부터 모든 도구가 일관되게 작동하도록 만듭니다. 당신의 스택, 패턴, 목소리가 이미 준비되어 있습니다.

모든 데이터는 ~/.engram/ 아래에 저장됩니다.

당신이 직접 열고, 편집하고, 백업하거나 마이그레이션 (migration)할 수 있는 일반 JSON 및 마크다운 (Markdown) 파일 형식입니다.

정체성 (Identity): 당신이 누구인지, 어떻게 소통하는지, 어떤 언어를 선호하는지
품질 표준 (Quality standards): 코드 리뷰 기준, 테스트 커버리지(test coverage) 기대치, 배포를 거부하는 사항
선호도 (Preferences): 코딩 스타일, AI 행동 방식, 선호하는 설명 방식
신뢰 경계 (Trust boundaries): 어떤 필드를 비공개로 유지할지, 어떤 도구에 접근 권한을 줄지
프로젝트 스냅샷 (Project snapshots): 진행 중인 작업에 대한 컨텍스트, 캡처 및 재로드 가능
학습된 교훈 (Lessons learned): 실수, 놀라운 점, 효과가 있었던 것과 없었던 것
주요 결정 사항 (Key decisions): 무엇을 선택했고, 무엇을 제외했으며, 그 이유는 무엇인지
도메인 지식 (Domain knowledge): 프로젝트와 도구 전반에 걸쳐 재사용 가능한 통찰력

대부분의 메모리 도구는 수동적입니다. 즉, 무언가를 넣으면 그것을 다시 돌려줄 뿐입니다. piia-engram은 능동적입니다.

프로젝트 간 지식 상속 (Knowledge inheritance across projects)

평문(plain text)으로 새로운 프로젝트를 설명하세요. get_knowledge_inheritance는

당신이 지금까지 작업했던 모든 것 중에서 가장 관련성이 높은 교훈과 결정 사항들을 선별하여 스타터 팩(starter pack)으로 반환합니다. 당신의 열 번째 프로젝트는 이전 아홉 개의 프로젝트로부터 얻은 이점을 단 한 번의 도구 호출(tool call)만으로 누릴 수 있습니다.

수동적 지식 캡처 (Passive knowledge capture)

세션 요약본을 extract_session_insights에 붙여넣으면

piia-engram이 교훈과 결정 사항을 추출하여 저장합니다. 수동으로 노트를 작성할 필요가 없습니다. 지식은 일반적인 AI 대화를 통해 축적됩니다.

MCP를 지원하지 않는 도구와도 작동 (Works with tools that do not support MCP)

ChatGPT, Gemini, Kimi — get_identity_card는

바로 붙여넣을 수 있는 마크다운 (Markdown) 형식의 정체성 카드(identity card)를 내보냅니다. 당신의 컨텍스트는 직접 연결할 수 없는 도구로도 전달됩니다.

자동 플레이북 추출 (Automatic playbook extraction)

PyPI 출시, Cloudflare 배포, MCP Registry 게시와 같은 다단계 워크플로(workflow)를 완료하면 piia-engram이 세션 종료 시 이를 감지합니다. 시스템은 구조화된 초안 플레이북(단계, 함정, 트리거 키워드)을 생성하여 스테이징 영역(staging area)에 저장합니다. 다음에 동일한 작업을 수행할 때, AI는 확인된 플레이북을 수동적 참조 자료로 검색하여 단계별로 안내하고 결과를 기록할 수 있습니다. 수동 기록은 필요하지 않습니다. Engram이 초안을 작성하면, 당신이 확인하고, 호스트 AI가 책임을 집니다. 아래의 '플레이북 자동 추출' 섹션을 참조하세요.

로컬 도구 레지스트리 (Local tools registry)

AI 도구들은 로컬 프로그램, 런타임, 그리고 CLI (Command Line Interface)를 끊임없이 검색합니다. register_tool은 무엇이 어디에 설치되어 있는지 기록하며, find_tool은 이를 즉시 검색합니다. 매 세션마다 which python을 입력할 필요가 없습니다. 환경 지도 (environment map)가 도구와 대화 전반에 걸쳐 유지됩니다.

지식 상태 및 탐색 (Knowledge health and discovery)

get_knowledge_overview는 오래된 레슨 (30일 이상 검토되지 않은 항목)을 드러내고, 네 가지 차원(신선도, 품질, 범위, 청결도)에 걸쳐 0~100 사이의 상태 점수를 계산하며, 재검토할 가치가 있는 공백을 표시합니다. suggest_merges는 전체 지식 베이스를 스캔하여 유사한 중복 항목을 찾아내고 실행 가능한 병합 명령을 반환합니다. link_knowledge는 관련된 레슨과 결정 사항들을 탐색 가능한 지식 그래프 (knowledge graph)로 연결합니다.

하이브리드 검색 (Hybrid search) (선택 사항, 기본값은 꺼짐)

기본 키워드 검색은 변경되지 않습니다. 교차 언어 검색(예: 영어 쿼리로 중국어 노트 찾기)을 위해 FTS5 전문 검색 (full-text search)과 시맨틱 벡터 레이어 (semantic vector layer)가 결합된 하이브리드 검색 (hybrid retrieval)을 선택하여 사용할 수 있습니다: pip install "piia-engram[vector]"를 실행하고 ENGRAM_SEARCH=hybrid를 설정하거나, engram setup을 통해 키 입력 한 번으로 활성화할 수 있습니다. 인덱스는 재구축 가능한 SQLite 파일이며, 당신의 JSON 저장소는 단일 진실 공급원 (single source of truth)으로 유지됩니다. docs/hybrid-search.md를 참조하세요.

pip install piia-engram
engram setup

piia-engram이 처음이신가요? 기본 17개 핵심 도구만을 사용하여 설치 -> 첫 메모리 -> 새로운 세션에서의 회상 경로를 안내하는 더 상세한 '첫 가치 퀵스타트 (first-value quickstart)'를 확인하거나, 설치 -> 첫 가치 -> 도구 간 연속성 -> 거버넌스 -> 개인정보 보호 -> FAQ를 다루는 전체 '사용자 가이드 (User Guide)'를 참조하세요. Claude Code, Codex, Cursor를 위한 호스트별 설정 카드가 준비되어 있습니다. 제안 전용 안전 컨텍스트 (proposal-only safe-context), 재생 (replay), 신선도/충돌 (freshness/conflict), 그리고 증거 초안 (evidence drafts)에 대해서는 '컨텍스트 거버넌스 (Context governance)'를 참조하세요.

설정 마법사는 다음을 수행합니다:

• 당신의 Python 환경을 감지합니다.
• Engram 데이터 폴더를 선택할 수 있게 합니다 (~/.engram

, 다른 드라이브, 또는 사용자 정의 경로) - 당신의 AI 도구들을 감지하고, 수정될 정확한 설정 파일(config files) 목록을 나열하며, 한 번의 키 입력 확인 후 MCP 연결을 작성합니다 (먼저 백업을 수행하며, 거절 시 파일은 수정되지 않은 상태로 유지됩니다)

• 시드 지식(seed knowledge, 역할, 기술 스택, 언어) 설정을 안내합니다
• 기존의 CLAUDE.md 또는 .cursorrules 파일로부터 스마트 임포트(Smart-import) 규칙을 가져옵니다 - 고급 모드(engram setup --advanced)에서는 선택 가능한 개인정보 보호 설정(도구 간 동기화, 익명 통계)을 보여줍니다. 당신의 AI 아이덴티티 카드(AI identity card)를 미리 보기 하세요— 즉각적인 가치를 증명합니다.

설정 후에는 MCP 연결을 작성하며(먼저 프롬프트에서 확인을 거칩니다), AI 도구를 재시작하세요. 많은 클라이언트가 시작 시 get_user_context를 호출할 수 있습니다. 호스트가 이를 선제적으로 수행하지 않는 경우, 명시적인 search_knowledge 또는 get_resume_brief 호출이 기대되는 L2 경로입니다.

비대화형(non-interactive) 또는 CI 실행의 경우, 확인 프롬프트를 건너뛰고 직접 작성합니다:

engram setup --apply-external-config

어떤 방식이든, 모든 외부 설정 작성은 선택된 Engram 데이터 폴더 아래에 백업되며, 프롬프트를 거절하면 모든 외부 설정은 수정되지 않은 상태로 유지됩니다.

언제든지 상태를 확인하세요:

engram status # 익명화된 설치 및 메모리 상태 요약
engram status --html # 로컬 익명화 상태 페이지 작성
engram continuity # 도구 간 핸드오프(handoff) 준비 상태를 보여주는 메타데이터 전용 증명
...

engram continuity