Claude Code를 위한 plain-text 기반 Cognitive Architecture: Cog

Who Should Read

Claude Code나 Aider 같은 AI 코딩 어시스턴트를 실무에서 매일 사용하는데, 세션이 바뀔 때마다 컨텍스트를 다시 설명해야 하는 불편함을 겪고 있는 개발자.

Core Mechanics

• Claude Code는 기본적으로 세션 간 메모리가 없어서, 대화가 끊기면 이전 맥락을 전혀 기억하지 못한다. Cog는 이 문제를 plain-text 파일들로 구성된 외부 메모리 시스템을 만들어 해결하려는 프로젝트다.
• 메모리를 단일 파일에 다 때려넣는 대신, 'hot(즉시 로드) → warm(필요시 로드) → cold(아카이브)' 같은 계층(Tiered Memory)으로 나눠서 관리한다. 이렇게 하면 컨텍스트 윈도우를 효율적으로 쓸 수 있고, 자주 쓰는 정보만 빠르게 접근 가능하다.
• 세션 시작 시 'onboarding 플로우', 세션 종료 시 'shutdown 플로우'를 두어 AI가 스스로 메모리를 정리하고 갱신하도록 설계했다. 마치 사람이 하루 일과를 시작할 때 TODO를 확인하고, 끝낼 때 일지를 쓰는 것과 비슷한 구조다.
• 단순한 사실(예: '데이터베이스는 PostgreSQL 16')보다 맥락이 담긴 교훈(예: '통합 테스트에서 DB를 mock하지 말 것, 테스트는 통과했는데 migration이 실패한 사례가 있었음')을 저장하는 게 훨씬 효과적이라는 게 이 프로젝트의 핵심 설계 철학 중 하나다.
• 프로젝트는 CLAUDE.md(Claude Code가 공식 지원하는 프로젝트별 지시 파일)와 유사하지만, 더 정교한 구조를 추가한 것이다. 아키텍처 결정, 파일 경로, 'X를 해라/Y는 하지 마라' 같은 규칙들을 체계적으로 정리해 Claude가 일관된 행동을 하도록 유도한다.
• 이 접근법은 Claude Code에만 국한되지 않고, Aider, OpenCode 등 다른 AI 코딩 도구에도 동일하게 적용 가능한 범용 패턴이다. plain-text 기반이라 어떤 도구와도 호환된다.
• Anthropic의 공식 Auto Dream 기능이나 episodic-memory 같은 대안도 존재하지만, Cog는 개발자가 직접 구조를 커스터마이징하고 파일을 버전 관리(git)할 수 있다는 점이 차별점이다.

Evidence

• 장기 메모리의 신뢰도 문제를 지적하는 댓글이 있었다. 30세션 전의 관찰과 한 마디 발언에서 추론한 추측이 동일한 레벨로 저장되면 메모리가 점점 쓸모없어진다는 것. 이를 해결하기 위해 confidence score와 timestamp를 태깅하고, 오래 강화되지 않은 기억을 decay시키며, 서로 충돌하는 관찰을 'contradictions log'로 따로 관리했더니 유용했다는 실제 구현 경험이 공유됐다.
• CLAUDE.md만 잘 써도 충분하다는 실용적인 반론도 있었다. Claude Code를 인프라 구축에 많이 쓰는 개발자가 '사실 저장보다 교훈 저장이 훨씬 효과적이었다'며, 복잡한 메모리 아키텍처보다 잘 작성된 CLAUDE.md 하나가 더 강력할 수 있다고 주장했다.
• 훨씬 더 정교한 워크플로우를 직접 구현한 사례도 있었다. onboarding.md와 journal.md, musings.md를 나눠 관리하고, 세션 종료 시 AI가 모든 문서와 코드의 일관성을 검토한 뒤 PR을 제출하게 하는 방식이었다. 'AI를 도구가 아닌 collaborator로 대우하면 결과물이 훨씬 좋아진다'는 의견이었는데, '토큰 소모가 엄청나다(token fire)'는 현실적인 단점도 솔직하게 언급했다.
• Codex가 Claude보다 컨텍스트 관리 면에서 낫다는 의견이 있었다. 'Claude는 컨텍스트에서 정보를 드롭하지만 Codex는 세션이 오래 지속돼도 내용을 잊지 않는다'는 비교 경험이 공유됐고, 이는 Claude Code의 근본적인 한계를 우회하려는 이 프로젝트의 존재 이유를 반증하는 사례이기도 하다.
• 이 접근 자체가 LLM 아키텍처의 한계를 텍스트 파일로 때우는 피상적인(superficial) 방법이라는 비판적 시각도 있었다. 로컬 오픈 모델이 더 경쟁력 있었다면 overnight fine-tuning으로 해결했을 문제라는 주장으로, 현재 LLM 패러다임 자체의 한계를 지적하는 철학적 논점이었다.

How to Apply

• Claude Code 프로젝트에서 세션마다 같은 설명을 반복하고 있다면, CLAUDE.md에 단순 사실 대신 'X를 하지 마라 + 그 이유(실패 사례 포함)' 형식으로 교훈을 작성해라. 예: '통합 테스트에서 DB mock 금지 — 과거 테스트는 통과했으나 실제 migration 실패 사례 있음'처럼 맥락을 포함하면 Claude가 훨씬 일관되게 동작한다.
• 메모리 파일을 하나로 관리하면 컨텍스트 윈도우를 낭비하게 된다. 'always-load(프로젝트 핵심 원칙)', 'load-when-needed(특정 모듈별 규칙)', 'archive(과거 결정 이력)' 세 단계로 파일을 나눠서, 세션 시작 시 Claude에게 상황에 맞는 파일만 읽도록 지시하면 토큰 효율이 올라간다.
• 장기 프로젝트에서 AI 메모리의 신뢰도가 걱정된다면, 저장하는 정보에 '언제 기록됐는지'와 '얼마나 확실한지(추측 vs 검증된 사실)'를 함께 메모해두는 습관을 들여라. 서로 충돌하는 정보가 생기면 삭제하지 말고 'conflict' 섹션에 양쪽 다 남겨두면 나중에 맥락 파악에 도움이 된다.
• 이 Cog 아키텍처는 Claude Code 전용이 아니므로, Aider나 다른 AI 코딩 도구를 사용하는 경우에도 동일하게 적용 가능하다. Cog의 공식 사이트(https://lab.puga.com.br/cog/)에서 구조를 참고해 자신의 도구에 맞게 파일 컨벤션만 바꿔서 도입해보면 된다.

Terminology

Related Resources

• Cog — Cognitive Architecture for Claude Code (원문)
• Claude Code 공식 Memory 문서
• Anthropic Auto Dream 가이드
• episodic-memory (Superpowers 프로젝트)