memtomem

AI 코딩 에이전트를 위한 마크다운 우선(Markdown-first) 장기 메모리 — 파일은 사용자 소유로 유지되며, 핵심 사용 방식은 기본적으로 후킹(hook-free) 방식으로 작동합니다.

Downloads

GitHub stars

Python 3.12+

License: Apache 2.0

CLA

Safety

🚧 Alpha — API, 기본값(defaults), 그리고 디스크 상의 설정 표면(on-disk config surfaces)은 0.x 릴리스 간에 변경될 수 있습니다. 피드백 및 이슈 보고가 특히 환영받습니다: Issues · Discussions.

memtomem은 사용자의 마크다운 노트, 문서 및 코드를 검색 가능한 지식 기반으로 변환하여 모든 AI 코딩 에이전트가 사용할 수 있게 합니다. 일반 .md 파일로 노트를 작성하면 — memtomem이 이를 인덱싱하고 키워드와 의미 모두로 검색 가능하게 만듭니다.

flowchart LR
    A["사용자 파일\n.md .json .py"] -->|인덱스| B["memtomem"]
    B -->|검색| C["AI 에이전트\n(Claude Code, Cursor 등)"]

처음 오셨나요? Getting Started 가이드를 따라 해보세요 — 5분 이내에 작동하는 환경을 구축할 수 있습니다. Claude Code 또는 Codex CLI 사용자인가요? Korean vibe-coding quickstart를 확인하세요.

memtomem을 사용하는 이유?

빠른 시작

1. 설치

uv tool install 'memtomem[all]'       # 또는: pipx install 'memtomem[all]'
mm --version                          # 설치 확인

[all]은 아래 섹션에서 설명하는 기능들 — ONNX 밀집 임베딩(dense embeddings), 한국어 토크나이저(Korean tokenizer), 코드 청커(code chunker), 그리고 웹 UI(Web UI)를 통합합니다. Ollama 및 OpenAI 임베딩 제공자(embedding providers)는 추가 설치가 필요 없습니다. 어떤 환경에 설치되어도 작동합니다. 해당 다운로드 없이 더 작은 설치(모델 다운로드 전 약 340 MB 대신 약 50 MB 설치)를 원한다면, 시작하기 가이드(Getting Started guide)의 최소 설치 옵션을 참조하십시오.

만약 mm --version이 최신 릴리스보다 오래된 버전을 보여준다면, uv가 캐시된 PyPI 메타데이터를 제공하고 있을 가능성이 높습니다. 다음 명령어로 다시 실행하거나 먼저 캐시를 지우십시오: uv tool install 'memtomem[all]' --refresh, 또는 uv cache clean memtomem. 기존의 uv 도구 설치를 업그레이드하려면 uv tool install을 다시 실행하는 대신 mm upgrade를 사용하십시오. 무엇이 유지되고 무엇이 중단되는지에 대한 내용은 CLI 참고 자료를 참조하십시오.

mm: command not found? uv tool install은 윔(shim)을 ~/.local/bin에 떨어뜨리는데, 이 경로는 macOS/Linux의 새 셸에서는 $PATH에 포함되어 있지 않습니다. uv tool update-shell을 실행한 다음 새로운 셸을 열고 mm --version을 다시 실행하십시오.

2. 설정(Setup)

Claude 플러그인을 업그레이드한 후: 로드(reloading) 후에 /mcp를 재확인하십시오.
이 플러그인은 memtomem[onnx]==0.6.8을 실행합니다. 수동으로 등록된 항목 중 실행 방식이 다른 경우 — 기본 전용(base-only)의 memtomem, 또는 이전 릴리스에 고정된 ONNX 실행 — 더 이상 중복 제거(deduplication)와 일치하지 않아 중복 도구(duplicate tools)를 노출할 수 있습니다. 수동 항목의 이름과 범위를 확인한 다음, 해당 실행 명령을 플러그인과 맞추거나 불필요한 등록을 제거하십시오.

mm init # 프리셋 선택기 후 memory_dir + MCP

