Claude Code의 영구 장기 기억

Yet Another Useless Claude Code Agent — persistent long-term memory for Claude Code, deployed as a self-hosted FastAPI + SQLite + sqlite-vec backend on Modal.com. Inspired by the MemGPT tiered memory architecture (now Letta), but built as a lightweight single-container stack with scale-to-zero billing (~$0-1/month). Every Claude Code session starts with full memory context and ends by persisting what happened. Memory survives across sessions, projects, and context compactions — accessible from Claude Code (laptop), Claude.ai (web), and Claude mobile (phone). ┌──────────────────────────────────────────────────────┐ │ Modal.com (scale-to-zero, ~$0-1/month) │ │ │ │ FastAPI + SQLite + sqlite-vec + Qwen3 embeddings │ │ Remote MCP (OAuth 2.1 + GitHub login) │ │ Persistent volume: /data/yaucca.db │ └───────────────┬──────────────────────────────────────┘ │ HTTPS ┌───────────┼───────────┐ │ │ │ ┌───┴────┐ ┌────┴───┐ ┌─────┴────┐ │ Claude │ │ Claude │ │ Claude │ │ Code │ │ .ai │ │ mobile │ │(laptop)│ │ (web) │ │ (phone) │ │ │ │ │ │ │ │ hooks │ │ remote │ │ remote │ │+remote │ │ MCP │ │ MCP │ │ MCP │ │ │ │ │ └────────┘ └────────┘ └──────────┘ - Hooks (Claude Code only): SessionStart injects memory, Stop persists raw exchanges, SessionEnd generates a summary via claude -p - Remote MCP (all surfaces): 7 tools for reading/writing memory blocks, semantic search over archival passages, and progressive disclosure drill-down - OAuth 2.1: GitHub login gates access — only allowed users can connect - Core Memory (5 blocks, always loaded): user ,projects ,patterns ,learnings ,context - Archival Memory (searchable): Long-term storage with Qwen3-Embedding-8B semantic vector search (1024 dims via OpenRouter) - Recall Memory (pre-loaded): Recent conversation history injected at startup - Python 3.11+ - uv - Modal account (free tier works) - OpenRouter API key (for embeddings) - GitHub OAuth App (for MCP auth) uv pip install yaucca[deploy] # Guided setup: checks Modal, shows GitHub OAuth instructions, # creates ~/.config/yaucca/.env, deploys to Modal yaucca-deploy yaucca-deploy walks you through each step: - Modal account — checks you're logged in (run modal setup if not) - Server URL — computed from your Modal username - GitHub OAuth App — tells you exactly what to fill in at https://github.com/settings/developers (Homepage URL, Callback URL) - Configuration — creates ~/.config/yaucca/.env with your auth token pre-generated and placeholders for the keys you need to paste in - Deploy — pushes secrets to Modal and deploys (only after .env is complete) First run will pause at step 4 and ask you to edit ~/.config/yaucca/.env with your OpenRouter API key and GitHub OAuth credentials. Fill those in, then re-run yaucca-deploy to finish. On every machine or cloud environment where you use Claude Code: uv pip install yaucca # Interactive setup: seeds your user profile, installs hooks + memory # rules, adds the remote MCP server yaucca-install yaucca-install does four things: - User profile → interactively asks your name, role, etc. and seeds the user memory block on the server (skips if already seeded; use--user-block "..." to skip the interactive prompt) - Hooks → added to ~/.claude/settings.json (SessionStart, Stop, SessionEnd — see Hook lifecycle below) - Memory rules → installed at ~/.claude/rules/yaucca-memory.md — teaches Claude how to use the memory blocks (read-modify-write, hygiene, when to update each block). Edit this file to customize. - MCP server → runs claude mcp add to register the remote MCP server First-time MCP auth: after install, start Claude Code and type /mcp → select yaucca → browser opens for GitHub login → authorize → connected. Token auto-refreshes after that. Claude.ai web / mobile: Settings → Integrations → Add custom integration → paste your server URL /mcp → GitHub OAuth. Claude Code cloud environments: Set YAUCCA_URL + YAUCCA_AUTH_TOKEN as environment variables, then add to your setup script: uv pip install yaucca && yaucca-install | Hook | When | What | Cost | |---|---|---|---| | SessionStart | Session opens | Injects core blocks + recent exchanges | 1 HTTP GET | | Stop | Every turn | Persists raw exchanges | 1 HTTP POST | | SessionEnd | Session closes | claude -p generates summary + updates context block | 1 LLM call | yaucca-install --uninstall # remove hooks claude mcp remove -s user yaucca # remove MCP cp ~/.claude/settings.json.bak ~/.claude/settings.json # restore backup Your data on Modal is never touched by rollback. | Variable | Default | Description | |---|---|---| YAUCCA_URL | (required) | Your Modal deployment URL | YAUCCA_AUTH_TOKEN | (none) | Bearer token for the REST API (hooks use this) | YAUCCA_REQUIRED | false | If true , hooks fail hard when cloud is unreachable | | Variable | Description | |---|---| YAUCCA_AUTH_TOKEN | Same token as client-side — authenticates hook REST calls | OPENROUTER_API_KEY | For Qwen3-Embedding-8B embeddings | YAUCCA_ISSUER_URL | Public URL of your deployment (OAut