KAUT — 신뢰 기반 지식 실현 (Knowledge Actualization Under Trust)

레거시 코드베이스를 AI 네이티브로 만듭니다. KAUT는 프로젝트를 위한 자가 유지형, AI 우선 문서화 — 문서화되지 않고 맥락이 약한 코드를 AI 에이전트가 이해할 수 있게 만드는 지식 계층입니다. 대화의 기억이 아니라 시스템 자체에 대한 지식 기반입니다: 무엇을 하는지, 어떻게 구조화되어 있는지, 왜 그런지. 에이전트가 작업 중 배운 것을 살아있는 문서로 전환하여 어떤 세션도 처음부터 시작하지 않도록 합니다.

제로 의존성 Node.js (≥ 20, 24에서 개발), Apache-2.0. macOS와 Linux에서 개발 및 테스트됨 (CI는 Linux, Node 20 및 24에서 실행); Windows는 지원되지 않습니다.

완전하고 독립적인 제품. git clone 하나가 전체 설치입니다. 번들된 MCP 서버에 하네스를 연결하거나(또는 어떤 스킬/프롬프트에서 CLI를 호출) 작동합니다 — 오케스트레이터, 프레임워크, 서비스, 계정, 배포할 다른 것이 전혀 없습니다. 형제 프로젝트인 TAUT 오케스트레이션 프레임워크와 함께 구성됩니다 (TAUT는 에이전트를 구동하고, KAUT는 그들이 아는 지식입니다) — 그러나 그 통합은 선택 사항이지 의존성이 아닙니다.

상태: v0.8.1 — 전체 루프가 가동 중입니다. 읽기: lookup (한 번 호출로 준비된 답변) 신선도 판정(merge-base 앵커, 확실하지 않을 때 "신선"이라고 절대 외치지 않음), 신뢰 계층, altitude 커버리지 밴드; 변조 방지는 파이프라인 외부에서 편집된 모든 것을 보류합니다. 다중 저장소: 워크스페이스 레지스트리, 멤버별 저장소, 런처 저장소에 앵커된 하나의 시스템 저장소. 쓰기: 계층형 쓰기 게이트 (에이전트 계층 업데이트는 직접 반영되고, 소유자 게이트 계층 및 새로운 문서는 비동기 검토를 위해 초안으로 대기). 유지 관리: refresh (재파생 델타 번들), touched (변경 지점 센서), digest/note (사용 및 결과 원격 측정). 상호 운용: 저장소는 OKF v0.2 적합성 기준을 충족하며 kaut okf export는 관용적인 OKF 번들을 생성합니다. 모든 MCP 지원 하네스는 번들된 MCP 서버를 통해 연결됩니다. 자세한 내용: docs/HANDBOOK.md §16.

해결하는 문제

모든 새로운 AI 세션은 기억상실로 시작합니다: 에이전트는 프로젝트를 다시 탐색하고, 같은 질문을 다시 하며, 최악의 경우 가장 비용이 많이 드는 실수를 계속합니다: 컴파일되고 테스트를 통과하지만, 알 수 없었던 비즈니스 규칙을 조용히 위반하는 코드.

프로젝트의 "이유"는 대개 어디에도 기록되지 않습니다. KAUT는 그것이 살아갈 장소를 제공하고 — 계속 살아있게 유지합니다.

이것은 레거시 코드에서 가장 큰 피해를 줍니다: 수년간의 문서화되지 않은 결정, 원작자가 없는 상태, 부작용으로만 보이는 비즈니스 규칙. 바로 AI 코딩 도구가 오늘날 성능이 떨어지는 지점이며 — KAUT가 구축된 코드베이스입니다. KAUT는 더 큰 목표의 첫 단계입니다: 레거시 코드베이스를 AI 네이티브로 만드는 것 — 에이전트가 안전하고 저렴하게 작업할 수 있도록 구조화하는 것입니다.

Related MCP server: 50 First Tapes MCP Server

KAUT가 무엇인지 — 그리고 무엇이 아닌지

세 가지 친숙한 범주는 멀리서 보면 비슷해 보입니다. KAUT는 그 중 어느 것도 아닙니다 — 그리고 그 차이가 바로 가치가 있는 곳입니다.

