kungfu-systems/kungfu 딥다이브
— 채팅이 끝나도 에이전트가 처음부터 다시 시작하지 않게 하는 작업 연속성 런타임

1프로젝트 한 줄 요약

이 프로젝트는 두 개의 얼굴을 가진다. 하나는 실전에서 검증된 저지연 저널 엔진(C++ yijinjing + libkungfu) — 원래 트레이딩용으로 "절대 데이터를 잃지 않는" 것이 목표였던 코어다. 다른 하나는 그 위에 얹힌 에이전트 연속성 제품 — kungfu run agent 한 줄로 에이전트를 돌리며 그 작업을 봉인된 에피소드로 남기는 것이 목표다. 아래가 이 프로젝트가 그리는 "골든 패스"다.

# 프로젝트 폴더에서, 목표로 삼은 첫 릴리스 진입점
cd your-project
kungfu run agent

# 설치된 런타임은 자신의 정책·프로토콜을 런타임 없이도 보여줄 수 있어야 한다
kungfu exit verify --info --json     # Exit(이탈) 정책 · 프로토콜 목록
kungfu agent brief                   # 에이전트용 로컬 브리핑

중요한 전제 두 가지. 첫째, Kungfu는 당신이 이미 쓰는 에이전트를 대체하지 않는다. kungfu run agent는 "골든 패스"일 뿐, Codex·Claude Code·VS Code·터미널은 그대로 쓰면서 같은 로컬 계약과 작업 상태를 공유하는 것이 목표다. 둘째, 현재 상태는 "Coming soon"(v4 알파)이다. 공개 CLI 아티팩트는 아직 없고, 소스 빌드로만 평가할 수 있다. 이 문서는 "무엇을 만들고 있는가"와 "왜 그 설계가 흥미로운가"에 초점을 두되, 프로젝트 자신이 강조하는 설계 의도 ≠ 구현됨 ≠ 검증됨 ≠ 릴리스됨의 구분을 그대로 존중한다.

2왜 주목받는가

에이전트 메모리·연속성을 표방하는 도구는 이미 많다(메모리 MCP, CLAUDE.md류 지침 파일, 벡터 메모리…). Kungfu가 트렌딩에 오른 이유는 접근이 근본부터 다르기 때문이다 — "파일에 메모를 더 쌓자"가 아니라, 금융 트레이딩에서 검증된 저지연 append-only 저널과 콘텐츠 주소 지정·머클 루트·신뢰 경계를 통째로 가져왔다는 점이다.

둘째, "기록했다"와 "믿을 수 있다"를 분리한다. 대부분의 메모리 도구는 무언가를 적으면 그걸 곧 진실로 취급한다. Kungfu의 핵심 불변식은 정반대다:

recorded != admitted != trusted          # 기록됨 ≠ 인정됨 ≠ 신뢰됨
write returned != visible != durable != projected
# 쓰기가 반환됐다고 보이는 것도, 영구적인 것도, 투영된 것도 아니다

Claim + Purpose + Cut + Proof  ->  TrustReport
# 주장 + 목적 + 컷 + 증거  →  신뢰 보고서
# Facts are authoritative. Projections are rebuildable.

에이전트가 스스로 "다 했어요"라고 주장(Claim)해도, 그 주장은 자기 자신을 승인할 수 없다. 목적(Purpose)에 비춘 평가와 증거(Proof)를 거쳐야 신뢰 보고서(TrustReport)가 된다. 이 "자기 승인 불가" 원칙은, 에이전트가 환각으로 "성공했다"고 우기는 문제를 구조적으로 막으려는 시도다.

셋째, 자기 자신에게 먹여본다(dogfooding). 이 저장소 자체가 .kungfu/(봉인된 에피소드)와 .xinfa/(검증된 컨텍스트 Atlas)를 실제로 담고 있다. 개념을 슬라이드로만 파는 게 아니라, 저장소가 곧 살아있는 증거다. 그리고 KFD 에이전트 공급망이라는 더 큰 야심 — 서로 독립적으로 소유된 제품들 사이로 "책임 있는 작업 사실"을 표준 형식으로 실어 나른다는 구상 — 도 함께 제시한다.

