# 프로젝트 가이드

개인 프로젝트 워크스페이스를 생성하고, 메모리 연결을 관리하며, TODO 및 결정을 추적하고, 에이전트 컨텍스트 범위를 지정합니다.

- Canonical: https://docs.xmemo.dev/ko/docs/guides/projects
- Locale: ko-KR
- Content-Locale: ko-KR
- Canonical-Content-Digest: 7f95ace70e5137cfc69dccdd21827d3a6a830c65f25f2cff83b344d35824c8ef
- Edition-Digest: d77ac156d08eb04431475cd2266b85d69718bed1401f22915a1c7c88262fe574
- Source-Revision: sha256:192851794c728ed3868a5be3be886563c1566aa6aec82e2a9d21109e443f6368

## 사용자 목표

전용 프로젝트 워크스페이스를 설정하여 컨텍스트 메모리를 구성하고, 운영 결정 및 활성 작업을 추적하며, 연결된 에이전트에서 집중된 프로젝트 컨텍스트를 검색하고, 프로젝트 연결을 제거해도 핵심 개인 메모리가 손상되지 않고 유지되는지 확인합니다.

## 이용 가능성 및 사전 요구 사항

프로젝트 워크스페이스는 Memory Console(https://xmemo.dev/me#projects) 및 지원되는 MCP 클라이언트 프로필을 통해 모든 개인 계정에서 사용할 수 있습니다:

- 개인 경계: 프로젝트는 현재 엄격히 개인 전용입니다. team_id를 사용하여 프로젝트 생성을 시도하면 서버에서 거부됩니다(HTTP 400). 설명서에서는 팀 프로젝트 지원을 약속하지 않습니다.
- 한도 없는 할당량: 워크스페이스 생성은 숫자 플랜 할당량이나 인위적인 프로젝트 제한에 의해 제한되지 않습니다. 계정은 필요에 따라 워크스페이스를 프로비저닝합니다.
- 파티션된 뷰: "주의 필요"(Attention Needed) 뷰와 지식(Knowledge) 대 작업(Working) 메모리 파티션은 계정에서 활성화된 경우 작동합니다(수렴 평가 모드는 기본적으로 꺼져 있음).
- 에이전트 연결성: 연결된 에이전트는 config/mcp-documentation-contract.json에 계약된 클라이언트 프로필과 일치하는 프로젝트 도구에 액세스합니다.

## 1. Memory Console에서 프로젝트로 이동

개인 대시보드에 로그인하고 https://xmemo.dev/me#projects를 엽니다. 왼쪽 탐색 메뉴에서 Workspace 섹션을 선택하고 Projects를 클릭합니다. 패널 헤더에는 "Browse project workspaces, context, and project memories."라는 문구가 표시되며 Total Projects, Active, Attention Needed, Archived에 대한 최상위 메트릭이 표시됩니다.

```text
https://xmemo.dev/me#projects
Workspace -> Projects -> Total Projects (0) | Active (0) | Attention Needed (—) | Archived (0)
```

## 2. 새 개인 프로젝트 워크스페이스 프로비저닝

상단 작업 영역에서 Create New Project를 클릭하여 워크스페이스 모달을 엽니다:

- 프로젝트 이름: 설명적인 프로젝트 이름을 입력합니다(예: "Incident Response Automation"). 필드에는 "Required, 1-128 characters."가 표시되며 제어 문자 및 경로 구분 기호(/ 또는 \)에 대해 유효성을 검사합니다.
- 프로젝트 식별자 미리보기: 미리보기 식별자(#incident-response-automation)를 검토합니다. 도우미는 "Non-authoritative preview. The backend server assigns the authoritative project key."라고 확인합니다.
- 설명: 선택적으로 최대 2000자까지 범위 헌장을 입력합니다(예: "Operational runbooks, triage checklists, and automated incident response workflows.").
- 제출: Create Project를 클릭합니다. 서버가 표준 식별자를 할당하고 프로젝트 세부 정보 뷰를 엽니다.

## 3. 메모리, TODO 및 결정 연결

워크스페이스가 프로비저닝되면 범위가 지정된 컨텍스트, 보류 중인 작업 및 아키텍처 결정으로 워크스페이스를 채웁니다:

- 메모리 연결: 프로젝트로 범위가 지정된 합성 운영 런북 메모리를 작성합니다(scope: "incident-response-automation"): "Runbook policy: P0 production outages trigger immediate secondary on-call escalation after 15 minutes of unacknowledged alerts."
- TODO 기록: 프로젝트 세부 정보 뷰에서 또는 에이전트를 통해 작업을 추가합니다: "Draft post-incident review template for payment gateway timeouts."
- 결정 기록: 아키텍처 결정을 기록합니다: "Use PagerDuty webhook adapter for primary incident ingestion."
- 히어로 메트릭 검사: 히어로 표시줄에 라이브 집계가 반영됩니다: Memories: 1, Open TODOs: 1, Decisions: 1.

```ts
await client.remember(
  "Runbook policy: P0 production outages trigger immediate secondary on-call escalation after 15 minutes of unacknowledged alerts.",
  {
    path: "projects/incident-response-automation/runbooks/p0-escalation",
    scope: "incident-response-automation",
  },
);
```

## 4. 에이전트 컨텍스트 검색 검증

승인된 에이전트 클라이언트를 연결하여 프로젝트 검색 시 프로젝트 간 노이즈 없이 범위가 지정된 레코드가 반환되는지 확인합니다:

- Cursor 또는 Ordinary Full: 에이전트는 get_project_context(project_id="incident-response-automation")를 호출하여 활성 메모리, 보류 중인 TODO 및 기록된 결정을 검색합니다.
- ChatGPT 또는 Generic Public: 에이전트는 get_project_summary(project_id="incident-response-automation") 또는 open_project_workspace를 호출하여 요약 상태를 검사합니다.
- ChatGPT 채팅 내 위젯: open_project_workspace로 열리는 채팅 내 대화형 위젯은 대화 내에서 직접 인라인 작업 카드를 제공하며, 이는 https://xmemo.dev/me#projects의 전체 웹 Memory Console과 구별됩니다.

```json
{
  "project_id": "incident-response-automation",
  "status": "active",
  "memories_count": 1,
  "open_todos": 1,
  "decisions": 1,
  "summary": "Operational runbooks, triage checklists, and automated incident response workflows."
}
```

## 5. 메모리 연결 해제 및 비파괴적 제거 확인

프로젝트 메모리를 제거하면 기본 개인 메모리 레코드는 유지되면서 워크스페이스 연결만 해제되는지 확인합니다:

- 메모리 서랍 열기: 프로젝트 메모리 목록에서 운영 런북 항목을 선택하여 세부 정보 서랍을 표시합니다.
- 제거 시작: 서랍 작업에서 Remove from Project를 클릭합니다.
- 연결 해제 확인: 모달이 열리고 헤더에 "Remove from Project", 부제목에 "This memory will be disassociated from this project workspace."가 표시됩니다. 경고를 확인하십시오: "The memory content remains in your personal memory archive, but will no longer appear in this project context."
- 확인 실행: Remove를 클릭합니다. 프로젝트 메모리 수가 0으로 감소합니다.
- 전역 지속성 확인: 개인 메모리 아카이브(/me#memory)로 이동하여 런북 메모리가 손상되지 않고 검색 가능한 상태로 유지되는지 확인합니다.

## 관찰 가능한 결과

이 워크플로를 완료하면 워크스페이스에서 완전한 운영 격리가 입증됩니다:

- 워크스페이스 상태: 프로젝트는 표준 슬러그 #incident-response-automation과 함께 활성 프로젝트(Active) 아래에 나열됩니다.
- 컨텍스트 격리: 연결된 에이전트가 프로젝트 컨텍스트를 쿼리하고 관련 없는 프로젝트의 오염 없이 범위가 지정된 사실을 수신합니다.
- 데이터 안전성: 워크스페이스에서 메모리 레코드 연결을 해제하면 프로젝트 집계는 성공적으로 감소하지만 아카이브에 개인 메모리 레코드는 영구적으로 유지됩니다.

## 에이전트가 액세스할 수 있는 항목

에이전트 도구 가용성은 config/mcp-documentation-contract.json에 구성된 클라이언트 프로필에 엄격하게 종속됩니다:

- chatgpt-public, generic-public 및 public-only 프로필: project, get_project_summary 및 open_project_workspace를 노출합니다.
- claude-plugin 프로필: project 및 get_project_context를 노출합니다.
- cursor-plugin 및 ordinary-full 프로필: get_project_context, update_project_todo 및 update_project_decision을 노출합니다.
- 프로필 경계: 다른 클라이언트 프로필은 프로젝트 도구를 노출하지 않습니다. 계약되지 않은 도구를 호출하려고 하면 도구 검색 거부가 발생합니다.

## 공유 및 라이프사이클 경계

프로젝트 워크스페이스는 명시적인 운영 및 데이터 경계를 적용합니다:

- 개인 경계: 현재 모든 워크스페이스는 개인 전용입니다. 팀 워크스페이스는 지원되지 않으며 team_id를 제공하는 요청은 유효성 검사에 실패합니다.
- 라이프사이클 상태: 메모리 탐색기는 레코드를 Active, Superseded, Expired 및 Archived 상태로 분류합니다.
- 큐레이션 파티션: 계정에서 활성화된 경우 워크스페이스는 지식(Knowledge) 및 작업(Working) 메모리 파티션을 제공합니다. Knowledge 파티션은 지속성 규칙을 유지하고, Working 파티션은 일시적인 세션 상태를 저장합니다.
- 지식 베이스와의 차이점: 프로젝트 파티션은 대화형 에피소드 메모리를 분류합니다. 반면 지식 베이스는 다중 리비전 스냅샷을 통한 정식 버전 관리 문서 관리를 제공합니다. 선별된 문서는 /docs/concepts/knowledge-bases를 참조하십시오.
- 할당량 경계: 개인 프로젝트 워크스페이스에는 숫자 할당량이 없습니다.

## 오류 복구

일반적인 엣지 케이스 및 복구 조치:

- 중복 프로젝트 이름(HTTP 409): 서버는 "A project with this name or identifier already exists in your workspace." 메시지와 함께 중복 프로젝트 이름을 거부합니다. 다른 프로젝트 이름을 입력하십시오.
- 잘못된 프로젝트 이름(HTTP 400): 프로젝트 이름에는 슬래시(/ 또는 \)를 포함하거나 128자를 초과하거나 예약된 토큰(_project, ., ..)을 사용할 수 없습니다. 생성 대화 상자에서 이름을 수정하십시오.
- 클라이언트 프로필 도구 불일치: 에이전트가 get_project_context를 찾을 수 없는 경우 활성 클라이언트 프로필을 확인하십시오. chatgpt-public 프로필은 get_project_summary를 노출하는 반면 get_project_context는 cursor-plugin 및 ordinary-full에 노출됩니다.
- 버전 충돌(HTTP 409): 다른 세션에서 프로젝트나 메모리를 동시에 수정하는 경우 서랍에 Reload 버튼과 함께 "Modified elsewhere, please reload"가 표시됩니다. 상태를 새로 고치려면 Reload를 클릭하십시오.

## 관련 참조

보완적인 기능 및 기술 참조는 다음을 살펴보십시오:

- 프로젝트 개념 참조: /docs/concepts/projects의 아키텍처 세부 정보 및 범위 지정 규칙.
- Memory Console 가이드: /docs/guides/memory-console의 전체 웹 콘솔 안내.
- 지식 베이스 가이드: /docs/concepts/knowledge-bases의 선별된 참조 문서 관리.
- 프로젝트 REST API: /docs/api/projects의 인증된 프로그래밍 방식 엔드포인트.

## ChatGPT 사용자

채팅에 전달자 토큰을 붙여넣지 않고도 XMemo 기본 설정, 프로젝트 사실, 결정 및 TODO에 대한 지속 가능한 액세스를 ChatGPT에 부여하세요.

ChatGPT/OpenAI 앱 OAuth 흐름을 통해 호스팅된 XMemo MCP 서버를 연결한 다음 XMemo 계정에 대한 메모리:읽기 및 메모리:쓰기 권한을 승인합니다.

종합 기본 설정이나 프로젝트 노트를 저장하고 새 채팅을 시작한 다음 작업을 계속하기 전에 XMemo를 통해 ChatGPT에 이를 불러오도록 요청하세요.

OAuth가 실패하거나 도구가 표시되지 않으면 호스트 앱의 MCP 서버에서 로그아웃하고 XMemo 서버 URL을 다시 연결한 후 직접 토큰을 생성하기 전에 다시 시도하세요.

## 부조종사/Codex 개발자

IDE와 CLI 에이전트 간에 리포지토리 결정, 코딩 규칙, 버그 수정 메모, 작업 기록을 전달합니다.

가능한 경우 VS Code / GitHub Copilot 및 Gemini CLI에 OAuth를 사용하세요. Copilot CLI, Codex, Cursor 또는 기타 직접 MCP 클라이언트의 경우 로컬 환경 또는 보안 저장소에 XMEMO_KEY를 유지하고 안정적인 XMEMO_AGENT_INSTANCE_ID를 설정하세요.

코드베이스 결정이나 버그 수정을 기록한 후 편집하기 전에 다음 IDE 또는 CLI 에이전트에게 관련 XMemo 컨텍스트를 기억하도록 요청하세요.

회수가 비어 있는 경우 선택한 MCP 구성 경로, 직접 클라이언트용 XMEMO_KEY 환경 변수 및 호스트 앱의 오래된 OAuth 자격 증명을 확인하세요.

## 팀/엔터프라이즈 파일럿 소유자

계정 제어, 소스 속성, 내보내기/삭제 워크플로, 검토자에게 안전한 설정 증거를 통해 공유 메모리를 평가합니다.

보호된 XMemo 작업 공간을 생성하거나 입력하고 승인된 사용자를 초대한 다음 준비 배지에 따라 OAuth 또는 범위가 지정된 직접 자격 증명을 통해 각 클라이언트를 연결합니다.

파일럿 멤버에게 가상 팀 메모리를 저장하고 XMemo에서 소스 속성을 확인한 다음 삭제/내보내기 및 지원 경로를 검토하도록 합니다.

구성원이 연결할 수 없는 경우 새 토큰을 발급하기 전에 역할 권한, OAuth 승인, 클라이언트 준비 상태 및 지원 지침을 확인하세요.

## 자율 에이전트 운영자

헤드리스 또는 예약 에이전트가 진행 상황을 기록하고, 이전 결정을 검색하고, 안정적이고 비밀이 아닌 인스턴스 ID를 유지하도록 합니다.

/api/v1/mcp/config/autonomous-agent를 가져옵니다. 실행기가 OAuth + 사용자 정의 헤더를 지원하는 경우 auth_modes.oauth를 선호합니다. 완전 헤드리스 러너에 대해서만 비밀 저장소의 XMEMO_KEY와 함께 auth_modes.xmemo_key를 사용하십시오.

XMemo에 진행 상황을 기록하는 하나의 합성 작업을 실행하고 실행기를 다시 시작한 다음 동일한 XMEMO_AGENT_INSTANCE_ID를 사용하여 해당 진행 상황을 호출하는지 확인합니다.

속성이 변경되거나 인스턴스 간에 분할된 경우 git 외부에서 XMEMO_AGENT_INSTANCE_ID를 유지하고 실행기가 시작할 때마다 이를 다시 생성하지 않는지 확인하세요.