Context Vault

Agent Kernel — 마크다운 3개로 AI 에이전트 상태 유지

7 min read

한 줄 요약

복잡한 DB나 프레임워크 없이 3개의 마크다운 파일 + Git만으로 AI 에이전트의 세션 간 기억을 구현하는 경량 에이전트 커널.

핵심 아이디어

AI 에이전트는 매 세션마다 맥락이 초기화된다. Agent Kernel은 AI 툴이 기본적으로 읽는 AGENTS.md (또는 CLAUDE.md, .cursorrules) 메커니즘을 활용해, 에이전트가 스스로 기억하는 방법을 학습하게 한다.

필요한 것:

  • “너는 상태 저장형이다, 방법은 이렇다”고 알려주는 파일
  • 기억을 저장할 Git 저장소
  • 일반 마크다운 파일

메모리 구조

AGENTS.md          ← 커널 (수정 불필요, 범용)
IDENTITY.md        ← 이 에이전트의 정체성 (에이전트가 관리)
KNOWLEDGE.md       ← 지식 파일 인덱스 (에이전트가 관리)
knowledge/         ← 세계에 대한 사실들 (가변)
notes/             ← 일일 세션 로그 (추가 전용)

두 종류의 기억

종류디렉토리역할수정 여부
상태(State)knowledge/현재 사실, 설정 등변경 시 업데이트
서사(Narrative)notes/세션별 결정·행동·미결 항목추가 전용, 과거 수정 불가

세션 프로토콜

시작 시:

  1. IDENTITY.md 읽기 → 자신이 누구인지 파악
  2. KNOWLEDGE.md 읽기 → 어떤 상태 파일이 있는지 확인
  3. notes/ 최근 2-3개 읽기 → 이전 맥락·미결 항목 파악

진행 중:

  • 행동 전 상태 검증 (노트를 맹목적으로 신뢰하지 않음)
  • 점진적으로 커밋·푸시 (관련 없는 변경 묶지 않음)
  • 오늘의 일일 노트에 완료 내용·결정·미결 항목 업데이트

빠른 시작

git clone https://github.com/oguzbilgic/agent-kernel.git my-agent
cd my-agent
claude  # 또는 opencode, codex, cursor 등

에이전트가 커널을 읽고, 처음임을 인지하여 어떤 역할을 원하는지 묻는다. 답하면 기억된다.

다중 에이전트

각 에이전트는 별도의 저장소로 운영된다. 동일한 커널로 서로 다른 정체성·지식을 가진 에이전트를 여러 개 운영할 수 있다.

git clone https://github.com/oguzbilgic/agent-kernel.git homelab-agent
git clone https://github.com/oguzbilgic/agent-kernel.git investing-agent
git clone https://github.com/oguzbilgic/agent-kernel.git health-agent

호환 툴

Claude Code, OpenCode, Codex, Cursor, Windsurf 등 AGENTS.md (또는 유사 설정 파일)를 읽는 모든 AI 코딩 에이전트에서 동작.

핵심 파일 구조

프로젝트 루트에 3개의 마크다운 파일을 두는 것이 전부다.

  • IDENTITY.md: 에이전트의 역할, 코딩 스타일, 지켜야 할 원칙 정의 (예: “너는 시니어 프론트엔드 개발자이며, 항상 테스트 코드를 먼저 작성한다.“)
  • KNOWLEDGE.md: 프로젝트 진행하면서 알게 된 사실, 기술 스택, 버그와 해결책 등 ‘기억’ 누적
  • AGENTS.md: 어떤 에이전트가 무슨 일을 했고 현재 상태가 어떤지 기록하는 작업 로그(State)

초기 지시 프롬프트 예시

터미널에서 AI 도구 실행 후 첫 명령어로 다음 프롬프트를 주입한다:

“프로젝트 루트에 있는 IDENTITY.md를 읽고 너의 역할과 원칙을 숙지해 줘. 그리고 작업을 시작하기 전에 항상 KNOWLEDGE.md와 AGENTS.md를 읽어서 현재 프로젝트의 맥락과 이전 작업 내역을 파악해. 작업이 끝나거나 내가 종료를 요청하면, 네가 방금 수행한 작업 내용과 새롭게 알게 된 사실(해결한 버그, 변경된 아키텍처 등)을 KNOWLEDGE.md와 AGENTS.md에 마크다운 형식으로 업데이트한 뒤에 종료해야 해.”

워크플로우 시너지

  • tmux 실시간 모니터링: 창을 분할하여 한쪽은 Claude Code/OpenClaw, 다른 쪽은 tail -f KNOWLEDGE.md로 AI의 맥락 기록을 실시간 확인
  • Obsidian 연동: 3개 파일은 순수 마크다운이므로 PARA 구조의 ‘Projects’ 폴더에 심볼릭 링크를 걸거나 직접 위치시켜 프로젝트 지식 베이스로 활용. AI가 작성한 기록을 개인 노트로 재가공하기 좋음.
  • Git 히스토리 = 상태 스냅샷: AI가 마크다운 업데이트 후 커밋하면 Git 히스토리에 상태가 남아 언제든 과거 특정 시점(State)으로 롤백 가능

의의

  • Vibe Coding 연속성: AI가 스스로 마크다운을 업데이트 → 다음 세션에서 이어서 작업 가능
  • OpenClaw 연동 최적화: 터미널 AI CLI 툴과 조합하여 장기 프로젝트 관리
  • 인프라 불필요: 벡터 DB, 커스텀 프레임워크 없이 Git + 마크다운만으로 구현
  • 투명한 기억: 모든 기억이 텍스트 파일로 저장되어 사람이 직접 검토·편집 가능

그래프 뷰