매 세션마다 프로젝트를 다시 파악하던 AI 에이전트에 Engram을 적용하고 문서 구조를 정리한 과정

프로젝트마다 에이전트 문서를 두던 방식

Engram을 사용하기 전에는 모든 프로젝트에 AGENTS.md를 두고 더 자세한 내용은 agent-docs/에 기록했다.

project/
├── AGENTS.md
├── README.md
├── agent-docs/
│   ├── architecture.md
│   ├── deployment.md
│   └── troubleshooting.md
└── src/

README.md는 사람을 위한 문서이고 AGENTS.md와 agent-docs/는 에이전트를 위한 문서라는 구분이었다. 에이전트가 저장소에 들어오자마자 필요한 정보를 찾을 수 있다는 점에서는 꽤 괜찮았다.

하지만 프로젝트가 늘어나자 단점도 같이 커졌다.

모든 저장소에 비슷한 에이전트 지침이 반복되었다.
코드나 배포 구성이 바뀔 때 README와 에이전트 문서를 함께 수정해야 했다.
소스 저장소와 실제 배포 디렉터리가 나뉜 프로젝트는 어느 쪽 문서가 최신인지 헷갈렸다.
공개 저장소에 서버 경로나 운영 상태처럼 공개하기 어려운 정보가 섞일 가능성이 있었다.
이전 작업에서 왜 그런 결정을 내렸는지는 문서만으로 잘 남지 않았다.

특히 마지막 문제가 컸다. 문서는 현재 상태를 설명하는 데는 좋지만, 조사 중에 세운 가설이나 실패한 방법까지 계속 쌓아두면 금방 읽기 어려워진다. 반대로 그런 과정을 지우면 다음 에이전트가 같은 시행착오를 다시 겪게 된다.

Engram을 붙여보자

내가 원한 것은 거대한 지식 베이스가 아니라 다음 세션이 이전 세션의 판단을 이어받는 것이었다.

그래서 Engram은 외부 서버나 동기화 기능 없이 Codex의 로컬 MCP로만 연결했다. 기억은 서버 안의 SQLite 데이터베이스에 저장하고, 프로젝트마다 독립된 이름을 사용하도록 했다.

그렇다고 README의 내용을 그대로 Engram에 옮겨 담지는 않았다.

서버의 기본 폴더 구조와 문서 공개 범위
Engram에 저장해도 되는 정보와 저장하면 안 되는 정보
특정 프로젝트에서 발견한 비직관적인 동작
배포 구성의 실제 기준이 되는 파일
다음 세션이 다시 조사하지 않아도 되는 버그 원인

새 세션의 흐름은 다음처럼 만들었다.

mem_current_project
        ↓
mem_context
        ↓
필요한 키워드로 mem_search
        ↓
README와 운영 문서, 현재 코드 확인
        ↓
작업
        ↓
mem_save로 중요한 결정과 발견 저장
        ↓
mem_session_summary

mem_context로 최근 작업을 먼저 불러오고, 현재 요청과 관련된 내용만 mem_search로 찾는다. 검색 결과가 길어서 잘렸을 때만 전체 기억을 다시 읽는다.

이렇게 하니 에이전트가 매번 모든 문서를 처음부터 읽는 대신 지금 필요한 문맥을 먼저 찾고 원문으로 검증하는 방식으로 작업할 수 있게 되었다.

처음부터 잘 굴러가지는 않았다

Engram을 연결한 뒤 가장 먼저 발견한 문제는 프로젝트 자동 감지였다.

서버의 작업공간 루트는 하나의 Git 저장소가 아니고 그 아래에 여러 저장소가 들어 있다. 여기서 private-docs는 공개 저장소의 README에 적기 어려운 실제 서버 경로, 배포 상태, 백업과 복구 절차 같은 비공개 운영 정보를 한곳에 모아둔 별도 저장소다.

이 위치에서 프로젝트를 자동 감지하면 서버 공통 프로젝트가 아니라 하위의 private-docs 저장소가 선택되는 경우가 있었다.

그 상태에서 아무 생각 없이 기억을 저장하면 서버 공통 결정이 private-docs 프로젝트 기억으로 들어간다.

그래서 세션 시작 시 mem_current_project의 결과를 반드시 확인하고, 서버 전체를 다루는 작업은 server-ops라는 프로젝트 이름을 명시하도록 했다. 여러 프로젝트를 한 세션에서 다룰 때도 기억은 각각 분리해서 저장한다.

두 번째 문제는 무엇이든 기억으로 만들고 싶어진다는 점이었다.

명령어를 한 번 실행했다는 사실, 코드만 보면 바로 알 수 있는 구조, 평범하게 성공한 테스트까지 모두 저장하면 검색 결과가 금방 지저분해진다. 반대로 너무 아끼면 다음 세션에 도움이 되지 않는다.