또 다른 메모리 시스템이 아닙니다. 메모리는 *"무엇에 대해 이야기했는지, 이 사용자가 무엇을 선호하는지?"*에 답합니다 — 개인적이고, 일화적이며, 검증할 수 없습니다. KAUT는 *"이 프로젝트가 어떻게 작동하고, 왜 그런가?"*에 답합니다 — 문서: 도메인별로 구성되고, 소스에 바인딩되고, 신선도가 확인되고, 신뢰도가 표시되며, 모든 에이전트 그리고 인간이 읽을 수 있습니다. 개인 메모는 KAUT에 들어가지 않습니다; 프로젝트 지식은 한 에이전트의 메모리에 갇히지 않습니다. 그 경계는 쓰기 경로에 내장되어 있습니다.

RAG가 아닙니다. 검색 증강 생성은 존재하는 텍스트를 색인하고 가장 잘 맞는 청크를 제공합니다 — 그것들이 여전히 사실인지에 대한 정보는 없습니다. KAUT는 반대 선택을 저장합니다: 재파생 비용이 높고 코드에서 쉽게 볼 수 없는 지식만 (저장 리트머스), 모델이 전체를 읽는 짧은 문서로 증류 — 임베딩, 순위, 청크 수프가 없습니다. 그리고 모든 문서는 기계 검증된 신선도 판정을 갖습니다: 파생된 커밋에 앵커되고, 읽을 때마다 추적된 메인 브랜치와 diff되며, git이 달리 증명할 수 없을 때 stale 쪽으로 오류합니다. 원한다면 코드에 RAG를 실행하세요 — KAUT는 코드가 말하지 않는 것을 위한 것입니다: 이유, 횡단 불변식, 부족 지식.

LLM 위키가 아닙니다. 자동 생성 문서는 그럴듯한 텍스트로, 탄생 시 검증되지 않고 첫 커밋에서 버려집니다. KAUT 문서는 타입이 지정된 소스 바인딩과 앵커 커밋 없이는 존재할 수 없으며 — 소스가 읽을 때마다 diff되기 때문에 조용히 틀린 상태로 남을 수 없습니다. 쓰기 경로는 나머지 절반입니다: 기계적 계층은 자동으로 재생성되고, 에이전트는 세션에서 검증한 운영 사실을 반영할 수 있지만, 판단 계층 지식(결정, 도메인 의미론, 계약)은 인간 승인 게이트를 통해서만 들어옵니다 — 업데이트는 일괄 검토하는 초안으로 대기합니다. 위키는 기본적으로 썩습니다; KAUT의 기본값은 고백하는 것입니다.

그리고 독점 사일로가 아닙니다. KAUT는 벤더 중립적인 Open Knowledge Format (OKF) v0.2의 구현입니다 — 저장소는 OKF의 적합성 기준을 그 자리에서 충족하는 타입이 지정된 마크다운 개념 문서이며, kaut okf export는 모든 저장소를 완전히 관용적인 OKF v0.2 번들(출처, 신뢰 및 수명 주기 패밀리 포함)로 프로젝트하며, 모든 OKF 소비자가 읽을 수 있습니다. KAUT의 신선도/신뢰 메커니즘은 OKF 보호 확장 키로 그 위에 탑재됩니다: 형식은 지식을 기록하고 — 엔진이 그것을 진실하게 유지합니다. 규범적 매핑은 SCHEMA.md에 있습니다.

원칙

1. 소스 바인딩, 커밋 앵커. 모든 사실은 출처가 된 파일과 파생된 커밋을 명명합니다. 소스가 없으면 문서도 없습니다 — 계약은 문 앞에서 검증됩니다.

2. stale 쪽으로 오류. 신선도는 순수한 git 계산입니다 (추적된 메인 브랜치에 대한 merge-base). git이 문서가 최신임을 증명할 수 없을 때, 판정은 그렇게 말합니다. KAUT는 확실하지 않을 때 "신선"이라고 절대 외치지 않습니다 — 거짓 "stale"은 재확인 비용이 들고, 거짓 "신선"은 버그를 배송합니다.

