AI 에이전트가 "어제 우리가 무슨 얘기 했지?"를 기억하는 방법은 보통 클라우드 메모리 서비스를 부르는 것이다. Honcho·Zep·MemGPT 같은 외부 HTTP API에 매번 왕복하면서 수십~수백 밀리초씩 까먹는다. Mnemosyne은 정반대 베팅을 한다 — SQLite 파일 한 개 + Python 표준 라이브러리로 모든 걸 처리해 ~2-10ms(in-process, 10K corpus)의 로컬 검색을 달성하고, 그러면서도 LongMemEval 벤치마크에서 98.9% 회상률로 클라우드 솔루션과 어깨를 나란히 한다. Nous Research의 Hermes 에이전트 플러그인으로 태어났지만 단독으로도 동작한다.
무엇을 하는 프로젝트인가.
일반적인 챗봇은 대화창이 닫히면 모든 걸 잊는다. 다음 날 같은 챗봇에게 "어제 내가 어떤 편집기 좋아한다고 했지?"라고 물어도 모른다. 메모리를 외부에 붙이려면 보통 클라우드 벡터DB(Pinecone·Weaviate)나 메모리 SaaS(Honcho·Zep)를 끼워 넣어야 한다. Mnemosyne은 그걸 전부 ~/.hermes/mnemosyne/data/mnemosyne.db 단일 SQLite 파일로 대체한다. HTTP 호출 0회, API 키 0개, 클라우드 비용 0원.
그러면서도 단순한 키-값 저장소가 아니라 벡터 검색 + 전문 검색 + 시간 그래프 + 자동 압축까지 다 들어있다. 그리스 신화의 기억의 여신 므네모쉬네에서 이름을 따왔고, 뮤즈의 어머니로 알려져 있다.
pip install mnemosyne-hermes 후 플러그인 링크 생성으로 ~/.hermes/plugins/mnemosyne/에 등록되어 매 LLM 호출 직전에 관련 기억을 알아서 주입한다.트렌딩 이유, 경쟁 제품 대비 장점.
2026년 5월 26일 TrendShift 일간 5위. 스타 수는 아직 76개로 적지만, 다음 세 가지가 동시에 맞아떨어져 트렌딩에 진입했다.
Honcho(plasticlabs)·Zep·MemGPT 모두 본질적으로 HTTP API + 클라우드 PostgreSQL/벡터DB다. 비용·지연·개인정보 노출 세 가지 문제가 동시에 있다. Mnemosyne은 로컬 SQLite로 네트워크 왕복 없이 ~2-10ms(in-process)에 처리하면서 LongMemEval 96.6%(Mempalace)·98.9%(Mnemosyne)로 정확도 면에서도 클라우드를 따라잡았다.
SQLite 진영에는 2024년 즈음부터 sqlite-vec(벡터 검색)와 FTS5(전문 검색)가 들어왔지만 둘을 하나의 쿼리에서 합쳐 쓰는 표준 패턴이 없었다. Mnemosyne은 50% 벡터 유사도 + 30% FTS 랭크 + 20% 중요도 공식으로 하이브리드 검색을 1급 시민으로 만들었다. 2000개 메모리에서도 검색이 7ms 안에 끝난다.
mnemosyne_sleep() 한 줄을 호출하면 오래된 working_memory를 자동으로 요약·압축해 episodic_memory로 옮긴다. 사람이 자는 동안 단기기억이 장기기억으로 정리되는 신경과학적 가설(memory consolidation)을 그대로 코드로 옮긴 셈. 다른 메모리 시스템들이 "오래된 거 그냥 자르기"인 반면, Mnemosyne은 요약하고 인덱스 다시 만들어 의미는 살리고 토큰만 줄인다.
| 시스템 | 저장소 | 읽기 지연 | LongMemEval | 요금 |
|---|---|---|---|---|
| Honcho | 클라우드 PG | 38ms | N/A | Freemium → $$$ |
| Zep | 클라우드 | 62ms | N/A | Freemium → $$$ |
| MemGPT | 로컬+클라우드 | 95ms | N/A | 무료~$ |
| Mempalace | 로컬 Chroma+SQLite | 5~20ms | 96.6% R@5 | 무료 |
| Mnemosyne | 로컬 SQLite | ~2-10ms | 98.9% R@All@5 | 무료 |
README의 "Zero-Dependency"는 core 패키지가 numpy·torch·scikit-learn 없이 동작한다는 뜻. 하지만 98.9%라는 벤치마크 점수는 fastembed + BAAI/bge-small-en-v1.5 모델이 깔려 있을 때만 나온다. 없으면 키워드 검색만 되고 LongMemEval 점수는 0.0%로 떨어진다(같은 문장을 다르게 표현하면 잡지 못함). 진짜 의미는 "embedding 백엔드를 fastembed/ctransformers/llama-cpp 중 골라 끼울 수 있고, 핵심 흐름은 그것 없이도 돈다"는 모듈성에 가깝다.
백엔드·임베딩·통합 레이어 각각 상세.
이 프로젝트의 가장 큰 베팅은 "SQLite로 다 한다"이다. setup.py의 install_requires는 사실상 비어 있다. 모든 핵심 기능이 Python 표준 라이브러리(sqlite3·json·uuid·hashlib·pathlib)와 SQLite 확장으로 끝난다.
__getattr__)으로 임베딩 백엔드가 없어도 core가 동작RETURNING·STRICT·UPDATE FROM 같은 모던 기능 활용vec0 가상 테이블로 HNSW 스타일 검색CREATE VIRTUAL TABLE vec_episodes USING vec0(embedding float[384])처럼 가상 테이블을 만들면 그 안에서 코사인 유사도·내적 같은 벡터 연산을 표준 SQL로 쓸 수 있다. 별도 벡터DB(Pinecone·Weaviate)를 띄울 필요가 없게 만든 게 핵심.CREATE VIRTUAL TABLE fts_episodes USING fts5(content)로 만들면 SELECT ... WHERE fts_episodes MATCH 'hermes 에이전트' 같은 쿼리로 BM25 점수가 자동 매겨진 결과를 가져온다. 한국어는 토크나이저가 약하지만 영어·로마자 기반 텍스트에서는 매우 빠르다.의미 검색을 활성화하려면 텍스트를 숫자 배열(벡터)로 바꿔야 한다. Mnemosyne은 PyTorch 의존성이 무거운 sentence-transformers 대신 ONNX Runtime만 쓰는 fastembed를 채택했다. 모델은 384차원짜리 bge-small-en-v1.5를 기본으로 쓴다 — 작지만 LongMemEval 98.9%를 달성한 그 모델이다.
옵션으로 ctransformers·llama-cpp-python·huggingface-hub 같은 LLM 백엔드도 끼워서 자체 추출(entity extraction)·요약(consolidation)에 활용한다.
Mnemosyne 코어 한 덩어리를 4개의 다른 인터페이스로 동시에 노출한다. 이는 같은 메모리 DB를 어떤 도구에서 접근해도 동일하게 보이게 만드는 핵심 설계.
hermes_memory_provider/plugin.yaml에 20개 도구 + 3개 훅(pre_llm_call·on_session_start·post_tool_call) 선언. 매 LLM 호출 직전에 관련 기억 자동 주입mnemosyne/mcp_server.py에서 Model Context Protocol(Anthropic 표준)로 노출. Claude Desktop·Cursor·다른 MCP 클라이언트에서 같은 메모리에 접근 가능from mnemosyne import remember, recall 직접 임포트해서 자체 에이전트에 박아 넣기python -m mnemosyne.cli store/recall/update/stats 터미널에서 직접 메모리 조작list_tools·call_tool 같은 JSON-RPC 메시지로 서버와 LLM이 대화한다. Mnemosyne을 MCP 서버로 띄우면 Claude Desktop이 같은 메모리 파일을 자기 도구처럼 쓸 수 있다.BEAM 3계층 + 하이브리드 검색 + sleep 사이클.
Mnemosyne v3에서 도입된 핵심 아이디어. 기존에는 "메모리 한 테이블에서 전부 LIMIT 1000으로 긁어 Python에서 점수 매기기"였는데, 이게 1000개 넘으면 선형으로 느려졌다. BEAM은 인간의 단기/장기 기억 구조를 흉내내 3계층으로 쪼갰다.
최근에 들어온 메모리. 매 LLM 호출 직전에 pre_llm_call 훅이 이 테이블에서 N개를 골라 시스템 프롬프트에 자동으로 끼워 넣는다. "오늘 아침에 사용자가 한 말"이 여기에 머문다.
오래된 working_memory가 sleep()으로 압축되어 옮겨오는 곳. 모든 메모리는 384차원 임베딩이 함께 저장되어 vec_episodes 가상 테이블에 인덱싱되고, 동시에 텍스트는 fts_episodes에 등록된다. 검색 시 벡터 유사도 50% + FTS 랭크 30% + 중요도 20%로 점수가 매겨진다.
에이전트가 작업 중간에 "잠깐 메모해두자"라고 적어두는 공간. mnemosyne_scratchpad_clear로 한 번에 비우거나 작업 종료 시 자동 정리. 사람으로 치면 책상 위 포스트잇.
BEAM 3계층 = 사람의 책상 + 책장 + 포스트잇. 지금 보고 있는 자료는 책상 위(working_memory), 보관용 자료는 책장(episodic_memory), 임시 메모는 포스트잇(scratchpad). 잘 때(sleep) 책상 위 자료를 정리해서 책장에 꽂아 넣는다. 누가 "그거 어디 있더라?" 물으면 책장에서 의미 + 키워드 + 중요도 점수로 찾아온다.
Mnemosyne의 recall() 함수가 호출되면 다음 한 줄짜리 SQL이 실행된다 (개념적 단순화).
왜 50/30/20일까? 벡터만 쓰면 동의어는 잡지만 정확한 고유명사가 약하고, FTS만 쓰면 표현이 다르면 못 잡고, 중요도만 쓰면 옛 메모리가 새 정보를 덮어버린다. 세 신호를 5:3:2로 합치는 게 LongMemEval 벤치마크에서 가장 안정적이었다는 결론이다.
사람의 수면 중 일어나는 기억 강화(memory consolidation) 가설을 그대로 구현한 메커니즘.
mnemosyne/core/aaak.py에 정의된 컨텍스트 압축 방언. LLM이 별도 디코더 없이 곧바로 파싱할 수 있는 무손실 단축 표기.
| 원본 자연어 | AAAK 압축 |
|---|---|
| PREFERENCE: Imperial units for GPS, 12-hour time format | PREF|imperial-units→GPS|12h-timefmt |
| User prefers Neovim over Vim | PREF Neovim>Vim |
| User has a Full-stack developer role and Real-time experience | HAS FSDEV+RT |
| Location: America/New_York | LOC|America/New_York |
카테고리 13종(PREF·TRAIT·STAT·INST·PROJ·LOC·FAM·OCC·DEC·EVT·TOOL·FACT·OPN) + 관용구 사전(PHRASE_MAP) + 구조 치환(쉼표→파이프, "for"→화살표, "and"→플러스) 3단계로 압축. 평균 14.9% 토큰 절감이라고 한다.
mnemosyne/core/triples.py에 구현된 "언제 사실이었나"를 기록하는 그래프. 일반 메모리는 "Maya는 auth-migration을 맡고 있다"라고 적지만, 그게 영원한 진실은 아니다. Temporal Triples는 시작 시각(valid_from)·종료 시각(valid_to)·신뢰도를 함께 저장한다.
주요 폴더/파일의 역할.
주목할 점 — core/beam.py가 ~401KB 단일 파일로 압도적으로 크다. 이건 의도적 모놀리스 선택이다. 3계층 메모리 + 하이브리드 검색 + sleep 사이클이 한 클래스 안에서 SQLite 트랜잭션을 공유하기 때문에 분리하면 락(lock) 문제가 생긴다. 한편 orchestrator.py가 681바이트로 가장 작은데, BEAM 엔진이 거의 모든 일을 직접 처리하기 때문에 별도 조정자가 필요 없다는 뜻이다.
이 레포를 공부할 때 beam.py를 위에서 아래로 읽으면 무리다. 진입점은 core/memory.py의 remember()·recall()이다. 거기서 BEAM 엔진을 호출하는 부분만 찾아 들어가는 게 효율적. beam.py는 "라이브러리"가 아니라 "설계 도큐먼트"에 가깝다고 보면 된다.
각 기술에서 배울 것 + 실습 아이디어.
왜 배워야 하나: 2026년 현재 LLM 앱 한 개 만들 때마다 Pinecone·Weaviate·Qdrant 같은 별도 벡터DB를 띄우는 게 표준이 됐는데, 데이터셋이 10만 행 미만이면 사실 SQLite + sqlite-vec로 충분하다. Mnemosyne은 그 가능성을 가장 깔끔하게 보여주는 참조 구현.
실습 아이디어: 자기 메모장 앱(블로그 글·읽은 책 메모)을 SQLite + sqlite-vec로 만들기. fastembed로 임베딩 → vec0 가상 테이블에 INSERT → 의미 검색 CLI 한 줄로 끝.
왜 배워야 하나: 벡터 검색만 쓰는 RAG는 고유명사(사람 이름·코드 변수명)에 약하다는 게 2025년 후반에 널리 인정됐다. 50/30/20 같은 단순 가중 결합이 의외로 강하다.
실습 아이디어: 자기 GitHub 이슈를 FTS5 + vec0 두 인덱스에 동시 등록 → 같은 쿼리를 벡터만·FTS만·하이브리드로 비교해 어디서 격차가 나는지 측정.
왜 배워야 하나: __init__.py에서 무거운 의존성을 즉시 import하면 pip install 직후의 셋업 명령조차 실패할 수 있다. Mnemosyne은 __getattr__ 모듈 레벨 함수로 호출 시점까지 import를 늦춘다.
실습 아이디어: 자기 라이브러리의 __init__.py를 __getattr__로 다시 짜서 import mylib 호출 시간이 얼마나 줄어드는지 timeit으로 측정.
왜 배워야 하나: hermes_memory_provider/plugin.yaml이 도구·훅을 선언하면 Hermes가 자동 로드한다. 같은 패턴이 VSCode 확장·Claude Code 플러그인·MCP 서버에서 반복된다 — "매니페스트로 외부 기능 발견"이라는 패턴이 사실상 업계 표준.
실습 아이디어: 자기 CLI 도구에 ~/.mytool/plugins/*.yaml를 스캔해 동적 로드하는 메커니즘을 붙여보기.
왜 배워야 하나: 같은 백엔드를 Python API + CLI + MCP 서버 세 가지로 동시 노출하는 게 2026년 라이브러리 표준 빌드 패턴이 됐다. Mnemosyne의 mcp_server.py + mcp_tools.py 분리가 그 좋은 예.
실습 아이디어: 자기 데이터(가계부·운동 로그)를 MCP 서버로 노출해 Claude Desktop에서 "이번 달 식비 얼마야?" 물어보기.
왜 배워야 하나: LLM 토큰은 곧 돈이다. 일반적인 압축(gzip)은 LLM이 못 푼다. Mnemosyne의 AAAK는 "LLM이 자연어처럼 그대로 읽을 수 있는 약속된 단축 표기"로 평균 15% 토큰을 줄인다. 도메인이 좁을수록 효과가 크다.
실습 아이디어: 자기 도메인(예: 운동 일지)에 맞는 단축 사전을 만들어 매 LLM 호출에서 절감되는 토큰 수 측정.
실제로 돌리려면 무엇이 필요한가.
"메모리 10만 개 = 종이 100권 분량의 일기". 일반인이 평생 SNS·일기·메모로 남기는 모든 텍스트가 대략 이 정도. Mnemosyne 한 DB로 평생 메모리를 담아도 라즈베리파이에서 검색이 10ms 안에 끝난다.
난이도별 5개 — 별 ★ 하나가 한 단계.
pip install mnemosyne-memory fastembed → mnemosyne CLI 실행 → store "사용자는 다크 모드를 선호한다" --importance 0.9 → recall "interface preferences"로 의미 검색 확인. 같은 메모리를 키워드 검색 vs 의미 검색으로 비교해 보기.
매일 5~10개 일기를 store로 넣고, "지난주에 행복했던 순간들"을 recall로 검색. importance를 조정해 가며 검색 순위가 어떻게 변하는지 관찰. stats로 working_memory vs episodic_memory 분포 확인.
pip install "mnemosyne-memory[mcp]" 후 Claude Desktop의 claude_desktop_config.json에 {"command":"python","args":["-m","mnemosyne.mcp_server"]} 추가. Claude에게 "내 메모리 검색해줘"라고 부탁해 17개 도구가 자동 노출되는지 확인. 본인의 일기·노트·코딩 메모를 채워 넣고 Claude에게 "어제 무슨 코딩 했지?" 같은 질문하기.
beam.sleep()의 동작을 분석해 같은 패턴을 자기 일기장 앱에 이식. LLM 요약은 OpenAI API 또는 로컬 llama-cpp-python 둘 다 시도. 압축 전후의 토큰 수 변화와 검색 결과 품질을 측정해 "sleep을 언제 돌릴지" 임계값을 결정.
TripleStore를 import 해서 가족 구성원의 거주지·직장·관계를 valid_from/valid_to와 함께 입력. as_of="2026-01-15"로 특정 시점의 상태를 쿼리. 모순 감지(contradiction detection)가 어떻게 동작하는지 veracity_consolidation.py를 읽고 분석. 추가로 자기 GitHub 커밋 로그를 triples로 임포트해 "2026년 1월에 어떤 PR이 열려 있었지?" 질의 만들기.
주차별 학습 계획 — 4주 풀스택 메모리 엔진 마스터.
| 주차 | 주제 | 학습 자료 + 실습 |
|---|---|---|
| 1주차 | SQLite + sqlite-vec 기초 | 공식 FTS5 문서 + sqlite-vec GitHub 읽기. 1만 개 위키 문서를 임포트해 벡터+FTS 인덱스 만들기. Mnemosyne의 core/embeddings.py + 마이그레이션 SQL 살펴보기. |
| 2주차 | 임베딩 모델 + RAG 파이프라인 | BAAI/bge-small-en-v1.5 모델 카드 + ONNX 변환 과정 학습. fastembed 소스 5분 만에 훑기. 자기 문서로 RAG 만들어 GPT-3.5/4와 비교. |
| 3주차 | MCP 프로토콜 + Hermes 플러그인 | Anthropic MCP 스펙(modelcontextprotocol.io) 정독. Mnemosyne의 mcp_server.py와 hermes_memory_provider/__init__.py를 비교해 두 호스트(MCP vs Hermes)에 어떻게 같은 백엔드가 노출되는지 분석. 본인 도구를 MCP로 만들어 Cursor + Claude Desktop 양쪽에 연결. |
| 4주차 | Memory Consolidation 알고리즘 | LongMemEval 논문(ICLR 2025) + Mempalace·Hindsight·MemGPT 비교 표 읽기. core/veracity_consolidation.py(40KB)를 한 함수씩 따라가며 모순 감지 + 통합 알고리즘 이해. 자기 도메인(예: 학습 일지)에 맞는 sleep 사이클 직접 구현. |
"순서대로 가지 말고 자기 문제부터 풀어라". 위 로드맵은 깊이 순서다. 하지만 "내가 매일 쓰는 메모장에 이걸 어떻게 붙이지?"라는 구체적인 문제 의식이 없으면 어떤 기술도 손에 안 잡힌다. 1주차 시작 전에 자기가 평소에 쓰는 도구(노션·옵시디언·메모장 앱) 중 하나를 골라 "여기에 Mnemosyne 같은 메모리를 붙인다면?"이라는 가설을 먼저 세우자.
이 레포에서 자주 등장하는 주요 기술 용어 정리.
더 깊이 파고들 자료.