people-context
<!-- mcp-name: io.github.JinyangWang27/people-context -->
English | 简体中文
당신의 에이전트는 이미 당신의 코드베이스를 기억합니다. 이제는 사람까지 기억할 수 있습니다.
people-context는 로컬 우선(local-first) MCP 서버이자 CLI로, 당신의 삶 속 사람들에 대한 지속적인 기억을 AI 에이전트에게 제공합니다. 즉, 그 사람이 누구인지, 어떻게 알게 되었는지, 마지막으로 무엇에 동의했는지, 그리고 어떤 방식으로 대화하는 것을 선호하는지에 대한 정보입니다. 당신의 기기에 있는 단 하나의 SQLite 파일만 사용하며, 계정, 클라우드, 네트워크 호출이 필요 없습니다.
CI
codecov
OpenSSF Scorecard
OpenSSF Best Practices
PyPI
PyPI downloads
Python
License
HOL Guard
pctx demo: seed a fictional dataset, list people, and print a brief
왜 필요한가 (Why)
비서에게 '보고 지연에 대해 Priya에게 어떻게 접근해야 할까요?'라고 묻는다고 가정해 봅시다. 비서는 아무것도 모릅니다. 어떤 Priya인지, 그녀가 파트너 조직의 담당자라는 사실, 지난주에 새로운 마감일에 합의했다는 사실, 또는 그녀가 전화 통화보다 짧은 이메일을 선호한다는 사실 등 어느 것도 알지 못합니다.
이러한 지식은 당신의 머릿속, 받은 편지함, 그리고 에이전트가 볼 수 없는 메모 파일에 흩어져 있습니다. people-context는 이를 한곳에 보관하여 에이전트가 제한적인 도구를 통해 질의할 수 있게 합니다:
- 이것은 무엇인가요? 이름, 별명(nicknames), 예명(aliases), 핸들에 대한 설명 가능한 이름 해석(Explainable name resolution)을 제공합니다. 두 명의 Priya가 매칭 이유와 함께 두 개의 후보로 돌아오며, 절대 조용한 추측만 하지 않습니다.
- 저는 무엇을 아나요? 관계, 조직 및 역할, 지속적인 사실(durable facts), 간결한 상호작용 요약, 특성(traits), 알림(reminders), 그리고 개인별 타임라인을 알고 있습니다. 이 정보들은 요청이 필요한 범위까지만 공개됩니다.
- 그들과 어떻게 대화하나요? 기록된 특성, 과거의 마찰(friction), 열린 후속 조치(open follow-ups), 그리고 사용자의 자체 작성 철학에 기반한 커뮤니케이션 가이드를 제공합니다.
- 누가 연락이 끊겼나요? 이미 저장된 정보를 바탕으로 관계의 노후화(Stale-relationship) 및 다가오는 날짜에 대한 보고서를 제공합니다.
- 데이터를 안전하게 가져오기. 이메일, mbox, vCard, 캘린더, LinkedIn, Outlook, WhatsApp 내보내기 파일은 검토 가능한 후보로 준비됩니다. 사용자가 기록할 내용을 승인하며, 원본 소스 콘텐츠는 절대 보관되지 않습니다.
신뢰에 대해 명확한 입장을 취합니다: 작성 내용은 감사(audited)되며, forget 명령어는 실제 삭제를 수행하고, 민감한 기록은 프롬프트가 열 수 없는 운영자 전용 게이트 뒤에 위치하며, 일반적인 명령은 네트워크에 접근하지 않습니다.
데모
실제 데이터를 건드리지 않고도 신원 해석(identity resolution), 그래프 순회(graph traversal), 그리고 경계가 지정된 컨텍스트(bounded context)를 확인하는 가장 빠른 방법은 패키징된 가상의 데이터셋을 사용하는 것입니다:
uvx --from people-context pctx demo --reset
이 데모는 항상 {XDG_DATA_HOME or ~/.local/share}/people-context/demo.db에 전용 데이터베이스를 작성합니다. 이는 --db, PEOPLE_CONTEXT_DB, 설정 파일, 그리고 --reset을 무시하며, --reset은 해당 파일과 그 동반 파일인 -wal/-shm만 교체하므로 실제 데이터베이스는 읽거나 수정되지 않습니다. 시딩(Seeding) 과정에서 감사된 가상의 사람, 핸들, 소속, 사실, 상호작용 및 연결된 관계 그래프를 작성한 후, 방금 생성한 ID를 사용하는 경로 지정 서버 명령어와 구체적인 도구 호출을 출력합니다:
Demo database: /home/you/.local/share/people-context/demo.db
Start MCP server: people-context-mcp --db /home/you/.local/share/people-context/demo.db
resolve_person {"query": "Amina Hassan"}
...
Person id는 시드(seed)마다 생성되므로, 출력되는 값은 위의 플레이스홀더와 다릅니다. 출력된 서버 명령을 MCP 클라이언트에서 시작하고, 출력된 호출들을 있는 그대로 실행하세요. docs/cli.md를 참조하세요.
빠른 시작 (Quick start)
Python 3.11 이상 버전과 uv가 필요합니다. 사용하려는 클라이언트를 선택하세요. 각 단계는 독립적입니다.
<details open>
<summary><b>Claude Code</b></summary>
claude plugin marketplace add JinyangWang27/people-context
claude plugin install people-context@people-context-plugins
Claude Code를 재시작하거나 /reload-plugins를 실행하세요. 서버와 함께 /people-context:who, /people-context:remember, 그리고 /people-context:reminders가 사용 가능합니다. 자세한 내용은 docs/claude-code-plugin.md를 참조하세요.
</details>
<details>
<summary><b>Claude Desktop</b></summary>
최신 릴리스에서 people-context.mcpb를 다운로드하여 열어주세요. Claude Desktop은 자체 uv 런타임과 함께 고정된(pinned) 릴리스를 설치합니다. 자세한 내용은 docs/desktop-and-editors.md를 참조하세요.
</details>
<details>
<summary><b>Codex</b></summary>
codex plugin marketplace add JinyangWang27/people-context
codex plugin add people-context@people-context-plugins
새로운 Codex 세션을 시작하세요. 자세한 내용은 docs/codex-plugin.md를 참조하세요.
</details>
<details>
<summary><b>Cursor, Windsurf, VS Code 또는 모든 MCP 클라이언트</b></summary>
클라이언트의 MCP 설정에 stdio 서버를 추가하세요 (.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, .vscode/mcp.json, ...):
{
"mcpServers": {
"people-context": {
...
또는 CLI가 작성하도록 하세요: uvx --from people-context pctx setup cursor (마찬가지로 windsurf, vscode, claude-desktop 사용 가능; 미리 보기를 위해 --dry-run 추가). VS Code는 `
openclaw plugins install clawhub:openclaw-plugin-people-context
The native plugin talks to the opt-in loopback HTTP server. Details: docs/openclaw-plugin.md.
</details>
<details>
<summary><b id="CLI only">CLI 전용</b></summary>
uv tool install people-context
pctx init
pctx --help
people-context와 people-context-mcp는 서버 명령어이며, pctx가 사람이 조작하는 CLI입니다.
</details>
다음으로 에이전트에서 시도해 보세요:
Who is Amina?
Remember that Amina from Open City Lab prefers short emails and hates surprise calls.
What should I know before my meeting with Daniel tomorrow?
두 번째는 단일 remember 도구 호출입니다. 이름이 해결되고, 아무도 일치하지 않을 경우에만 사람이 생성되며, 소속 및 선호도가 하나의 감사 추적(audited) 트랜잭션으로 기록됩니다.
모호한 이름은 추측이 아닌 후보 목록으로 반환됩니다.
또는 에이전트 없이도 사용할 수 있습니다: pctx remember "Amina Hassan" "prefers short emails" --org "Open City Lab" 및 pctx brief "Amina Hassan". 다섯 가지 작동 시나리오는 docs/use-cases에 있습니다.
브라우저에서 검토 및 편집하기
터미널보다 테이블 형태를 선호하십니까? pctx browse --open은 동일한 데이터베이스 위에 로컬 페이지를 엽니다:
- 사람 검색: 이름, 별명(alias), 요약 검색 및 정렬 기능 제공 (이름별 또는 최신 추가/편집 순) 후 특정 조직이나 그룹으로 범위를 좁히고, 한 사람의 상세 정보 열람.
- 사람 이름 변경 (기존 이름은 별명(alias)으로 유지) 또는 요약 재작성.
- 사람의 별명 및 이메일 주소 추가, 수정 또는 제거.
- 소속(조직, 역할, 선택적 날짜), 사실 정보, 또는 상호작용 기록 추가.
- 소속, 사실, 상호작용, 특성(trait), 또는 알림을 제자리에 수정하며, 변경 전후 내용은 감사 로그(audit log)에 보존됨.
- 확인 절차 후 소속, 사실 또는 상호작용 영구 삭제.
- 스테이징된 가져오기 배치(staged import batch)를 사람별로 검토하고, 후보군을 편집한 후 철회하거나 커밋함.
이 기능은 127.0.0.1에만 바인딩하며, 모든 요청에는 URL에 해당 실행(per-launch) 토큰이 필요하고, 모든 쓰기 작업은 CLI 및 MCP 도구와 동일한 감사된 사용 사례를 거칩니다. 민감한 기록은 운영자가 활성화하지 않는 한 숨겨진 상태로 유지됩니다. 'Done'을 누르거나 Ctrl-C를 누를 때까지 실행됩니다. docs/cli.md 참조.
기억하는 것과 절대 하지 않는 것
| 기억하는 것 | 절대 하지 않는 것 |
|---|
| 이름, 별명(nicknames), 별칭(aliases), 핸들(handles) | 어디든 아무것도 업로드하지 않음 |
| ... | |
비교
| people-context | Assistant memory (ChatGPT, Claude) | Memory platforms (Mem0 및 유사 플랫폼) |
|---|
| 데이터 저장 위치 | 사용자가 소유한 SQLite 파일 하나 | 공급업체 계정(Vendor account) | 공급업체 플랫폼 또는 자체 배포 |
| ... | | | |
| 공급업체 문서 링크가 포함된 날짜 및 출처 버전은 docs/privacy-and-safety.md에 있습니다. | | | |
보안 모델
이 프로젝트는 실행하는 사용자의 파일 시스템 권한으로 로컬 Python을 실행합니다. 일반적인 MCP 검색은 높은 수준의 민감한 컨텍스트 및 전체 내보내기를 제외합니다. 운영자 게이트(Operator-gated) 도구는 프로세스 환경 플래그를 필요로 하며, 모델은 인수를 통해 이를 활성화할 수 없습니다. Vault 내보내기는 의도적으로 CLI 전용입니다.
데이터베이스는 기본적으로 평문(plaintext) SQLite를 사용합니다. 유닉스 계열 시스템에서는 새 데이터베이스가 0600 권한으로 생성되므로, 다른 로컬 계정에서 읽을 수 없습니다. 이는 암호화가 아니라 계정 간의 경계일 뿐이므로, 전체 디스크 암호화(Full-Disk Encryption)와 함께 사용하거나 저장 시점(at-rest) 암호화를 위해 SQLCipher를 선택할 수 있습니다 (uv sync --extra encrypted, 키는 PEOPLE_CONTEXT_DB_KEY에서만 읽기 가능). 데이터베이스 파일 권한 및 선택적 저장 시점 암호화를 참조하십시오.
더 나아가기 (Going further)
- Loopback HTTP: stdio(표준 입출력)를 생성할 수 없는 클라이언트를 위한 기능입니다:
people-context-mcp --http --host 127.0.0.1 --port 8765. 설계상 인증되지 않고 로컬 전용이므로, stdio 사용을 선호합니다. docs/cli.md를 참조하십시오.
- 의미론적 검색 (Semantic search):
uv sync --extra semantic && pctx reindex --semantic 명령은 고정된 다국어 Model2Vec 모델을 한 번 다운로드하며, 서버 시작 및 검색 과정에서는 캐시만 사용합니다.
- Obsidian:
pctx export-vault --output ~/PeopleVault는 결정론적이고 탐색 가능한 볼트(vault)를 작성하며, 읽기 전용 Obsidian 플러그인이 실시간 요약본을 렌더링합니다. docs/obsidian-plugin.md를 참조하십시오.
- 가져오기 (Import): 이메일, mbox, vCard, .ics, LinkedIn, Outlook, WhatsApp 내보내기를 통해
pctx import stage SOURCE PATH 명령으로 스테이징(stage)한 후 review 및 commit을 수행합니다. 에이전트도 동일하게 추출된 후보군을 스테이징할 수 있습니다. docs/import.md를 참조하십시오.
- 로컬 브라우저 (Local browser):
pctx browse --open은 사람들을 탐색하고, 이름을 변경하며, 요약본(summary)과 별칭(aliases)을 편집하고, 소속(affiliations), 사실(facts), 특성(traits), 알림(reminders)을 수정하며, 스테이징된 가져오기 배치(import batches)를 검토, 편집 및 커밋하기 위해 루프백 전용이며 토큰으로 보호되는 페이지를 제공합니다. 브라우저에서 검토 및 편집를 참조하십시오.
- 그룹 (Groups):
pctx group을 사용하여 클래스, 팀, 클럽, 가구(households) 등의 기록을 작성한 후, pctx group shared A B 명령으로 두 사람이 어떻게 서로 아는지 물어볼 수 있습니다. docs/shared-connections-examples.md를 참조하십시오.
- 보고서 및 유지보수:
pctx stale, pctx upcoming, pctx timeline, pctx doctor, pctx stats.
- 백업 및 두 번째 장치:
pctx sync push --output DIR와 pctx sync pull --input PATH.
- Docker:
docker run --rm -i -v people-context-data:/data ghcr.io/jinyangwang27/people-context:latest.
이는 샌드박스가 아닌 편의 이미지입니다. docs/docker.md를 참조하십시오.
- 데이터베이스 위치:
--db, 그리고 PEOPLE_CONTEXT_DB, 다음으로 XDG 설정 파일, 마지막으로 공유되는 ~/.pctx/people.db 순서로 지정됩니다. pctx db-path -v를 사용하여 검사할 수 있습니다.
전체 명령어 참조는 docs/cli.md에 있으며, MCP 도구 인벤토리 및 응답 계약은 docs/mcp-interface.md에 있습니다. 릴리스 간 안정적으로 유지되는 내용은 docs/compatibility.md를 확인하십시오.
