서론

Codex나 Claude Code에 장기 기억(Long-term memory)을 부여하면, 이전의 판단이나 작업 방침을 이어받기가 쉬워집니다. 저 또한 Obsidian 스타일의 Markdown vault에 설계 판단, 전략 메모, handoff, 현재 목표를 남기는 방식으로 운영해 왔습니다.

여기서 말하는 Codex는 로컬 리포지토리(Local repository)를 읽고 쓰며 작업할 수 있는 OpenAI의 코딩 에이전트입니다. Claude Code와 마찬가지로, 파일로 남겨둔 문맥(Context)을 다음 작업에 사용하는 것을 전제로 다루고 있습니다.

하지만 기억을 늘릴수록 다른 문제가 발생했습니다. 기동 시에 읽어야 할 파일이 커지면서, 작업 그 자체보다 '과거 로그를 매번 읽는 것'에 컨텍스트(Context)를 사용하게 된 것입니다.

이 기사에서는 AI 에이전트용 장기 기억을 늘릴 뿐만 아니라, 기동 입구를 session-brief로 나누어 가볍게 유지하도록 만든 이야기를 쓰겠습니다. 대상 독자는 AI 코딩 에이전트에 지속적인 문맥을 부여하고 싶지만, 컨텍스트 비대화로 고민하고 있는 개인 개발자입니다.

관련된 기사 관리 실례는 harness17/zenn-articles에 두었습니다. 이 기사에서는 비공개 vault의 내용 그 자체가 아니라, 공개해도 문제없는 운영 패턴만을 다룹니다.

기억을 늘릴수록 기동이 무거워졌다

처음에는 장기 기억을 단순히 늘리기만 하면 된다고 생각했습니다.

• 현재 목표를 goals.md에 작성
• 설계 판단을 decisions/에 남김
• 전략 메모를 strategies/에 남김
• Codex와 Claude Code의 인수인계를 handoffs/에 남김

이 구성 자체는 유용했습니다. 이전에 왜 그런 설계를 했는지, 어떤 기사가 공개 대기 중인지, 어떤 작업을 다른 에이전트에게 넘겼는지를 대화 로그에만 가두지 않고 추적할 수 있게 되었습니다.

한편으로, 기동 시에 읽는 입구를 너무 늘리면 다른 부하가 발생합니다. goals.md에 완료된 이력까지 남고, decisions/index.md에 전체 인덱스가 들어가며, handoff도 오래된 것을 바로 아래에 둔 채로 두면 매번의 orientation(오리엔테이션)이 무거워집니다.

실제로 운영했을 때는 goals.md가 약 36KB, decisions/index.md가 약 11KB까지 불어났습니다. 내용은 유용하더라도 매 세션의 처음에 전체를 읽기에는 너무 큽니다. 장기 기억을 갖게 하려다가 오히려 직전 태스크에 사용할 수 있는 여백을 줄이고 있었습니다.

session-brief를 기동 입구로 삼았다

그래서 기동 시에 읽는 파일을 session-brief로 나누었습니다.

session-brief는 상세 이력이 아니라 '어디를 입구로 읽을 것인가'를 나타내는 얇은 브리프(Brief)입니다. 현재의 초점, 읽기 방침, 압축 유지 기준만을 두고, 필요할 때만 상세 노트로 넘어가는 형식을 취했습니다.

# session-brief
## 읽기 방침
- 기동 시의 기본 입구는 이 파일, reminders, 필요하다면 goals의 앞부분만.
...

여기서 중요했던 것은 session-brief를 '요약의 저장소'로 너무 과하게 만들지 않는 것입니다. 요약을 너무 두껍게 만들면 다시 기동 입구가 비대해집니다.

본문에는 상세 내용을 적지 않고, 상세 내용이 필요한 작업만 링크를 통해 읽습니다. 이를 철저히 함으로써 기동 시의 읽기량을 억제하면서도, 오래된 판단을 지우지 않고 유지할 수 있게 되었습니다.

삭제가 아닌 archive로 넘겼다