지금은 다음 내용만 주로 저장한다.

중요한 설계 결정과 그 이유
실제 버그의 원인과 검증 결과
실패한 접근에서 얻은 재사용 가능한 교훈
예상하기 어려운 외부 시스템의 동작
다음 세션이 이어받아야 하는 작업 문맥

비밀값, 환경 파일 내용, 인증 헤더, 원문 로그와 사용자 프롬프트는 저장하지 않는다. 코드에서 바로 알 수 있는 사실도 기억 대신 코드에 맡긴다.

문서를 줄였더니 입구가 사라졌다

Engram을 도입한 뒤에는 프로젝트의 에이전트 전용 문서를 없애고 README만 남기는 방향으로 정리했다. 중복 문서는 확실히 줄었지만, 이번에는 반대쪽 걱정이 생겼다.

Engram에만 의존하면 기억을 검색하기 전까지 에이전트가 어디서 무엇을 찾아야 하는지 알기 어렵다. 삭제, 복구, 마이그레이션 같은 중요한 운영 작업을 과거의 기억만 보고 실행하는 것도 위험하다.

실제로 문서 구조를 점검했을 때 비공개 운영 문서는 약 2,700줄, 각 프로젝트의 README는 합쳐서 약 1,000줄이었고 Engram에는 5개 프로젝트의 기억 23개가 저장되어 있었다. 즉, 모든 지식이 Engram으로 옮겨간 상태는 아니었다. 이미 안정적인 정보의 대부분은 문서에 있었고 Engram은 최근 결정과 문제 해결 과정에 가까웠다.

프로젝트마다 있던 에이전트 문서를 없애자 중복은 줄었지만, README와 비공개 운영 문서, Engram을 어떤 순서로 확인해야 하는지 알려주는 입구도 함께 사라졌다.

그래서 작업공간 루트에 얇은 AGENTS.md 하나를 다시 만들었다. 이 문서는 프로젝트별 상세 내용을 복제하지 않는다. 대신 에이전트가 처음 세션을 시작했을 때 다음 정보를 찾을 수 있게 해준다.

소스 코드, 배포 구성, 비공개 문서가 있는 위치
각 프로젝트와 Engram 프로젝트 이름의 연결
README, 비공개 문서, Engram 중 무엇을 우선해야 하는지
세션 시작과 종료 때 기억을 사용하는 순서
저장하면 안 되는 정보와 블로그 후보 기준

결국 AGENTS.md는 지식의 본체가 아니라 서버 문서와 기억을 찾아가는 안내판이 되었다.

README, private-docs, Engram의 역할 나누기

현재는 정보의 성격에 따라 저장 위치를 세 가지로 나눈다.

위치	저장하는 내용
프로젝트 `README.md`	제품 동작, 공개 가능한 구조, 설치와 사용법, 검증 방법
`private-docs`	실제 서버 경로, 배포 상태, 백업과 복구, 비공개 운영 절차
Engram	결정 이유, 버그 원인, 실패한 접근, 비직관적인 발견, 세션 인수인계

코드와 README는 제품이 현재 어떻게 동작하는지 설명한다. 중요한 운영 작업은 private-docs 원문을 기준으로 한다. Engram은 “왜 이렇게 되었는가”와 “다음에 무엇을 기억해야 하는가”를 맡는다.

세 정보가 충돌할 때도 Engram을 무조건 믿지 않는다. 현재 코드와 실제 실행 상태를 확인한 뒤 오래된 문서나 기억을 갱신한다.

이 구분을 하고 나니 에이전트 문서를 없앤다는 말의 의미도 조금 달라졌다. 문서를 기억으로 대체한 것이 아니라, 중복된 에이전트 문서를 없애고 정보마다 알맞은 저장소를 정한 것에 가까웠다.

projects와 services로 나눈 또 한 번의 시행착오

private-docs를 처음 만들 때는 소스 프로젝트 문서를 projects/, 배포 서비스 문서를 services/로 나눴다.

private-docs/
├── projects/
│   ├── project-a/
│   └── project-b/
└── services/
    ├── service-a/
    └── service-b/

처음에는 실제 서버 폴더 구조와 비슷해서 자연스럽게 보였다. 하지만 어떤 프로젝트는 소스만 있고, 어떤 프로젝트는 배포 구성만 있으며, 어떤 프로젝트는 둘 다 가지고 있었다.

소스와 배포 구성을 모두 가진 프로젝트는 두 폴더에 문서가 생겼다. 실제로 한 프로젝트의 문서가 projects/와 services/ 양쪽에 존재했고, 한쪽에는 현재 Compose 구성에 없는 오래된 컨테이너 정보까지 남아 있었다.

