MCP Memory: OKF 마크다운과 SQLite FTS5로 만든 에이전트 장기 기억 서버

Who Should Read

Claude Code·Cursor 에이전트가 세션마다 맥락을 잊어 handoff 프롬프트를 매번 쓰는 개발자

Core Mechanics

• 메모리를 MCP 서버로 붙인다
  • MCP-Memory는 Claude Desktop, Cursor, Windsurf, Codex 같은 에이전트에 장기 기억을 주는 MCP 서버다.
  • 에이전트가 메모리를 읽고, 저장하고, 검색하고, 지울 수 있다.
• 메모리가 마크다운 파일과 DB 두 곳에 저장된다
  • 메모리 한 건이 OKF v0.2 마크다운(YAML frontmatter 포함)으로 프로젝트의 memory/ 폴더에 저장된다.
  • 같은 내용을 .mcp_memory/memories.db(SQLite)에 인덱싱해 검색에 쓴다.
• 검색은 SQLite FTS5(전문 검색 엔진)가 맡는다
  • README는 key 조회 20ms 미만, 키워드 검색은 즉시라고 주장한다.
  • 키, 태그, namespace로 필터링할 수 있다.
• MCP 툴은 6개다
  • memory_store, memory_retrieve, memory_search, memory_delete, memory_get_last, memory_update_last가 있다.
  • get_last와 update_last는 system/last_memory라는 세션 체크포인트를 읽고 갱신한다.
• 프로젝트별로 격리되고 설정은 한 번이면 된다
  • 기본값은 프로젝트 루트마다 별도 저장소다.
  • python3 setup.py가 설치된 MCP 도구를 찾아 자동 등록한다.

Community Reactions

• 그냥 마크다운과 grep이면 되지 않느냐는 반론
  • 댓글에서 MCP 도구는 에이전트를 느리게 하고 토큰을 낭비하는 경우가 많았다는 경험이 나왔다.
  • grep 수준의 메모리 시스템이 또 나왔다는 비판과 Claude 내장 메모리, mem0와 뭐가 다르냐는 질문도 있었다.
• MEMORY.md 한 파일로 충분히 잘 쓴다는 경험
  • 댓글 작성자는 루트의 MEMORY.md를 새 대화마다 참조시킨다.
  • 작업이 끝나면 에이전트에게 교훈을 반영하고 낡은 내용은 지우게 해서 handoff 프롬프트가 필요 없어졌다고 한다.
• Claude Code가 외부 메모리 툴을 잘 안 쓴다는 경험
  • 댓글 작성자는 비슷한 도구를 만들어 코딩 표준과 결정 사항을 저장하고 있다.
  • Codex와 OpenCode의 OpenAI 모델은 툴을 잘 쓰지만 Claude Code는 자체 메모리 툴을 선호하는 듯했다고 한다.
  • Opus 5 이후 더 심해져 더 자세한 설정 지침을 넣어야 했다고 한다.
• 벡터 검색과 git 기반 대안 제안
  • 대화를 요약해 임베딩하고 pgvector로 검색하는 방식이 FTS보다 정확할 것 같다는 의견이 있었다.
  • git repo를 원본으로 두고 FTS5는 속도용 인덱스로만 쓰면 사람이 리뷰하기 쉽겠다는 제안도 있었다.

How to Apply

• Claude Code에 메모리 서버 등록해 보기
  • 저장소를 clone하고 claude mcp add --scope user memory -- /ABSOLUTE/PATH/TO/run.sh를 실행하라.
  • 작은 프로젝트에서 memory_store로 코딩 스타일 한 건을 저장하고 새 세션에서 memory_search로 찾아보라.
• 세션 시작·종료 규칙을 지시문에 넣기
  • CLAUDE.md나 시스템 프롬프트에 시작 시 memory_get_last 호출, 마일스톤마다 memory_update_last 호출을 적어라.
  • 에이전트가 툴을 안 쓰면 지침을 더 구체적으로 쓰라.
• MEMORY.md 방식과 직접 비교하기
  • 같은 작업을 MEMORY.md 방식과 이 서버 방식으로 두 번 돌려 토큰 사용량과 맥락 복원 정도를 비교하라.
  • 결과가 비슷하면 단순한 파일 방식을 유지하라.
• 여러 프로젝트가 기억을 공유해야 하면 전역 저장소로 바꾸기
  • MCP 설정에 MCP_MEMORY_DB_PATH=~/.mcp_memory/memories.db를 넣어라.
  • MCP_MEMORY_DIR=~/.mcp_memory/memory도 같이 지정하라.

Try It

# Claude Code 터미널에서 실행 (설치 및 등록)

git clone https://github.com/fellowgeek/mcp-memory
cd mcp-memory
python3 setup.py

# 또는 Claude Code CLI에 직접 등록
claude mcp add --scope user memory -- $(pwd)/run.sh

# Claude Code 세션에서 붙여넣을 지시
# 세션을 시작하면 memory_get_last를 호출해 마지막 체크포인트를 읽어라.
# 작업 중 마일스톤을 끝내면 memory_update_last로 요약을 저장하라.
# 지금 key는 user/preferences/coding_style, content는 {{선호하는 코딩 스타일}}로 memory_store를 호출해라.

# 이어서 해 볼 것: 새 세션을 열고 memory_search로 query="{{키워드}}"를 검색해 보라.

Terminology

관련 논문

• 같은 시뮬레이션, 다른 근거: 도구 출력을 파일로 넘기면 LLM 에이전트 정확도가 어디서 깎이나

  긴 툴 출력을 파일로 넘기자 GPT-5.1은 정확도 11.3%p 하락, 정식 출력 지정하니 회복

• 가짜 뉴스가 진짜 폭락을: LLM 트레이딩 에이전트 대상 정보 주입 공격

  가짜 헤드라인 한 줄로 LLM 트레이딩 에이전트 62%를 조종했다(프롬프트 주입은 14%)

• Harness Engineering 101: LLM은 뇌, harness는 몸

  에이전트는 JSON 배열을 관리하는 루프이고, 16개 챕터로 직접 만들어 본다

• Harness²: 에이전트 harness를 스스로 고쳐 쓰는 재귀 최적화 프레임워크

  모델은 고정하고 harness를 재귀로 고쳤더니 벤치마크 점수가 최대 11.8%p 올랐다

• 해고된 Savannah 경찰관, ICE 요원 남편에게 Flock 계정 공유

  경찰관이 Flock 계정을 남편(ICE 요원)에게 공유했고, 감사에서 983건 검색이 드러나 해고됐다

• tmux와 Claude Code: 세션, send-keys, 그리고 한계선

  tmux로 Claude Code 여러 개를 돌리면 편하지만 에이전트 4개쯤에서 한계가 온다

• Hybrid Reasoning Agents: 잠재 공간에서 생각하고 텍스트로 행동하는 LLM 에이전트

  잠재 공간 추론과 텍스트 도구 호출을 섞었더니 성능 10.4%↑, 토큰 최대 54.7%↓

Related Resources

• https://github.com/fellowgeek/mcp-memory
• https://news.ycombinator.com/item?id=48900288#48901679
• https://markbase.cloud/
• https://rcarmo.github.io/projects/memento/