Mem

mem — Per-project External Memory / 프로젝트별 외장 기억소

Identity / 정체성

Different from Claude Code's built-in /memory (conversation notes).

/memory (Claude Code 기본 대화 메모) 와는 다른 컨셉.

• Built-in /memory: conversation flow notes, user preferences

• /mem (this skill): per-project code/deployment/decision records as split markdown files → recall only the chapter you need → save context window

• 기본 /memory: 대화 흐름 메모, 사용자 선호 등

• /mem (이 스킬): 프로젝트별 코드/배포/결정 기록. md 파일로 분할 저장 → 필요한 챕터만 호출 → 컨텍스트 윈도우 절약

The skill is global but data is per-project. Storage location is based on the current working directory (pwd), written under memory/.

스킬은 글로벌이지만 데이터는 프로젝트별. 호출 시점의 현재 작업 디렉토리(pwd) 기준으로 memory/ 폴더에 저장.

Hard Rules / 규칙 (강제)

1. Location / 위치: <pwd>/memory/. If project root differs, prefer git rev-parse --show-toplevel.
2. Naming / 명명: NN-<kebab-case>.md. NN is 2 digits (01-, 02-...). Next number = current max + 1.
3. Header template / 헤더 템플릿:

   # <Title>
   
   **최종 갱신**: YYYY-MM-DD
   
   <One-line summary — what this document is>
   

4. Footer (optional) / 푸터:

   ## 같이 보면 좋은 문서
   - `XX-other.md` — cross-reference
   

5. Size limit / 크기 제한: > 8KB → suggest split. If user declines, save as-is.
6. Auto .gitignore / 자동 등록: append memory/ to protect secrets/SSH/tokens. Skip if already present.
7. README.md is the always-fresh index / 인덱스: regenerate on add/rename/delete.
8. "When to open" hints / 검색 hint 권장: 1-2 lines of grep-friendly keywords at the top of each file.

Subcommands / 서브커맨드

/mem (no args) — Smart Auto-Router / 스마트 자동 라우터

Inspects state and picks the right action. User types short command once.

상황을 보고 알맞은 동작 자동 선택. 사용자는 명령 짧게 한 번만.

Routing logic (top to bottom) / 판정 로직 (위에서부터 검사):

1. memory/ folder does not exist → auto init

   • Create folder, register .gitignore, write README skeleton
   • End. Hint: "Initialized. From next /mem, work will auto-save."

   memory/ 폴더 없음 → init 자동 수행

2. memory/ exists + meaningful work detected since last save → auto save

   • "Meaningful work" criteria / "의미있는 작업" 판정:
     • Previous assistant turn used Edit / Write / Bash (git commit/deploy)
     • git diff --stat shows ≥ 10 changed lines
     • Conversation contains explicit signals like "deployed", "fixed bug", "added feature"
   • Auto-infer topic from recent conversation → create new NN-<kebab>.md
   • Apply 8KB gate (same as save)
   • Auto-update README index
   • Output: "Saved: memory/NN-<name>.md (X.X KB)"

3. memory/ exists + no save-worthy work (clean state) → fallback to catchup

   • Output memory/README.md only (quick reference + index table)
   • New session pattern

Principles / 원칙:

• One call = one action. init and save never co-occur (user needs to call /mem once more).
• Auto-save must output 1 line confirming the file. Never silent.
• If ambiguous → ask user instead of auto-saving.

Explicit calls when needed / 명시적 호출이 필요할 때:

• /mem catchup — clean state but want to see README anyway
• /mem init — force re-init (rarely needed, auto-router handles it)
• /mem save <topic> — override auto-inferred topic name

/mem init (explicit)

Auto-router usually handles it, but explicit re-init is supported.

1. Create <project>/memory/ (skip + warn if exists)
2. Append memory/ to .gitignore if absent
3. Write README template (confirm before overwrite)
4. Hint: "Initialized"

/mem save <topic> [--file NN-<name>.md]

Save the immediately preceding work/conversation as a new file.

직전 작업/대화 내용을 새 파일로 저장.

1. Topic → filename suggestion (NN-<kebab>.md)
2. Recent conversation → draft body
3. Insert header
4. If projected size > 8KB:
   • "This is X KB. Split suggestion: part A (~3KB), part B (~4KB). Which?"
   • Confirm with user, then split or save as-is
5. Save → update README index
6. Output: "Saved: memory/NN-<name>.md"

/mem recall <keyword>

Grep-based pinpoint instead of reading everything.

전체 안 읽고 키워드 매칭만.