반대로 실제 배포 중인데도 이미 projects/ 아래에서 운영 문서를 관리하는 프로젝트도 있었다. 결국 소스가 있는지, 배포되었는지는 문서를 나누는 기준으로 쓰기 어려웠다. 둘은 프로젝트의 분류가 아니라 서로 독립된 속성이었다.

그래서 비공개 문서는 모두 Engram 프로젝트 이름과 같은 projects/<key>/ 아래로 합쳤다.

workspaces/
├── AGENTS.md
├── repositories/
├── services/
└── private-docs/
    ├── README.md
    ├── projects/
    │   ├── project-a/
    │   ├── project-b/
    │   └── service-only-project/
    └── server/

실제 소스와 배포 폴더는 그대로 유지한다. 문서만 하나의 독립 작업 단위에 모으고, 그 안에서 소스 경로와 배포 경로를 함께 설명한다. 덕분에 에이전트가 프로젝트 이름 하나로 README, 비공개 문서와 Engram 기억을 연결할 수 있게 되었다.

개발 흔적을 블로그 글로 사용하기

문서 구조를 정리하면서 Engram에 한 가지 역할을 더 추가했다.

나는 개발 중에 겪은 문제를 바탕으로 개발기나 트러블슈팅 글을 작성한다. 그런데 문제가 해결된 뒤 시간이 지나면 처음 세운 가설이나 실패한 방법은 잘 기억나지 않는다. Git에는 최종 변경은 남지만 왜 그 방법을 선택했는지까지 모두 남지는 않는다.

이런 과정은 README나 운영 문서에 계속 쌓기에는 너무 일시적이고, 블로그 초안으로 바로 만들기에는 아직 정리되지 않았다. Engram이 중간 저장소로 잘 맞았다.

다음 다섯 가지 중 세 가지 이상을 만족하면 일반 세션 요약과 별도로 [blog-seed] 기억을 남긴다.

처음 보인 증상과 실제 원인이 다른가?
다른 프로젝트에도 재사용할 교훈이 있는가?
가설, 실패한 접근과 트레이드오프가 있는가?
코드, 커밋, 테스트 같은 검증 근거가 있는가?
다른 개발자의 조사 시간을 줄일 수 있는가?

후보에는 증상, 가설, 실패한 방법, 원인, 해결책, 검증 결과와 글의 핵심 관점을 기록한다. 나중에 실제 글을 쓸 때는 Engram만 복사하지 않고 Git 기록과 현재 코드, 문서를 다시 확인한다. 공개하면 안 되는 서버 정보도 이때 제거한다.

재미있게도 이 글 자체가 그 흐름을 처음부터 끝까지 시험한 결과다. Engram에 남겨둔 도입 당시의 결정과 세션 요약을 찾고, 실제 문서 커밋과 현재 구조를 대조한 다음 기존 블로그 글의 문체에 맞춰 다시 구성했다.

최종적으로 정착한 흐름

새 세션이 시작되면 에이전트는 먼저 루트 AGENTS.md를 읽는다. 여기서 대상 프로젝트의 경로와 Engram 이름을 확인한다.

그다음 최근 세션 문맥과 관련 기억을 검색하고, README와 비공개 문서, 현재 코드를 대조한 뒤 작업한다. 작업이 끝나면 변경의 성격에 따라 기록 위치를 고른다.

제품 동작과 공개 사용법 변경 ───────→ README
서버 운영 절차와 배포 정보 변경 ────→ private-docs
결정 이유와 버그 원인 발견 ─────────→ Engram
블로그 가치가 있는 해결 과정 ───────→ Engram [blog-seed]

이 구조의 목표는 Engram이 없으면 아무것도 할 수 없게 만드는 것이 아니다. 에이전트가 매 세션마다 같은 조사를 반복하지 않도록 기억을 제공하면서도, 현재 상태와 중요한 운영 절차는 사람이 읽을 수 있는 문서에 남기는 것이다.

처음에는 에이전트 문서를 모두 기억으로 바꾸면 된다고 생각했다. 하지만 실제로 필요한 것은 문서를 없애는 일이 아니라 현재 사실, 비공개 운영 정보, 시간에 따라 쌓이는 판단의 흔적을 서로 다른 위치에 두는 일이었다.

이제 다음 세션의 에이전트는 서버를 완전히 처음 보는 상태에서 시작하지 않는다. 무엇을 먼저 읽어야 하는지 알고, 이전 에이전트가 어디에서 막혔는지 찾을 수 있으며, 그래도 중요한 작업을 수행할 때는 현재 코드와 문서를 다시 확인한다.

내가 원했던 기억은 결국 이런 형태에 가장 가까웠다.

Temple's Hideout

Engram으로 AI 에이전트에게 서버의 기억을 만들어주기

목차