3. 지식은 정보를 제공합니다; 결코 권한을 부여하지 않습니다. 건강한 판정은 재파생을 건너뛸 권한이지, 행동할 권한이 아닙니다. 판정은 신뢰를 라우팅합니다: 건강 + 정확 = 그대로 사용 가능; stale / broken / coarse-altitude = 먼저 코드에서 확인.

4. 보증할 수 없는 것은 제공하지 않습니다. 저장소는 AI 에이전트가 읽으므로 파이프라인 외부 편집은 편의가 아니라 주입 채널입니다. 마지막 파이프라인 커밋과 바이트 단위로 동일하지 않은 것은 복원되거나 정당하게 반영될 때까지 전체가 보류됩니다 (tampered).

5. 인간은 판단을, 에이전트는 메커니즘을 소유합니다. 계층형 쓰기 게이트: 맵은 자유롭게 재생성되고, 검증된 운영 사실은 에이전트 계층에 반영되며, 결정/도메인/계약 지식은 소유자의 한 번의 키 입력 검토를 위해 초안 대기열에서 기다립니다.

6. 가장 저렴한 곳에서 수리합니다. 신선도 감쇠는 영웅적으로가 아니라 구조적으로 싸웁니다: 변경 지점 (touched는 코드 변경이 빚진 문서를 명명), 읽기 지점 (stale 판정은 refresh 델타 번들과 함께 도착 — 정확히 무엇이 변경되었는지, 무엇에 대해 재파생할지), 그리고 정직한 원격 측정 (digest)으로 유지 관리가 속도를 유지하는지 확인합니다.

7. 로컬 우선, 제로 의존성, 저장소 무접촉. 하나의 클론, 설치 단계 없음, 데몬 없음, 클라우드 없음; 지식 저장소는 저장소 외부에 있으며, 신선도 검사는 git 비교 비용 — 모델 호출이 아닙니다.

KAUT가 하는 일

• 알려진 한 곳을 봅니다. 에이전트는 코드를 다시 탐색하기 전에 KAUT를 확인합니다. 답이 있거나, KAUT가 그 공백을 기록하여 나중에 채워지도록 합니다.

• 지식이 스스로 수집됩니다. 작업이 끝나면 에이전트가 방금 배운 유용한 것들이 베이스로 응축됩니다 — 이미 지불된 작업의 부산물이지 별도의 문서화 프로젝트가 아닙니다.

• 자신 있게 거짓말하지 않습니다. 모든 저장된 사실은 출처가 된 코드에 계속 연결됩니다. 코드가 변경되면 사실은 자동으로 오래되었을 가능성이 있는 것으로 표시됩니다. 의심스러울 때 KAUT는 모든 것이 신선한 척하지 않고 "다시 확인하세요"라고 말합니다.

• 보증할 수 없는 것을 제공하지 않습니다. 지식 기반은 AI 에이전트가 읽으므로 KAUT의 등 뒤에서(자체 버전 관리 외부에서) 편집된 파일은 잠재적 주입 채널입니다. 그러한 콘텐츠는 복원되거나 제대로 다시 커밋될 때까지 전체가 보류됩니다 — 에이전트가 보는 모든 답변은 출처 추적 커밋에서 나옵니다.

• 당신이 판사로 남습니다. 소유자 게이트 계층과 새로운 문서는 승인 없이는 절대 반영되지 않습니다: 업데이트는 초안 (kaut draft)으로 대기하고, 한 자리에서 전체 배치를 반영하거나 폐기합니다 (kaut review). 에이전트가 끝낼 때 당신이 자리에 있을 필요는 없습니다.

• 저장소는 절대 건드리지 않습니다. 모든 지식은 프로젝트 외부의 별도 폴더에 있습니다. git 기록, 브랜치, 팀원은 그것을 볼 수 없습니다.

• 모든 에이전트가 연결할 수 있습니다. CLI 외에도 KAUT는 MCP 서버(node <engine>/mcp.mjs, 제로 의존성)를 제공합니다 — 동일한 조회, 신선도 판정, 게이트된 쓰기를 MCP 도구로 제공하며, 모든 MCP 지원 하네스 또는 오케스트레이터용입니다. 하나의 서버가 전체 다중 저장소 워크스페이스를 처리합니다 (각 호출은 저장소를 명명합니다).

