memem

Claude Code를 위한 지속적이고 스스로 진화하는 메모리. 매 세션마다 프로젝트를 다시 설명하는 일을 멈추세요.

LLM/AI 도구 검색은 llms.txt를 참조하세요.

  ███╗   ███╗███████╗███╗   ███╗███████╗███╗   ███╗
  ████╗ ████║██╔════╝████╗ ████║██╔════╝████╗ ████║
  ██╔████╔██║█████╗  ██╔████╔██║█████╗  ██╔████╔██║
  ██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║
  ██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║
  ╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝
  persistent memory for Claude Code

memem이란 무엇인가요?

memem은 Claude Code가 세션 간에 지속적인 메모리를 유지할 수 있도록 해주는 Claude Code 플러그인입니다. 백그라운드 마이너가 완료된 세션에서 지속 가능한 교훈(결정, 관례, 버그 수정, 선호 사항)을 추출하여 Obsidian 볼트에 마크다운으로 저장하고, 각 새 세션이 시작될 때 쿼리에 맞춘 브리핑을 통해 관련 내용을 자동으로 제공합니다.

로컬 우선(local-first) 방식입니다: 클라우드 서비스나 API 키가 필요 없으며, 특정 업체에 종속되지 않습니다. 모든 데이터는 ~/obsidian-brain/memem/memories/에 사람이 읽을 수 있는 마크다운 형태로 저장됩니다.

memem은 언제 사용해야 하나요?

다음과 같은 경우 memem을 사용하세요:

• Claude Code를 매일 사용하며 매번 새로운 세션마다 프로젝트를 다시 설명해야 하는 경우

• 마크다운으로 찾아보고 편집할 수 있는 지속적인 메모리를 원하는 경우

• 업체 종속이 전혀 없는 로컬 우선 도구를 선호하는 경우

• 이미 Obsidian을 사용 중인 경우 (memem은 볼트에 바로 연결됩니다)

다음과 같은 경우 memem을 건너뛰세요:

• CLAUDE.md로 충분하며 백그라운드 데몬을 원하지 않는 경우

• 여러 기기 간에 클라우드 동기화된 메모리가 필요한 경우 (memem은 로컬 전용입니다)

• Python 3.11 미만 버전을 사용하는 경우

memem은 CLAUDE.md와 어떻게 다른가요?

CLAUDE.md는 프로젝트당 하나씩 수동으로 편집하는 파일입니다. memem은 다음을 제공합니다:

• 자동 추출 — 수동으로 메모할 필요가 없으며, 마이너가 완료된 모든 세션에서 교훈을 포착합니다.

• 쿼리 인식 컨텍스트 — 정적인 덤프가 아니라 현재 질문과 관련된 메모리만 주입됩니다.

• 스스로 진화 — 프로젝트가 발전함에 따라 메모리가 자동으로 병합, 업데이트 및 폐기됩니다.

• 프로젝트 간 공유 — 특정 리포지토리에 국한되지 않고 사용하는 모든 Claude Code 프로젝트에서 작동합니다.

• 보안 스캔 — 모든 쓰기 작업은 프롬프트 인젝션 및 자격 증명 유출 여부를 스캔합니다.

• 탐색 가능 — 그래프 뷰와 백링크를 무료로 제공하는 Obsidian 볼트.

memem은 어떻게 설치하나요?

/plugin marketplace add TT-Wang/memem
/plugin install memem

이것으로 끝입니다. 첫 실행 시 bootstrap.sh가 모든 것을 스스로 복구합니다:

1. Python ≥ 3.11 확인

2. uv가 없으면 설치 (공식 Astral 설치 프로그램 사용)

3. 플러그인 로컬 .venv에 종속성 동기화 (uv.lock 기준 해시 캐시)

4. ~/.memem/ 및 ~/obsidian-brain/ 생성 및 카나리 테스트

5. ~/.memem/.capabilities 작성 (저하 모드 결정에 사용)

6. 실제 MCP 서버 실행

첫 실행: 약 5초. 이후 모든 실행: 약 100ms. 별도의 pip install 단계가 없습니다.

첫 Claude Code 세션에서는 무슨 일이 일어나나요?