3기술 스택 전체 지도

Kungfu는 4개 언어가 하나의 저널 위에 층층이 쌓인 폴리글랏 모노레포다. 진짜 심장은 C++ 코어(framework/core, 전체의 93MB)이고, Rust·Node/TS·Python은 각자 다른 각도에서 그 코어를 감싼다. 언어마다 역할이 칼같이 나뉜다.

코어 (데이터 평면 + 런타임, C++23)

주변 언어 3종 (껍질)

4아키텍처 심화 분석

전체 구조를 한 문장으로: 맨 아래 yijinjing 저널이 유일한 진실원(원장), 그 위 libkungfu 런타임이 사실을 인정·봉인·검증하고, JSON·SQLite·GUI는 언제든 다시 만드는 투영(사본)이다. 아래가 그 층위다.

핵심 설계 ① — Fact와 Episode는 직교하는 두 축이다

Kungfu 사상의 중심에 이 구분이 있다. 헷갈리기 쉬운데, 둘은 경쟁하는 개념이 아니라 서로 다른 질문에 답하는 두 축이다.

Fact     ->  이 Cut(컷)에서 무엇이 인정되었는가   (지금의 스냅샷)
Episode  ->  여러 Cut에 걸쳐 무엇이 일어났는가       (시간의 흐름)

Fact는 "지금 이 순간 참으로 인정된 것들"의 집합이고, Episode는 "작업이 진행되며 벌어진 인과의 사슬"이다. 여기서 Cut이 결정적이다. Cut은 "이 질문에 답한 정확한 사실 경계"를 고정해, 3일 전에 던진 질문의 답을 오늘 다시 물어도 똑같이 재현되게 만든다. 시간이 흘러 사실이 바뀌어도, 특정 Cut에서의 답은 영원히 그대로다.

핵심 설계 ② — 봉인된 에피소드는 진짜로 해시로 굳는다

추상 개념 같지만, 이 저장소의 .kungfu/ 안에는 실제로 봉인된 에피소드가 들어 있다. 아래는 실제 claims.jsonl의 한 조각이다(프레임 한 줄 = JSON 한 줄).

# .kungfu/episodes/sealed/sha256/<aa>/<full-hash>/claims.jsonl (실제 발췌)
{"index":0,"record":{"actor":"codex/pro-qian/dev-cache-scope-closure",
  "episode_id":202607170318,"record_kind":"episode_open",
  "schema":"kungfu.episode.manifest/v1","status":"open",
  "title":"Dev cache scope closure qualification",
  "begin_time":"1784258833068159208"}}          # ← 나노초 타임스탬프
{"index":2,"record":{"algorithm":"sha256","record_kind":"episode_root_committed",
  "root_value":"8367e64b1245a7c709187501a4592d2ea2044662a01312752ee7ce302caab4e9",
  "covered_record_count":2}}                     # ← 이 루트가 곧 봉인된 정체성

episode_open으로 열리고, 프레임들이 이어 붙고, 마지막에 episode_root_committed가 sha256 루트를 커밋하며 봉인된다. 이 루트 해시가 곧 에피소드의 콘텐츠 주소이자 변조 불가능한 정체성이다 — Git이 커밋을 해시로 굳히는 것과 똑같은 원리를, "에이전트가 한 작업"에 적용한 것이다.

핵심 설계 ③ — shifu: curl만으로 스스로 서는 단일 진입점

폴리글랏 모노레포의 악몽은 "빌드 환경 맞추기"다. Kungfu는 이를 shifu(師父, 스승)라는 3단 런처로 푼다. 신선한 클론에서 필요한 건 curl 하나뿐 — shifu가 node(fnm+.node-version)·python(uv)·툴체인(Buildchain)을 ~/.cache/kungfu에 알아서 부트스트랩한다. 그리고 218개 npm 스크립트가 전부 shifu 게이트를 통과해야만 실행된다(build조차 require-shifu.mjs를 먼저 지난다). "아무 명령이나 날것으로 도는" 일이 없다.