대화형 피커는 세 가지 프리셋 — Minimal (BM25, 다운로드 없음), English (권장) (ONNX multilingual-e5-small + English reranker + 자동 디스커버리 제공자), Korean-optimized (ONNX multilingual-e5-small + kiwipiepy 토크나이저, reranker 없음) — 그리고 전체 10단계 마법사를 여는 Advanced 항목으로 시작합니다. 프리셋 경로는 메모리 디렉터리와 MCP 등록에 대해서만 질문하며, 나머지 모든 것은 해당 프리셋에서 설정됩니다.

가장 빠른 다운로드 없는 첫 번째 증명을 위해 Minimal을 선택하고; 시맨틱 검색 추가 준비가 되면 나중에 mm init을 다시 실행하세요.

인덱싱 대 디스커버리 (Claude Code): 자동 디스커버리를 설정하는 제공자 메모 폴더(예: ~/.claude/projects/*/memory/)는 검색 인덱스에 추가됩니다. 이는 Web UI의 ~/.claude/projects/에 대한 옵트인 Context Gateway 스캔과는 별개이며, 후자는 Skills, Custom Commands 및 Subagents를 위한 프로젝트 루트를 디스커버리합니다 — 차이점과 lossy-slug 주의사항은 Configuration → Context Gateway를 참조하세요.

자동화/CI의 경우:

mm init --non-interactive                   # minimal preset, 프롬프트 없음
mm init --preset korean --non-interactive   # Korean-optimized bundle, 프롬프트 없음
mm init --advanced                          # 전체 10단계 마법사 강제 실행

전체 모델/제공자 매트릭스는 Embeddings를 참조하세요.

<a id="3-use"></a>

3. 완전한 메모리 왕복(round trip) 검증

첫 번째 성공 경로는 기존 노트 디렉터리나 연결된 에디터를 요구하지 않습니다:

mm status
mm add "배포 체크리스트는 블루-그린 롤아웃을 사용합니다" --tags ops
mm search "blue-green"

mm add는 구성된 사용자 메모 디렉터리에 쓰기하고 해당 항목을 즉시 인덱싱합니다. 마지막 명령어는 방금 추가한 문장을 반환해야 합니다.

그런 다음 에디터 연결을 검증하세요:

"mem_status 도구를 호출하세요"

기존 노트를 동일한 인덱스로 가져오려면, mm index를 이미 존재하는 디렉터리를 가리키도록 설정하세요:

mm index /path/to/your/notes

mm status --json (또는 --format json)은 스크립트 및 CI를 위한 기계가 읽을 수 있는 출력과 동일한 상태 정보를 제공합니다.

<a id="4-web-ui-optional"></a>

4. 웹 UI 열기 (선택 사항)

mm web                # http://127.0.0.1:8080에서 세련된 대시보드 표시
mm web -b             # 백그라운드에서 실행; 로그는 ~/.memtomem/logs/web.log에 저장
mm web status         # pid/포트/시작 시간 표시
...

mm web은 기본적으로 세련된 페이지를 보여줍니다. --dev를 전달하거나 (또는 셸 프로필에서 MEMTOMEM_WEB__MODE=dev 설정) Sessions, Working Memory, Health Report와 같은 유지 관리자 페이지에 노출하려면 이 옵션을 사용하세요.

<a id="minimal-install"></a>
최소 구성 (Minimal) (번들 모델 없음, 약 50MB):

uv tool install memtomem             # 추가 기능(extras) 없음 — 나중에 추가할 때까지 로컬 ONNX 모델, 웹 UI 또는 한국어 토크나이저가 없으며; Ollama/OpenAI 임베딩은 여전히 작동함

필요한 기능별로 나중에 옵트인: uv tool install --reinstall 'memtomem[onnx,web]' ( 추가 기능 테이블 참조). --reinstall은 전체 세트를 대체하므로 유지하고 싶은 모든 추가 기능을 나열해야 합니다. 단순한 mm upgrade는 현재 설치에서 감지된 추가 기능을 유지하지만, 명시적인 mm upgrade --extras 목록도 전체 세트 이름을 지정해야 합니다.

프로젝트 범위 (Project-scoped) (프로젝트별 격리):

uv add 'memtomem[all]' && uv run mm init    # 모든 명령어는 `uv run` 접두사가 필요함

설치 없음 (No install) (필요시 uvx 사용):

claude mcp add memtomem -s user -- uvx --isolated --from "memtomem[all]==0.6.8" memtomem-server

OpenCode / Codex / Cursor / Antigravity / Windsurf / Claude Desktop / Gemini CLI / Kimi Code에 대한 내용은 MCP 클라이언트 설정을 참조하세요.

주요 기능 (Key Features)

• 하이브리드 검색 (Hybrid search) — 하나의 쿼리에서 BM25 키워드 + 밀집 벡터(dense vector) + RRF 융합을 결합

• 의미 기반 청킹 (Semantic chunking) — 헤딩 인식 마크다운, AST 기반 파이썬, tree-sitter JS/TS, 구조 인식 JSON/YAML/TOML 지원

• 점진적 인덱싱 (Incremental indexing) — 청크 레벨 SHA-256 차분(diff); 변경된 청크만 재임베딩

• 네임스페이스 (Namespaces) — 폴더 이름에서 자동 파생되는 범위별 그룹으로 메모리 정리; 웹 UI의 Settings → Namespaces에서 검토 및 레이블링(색상, 설명) 가능

• 유지보수 (Maintenance) — 근접 중복 감지, 시간 기반 감쇠(decay), TTL 만료, 자동 태그 지정

• 웹 UI (Web UI) — 검색, 소스, 태그, 타임라인, 중복 제거 등 시각적 대시보드 제공 (mm web --dev를 통해 전체 관리자 인터페이스 접근 가능)

• 컨텍스트 게이트웨이 (Context Gateway) — 프로젝트 또는 사용자 스토어에 표준화된 스킬(Skills), 명령어(Commands), 서브 에이전트를 유지하고, 선택적으로 별도의 위키에서 재사용 가능한 자산을 설치한 후 지원되는 AI 런타임으로 푸시합니다. Context Gateway를 참조하세요.

• MCP 도구 (MCP tools) — mem_do 메타 도구가 최소 컨텍스트 사용을 위해 core 모드의 모든 비핵심 동작을 라우팅합니다.

• 예측 가능한 핵심 기능 (Predictable core) — 메모리 작업은 명시적인 CLI/MCP 호출(mm add, mem_add, mem_index 등)로 실행됩니다. 선택적 클라이언트 훅(client hooks)은 숨겨진 런타임 기본값이 되는 대신 별도로 설치 및 제거됩니다.

• Scriptable CLI — 스크립트용 JSON 출력: mm status의 --json, 쓰기 명령어(mm add / mm reset / mm purge), mm session start / end / list / events, mm schedule list, mm watchdog status / run 및 mm doctor, 그리고 mm search와 mm recall의 --format json; mm warmup은 로컬 모델을 미리 로드하여 첫 번째 쿼리 시 콜드 스타트 비용을 건너뜁니다.

• 예약 작업 (Scheduled jobs) — 크론 기반 압축, 중요도 감쇠(importance decay), 데드 링크 정리 및 중복 제거 검색을 위한 mm schedule add/list/run-now/delete (또는 mem_do(action="schedule_*"))

• 고정 컨텍스트 (Pinned Context) — mm pinned compose를 사용하여 검색된 결과보다 앞서 작은 사용자/프로젝트/에이전트 Markdown 블록을 유지합니다.

• LangGraph Store — 선택적 MemtomemBaseStore는 LangGraph의 튜플 네임스페이스 장기 메모리 계약(long-term-memory contract)을 구현합니다.

• 하이브리드 LangGraph Store — MemtomemHybridStore는 전용 SQLite 영속성, BM25/dense/RRF 검색, TTL 및 진단 기능을 추가합니다.

생태계 (Ecosystem)

문서 (Documentation)

**memtomem.com**에 호스팅되어 있으며, 이 리포지토리에서도 Markdown으로 사용할 수 있습니다. memtomem이 처음이신가요? 가이드에는 권장 읽기 순서가 있습니다. 아래 표는 그 순서를 따르며, 두 개의 실행 가능한 예제는 첫 번째 실행 가이드 뒤에 배치되어 있습니다:

기여 (Contributing)

설정 지침 및 기여자 가이드는 CONTRIBUTING.md를 참조하십시오.

라이선스 (License)

Apache License 2.0. 기여는 Contributor License Agreement의 조건에 따라 수락됩니다.