첫 메시지를 입력하면 UserPromptSubmit 훅이 실행되어 메모리가 없음을 확인하고(방금 설치했으므로), Claude의 컨텍스트에 환영 배너를 주입합니다. Claude는 배너를 읽고 memem이 활성화되었음을 알려주며, 기존 Claude Code 세션이 있는 경우 /memem-mine-history를 통해 마이닝할 것을 제안합니다.

평소처럼 작업하세요. 마이너 데몬은 백그라운드에서 조용히 실행됩니다. 세션이 종료되고 5분 동안 유휴 상태가 되면, 마이너는 Claude Haiku를 사용하여 기록에서 메모리를 추출하고 볼트에 기록합니다.

두 번째 세션부터: 훅이 첫 메시지를 context_assemble로 보내고, 이는 Haiku에게 관련 메모리를 제공하여 맞춤형 브리핑을 작성하도록 요청합니다. [memem] 12 memories · miner OK · assembly OK와 같은 상태 배너와 함께 브리핑이 표시됩니다. Claude는 전체 컨텍스트를 가지고 시작하므로 다시 설명할 필요가 없습니다.

memem은 무엇을 저장하나요?

세션 로그가 아닌 지속 가능한 지식을 저장합니다:

• 아키텍처 결정 및 근거 ("...하기 때문에 RS256 JWT를 사용함")

• 관례 ("테스트는 spec/이 아니라 tests/에 위치함")

• 잊기 쉬운 버그 수정 ("bcrypt.compare는 비동기이므로 await를 사용해야 함")

• 사용자 선호 사항 ("스택형 PR이 아닌 단일 커밋을 선호함")

• 알려진 문제 ("JWT_SECRET이 설정되지 않으면 'secret'으로 기본값 지정됨 — #123에서 추적 중")

다음은 저장하지 않습니다:

• 원시 세션 기록 (이는 transcript_search를 통해 검색 가능하며 메모리로 저장되지 않음)

• 사소하거나 명백한 사실

• 세션 결과 ("오늘 나는 X에 대해 작업함")

memem은 메모리를 어디에 저장하나요?

MEMEM_DIR 및 MEMEM_OBSIDIAN_VAULT 환경 변수를 통해 memem의 저장 위치를 변경할 수 있습니다.

Claude가 호출할 수 있는 MCP 도구는 무엇인가요?

memem이 추가하는 슬래시 명령어는 무엇인가요?

• /memem — 환영, 상태, 도움말

• /memem-status — 메모리 수, 프로젝트, 검색 DB 크기, 마이너 상태

• /memem-doctor — 차단 요소에 대한 수정 지침이 포함된 사전 상태 점검

• /memem-mine — 마이너 데몬 수동 시작 (일반적으로 자동 시작)

• /memem-mine-history — 선택 사항: 설치 전 모든 Claude Code 세션 마이닝

claude CLI가 PATH에 없으면 어떻게 되나요?

memem은 **저하 모드(degraded mode)**로 진입합니다. Haiku 기반 컨텍스트 어셈블리와 스마트 리콜 기능 없이도 여전히 작동합니다. 쿼리 맞춤형 브리핑 대신 FTS 전용 키워드 리콜만 제공됩니다. 모든 세션 상단에 [memem] N memories · miner OK · assembly degraded (claude CLI missing — FTS-only recall)가 표시되어 이유를 알 수 있습니다.

이는 의도된 설계입니다: 선택적 종속성이 누락되면 실패가 아닌 저하가 발생해야 합니다.

문제를 진단하려면 어떻게 해야 하나요?

/memem-doctor를 실행하세요. 부트스트랩 심이 실행하는 것과 동일한 사전 점검(Python 버전, mcp 가져오기 가능 여부, PATH의 claude CLI, 디렉토리 쓰기 가능 여부, uv 사용 가능 여부)을 수행한 다음, 각 차단 요소에 대한 명시적인 수정 지침과 함께 HEALTHY, DEGRADED 또는 FAILING으로 표시된 보고서를 출력합니다.

더 깊은 디버깅을 위해서는:

tail -f ~/.memem/bootstrap.log   # first-run shim log
tail -f ~/.memem/miner.log       # miner daemon log
cat ~/.memem/events.jsonl        # memory operation audit trail
python3 -m memem.server --status   # detailed status dump

마이닝 파이프라인은 어떻게 작동하나요?

Session ends → miner daemon sees the JSONL file in ~/.claude/projects/
  → Waits 5 minutes for the file to "settle" (no more writes)
  → Filters to human messages + assistant prose (strips tool calls, system reminders)
  → One Haiku call with the full context: "extract durable lessons"
  → Haiku returns JSON array of memory candidates
  → Each candidate runs: security scan → dedup check → contradiction detection → save
  → Index rebuilt, per-project playbooks grown and refined
  → Session marked COMPLETE in ~/.memem/.mined_sessions

리콜 파이프라인은 어떻게 작동하나요?

First message in a new session → auto-recall.sh hook fires
  → Reads ~/.memem/.capabilities for status banner
  → If claude CLI is available → sends (message, memories) to Haiku
      → Haiku synthesizes a focused briefing (300-800 tokens usually)
      → Brief injected into Claude's context as "memem context briefing"
  → If claude CLI is missing → falls back to FTS-only keyword recall
  → Either way, Claude starts its reply with relevant context already loaded

아키텍처

memem은 작고 집중된 모듈로 나뉩니다:

• models.py — 데이터 유형, 경로 상수

• security.py — 프롬프트 인젝션 + 자격 증명 유출 스캔

• telemetry.py — 액세스 추적, 이벤트 로그 (원자적 쓰기, fcntl 잠금)

• search_index.py — SQLite FTS5 인덱스

• obsidian_store.py — 메모리 I/O, 중복 제거 점수, 모순 탐지

• playbook.py — 프로젝트별 플레이북 성장 + 정제

• assembly.py — Haiku를 통한 컨텍스트 어셈블리

• capabilities.py — 저하 모드를 위한 런타임 기능 탐지

• storage.py — 서버 수명 주기 도우미 (PID 관리, 마이너 자동 시작)

• server.py — 씬 MCP 진입점 (FastMCP 지연 로드)

• cli.py — 비 MCP 진입점을 위한 명령 디스패처

• mining.py — 세션 마이닝 파이프라인

다중 신호 리콜 점수:

• 50% FTS 관련성

• 15% 최신성 (0.995^시간 감쇠)

• 15% 액세스 기록 (사용 강화)

• 20% 중요도 (Haiku의 1-5 척도)

메모리 스키마 (마크다운 프런트매터):

---
id: uuid
schema_version: 1
title: "descriptive title"
project: project-name
tags: [mined, project-name]
related: [id1, id2, id3]
created: 2026-04-13
updated: 2026-04-13
source_type: mined | user | import
source_session: abc12345
importance: 1-5
status: active | deprecated
valid_to:                     # set when deprecated
contradicts: [id1]            # flagged conflicts
---

구성

Obsidian 설정 (선택 사항, 권장)

memem은 Obsidian 없이도 작동하며 마크다운을 작성합니다. 하지만 Obsidian을 사용하면 그래프 뷰와 백링크를 무료로 얻을 수 있습니다:

1. 다운로드: https://obsidian.md (무료)

2. ~/obsidian-brain을 볼트로 열기

3. 메모리는 memem/memories/에, 플레이북은 memem/playbooks/에 나타납니다.

4. 그래프 뷰를 사용하여 related 필드를 통해 메모리가 어떻게 연결되는지 확인하세요.

요구 사항

• Claude Code

• Python ≥ 3.11

• uv (첫 실행 시 bootstrap.sh에 의해 자동 설치)

• PATH에 claude CLI (선택 사항 — Haiku 기반 어셈블리에 필요; 저하 모드는 없이도 작동)

개발

git clone https://github.com/TT-Wang/memem.git
cd memem
pip install -e ".[dev]"
pytest             # 54 tests
ruff check .       # lint
mypy memem # type check (strict)

PR 프로세스는 CONTRIBUTING.md를, 버전 기록은 CHANGELOG.md를 참조하세요.

라이선스

MIT