Quick Start

memtomem은 AI 에이전트에 세션이 바뀌어도 사라지지 않는 기억을 붙여 주는 도구입니다. 에이전트는 MCP(AI 에이전트를 외부 도구·데이터에 연결하는 표준 방식)로 memtomem에 연결됩니다.

이 가이드는 가장 기본이 되는 흐름 하나를 먼저 완성하는 데 초점을 둡니다. 장기 기억을 맡는 LTM 서버를 설치하고 초기 설정을 마친 뒤, CLI에서 기억 하나를 저장하고 다시 검색합니다. 이 확인에는 기존 노트 폴더나 연결된 에이전트가 필요하지 않습니다. MCP 클라이언트 연결과 기존 파일 인덱싱은 기본 기억 흐름이 동작한 다음 진행하며, STM은 선택 사항입니다.

1. 설치

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

[all]은 웹 UI, 로컬 임베딩(ONNX), 코드 분할, 한국어 토크나이저, Ollama / OpenAI 클라이언트, Langfuse, LangGraph 어댑터를 포함합니다. 더 가벼운 BM25 전용 설치는 설치를 참고하세요.

설치 직후 mm --version이 예상보다 오래된 버전을 출력하면 패키지 메타데이터를 갱신하며 업그레이드하세요:

uv tool install 'memtomem[all]' --refresh

셸이 mm 자체를 찾지 못하면(command not found) uv tool update-shell을 실행하고 터미널을 다시 여세요 — 문제 해결 참고.

2. 초기 설정

mm init

mm init 마법사는 프리셋 피커로 시작합니다:

프리셋	적합한 상황	동작
Minimal	첫 스모크 테스트, 최소 설치	BM25 키워드 검색만 사용
English	영어 프로젝트 대부분	로컬 ONNX 임베딩 + 영어 리랭커
Korean	한국어 또는 다국어 노트	다국어 임베딩, 리랭커, 한국어 토크나이저

모델 다운로드 없이 가장 빠르게 확인하려면 Minimal을 선택하세요. 첫 검색까지 확인한 뒤 mm init을 다시 실행해 시맨틱 검색을 추가할 수 있습니다.

스크립트나 CI에서는 다음을 사용할 수 있습니다:

mm init --non-interactive                   # minimal 프리셋, 프롬프트 없음
mm init --preset english --non-interactive  # 영어 프리셋, 프롬프트 없음
mm init --preset korean --non-interactive   # 한국어 프리셋, 프롬프트 없음
mm init --advanced                          # 전체 마법사

설정 중 Claude Code 기억, Claude 플랜, Codex CLI 기억 같은 기존 AI 에이전트 메모리 폴더를 등록해 감시 대상으로 둘 수 있습니다. 등록은 이후 변경 감시를 위한 것이므로, 기존 파일은 mm index로 한 번 시드하세요.

mm init 마법사는 마지막에 memtomem을 MCP 클라이언트(예: Claude Code)에 자동 등록할지 물어봅니다. 여기서 수락하면 아래 4단계는 이미 끝난 셈이며, 이 프롬프트를 건너뛴 경우에만 아래 수동 단계가 필요합니다.

3. 기억 저장·검색 확인

먼저 CLI가 설정과 DB를 열 수 있는지 확인합니다:

mm status

청크 수가 0개여도 정상입니다. 이제 기존 폴더나 에이전트에 의존하지 않고 기억 하나를 저장한 뒤 다시 검색합니다:

mm add "배포 체크리스트는 blue-green 방식을 사용한다" --tags ops
mm search "blue-green"

검색 결과에 방금 저장한 문장이 나오면 성공입니다. mm add는 설정된 사용자 기억 디렉터리에 Markdown 파일을 쓰고 즉시 인덱싱합니다.

4. MCP 클라이언트 연결

mm init 마법사에서 “Claude Code 에 자동 등록”을 선택했다면 LTM(memtomem-server)은 이미 등록되어 있습니다 — LTM 추가 명령은 필요 없습니다.

수동 등록이 필요한 경우(자동 등록을 건너뛰었거나 다른 머신으로 옮긴 경우):

claude mcp add memtomem -s user -- memtomem-server

~/.cursor/mcp.json에 서버를 추가합니다:

{
  "mcpServers": {
    "memtomem": {
      "command": "uvx",
      "args": ["--from", "memtomem", "memtomem-server"]
    }
  }
}

command는 반드시 memtomem-server여야 합니다 — memtomem은 CLI이며 MCP 서버를 실행하지 않습니다.

~/.codeium/windsurf/mcp_config.json에 서버를 추가합니다:

