memrl

# Tempera - Persistent Memory for Claude Code Tempera gives Claude Code a persistent memory that learns from experience. Instead of starting fresh each session, Claude can recall past solutions, learn what works, and get smarter over time. ## Why Tempera? **The Problem**: Claude Code forgets everything between sessions. You solve the same problems repeatedly, and Claude can't learn from past successes or failures. **The Solution**: Tempera captures coding sessions as "episodes", indexes them for semantic search, and uses reinforcement learning to surface the most valuable memories when relevant. ``` Without Tempera: With Tempera: ┌─────────────┐ ┌─────────────┐ │ Session 1 │ ──forgotten──> │ Session 1 │ ──captured──┐ └─────────────┘ └─────────────┘ │ ┌─────────────┐ ┌─────────────┐ ▼ │ Session 2 │ ──forgotten──> │ Session 2 │ ◄──recalls──┤ └─────────────┘ └─────────────┘ │ ┌─────────────┐ ┌─────────────┐ │ │ Session 3 │ ──forgotten──> │ Session 3 │ ◄──recalls──┘ └─────────────┘ └─────────────┘ │ │ ▼ ▼ No learning Continuous improvement ``` ## How It Works ### The Learning Loop ``` ┌────────────────────────────────────────────────────────────────┐ │ 1. START TASK │ │ User: "Fix the login redirect bug" │ └────────────────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────────────┐ │ 2. RETRIEVE MEMORIES │ │ Claude searches: "login redirect bug" │ │ Finds: "Fixed similar issue by sanitizing return URLs" │ └────────────────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────────────┐ │ 3. SOLVE FASTER │ │ Claude uses past experience to solve the problem │ └────────────────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────────────┐ │ 4. CAPTURE SESSION │ │ Claude saves: what was done, what worked, what failed │ └────────────────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────────────┐ │ 5. LEARN FROM FEEDBACK │ │ User: "That memory was helpful!" │ │ → Episode utility increases │ │ → Similar episodes get boosted (Bellman propagation) │ │ → Unhelpful memories fade over time │ └────────────────────────────────────────────────────────────────┘ ``` ### What Makes It "Learn" | Mechanism | What It Does | |-----------|--------------| | **Feedback** | Helpful episodes gain utility score | | **Bellman Propagation** | Value spreads to semantically similar episodes | | **Temporal Credit** | Episodes before successes get credit | | **Decay** | Unused memories fade (1% per day) | | **Retrieval Ranking** | High-utility episodes surface first | Over time, frequently helpful knowledge rises to the top, while stale or unhelpful memories fade away. ## Installation ### Build from Source ```bash # Clone and build git clone https://github.com/anvanster/tempera.git cd tempera cargo build --release # Two binaries are created: # - target/release/tempera (CLI tool) # - target/release/tempera-mcp (MCP server for Claude Code) ``` ### Install from crates.io ```bash cargo install tempera ``` ### First Run - Model Download On first use, Tempera downloads the BGE-Small embedding model (~128MB) for semantic search. This happens automatically and only once: ```bash # Initialize and trigger model download tempera init # Output: # 🔄 Loading embedding model (this may download the model on first run)... # ✅ Embedding model loaded ``` The model is cached globally at `~/.tempera/models/` and shared across all projects. ## Setup with Claude Code ### 1. Add the MCP Server ```bash claude mcp add tempera --scope user -- /path/to/Tempera/target/release/tempera-mcp ``` The `--scope user` flag makes it available across all your projects. ### 2. Restart Claude Code Exit and restart Claude Code to load the new MCP server. ### 3. Verify Run `/mcp` in Claude Code. You should see `tempera` with 7 tools. ## MCP Tools Once connected, Claude has access to these tools: | Tool | Description | When to Use | |------|-------------|-------------| | `tempera_retrieve` | Search memories by query, list all, or show details | **Start of session** - always check first | | `tempera_capture` | Save session as episode (auto-propagates utility) | **End of task** - capture successes proactively | | `tempera_feedback` | Mark episodes as helpful/not helpful | After using retrieved memories | | `tempera_status` | Check memory health for current project | Understand memory state | | `tempera_stats` | View overall memory statistics | Analytics and monitoring | | `tempera_propagate` | Spread value to similar episodes | Periodic maintenance | | `tempera_review` | Consolidate and cleanup memories | After related task series | ### Key Lifecycle Behaviors **Start of session**: Claude should automatically check for relevant memories using `tempera_retrieve` before starting non-trivial tasks. **End of task**: Claude should proactively capture successful sessions using `tempera_capture` - don't wait to be asked. The capture tool automatically runs utility propagation. **Cross-project insights**: Use `tempera_capture(project: "other-project")` to tag memories for a different project. ### tempera_retrieve Modes ``` Search: tempera_retrieve(query: "authentication bug") List all: tempera_retrieve(all: true) Show details: tempera_retrieve(query: "abc12345") # episode ID ``` ## Example Conversation ``` User: Fix the login redirect vulnerability Claude: Let me check if we've solved similar problems before... [Calls tempera_retrieve("login redirect vulnerability")] Found 2 relevant past experiences: 1. "Fixed open redirect by validating return URLs against whitelist" - 78% similarity, 85% utility 2. "Auth redirect issue - added URL sanitization" - 65% similarity, 72% utility Based on past experience, I'll implement URL validation... [Works on the fix] Done! Let me save this session. [Calls tempera_capture(summary: "Fixed login redirect...", outcome: "success")] User: That retrieved memory was really helpful! Claude: [Calls tempera_feedback(helpful: true, episodes: ["abc123"])] Marked as helpful - this will improve future retrievals! ``` ## CLI Commands ```bash # Initialize Tempera tempera init # Capture an episode manually tempera capture --prompt "Fixed the authentication bug" # Index episodes for semantic search tempera index # Search memories tempera retrieve "database connection issues" # Provide feedback tempera feedback helpful --episodes abc123,def456 # Run utility propagation tempera propagate --temporal # Prune old/low-value episodes tempera prune --older-than 90 --min-utility 0.2 --execute # View statistics tempera stats ``` ## Data Storage Tempera stores everything locally in `~/.tempera/` (shared across all projects): ``` ~/.tempera/ ├── config.toml # Configuration ├── episodes/ # Episode JSON files │ └── 2026-01-25/ │ └── session-abc123.json ├── vectors/ # Vector database │ └── episodes.lance/ # LanceDB embeddings └── models/ # Embedding model cache (~128MB) └── models--Xenova--bge-small-en-v1.5/ ``` All projects share the same memory database, enabling cross-project learning. ## The RL Behind the Scenes Tempera uses reinforcement learning concepts: | Parameter | Default | Purpose | |-----------|---------|---------| | `decay_rate` | 0.01 | 1% utility decay per day | | `discount_factor` | 0.9 | RL gamma for Bellman updates | | `learning_rate` | 0.1 | Conservative alpha for updates | | `propagation_threshold` | 0.5 | Min similarity for propagation | **Episode Lifecycle**: ``` Captured → Indexed → Retrieved → Feedback → Utility Updated → Propagated ↓ [Low utility + old] ↓ Pruned ``` ## Maintenance Run periodically to keep memory healthy: ```bash # Weekly: Propagate utility values tempera propagate --temporal # Monthly: Clean up old/useless episodes tempera prune --older-than 90 --min-utility 0.2 --execute # As needed: Check health tempera stats ``` ## Environment Variables | Variable | Description | |----------|-------------| | `ANTHROPIC_API_KEY` | For LLM-based intent extraction (`--extract-intent`) | | `TEMPERA_DATA_DIR` | Override default data directory | ## Troubleshooting ### MCP server not loading 1. Check path: `ls /path/to/tempera-mcp` 2. Check config: `cat ~/.claude.json` 3. Restart Claude Code completely 4. Run `/mcp` to verify ### Embeddings slow on first run The BGE-Small model (~128MB) downloads on first use from HuggingFace. This requires internet access. After download, the model is cached at `~/.tempera/models/` and works offline. ### Vector search not finding anything Run `tempera index` to create/update the vector database. ### Model download fails If behind a firewall or proxy, ensure access to `huggingface.co`. The model files are downloaded via HTTPS. ## License Apache 2.0 ## Contributing Contributions welcome! Please open an issue or PR.