@crewx/memory 0.1.2 → 0.1.3

package/SKILL.md

@@ -0,0 +1,556 @@
+---
+name: memory-v2
+description: 마크다운 + 프론트매터 기반 장기 기억 스킬. 드릴다운 구조로 확장성 있는 기억 관리.
+version: 0.10.0
+---
+
+# Memory V2 Skill
+
+마크다운 + 프론트매터 기반의 장기 기억 관리 스킬입니다.
+
+## 설치
+
+`packages/built-in/memory`에 포함되어 있으며, `npx memory` 명령으로 사용합니다.
+
+## 특징
+
+- **프론트매터**: 메타데이터 분리 (날짜, 카테고리, 태그, 토픽)
+- **드릴다운**: index.md → entries/ 구조
+- **가독성**: 사람이 직접 읽고 편집 가능
+- **Git 친화적**: 개별 파일로 버전 관리
+
+## 커맨드 Alias
+
+자주 쓰는 커맨드의 단축 별칭입니다. 기존 커맨드와 동일하게 동작합니다.
+
+| Alias | 실제 커맨드 | 설명 |
+|-------|-----------|------|
+| `read` | `get` | 기억 상세 조회 |
+| `list` | `index` | 전체 인덱스 보기 |
+| `rm` | `delete` | 기억 삭제 |
+| `ls` | `recent` | 최근 기억 보기 |
+
+```bash
+# 아래 두 명령은 동일
+npx memory get agent_id ABC123
+npx memory read agent_id ABC123
+
+npx memory index agent_id
+npx memory list agent_id
+```
+
+## 디렉토리 구조
+
+```
+memory/
+└── {agent_id}/
+    ├── summary.md    # 전체 요약 (토픽별 섹션 + entries/ 링크)
+    ├── graph.json    # 그래프 데이터
+    └── entries/      # 개별 기억들
+        └── {id}.md   # 파일명 = nanoid (예: QOSIOs.md)
+```
+
+> **파일명 규칙**: `{id}.md` (예: `QOSIOs.md`). 날짜·제목 등 메타데이터는 프론트매터에 있으므로 파일명에 중복하지 않습니다. 토큰 절약 + 파일명 충돌 방지.
+
+## 명령어
+
+### 저장
+
+```bash
+npx memory save <agent_id> "<summary>" [category] [--topic=xxx] [--tags=a,b,c] [--body="상세 내용"]
+```
+
+**옵션:**
+| 옵션 | 설명 | 예시 |
+|------|------|------|
+| `category` | 기억 분류 | decision, task, project, schedule, context, preference, general |
+| `--topic` | 토픽 그룹 | `--topic=crewx-strategy` |
+| `--tags` | 태그 (쉼표 구분) | `--tags=gemini,pricing` |
+| `--body` | **상세 내용 (권장!)** | `--body="배경, 근거, 결정사항 등"` |
+
+**⚠️ 중요: `--body` 옵션을 반드시 사용하세요!**
+- `--body` 없으면 플레이스홀더만 저장됨
+- 나중에 맥락 파악이 어려워짐
+- 최소 1-2문장 이상 상세 내용 권장
+
+**예시:**
+```bash
+# ❌ 나쁜 예 - 상세 없음
+npx memory save cto "Gemini 3.0 Flash 모먼트" decision --topic=crewx-strategy
+
+# ✅ 좋은 예 - 상세 포함
+npx memory save cto "Gemini 3.0 Flash 모먼트 - 전략적 분기점" decision --topic=crewx-strategy --tags=gemini,pricing --body="SWE-bench 78%로 Claude 3.5 Sonnet(49%) 압도. 가격은 1/6. CrewX 전략 검증됨 - 오케스트레이션이 핵심 해자."
+```
+
+### 인덱스 조회
+
+```bash
+npx memory index <agent_id>              # 중기기억 (토픽 요약만)
+npx memory index <agent_id> --recent      # 최근 엔트리 목록
+npx memory index <agent_id> --full        # 전체 보기
+```
+
+**드릴다운 패턴:** `index` → 필요한 토픽만 `topic` → 필요한 엔트리만 `get`
+
+### 토픽 드릴다운
+
+```bash
+npx memory topic <agent_id> <topic_name>
+```
+
+### 최근 기억
+
+```bash
+npx memory recent <agent_id> [days=30]
+```
+
+### 키워드 검색 (빠름)
+
+```bash
+npx memory find <agent_id> "<keyword>"
+```
+
+grep 기반 문자열 매칭. 빠르고 무료.
+
+### 시맨틱 검색 (AI)
+
+```bash
+npx memory search <agent_id> "<질문>"
+```
+
+**Gemini 2.0 Flash** 기반 시맨틱 검색. 유사어/맥락 이해.
+
+- 스킬 내부 `@memory_searcher` 에이전트 사용 (crewx.yaml)
+- 비용: ~$0.015/1M tokens (거의 무료)
+
+**예시:**
+```bash
+# 키워드 검색 (빠름)
+npx memory find crewx_dev_lead "에이전트"
+
+# 시맨틱 검색 (AI)
+npx memory search crewx_dev_lead "작업 배정할 때 주의할 점"
+```
+
+### 상세 조회 (드릴다운)
+
+```bash
+npx memory get <agent_id> <memory_id>
+```
+
+### 기억 수정 (update)
+
+```bash
+npx memory update <agent_id> <memory_id> [옵션]
+```
+
+**옵션:**
+| 옵션 | 설명 |
+|------|------|
+| `--summary` | 요약 수정 |
+| `--body` | 상세 내용 수정 |
+| `--topic` | 토픽 변경 |
+| `--category` | 카테고리 변경 |
+| `--tags` | 태그 변경 (쉼표 구분) |
+
+**예시:**
+```bash
+# 요약과 상세 내용 수정
+npx memory update cto VkY9X6 --summary="수정된 요약" --body="수정된 상세 내용"
+
+# 토픽만 변경
+npx memory update cto VkY9X6 --topic=new-topic
+```
+
+### 기억 삭제 (delete)
+
+```bash
+npx memory delete <agent_id> <memory_id> [--force]
+```
+
+- `--force` 없으면 확인 메시지만 출력
+- `--force` 있으면 실제 삭제
+
+**예시:**
+```bash
+# 삭제 확인
+npx memory delete cto VkY9X6
+
+# 실제 삭제
+npx memory delete cto VkY9X6 --force
+```
+
+### 기억 병합 (merge)
+
+```bash
+npx memory merge <agent_id> <memory_id1> <memory_id2> [--summary="병합 요약"]
+```
+
+- 두 기억을 하나로 병합
+- 원본 두 기억은 삭제됨
+- 태그는 합쳐짐 (중복 제거)
+- 병합된 파일에 `merged_from` 메타데이터 추가
+
+**예시:**
+```bash
+# 두 기억 병합
+npx memory merge cto abc123 def456
+
+# 커스텀 요약으로 병합
+npx memory merge cto abc123 def456 --summary="VLM 파인튜닝 종합 정리"
+```
+
+### 요약 생성 (summarize)
+
+```bash
+npx memory summarize <agent_id> [--force]
+```
+
+MemGAS 증분 요약 방식을 적용한 기억 요약 기능입니다.
+
+**구조:**
+- `summary.md` 1개에 토픽별 요약 + entries/ 상대경로 링크
+- `save`/`delete` 실행 시 자동으로 summary.md 갱신
+- `summarize`는 수동 트리거용 (자동 갱신 실패 시 또는 `--force`로 전체 재생성)
+
+**증분 추적:**
+- 프론트매터에 `last_entry_id` 저장
+- 다음 실행 시 해당 ID 이후 엔트리만 추출하여 요약에 반영
+- `@memory_summarizer` (Haiku) 에이전트가 요약 생성
+- AI 호출 실패 시 bullet-point 폴백
+
+**옵션:**
+| 옵션 | 설명 |
+|------|------|
+| `--force` | 전체 재생성 (증분 무시) |
+
+**예시:**
+```bash
+# 증분 요약 (새 엔트리만 반영)
+npx memory summarize ui_devlead
+
+# 강제 전체 재생성
+npx memory summarize ui_devlead --force
+```
+
+### 요약 생성 (summarize-dirty)
+
+`save`/`delete`는 동기 summarize 대신 **dirty flag**만 생성하며, cron과 연동해 dirty가 있는 에이전트만 비동기로 summary를 갱신합니다.  
+cron이 매 1분마다 체크하여 실행합니다.
+
+```bash
+npx memory summarize-dirty
+```
+
+**cron 등록 예시:**
+```bash
+npx cron add "*/1 * * * *" "npx memory summarize-dirty" --mode command --name "memory-debounce"
+```
+
+**summary.md 포맷:**
+```markdown
+---
+last_entry_id: QOSIOs
+last_updated: 2026-02-16
+entry_count: 48
+summarizer: haiku
+---
+
+## mcp-http (4건)
+MCP HTTP 엔드포인트 구현 완료...
+→ [entries/HYpwPP.md](entries/HYpwPP.md)
+→ [entries/ImH-56.md](entries/ImH-56.md)
+
+## cli-service (3건)
+CLI 쉘환경 감지 성능 개선...
+→ [entries/a3cOL8.md](entries/a3cOL8.md)
+```
+
+### 파일명 마이그레이션 (migrate)
+
+```bash
+npx memory migrate <agent_id>
+```
+
+기존 한글 slug 파일명(`2026-02-16-한글slug.md`)을 ID 기반(`QOSIOs.md`)으로 일괄 변환합니다.
+
+- 각 .md 파일의 프론트매터에서 `id` 읽고 → `{id}.md`로 리네이밍
+- 완료 후 summary.md 자동 재생성 + 그래프 갱신
+- 이미 ID 파일명인 파일은 스킵
+
+**예시:**
+```bash
+npx memory migrate ui_devlead
+```
+
+## 프론트매터 스키마
+
+```yaml
+---
+id: yLC8Iv  # nanoid 6자리
+date: 2025-12-23
+category: decision
+tags: ["strategy", "gemini"]
+topic: crewx-strategy
+summary: "한 줄 요약"
+---
+```
+
+## 에이전트 프롬프트 가이드
+
+```markdown
+<memory-v2-guide agent_id="{{agent_id}}">
+# Memory V2 사용 가이드
+
+## 대화 시작 시 (필수!)
+```bash
+# 중기기억 로드 (토픽 요약 + 드릴다운 안내)
+npx memory index {{agent_id}}
+
+# 필요시 드릴다운
+npx memory index {{agent_id}} --recent   # 최근 목록
+npx memory topic {{agent_id}} <topic>    # 토픽 상세
+npx memory get {{agent_id}} <id>         # 개별 기억
+```
+
+## 기억 저장 트리거
+- "기억해둬", "저장해", "메모해" 요청 시
+- 중요한 결정사항 발생 시
+- CEO 지침 수령 시
+
+## 토픽 선택 가이드 ⭐
+
+**저장 시 반드시 적절한 토픽을 지정하세요!**
+
+1. **기존 토픽 확인**: `index` 명령으로 기존 토픽 목록 확인
+2. **기존 토픽 선택**: 관련 토픽이 있으면 그 토픽 사용
+3. **새 토픽 생성**: 없으면 새 토픽명 생성 (kebab-case, 예: `new-feature`)
+
+**토픽 네이밍 규칙:**
+- kebab-case 사용 (예: `vlm-finetuning`, `crewx-strategy`)
+- 프로젝트/기능/주제 단위로 묶기
+- 너무 세분화하지 말 것 (5개 미만이면 병합 고려)
+
+**예시:**
+```bash
+# 기존 토픽에 추가
+npx memory save {{agent_id}} "VLM 학습률 조정" decision --topic=vlm-finetuning
+
+# 새 토픽 생성
+npx memory save {{agent_id}} "신규 기능 기획" decision --topic=new-feature-x
+```
+
+## 저장 명령 (--body 필수!)
+```bash
+# ⚠️ 항상 --body 포함해서 저장!
+npx memory save {{agent_id}} "<요약>" <category> --topic=<topic> --body="<상세 내용>"
+```
+
+**--body 작성 가이드:**
+- 왜 이 결정을 했는지 (배경/근거)
+- 핵심 수치나 데이터
+- 관련 파일/문서 경로
+- 후속 액션이 있으면 포함
+
+## 카테고리 선택
+- **decision**: 의사결정, CEO 지침
+- **task**: 할 일, 작업 계획
+- **project**: 프로젝트 정보
+- **schedule**: 일정, 미팅
+- **context**: 배경 정보, 상황
+- **preference**: 선호도, 규칙
+- **general**: 기타
+
+</memory-v2-guide>
+```
+
+## 기존 memory 스킬과 차이점
+
+| 항목 | memory (v1) | memory-v2 |
+|------|-------------|-----------|
+| 저장 형식 | JSON 배열 | 마크다운 파일 |
+| 메타데이터 | content 내 혼합 | 프론트매터 분리 |
+| 조회 | 전체 로드 | 인덱스 → 드릴다운 |
+| 토픽 지원 | 없음 | 있음 |
+| 가독성 | 낮음 | 높음 |
+
+## 기억 연결 그래프
+
+기억 간 연관성을 그래프로 관리합니다.
+
+### 그래프 빌드
+
+```bash
+npx memory mindmap build <agent_id>
+```
+
+규칙 기반으로 연결 생성:
+- **같은 topic**: weight 0.7 (⚠️ `general` 제외)
+- **공통 tags**: weight 0.4~0.8 (1개=0.4, 2개=0.6, 3개+=0.8)
+- **같은 날짜**: weight 0.3 (기본 OFF)
+- **같은 category**: weight 0.2 (⚠️ `general` 제외)
+
+> **edgeThreshold = 0.3** → 총 weight가 0.3 이상이어야 연결됨
+
+### ⭐ 연결성 높이는 저장 팁
+
+**핵심: `general`을 피하고 구체적으로!**
+
+| 방법 | Weight | 효과 |
+|------|--------|------|
+| topic 지정 | +0.7 | 같은 토픽 기억들 자동 연결 |
+| 태그 2개+ | +0.6 | 토픽 달라도 태그로 연결 |
+| 태그 3개+ | +0.8 | 최대 연결 강도 |
+| category | +0.2 | decision/task 등 구체적으로 |
+
+**❌ 나쁜 예 (연결 안 됨)**
+```bash
+# topic=general, category=general → 연결 0
+npx memory save agent "Discord 설정 제거" general
+```
+
+**✅ 좋은 예 (강한 연결)**
+```bash
+# topic + category + tags → 최대 연결
+npx memory save agent "Discord 설정 제거 결정" decision \
+  --topic=discord \
+  --tags=settings,cpo-decision,oauth \
+  --body="CPO 회의 결과..."
+```
+
+**태그 활용 전략:**
+- 관련 기능/모듈명: `discord`, `oauth`, `settings`
+- 회의/결정자: `cpo-decision`, `dev-meeting`
+- 상태: `completed`, `blocked`, `wip`
+
+### 그래프 요약 보기
+
+```bash
+npx memory mindmap show <agent_id>
+```
+
+토픽별 클러스터, 허브 노드(연결 많은 기억) 등 표시.  
+기본 출력은 **Mermaid 포맷**이며, VS Code 마크다운 프리뷰에서 그래프로 시각화됩니다.  
+`--format=mermaid`가 기본값이고, `--format=text`로 텍스트 출력도 가능합니다.
+
+**기간 필터 옵션:**
+```bash
+npx memory mindmap show <agent_id> --period=stm  # 24h
+npx memory mindmap show <agent_id> --period=mtm  # 7d
+npx memory mindmap show <agent_id> --period=ltm  # 30d
+```
+
+### PNG 이미지 내보내기
+
+Mermaid 출력을 PNG 이미지로 변환하여 시각적으로 확인할 수 있습니다.
+
+```bash
+# 1. mermaid 코드를 파일로 저장
+npx memory mindmap show <agent_id> | sed 's/^```mermaid$//' | sed 's/^```$//' > /tmp/graph.mmd
+
+# 2. PNG 변환 (npx로 설치 없이 실행)
+npx @mermaid-js/mermaid-cli -i /tmp/graph.mmd -o graph.png -w 2400 -H 1600 -b white
+
+# 기간 필터 + PNG (예: 최근 24시간만)
+npx memory mindmap show <agent_id> --period=stm | sed 's/^```mermaid$//' | sed 's/^```$//' | grep -v '^(' > /tmp/graph-stm.mmd
+npx @mermaid-js/mermaid-cli -i /tmp/graph-stm.mmd -o graph-stm.png -w 1600 -H 900 -b white
+```
+
+> **팁**: 전체 그래프(58+ 노드)는 복잡하므로 `--period=stm`(24h)이나 `--period=mtm`(7d)으로 축소해서 보는 걸 권장합니다.
+
+### 연결된 기억 조회
+
+```bash
+npx memory mindmap related <agent_id> <memory_id>
+```
+
+특정 기억과 연결된 기억들을 weight 순으로 표시.
+
+### 수동 연결 관리
+
+```bash
+# 연결 추가
+npx memory mindmap add <agent_id> <from_id> <to_id> [type]
+
+# 연결 제거
+npx memory mindmap remove <agent_id> <from_id> <to_id>
+```
+
+### 시각화 (HTML) - 공용 그래프
+
+```bash
+npx memory mindmap html
+```
+
+**모든 에이전트의 연결 그래프를 한 곳에 통합한 공용 시각화**를 생성합니다.
+
+**특징:**
+- 모든 에이전트의 graph.json 데이터를 하나의 HTML에 임베드
+- 드롭다운으로 에이전트 선택 → 해당 그래프로 실시간 전환
+- D3.js force-directed 그래프
+- 토픽별 색상 구분
+- 줌 & 드래그 지원
+- 호버 시 상세 정보 툴팁
+- 노드 크기 = 연결 수
+- 서버 없이 file:// 프로토콜로 바로 열기 가능
+
+**사용법:**
+```bash
+# 1. 공용 HTML 생성 (agent_id 필요 없음)
+npx memory mindmap html
+
+# 2. 브라우저에서 열기
+npx memory mindmap open
+```
+
+**예시:**
+```bash
+# 전체 에이전트 그래프 통합 시각화
+npx memory mindmap html
+```
+
+### 브라우저에서 열기
+
+```bash
+npx memory mindmap open [agent_id]
+```
+
+특정 에이전트의 그래프를 브라우저에서 바로 엽니다.
+
+**예시:**
+```bash
+# CTO 그래프 열기
+npx memory mindmap open cto
+
+# 전체 (기본 에이전트) 열기
+npx memory mindmap open
+```
+
+### 저장 위치
+
+```
+memory/{agent_id}/graph.json         # 그래프 데이터
+memory/mindmap.html                  # 공용 시각화 HTML (npx memory mindmap html로 생성)
+```
+
+---
+
+## 기억 계층 구조
+
+`index` 명령은 인지심리학(Ebbinghaus, Atkinson-Shiffrin)과 AI 에이전트 메모리 연구(MemoryOS, A-Mem)에 기반한 3계층 출력을 제공합니다.
+
+| 계층 | 시간 | 출력 |
+|------|------|------|
+| 단기 (STM) | 24h | `## 🔥 최근 작업` |
+| 중기 (MTM) | 7일 | 토픽별 요약 (summary.md) |
+| 장기 (LTM) | 30일 | `--recent` 또는 `--full` |
+
+상세 설계 근거: [README.md](./README.md#설계-근거-계층적-기억-아키텍처)
+
+---
+
+## v1 → v2 마이그레이션
+
+```bash
+npx memory migrate <agent_id>
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewx/memory",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Memory engine for CrewX - markdown + frontmatter based long-term memory",
   "type": "commonjs",
   "main": "dist/src/engine.js",
@@ -14,7 +14,7 @@
   "bin": {
     "memory": "./dist/cli.js"
   },
-  "files": ["dist"],
+  "files": ["dist", "SKILL.md"],
   "scripts": {
     "build": "tsc",
     "dev": "ts-node cli.ts",
@@ -23,7 +23,7 @@
   "keywords": ["crewx", "memory", "markdown", "frontmatter"],
   "license": "MIT",
   "dependencies": {
-    "@crewx/knowledge-core": "^0.1.2",
+    "@crewx/knowledge-core": "^0.1.3",
     "gray-matter": "^4.0.3",
     "nanoid": "^3.3.11"
   },