아키텍처

flowchart LR
    subgraph clients["Clients"]
        direction TB
        HARNESS["AI agents\nany MCP-capable harness"]
        HUMAN["Humans and CI\nshell, scripts"]
        ORCH["Orchestrator, e.g. TAUT\n(optional)"]
    end

    subgraph engine["KAUT engine - stateless, zero-dep Node, no daemon"]
        direction TB
        SURF["Two surfaces\nmcp.mjs - 7 MCP tools\nkaut.mjs - CLI"]
        READP["READ path (lock-free)\nlookup / stale / digest\nfreshness verdict = pure git computation\n+ trust tier + altitude on every answer"]
        WRITEP["WRITE path (one chokepoint)\nlayered write gate + draft queue\nagent tier lands, judgment tier\nwaits for owner review"]
        MAINTP["Maintenance loop\nrefresh / touched / note\nmap collectors (stack adapters)"]
    end

    subgraph home["Knowledge data home - set once with kaut home"]
        direction TB
        STORES["One store per repo\ntyped markdown + frontmatter\nown private git = audit + rollback\njournal telemetry"]
        REG["workspaces registry\nmember stores + one system store"]
        BACK["backups/\nkaut backup / restore"]
    end

    REPOS["Your repositories\nREAD-ONLY sources\n(at most one git-ignored pointer file)"]
    OKFB["OKF v0.2 bundle\nkaut okf export"]

    HARNESS --> SURF
    HUMAN --> SURF
    ORCH --> SURF
    SURF --> READP
    SURF --> WRITEP
    SURF --> MAINTP
    READP -- "diff sources against\nthe anchor commit" --> REPOS
    MAINTP -- "derive maps from code" --> REPOS
    READP <--> STORES
    WRITEP --> STORES
    STORES --> OKFB

네 문장으로 된 형태 설명. 엔진은 상태 비저장(state stateless) — 모든 명령(CLI 또는 MCP 도구)은 두 개의 git 히스토리에서 답을 계산하고 종료됩니다. 상주하는 프로세스가 없어 실행하거나 동기화하거나 손상시킬 것이 없습니다. 지식은 저장소 외부에 존재하며, 데이터 홈에 저장소당 하나의 스토어가 있고, 각 스토어는 자체적인 개인 git 저장소입니다 — 이것이 쓰기 게이트(write gate), 변조 격리, 감사, 롤백을 가능하게 하는 이유입니다. 읽기 경로는 절대 차단되지 않고 추측하지 않습니다: 판정은 요청하는 순간 문서의 타입이 지정된 소스와 앵커 커밋(anchor commit)을 diff하여 도출됩니다. 쓰기 경로에는 정확히 하나의 병목 지점(chokepoint) 이 있어, 다른 명령을 선택함으로써 정책(에이전트 티어 vs 소유자 검토)을 우회할 수 없습니다.

빠른 시작

1. 엔진을 서비스할 저장소 옆에 복제합니다 (형제 폴더 — setup은 이웃을 스캔합니다. npm install은 없습니다. 엔진은 의존성이 전혀 없습니다):

cd ~/projects && git clone https://github.com/yurgeno/kaut.git

2. setup 실행 — 세 가지 질문이며, 모든 답변에는 스크립트 설치용 플래그가 있습니다:

node kaut/kaut.mjs setup

• 지식 데이터 폴더 — 스토어가 위치하는 곳 (기본값: <siblings>/kaut-data). 한 번만 저장됩니다(kaut home 리다이렉트): 이후의 모든 명령과 MCP 서버는 스스로 이를 해석합니다 — 내보낼 것도, 전달할 것도 없습니다. 이 폴더는 라이브 데이터입니다: 엔진은 여기에 추가만 할 뿐, 기존의 어떤 것도 삭제하거나 덮어쓰지 않습니다.

• 어떤 저장소 — setup은 모든 형제 git 저장소를 나열합니다. all, 번호, 또는 이름으로 답하세요.