# 신선한 클론에서 소스 평가 — 이게 전부다
git clone https://github.com/kungfu-systems/kungfu.git
cd kungfu
./shifu doctor              # 환경 진단(스스로 부트스트랩)
./shifu sync && ./shifu build  # 의존성 동기화 + 빌드

# 불변식(Fact/Episode 규칙)을 소스에서 직접 캐묻기
./shifu invariant:verify -- --list --json

핵심 설계 ④ — Xinfa: 검증된 컨텍스트 컴파일러

Xinfa(心法, 내공의 심법)는 "인간-에이전트 소프트웨어 개발을 위한 검증된 컨텍스트 컴파일러"다. 편리한 README나 낡은 요약, 추측한 경로가 슬그머니 "권위"가 되는 걸 막는 게 목표다. 선언된 프로젝트 소스에서 불변의 Atlas(지도)를 컴파일하고, 작업에 필요한 한정된 "Task Chart"만 골라 에이전트에게 준다. 각 에이전트 경로에는 측정된 토큰 예산이 붙는다(예: 문서 통제 66,560 · 코어 개발 16,384). 흐름은 compile → verify → route resolve → context. 실제로 이 저장소의 .xinfa/project.json이 그 컴파일된 노드·엣지·경로 그래프를 담고 있다.

핵심 설계 ⑤ — KFD 에이전트 공급망

가장 야심 찬 층위다. Kungfu는 자신을 "열린 에이전트 공급망"의 4번째 계층으로 규정한다.

KFD-3 발견  ->  Buildchain 아티팩트 증거  ->  KFD-2 평가
   ->  libkungfu / .kungfu 지속 작업 사실  ->  독립 Agent Hub들

발견(KFD-3)·검증 증거(Buildchain)·평가(KFD-2) 위에서, Kungfu는 "지속되는 작업 사실과 에피소드를 기록·정렬·질의·검증·수출·복구하는 4번째 층"을 맡는다. 그 위 독립 Agent Hub들은 서로 다른 제품이 소유하되, "책임 있는 작업 객체"를 표준 경계로 주고받는다. 각 수신자는 무엇을 받아들일지(admission)를 스스로 통제한다. 아직 대부분 "declared(선언)" 단계지만, "벤더가 달라도 작업 사실은 이식된다"는 방향성 자체가 이 프로젝트의 큰 그림이다.

5디렉토리 구조 해부

구조가 말해 주는 것: 코어와 계약이 압도적 비중이다. framework/core(C++)가 심장이고, framework/*/*.contract.json 15개 폴더가 "규칙의 단일 진실원"으로 흩어져 있다. 껍질(GUI·TUI·CLI·SDK)은 이 코어를 각 언어로 감싼 얇은 층일 뿐이다. 그리고 숨김 폴더 .kungfu/·.xinfa/가 진짜 핵심 — 이 저장소가 자기 자신의 작업을 봉인된 에피소드와 검증된 Atlas로 남기며 스스로를 증거로 삼고 있다. 개념을 코드가 아니라 데이터로 증명하는 셈이다.

6학습 포인트

실습 아이디어 (짧게)

클론한 저장소의 .kungfu/episodes/sealed/로 들어가 실제 claims.jsonl과 manifest.json을 열어 봐라. episode_open → 프레임들 → episode_root_committed의 흐름을 눈으로 따라가고, 커밋된 root_value(sha256)가 어떻게 그 에피소드의 정체성이 되는지 확인하라. 개념 문서 100장보다 이 JSONL 몇 줄이 "봉인된 에피소드"를 더 확실히 각인시킨다.

7시스템 / 빌드 요구사항

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

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

10핵심 키워드 사전

11참고 링크