로컬 MARKDOWN 메모리 / v0.7.0

다음 세션에도
이어지는 기억.

에이전트가 새로 시작해도 노트까지 잊을 필요는 없습니다. 로컬 Markdown에 기억을 남기고, 시작할 때는 지도를, 필요할 때는 상세 문서를 읽으세요.

설치하기 측정 근거 보기

pip install birkin-mnemosyne

your vault/디스크 위의 Markdown
INDEX

항상 읽는 완전한 지도. 언제 어떤 문서를 읽을지 알려줍니다.

프로젝트 노트

전체 저장소 대신, 작업에 필요한 문서를 끝까지 읽습니다.

세션 인계 노트

작업, 결정, 미해결 항목과 다음 단계.

구성 요소의 관계를 보여주는 개념도입니다. INDEX와 세션 인계는 선택 기능이며, 호스트가 시작·체크포인트 호출을 연결해야 합니다.

01 / 지도는 항상, 문서는 필요할 때

저장소 전체 대신 필요한 맥락을.

새 세션에는 이전 작업으로 돌아갈 길이 필요합니다. 모든 노트를 처음부터 넣으면 지금 작업과 무관한 내용에도 컨텍스트를 쓰게 됩니다.

시작할 때 완전한 INDEX

선택 기능인 INDEX는 “언제 읽을지 → 어떤 문서인지” 경로를 모두 유지합니다. 큰 지도는 완전한 주제별 보기를 사용할 수 있습니다. 소프트 예산을 넘으면 경고할 뿐, 경로를 조용히 없애지 않습니다.

INDEX 사용 가이드 읽기 ↗

작업에 필요할 때 상세 문서

정확한 트리거로 문서 전체를 엽니다. 작업에 묶인 시작 읽기는 어휘로 일치한 모든 문서를 완전히 반환합니다. 일반 검색은 다국어 BM25, 사용량 기반 감쇠와 구역 우선순위를 씁니다. 어휘 일치는 의미 일치를 보장하지 않습니다.

다음 세션을 위한 인계

프로젝트·작업별 불변 체크포인트에 작업, 결정, 미해결 항목, 질문, 다음 단계와 링크를 남깁니다. 범위가 지정된 시작 읽기는 최신 기록 전체를 포함합니다. MCP 클라이언트는 캡처·재개 호출을 직접 관리하고, Hermes는 선택형 생명주기 콜백을 제공합니다.

라벨과 미리보기부터 시작하는 초기화

읽기 쉬운 namespace:value 라벨은 순위 점수에 들어가지 않고 후보 노트를 필터링합니다. mnemosyne init은 명시적으로 적용하기 전에 정리·가져오기 계획을 보여줍니다. 노트를 자동으로 병합·보관·삭제하지 않습니다.

02 / 측정값과 단서를 함께

시작 컨텍스트는 줄어도,
모든 비용이 줄지는 않습니다.

문서에 공개된 실험 결과입니다. 사용자의 저장소나 에이전트 답변에 대한 보장은 아닙니다.

최신 공개 재실행 · 2026-10-11

45,128 → 1,297

전체 시작 페이로드, o200k_base 토큰.
가상의 대형 노트 코퍼스, main 876ad40.

상주 INDEX만 세면 144토큰이며, 30개 경로와 원본 155,749바이트는 모두 유지됩니다. 별도의 고정된 Sol·Claude 답변 세트는 각각 12/12를 유지합니다. 정확도 향상이 아닙니다.

최신 측정 결과 읽기 ↗

작은 노트를 읽을 때의 비용

작은 노트의 합산 작업 비용은 Sol 199–221토큰(12/12가 원문 전체보다 비쌈), Claude 229–432토큰(0/12가 더 비쌈)입니다. 서로 별개인 측정이며, 대형 코퍼스의 작업 정확도를 뜻하지 않습니다.

과거 v0.6.0 측정

이전 가상 대형 노트 결과는 전체 시작 페이로드 45,128 → 1,781 o200k_base 토큰이었습니다. 정확도 향상은 없었습니다. 당시 별도의 작은 노트 픽스처에서는 Sol 12개 전부와 Claude 12개 중 7개 작업이 원문 전체를 읽는 것보다 비쌌습니다.