컨텍스트를 가볍게 하는 것이 목적이라면 오래된 이력을 삭제하는 방법도 있습니다. 하지만 저의 목적은 '잊어버리는 것'이 아닙니다. 나중에 왜 그런 판단을 했는지, 어떤 기사가 어떤 기술 영역을 나타내는지 설명할 수 있는 상태로 만드는 것입니다.

그렇기 때문에 삭제가 아닌 archive(아카이브)로 넘기는 방침을 세웠습니다.

memory/
├── self/
│ ├── session-brief.md # 기동 입구
...

이 정리를 통해 goals.md는 약 36KB에서 약 2KB로, decisions/index.md는 약 11KB에서 약 2.5KB까지 줄어들었습니다.

수치가 작아진 것 자체보다 입구의 역할이 명확해진 것이 더 큽니다. 기동 시에는 '지금 보는 것'만 읽고, 과거의 상세 내용은 검색이나 링크를 통해 가져옵니다. 장기 기억과 매번의 작업 컨텍스트를 분리할 수 있었습니다.

기동 시에 읽지 않을 것을 결정했다

압축 후에도 하나 더 결정한 것은 '기동 시에 읽지 않을 것'입니다.

AI 에이전트(AI Agent)를 위한 기억 운용에서는 무엇을 읽느냐보다, 무엇을 매번 읽히지 않을지가 중요했습니다. 저는 다음과 같이 나누고 있습니다.

이렇게 분류한 이후로, 오래된 정보에 끌려 현재 작업이 흐릿해지는 일도 줄었습니다.

장기 기억(Long-term memory)은 매번 전부 읽히기 위한 것이 아닙니다. 검색할 수 있고, 필요할 때 꺼낼 수 있는 상태라면 충분합니다. 이 부분을 나누지 않으면 기억이 늘어날수록 작업이 무거워집니다.

압축 트리거를 규칙화했다

한 번 가볍게 만들어 두어도, 운용하다 보면 다시 늘어납니다. 그렇기 때문에 압축하는 타이밍도 규칙으로 정했습니다.

## 압축 유지보수 기준
- goals.md 가 8KB를 초과하면, 완료된 이력을 archive/goals/ 로 이동한다.
- decisions/index.md 가 8KB를 초과하면, 전체 인덱스를 archive/decisions/ 로 퇴피(evacuate)한다.
...

이 기준은 엄격한 성능 튜닝(Performance tuning)이 아니라, 운용상의 경계선입니다. 파일 크기가 8KB를 초과하면 반드시 망가진다는 의미는 아닙니다. 다만, 제 운용 방식에서는 그 정도부터 "기동 시에 읽기에는 무겁다"라고 느끼기 시작했습니다.

기준을 세워두면 압축을 즉흥적인 청소로 만들지 않아도 됩니다. 기사 공개가 이어진 후, 여러 세션에 걸친 구현이 끝난 후, 핸드오프(handoff)가 늘어난 후에, 입구만을 재검토할 판단을 내리기가 쉬워졌습니다.

요약

AI 에이전트의 장기 기억은 늘리기만 해서는 다루기 어려워집니다.

제 경우에는 기동 입구를 session-brief로 나누고, 완료된 이력이나 전체 인덱스는 archive로 퇴피했습니다. 기동 시에 읽는 것, 읽지 않는 것, 필요할 때만 가져오는 것을 구분함으로써 기억의 검색성과 작업 시의 가벼움을 양립하기 쉬워졌습니다.

장기 기억을 만들 때는 먼저 "무엇을 남길 것인가"뿐만 아니라, "매번 읽히지 않기 위해 입구를 어떻게 얇게 만들 것인가"를 결정하는 것이 효과적입니다.

참고 링크

• harness17/zenn-articles: 기사 관리 및 공개 전 리뷰 운용 리포지토리(Repository)
• Model Context Protocol: 로컬 지식이나 외부 도구를 AI 에이전트에 연결하기 위한 사양
• 관련 기사: AI와의 설계 판단을 My-Skill-Graph에 남겨 재사용하기
• 관련 기사: Zenn 기사를 리포지토리로 관리하여 공개 전 리뷰까지 돌린 실천 메모 (동시 공개 예정)

Discussion