지식 베이스 가이드

사용자 목표

개인 또는 팀 워크스페이스에서 구조화된 지식 베이스를 유지 관리하고, 마크다운 및 형식화된 문서를 수집하며, 검증된 변경 불가능한 리비전을 게시하고, 자율 에이전트가 출처 귀속과 함께 인용된 사실을 검색하도록 구성합니다.

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

계정에 Knowledge가 활성화된 경우 웹 콘솔의 https://xmemo.dev/me#knowledge (개인 워크스페이스) 또는 https://xmemo.dev/me?space=<team_id>#knowledge (팀 워크스페이스)에서 지식 베이스 작성 및 검사를 사용할 수 있습니다. 시작하기 전에 다음 사전 요구 사항을 확인하십시오:

• 인증 요구 사항: 활성 사용자 세션이 필요합니다. 인증되지 않은 방문은 /login (로그인 페이지)으로 리디렉션됩니다.
• 토큰 범위: 프로그래밍 방식 액세스에는 검색 및 주소 지정 읽기를 위한 knowledge:read와 항목 생성 또는 편집을 위한 knowledge:write가 필요합니다.
• 지원되는 파일 형식: 브라우저 내 텍스트/코드 리더는 .md, .markdown, .txt, .json, .csv, .py, .js, .ts, .tsx, .html, .yaml, .yml 및 .toml을 지원합니다. 문서 추출은 .pdf, .docx, .pptx 및 .xlsx를 지원합니다.
• 드래그 앤 드롭 인터페이스: 콘솔에 "Drag & drop files here"와 보조 텍스트인 "Supports PDF, Word, PowerPoint, Excel, Markdown, and text files (.pdf, .docx, .pptx, .xlsx, .md, .txt, .csv, .json, etc.)"가 표시됩니다.

1. 웹 콘솔에서 지식 베이스 생성

브라우저에서 https://xmemo.dev/me#knowledge로 이동합니다. "Create Knowledge Base"를 클릭하여 생성 대화 상자를 엽니다. Name에 "Engineering Runbooks"를 입력하고 Description에 "Operational runbooks and deployment procedures."를 입력합니다. 생성을 확인하여 활성 베이스를 초기화합니다.

# Access personal knowledge workspace
https://xmemo.dev/me#knowledge

# Access team knowledge workspace with explicit space parameter
https://xmemo.dev/me?space=<team_id>#knowledge

2. 합성 지식 항목 추가 및 게시

새로 생성된 "Engineering Runbooks" 베이스를 열고 "Create Knowledge item"을 클릭하여 마크다운 또는 로컬 파일에서 항목을 생성합니다. Title에 "Deployment Guidelines"를 입력하고 초기 합성 지침을 붙여넣습니다. 항목은 "draft" 상태로 초기화됩니다:

## Deployment Guidelines

Production deployments require two peer approvals, clean migration dry-runs, and verified canary health.

3. 에이전트 검색을 위한 초안 항목 게시

"draft" 상태인 동안 해당 항목은 인간 편집자만 볼 수 있는 비공개 상태로 유지됩니다. 에이전트가 검색할 수 있도록 하려면 "Publish"를 클릭합니다. 콘솔에 "Published content becomes eligible for authorized Knowledge search."라는 안내가 표시됩니다. 확인되면 항목이 "published" 상태로 전환되어 리비전 1이 현재 검색 가능한 리비전으로 설정됩니다.

• 초안 비공개 보호: 초안 항목은 에이전트 발견 및 쿼리 검색에서 제외됩니다.
• 게시 작업: 게시하면 항목 상태가 "published"로 업데이트되고 current_revision_id가 리비전 1로 설정됩니다.
• 변경 불가능한 리비전: 리비전 1의 표준 콘텐츠, 해시 및 메타데이터는 변경 불가능하게 보존됩니다.

4. 에이전트 인용을 통한 지식 검색

search_knowledge를 제공하는 클라이언트 환경(예: cursor-plugin 또는 ordinary-full)의 승인된 에이전트는 게시된 런북을 쿼리할 수 있습니다. 도구는 명시적 인용 참조 포인터가 포함된 순위가 매겨진 발췌문을 반환합니다:

# Query knowledge via standalone Skill CLI
node scripts/xmemo-skill.mjs recall-context --query "production deployments" --include_knowledge true

5. 콘텐츠 업데이트 및 변경 불가능한 새 리비전 게시

기술적 절차가 변경되면 "Deployment Guidelines"를 열고 "Edit Knowledge item"을 클릭합니다. 새로운 운영 요구 사항을 반영하도록 콘텐츠를 업데이트합니다. "Save new revision"을 클릭합니다. 콘솔에 "Saving content creates an immutable new revision. Metadata changes do not create a revision."이 표시됩니다:

## Deployment Guidelines

Production deployments require two peer approvals, clean migration dry-runs, verified canary health, and automated smoke verification.

관찰 가능한 결과

웹 콘솔 및 에이전트 검색을 통해 게시된 항목과 해당 리비전 출처를 확인합니다:

• 콘솔 배지: 항목 카드에 "Published" 상태 배지가 표시되고 현재 활성 리비전을 가리킵니다.
• 리비전 계보: "Revision history"를 열면 타임스탬프 및 작성자 귀속 정보와 함께 리비전 2가 현재 버전으로, 리비전 1이 이전 버전으로 표시됩니다.
• 에이전트 검색 결과: 쿼리 검색은 리비전 2만 평가합니다. 이전 리비전 1은 정확한 knowledge_revision_id를 지정하는 주소 지정 읽기를 통해 계속 액세스할 수 있습니다.

에이전트가 액세스할 수 있는 범위

지식 베이스는 에이전트 통합에 대해 엄격한 액세스 및 가시성 경계를 적용합니다:

• 게시된 항목만 허용: 에이전트는 초안 항목에 액세스할 수 없습니다. 쿼리 검색은 활성 베이스의 게시된 항목만 평가합니다.
• 현재 리비전 경계: 쿼리 검색은 자동으로 current_revision_id로 확인됩니다. 대체된 이전 리비전은 쿼리 검색 결과에 나타날 수 없습니다.
• 프로필 가용성: 읽기 전용 MCP 도구 search_knowledge는 cursor-plugin 및 ordinary-full 클라이언트 프로필에서만 엄격하게 사용할 수 있습니다(config/mcp-documentation-contract.json). 다른 클라이언트 프로필은 recall_context를 사용하며, 활성화되고 승인된 경우 Knowledge가 자동으로 포함됩니다.
• 리콜 동작: MCP recall_context는 계정에 Knowledge가 활성화되어 있고 토큰에 knowledge:read가 포함된 경우 Knowledge를 자동으로 포함합니다. 모든 recall이 Knowledge를 검색하는 것은 아닙니다.

공유 및 스토리지 경계

지식 베이스는 엄격한 공간 격리 및 관리 역할 경계를 유지합니다:

• 개인 공간 대 팀 공간: 개인 베이스(/me#knowledge)는 해당 계정에 비공개입니다. 팀 베이스(?space=<team_id>#knowledge)는 팀 역할 액세스를 적용합니다(routes/knowledge.py:129-134).
• 역할 기능: Owner 및 Admin은 base:admin 및 item:write 권한을 보유합니다(베이스 및 항목 생성, 보관, 업데이트, 삭제). Member는 item:write 권한을 보유합니다(항목 생성, 편집 및 게시). Viewer는 읽기 전용 권한만 보유합니다.
• 보관 대 영구 삭제: 보관("Are you sure you want to archive knowledge base '<name>'? Archived bases will no longer be retrieved by agents.")은 손실 없이 검색을 일시 중단합니다. 영구 삭제("Are you sure you want to permanently delete knowledge base '<name>' and all its items? This action cannot be undone.")는 데이터를 물리적으로 제거합니다.
• 프로젝트 메모리 독립성: 지식 베이스는 프로젝트 작업/지식 메모리 파티션과 독립적으로 작동합니다. 프로젝트에서 메모리 연결을 해제해도 지식 베이스 문서에는 영향을 주지 않습니다.

장애 복구

다음 진단 단계를 사용하여 일반적인 지식 베이스 액세스 및 추출 문제를 해결하십시오:

• 문서 추출 진행 중: .pdf, .docx, .pptx 또는 .xlsx 문서를 업로드할 때 "Extraction is still in progress. Try again when it succeeds." 메시지가 표시되는 동안 기다리십시오.
• 문서 추출 실패: 처리가 실패하면 콘솔에 "Extraction failed. Retry the Document from its existing Document surface first."가 표시됩니다. 파일 무결성을 확인하거나 일반 마크다운 텍스트를 업로드하십시오.
• 에이전트 쿼리에서 항목이 반환되지 않음: 항목 상태가 "Published"("draft" 아님)인지, 베이스가 활성 상태(보관되지 않음)인지, 클라이언트 토큰에 knowledge:read 범위가 포함되어 있는지 확인하십시오.
• 동시 업데이트 충돌: 편집이 열려 있는 동안 다른 사용자나 에이전트가 항목을 업데이트한 경우 콘솔에 "This Knowledge item changed elsewhere. Refresh it and try again."이 표시됩니다. 페이지를 새로고침하고 변경 사항을 다시 적용하십시오.
• 검색 모드 선택: 하이브리드 검색에서 정확한 런북 기호나 구성 키를 찾지 못하는 경우 정확한 토큰 일치를 위해 렉시컬 모드(mode="lexical")로 전환하십시오.

관련 참조

지식 베이스 개념, 관련 도구 및 워크스페이스 관리에 대해 계속 살펴보십시오:

• 개념: 지식 베이스 (/docs/concepts/knowledge-bases) — 아키텍처 모델, 리비전 DAG 및 검색 모드.
• 도구: search_knowledge (/docs/tools/search-knowledge) — 주소 지정 읽기 및 검색 매개변수를 위한 도구 참조.
• 도구: recall_context (/docs/tools/recall-context) — 자동 Knowledge 검색 기능이 있는 컨텍스트 패킹 도구.
• 가이드: Memory Console (/docs/guides/memory-console) — 전체 웹 콘솔 탐색 가이드.
• 개념: 출처 및 귀속 (/docs/concepts/provenance-attribution) — 인용 봉투 및 작성자 귀속.