# Mem

> Per-project external memory. Splits work notes into topic-based markdown files under the current project's memory/ folder. Saves context window by recalling only the needed chapter. Subcommands: save, recall, update, split, index, catchup, visualize. Separate from Claude Code's built-in /memory (conversation notes) — this is for code/deployment/decision records. 프로젝트별 외장 기억소. 현재 프로젝트의 memory/ 폴더에 주제별 md 파일로 작업 내용을 분할 저장. 컨텍스트 윈도우 절약 + 필요한 챕터만 호출하는 패턴. 서브커맨드: save, recall, update, split, index, catchup, visualize. Claude Code 기본 /memory (대화 메모) 와는 별개 — 이건 코드/배포/결정 기록용. Triggers (Korean): "메모리에 저장", "기억해줘", "memory 정리", "어디까지 했지". Triggers (English): "save to memory", "remember this", "where were we", "memory dump".

- Skill: `wjb127/mem` (Agent Skill)
- Install (CLI): `npx skillmds@latest add wjb127/mem`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wjb127/mem/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: wjb127 (https://skillmd.com/u/wjb127)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wjb127/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 / 헤더 템플릿**:
   ```markdown
   # <Title>

   **최종 갱신**: YYYY-MM-DD

   <One-line summary — what this document is>
   ```
4. **Footer (optional) / 푸터**:
   ```markdown
   ## 같이 보면 좋은 문서
   - `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 / 기본 템플릿

```markdown
# 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 ]
```