Knowledge Bases

Base, Item 및 Revision 아키텍처

Knowledge Base는 owner-scoped 또는 team-scoped 참조 문서, 사양 및 런북의 모음입니다. 기술 지식을 세 가지 고유한 계층적 엔터티로 구성합니다.

• Knowledge Base: 최상위 컨테이너("Engineering Runbooks" 등). Base에는 이름, 설명, 상태(active 또는 archived) 및 공간 소유권(Personal 또는 Team)이 있습니다.
• Knowledge Item: Base 내의 개별 문서 또는 가이드라인("Deployment Guidelines" 등). Item에는 제목, 로케이터, 상태(draft, published 또는 archived), 소스 유형(user_created 또는 file) 및 current_revision_id 포인터가 있습니다.
• Knowledge Revision: 표준 콘텐츠, 리비전 번호, 콘텐츠 형식(markdown 등), 콘텐츠 해시, 소스 메타데이터 및 provenance를 포함하는 변경 불가능한(immutable) 스냅샷.
• 게시 수명 주기: Item은 draft 상태에서 시작합니다. 게시(published)되면 해당 current revision을 에이전트가 검색할 수 있습니다. 이후의 편집은 이전 리비전을 변경하지 않고 변경 불가능한 새 리비전을 생성하고 current 포인터를 이동합니다.

게시 경계 및 에이전트 가시성

Knowledge Base는 사람이 작성하는 작업과 자율 에이전트의 검색 사이에 엄격한 게시 경계를 적용합니다. 호출자는 query search와 addressed read 중에서 선택합니다. Query search는 현재 활성 리비전의 게시된 item만 평가하여 최신성을 보장합니다.

• 활성 Base만 해당: 보관된(archived) Base는 에이전트 검색 대상에서 제외됩니다. 보관은 콘텐츠를 파기하지 않고 포함된 모든 item의 검색을 중단합니다.
• 게시된 Item만 해당: 초안(draft) item은 명시적으로 게시될 때까지 작성자와 팀 편집자에게 비공개로 유지됩니다. 에이전트는 query search에서 초안 item을 검색하거나 인용할 수 없습니다.
• 기본적으로 Current 리비전 대상: Query search는 current_revision_id가 참조하는 리비전만 평가합니다. 대체된 이전 리비전은 query search 결과로 나타날 수 없습니다.
• 주소 지정 읽기(Addressed read): 주소 지정 읽기는 knowledge_item_id와 함께 knowledge_revision_id를 제공하여 정확한 이전 리비전을 검사할 수 있으므로 재현 가능한 인용을 유지합니다.

query search       -> active base + published item + current_revision_id
addressed (no pin) -> published item's current revision
addressed (pinned) -> exact immutable revision (e.g. knowledge:<item-id>@<revision-id>)

검색 모드: Hybrid, RRF, Semantic 및 Lexical

검색 런타임은 어휘적 정밀도와 의미론적 이해의 균형을 맞추기 위해 네 가지 검색 모드를 지원합니다.

• hybrid(기본값): 매개변수 alpha(기본값 0.5)를 사용한 정규화된 어휘 및 의미 점수의 선형 결합. 1에 가까운 alpha는 정확한 어휘 일치를 선호하고 0에 가까운 alpha는 개념적 의미 유사성을 선호합니다. 벡터 점수를 사용할 수 없는 경우 lexical로 폴백합니다.
• rrf(Reciprocal Rank Fusion): 순위 상수 k(기본값 60)를 사용하여 독립적인 어휘 및 의미 순위 목록을 융합하여 점수 보정 없이도 균형 잡힌 순서를 보장합니다.
• semantic: 임베딩 표현 기반의 벡터 유사도 순위 지정으로, 임베딩이 구성되지 않은 경우 어휘 매칭으로 폴백합니다.
• lexical: 정확한 기호, 함수 이름, 오류 코드 및 구성 키에 최적화된 정규화된 토큰 및 구문 매칭.

지원되는 파일 형식 및 업로드 파이프라인

Knowledge item은 markdown으로 직접 작성하거나 두 가지 고유한 수집 메커니즘을 통해 로컬 파일에서 가져올 수 있습니다.

• 브라우저에서 읽는 텍스트 및 코드 파일: 일반 텍스트 및 코드 파일(.md, .markdown, .txt, .json, .csv, .py, .js, .ts, .tsx, .html, .yaml, .yml, .toml)은 브라우저에서 직접 읽고 표준 markdown 콘텐츠로 저장됩니다.
• 문서 추출 파이프라인: 서식이 지정된 문서(.pdf, .docx, .pptx, .xlsx)는 Documents API를 통해 업로드되고 텍스트 추출 워커를 통해 처리되며 추출이 성공하면 Knowledge item으로 스냅샷이 생성됩니다.
• 파일 경계: 수집 경계는 클라이언트 및 서버 환경 전체에 적용됩니다. 안정적인 처리를 위해 지식을 모놀리식 파일 덤프가 아닌 집중되고 모듈화된 문서로 구성하세요.

