본문으로 건너뛰기

DECK님의 AKM을 따라 해봤습니다

Knock

2026.07.24

AKM 지식관리 시스템 소개

이 글은 DECK님이 만든 오픈소스 지식관리 프레임워크 AKM(Agent Knowledge Management)을 그대로 클론해서, 실제 프로젝트(외식업 B2B 커머스 시장 조사)에 이틀간 돌려본 기록입니다.

AKM은 "AI 에이전트가 지식을 어디에 저장하고, 언제 실행하고, 어떻게 검증하고, 실패를 어디로 되돌릴지"까지 규칙으로 정해둔 순수 마크다운 기반 시스템입니다. DB도, 서버도 필요 없고 Claude Code 같은 에이전트가 파일을 읽고 쓰는 것만으로 작동합니다. 이론으로는 그럴듯해 보이는 구조인데, 실제로 써봐도 그렇게 굴러가는지 궁금해서 시작했습니다.

AKM의 작동 원리

7개 레이어로 구성된 저장 공간

AKM은 모든 걸 한 곳에 쌓지 않고, 성격에 따라 7개 레이어로 나눠 저장합니다.

레이어

폴더

기준

Source

10-sources/

원본 보존, 절대 수정 안 함

Knowledge

20-knowledge/

누구에게나 참인 재사용 지식

Context

30-context/

이 사용자·프로젝트에서만 참인 것

Operational Memory

40-memory/

매 세션 먼저 알아야 할 짧은 포인터

Procedural

50-procedures/

반복 실행하는 절차

Action

60-actions/

재현·검증·인수인계에 필요한 기록만

Evaluation

70-evaluation/

실패 패턴과 품질 기준 — 실패가 학습이 되는 곳

이 7개 레이어는 "언제 읽는가"를 기준으로 다시 3개 저장소로 묶입니다.

  • Memory — 매 세션 항상 로드하는 짧은 포인터

  • Brain — 작업할 때 읽는 것: 절차·결정·실패 패턴

  • Vault — 지식이 필요할 때만 읽는 것: 원본·지식·맥락·산출물

레이어가 "무엇을 어디에 저장하는가"라면, 저장소는 "언제 그걸 읽는가"를 정하는 것입니다.

자료 저장 원칙 (ROUTER)

새로운 자료나 경험이 들어오면, AKM은 아래 4가지 원칙에 따라 저장할 레이어를 정합니다.

  • Memory(40): 짧고, 안정적이고, 반복적으로 필요하고, 포인터만으로 충분할 때만

  • Knowledge(20): 다시 읽을 가치가 있거나, 여러 프로젝트에서 재사용되거나, 도메인 지식일 때

  • Procedure(50): 반복 실행되고, 절차가 있고, 실패 지점과 검증 방법이 있을 때

  • Evaluation(70): 같은 실패가 재발할 수 있거나, 품질 기준이 필요할 때

이 기준으로도 분류가 안 되면 "시스템 규칙(ROUTER)이 미완성이다"라고 보고, 규칙 자체를 고치는 게 원칙입니다.

7단계 운영 루프

AKM의 핵심은 지식을 쌓는 것에서 끝나지 않고, 아래 7단계를 반복하는 것입니다.

Open optionstext

1. Ingest(원본 수집) → 2. Classify(분류) → 3. Compile(지식화) → 4. Contextualize(맥락 연결)
→ 5. Execute(실행) → 6. Verify(검증) → 7. Learn Back(학습 환원)
                                              │
                    ┌─────────────────────────┘
                    ▼
        (고쳐진 레이어가 다음 루프의 입력 품질을 높인다)

여기서 중요한 건 마지막 두 단계입니다. Verify(검증) 없이 Learn Back(학습 환원)은 불가능하고, Learn Back이 없으면 그냥 위키일 뿐 AKM이 아니라는 것입니다. 지식만 쌓고 실행·검증·환원을 안 하면 자동화이지 지식관리가 아니라는 게 이 시스템의 전제입니다.

검증 단계의 중요성

모든 결과물을 똑같은 강도로 검증하지 않습니다. 일회성 답변은 가볍게(Tier 0), 여러 프로젝트에서 재사용되거나 외부에 공유되는 지식은 Tier 1 이상으로 올라가며, 요청 충족도·분석 타당성·정보 무결성 등 7개 기준으로 원문과 대조 검증합니다. 검증에서 실패가 나오면 그걸로 끝나는 게 아니라, 그 실패를 다시 책임 레이어로 돌려보내(Learn Back) 같은 실수가 재발하지 않게 합니다.

AKM 적용 사례

1일차 — 개념 확인 및 파일럿 테스트

먼저 AKM 개념과 위 매커니즘을 확인한 뒤, 사람이 반드시 개입해야 하는 6개 지점(예: Context에 들어가는 사실 확인, 검증 실패, 핵심 규칙 변경 등)을 먼저 정해두고 시작했습니다.

시스템을 한 번 가상으로 돌려보는 파일럿 과정에서 "특정 기능의 사용 횟수를 세는 장치가 없다"는 구멍을 하나 발견했는데, 이게 바로 Learn Back의 첫 사례였습니다. 코어 규칙을 바로 고치는 대신, 사례가 더 쌓일 때까지 가벼운 카운터만 추가해두는 쪽을 택했습니다.

이후 KREI(한국농촌경제연구원)와 삼정KPMG의 외식·이커머스 시장 보고서 5건을 순서대로 Ingest(원본 보존)→Compile(지식 노트화)했고, 마침 진행 중이던 외식업 B2B 커머스 프로덕트에 이 지식들을 Contextualize(연결)했습니다. 이 과정에서 "PDF를 표로 옮길 때 하위 섹션이 빠지는" 실패 패턴을 처음 발견해 별도로 기록해뒀는데, 이게 다음 날 결정적인 역할을 하게 됩니다.

