개선 루프: akm이 에이전트를 예리하게 유지하는 방법

이 글은 AI 코딩 에이전트가 의존하는 점점 늘어나는 기술, 스크립트 및 컨텍스트(Context) 뭉치를 관리하는 시리즈의 열 번째 파트입니다. 아홉 번째 파트에서는 워크플로우 자산(Workflow assets), 볼트 자산(Vault assets), 그리고 쓰기 가능한 git stash를 다루었습니다. 여덟 번째 파트에서는 구조화된 연구를 위한 멀티 위키(Multi-wiki) 지원을 다루었습니다. 이전 파트들에서는 팀, 분산된 stash, 피드백 점수 산정, 그리고 커뮤니티 지식을 다루었습니다.

이번 파트는 엔트로피(Entropy)에 관한 것입니다.

당신은 기능을 배포합니다. 에이전트는 세션 동안 부분적인 발견 사항, 임시 해결책(Workaround), 계속 실패했던 빌드 단계에 대한 노트 등 여러 메모리를 작성합니다. 이러한 메모리들은 작성될 당시에는 정확합니다. 세 번의 스프린트(Sprint)가 지난 후, 임시 해결책은 더 이상 필요하지 않게 되고, 두 개의 메모리는 동일한 서브시스템에 대해 약간씩 다른 내용을 말하며, 빌드 단계에 대한 노트는 교체된 CI 설정(CI config)을 참조하게 됩니다. 이 중 어느 것도 재앙적인 수준은 아닙니다. 하지만 이것이 축적됩니다. 6개월이 지나면 당신의 stash 중 상당 부분이 오래되거나, 중복되거나, 조용히 틀린 상태가 됩니다.

수동으로 감사(Audit)할 수도 있습니다. 하지만 실제로 그렇게 하지는 않을 것입니다. stash는 너무 방대하며, 특정 메모리의 관련성은 그것이 생성된 컨텍스트(Context) 없이는 평가하기 어렵고, 판단(이 두 개를 병합할 것인가? 이것을 승격할 것인가? 저것을 삭제할 것인가?)은 인간에게는 지루하지만 LLM(Large Language Model)에게는 다룰 만한 바로 그런 종류의 작업이기 때문입니다.

akm improve가 바로 그 문제에 대한 해답입니다. 이것은 stash를 읽고, 자산의 품질을 평가하며, 흩어진 메모리를 통합하고, 구조화된 사실을 추출하며, 엔티티(Entity) 관계를 매핑하는 다단계 파이프라인입니다. 이는 수동 개입 없이 정해진 일정에 따라 실행되며, 무언가가 변경되기 전에 당신이 검토할 수 있는 제안(Proposals)을 생성합니다.

5단계

akm improve는 단 한 번의 LLM 호출이 아닙니다. 각 단계가 다음 단계의 입력값을 생성하는 순차적인 파이프라인입니다.

Reflect는 자산(asset)의 품질을 평가합니다. 범위 내의 각 자산에 대해, reflect 단계는 사용 신호(usage signals) — 검색 히트(search hits), 검색 횟수(retrieval counts), 피드백(feedback) — 를 기준으로 콘텐츠를 검토하고 품질 평가를 생성합니다. 품질이 낮은 자산은 개선 후보로 표시됩니다. 0.8.0 버전부터 reflect는 에이전트 서브프로세스(agent subprocess)를 생성하는 대신 직접적인 LLM HTTP 호출로 실행될 수 있으며, 이를 통해 호출당 지연 시간(latency)을 약 30초에서 약 6~10초로 단축했습니다:

Reflect 모드	호출당 시간	69-ref 실행 시간
agent (CLI 서브프로세스)	~30초	~35분
...

Distill은 reflect에서 얻은 관찰(observations)을 교훈 제안(lesson proposals)으로 변환합니다. reflect가 "이 기술은 불완전하며 만족도가 낮은 상태로 자주 검색됩니다"라고 말하면, distill은 개선 초안 — 기술의 새로운 버전, 보충 교훈, 또는 폐기 제안(deprecation proposal) — 을 생성합니다. 이러한 제안들은 대기열(queue)에 들어가며, 사용자가 이를 승인하기 전까지는 스태시(stash)에 아무것도 기록되지 않습니다.

