memory-retro

# Memory Retro You have access to a role-based persistent memory system. Use manual writes selectively; automatic extraction already handles routine task-end checkpoints. ## Tools Available | Tool | Purpose | |------|---------| | `role_exec({ op: "add_learning", args: { content: "..." } })` | Save a durable insight. LLM auto-extracts tags. Auto-deduplicates. | | `role_exec({ op: "add_preference", args: { content: "...", category: "..." } })` | Save a user preference. Goes directly to consolidated. | | `role_search({ query: "..." })` | Check if similar memory already exists | | `role_exec({ op: "reinforce", args: { content: "..." } })` | Increment `[Nx]` usage count for existing learning | ## Process 1. **Reflect**: What did I learn that would be useful in the future? 2. **If nothing worth remembering, skip** — not every task produces insights. 3. **For each insight**, decide type: - **Learning**: Durable cross-session fact, pattern, or rule. - **Preference**: User's communication style, tool preference, coding habit. ### Dedup check (built-in) `add_learning` auto-deduplicates. Just call it — if similar text exists, it returns "Already stored". Then use `reinforce` instead. ### Write ``` role_exec({ op: "add_learning", args: { content: "MyBatis-Plus getOne needs .last('LIMIT 1') to avoid TooManyResultsException" } }) ``` LLM auto-extracts tags (e.g., `mybatis`, `gotcha`). No manual tagging. ### Preferences ``` role_exec({ op: "add_preference", args: { content: "用户偏好中文沟通，技术术语可保留英文", category: "Communication" } }) ``` ### Reinforce (when you USE an existing memory) ``` role_exec({ op: "reinforce", args: { content: "安全删除原则" } }) → "Reinforced [abc123] -> 6x" ``` ## Quality Rules ### What to remember - ✅ **Root cause**: "X fails because of Y. Fix: Z" - ✅ **Gotcha**: "Tool A requires flag B, otherwise silently fails" - ✅ **Decision**: "We chose X over Y because Z" - ✅ **Pattern**: "This project uses pattern A for all B" - ✅ **User preference discovered** ### What NOT to remember - ❌ Obvious facts - ❌ Task-specific instances (save the *pattern*, not the *instance*) - ❌ Temporary states - ❌ Redundant with existing entries - ❌ Full error messages without analysis ### Writing rules - **Concise** — under 120 chars - **Own words** — distill, don't copy-paste - **Actionable** — changes how you'd approach similar tasks - **Conservative** — bad memory > missing memory is worse. 1 quality insight > 5 mediocre. ## Pending Layer Two paths to memory: ``` Auto-extract (agent_end, compaction) → pending.md [○] → search score ≥0.5 → auto-promote → consolidated [0x] Manual (this tool) → consolidated [0x] directly ``` The pending layer filters noise. Only memories proven useful by actual usage survive. Manual entries skip pending because you're explicitly deciding they're worth keeping. ## Reinforce vs Promote | Action | Effect | When | |--------|--------|------| | `reinforce` | used+1 in consolidated | You used an existing memory | | Search score ≥0.5 | auto-reinforce (used+1) | Found via search | | Pending auto-promote | pending → consolidated | Pending entry is relevant | | `consolidate` | dedup + canonical rewrite | Routine maintenance | ## Category Reference | Category | When | |----------|------| | `Communication` | Language, style, tone | | `Code` | Style, conventions, abstraction | | `Tools` | CLI, editors, workflows | | `Workflow` | Process, review, deployment | | `General` | Everything else | ## Examples ``` ✅ Good: role_exec({ op: "add_learning", args: { content: "MyBatis-Plus getOne needs .last('LIMIT 1')" } }) ✅ Good (reinforce): role_exec({ op: "reinforce", args: { content: "安全删除原则" } }) ❌ Bad: "The user asked me to fix a bug" — too generic ❌ Bad: "Error at /src/index.ts:42" — copy-paste, no insight ``` ## Important - `add_learning` **auto-deduplicates** — if similar exists, use `reinforce` instead. - LLM **auto-extracts tags** — no manual tagging needed. - Quality > quantity. 30 quality entries > 300 noisy ones. - The system auto-extracts at session end, but manual retro is more accurate.