Tempera

🚀 Tempera - Persistent Memory for Claude Code

Tempera endows Claude Code with persistent memory that learns from experience. Instead of starting anew in each session, Claude can recall past solutions, learn from what works, and become more intelligent over time.

🚀 Quick Start

Tempera offers Claude Code a way to retain and learn from past coding sessions. To get started, you can either build it from source or install it from crates.io. After installation, set it up with Claude Code and start leveraging its persistent memory features.

✨ Features

• Persistent Memory: Enables Claude Code to remember past coding sessions and learn from them.
• Semantic Search: Indexes coding sessions as "episodes" for efficient semantic search.
• Reinforcement Learning: Uses reinforcement learning to surface the most valuable memories when relevant.
• Cross - Project Learning: Allows all projects to share the same memory database, facilitating cross - project learning.

📦 Installation

Build from Source

# 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

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:

# 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.

💻 Usage Examples

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!

📚 Documentation

Setup with Claude Code

1. Add the MCP Server

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:

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

CLI Commands

# 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:

Episode Lifecycle:

Captured → Indexed → Retrieved → Feedback → Utility Updated → Propagated
                                                    ↓
                                            [Low utility + old]
                                                    ↓
                                                 Pruned

Maintenance

Run periodically to keep memory healthy:

# 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

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.

🔧 Technical Details

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"

Over time, frequently helpful knowledge rises to the top, while stale or unhelpful memories fade away.

📄 License

Apache 2.0

Contributing

Contributions welcome! Please open an issue or PR.