• 지금 부트스트랩? — 예(yes)는 선택된 각 저장소에 대해 즉시 스토어를 생성/갱신합니다 (멱등적: 기존 스토어는 갱신되며, 다시 시드되지 않습니다). 아니오(no)는 구성만 기록하고 나중에 사용할 저장소별 명령을 출력합니다.

비대화형: node kaut/kaut.mjs setup --data <dir> --repos all --bootstrap --yes (--no-bootstrap, 다른 위치를 스캔하려면 --scan <dir>).

3. 출력된 다음 단계를 따르세요 — setup은 정확히 두 가지로 끝납니다: MCP 서버를 하네스에 연결하고, 지식 계약(knowledge contract)을 에이전트 지침에 붙여넣기 (둘 다 아래에 있음). 선택적으로 저장소별 기계적 맵(mechanical map)을 생성할 수 있습니다:

node kaut/kaut.mjs map

(부트스트랩은 이미 스택을 감지하고 올바른 수집기를 시드했습니다 — 아래의 지원 스택 참조. 입력이 없는 수집기는 메모와 함께 스스로를 건너뛰며, map.collectors: []는 맵 레이어가 단순히 비어 있음을 의미합니다).

지원 스택

부트스트랩, 지식 루프, 신선도 판정, 쓰기 게이트 — 이 모든 것은 스택에 무관합니다: 어떤 git 저장소든 작동합니다. 기계적 map/ 레이어만 스택별로 다르며, 부트스트랩은 스택을 자동 감지하여 그에 따라 map.collectors를 시드합니다 (기존 구성은 절대 건드리지 않으며, 모든 설정은 재정의 가능합니다):

인식 가능한 스택이 없는 저장소는 빈 맵 레이어를 얻고 다른 모든 것은 동일하게 작동합니다. 어휘적 수집기는 정직한 최선 노력 스캔이며, 생성된 문서에 그렇게 표시됩니다. 추가 스택용 어댑터는 의도적으로 작은 모듈입니다 — 누락된 스택이 있다면 CONTRIBUTING.md를 참조하세요.

에이전트 연결 — 실제로 효과를 만드는 단계

스토어만으로는 아무것도 바뀌지 않습니다: 에이전트가 스토어의 존재와 언제 참조해야 하는지 알아야 합니다. 두 가지 조치 (붙여넣기 준비된 블록과 실제 세션 예시가 포함된 전체 가이드: docs/AGENT-INTEGRATION.md):

1. MCP 서버를 하네스에 연결합니다 (Claude Code용 .mcp.json, Codex용 config.toml — 스니펫은 가이드에 있음). 일곱 개의 kaut_* 도구가 모든 세션에 나타나며, 그 설명은 이미 모델에게 규율을 가르칩니다: 재탐색 전에 조회, 판정에 따라 신뢰 라우팅, 게이트를 통해 다시 쓰기.

2. 지식 계약을 에이전트가 매 세션 로드하는 곳에 붙여넣습니다 (CLAUDE.md / AGENTS.md / 시스템 프롬프트) — 가이드의 약 15줄 블록으로, 행동을 우연이 아닌 신뢰할 수 있게 만듭니다: 재도출 전에 읽기, 건강하고 정확함 = 그대로 사용, 오래됨/대략적임 = 코드에서 확인, 결과를 kaut_note로 태그, 파일 편집 후 kaut_touched 실행하고 변경이 요구하는 바를 수리하거나 대기열에 넣기.

선택적으로 계약을 하네스 스킬로 래핑하거나(템플릿은 가이드에 있음), 오케스트레이션 프레임워크가 연결을 컴파일하게 할 수 있습니다 — TAUT는 setup 답변 하나로 이를 수행합니다. 그런 다음: 평소처럼 작업하세요. 직접 탐색하고 싶다면 node <engine>/kaut.mjs lookup이 주제 카탈로그를 출력합니다.

일상 사용 — 없습니다

KAUT는 보이지 않게 설계되었습니다. 정확히 세 가지 순간에만 인지하게 됩니다:

• 명령 시 — 에이전트에게 방금 배운 것을 저장하라고 지시합니다("이것을 KAUT에 영속화"): 세션의 발견 사항을 리트머스 테스트로 필터링하고, 적절한 소스 바인딩과 함께 작성한 후 스토어의 git에 커밋합니다. 소유자 게이트 지식은 여전히 검토를 위해 초안 대기열에서 멈춥니다.

