AI 에이전트를 오래 사용하다 보니 이상한 문제가 반복됐습니다.
자료는 옵시디언에 쌓이고, 에이전트의 메모리에는 제 선호와 프로젝트 정보가 들어가고, 별도의 스킬에는 작업 절차가 저장됐습니다. 그런데 새 세션을 시작하면 중요한 맥락을 다시 설명해야 했고, 이미 해결한 문제를 같은 방식으로 틀리는 일도 생겼습니다.
지식이 없는 것은 아니었습니다. 오히려 지식이 여러 장소에 너무 많이 있었습니다.
원본 자료와 요약문이 섞여 있었습니다.
사용자 선호와 일반 지식의 경계가 불분명했습니다.
작업 절차 안에 도메인 지식이 함께 들어갔습니다.
성공과 실패를 모두 저장하니 실행 기록이 쌓이기만 했습니다.
결과를 검증하는 기준은 작업할 때마다 다시 만들었습니다.
Claude Code, Codex 등 에이전트마다 같은 규칙을 중복해서 전달했습니다.
이 문제를 해결하기 위해 만든 구조가 AKM, Agent Knowledge Management입니다.
AKM은 특정 앱이나 플러그인, 벡터 데이터베이스의 이름이 아닙니다. 에이전트가 무엇을 읽고, 어디에 저장하고, 어떤 절차로 실행하며, 결과를 어떻게 검증하고, 실패를 어디에 되돌려야 하는지를 정하는 지식 운영 아키텍처입니다.
진행 방법
1. 모든 정보를 한 저장소에 넣지 않았다
처음 한 일은 검색 기능을 만드는 것이 아니라 정보의 역할을 분리하는 것이었습니다.
AKM은 정보를 일곱 개 레이어로 구분합니다.
Source: 문서, 웹페이지, 녹취, 코드와 같은 수정하지 않는 원본
Knowledge: 여러 원본을 읽고 정리한 재사용 가능한 지식
Context: 특정 사용자, 조직, 프로젝트에서만 유효한 맥락
Operational Memory: 매 세션 시작 전에 반드시 알아야 하는 짧은 포인터
Procedure: 반복 작업의 순서, 도구, 실패 지점, 검증 방법
Action: 재현이나 인수인계에 필요한 실행 기록
Evaluation: 실패 패턴, 품질 기준, 감사와 검증 결과
외부에 전달할 결과물은 80-outputs, 더 이상 사용하지 않는 기록은 90-archive에서 관리합니다.
구분 기준은 비교적 단순합니다.
누구에게나 적용되는 내용은 Knowledge
특정 사용자나 프로젝트에서만 참인 내용은 Context
매번 먼저 알아야 하지만 전문을 읽을 필요가 없는 내용은 Memory
반복 실행할 단계와 검증 방법이 있으면 Procedure
같은 실패가 다시 발생할 수 있으면 Evaluation
폴더를 나누는 것보다 중요한 것은 각 레이어가 서로 다른 방식으로 고장 난다는 점이었습니다.
긴 지식을 메모리에 넣으면 모든 세션이 무거워집니다. 도메인 지식을 스킬에 넣으면 지식과 절차를 이중으로 관리하게 됩니다. 모든 실행을 기록하면 로그 쓰레기가 쌓입니다. 평가 레이어가 없으면 같은 실수가 반복됩니다.
그래서 분리해서 저장하고, 링크와 메타데이터로 다시 연결했습니다.
2. 문서가 늘어날수록 메모리는 오히려 줄였다
2026년 7월 22일 기준 개인 AKM 인스턴스에는 약 8,591개의 Markdown 문서가 있습니다.
그중 주요 구성은 다음과 같습니다.
원본 자료: 3,601개
재사용 지식: 3,001개
프로젝트와 사용자 맥락: 768개
반복 절차: 63개
선별된 실행 기록: 488개
평가와 검증 기록: 142개
외부 산출물: 470개
반면 매 세션에 먼저 읽는 40-memory에는 네 개의 문서만 남겼습니다.
처음에는 중요한 내용을 모두 메모리에 넣어야 에이전트가 똑똑해진다고 생각했습니다. 실제로는 반대였습니다. 긴 내용을 매번 읽히는 것보다, 어디에 무엇이 있는지를 알려주는 짧은 포인터가 더 유용했습니다.
현재는 세션을 시작할 때 전체 지식을 읽지 않습니다.
시스템 INDEX를 읽습니다.
네 개의 공통 메모리 포인터를 읽습니다.
현재 작업과 관련된 Knowledge, Context, Procedure만 추가로 찾습니다.
중요한 주장은 원문을 직접 확인합니다.
메모리는 지식 창고가 아니라 탐색을 시작하기 위한 작은 지도에 가까워졌습니다.
3. 저장보다 운영 루프를 먼저 정했다
AKM의 운영 흐름은 다음과 같습니다.
Ingest → Classify → Compile → Contextualize → Execute → Verify → Learn Back
먼저 새 자료를 인입하고, 어떤 레이어에 속하는지 분류합니다. 원본은 보존하고, 여러 원본에서 재사용 가능한 지식을 만듭니다. 그 지식을 현재 프로젝트와 연결한 뒤 실제 작업에 사용합니다.
결과가 나오면 끝내지 않고 검증합니다. 실패하면 해당 실패의 원인을 만든 레이어를 수정합니다. 이 마지막 과정을 Learn Back이라고 부릅니다.
예를 들면 다음과 같습니다.
같은 실수가 세션마다 반복되면 Memory에 예방 포인터를 추가합니다.
절차를 그대로 따랐는데 결과가 틀리면 Procedure의 검증 단계를 수정합니다.
사용자의 의도를 잘못 이해했다면 Context를 수정합니다.
오래된 지식을 사용했다면 Knowledge의 신뢰도를 낮추거나 교체합니다.
완료했다고 보고했지만 검증하지 않았다면 Evaluation에 새로운 검증 기준을 만듭니다.
지식만 쌓고 실행하지 않으면 위키에 머뭅니다. 실행만 반복하고 검증하지 않으면 자동화에 머뭅니다. 실패를 다음 실행의 입력 품질 개선으로 되돌리는 것이 AKM에서 가장 중요한 부분이었습니다.
4. 실제 글 하나도 여러 종류의 기록으로 분리했다
최근 Cerebras의 조직 지식베이스 사례를 정리할 때도 같은 방식을 사용했습니다.
먼저 Cerebras의 원문을 Source로 보존했습니다. 원문에서 확인한 구현 방식과 공개되지 않은 정보를 구분해 읽기 노트를 만들었습니 다. Cerebras의 방법 중 AKM에 적용할 부분은 별도의 통합 판단 문서로 분리했습니다.
마지막으로 외부 독자를 위한 지피터스 사례글을 Output으로 만들었습니다.
이렇게 나누면 원문이 수정된 요약문으로 덮이지 않습니다. Cerebras가 실제로 공개한 내용과 제가 AKM에 적용하며 추가한 판단도 섞이지 않습니다. 나중에 다른 글이나 강의자료를 만들 때는 필요한 레이어만 다시 사용할 수 있습니다.
5. 검색 결과를 바로 근거로 사용하지 않았다
문서가 늘면서 검색 구조도 필요해졌습니다. 현재는 파일명과 정확한 용어 검색, qmd 기반 검색, 관계 탐색, 직접 읽기를 구분해 사용하고 있습니다.
여기서 정한 원칙은 검색 결과와 근거를 구분하는 것입니다.
검색 결과에 나타난 문서는 아직 후보일 뿐입니다. 중요한 사실을 외부에 사용할 때는 해당 문서와 위치를 직접 읽어야 합니다. 직접 읽었다고 해서 문서 전체가 모든 주장을 뒷받침하는 것도 아닙니다. 어떤 문장이 어떤 주장을 지원하는지 범위를 좁혀야 합니다.
그래서 AKM의 근거 구조에서는 상태를 다음과 같이 나눕니다.
Candidate: 검색에서 찾았지만 아직 직접 읽지 않은 자료
Direct Read: 해당 위치를 실제로 읽은 자료
Claim Supported: 특정 주장을 지원한다고 확인한 자료
Conflicted: 다른 근거와 충돌하는 자료
Stale: 현재 기준에서 오래되었거나 대체된 자료
관련성이 높다고 검색된 문서가 반드시 최신이거나 권위 있는 문서는 아닙니다. 검색 점수보다 프로젝트 범위와 출처의 권위를 먼저 확인하고, 최신성은 같은 조건 안에서 비교하도록 했습니다.
6. 여러 에이전트가 같은 본문을 사용하게 했다
에이전트마다 별도의 기억 시스템이 있습니다. 이를 모두 AKM으로 교체하려고 하면 오히려 복잡해집니다.
그래서 각 에이전트의 기본 메모리는 그대로 두고 AKM을 연결하는 얇은 어댑터를 만들었습니다.
각 어댑터는 네 가지 질문에만 답합니다.
AKM 루트는 어디인가?
세션 시작 시 무엇을 읽는가?
새 정보를 저장할 때 어떤 라우팅 규칙을 따르는가?
실패했을 때 어떤 Learn Back 절차를 사용하는가?
공통 지식과 운영 규칙의 본문은 AKM에 한 번만 둡니다. Claude Code, Codex 등 각 에이전트의 메모리에는 AKM을 찾아가는 포인터만 둡니다.
결과와 배운 점
현재 결과
AKM은 아직 완성된 제품이 아닙니다. 다만 개인 업무에서 실제로 사용하는 지식 운영 인스턴스는 만들어졌습니다.
가장 크게 달라진 점은 지식을 많이 저장한 것이 아니라, 새로운 정보와 실패를 어디에 둘지 판단할 기준이 생긴 것입니다.
원본과 해석을 구분할 수 있게 됐습니다.
일반 지식과 프로젝트 맥락이 섞이지 않게 됐습니다.
반복 작업만 절차로 승격하게 됐습니다.
성공 로그를 무조건 쌓지 않게 됐습니다.
실패를 삭제하지 않고 다음 실행을 수정하는 자료로 사용하게 됐습니다.
여러 에이전트가 같은 지식과 운영 규칙을 참조할 수 있게 됐습니다.
8,591개의 문서를 운영하면서도 매 세션에 먼저 읽는 메모리를 네 개로 제한한 것이 현재 구조를 가장 잘 보여주는 결과라고 생각합니다.
배운 점 1. 지식의 양보다 역할 분리가 먼저였다
처음에는 더 좋은 검색과 더 큰 컨텍스트가 필요하다고 생각했습니다. 실제로는 검색 전에 원본, 지식, 맥락, 절차, 평가를 구분하는 일이 먼저였습니다.
구분되지 않은 자료를 벡터 검색에 넣으면 더 빨리 찾을 수는 있어도, 어떤 자료를 신뢰하고 실행에 사용해야 하는지는 여전히 판단하기 어렵습니다.
배운 점 2. 에이전트 메모리는 작아야 했다
에이전트가 모든 내용을 기억해야 한다는 생각을 버렸습니다.
메모리에는 매번 알아야 할 짧은 운영 규칙만 두고, 긴 지식은 필요할 때 검색하게 하는 편이 효율적이었습니다. 중요한 것은 많이 기억하는 것이 아니라 필요한 자료를 올바른 순서로 찾는 것입니다.
배운 점 3. 실패를 저장하는 것만으로는 부족했다
실패 기록을 남겨도 다음 작업이 그 기록을 읽지 않으면 아무 변화가 없습니다.
반복 실수는 Memory, 잘못된 절차는 Procedure, 오래된 사실은 Knowledge, 잘못 이해한 선호는 Context로 되돌려야 했습니다. 실패가 어느 레이어를 수정했는지까지 연결해야 다음 실행이 실제로 달라졌습니다.
배운 점 4. 상세한 근거가 항상 좋은 컨텍스트는 아니었다
근거 검색 파일럿에서는 출처, 권위, 직접 읽기, 충돌 여부를 상세히 기록했습니다. 안전성과 정확성 확인에는 도움이 됐지만, 모델에 전달되는 문맥의 중앙값이 887토큰에서 10,172.5토큰으로 증가했습니다.
감사용 근거 패킷과 모델이 답변 생성에 사용하는 압축 패킷을 분리해야 한다는 것을 배웠습니다. 검증 가능 성을 높이기 위해 모든 정보를 모델 입력에 넣으면 오히려 효율이 크게 떨어질 수 있습니다.
다른 조직에서 작게 시작한다면
처음부터 일곱 개 레이어와 수천 개의 문서를 만들 필요는 없습니다.
반복 질문이 많은 업무 하나를 고르고 다음과 같이 시작할 수 있습니다.
비민감 원본 문서 10~20개를 Source에 넣습니다.
반복해서 사용할 개념과 답변을 Knowledge로 정리합니다.
담당자, 적용 범위, 검토일을 Context에 기록합니다.
실제 질문 10개로 검색과 답변을 시험합니다.
답변마다 원본 링크와 인용을 요구합니다.
틀린 답이 나오면 실패 원인에 따라 Knowledge, Context, Procedure 중 하나를 수정합니다.
같은 실패가 다시 발생하는지 확인합니다.
이 과정이 반복되면 그때 검색 인덱스, 벡터 검색, 권한 관리와 자동화를 추가해도 늦지 않습니다.
AKM을 만들며 얻은 가장 큰 교훈은 다음과 같습니다.
에이전트 지식관리는 정보를 많이 저장하는 일이 아니라, 다음 실행이 이전 실행보다 나아지도록 지식과 실패를 제자리로 돌려놓는 일이다.