1. grep -l -i "<keyword>" memory/*.md to find candidates
2. 0 candidates → "No match. Show README?"
3. 1-2 → read those files only, answer
4. ≥ 3 → list with first-line titles, ask user to pick
5. NEVER read all files at once (compact prevention) / 절대 모든 파일을 한 번에 읽지 말 것

/mem update <file pattern or keyword>

Detect stale chapters by comparing to current code.

stale 잡고 갱신.

1. Read matching files
2. Compare to current state (git diff, filesystem)
3. Highlight mismatches: "this line says X but the code is Y now"
4. Confirm with user, apply edits
5. Auto-update header date

/mem split <file>

Split an oversized file by semantic groups.

파일이 커졌을 때 의미 단위로 쪼개기.

1. Read target file
2. Suggest groupings by ## section headers
3. Confirm → create new files + simplify original into an index page
4. Update README index

/mem index

Regenerate README.md automatically.

1. ls memory/*.md, extract title + "When to open" keyword for each
2. Update index table
3. Preserve "Quick reference" section

/mem visualize (alias: /mem viz)

Bird's-eye map of memory. Only reads README.md — never opens individual files (compact prevention).

한눈에 보는 기억소 지도. README.md만 읽어서 시각화.

1. Read memory/README.md only
2. Auto-categorize files into 5-6 buckets based on filename/description:
   • Deployment/Operations
   • Security/Rules
   • Accounts/Identifiers
   • Infrastructure/External
   • Features
   • Operational know-how (gotchas, handoff, workflow)
   • Other (if needed)
3. Output ASCII tree diagram (project root → category → file)
4. One-line summary table (filename + 1-line keyword summary)
5. "Common scenarios" section — category combos (e.g., new deploy → 01+09, incident → 02+07)
6. Footer hint: /mem recall <keyword> for pinpoint

Rules / 규칙:

• Never read individual files. README one-liners only.
• Max 5-6 categories. Don't over-split.
• One-screen output. ≥ 10 files → category-only tree + separate file table.
• Box/table width ≤ 90 chars for terminal.

/mem rm <file>

Delete with 1-time confirmation. Updates README index.

파일 삭제 (확인 1회 받음). README 인덱스도 갱신.

Auto-suggest Stop Hook / 자동 제안 Stop hook

After significant code changes, inject a context hint automatically.

작업 후 의미 있는 코드 변경이 감지되면 자동 컨텍스트 주입.

Install: scripts/install-stop-hook.sh (registers in user settings.json).

설치: scripts/install-stop-hook.sh (사용자 settings.json에 등록).

Conditions / 조건:

• Changed lines since last commit ≥ 30 (small changes → silent)
• ≥ 5 min since last /mem save (anti-spam)
• ~/.claude/.mem-autosuggest-off file does not exist

Toggle / 토글:

• touch ~/.claude/.mem-autosuggest-off → off / 끔
• rm ~/.claude/.mem-autosuggest-off → on / 켬

README.md Template / 기본 템플릿

# memory/

External memory managed by `/mem` skill. Topic-split markdown files.
Recall only the chapter you need → save context window.

Registered in `.gitignore` — does not go to git (protects secrets/SSH/tokens).

## Quick Reference

- Entry point: <URL or N/A>
- Deploy: <how>
- Repo: <github URL>

## File Index

| File | When to open |
|---|---|
| (auto-updated) | (auto-updated) |

## Usage

- Restore context: `/mem catchup`
- Keyword search: `/mem recall <keyword>`
- New memo: `/mem save <topic>`
- Visualize: `/mem visualize`

Safeguards / 안전장치

• Auto .gitignore registration → secrets safe
• 8KB size gate → no compact triggers
• Recall is grep-first → never read all at once
• Delete requires confirmation
• Split preserves a simplified index page → no information loss

Usage Example / 사용 예시

# First call in new project → auto-init
$ cd ~/Project/new-project
> /mem
✓ memory/ created, .gitignore registered, README skeleton written
✓ Next /mem will auto-save your work

# After work → auto-save
> /mem
✓ Analyzed last conversation: "server deployment flow"
✓ Saved: memory/01-server-deployment.md (3.2 KB)
✓ README index updated

# New session (no work) → auto-catchup
$ claude
> /mem
[ memory/README.md output — quick reference + index ]

# Bird's-eye view
> /mem viz
[ ASCII tree + category breakdown + scenarios ]

# Pinpoint recall
> /mem recall "kakao login"
[ opens memory/07-auth-providers.md only — others untouched ]

# Stale detection
> /mem update "auth"
[ checks files 04, 06, 07 against code → shows mismatches → applies edits ]