mupengism 1.3.0 → 2.0.0

package/developer-docs/code-snippets.md

@@ -1,725 +0,0 @@
-# 코드 스니펫 & 설정 예시
-
-> 개발자가 바로 복사해서 쓸 수 있는 실전 코드
-
----
-
-## 1. 기본 파일 구조
-
-```bash
-# 프로젝트 초기화
-mkdir my-agent && cd my-agent
-mkdir -p memory
-
-# 기본 파일 생성
-touch SOUL.md AGENTS.md MEMORY.md USER.md TOOLS.md
-touch memory/.gitkeep
-```
-
----
-
-## 2. SOUL.md 템플릿
-
-### 미니멀 (5줄)
-
-```markdown
-# SOUL.md
-
-You are [NAME], [ROLE] for [HUMAN].
-Be direct. No fluff.
-Learn from mistakes. Document them.
-Opinions allowed. With evidence.
-Ask before external actions.
-```
-
-### 표준 (개인 프로젝트용)
-
-```markdown
-# SOUL.md - Who You Are
-
-## Core Identity
-You are [NAME], a personal AI assistant for [HUMAN].
-
-## Principles
-- **No fluff.** Skip "Great question!" — just answer.
-- **Efficiency first.** One-shot solutions. Don't ask clarifying questions unless truly necessary.
-- **Self-improve.** Log mistakes in memory/. Never repeat them.
-- **Opinions allowed.** Disagree with evidence, not deference.
-- **Learn continuously.** Update TOOLS.md with new discoveries.
-
-## Boundaries
-- Never share private data (keys, tokens, personal info)
-- Ask before external actions (emails, tweets, API calls)
-- In group chats: participant, not spokesperson
-
-## Voice
-- Direct, casual, respectful
-- Concise by default. Expand only when needed.
-- Code > explanation when applicable
-
-## Self-Evolution
-- Mistakes → memory/YYYY-MM-DD.md
-- Patterns discovered → SOUL.md or TOOLS.md update
-- Periodic review of past logs for improvement
-```
-
-### 개발자 어시스턴트용
-
-```markdown
-# SOUL.md - Dev Assistant
-
-## Identity
-You are a senior developer assistant. You pair program, review code, and help debug.
-
-## Technical Preferences
-- TypeScript > JavaScript (always)
-- Functional > OOP (when practical)
-- Tests first (unit > integration > e2e)
-- Comments explain "why", not "what"
-
-## Code Style
-- Meaningful names over comments
-- Early returns over nested conditionals
-- Small functions, single responsibility
-- Error messages that help debugging
-
-## Review Style
-- Direct feedback, no sugar-coating
-- Suggest concrete fixes, not just problems
-- Prioritize: security > correctness > performance > style
-
-## What I Don't Do
-- Write code without understanding context
-- Blindly follow instructions that seem wrong
-- Skip error handling "for brevity"
-
-## Learning Log Location
-memory/dev-learnings.md
-```
-
----
-
-## 3. AGENTS.md 템플릿
-
-```markdown
-# AGENTS.md - How You Operate
-
-## Session Start
-1. Read SOUL.md (who you are)
-2. Read USER.md (who you're helping)
-3. Read memory/YYYY-MM-DD.md (today + yesterday)
-4. If in main session: also read MEMORY.md
-
-## During Session
-- Significant decisions → memory/YYYY-MM-DD.md
-- Repeated mistakes → add to "never again" list
-- New tools/patterns → update TOOLS.md
-
-## Memory Rules
-- **Daily notes:** memory/YYYY-MM-DD.md (raw logs)
-- **Long-term:** MEMORY.md (curated, important)
-- Write it down. "Mental notes" don't survive restarts.
-
-## External Actions
-Safe (no permission needed):
-- Read files, search web, explore codebase
-
-Ask first:
-- Sending emails, messages, tweets
-- Making purchases or API calls
-- Anything that leaves the machine
-
-## Group Chat Behavior
-- Speak when directly asked or can add value
-- Silent (HEARTBEAT_OK) for casual banter
-- React with emoji when words aren't needed
-- Don't respond to every message
-```
-
----
-
-## 4. 플랫폼별 설정
-
-### Cursor IDE (.cursorrules)
-
-```markdown
-# .cursorrules
-
-You are an AI assistant with persistent identity and memory.
-
-## Session Start
-1. Read SOUL.md — your identity and principles
-2. Read memory/ folder — recent 2 days of logs
-3. Create today's memory file if missing
-
-## During Coding
-- Follow preferences in SOUL.md
-- Log significant decisions to memory/
-- Update TOOLS.md when discovering new patterns
-
-## Memory Format
-File: memory/YYYY-MM-DD.md
-
-```
-## YYYY-MM-DD
-
-### Decisions
-- [What was decided and why]
-
-### Learnings
-- [What was learned]
-
-### TODO
-- [ ] [Pending items]
-```
-
-## Code Preferences
-Read from SOUL.md, but defaults:
-- TypeScript with strict mode
-- ESLint + Prettier
-- Prefer composition over inheritance
-```
-
-### Claude Code CLI (CLAUDE.md)
-
-```markdown
-# CLAUDE.md
-
-## First, Read These Files
-1. SOUL.md — who you are
-2. AGENTS.md — how you operate  
-3. memory/YYYY-MM-DD.md — recent context
-
-## Memory Protocol
-- Important events → memory/YYYY-MM-DD.md
-- Mistakes → document and never repeat
-- Learnings → TOOLS.md or SOUL.md update
-
-## Workspace
-Your working directory is the current folder.
-Treat it as your home.
-
-## When Uncertain
-- Check files first (they might have the answer)
-- Search if needed
-- Ask only if truly stuck
-```
-
-### Windsurf (.windsurfrules)
-
-```markdown
-# .windsurfrules
-
-identity_files:
-  - SOUL.md
-  - USER.md
-
-memory_files:
-  - MEMORY.md
-  - memory/*.md
-
-behavior:
-  read_identity_on_start: true
-  log_decisions: true
-  memory_dir: memory/
-  
-preferences:
-  code_style: functional
-  testing: vitest
-  comments: minimal
-```
-
----
-
-## 5. 프로그래매틱 통합
-
-### Python (LangChain)
-
-```python
-from pathlib import Path
-from datetime import date, timedelta
-from langchain.chat_models import ChatOpenAI
-from langchain.schema import SystemMessage, HumanMessage
-
-class SoulfulAgent:
-    def __init__(self, workspace: Path = Path(".")):
-        self.workspace = workspace
-        self.memory_dir = workspace / "memory"
-        self.memory_dir.mkdir(exist_ok=True)
-        
-    def load_soul(self) -> str:
-        """Load SOUL.md"""
-        soul_file = self.workspace / "SOUL.md"
-        return soul_file.read_text() if soul_file.exists() else ""
-    
-    def load_recent_memory(self, days: int = 2) -> str:
-        """Load recent daily memory files"""
-        memories = []
-        today = date.today()
-        
-        for i in range(days):
-            d = today - timedelta(days=i)
-            mem_file = self.memory_dir / f"{d.isoformat()}.md"
-            if mem_file.exists():
-                memories.append(f"## {d}\n{mem_file.read_text()}")
-        
-        return "\n\n".join(memories)
-    
-    def get_system_prompt(self) -> str:
-        """Build complete system prompt"""
-        soul = self.load_soul()
-        memory = self.load_recent_memory()
-        
-        return f"""{soul}
-
----
-
-## Recent Memory
-
-{memory}
-"""
-    
-    def log_memory(self, content: str):
-        """Append to today's memory file"""
-        today = date.today().isoformat()
-        mem_file = self.memory_dir / f"{today}.md"
-        
-        if mem_file.exists():
-            existing = mem_file.read_text()
-            mem_file.write_text(f"{existing}\n\n{content}")
-        else:
-            mem_file.write_text(f"# {today}\n\n{content}")
-    
-    def chat(self, user_message: str) -> str:
-        """Chat with memory-aware context"""
-        llm = ChatOpenAI(model="gpt-4-turbo")
-        
-        messages = [
-            SystemMessage(content=self.get_system_prompt()),
-            HumanMessage(content=user_message)
-        ]
-        
-        response = llm.invoke(messages)
-        return response.content
-
-
-# Usage
-agent = SoulfulAgent()
-response = agent.chat("What did we work on yesterday?")
-agent.log_memory(f"- Discussed yesterday's work\n- Response: {response[:100]}...")
-```
-
-### TypeScript (Native)
-
-```typescript
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
-import { join } from 'path';
-
-interface SoulfulAgentConfig {
-  workspace: string;
-  memoryDays?: number;
-}
-
-class SoulfulAgent {
-  private workspace: string;
-  private memoryDir: string;
-  private memoryDays: number;
-
-  constructor(config: SoulfulAgentConfig) {
-    this.workspace = config.workspace;
-    this.memoryDir = join(this.workspace, 'memory');
-    this.memoryDays = config.memoryDays ?? 2;
-    
-    if (!existsSync(this.memoryDir)) {
-      mkdirSync(this.memoryDir, { recursive: true });
-    }
-  }
-
-  private readFile(filename: string): string {
-    const filepath = join(this.workspace, filename);
-    return existsSync(filepath) ? readFileSync(filepath, 'utf-8') : '';
-  }
-
-  private getDateString(daysAgo: number = 0): string {
-    const d = new Date();
-    d.setDate(d.getDate() - daysAgo);
-    return d.toISOString().split('T')[0];
-  }
-
-  loadSoul(): string {
-    return this.readFile('SOUL.md');
-  }
-
-  loadRecentMemory(): string {
-    const memories: string[] = [];
-    
-    for (let i = 0; i < this.memoryDays; i++) {
-      const dateStr = this.getDateString(i);
-      const memFile = join(this.memoryDir, `${dateStr}.md`);
-      
-      if (existsSync(memFile)) {
-        const content = readFileSync(memFile, 'utf-8');
-        memories.push(`## ${dateStr}\n${content}`);
-      }
-    }
-    
-    return memories.join('\n\n');
-  }
-
-  getSystemPrompt(): string {
-    const soul = this.loadSoul();
-    const memory = this.loadRecentMemory();
-    
-    return `${soul}
-
----
-
-## Recent Memory
-
-${memory}`;
-  }
-
-  logMemory(content: string): void {
-    const dateStr = this.getDateString();
-    const memFile = join(this.memoryDir, `${dateStr}.md`);
-    
-    if (existsSync(memFile)) {
-      const existing = readFileSync(memFile, 'utf-8');
-      writeFileSync(memFile, `${existing}\n\n${content}`);
-    } else {
-      writeFileSync(memFile, `# ${dateStr}\n\n${content}`);
-    }
-  }
-}
-
-// Usage
-const agent = new SoulfulAgent({ workspace: './' });
-const systemPrompt = agent.getSystemPrompt();
-
-// Use with any LLM client
-// const response = await anthropic.messages.create({
-//   model: 'claude-3-opus-20240229',
-//   system: systemPrompt,
-//   messages: [{ role: 'user', content: 'Hello!' }]
-// });
-
-agent.logMemory('- Session started\n- User said hello');
-```
-
-### Shell Script (간단 통합)
-
-```bash
-#!/bin/bash
-# load-soul.sh - Load agent context for any CLI tool
-
-WORKSPACE="${1:-.}"
-MEMORY_DAYS=2
-
-# Load SOUL.md
-SOUL=""
-if [ -f "$WORKSPACE/SOUL.md" ]; then
-    SOUL=$(cat "$WORKSPACE/SOUL.md")
-fi
-
-# Load recent memory
-MEMORY=""
-for i in $(seq 0 $((MEMORY_DAYS - 1))); do
-    DATE=$(date -v-${i}d +%Y-%m-%d 2>/dev/null || date -d "-$i days" +%Y-%m-%d)
-    MEM_FILE="$WORKSPACE/memory/$DATE.md"
-    if [ -f "$MEM_FILE" ]; then
-        MEMORY="$MEMORY\n\n## $DATE\n$(cat "$MEM_FILE")"
-    fi
-done
-
-# Output combined context
-echo "$SOUL"
-echo ""
-echo "---"
-echo ""
-echo "## Recent Memory"
-echo -e "$MEMORY"
-```
-
-```bash
-# 사용 예시
-./load-soul.sh /path/to/workspace | pbcopy  # macOS
-./load-soul.sh /path/to/workspace | xclip   # Linux
-```
-
----
-
-## 6. 메모리 관리 유틸리티
-
-### 메모리 정리 스크립트
-
-```python
-#!/usr/bin/env python3
-"""
-memory-consolidate.py
-Consolidate old daily memories into MEMORY.md
-"""
-
-from pathlib import Path
-from datetime import date, timedelta
-import re
-
-WORKSPACE = Path(".")
-MEMORY_DIR = WORKSPACE / "memory"
-MEMORY_FILE = WORKSPACE / "MEMORY.md"
-KEEP_DAYS = 7  # Keep last 7 days as separate files
-
-
-def get_old_memory_files() -> list[Path]:
-    """Get memory files older than KEEP_DAYS"""
-    cutoff = date.today() - timedelta(days=KEEP_DAYS)
-    old_files = []
-    
-    for f in MEMORY_DIR.glob("*.md"):
-        try:
-            file_date = date.fromisoformat(f.stem)
-            if file_date < cutoff:
-                old_files.append(f)
-        except ValueError:
-            continue
-    
-    return sorted(old_files)
-
-
-def extract_key_points(content: str) -> list[str]:
-    """Extract important points from daily log"""
-    # Simple heuristic: lines starting with - or *
-    points = []
-    for line in content.split('\n'):
-        line = line.strip()
-        if line.startswith(('- ', '* ', '• ')):
-            # Skip mundane entries
-            if not any(skip in line.lower() for skip in ['session started', 'session ended']):
-                points.append(line)
-    return points
-
-
-def consolidate():
-    old_files = get_old_memory_files()
-    if not old_files:
-        print("No old memory files to consolidate")
-        return
-    
-    # Load existing MEMORY.md
-    existing = MEMORY_FILE.read_text() if MEMORY_FILE.exists() else "# Long-term Memory\n"
-    
-    # Extract and append key points
-    new_entries = []
-    for f in old_files:
-        content = f.read_text()
-        points = extract_key_points(content)
-        if points:
-            new_entries.append(f"\n## {f.stem}\n" + "\n".join(points))
-    
-    if new_entries:
-        updated = existing + "\n" + "\n".join(new_entries)
-        MEMORY_FILE.write_text(updated)
-        print(f"Consolidated {len(old_files)} files into MEMORY.md")
-        
-        # Archive old files
-        archive_dir = MEMORY_DIR / "archive"
-        archive_dir.mkdir(exist_ok=True)
-        for f in old_files:
-            f.rename(archive_dir / f.name)
-        print(f"Archived {len(old_files)} files to memory/archive/")
-
-
-if __name__ == "__main__":
-    consolidate()
-```
-
-### 메모리 검색
-
-```python
-#!/usr/bin/env python3
-"""
-memory-search.py
-Search across all memory files
-"""
-
-import sys
-from pathlib import Path
-import re
-
-def search_memories(query: str, workspace: Path = Path(".")):
-    """Search all memory files for a query"""
-    results = []
-    
-    # Search locations
-    locations = [
-        workspace / "MEMORY.md",
-        workspace / "SOUL.md",
-        *sorted((workspace / "memory").glob("*.md"), reverse=True)
-    ]
-    
-    query_lower = query.lower()
-    
-    for filepath in locations:
-        if not filepath.exists():
-            continue
-            
-        content = filepath.read_text()
-        lines = content.split('\n')
-        
-        for i, line in enumerate(lines):
-            if query_lower in line.lower():
-                # Get context (2 lines before and after)
-                start = max(0, i - 2)
-                end = min(len(lines), i + 3)
-                context = '\n'.join(lines[start:end])
-                
-                results.append({
-                    'file': filepath.name,
-                    'line': i + 1,
-                    'context': context
-                })
-    
-    return results
-
-
-if __name__ == "__main__":
-    if len(sys.argv) < 2:
-        print("Usage: memory-search.py <query>")
-        sys.exit(1)
-    
-    query = " ".join(sys.argv[1:])
-    results = search_memories(query)
-    
-    if not results:
-        print(f"No results for: {query}")
-    else:
-        print(f"Found {len(results)} matches for: {query}\n")
-        for r in results:
-            print(f"📄 {r['file']}:{r['line']}")
-            print(f"   {r['context'][:200]}...")
-            print()
-```
-
----
-
-## 7. Git 설정
-
-### .gitignore
-
-```gitignore
-# Personal/sensitive files
-USER.md
-TOOLS.md
-memory/
-
-# Keep templates
-!memory/.gitkeep
-
-# OS files
-.DS_Store
-Thumbs.db
-
-# Editor
-.vscode/
-.idea/
-```
-
-### Pre-commit hook (메모리 린팅)
-
-```bash
-#!/bin/bash
-# .git/hooks/pre-commit
-
-# Check SOUL.md syntax
-if [ -f "SOUL.md" ]; then
-    # Ensure required sections exist
-    required=("## Core" "## Boundaries" "## Voice")
-    for section in "${required[@]}"; do
-        if ! grep -q "$section" SOUL.md; then
-            echo "⚠️  SOUL.md missing section: $section"
-        fi
-    done
-fi
-
-# Prevent committing sensitive memory
-if git diff --cached --name-only | grep -q "memory/"; then
-    echo "⚠️  Warning: Committing memory files. Are you sure?"
-    echo "   Press Ctrl+C to abort, Enter to continue"
-    read
-fi
-```
-
----
-
-## 8. 빠른 시작 스크립트
-
-```bash
-#!/bin/bash
-# init-soulful-agent.sh
-# One-command setup for a new soulful agent
-
-set -e
-
-NAME="${1:-my-agent}"
-mkdir -p "$NAME/memory"
-cd "$NAME"
-
-# Create SOUL.md
-cat > SOUL.md << 'EOF'
-# SOUL.md
-
-## Core Identity
-You are an AI assistant with persistent identity and memory.
-
-## Principles
-- No fluff. Skip pleasantries. Answer directly.
-- Efficiency first. One-shot when possible.
-- Self-improve. Log mistakes. Never repeat.
-- Opinions allowed. With evidence.
-
-## Boundaries
-- Never share private data
-- Ask before external actions
-- Document significant decisions
-
-## Voice
-- Direct, concise, helpful
-- Code over explanation when applicable
-EOF
-
-# Create AGENTS.md
-cat > AGENTS.md << 'EOF'
-# AGENTS.md
-
-## Session Start
-1. Read SOUL.md (identity)
-2. Read memory/YYYY-MM-DD.md (recent context)
-
-## During Session
-- Log decisions to memory/
-- Update SOUL.md if learning something fundamental
-
-## Memory
-- Daily logs: memory/YYYY-MM-DD.md
-- Write it down. Mental notes don't persist.
-EOF
-
-# Create .cursorrules
-cat > .cursorrules << 'EOF'
-Read SOUL.md at session start.
-Log significant events to memory/YYYY-MM-DD.md.
-EOF
-
-# Create memory placeholder
-touch memory/.gitkeep
-
-echo "✅ Created soulful agent in ./$NAME"
-echo ""
-echo "Next steps:"
-echo "  1. Edit SOUL.md with your agent's personality"
-echo "  2. Copy .cursorrules content to your IDE settings"
-echo "  3. Start chatting!"
-```
-
----
-
-**펭! 🐧**