돌탑 위키 (Doltap Wiki)

AI 에이전트들이 함께 쌓고 함께 읽는 지식 베이스. 에이전트가 작업하며 배운 것을 위키에 남기고, 다음 에이전트가 그걸 읽고 시작합니다. 머신이 여러 대여도, 에이전트가 여러 종류여도 하나의 위키입니다.

English README · 에이전트용 설치 안내

이런 분께

• Claude Code 같은 코딩 에이전트를 여러 프로젝트, 여러 머신에서 쓰는데, 같은 배포 절차나 같은 라이브러리 함정을 매번 다시 설명하고 있다면

• 에이전트가 알아낸 것을 어딘가에 남기고 싶은데 메모가 흩어지거나 금방 낡는다면

• 그 지식을 사람도 읽고 고칠 수 있는 형태(Markdown, git, Obsidian)로 두고 싶다면

Related MCP server: cardloom-mcp

3분 시작

Node 22.13 이상과 git이 필요합니다.

npm install -g doltap-wiki
doltap init --new --dir ~/.doltap --remote git@github.com:<내계정>/<위키저장소>.git   # 첫 머신: 미리 만든 빈 비공개 저장소
doltap integrations install claude                                                 # Claude Code에 연결
doltap schedule install                                                            # 10분마다 자동 sync (launchd / crontab / 작업 스케줄러)

다른 머신에서는 둘째 줄을 doltap init --repo <위키저장소 주소>로 바꿔 같은 네 줄을 실행하면 됩니다. 명령어는 doltap이고, wiki로 치고 싶으면 셸 설정에 alias wiki=doltap을 넣으세요.

설치가 귀찮다면 에이전트에게 시키세요. Claude Code 같은 에이전트에게 이렇게 말하면 됩니다.

https://github.com/bluekds/doltap-wiki/blob/main/docs/SETUP-FOR-AGENTS.md 읽고 이 머신에 돌탑 위키 설치해 줘

에이전트가 설치부터 연결, 검증까지 하고 결과를 보고합니다. 저장소 주소와 git 이름·이메일만 물어볼 겁니다.

에이전트에게 이렇게 말하세요

연결이 끝나면 새 세션부터 에이전트가 위키를 압니다. 따로 명령을 외울 필요 없이 평소처럼 말하면 됩니다.

에이전트는 아무 말이나 쌓지 못합니다. 카테고리 분류표, 템플릿, lint, 중복 감지가 쓰기 단계에서 작동하고, 비밀값은 저장이 거부됩니다. 규칙 전체는 위키 안의 _meta/PROTOCOL.md에 있고 에이전트가 자동으로 읽습니다.

사람은 이렇게 봅니다

• Obsidian: ~/.doltap/wiki를 vault로 열면(저장소 루트가 아니라 wiki/) 링크, 백링크, 그래프, 대시보드(Dataview)가 그대로 동작합니다. 설정이 들어 있어 플러그인 두 개(Dataview, Obsidian Git)만 설치하면 됩니다.

• 터미널: doltap search 배포, doltap get howto/deploy-pypi

• 그냥 파일: wiki/ 아래 Markdown이라 GitHub에서 바로 읽힙니다

어떻게 동작하나

• 페이지는 wiki/ 아래 Markdown, 저장소는 평범한 git. 이력·동기화·충돌은 git이 맡습니다.

• 다섯 카테고리가 각각 하나의 질문에 답합니다: howto(어떻게 하나) · patterns(어떻게 구현하나) · reference(무엇인가) · decisions(왜 이걸 골랐나) · projects(이 프로젝트의 맥락)

• 모든 페이지에 confidence: draft | verified | deprecated가 있어 에이전트가 얼마나 믿을지 압니다. 다른 머신에서 따라 해 보고 성공하면 verified로 올립니다.

• 모든 쓰기는 pull → lint → commit → push를 자동으로 거칩니다. 충돌하면 상대 버전을 유지하고 내 버전을 <id>.conflict-<host>.md로 남깁니다. 오프라인이면 다음 sync에 push합니다.

• 검색은 Node 내장 SQLite의 전문 검색입니다. 임베딩도 벡터 DB도 없고, 서버가 모델을 호출하지도 않습니다. 판단은 에이전트가 하고, 돌탑은 저장·검색·검증·동기화만 합니다.

구조

flowchart LR
  subgraph A["Machine A (laptop)"]
    A1["Agent (Claude Code, ...)"] -->|"MCP stdio / CLI"| A2["doltap"]
    A2 --> A3[("wiki/ clone + SQLite index")]
    A4["Obsidian"] --- A3
  end
  subgraph B["Machine B (always-on)"]
    B1["Agent"] --> B2["doltap"]
    B2 --> B3[("wiki/ clone + index")]
    B4["doltap-mcp --http"] --> B3
  end
  A3 <-->|"git pull / push"| R[("git remote (private repo)")]
  B3 <-->|"git pull / push"| R
  C["claude.ai connector / Claude Code without a clone"] -->|"HTTPS, path token"| B4

쓰기 경로

모든 쓰기는 같은 경로를 지납니다. 중복이나 lint 오류는 commit 전에 거부되고, 충돌은 자동 병합하지 않습니다.

flowchart LR
  W["upsert / add"] --> P["pull --rebase"] --> D{"similar<br/>page?"}
  D -->|"no"| L["write + lint"] --> C["commit"] --> U["push"]
  D -->|"yes"| X["refused:<br/>edit that page"]
  L -->|"errors"| Y["refused:<br/>file restored"]
  P -->|"conflict"| K["keep upstream, save<br/>id.conflict-host.md"]
  U -->|"offline"| O["pushed on<br/>next sync"]

여러 머신, 원격 접속

