inkeep/open-knowledge 딥다이브
— AI-네이티브 로컬퍼스트 마크다운 에디터 + LLM 위키 엔진

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

2왜 주목받는가

Notion·Obsidian 대비 차별점과 트렌딩 이유.

2026년 중반, "AI 에이전트에게 어떻게 지식을 공급하고 협업할 것인가"라는 질문이 뜨겁다. OpenKnowledge는 이 질문에 에디터 레이어와 에이전트 레이어를 동일한 CRDT 문서로 묶는 방식으로 답한다.

3기술 스택 전체 지도

6개 패키지에 걸친 전체 기술 구성 상세.

프론트엔드 · 에디터 UI

에디터 엔진 · 실시간 협업

AI 통합 · MCP 서버

백엔드 · 저장소 · 인프라

4아키텍처 심화 분석

에디터 ↔ AI ↔ 위키가 연결되는 방식. ASCII 시스템 구조도.

핵심 설계 패턴 1 — CRDT 기반 에이전트-인간 동시 편집

OpenKnowledge의 가장 독창적인 설계는 에이전트 세션도 Hocuspocus WebSocket 클라이언트로 참여한다는 점이다. AgentSessionManager는 에이전트마다 고유 ID와 아이콘·색상을 부여하고, Yjs의 Awareness(인식) API를 통해 에이전트 커서 위치가 인간 화면에 실시간으로 나타난다.

핵심 설계 패턴 2 — 양방향 마크다운 직렬화

리치텍스트(ProseMirror/Tiptap 노드 트리) ↔ 마크다운 텍스트의 손실 없는 왕복 변환이 이 프로젝트의 기술적 난제다. packages/core/src/extensions/에는 표·각주·수학식·위키링크·JSX 컴포넌트 등 수십 개의 "fidelity 확장"이 있다. @handlewithcare/remark-prosemirror 패치 버전을 사용하고, remark/mdast 생태계를 적극 활용해 파싱한다.

핵심 설계 패턴 3 — 스킬 시스템 (에이전트 도구 모음)

ok init 명령을 실행하면 Claude Code·Cursor·Codex의 설정 디렉토리에 OpenKnowledge 스킬이 자동 설치된다. 스킬은 SKILL.md를 포함하는 ZIP 아카이브(.ok/skills/)로 관리되며, MCP 서버의 skills 도구로 설치·업데이트·삭제된다. 에이전트가 이 스킬을 호출하면 OpenKnowledge MCP 서버에 연결해 위키를 탐색한다.

핵심 설계 패턴 4 — 시맨틱 검색 (선택적 임베딩)

기본은 @orama/orama의 BM25 전문 검색이다. 사용자가 search.semantic.enabled: true와 OpenAI API 키를 설정하면 임베딩 벡터가 BM25 점수와 RRF(Reciprocal Rank Fusion)로 융합되어 키워드 없이도 의미적으로 관련된 문서를 찾는다. 문서는 8,000자 단위로 청킹(400자 오버랩)되어 최대 80개 청크로 색인된다.

5디렉토리 구조 해부

모노레포 6개 패키지의 역할과 핵심 파일.

6학습 포인트 (기술별)

이 레포를 통해 무엇을 배울 수 있는가.

① Tiptap v3 — 리치텍스트 에디터 커스터마이징

Tiptap은 ProseMirror 위에 편의 레이어를 얹은 에디터 프레임워크다. OpenKnowledge는 30개 이상의 커스텀 확장(Extension)을 구현하여 [[위키링크]], /슬래시 명령어, 수식 인라인, 테이블 컨트롤, 각주, MDX 컴포넌트 등을 지원한다. "어떻게 에디터에 도메인 특화 기능을 추가하는가"의 실전 교과서다.

② Yjs + CRDT — 충돌 없는 실시간 동시 편집

Yjs는 CRDT(Conflict-free Replicated Data Type) 라이브러리다. 여러 클라이언트(인간 + 에이전트)가 동시에 같은 문서를 수정해도 자동으로 합산하여 일관된 결과를 만든다. Git merge처럼 충돌이 생겨 수동 해소할 필요가 없다.

③ MCP(Model Context Protocol) 서버 구현

OpenKnowledge의 서버(packages/server/src/mcp/)는 20개 이상의 MCP 도구를 노출한다. search, write, edit, exec, skills, history, workflow 등 에이전트가 노트북 전체를 조작할 수 있는 API 세트다. Zod로 입출력 스키마를 정의하고, 세밀한 에러 메시지로 에이전트를 안내하는 방법을 볼 수 있다.

④ 마크다운 → ProseMirror 왕복 변환

remark/mdast(마크다운 AST) ↔ ProseMirror 노드 트리의 변환은 놀랍도록 복잡하다. 특히 MDX(JSX 컴포넌트), 수학식, 위키링크처럼 표준 마크다운을 벗어난 확장을 "손실 없이" 왕복시키는 코드(packages/core/src/markdown/)는 파서 엔지니어링의 실전 연습장이다.

⑤ 모노레포 구성 (Turborepo + Bun)

6개 패키지가 서로를 workspace:*로 참조하며, Turborepo가 의존 그래프를 분석해 변경된 패키지만 재빌드한다. 패키지 간 타입 공유, 공통 설정(biome.jsonc), 개발 DX를 어떻게 유지하는지 배울 수 있다.

⑥ Electron + Vite (electron-vite) 데스크톱 앱

packages/desktop/은 electron-vite로 구성된다. main/preload/renderer 세 프로세스 구조와 contextBridge 보안 패턴, auto-updater 연동, 네이티브 패키지(node-pty, @napi-rs/keyring) 통합 방법을 실제 코드로 배울 수 있다.

7시스템 요구사항 · 설치

직접 실행하기 위한 환경 조건과 명령어.

요구사항

빠른 시작 (CLI 방식, Linux/Windows/Intel Mac)

# 1. CLI 전역 설치
npm install -g @inkeep/open-knowledge

# 2. 노트 폴더로 이동 (없으면 새 폴더 생성)
mkdir my-wiki && cd my-wiki

# 3. 프로젝트 초기화 (Claude Code, Cursor, Codex MCP 설정 자동 생성)
ok init

# 4. 에디터 서버 시작 + 브라우저 자동 오픈
ok start --open

개발 환경 구성 (소스에서 빌드)

# Bun 설치
curl -fsSL https://bun.sh/install | bash

# 레포 클론 및 의존성 설치
git clone https://github.com/inkeep/open-knowledge.git
cd open-knowledge
bun install

# 앱 개발 서버 실행 (packages/app)
bun run --filter @inkeep/open-knowledge-app dev

# 전체 빌드 + 타입체크 + 테스트
bun run check

시맨틱 검색 활성화

# 프로젝트 루트의 .ok/config.local.yaml 생성
search:
  semantic:
    enabled: true
    apiKey: sk-...      # OpenAI API 키
    # model: text-embedding-3-small (기본값)
    # dimensions: 1536 (기본값)

8직접 해볼 수 있는 실습 과제

난이도별 3~5개 과제. 코드를 읽는 것을 넘어 직접 만들어본다.

9관련 기술 심화 학습 로드맵

이 레포를 완전히 이해하기 위한 주차별 학습 경로.

10핵심 키워드 사전

이 레포를 읽으면서 만나는 핵심 개념 정리.

11참고 링크

더 깊이 파고들기 위한 공식 자료와 관련 기술 문서.