에이전트 메모리를 파이프라인 대신 파일 포맷으로: memoryfield

TL;DR Highlight

메모리를 Markdown+SQLite 벡터 인덱스로 두니 검색 2번이면 끝났다

Who Should Read

에이전트에 장기 메모리를 붙이려는데 pgvector·그래프DB 같은 복잡한 파이프라인이 부담스러운 백엔드 개발자

Core Mechanics

메모리는 파이프라인이 아니라 데이터다
- 기존 메모리 시스템은 대화에서 정보를 뽑아내는 여러 단계 처리 과정으로 만들어져 있다.
- 저자는 메모리를 데이터 포맷으로 정의하고 처리 과정은 두지 말자고 한다.
memoryfield는 zip 안의 md 파일과 SQLite
- zip 안에 Markdown 페이지(YAML frontmatter는 선택)와 SQLite 벡터 인덱스(선택)를 넣는 구조다.
- 예시 인덱스는 nomic-embed-text-v1.5를 쓴다.
청킹 없이 에이전트가 산문으로 직접 쓴다
- 메모리는 에이전트가 쓰는 시점에 바로 Markdown으로 쓰면 되므로 청킹·요약 같은 가공이 필요 없다.
- 페이지는 약 8kb(약 2000 토큰) 이내로 제한하고, 더 쓸 내용은 페이지를 추가한다.
그래프 탐색 대신 시맨틱 점프
- 그래프를 타면 깊이 N마다 N+1번 툴 호출이 필요하고 호출당 2~3초 정도 걸린다고 한다.
- 시맨틱 검색으로 관련 페이지를 바로 찾고 병렬로 읽으면 툴 호출은 최대 2번(검색 1, 읽기 1)이다.
접근 방식은 모델에 맡긴다
- 전용 API 없이 파일만 주니 에이전트가 perl로 일괄 치환하거나 메모리 안에 CSV를 넣고 SQLite로 질의하는 식으로 스스로 방법을 만든다고 한다.
- 모델이 좋아질수록 메모리 활용도 같이 좋아진다는 주장이다.

Community Reactions

메모리를 아예 안 쓴다는 경험
- 오염된 한 줄이 이후 전체에 악영향을 줘서, temp 폴더의 문서를 에이전트·모델별로 쓰고 계속 정리한다는 댓글이 있었다.
- 추론으로 만들 수 있는 정보는 노이즈라 문서에 넣지 않는다고 한다.
잘 쓴 AGENTS.md가 메모리보다 낫다는 의견
- 메모리를 켜는 것보다 AGENTS.md를 잘 쓰는 쪽이 거의 항상 결과가 좋았다는 경험이 있었다.
"무관한 자료는 검색에 안 나온다"는 주장은 낙관적이라는 반론
- 잘못된 곳을 뒤졌거나 나중에 틀린 것으로 밝혀진 과거 기록도 의미상으로는 관련 있어 보여 계속 검색된다는 의견이다.
- 모든 메모리가 벡터뿐이면 키워드 검색이 실패할 수 있어 하이브리드 검색이 여전히 유용하다는 의견도 있었다.
git 저장소로 쓰자는 제안
- zip 재생성 대신 Markdown 페이지를 git 저장소로 관리하면 증분 쓰기·커밋 해시 고정·diff를 공짜로 얻는다는 의견이다.
- SQLite는 재생성 가능한 캐시이니 gitignore하면 된다고 한다.
유사한 구성으로 잘 쓴다는 경험
- 세션 턴을 sqlite-vec에 저장하고 MCP로 검색시키며 노트는 md로 쓰게 했더니 단순하면서 더 낫더라는 경험이 있었다.
- 노트 덕에 사용자가 잘못 쌓인 교훈을 고칠 수 있었다고 한다.

How to Apply

샘플 memoryfield로 검색 흐름 체험하기
- ollama, uv, npx를 갖추고 ollama pull nomic-embed-text 후 CLI와 skill을 설치하라.
- 저자가 제공한 soapstones.memoryfield.zip을 열어 에이전트가 검색 후 병렬로 읽는지 확인하라.
기존 에이전트 메모리를 md 페이지로 옮기기
- 사실 목록으로 쪼갠 기록을 8kb 이하 산문 페이지로 다시 쓰고 title·summary·uuid·날짜 frontmatter를 붙여라.
- 각 페이지에 출처 URL 인용을 넣어 나중에 검증할 수 있게 하라.
그래프 탐색 툴 호출 수를 세어 보기
- 현재 지식 그래프·위키 방식에서 한 질문에 툴 호출이 몇 번 나가는지 로그로 확인하라.
- 검색 1번 후 병렬 읽기 구조로 바꿔 호출 수와 지연을 비교하라.
외부에서 받은 메모리는 해시 고정 후 검토하기
- 공유받은 zip은 열어서 내용을 직접 읽어라.
- sha256sum으로 고정하고 신뢰하는 출처만 에이전트에 연결하라.

Try It

복사해서 바로 해보기

# Claude Code 터미널에서 실행 (원문의 설치 절차 그대로)
# 필요: ollama, uv, npx
ollama pull nomic-embed-text
uv tool install git+https://github.com/calpaterson/memoryfield-tool
npx skills add calpaterson/memoryfield-skill -g -y

# 설치 후 Claude Code에 이렇게 요청해 보기
# "memoryfield skill로 ./my-memories.memoryfield.zip을 만들고, 오늘 배운 {{주제}}를 8kb 이하 Markdown 페이지로 저장해줘. 출처 URL을 포함해."

# 이어서 해 볼 것: soapstones.memoryfield.zip을 받아 'Reddit 검색하는 법'을 물어보고 툴 호출 횟수를 세어 보기

Terminology

memoryfieldMarkdown 페이지 묶음과 SQLite 벡터 인덱스를 zip 하나에 담은 휴대용 메모리 포맷이다. 메모장 폴더에 검색 색인을 붙인 것과 비슷하다.

시맨틱 검색단어가 아니라 의미가 비슷한 문서를 임베딩 벡터로 찾는 검색이다. 키워드가 달라도 같은 뜻이면 찾는다.

Karpathy wiki서로 링크된 Markdown 문서들을 에이전트가 따라가며 읽는 지식 그래프형 메모리다. 위키 링크를 클릭해 들어가는 식이다.

frontmatterMarkdown 파일 맨 위에 --- 로 감싸 넣는 YAML 메타데이터다. 제목·날짜 같은 파일 정보표 역할을 한다.

하이브리드 검색키워드 검색과 벡터 검색을 함께 쓰는 방식이다. 정확한 단어 일치와 의미 유사도를 둘 다 잡는다.