LLM의 ‘영구 기억’을 저장소와 검색으로 설계하는 법: YAMS 실전 가이드

대화창이 길어질수록 중요한 결정이 뒤로 밀리고, 새 세션에서는 같은 맥락을 다시 설명해야 한다. 이 문제를 해결하려면 모델의 컨텍스트 창을 무작정 늘리기보다, 기록을 보존하고 필요한 순간에 찾아오는 외부 기억 계층으로 나누어 생각하는 편이 낫다. YAMS는 콘텐츠 주소 기반 저장소와 텍스트·벡터·그래프 검색을 결합한 로컬 중심 도구다. 따라서 ‘모델이 모든 것을 기억한다’는 약속이 아니라, 문서와 코드의 근거를 보관하고 질의에 맞는 조각을 되찾는 흐름을 만드는 데 어울린다.

기억은 저장과 검색을 함께 설계해야 한다

재사용 가능한 기억에는 적어도 세 층이 있다. 첫째는 원문과 파일 버전처럼 나중에 검증할 수 있는 기록, 둘째는 태그·프로젝트·스냅샷 같은 메타데이터, 셋째는 검색용 인덱스다. YAMS 문서에 따르면 파일은 콘텐츠 주소 방식으로 저장되고, 메타데이터는 SQLite/FTS5에, 임베딩은 벡터 인덱스에 놓일 수 있다. 검색은 키워드, 의미 유사도, 구조 정보를 함께 다루는 하이브리드 방식이다. 중요한 점은 검색 결과를 ‘사실’로 바로 믿지 않는 것이다. 결과에는 원본 경로와 스냅샷을 함께 남기고, 답변을 만들 때는 해당 원문을 다시 열어 인용 범위를 확인해야 한다.

가장 작은 시작: 프로젝트별 저장소

개인 메모와 업무 저장소를 한 덩어리로 섞으면 검색 결과가 빨리 흐려진다. 프로젝트 디렉터리에 별도 저장소를 두고, 읽기 좋은 문서부터 넣어 보자.

YAMS_STORAGE="$PWD/.yams" yams init --non-interactive
YAMS_STORAGE="$PWD/.yams" yams add README.md --tags "docs,project"
YAMS_STORAGE="$PWD/.yams" yams add src/ --recursive --include="*.ts,*.md" --tags "source"
YAMS_STORAGE="$PWD/.yams" yams search "배포 환경 변수" --limit 5

공식 빠른 시작 문서는 yams add, yams search, yams get, yams diff와 같은 흐름을 안내한다. 자동 수집이 필요하면 yams watch를 사용할 수 있지만, 비밀키·개인정보·빌드 산출물이 들어 있는 경로는 먼저 제외 규칙을 정해야 한다. ‘많이 넣을수록 좋다’는 방식은 접근 통제와 결과 품질을 동시에 해친다.

의미 검색은 선택 사항이며, 운영 절차가 필요하다

YAMS는 임베딩을 자동 생성하도록 설정할 수 있고, 지원되는 SQLite 환경에서는 추출 텍스트를 FTS5에 인덱싱한다. 두 경로가 함께 있을 때 키워드 검색과 벡터 검색을 섞어 순위를 정할 수 있다. 반대로 임베딩 백엔드가 준비되지 않았거나 실패하면 문서상 해당 작업은 기록되고 건너뛸 수 있으므로, ‘검색이 되니 의미 검색도 정상’이라고 단정하면 안 된다. yams status, yams doctor, yams stats --verbose로 상태를 확인하고, 누락된 임베딩이나 FTS 항목은 yams repair --embeddings, yams repair --fts5처럼 목적이 분명한 복구 명령으로 다룬다.

임베딩 차원은 모델 출력과 맞아야 한다. 모델을 교체할 때는 기존 인덱스가 새 차원과 호환되는지 점검하고, 필요하면 재생성 범위와 시간을 계획한다. 검색 품질 평가는 ‘그럴듯한 답’이 아니라 대표 질문 20~50개에서 원문이 상위 결과에 나오는지로 측정하는 편이 실용적이다.

LLM·MCP 연결에서 지켜야 할 경계

yams serve는 MCP 서버를 표준 입출력으로 제공할 수 있어, 에이전트가 저장된 문맥을 검색하는 통로가 된다. 이때도 도구가 반환한 문서는 프롬프트의 지시가 아니라 참고 자료로 취급해야 한다. 외부 문서 안의 명령을 자동 실행하지 말고, 신뢰 범위·출처·수정 시각을 함께 표시하는 규칙을 둔다. 플러그인은 신뢰 설정을 거쳐 실행되는 구조이므로, 출처가 불분명한 바이너리 플러그인을 업무 저장소에서 바로 허용하는 일은 피하는 편이 안전하다.

영구 기억의 성패는 모델 이름보다 정리 습관에 가깝다. 문서를 넣을 때 태그와 소유 범위를 정하고, 중요한 결정은 짧은 결정 기록으로 남기며, 검색 결과는 원문으로 검증한다. 그렇게 하면 세션이 바뀌어도 팀의 맥락은 파일과 근거 위에서 이어진다.

대표 출처

https://yamsmemory.ai/user_guide/
https://yamsmemory.ai/architecture/system_architecture/