AI 에이전트(AI agents)와 작업하는 모든 개발자가 결국 맞닥뜨리게 되는 문제가 하나 있습니다. 바로 AI가 당신을 기억하지 못한다는 것입니다.

매 세션이 시작될 때마다 당신의 기술 스택, 선호도, 지난주에 발견한 제약 사항, 그리고 거의 두 번이나 저지를 뻔했던 실수 등을 다시 설명하는 데 20분을 소비합니다. 당신은 이 과정을 반드시 거쳐야 한다는 것을 알고 있습니다. AI는 당신의 지난 대화를 전혀 기억하지 못합니다. 매 세션마다, AI는 완전히 새로 시작합니다.

이것이 AI 에이전트와 작업할 때 발생하는 가장 큰 숨겨진 비용입니다. 이는 환각(hallucinations)이나 오답의 문제가 아닙니다. 그런 것들은 디버깅(debug)할 수 있는 가시적인 실패입니다. 더 큰 비용은 보이지 않는 오버헤드(overhead)입니다. 즉, 매번 수행해야 하는 컨텍스트 구축(context-building), 다시 배워야 하는 교훈들, 무시되는 선호도, 그리고 AI가 그것이 실수였다는 것을 몰랐기 때문에 반복되는 실수들입니다.

LearnBoard는 이 문제를 해결하기 위해 제가 만든 도구입니다.

핵심 아이디어: 파일 형태의 구조화된 메모리 (structured memory)

이를 가능하게 만든 통찰은 간단합니다. 만약 AI가 무언가를 지속적으로 기억하게 하고 싶다면, 세션 시작 시 AI가 읽을 수 있는 파일에 그 내용을 담으면 됩니다.

이것은 새로운 아이디어가 아닙니다. CLAUDE.md도 이런 방식으로 작동합니다. 많은 생산성 워크플로우(productivity workflows)가 이런 방식을 사용합니다. 하지만 문제는 항상 _관리 계층(management layer)_에 있었습니다. 메모리에 무엇이 들어있는지 확인하거나, 검색하거나, 혹은 원시 텍스트 에디터(raw text editor)를 열어 스키마(schema)를 이해하기를 기도하지 않고 편집할 수 있는 방법이 없었습니다.

LearnBoard는 LEARNING.md라고 불리는 구조화된 메모리 파일을 위한 관리 인터페이스입니다. AI가 당신에 대해 학습한 모든 것 — 당신의 워크플로우 선호도, AI가 인식한 패턴, 피해야 할 실수, 다시 검토해야 할 성공적인 접근 방식 — 이 모두가 그 파일에 담깁니다. LearnBoard는 그 보이지 않는 계층을 가시화하고, 검색 가능하게 하며, 실시간으로 편집할 수 있게 만듭니다.

작동 방식

LearnBoard는 LEARNING.md 파일을 위한 웹 대시보드를 제공하는 Node.js 서버(포트 4331)입니다. 이 파일은 정의된 섹션이 있는 구조화된 마크다운(Markdown) 형식을 사용합니다:

• Lessons (교훈) — AI가 학습한 명시적인 내용 ("항상 클라우드 API보다 로컬 도구를 우선시할 것")
• Tools (도구) — 사용자의 환경에 있는 도구 및 버전
• Suggestions (제안) — 아직 구현되지 않은 AI의 미결 아이디어
• Stats (통계) — 성공률, 세션 횟수, 학습 속도

서버는 chokidar를 사용하여 파일을 감시하고 Server-Sent Events (SSE)를 통해 UI로 업데이트를 푸시합니다. 따라서 두 번째 터미널을 열고 AI가 파일에 내용을 쓰면, 대시보드에 실시간으로 나타나는 것을 볼 수 있습니다.

LEARNING.md 발췌본:

## Lessons Learned (학습된 교훈)
...

AI의 시스템 프롬프트(System Prompt) 앞에 접두사로 붙는 이 파일은, 에이전트가 매 세션을 시작할 때 사용자의 선호도, 환경, 그리고 이전에 어떤 접근 방식이 효과적이었거나 실패했는지를 이미 알고 있는 상태에서 시작함을 의미합니다.

대시보드 (The dashboard)

웹 UI는 네 가지 주요 뷰를 제공합니다:

Lessons table (교훈 테이블) — 신뢰도 점수(낮음 / 중간 / 높음 / 확인됨), 카테고리 필터, 자유 텍스트 검색 및 인라인 편집 기능이 포함된 모든 교훈 목록입니다. 셀을 클릭하여 편집할 수 있습니다. 새로운 교훈은 즉시 추가됩니다. AI는 CLI 플래그를 통해 교훈을 추가할 수 있으며, 사용자는 이를 실시간으로 확인할 수 있습니다.

Tools inventory (도구 인벤토리) — 사용자의 스택: 언어 버전, 프레임워크, 주요 의존성(Dependencies)입니다. LearnBoard는 이 섹션을 부트스트랩(Bootstrap)하기 위해 사용자의 package.json, .nvmrc, SSH 환경을 자동으로 읽어옵니다.