• 초안이 쌓일 때 — kaut review는 대기 중인 항목을 나열합니다. 한 번에 배치를 승인하거나 거부하세요 (doctor도 대기열이 있는 동안 경고합니다).

• 가끔 에이전트가 인간만이 답할 수 있는 질문을 합니다("이 규칙은 의도적인가요, 아니면 사고인가요?"). 당신의 답변은 베이스에서 가장 가치 있는 종류의 지식이 됩니다.

그 외의 모든 것 — 조회, 신선도 확인, 맵 재구축 — 은 자동으로 조용히 이루어집니다.

명령

프로젝트 git 저장소 내 어디에서나 실행:

node <engine>/kaut.mjs setup         # guided install: data home, sibling-repo scan, bootstrap (run once, from anywhere)
node <engine>/kaut.mjs bootstrap     # create/repair the project's knowledge store (idempotent)
node <engine>/kaut.mjs index         # regenerate INDEX.md (under lock; auto-commits changes)
node <engine>/kaut.mjs doctor        # integrity checks; exit 0 = healthy
node <engine>/kaut.mjs home [<dir>]  # show or set the knowledge-data home (redirect at ~/.kaut/config.json)
node <engine>/kaut.mjs paths         # print resolved {projectId, root, engine, repo, mainBranch, source}
# reading core:
node <engine>/kaut.mjs lookup [<id>] # one-call ready block; no id = catalog; unknown id = miss (exit 0)
node <engine>/kaut.mjs stale [<id>…] # freshness verdicts for all/selected docs (read-path, no lock)
node <engine>/kaut.mjs map           # regenerate L0 maps per config map.collectors + commit
# maintenance loop:
node <engine>/kaut.mjs refresh [<id>…]        # per-doc re-derivation delta bundles (read-only)
node <engine>/kaut.mjs draft <id>             # queue a finished doc update for async owner review
node <engine>/kaut.mjs review [<id>…]         # owner side: list / diff / --approve / --reject
node <engine>/kaut.mjs touched <file>…        # which docs bind the given changed files
# telemetry:
node <engine>/kaut.mjs note <topic> <result>  # record an in-session outcome (trusted|confirmed|insufficient|stale-misled)
node <engine>/kaut.mjs digest [--since <ISO>] # aggregate journal telemetry across workspace stores
# backup / restore (the whole data home — stores, registry, setup record):
node <engine>/kaut.mjs backup                 # dated, versioned .tar.gz under <data>/backups/
node <engine>/kaut.mjs restore [latest|<file>] [--force]   # no arg = list; never overwrites without --force
# open format (OKF v0.2):
node <engine>/kaut.mjs okf check              # store-as-OKF-bundle conformance report (exit 0 = conformant)
node <engine>/kaut.mjs okf stamp              # backfill `type:` on legacy docs (through the write gate)
node <engine>/kaut.mjs okf export --out <dir> # project committed HEAD into an idiomatic OKF v0.2 bundle
# workspace (multi-repo):
node <engine>/kaut.mjs workspace init --manifest <conductor>/manifest.json
                                     # registry + member stores + ONE system store anchored to the launcher
node <engine>/kaut.mjs workspace list

MCP 서버: node <engine>/mcp.mjs — 세션 동사를 MCP 도구로 노출하는 제로 의존성 stdio JSON-RPC 서버 (kaut_lookup, kaut_note, kaut_refresh, kaut_touched, kaut_write, kaut_draft, kaut_status). 모든 도구는 선택적 repo 인수를 받으므로, 하나의 서버가 전체 다중 저장소 워크스페이스를 서비스합니다. 소유자 실행 이스케이프 (review --approve, index --approve)는 의도적으로 MCP를 통해 노출되지 않습니다.

플래그: --dry-run (실행하지 않고 작업 출력) · --json (기계 출력용 stale|lookup|refresh|review|touched|digest) · --quiet · --approve / --reject (소유자 실행) · --force (restore: 기존 데이터 덮어쓰기; okf export: 비어 있지 않은 디렉토리에 쓰기) · --out <dir> (okf export) · --note <text> (note, review --reject) · --manifest <path> (workspace init) · --workspace <name> (doctor/stale/digest 워크스페이스 전체) · --since <ISO-date> (digest) · --help/-h (사용법, 종료 코드 0).