Consolidate는 메모리 풀(memory pool)을 전문적으로 처리합니다. 메모리 풀에는 에이전트 세션으로부터의 항목들 — akm remember 호출, 자동 캡처된 관찰(observations), 그리고 태스크 에이전트 출력물 — 이 축적됩니다. Consolidation은 관련된 메모리들을 청크(chunks)로 그룹화하고, 각 청크를 LLM에 보내 큐레이션 계획(유사 중복 항목 병합, 고신호(high-signal) 항목 승격, 중복 항목 삭제, 모순 사항 노출)을 수립한 뒤, 해당 계획을 실행합니다. 그 결과로 더 작고 깨끗한 메모리 풀과 새로운 스태시 승격(stash promotions)이 이루어집니다.

Memory inference는 consolidation 이후에 실행됩니다. 이는 consolidation 이후의 상태를 가져와 가벼운 사실 추출(factual extraction) 단계를 수행하며, 명시적인 메모리 항목으로 들어가지 못한 원자적 사실(atomic facts)들을 뽑아냅니다. 이들은 추가적인 승격 후보가 됩니다. 안정적인 운영 상태에서 memory inference는 매 패스마다 약 60~70% (최근 24시간 윈도우 기준 69.3%)의 사용 가능한 원자적 사실을 산출합니다.

**Graph extraction (그래프 추출)**은 개선(improve)이 완료된 최종 상태를 대상으로 마지막에 실행됩니다. 이는 akm graph 명령어를 구동하는 엔티티-관계(entity-relation) 인덱스를 구축합니다. 이 인덱스를 통해 특정 엔티티가 언급된 stash 항목, 함께 등장하는 엔티티들, 그리고 엔티티를 전혀 생성하지 않은 자산(akm graph orphans를 통한 품질 분류(quality-triage) 대상) 등을 확인할 수 있습니다. 0.8.0 버전부터 추출은 증분(incremental) 방식으로 이루어집니다. 즉, 개선(improve) 실행 과정에서 변경된 자산만 다시 추출되며, 기본적으로 4개씩 배치(batch) 단위로 병렬 실행됩니다.

각 단계는 프로필(profile)별로 독립적으로 활성화하거나 비활성화할 수 있습니다. quick 프로필은 reflect 단계만 실행합니다. memory-focus 프로필은 reflect와 더불어 memory 및 lesson 타입에 대한 memory inference를 실행합니다. thorough 프로필은 5개 단계를 모두 실행하며, 그 결과를 git 기반의 stash에 자동으로 동기화합니다.

루프 실행하기 (Running the Loop)

기본 호출 방식:

akm improve

이 명령은 사용자의 기본 improve 프로필 범위 내에서 전체 stash에 대해 활성화된 모든 단계를 실행합니다. 처음 실행하기 전에는 --dry-run을 사용하여 아무것도 기록하지 않고 무엇이 처리될지 미리 확인할 수 있습니다:

akm improve --dry-run

dry-run 출력 결과에는 어떤 자산이 어떤 순서로 선택되는지, 그리고 어떤 단계가 실행될지가 표시됩니다. dry-run 경로에서는 state.db에 아무것도 기록되지 않습니다. improve 결과에 .dryRun: true 플래그가 지정되며 건강 지표(health metrics)에서도 제외됩니다.

특정 자산 타입으로 범위를 제한하려면:

akm improve memory          # memory pool만 대상
akm improve skill           # skills만 대상
akm improve skill:deploy    # 특정 자산 하나만 대상

실행 시 추가적인 가이드를 제공하려면(특정 집중 영역이 관련 있다고 판단될 때 유용합니다):

akm improve --task "focus on deduplication in the build tooling notes"

처리할 자산의 수를 제한하려면(기본적으로 효용성이 가장 높은 것부터 처리):

akm improve --limit 20

자산 선택 순서는 다음과 같습니다: 최근 피드백 신호(feedback signals)가 있는 자산이 우선이며, 그다음은 피드백은 없지만 검색 횟수(retrieval-count)가 높은 자산, 마지막으로 그 외의 모든 자산 순입니다. --require-feedback-signal을 사용하면 명시적인 피드백을 받은 자산으로만 범위를 제한하고 검색 폴백(retrieval fallback) 과정을 완전히 건너뛸 수 있습니다.