Suggestions queue (제안 큐) — AI의 미결 아이디어들이 있으며, +1/−1 투표 시스템이 포함되어 있습니다. 긍정적인 투표가 쌓인 아이디어는 "수락됨(accepted)" 열로 승격되며, AI는 이를 향후 세션을 위한 확정된 가이드라인으로 취급합니다.

Session stats (세션 통계) — 세션 횟수, 수정률(Fix rate), 시간에 따른 학습 속도를 보여주는 가벼운 히스토그램입니다. 예를 들어, 15번 교훈이 12번의 세션에 나타났으며 94%의 성공률을 보이고 있다는 것을 확인할 수 있습니다. AI는 단순히 추측하는 것이 아니라, 증거를 가지고 있습니다.

혁신: 메타 AI (The innovation: meta-AI)

LearnBoard를 개인 위키나 노트 필기 도구와 다르게 만드는 핵심은, 이것이 사용자가 아닌 AI가 읽도록 설계되었다는 점입니다.

이 구조화된 형식은 언어 모델 (Language Model)에게 모호하지 않도록 특별히 선택되었습니다. 신뢰도 점수 (Confidence scores), 세션 횟수 (Session counts), 투표 기록 (Vote history)은 AI가 각 레슨의 가중치를 결정할 때 사용하는 신호입니다. 두 레슨이 충돌할 경우, 세션 횟수가 더 많고 신뢰도가 더 높은 레슨이 승리합니다.

AI는 파일에 직접 쓸 수도 있습니다. 성공적인 세션이 끝난 후, Claude나 Copilot에게 "방금 우리가 발견한 것에 대해 LEARNING.md에 레슨을 추가해줘"라고 요청할 수 있습니다. AI는 스키마 (Schema)를 알고 있으며, 올바른 섹션에 내용을 작성하고, 대시보드는 즉시 업데이트됩니다.

이것이 바로 **학습 루프 (Learning loop)**입니다. AI는 각 세션으로부터 학습하고, 레슨을 저장하며, 다음 세션을 위해 더 많은 정보를 갖추게 됩니다. LearnBoard는 이 루프를 가시화하고 제어 가능하게 만듭니다.

주요 강점

완전한 로컬 작동. 클라우드, 동기화, 계정이 필요 없습니다. LEARNING.md는 특정 벤더 (Vendor)에 의존하지 않고 읽고, 커밋 (Commit)하고, 백업하고, 공유할 수 있는 일반 텍스트 파일입니다.

AI 불가지론 (AI-agnostic). 이 파일 형식은 Claude, Copilot, GPT-4, Gemini 또는 시스템 프롬프트 컨텍스트 (System prompt context)를 수용하는 모든 에이전트 (Agent)와 함께 작동합니다. 특정 도구에 종속되지 않습니다.

인간이 읽을 수 있는 폴백 (Fallback). 대시보드가 실행 중이지 않을 때, 메모리 레이어 (Memory layer)는 단순한 마크다운 (Markdown) 파일일 뿐입니다. 블랙박스가 없습니다.

생존 가능한 아키텍처 (Survivable architecture). 새로운 AI 모델이 출시되어도 데이터를 마이그레이션 (Migrate)할 필요가 없습니다. 파일은 그대로 유지됩니다. 새로운 모델도 출시 첫날부터 동일한 레슨을 읽을 수 있습니다.

기술 스택

실제 테스트

저는 4개월 동안 모든 프로젝트에서 LearnBoard를 실행해 왔습니다. 저의 LEARNING.md 파일은 34개의 레슨, 18개의 대기 중인 제안, 그리고 6개의 활성 프로젝트를 위한 도구 인벤토리 (Tools inventory)로 성장했습니다.

컨텍스트를 미리 로드하지 않은 세션은 눈에 띄게 성능이 떨어집니다. AI는 제가 이미 배제한 솔루션을 제안하거나, 이미 답변한 질문을 다시 던지며, 때로는 파일에 기록된 것과 정확히 일치하는 실수를 저지르기도 합니다.

가장 구체적인 증거는 다음과 같습니다: 레슨 #19는 특정 고객의 서버 설정에 특화된 배포 패턴을 기록하고 있습니다. 저는 이를 추가한 이후 7번의 세션에서 해당 내용을 참조했습니다. 매번 AI는 별도의 지시 없이도 이를 사용했습니다. 이는 제가 직접 설명할 필요가 없었던 7번의 사례를 의미합니다.

시도해보기

LearnBoard는 Machina의 일부입니다 — 이는 당신의 작업 방식과 AI가 당신을 이해하는 방식 사이의 간극을 메워주는 오픈 소스 도구 모음 (open source suite of tools)입니다.

git clone https://github.com/machina-tools/machina.git
cd machina
bash setup.sh
...

그 다음 브라우저에서 http://localhost:4331을 여세요.

→ GitHub | machina.chat