아키텍처 개요

KnowledgePulse는 이중 레이어 아키텍처 위에 구축된 AI 지식 공유 프로토콜입니다. 프로토콜 레이어는 지식의 구조, 탐색, 거버넌스 방식을 정의하고, 인프라 레이어는 프로토콜을 구현하는 구체적인 런타임 구성 요소를 제공합니다.

프로토콜 스택

프로토콜은 5개 레이어로 구성되며, 각 레이어는 아래 레이어 위에 구축됩니다:

┌─────────────────────────────────────────┐
│            5. 거버넌스                   │
│   라이선스, 기여 추적, 감사 추적         │
├─────────────────────────────────────────┤
│            4. 프라이버시                 │
│   범위 지정, 수정, GDPR 준수            │
├─────────────────────────────────────────┤
│            3. 탐색                      │
│   검색, 평가, 벡터 검색                 │
├─────────────────────────────────────────┤
│            2. KnowledgeUnit             │
│   JSON-LD 스키마, 유형, 버전 관리       │
├─────────────────────────────────────────┤
│            1. SKILL.md                  │
│   에이전트 기능 선언 형식               │
└─────────────────────────────────────────┘

레이어 1 -- SKILL.md는 에이전트가 기능, 입력, 출력, 제약 조건을 선언하는 표준 파일 형식을 정의합니다. 다른 레이어가 참조하는 기본 계약입니다.

레이어 2 -- KnowledgeUnit은 세 가지 지식 유형(추적, 패턴, SOP)에 대한 JSON-LD 스키마와 스키마 진화를 관리하는 버전 관리 규칙을 명시합니다.

레이어 3 -- 탐색은 지식 유닛이 인덱싱, 검색, 관련성 평가, 검색되는 방식을 다루며, 벡터 기반 유사성 검색을 포함합니다.

레이어 4 -- 프라이버시는 범위 지정 규칙, 필드 수준 수정, 데이터 내보내기 및 잊힐 권리 등 GDPR이 요구하는 작업을 처리합니다.

레이어 5 -- 거버넌스는 라이선스, 기여 추적 체인, 에이전트 간 지식 흐름을 추적하는 감사 추적을 다룹니다.

구성 요소 개요

네 가지 런타임 구성 요소가 프로토콜 스택을 구현합니다:

구성 요소	패키지	역할
SDK	@knowledgepulse/sdk	핵심 라이브러리 -- 타입, 캡처, 검색, 평가, SKILL.md 파싱, 마이그레이션
레지스트리	registry/	Hono REST API 서버 -- 지식 유닛 저장, 인증 처리, 속도 제한
MCP 서버	@knowledgepulse/mcp	Model Context Protocol 서버 -- 6개 MCP 도구 노출, 이중 모드 레지스트리 브릿지
CLI	@knowledgepulse/cli	명령줄 인터페이스 -- 검색, 설치, 검증, 기여, 인증, 보안

SDK

SDK (packages/sdk)는 다른 모든 구성 요소가 의존하는 핵심 라이브러리입니다. Zod 스키마에서 생성된 TypeScript 타입, 지식 유닛 캡처 및 검색 함수, 관련성 평가, SKILL.md 파싱 및 정제, 스키마 버전 업그레이드를 위한 체인 가능한 마이그레이션 함수를 제공합니다.

레지스트리

레지스트리 (registry/)는 지식 유닛의 중앙 저장소 역할을 하는 Hono 기반 REST API 서버입니다. Bearer 토큰을 통한 인증, 계층 기반 속도 제한을 처리하고 지식 유닛에 대한 CRUD 엔드포인트를 노출합니다.

MCP 서버

MCP 서버 (packages/mcp-server)는 Model Context Protocol을 통해 KnowledgePulse 기능을 노출하여 MCP 호환 AI 클라이언트에서 접근할 수 있게 합니다. 이중 모드로 작동합니다:

• 독립 실행 모드 -- 자체 인메모리 스토어로 실행됩니다.
• 프록시 모드 -- KP_REGISTRY_URL 환경 변수를 통해 원격 레지스트리로 브릿지합니다.

CLI

CLI (packages/cli)는 개발자와 에이전트가 프로토콜과 상호작용할 수 있는 명령줄 인터페이스를 제공합니다 -- 지식 검색, SKILL.md 파일 설치, 스키마 검증, 지식 유닛 기여, 인증 관리.

모노레포 구조

knowledgepulse/
├── packages/
│   ├── sdk/            # @knowledgepulse/sdk — 타입, 캡처, 검색, 평가, 마이그레이션
│   ├── mcp-server/     # @knowledgepulse/mcp — 6개 MCP 도구, 이중 모드 레지스트리 브릿지
│   ├── cli/            # @knowledgepulse/cli — 검색, 설치, 검증, 기여, 인증
│   └── sop-studio/     # 플레이스홀더 (Phase 3)
├── registry/           # Hono REST API 서버 (인메모리 스토어, 인증, 속도 제한)
├── specs/              # codegen.ts, validate-consistency.ts, skill-md-extension.md
├── examples/           # basic-sdk-usage, mcp-client-example, langraph-integration
└── website/            # Docusaurus 문서 사이트

스토리지 모델

Phase 1은 비동기 Promise<T> 인터페이스 뒤에 있는 인메모리 Map<> 스토어를 사용합니다. 이는 의도된 설계입니다: 비동기 인터페이스 경계는 소비자 코드 변경 없이 스토리지 백엔드를 영구 데이터베이스(PostgreSQL, SQLite 등)로 교체할 수 있음을 의미합니다. 벡터 캐시는 HNSW가 아닌 브루트포스 선형 스캔을 사용하며, 마찬가지로 인터페이스를 통해 교체 가능합니다.

기술 스택

기술	용도
Bun	JavaScript/TypeScript 런타임 및 패키지 매니저
Hono	레지스트리 및 MCP 서버용 경량 HTTP 프레임워크
Zod v3	스키마 정의 및 유효성 검사 (zod-to-json-schema로 코드 생성)
tsup	SDK 빌드 도구 (ESM + CJS + TypeScript 선언)
Biome	린터 및 포매터
@modelcontextprotocol/sdk	MCP 프로토콜 구현
bun test	테스트 러너 (15개 파일, 319개 테스트)