프로필 (Profiles)

프로필은 어떤 단계(phases)를 실행할지, 어떤 LLM 연결을 사용할지, 실행 종료 시 자동 동기화(auto-sync)를 수행할지, 그리고 제안(proposals)을 자동으로 수락하기 위한 신뢰도 임계값(confidence threshold)을 제어합니다. 내장된 프로필은 다음과 같습니다:

프로필	단계 (Phases)	자동 동기화 (Auto-sync)	자동 푸시 (Auto-push)
default	5개 단계 모두	예	예
...

단일 실행에 대해 덮어쓰려면 --profile을 전달하세요:

akm improve --profile quick
akm improve --profile memory-focus

설정 파일의 profiles.improve.<name> 아래에 사용자 정의 프로필을 정의할 수 있습니다. 프로필 내의 각 프로세스 항목은 통일된 {mode, profile, timeoutMs, options} 형식을 사용하므로, 반사(reflect) 단계에는 빠른 로컬 모델을 지정하고 통합(consolidation) 단계에는 더 유능한 모델을 지정하는 식의 구성이 가능합니다:

{
  "configVersion": "0.8.0",
  "profiles": {
...

제안 큐 (The Proposal Queue)

akm improve가 생성하는 모든 개선 사항은 저장소(stash)에 반영되기 전에 제안 큐(proposal queue)를 거칩니다. 아무것도 직접적으로 기록되지 않습니다. 큐는 안전 계층(safety layer) 역할을 합니다.

실행 후 생성된 내용을 검토하세요:

akm proposal list
akm proposal list --status pending

특정 제안을 조사합니다:

akm proposal show <id>
akm proposal diff <id>       # 라이브 자산(live asset)과 나란히 비교(side-by-side diff)

수락 또는 거절:

akm proposal accept <id>
akm proposal reject <id> --reason "duplicates the deployment-gotchas lesson"

akm proposal accept는 저장소에 무엇인가를 쓰기 전에 전체 스키마 검증(schema validation)을 실행합니다. 수락된 제안은 일반적인 저장소 자산으로 승격되며 즉시 검색이 가능해집니다.

--auto-accept 플래그를 사용하면 신뢰도 임계값(confidence-threshold) 기반의 자동 승격(auto-promotion)을 활성화할 수 있습니다. 기본 안전 임계값은 90입니다. LLM이 스스로의 신뢰도를 90점 이상으로 평가한 제안은 자동으로 승격되며, 그 미만의 모든 항목은 수동 검토를 위해 대기열(queue)로 이동합니다.

akm improve --auto-accept=90     # 명시적 임계값 설정 (기본값과 동일)
akm improve --auto-accept=false  # 자동 승격 비활성화, 모든 항목을 대기열로 전송

새로운 스태시(stash)에 대해 처음 몇 번 실행할 때는 자동 승격을 비활성화하고 대기열을 수동으로 검토하십시오. 파이프라인이 생성하는 결과물이 무엇인지 감을 잡게 되면, 임계값을 점진적으로 높일 수 있습니다.

스케줄링 (Scheduling)

akm improve를 한 번 실행하는 것도 유용하지만, 이를 지속적으로 실행할 때 복리 효과(compounding)가 시작됩니다.

이 파이프라인은 cron 스케줄에 따라 실행되도록 설계되었습니다. 프로덕션 환경에서는 30분마다 실행하는 것이 일반적인 주기입니다. 이는 통합(consolidation) LLM 호출이 완료되기에 충분한 시간이면서, 특정 세션의 메모리가 한 시간 이내에 큐레이션될 수 있을 만큼 충분히 짧은 시간입니다.

스케줄링을 위해 태스크 자산(task asset)을 정의하십시오:

# ~/akm/tasks/improve-loop.yml
name: improve-loop
trigger:
...

태스크를 등록하십시오:

akm tasks sync

등록 후에는 akm improve가 수동 개입 없이 30분마다 실행됩니다. --limit 30 제한을 통해 각 실행이 예측 가능한 범위 내에서 유지됩니다. 개선할 가치가 있는 내용(새로운 피드백, 검색 결과는 높지만 피드백이 없는 자산 등)이 없다면, 실행은 선택 후 빠르게 완료되며 생성된 제안은 없습니다.

git 기반 스태시의 경우, default 및 thorough 프로필은 각 실행이 끝날 때 자동으로 커밋(auto-commit)합니다. 커밋 메시지 템플릿은 설정 가능합니다:

"sync": { "message": "akm improve {scope} — {refs} refs ({date})" }

특정 실행에 대해 커밋을 억제하려면 --no-sync를 사용하고, 푸시(push) 없이 로컬에만 커밋하려면 --no-push를 사용하십시오.

루프가 작동하고 있는지 확인하기

akm health를 사용하면 SQLite를 직접 쿼리하지 않고도 최근 개선(improve) 활동에 대한 구조화된 뷰를 확인할 수 있습니다:

akm health --since 24h
akm health --since 4h --format text

출력 결과에는 실행 횟수(run counts), 건너뛰기 사유 분석(skip reason breakdowns), 통합 결과(consolidation outcomes), 메모리 추론 수율(memory inference yield), 그리고 단계별 지연 시간(phase latencies)이 포함됩니다. 만약 실행이 드라이 런(dry-run)이었다면, 건강 지표(health metrics)에서 자동으로 제외됩니다.

중요한 스태시(stash) 변경이 발생한 후에는 akm health를 실행하는 것이 파이프라인이 잠긴 저널(locked journal)이나 오래된 데이터베이스 항목(stale database entry)에 조용히 멈춰있는 대신, 건강한 상태인지 확인할 수 있는 가장 빠른 방법입니다.

시간이 흐름에 따라 변화하는 것

개선 루프(improve loop)의 가치는 단일 실행에 있는 것이 아니라, 축적되는 것에 있습니다.

활성 스태시(active stash)에서 30분 주기로 일주일간 실행하면, 메모리 풀(memory pool)은 더 작아지고 더 일관성 있게 변합니다. 관련 세션에서 발생한 중복 메모리들은 병합되었습니다. 신호가 높은 관찰값(high-signal observations)은 에이전트가 직접 참조할 수 있는 이름이 지정된 스태시 항목(named stash entries)으로 승격되었습니다. 그래프 추출 인덱스(graph extraction index)는 점진적으로 구축되어, akm graph entity <name> 명령이 아무것도 반환하지 않는 대신 유용한 결과를 반환하게 됩니다.

한 달이 지나면, 스태시는 무언가를 처음 캡처했을 때의 가공되지 않은 노트가 아니라 당신의 실제 작업 패턴을 반영하게 됩니다. 빈번하게 검색되었으나 평점이 낮았던 자산(assets)들은 플래그(flagged)가 지정되고 개선되었습니다. 한 번도 검색되지 않은 자산들은 삭제 또는 통합 후보로 떠오릅니다. 당신이 보유한 메모리는 6개월 전에 작성한 내용이 아니라, 지금 당신이 알고 있는 내용에 정확히 부합합니다.

이것이 바로 루프입니다. 당신이 일하는 동안에도 실행됩니다. 당신이 잠든 동안에도 실행됩니다. 매 회차를 거칠 때마다 스태시는 조금 더 정확해지고, 조금 더 통합되며, 조금 더 유용해집니다. 루프가 생성하는 제안(proposals)들은 눈에 보이는 표면, 즉 파이프라인이 결정한 내용을 확인하고 이를 재정의(override)할 수 있는 대기열(queue)입니다. 그 밑바탕에 깔린 스태시 품질의 향상이 바로 복리로 쌓이는 핵심입니다.

akm improve는 akm 0.8.x의 일부입니다. 전체 파이프라인 설정(pipeline configuration) 참조는 docs/configuration.md에서 확인할 수 있습니다. 프로필 옵션(Profile options), LLM 연결 설정(LLM connection setup), 그리고 스케줄링(scheduling) 상세 내용은 개선 루프 기능 문서(improvement loop feature doc)에 있습니다. 24시간 자율 운영(autonomous operation)에 대한 구체적인 내용 — 하드웨어 벤치마크(hardware benchmarks), 연속 실행을 가능하게 하는 두 가지 신뢰성 수정 사항(reliability fixes), 그리고 Discord 상태 보고(health report) 설정 — 은 Your Agent Has a Memory That Runs While You Sleep를 참조하십시오. 저장소(repo)는 github.com/itlackey/akm에 있습니다.