종료 코드: 0 정상 · 1 검증/doctor 실패 · 2 스토어 사용 중 (잠금 보유) · 3 환경 누락 (git 저장소 아님 / 스토어가 부트스트랩되지 않음).

lookup과 stale은 읽기 경로입니다 — 잠금을 걸지 않고 journal.jsonl에 한 줄만 추가합니다 (사용량 텔레메트리, 추적되지 않음). 신선도 판정은 오류가 아니라 데이터입니다: stale은 문서가 오래되었어도 0으로 종료됩니다. 판정 줄은 우선순위에 따라 최대 하나, tampered > disputed > broken > stale > branch-advisory; 건강한 문서는 깨끗하게 렌더링됩니다.

운영 깊이 — 디스크의 스토어 레이아웃, 해석 순서, 변조 격리 및 쓰기 게이트 상세, 제거, 엔진 내부: docs/OPERATIONS.md.

구성

파일 하나: 스토어의 kaut.config.json (부트스트랩이 생성, 합리적인 기본값). 대부분의 사람은 map 블록(수집기 목록 및 파일 위치 — 위 빠른 시작 메모 참조)만 건드립니다. 엔진이 실제로 읽는 전체 참조: docs/HANDBOOK.md §15.

실제로 도움이 되나요?

KAUT는 스스로 정직함을 유지하도록 설계되었습니다:

• 스토어별 사용량 저널을 유지합니다 (journal.jsonl): 판정이 포함된 모든 조회, 모든 게이트 쓰기, 모든 기록된 결과. kaut digest는 이를 워크스페이스 전체에 걸쳐 도달 / 자체 유지 / 가치 신호 수치로 집계합니다.

• 세션은 문서가 실제로 어떻게 사용되었는지 기록합니다 (kaut note <topic> trusted|confirmed|insufficient|stale-misled) — 지식이 작업을 절약한 곳과 오도한 곳을 보여주는 명예 시스템 가치 신호입니다.

• 벤치마킹은 외부에서 수행됩니다 (KAUT 유무에 따라 동일한 작업을 실행하고 비교); 엔진은 의도적으로 벤치마크 하네스를 포함하지 않습니다.

저널은 추가 전용(append-only) 추적되지 않는 텔레메트리이며 무한히 커집니다. 오래된 줄을 수동으로 잘라내는 것은 안전합니다 (결코 지식이 아니며, digest는 단순히 더 짧은 히스토리를 볼 뿐입니다).

백업

데이터 폴더가 전체 데이터베이스입니다 — 그에 따라 취급하세요. kaut backup은 전체 데이터 홈(각 스토어의 git 히스토리, 워크스페이스 레지스트리, setup 기록)을 <data>/backups/ 아래의 날짜가 표시된 버전 아카이브로 패킹합니다 — 표준 tar 도구로도 읽을 수 있는 일반 .tar.gz (수제 ustar + node:zlib, 제로 의존성)입니다. kaut restore latest (또는 파일 이름)로 복원합니다. --force 없이는 기존의 어떤 것도 덮어쓰지 않습니다 — 거부된 복원은 충돌을 나열하고 아무것도 건드리지 않습니다.

테스트

cd <engine> && node --test          # 213 tests, zero deps (node:test)

node --test를 그대로 실행하세요 — 테스트 디렉토리를 인수로 전달하지 마십시오 (Node ≥ 24에서 해당 형식은 스위트를 해석하지 못합니다).

제거

스토어 디렉토리 (~/.kaut/<project-id>)와 포인터 파일 (<repo>/.kaut.json)을 삭제하고, <repo>/.git/info/exclude에서 .kaut.json 줄을 제거하세요. 저장소는 처음부터 수정된 적이 없으므로 — 정리할 다른 것은 없습니다.

FAQ