에이전트 액세스 인터페이스 및 클라이언트 프로필

승인된 에이전트는 전용 MCP 도구 및 독립형 Skill 명령을 통해 Knowledge에 액세스합니다.

• MCP search_knowledge: knowledge:read 토큰 범위가 필요한 전용 읽기 전용 검색 도구입니다. 특히 cursor-plugin 및 ordinary-full 클라이언트 프로필(config/mcp-documentation-contract.json)에 노출되며 chatgpt-public 또는 generic-public 프로필에는 노출되지 않습니다.
• MCP recall_context: 계정에 Knowledge가 활성화되어 있고 토큰에 knowledge:read가 포함된 경우 에피소드 기억과 함께 관련 Knowledge item을 자동으로 포함합니다.
• 독립형 XMemo Skill: 명시적인 지식 포함을 통해 recall-context를 실행합니다: node scripts/xmemo-skill.mjs recall-context --query "api authentication" --include_knowledge true.
• 범위 적용: 모든 recall이 자동으로 Knowledge를 쿼리하는 것은 아닙니다. 검색은 구성되어 있고 토큰 범위에서 허용되며 활성 클라이언트 프로필에서 지원되는 경우에만 수행됩니다.
• REST 동반 엔드포인트: 인증된 동반 엔드포인트 POST /api/v1/knowledge/search는 백엔드 서비스 및 사용자 지정 도구에 지식 검색에 대한 직접적인 프로그래밍 방식 액세스를 제공합니다.

{
  "type": "knowledge_search",
  "results": [
    {
      "knowledge_item_id": "item_runbook_deploy",
      "knowledge_revision_id": "rev_v2_deploy_runbook",
      "title": "Production Deployment Runbook",
      "content": "Production deployments require two peer approvals, clean migration dry-runs, and verified canary health.",
      "reference": "knowledge:item_runbook_deploy@rev_v2_deploy_runbook",
      "score": 3.84
    }
  ]
}

팀 역할, 공간 및 수명 주기 작업

Knowledge Base는 역할 기반 액세스 제어를 통해 개인 및 공동 작업 워크스페이스를 지원합니다.

• 역할 기능: Owner 및 Admin은 base:admin 및 item:write 권한을 보유합니다(Base 및 Item 생성, 보관, 업데이트, 삭제). Member는 item:write 권한을 보유합니다(Item 생성, 편집 및 게시 가능, Base 삭제 또는 보관 불가). Viewer는 읽기 전용 권한만 보유합니다.
• 공간 경계: Personal 공간(/me#knowledge)은 소유자에게 비공개입니다. Team 공간(?space=<team_id>#knowledge)은 인증된 팀 구성원 간에 게시된 문서를 공유합니다.
• 보관 및 영구 삭제: Base를 보관하면 상태가 archived로 설정되어 전체 복원을 허용하면서 에이전트 쿼리에서 모든 item이 즉시 제외됩니다. 영구 삭제는 Base와 모든 관련 리비전을 물리적으로 되돌릴 수 없게 파기합니다.

프로젝트 메모리와의 차이점

Knowledge Base는 대화형 프로젝트 메모리와는 다른 보장 하에 작동하는 정선된 참조 문서를 제공합니다.

• Knowledge Base item: 다중 리비전 기록 및 정확한 인용 참조(knowledge:<item-id>@<revision-id>)를 갖춘 정선된 버전 관리 참조 문서(런북, 설계 문서, 코딩 표준 등).
• 프로젝트 Knowledge/Working 메모리: 프로젝트 워크스페이스 내에서 영구 컨텍스트(knowledge) 대 일시적 작업 상태(working 메모리)로 분류되는 대화형 메모리 레코드.
• 독립성: 프로젝트에서 메모리 레코드를 제거하거나 문서 연결을 해제해도 기본 Knowledge Base item이 수정, 보관 또는 삭제되지 않습니다.

가용성 및 런타임 활성화

Knowledge Base는 Preview가 아닌 핵심 기능으로 문서화되어 있습니다. 계정에 Knowledge가 활성화되어 있으면 가용성이 활성 상태입니다. 백엔드 지식 런타임이 구성되지 않았거나 비활성화된 경우 요청은 knowledge_runtime_disabled 코드와 함께 HTTP 503을 반환합니다. 카탈로그 플랜 지정(예: Plus 티어 할당)은 런타임 적용 메커니즘이 아닌 플랜 허용량을 나타냅니다. 플랜 티어를 적용하는 API 경로는 없습니다.