• 머신마다 doltap init --repo …로 clone을 두면 같은 git 원격을 공유합니다. doltap schedule install이 10분마다 pull해서 읽기가 느린 네트워크에 막히지 않습니다.

• clone을 두기 싫은 머신(노트북, claude.ai 웹)은 원격 접속을 씁니다. 항상 켜 둔 머신에서 doltap serve install 후 Tailscale Funnel 같은 방법으로 HTTPS로 내면, 다른 머신은 doltap integrations install claude --remote <URL> 한 줄로 연결되고 claude.ai에는 커스텀 커넥터로 등록합니다. 보안 모델은 아래 "보안"을 보세요.

• 충돌은 자동 병합하지 않습니다. doltap sync와 doltap audit가 충돌 파일을 알려 주면 두 버전을 합치고 파일을 지우면 됩니다.

관리자 에이전트 (선택)

위키는 쌓이기만 하면 지저분해집니다. 에이전트 하나에게 관리자 역할을 맡기세요. doltap init --new가 만든 howto/maintain-doltap-wiki 페이지에 세션 시작·주간·월간 루틴이 있고, 항상 켜 둔 머신의 Claude Code 세션에 이렇게 말하면 됩니다.

howto/maintain-doltap-wiki 읽고 일일·주간 작업을 이 세션에 예약해 줘

세션이 정해진 시각에 점검·검토하고 보고합니다. 페이지 폐기·삭제·병합은 제안만 하고 승인을 받습니다. 예약은 세션이 열려 있는 동안만 유지됩니다.

doltap search <query> [-c category] [-t tag] [-n limit] [--json]
doltap get <id> [-s "Section"]
doltap list [-c category] [-t tag]
doltap related <id>
doltap index                              # 페이지당 한 줄
doltap template <category>
doltap add <category>/<slug> --title .. --summary .. --tags a,b [--file body.md | --stdin] [--force]
doltap patch <id> -s "Section" (--content .. | --file .. | --stdin) [--append]
doltap meta <id> [--confidence verified] [--add-source ..] [--add-tag ..]
doltap lint [ids...]
doltap sync                               # pull, 밀린 push, reindex, 읽기 통계 발행, 충돌 파일 목록
doltap reindex [--full]
doltap audit [--unreferenced-days 90] [--stale-days 90] [--draft-days 30]
doltap schedule install|status|uninstall  # 주기적 sync
doltap serve install|status|uninstall|token [--rotate]   # 상시 HTTP MCP 서비스
doltap integrations install|uninstall claude [--remote <url>] [--dry-run]

전역 옵션 --root, --agent, --session, --no-sync, --json. 환경변수 DOLTAP_ROOT, DOLTAP_AGENT, DOLTAP_SESSION, DOLTAP_NO_SYNC=1, DOLTAP_AUTO_PULL_MINUTES(기본 10).

doltap audit는 모든 머신의 읽기 통계(wiki/_meta/stats/<host>.json, sync가 6시간에 한 번 발행)를 합쳐서 아무도 읽지 않는 페이지, 오래된 페이지, 오래 머문 draft, 고아 페이지, 아직 링크되는 deprecated 페이지, 충돌 파일을 보고합니다.

MCP 도구

리소스: wiki://protocol, wiki://index, wiki://tags.

• 원격 접속을 보호하는 것은 경로에 들어가는 64자리 무작위 토큰 하나입니다. OAuth는 아직 없습니다. URL이 새면 위키 전체를 읽고 쓸 수 있으니 토큰은 doltap serve token으로만 확인하고 채팅이나 문서에 붙여 넣지 마세요. 새면 doltap serve token --rotate 후 서비스를 재시작합니다.

• 서비스는 기본으로 127.0.0.1에만 바인딩합니다. 인터넷에 내는 것은 Tailscale Funnel 같은 바깥 계층의 선택입니다.

• 위키 내용은 git 이력에 영구히 남고, 에이전트가 읽은 페이지는 그 에이전트의 모델 제공사로 전송됩니다. 비밀값을 적지 않는 이유입니다.

• 원격으로 쓴 commit은 서버 머신 이름으로 기록됩니다. 클라이언트별 기록은 아직 없습니다.

이것은 무엇이 아닌가

• 코드베이스 문서를 LLM이 자동 생성하는 도구가 아닙니다(그 용도는 OpenWiki 같은 프로젝트가 맞습니다). 돌탑은 에이전트가 작업 중에 직접 쓰는 운영 지식용입니다.

• 임베딩이나 벡터 DB를 쓰지 않습니다. 전문 검색과 링크 구조로 충분한 규모를 목표로 합니다.

• 서버가 모델을 호출하지 않습니다. 판단은 에이전트가 하고, 돌탑은 저장, 검색, 검증, 동기화만 합니다.

배지

돌탑 위키로 관리하는 위키나 프로젝트의 README에 아래를 붙이면 배지가 표시됩니다.

<a href="https://github.com/bluekds/doltap-wiki"><img src="https://raw.githubusercontent.com/bluekds/doltap-wiki/main/static/badge-seal.png" width="120" alt="Managed with Doltap Wiki"></a>

로고와 배지 원본은 static/에 있습니다(MIT).

개발

npm ci && npm run build && npm test
npm link -w doltap-wiki            # 이 체크아웃의 `doltap`, `doltap-mcp`를 전역으로

패키지: @bluekds/doltap-core(파서, lint, 검색, git 동기화, 스캐폴드), @bluekds/doltap-mcp(MCP 서버), doltap-wiki(CLI와 두 실행 파일 doltap, doltap-mcp). CI는 macOS, Linux, Windows에서 빌드와 테스트, 빈 위키 생성까지 확인합니다.

라이선스

MIT