이 글은 온프레미스 메뉴얼답변시스템을 구현하기 위한 과정에서 LLM wiki의 개념과 구현 사례를 구체적으로 이해하기 위해서 작성하였습니다.
AKM
DECK6/akm (Agent Knowledge Management, MIT). 동명의 별개 프로젝트 itlackey/akm과 다름
1. 모습
마크다운 기반 에이전트 지식 운영 체계.
DB·서버 없이 폴더 규약 + 프롬프트 스니펫 + 선택적 lint 스크립트로 동작하며, 파일을 읽는 에이전트(Claude Code, Codex 등)라면 어디에나 연결된다.
카파시의 LLM Wiki(소스/위키/스키마 3레이어, "Obsidian은 IDE, LLM은 프로그래머, 위키는 코드베이스")에서 출발했으나, GLOSSARY 명시대로 "LLM Wiki는 Knowledge Layer의 디자인 패턴일 뿐 AKM의 전부가 아니다."
정체성 문장: "지식만 쌓으면 위키, 실행만 반복하면 자동화. Learn Back이 있어야 AKM."
(참고: 카파시는 gist 발표 한 달 뒤인 2026년 5월 Anthropic 사전학습 팀에 합류했다 — 외장 기억을 스케치하고 내장 기억을 만드는 부서로 간 셈.)
2. 구조
레이어 (서가) — 무엇을 어디에
폴더 역할 핵심 규칙
00-inbox 접수 검역소 신규 입력 무조건 착륙, 7일 상한 (예외: 보관용 원본→10, 실행 로그→60/runs 직행)
10-sources 원본 보존 수정 절대 금지
20-knowledge 재사용 지식 누구에게나 참 (세상이 보증)
30-context 조직·사용자 맥락 우리에게만 참 (우리가 보증). 암묵지의 자리
40-memory 상주 포인터 매 세션 전부 로드 — 몇 줄만, 긴 지식 금지
50-procedures 실행 절차 단계+실패지점+검증법. skill/workflow/checklist/playbook
60-actions 선별된 실행 기록 재현·검증·복구·인수인계용만. 나머지 저장 금지
70-evaluation 품질 판정 rubric(기준)·failure-pattern(오답)·recovery·audit
80-outputs 외부용 산출물 납품함
90-archive 수명 종료 deprecated 딱지 후 이동
99-system 운영 규칙 ROUTER·SCHEMA·LOOP·VERIFICATION·GLOSSARY·INDEX·LOG·템플릿
템플릿: 서가가 정해지면 글의 형식도 정해진다. akmType별 템플릿 14종(99-system/templates/)이 "이 섹션을 이 순서로 채워라"를 규정 — 쓰고 나서 분류하는 게 아니라 분류가 글쓰기보다 먼저다(write-to-spec).
저장소 — 언제 읽는가
Memory(40, 항상) /
Brain(50+60+70, 행동할 때) /
Vault(10+20+30+80, 필요할 때).
레이어 = 저장 의미론, 저장소 = 로딩 동작.
따라서 20/30 구분은 토큰 문제가 아니라(둘 다 Vault) 유지보수 단위다: 낡는 이유(세상 vs 우리), 검증법(출처 대조 vs 조직에 묻기), 공유 범위(공개 가능 vs 내부), 충돌 시 우선순위(30이 20을 로컬 오버라이드)가 갈린다.
두 생산 라인의 순환
[지식 라인] 바깥 → 10(수집) → 20(컴파일) → 30(맥락 연결) ← 들어오는 길
[실행 라인] 40+50(+20/30 참조) → 실행 → 70 채점 → 80 납품 / 60 기록 ← 나가는 길
└ 실패 → 70 기록 → 원인 문서 수정 (Learn Back)
10/20/30은 실행의 입력, 80/60은 실행의 출력(60은 내부에 남는 송장 사본). 에이전트 산출물이 재입고되는 경로(sourceType: agent-output)만 예외.
입고 인지는 pull 방식 — 감시 데몬 없음, 세션 중 에이전트 + 주간 triage(date created 기준)가 전부.
3. 작동 원리
구동부: 여섯 줄 스니펫
설치란 adapters/claude-code/README.md의 6줄 스니펫을 자기 CLAUDE.md에 붙여넣는 것(레포 안에서 돌리면 루트 CLAUDE.md/AGENTS.md의 확장판이 대신함).
매 세션 상주하는 건 이 여섯 줄뿐이고, 각 줄이 시스템 기둥 하나씩의 후크다: ①②조회(INDEX·40 먼저 → 20/30/50) ③저장 라우팅(ROUTER) ④검증(VERIFICATION) ⑤Learn Back(LOOP) ⑥위생(10 불변, INDEX/LOG 갱신).
읽기의 3단 깔때기:
1단 = 스니펫 6줄(항상) →
2단 = 40 전체+INDEX(세션 시작, 짧은 것 전부) →
3단 = 20/30/50(필요할 때, INDEX가 가리킨 파일만). 내려갈수록 빈도는 줄고 양은 커진다. 2단이 매번 통째로 읽히므로 40과 INDEX에 "짧아야 한다" 규칙이 강하게 붙는다.
운영 루프
Ingest → Classify → Compile → Contextualize → Execute → Verify → Learn Back.
지식 입고는 1–4만, 실행 요청은 5–7만 돌 수 있으나, Verify 없인 Learn Back이 불가능하고 Learn Back 없인 루프가 닫히지 않는다.
라우팅
ROUTER의 Q1~Q8 first-match 결정 트리 = 자연어로 쓰인 if-else 체인(early return).
50 승격은 5조건 전부(반복+단계+실패지점+검증법+개선),
60 저장은 4용도(재현·검증·복구·인수인계) 중 하나 — 기본값은 "저장 안 함".
애매함은 보류하지 않는다: tie-breaking으로 제거하거나, 분류 불가면 ROUTER 자체를 개정하거나(시스템 결함 취급), trustLevel/nextAction 딱지로 명시한다.
검증 — "했다"와 "확인됐다"의 분리
위험 비례 4등급:
Tier 0(일회성, 사실만 확인) /
Tier 1(저장되는 모든 노트 — 저장된 오류는 복리로 재생산되므로) /
Tier 2(보고서·공개물, +핵심 주장 표본 검증) /
Tier 3(의료·법률·계약, +claim ledger+2차 검토).
"틀렸다"의 판정 주체, 신뢰도 순 4겹:
①현실 신호(에러·반려·테스트 실패 — 도구 실행 결과가 관찰 채널로 돌아오는 것. 단 세상은 침묵할 수 있다)
②기계 검사(lint·스크립트)
③rubric 든 LLM 자기 채점(공식적으로 최하위 증거 — 실행자와 채점자가 같은 확률적 인터프리터라는 순환)
④사람 피드백.
rubric은 대부분 에이전트가 만들되("기준 없으면 기준부터 만들어라") 권위는 재료에서 온다 — 외부 요구사항·실제 실패(판례)·사람 승인. rubric도 노트라서 현실과 어긋나면 개정된다. 서열은 항상 현실 > 채점표.
Learn Back — 실체는 상주 지시 한 줄
일반 원리: "실패는, 다음 실행이 읽게 될 문서 중 자기를 낳은 것을 고친다."
매핑:
절차대로 했는데 틀림→50 /
같은 실수 반복→40 경고 추가 /
지식이 틀림→20 /
의도 오해→30 /
오분류→ROUTER 개정 /
무검증 완료보고→70 rubric 신설.
수리 대상은 미래가 읽는 문서(20/30/40/50/70/99)뿐 — 과거의 스냅샷(10/60/80/90)은 고쳐도 미래가 안 바뀐다.
자동 장치는 없다. 실체는 스니펫 ⑤("실패 시 LOOP 매핑을 따르라")가 상주하고, LLM이 매핑표를 읽고, LLM의 Edit 도구가 파일을 고치는 것. 지시를 건너뛰면 루프는 안 돈다 — 이것 역시 프롬프트 순응에 의존한다. LLM이 게으르면 의도된 LOOP 실패.
4. 구현의 실체
엔진이 없다.
실행 코드는 lint·export 스크립트뿐. AKM에는 동사가 하나도 없다 — 읽기·쓰기·검색·수정 전부 하네스의 도구이고, AKM은 명사(무엇이 어디에, 어떤 라벨로)만 소유한다.
게임기(하네스)와 카트리지(AKM)의 관계: 카트리지는 혼자 아무것도 실행하지 않지만 어느 기기에 꽂아도 내용은 같다.
LLM = 확률적 인터프리터.
ROUTER가 코드가 아니라 산문인 이유: 조건식(is_repeatable_procedure?)이 의미 판단이라 기계가 평가 못 한다. 이 인터프리터는 파이썬보다 능력이 크고(의미 술어 평가) 신뢰성이 낮다(같은 규칙을 확률적으로 다르게 실행). AKM의 절반(lint·Tier·Learn Back·40 경고)은 전부 이 불량 인터프리터 대책이다.
한 문장: "의미를 이해하지만 신뢰할 수 없는 인터프리터를 위해 쓰인 프로그램 + 그 오류를 흡수하는 예외 처리 체계."
온톨로지의 저강도 수입.
frontmatter 키-값 = 사실상 트리플,
SCHEMA enum = 미니 온톨로지,
lint = 미니 SHACL.
빠진 것은 질의(SPARQL)와 추론 — 필요 시 TTL export로 파생 가능한 구조.
왜 외장 기억인가.
파라미터 속 지식(FFN 중심 분산 저장이 유력한 해석)은 손실 압축·수정 불가·출처 없음·확률적 인출.
파일 속 지식은 정확·즉시 수정·출처 명시·재현 가능.
이 비대칭("모델은 얼어 있고 파일은 살아 있다")의 귀결: ①학습은 수정 가능한 쪽에서 일어난다(Learn Back = 학습을 파일 레이어로 이사시킨 것 — 재학습 없이 나아지는 유일한 경로) ②능력은 모델에게, 지식은 파일에게 ③볼트는 두고 인터프리터만 교체 가능(축적물 전부 이월).
5. 검색 — 이 시스템의 아킬레스건
플랫 INDEX는 O(n)이다.
노트 1만 개 × 줄당 20~30토큰 = INDEX만 20만~30만 토큰으로 "매 세션 INDEX를 읽어라"가 물리적으로 붕괴한다.
완화책:
계층 인덱스(공식 해법):
index.mjs가 디렉토리별 INDEX.local.md 생성. 루트는 굵은 포인터만, 상세는 폴더 인덱스로 — 통독이 트리 하강으로 바뀐다(progressive disclosure).
grep(실전 해법, 단 AKM 규칙 밖):
검색 실행은 하네스 능력이다. AKM의 기여는 실행이 아니라 ①검색 가능성(전부 플레인 텍스트 — HWP/PDF엔 grep이 안 통함) ②hit의 해석 가능성(경로=레이어, 파일명=주제, description 줄=요약 → 열기 전에 내용 유추) ③회수 비용(한 파일=한 주제라 hit=꼭 맞는 노트). 손전등은 아무 창고에서나 켜지지만, 라벨 붙은 창고에서만 비춘 것이 무엇인지 안다.
라벨 경제학:
저장 시 라벨 비용 한 번(파일명·description·INDEX 줄)으로 검색 시마다 본문 통독을 면제받는 상각 구조. INDEX·폴더 인덱스·description·40 포인터 전부 같은 원리(열기 전에 고르게 하라)의 스케일 변주. "토큰 재배치"의 행선지 = 분류 + 검증 + 라벨 제작.
누락 문제:
물리적 누락(파일은 있는데 목록에 없음)은 기계 검사로 봉쇄됨(lint 커버리지 검사 + index.mjs 자동 생성 + CI).
남은 구멍은 의미적 누락 — 목록엔 있지만 요약이 나빠 검색에 안 걸리는 노트. 기계가 판정 못 하는 의미의 영역이라 Learn Back("못 찾은 노트의 description을 고쳐라")으로만 수리된다. 근본적으로 만 개 이상·의미 검색이 필요해지면 임베딩/KG를 외부에서 얹어야 한다(itlackey류 "찾기 엔진"과의 역할 분담 지점).
6. 위치 평가
잘 구성된 점:
모든 판단에 결정 규칙(트리·Tier·매핑표·tie-breaking), 시스템 자신도 개정 대상.
컨텍스트 경제 반영(포인터·한 줄 규칙).
기계 검증 가능 부분의 분리(enum+JSON Schema+lint+CI+테스트+fixture).
무의존·중립·감사 가능. 실운영(비대화 방지 조항들).
한계:
강제력 없음(프롬프트 순응 의존 — 분류도 채점도 Learn Back도).
검색 원시적(위 5절).
운영 규율 부담(병목은 작성이 아니라 유지보수 — 사서 노동을 토큰으로 지불).
토큰 절약 아님(재배치 — 반복 설명을 줄여 분류·검증·라벨에 토큰을 씀).
공개된 검증 사례 없음(벤치마크 있는 거 같음).
카파시 대비:
아이디어(gist) → 정밀 사양(현 위치) → 실행기(기존 에이전트, 빌려 씀) → 운영 인스턴스(비공개) → 공개 검증(없음).
에이전트 패러다임에서 정밀한 지시 문서는 부속물이 아니라 구현 계층이므로, 에세이를 클론 가능한 사양으로 컴파일한 것은 실재하는 진보임(특히 Learn Back은 카파시에 없던 독창 기여). 다만 진보의 종류는 발명이 아니라 표준화이고, 결여는 코드가 아니라 증거다. AKM 자신의 잣대로 trustLevel: unverified.
팔란티어와의 관계:
같은 목적지(에이전트가 조직 지식으로 업무 수행)의 정반대 접근.
팔란티어 = 형식 온톨로지+기계 강제+전사 통합+고가 톱다운,
AKM = 마크다운+프롬프트 약속+무의존+무료 보텀업 — "서민의 팔란티어".
중간지대(가벼운 지식 기반+MCP 연결 시스템+범용 에이전트)가 열리는 중이며, 그 조합에서 AKM의 자리는 팔란티어 온톨로지의 자리(에이전트가 조직을 이해하는 지식층)다.
사용 스펙트럼:
같은 볼트가 ①질의응답(문서검색 — 10/20/30+INDEX로 충분, 현실적 도입 시작점) → ②실행 코치(파일 도구로 초안·체크리스트까지) → ③직접 실행(ERP API·MCP 연결 시)으로 자란다. AKM은 문서검색 시스템으로 시작해 도구가 붙는 만큼 업무처리의 지식 기반으로 성장하도록 설계된 볼트다.
7. 직접 지을 때의 설계 원칙
관할 분리 — "기계의 것은 기계에게, LLM의 것은 LLM에게." 결정론 판정(스키마·링크·패턴·개수)은 코드로, 의미 판단만 LLM에.
래칫 — LLM 판단을 규칙화되는 대로 코드로 승격("너무 길다"→"3줄 이하"). 굳힌 만큼 확률 오류의 표면적이 준다.
판정기 제작에 LLM을 써라 — 매번 눈으로 검사시키지 말고 검사 스크립트를 한 번 짜게 하라. 오류가 매 실행에서 제작 시점 한 번으로 압축된다.
검증 강도는 피해 크기에 비례 — 최소선은 "저장되는 것은 무조건 검증".
저장은 좁은 문 — 승격은 ALL 조건, 기록은 4용도. 기준은 저장 비용이 아니라 미래의 검색 신호 대 잡음비.
실패는 로그가 아니라 수리 명령 — "실패 유형→고칠 문서" 매핑을 미리 정의하고, 분류 규칙 자체도 수리 대상에 포함.
작게 시작 — 10/20/50/70 + 30 한 건으로 전체 루프부터 시험. 하위 구분은 메타데이터만 맞으면 나중에 소급 가능.
해석과 원문을 구분 — "그 문장이 원문에 있는가"를 묻는 습관이 claim-support 검증이다. 같은 이름의 다른 레포, 문서에 없는 그럴듯한 규칙을 경계.
판정을 현실과 기계 쪽으로 밀어내라 — Verification 항목은 기계 확인 가능한 문장으로("파일이 존재하는가", "합계가 일치하는가"). LLM 자기 채점은 최후 수단, rubric의 권위는 외부 요구·실제 실패·사람 승인이라는 재료에서.
한 줄 결론
AKM은 **"신뢰할 수 없는 확률적 인터프리터 위에서 지식을 운영·검증·개선하기 위한 규약 체계"**다. 사양으로서 치밀하고 LLM Wiki의 목적은 초과 달성했으나, 엔진이 아니라 헌법이므로 품질은 에이전트 성능과 운영 규율이 결정하고, 규모의 한계는 검색에서 오며, 지금 결여된 것은 기능이 아니라 공개된 운영 증거다.