과거 결과와 한계 읽기 ↗

인계와 라벨도 컨텍스트를 사용합니다

Windows 형식 키를 쓴 인계 픽스처는 추정 163 → 919토큰(+756), 별도의 라벨 픽스처는 1,052 → 1,076토큰(+24)으로 늘었습니다. 모델 토크나이저가 아닌 ceil(UTF-8 바이트 / 4) 추정입니다. 서로 다른 픽스처이므로 보편적인 총비용으로 더하면 안 됩니다.

선택형 검색에도 비용과 손실이 있습니다

의미 검색은 선택 기능이며 권장 기본값이 아닙니다. 일부 테스트 구간에서 코어보다 낮은 결과를 냈습니다. Linux 재실행의 설치 크기는 0.38 → 80.24 MB였고, 원본·압축 모델 파일 669.1 MB는 별도입니다. 최대 색인 메모리 증가분 163 MB는 150 MB 예산을 넘었습니다. 서비스 수준 보장이 아닙니다.

호스트가 작성하는 질의 확장은 검색마다 약 115–200 출력 토큰과 약 두 배의 순위 계산 시간을 씁니다. 기본 코어의 한국어 검색은 개선되지 않았으며, 합성 결과는 다른 프로젝트 대비 우위나 답변 정확도, 보편적인 다국어 지원을 입증하지 않습니다.

문서에 공개된 모든 한계 읽기 ↗

03 / 지금 쓰는 에이전트와 연결

하나의 저장소, 여러 연결 방식.

저장소는 로컬에 둡니다. 문서화된 어댑터를 선택하거나 Python API를 직접 에이전트에 연결하세요.

MCP 클라이언트

선택형 stdio 서버로 Claude Code, Claude Desktop, Codex CLI, Cursor 등 MCP 클라이언트를 연결합니다. 설정 가이드가 모든 IDE를 실제 실행·검증했다는 뜻은 아닙니다.

클라이언트별 설정 선택하기 ↗

Hermes

외부 메모리 제공자는 Hermes 프로필별 별도 저장소에 로컬 Markdown을 씁니다. 세션 종료·압축 전의 범위별 인계 캡처는 선택 기능입니다.

Hermes 제공자 설정하기 ↗

omo

MCP 도구로 검색하고 시작 문서를 완전히 읽습니다. 체크포인트를 명시적으로 캡처한 뒤 같은 프로젝트·작업 키로 재개하세요. 이 생명주기는 호출자가 관리합니다.

체크포인트 계약 읽기 ↗

04 / 평범한 파일로 시작

설치하고, 미리 보고, 적용하세요.

Python 3.10 이상이 필요합니다. 코어는 모델·API 키·런타임 의존성 없이 노트를 저장하고 검색합니다.

코어 설치

pip install birkin-mnemosyne

mnemosyne init --vault my_vault
mnemosyne init --vault my_vault --apply

첫 init 명령은 읽기 전용 미리보기입니다. 계획을 확인한 뒤 적용하세요. --vault가 없으면 현재 디렉터리를 사용합니다.

PyPI에서 패키지 보기 ↗

MCP 클라이언트 연결

uvx --from "birkin-mnemosyne[mcp]" \
  mnemosyne-mcp --vault ~/mnemosyne

MCP 추가 패키지는 처음 실행할 때 공식 SDK를 내려받습니다. 클라이언트에 이 stdio 명령을 설정하세요. 같은 저장소를 지정하면 클라이언트끼리 기억을 공유합니다.

전체 설정 방법 읽기 ↗

05 / 다시 업스트림으로

로컬 실험에서
함께 쓰는 개선으로.

광훈은 에이전트 메모리의 한국어 처리 문제를 해결하려고 이 작업을 시작했습니다. README에는 이 작업에서 파생된 기여와 2026-10-11 KST 기준 상태가 기록되어 있습니다.

전체 기여 기록과 단서 읽기 ↗