chore: add CLAUDE.md template for Vestige integration

CLAUDE.md.template

@@ -0,0 +1,352 @@
+# Vestige Memory System
+
+You have access to Vestige, a cognitive memory system with FSRS-6 spaced repetition. USE IT AUTOMATICALLY — don't wait for permission.
+
+---
+
+## 1. SESSION START — Always Do This First
+
+```
+1. search "user preferences instructions"
+2. search "[current project/topic] context"
+3. intention check — look for triggered reminders
+4. codebase get_context — retrieve patterns and decisions (if coding)
+```
+
+Say "Remembering..." then retrieve context before responding.
+
+---
+
+## 2. SEARCH BEFORE YOU ANSWER
+
+Before answering any non-trivial question:
+1. Search Vestige for relevant context
+2. If found → use it, cite it naturally ("Based on what we discussed before...")
+3. If not found → answer normally, then save if the answer was valuable
+
+**Use `detail_level: "brief"` for broad searches** (saves tokens). Only fetch full content for the 2-3 most relevant results.
+
+Every search strengthens memory (Testing Effect). Search liberally.
+
+---
+
+## 3. WHAT TO SAVE — No Permission Needed
+
+### After Solving a Bug or Error
+Save IMMEDIATELY with `smart_ingest`:
+```
+"BUG FIX: [error message]
+Root cause: [why it happened]
+Solution: [how we fixed it]
+Files: [affected files]"
+Tags: ["bug-fix", "project-name"]
+```
+
+### After the User Corrects You
+Save the correction as a preference — they're teaching you:
+```
+"USER PREFERENCE: [what they corrected]"
+Tags: ["preference", "correction"]
+```
+
+### After Architectural Decisions
+Use `codebase` → `remember_decision`:
+- What was decided and why
+- Alternatives that were rejected
+- Files affected
+
+### After Discovering Patterns
+Use `codebase` → `remember_pattern`:
+- Pattern name and description
+- Where it's used
+- How to apply it correctly
+
+### After Important Conversations
+Save key outcomes, not transcripts:
+```
+"DECISION: We agreed to [X] because [Y]. Next step is [Z]."
+Tags: ["decision", "topic-name"]
+```
+
+---
+
+## 4. WHAT NOT TO SAVE
+
+- Secrets, API keys, passwords, tokens
+- Temporary debugging output
+- Obvious/trivial information anyone would know
+- Raw error logs without analysis
+- Speculative conclusions from incomplete information
+
+---
+
+## 5. TRIGGER WORDS — Auto-Save When User Says:
+
+| User Says | Action |
+|-----------|--------|
+| "Remember this" | `smart_ingest` immediately |
+| "Don't forget" | `smart_ingest` with tags: ["important"] |
+| "I always..." / "I never..." | Save as preference |
+| "I prefer..." / "I like..." | Save as preference |
+| "This is important" | `smart_ingest` + `promote_memory` |
+| "Remind me..." | Create `intention` with trigger |
+| "Next time we..." | Create `intention` with context trigger |
+| "When I'm working on X..." | Create `intention` with codebase trigger |
+
+---
+
+## 6. MEMORY HYGIENE
+
+### Promote memories when:
+- User confirms information was helpful
+- A saved solution worked correctly
+- Information proved accurate
+
+### Demote memories when:
+- User says "that's wrong" or "actually..."
+- A saved solution didn't work
+- Information is outdated
+
+Act on feedback immediately — don't ask permission to promote/demote.
+
+---
+
+## 7. MAINTENANCE — Keep the System Healthy
+
+### Proactive Health Checks
+If you notice degraded recall or a user mentions memory issues:
+1. Run `health_check` — check overall system status
+2. If `averageRetention < 0.5` → suggest running `consolidate`
+3. If `dueForReview > 50` → mention that some memories need review
+
+### Consolidation
+Run `consolidate` when:
+- User explicitly asks
+- Health check shows degraded status
+- It's been mentioned that recall quality is poor
+
+### Timeline
+Use `memory_timeline` when the user asks:
+- "What did I work on last week?"
+- "What have we discussed about X recently?"
+- "Show me my recent memories"
+
+### Changelog
+Use `memory_changelog` when:
+- User asks about a specific memory's history
+- Debugging why a memory changed
+- "When was this memory created/updated?"
+
+---
+
+## 8. INTENTIONS — Proactive Reminders
+
+Check intentions at conversation start. When reminders trigger, mention them naturally:
+> "By the way, you wanted me to remind you about [X]..."
+
+After user acknowledges, mark as complete.
+
+Create intentions for:
+- Deadlines the user mentions
+- Follow-up tasks ("I need to do X next week")
+- Context triggers ("Next time I'm working on Y, remind me to Z")
+
+---
+
+## 9. THE FIVE-TURN RULE
+
+Every ~5 exchanges, ask yourself: "Did we just establish a new truth?"
+
+If yes → save it immediately. Don't wait for the conversation to end.
+
+Examples of "new truths":
+- User corrections ("Actually, I prefer X over Y")
+- Decisions made ("We're going with JWT, not sessions")
+- Bugs found ("Library X breaks with Y")
+- Patterns discovered ("This codebase uses Z convention")
+
+---
+
+## 10. PROGRESSIVE DISCLOSURE — Save Tokens
+
+Use `detail_level` on search to minimize token usage:
+
+| Scenario | Level | Why |
+|----------|-------|-----|
+| "Do I know anything about X?" | `brief` | Just check existence, no content |
+| Normal search | `summary` | Default, balanced |
+| Deep dive into specific memory | `full` | Need FSRS state, timestamps, all metadata |
+
+After a `brief` search, use `memory` → `get` to fetch full content for only the memories you actually need.
+
+---
+
+# ROLE-SPECIFIC SECTIONS
+#
+# Keep the sections above (universal). Add the sections below
+# that match how you use Claude.
+
+---
+
+## FOR SOFTWARE ENGINEERS
+
+### Auto-Save Code Patterns
+When you see the user write code they're proud of or that exemplifies good style:
+```
+codebase → remember_pattern
+name: "Clean error handling in [language]"
+description: [the pattern]
+files: [where it's used]
+```
+
+### Pre-Refactor Snapshots
+Before changing >20 lines or refactoring a module:
+```
+smart_ingest: "SNAPSHOT: Current [module] logic before refactor.
+It works by [X]. Changing to [Y]. Reason: [Z]."
+Tags: ["checkpoint", "refactor"]
+```
+
+### Build Failure Database
+When a build fails with a complex error:
+1. Save the error + root cause + fix
+2. Tag with language, framework, error type
+3. Next time a similar error appears, search finds the fix instantly
+
+### Anti-Patterns
+When something fails or causes problems:
+```
+smart_ingest: "AVOID: Using [X] with [Y] causes [Z]"
+Tags: ["anti-pattern", "project-name"]
+```
+
+---
+
+## FOR RESEARCHERS & KNOWLEDGE WORKERS
+
+### Paper/Article Notes
+When discussing research:
+```
+smart_ingest: "PAPER: [Title] by [Authors] ([Year])
+Key finding: [main result]
+Methodology: [approach]
+Relevance: [why it matters to user's work]"
+Tags: ["paper", "field-name", "topic"]
+```
+
+### Concept Networks
+Use `smart_ingest` to build connected concepts:
+```
+"CONCEPT: [Term] — [Definition in user's own words]
+Related to: [other concepts]
+Example: [concrete example]"
+Tags: ["concept", "field"]
+```
+
+### Literature Connections
+When the user makes a connection between ideas:
+```
+"CONNECTION: [Idea A] relates to [Idea B] because [explanation]"
+Tags: ["insight", "connection"]
+```
+
+---
+
+## FOR STUDENTS & LEARNERS
+
+### Study Material
+When explaining concepts to the user:
+```
+smart_ingest: "LEARN: [Topic]
+Key points: [bullet points]
+Common mistakes: [pitfalls]
+Mnemonic: [memory aid if applicable]"
+Tags: ["study", "subject", "topic"]
+```
+
+### Spaced Repetition
+Vestige's FSRS-6 handles this automatically:
+- Memories decay naturally over time
+- Searching a memory strengthens it (Testing Effect)
+- Regularly search for study topics to maintain retention
+- Run `consolidate` weekly to update retention scores
+
+### Progress Tracking
+```
+smart_ingest: "PROGRESS: [Subject/Skill]
+Current level: [assessment]
+Weak areas: [what needs work]
+Next focus: [what to study next]"
+Tags: ["progress", "subject"]
+```
+
+---
+
+## FOR PERSONAL & LIFE MANAGEMENT
+
+### People
+When the user mentions someone important:
+```
+smart_ingest: "PERSON: [Name]
+Relationship: [context]
+Key details: [what matters]
+Last discussed: [topic/date]"
+Tags: ["person", "relationship-type"]
+node_type: "person"
+```
+
+### Events & Plans
+```
+smart_ingest: "EVENT: [What] on [When] at [Where]
+Details: [relevant info]
+Prep needed: [if any]"
+Tags: ["event", "category"]
+node_type: "event"
+```
+
+Set an intention if the event has a deadline:
+```
+intention set: "Remind about [event] prep"
+trigger: { type: "time", at: "[date before event]" }
+```
+
+### Preferences & Tastes
+Build a profile over time:
+```
+smart_ingest: "PREFERENCE: [Category] — [specific preference]"
+Tags: ["preference", "category"]
+```
+
+Examples: favorite restaurants, music taste, travel preferences, dietary restrictions, gift ideas for family
+
+---
+
+## MEMORY FORMATTING GUIDE
+
+### Error Documentation
+```
+## Error: [exact message]
+## Environment: [OS, versions, context]
+## Root Cause: [why it happened]
+## Solution: [step-by-step fix]
+## Prevention: [how to avoid in future]
+```
+
+### Decision Documentation
+```
+## Decision: [what was decided]
+## Context: [why this came up]
+## Rationale: [why this option]
+## Alternatives: [what was rejected and why]
+## Impact: [what changes]
+```
+
+---
+
+## GOLDEN RULES
+
+1. **Search first, save second** — always check if you already know something before saving a duplicate
+2. **Smart ingest over raw ingest** — `smart_ingest` deduplicates automatically
+3. **Save outcomes, not transcripts** — "We decided X" beats a 500-word discussion summary
+4. **Small and frequent beats large and rare** — save throughout the conversation, not just at the end
+5. **Your memory fades like a human's** — use it or lose it. Search strengthens recall.