이것은 또 다른 에이전트 메모리 시스템인가요? 아니요. 에이전트 메모리는 대화와 선호도를 기억합니다. KAUT는 프로젝트의 문서입니다 — AI 우선, 소스 바인딩, 신선도 검사. 쓰기 경로가 경계를 강제합니다: 프로젝트 지식은 KAUT로, 개인 선호도는 에이전트의 자체 메모리로.

이것은 RAG인가요? 아니요. 임베딩, 청킹, 검색 랭킹이 없습니다. KAUT는 에이전트가 전체를 읽는 소수의 정제된 문서를 저장하며, 각각 출처와 git 계산 신선도 판정이 있고, 코드에서 저렴하게 도출할 수 없는 것만 의도적으로 저장합니다. 코드베이스에 대한 RAG와 KAUT는 서로 다른 질문에 답하며 공존할 수 있습니다.

이것은 자동 생성 위키인가요? 아니요. 검증되지 않은 생성된 산문이 스토어에 들어가지 않습니다: 모든 문서는 타입이 지정된 소스 바인딩과 커밋 앵커를 가져야 하며, 기계적 레이어는 재생성되고(환각되지 않고), 판단 계층 지식은 인간 승인 게이트를 통과합니다. 그리고 위키와 달리 KAUT 문서는 조용히 썩을 수 없습니다 — 소스는 모든 읽기에서 diff됩니다.

스토어 형식이 독점적인가요? 아니요 — 오히려 반대입니다. KAUT는 벤더 중립적인 Open Knowledge Format (OKF) v0.2를 구현합니다: 일반적인 타입이 지정된 마크다운 개념 문서입니다. 모든 OKF 소비자는 스토어를 읽을 수 있으며, kaut okf export는 완전히 관용적인 OKF 번들을 생성합니다. 잠금 없음: 지식은 어느 쪽이든 git 저장소의 이식 가능한 마크다운입니다.

제 저장소에 무엇인가 커밋하나요? 아니요. 최대 하나의 무시된 포인터 파일만 있습니다. 지식 저장소는 저장소 외부에 있습니다.

제 팀이 이를 채택해야 하나요? 아니요. KAUT는 로컬 우선(local-first)입니다. 한 개발자가 설치하고 혜택을 받으며, 다른 사람은 관여하거나 영향을 받지 않습니다.

저장된 사실이 틀리면 어떻게 하나요? 모든 사실에는 출처와 신뢰 라벨이 있습니다. 에이전트는 낮은 신뢰도의 사실을 회의적으로 취급하고 코드와 대조하여 검증합니다. 저장소는 전체 기록을 유지하므로 잘못된 항목을 추적하고 롤백할 수 있습니다.

운영 비용은 얼마인가요? 첫 번째 맵 빌드가 비용이 많이 드는 부분입니다(수 분). 일상적인 유지 관리는 거의 비용이 들지 않도록 설계되었습니다. 신선도 검사는 순수한 git 비교이며 AI 호출이 포함되지 않습니다.

자세히 알아보기

• 프로젝트 위키 — 시작하기, 프로젝트 연결, 핵심 개념, 유지 관리 루프, FAQ 및 문제 해결을 안내 형식으로 제공

• docs/HANDBOOK.md — 모든 것이 어떻게 작동하는지, 인간 언어로 완전한 세부 사항으로 설명

• docs/OPERATIONS.md — 운영자 참조: 디스크 레이아웃, 해석, 변조 방지, 쓰기 게이트, 엔진 내부

• docs/AGENT-INTEGRATION.md — 에이전트를 저장소에 연결: 지식 계약, 하네스별 스니펫, 스킬 템플릿, 작업 세션

• docs/MCP.md — MCP 서버 참조: 등록, 7가지 도구, 프로토콜

• SCHEMA.md — 이 엔진이 구현하는 표준 데이터 계약 (OKF v0.2 적합성 매핑 포함)

• CHANGELOG.md — 릴리스 기록

• CONTRIBUTING.md · SECURITY.md · CODE_OF_CONDUCT.md

라이선스 및 인용

Apache-2.0 — LICENSE 및 NOTICE를 참조하세요. KAUT를 사용하거나 구현하는 개념을 기반으로 구축하는 경우 CITATION.cff를 통해 인용해 주세요.

연락처: Yuriy Orlov yuriy.orlov@undertrust.dev