{
  "mcpServers": {
    "memtomem": {
      "command": "uvx",
      "args": ["--from", "memtomem", "memtomem-server"]
    }
  }
}

command는 반드시 memtomem-server여야 합니다 — memtomem은 CLI이며 MCP 서버를 실행하지 않습니다.

설정 파일(macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json)에 서버를 추가한 뒤 Claude Desktop을 재시작합니다:

{
  "mcpServers": {
    "memtomem": {
      "command": "uvx",
      "args": ["--from", "memtomem", "memtomem-server"]
    }
  }
}

다른 클라이언트와 전체 옵션 목록은 MCP 클라이언트 설정을 참고하세요.

등록 후 에이전트에게 “mem_status를 호출해줘”라고 요청하세요. MCP 클라이언트가 터미널에서 확인한 서버를 제대로 실행하는지 검증할 수 있습니다. 에이전트에 memtomem 도구가 보이지 않으면 문제 해결을 참고하세요.

5. 기존 노트 인덱싱

기본 기억 왕복을 확인한 다음, 실제로 존재하는 노트·문서·코드 폴더를 인덱싱합니다:

mm index ~/notes
mm index ~/projects/my-app/docs

예시 경로를 실제 경로로 바꾸고, 해당 파일에 들어 있는 문구를 검색해 결과를 확인하세요.

이후 MCP 클라이언트에서는 자연어로 지시하면 됩니다:

에이전트에 지시	보통 호출되는 도구	결과
”memtomem 상태 확인”	`mem_status`	연결 및 인덱스 요약
”이 결정을 기억해줘…”	`mem_add`	마크다운 기억으로 저장
”이 docs 폴더 인덱싱해줘”	`mem_index`	기존 파일이 검색 가능해짐
”배포 체크리스트 검색”	`mem_search`	관련 기억 스니펫 순위 목록

6. Web UI 열기

mm web --open

기본 Web UI는 검색, 소스, 태그, 타임라인, 설정, Context Gateway를 다루는 사용자용 화면입니다. mm web --dev는 대부분의 사용자에게는 필요 없는 유지보수용 페이지를 추가합니다.

선택 사항: STM은 나중에 추가

memtomem-stm은 관련 기억을 자동으로 찾아 붙여 주는 서피싱과 도구 응답 압축을 담당하는 별도 프록시(에이전트와 실제 도구 사이의 중계 계층)입니다. 위 LTM 흐름이 동작한 뒤 추가하세요:

uv tool install memtomem-stm
mms init --mcp claude   # 업스트림 서버 하나를 입력받고, STM을 Claude Code에 등록

mms init은 업스트림 MCP 서버 하나(이름, prefix, command)를 추가하도록 안내한 뒤 3가지 클라이언트 등록(Claude Code / .mcp.json 작성 / 건너뛰기)을 제안합니다. 완료 후 읽기 전용 명령 3개로 설정을 확인하세요:

mms list      # 등록한 업스트림 목록(및 SURFACING 열)
mms status    # 설정 요약 — 프록시가 활성화되어 올바른 파일을 가리키는가?
mms health    # 업스트림 연결성과 LTM 서피싱 준비 상태 점검

Claude Code가 아닌 클라이언트에서는 한 줄 command 블록으로 STM을 수동 등록합니다:

{
  "mcpServers": {
    "mms": { "command": "mms" }
  }
}

STM의 프록시 도구는 <prefix>__<tool> 형태로 이름이 붙습니다. 등록 후 프록시 도구가 목록에서 사라졌다면, 대개 합쳐진 이름이 MCP의 64자 제한을 넘은 경우입니다 — 원인과 해결 방법(더 짧은 prefix, 또는 짧은 클라이언트 이름으로 등록)은 문제 해결을 참고하세요.

STM이 맞지 않으면 mms eject로 각 서버를 원래 호스트 설정으로 되돌릴 수 있으므로, 프록시 뒤로 옮기는 작업은 되돌릴 수 있습니다.

도구 응답 압축이나 자동 기억 주입이 필요해질 때 STM 개요를 참고하세요.

다음 단계

세션을 넘나드는 기억 — 한 세션에서 저장하고 다른 세션에서 불러오기
하이브리드 검색 — BM25 + 벡터 + RRF 융합
MCP 도구 — core, standard, full 도구 모드
Context Gateway — 에이전트, 스킬, 커맨드를 런타임 간 동기화하고, 프로젝트 사이에서 이동·복사하거나 여러 프로젝트를 한 번에 동기화
문제 해결 — command not found, 도구 누락, 서피싱 미작동 해결