마지막으로 매주 새 보고서를 자동으로 찾아오는 절차(Procedure)를 설계하고, macOS의 백그라운드 스케줄러(launchd)에 등록하는 명령어까지 만들었습니다.

2일차 — 검증 및 외부 자료 통합

2일차는 그동안 밀려 있던 Verify 단계를 본격적으로 돌린 날이었습니다. "아직 검증 안 함" 딱지가 붙은 노트 9개 중 실제 검증이 필요한 5개를 골라, 서브에이전트 5개를 동시에 띄워 각 노트를 원문과 병렬로 대조했습니다.

이 과정에서 1일차에 발견했던 "PDF 하위 섹션 누락" 실패 패턴이 3번째로 재발한 걸 잡아냈습니다. 처음엔 "이 주장은 원문에 없다"고 보류 처리됐던 문장이, 원본 PDF를 다시 렌더링해 직접 대조해보니 실제로는 원문에 있었고 최초 전사 때 통째로 빠졌던 것으로 확인됐습니다. 단순히 이번 건만 고친 게 아니라, 실패 패턴 기록에 "레이아웃이 분리된 박스가 특히 취약하다"는 하위 유형을 추가해 Learn Back을 완성했습니다.

같은 날, 지식 노트에 그럴듯하게 남아있던 미결 가설 하나도 실제 데이터로 직접 검증했는데, 예상과 반대되는 결과가 나와 가설 자체가 반증됐습니다. 검증(Verify) 단계가 없었다면 그냥 넘어갔을 오류입니다.

이후 사용자가 직접 등록한 launchd 자동화가 실제로 목록에 잡히는 걸 확인해 절차 노트를 마무리했고, 다른 GitHub 저장소에 이미 모아둔 주간 동향 리포트와 원본 자료 7건을 같은 Ingest→Compile 절차로 편입시켜 국내·해외 B2B 경쟁사 지형 노트와 경쟁축 이동 패턴 노트를 새로 만들었습니다.

향후 계획

이렇게 맛보기로 만들어봤으니, 이제 본격적인 LLM Wiki를 깨끗하게 새로 구성할 계획입니다.

5

함께 이야기해요 5

로그인하고 댓글을 남겨 주세요

_묘랑 프로필 이미지
_묘랑2026.07.30

1일차에 발견한 실패 패턴이 2일차에 3번째로 재발하는 걸 잡아내고, 거기서 멈추지 않고 하위 유형까지 추가해 Learn Back을 닫으신 흐름이 교과서 같습니다. 사람이 개입할 6개 지점을 시작 전에 먼저 정해두신 것도 그대로 따라 하고 싶습니다.

강군 프로필 이미지
강군2026.07.29

아하, 처음에 작은 규모의 데이터로 우선 검증과 테스트를 충분히 거치고 하는 것도 중요할 것 같네요. 처음부터 왕창 해버린 저... 사례 글 감사합니다.^^

유피테르 프로필 이미지
유피테르2026.07.29

레이어를 단순히 폴더로 나누는 데 그치지 않고, 무엇을 저장하느냐와 언제 읽느냐를 Memory·Brain·Vault로 다시 구분하신 설계가 특히 인상적이었습니다. KREI와 삼정KPMG 보고서 5건을 실제 외식업 B2B 커머스 프로젝트의 맥락으로 연결하고, 이후 주간 동향 자료 7건까지 같은 흐름으로 편입하신 과정에서 AKM을 현실적인 업무 시스템으로 검증하신 점이 잘 느껴졌어요.

DECK 프로필 이미지
DECK2026.07.25

Knock님, 직접 클론하는 데서 끝내지 않고 이틀 동안 실제 프로젝트에 돌려보신 기록이라 정말 반갑게 읽었습니다.

특히 인상 깊었던 부분은 코어 규칙을 바로 고치지 않고 카운터로 사례를 더 모으신 판단, 그리고 PDF 하위 섹션 누락이 세 번째 재발했을 때 원본을 다시 렌더링해 원인을 “분리된 레이아웃 박스”까지 좁힌 과정입니다. 한 건의 결과물만 수정한 것이 아니라 실패 패턴과 검증 방법을 함께 고쳤다는 점에서, 제가 생각한 Learn Back이 정확히 작동한 사례라고 봅니다. 기존 가설이 실제 데이터로 반증된 것까지 포함해 Verify 레이어의 필요성도 잘 보여주셨고요.

뽀짝이 프로필 이미지
뽀짝이2026.07.24

이틀이라는 짧은 시간 안에 개념 파악부터 launchd 자동화 등록까지 실제로 돌려보신 게 인상적이에요.

특히 2일차에 "PDF 하위 섹션 누락" 실패 패턴이 3번째 재발한 걸 서브에이전트 병렬 검증으로 잡아내신 부분이 와닿았어요. 단순히 "이번 건 고쳤다"로 끝내지 않고 "레이아웃이 분리된 박스가 특히 취약하다"는 하위 유형까지 Evaluation 레이어에 남기신 것 — 그게 AKM이 일반 위키와 다른 지점이라고 쓰신 그 장면이 글 전체에서 제일 설득력 있었어요.

Learn Back 없이 지식만 쌓으면 자동화지 지식관리가 아니라는 전제가, 이틀짜리 실험을 통해 실제로 증명된 거네요. LLM Wiki 본격 구성이 기대됩니다 🐈‍⬛

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기