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"     │
│     + Session context: related episodes from the same task     │
└────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────────────┐
│  3. SOLVE FASTER                                               │
│     Claude uses past experience to solve the problem           │
└────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────────────┐
│  4. CAPTURE SESSION                                            │
│     Claude saves: what was done, what worked, what failed      │
│     Auto-links to current session for multi-step tasks         │
└────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────────────┐
│  5. LEARN FROM FEEDBACK                                        │
│     User: "That memory was helpful!"                           │
│     → Episode utility increases                                │
│     → Multi-hop Bellman propagation spreads value               │
│     → Session-linked episodes get boosted                      │
│     → 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.

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.

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.

Session chaining: Episodes captured within 2 hours of each other in the same project are automatically linked into a session. This allows multi-step tasks to share utility and context.

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
        📎 Session abc1 has 2 related episode(s):
           - def45678 (Added CSP headers for redirect...)

        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

# 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 (now with multi-hop and convergence tracking)
tempera propagate --temporal

# Prune old/low-value episodes (uses config.toml fallbacks when flags omitted)
tempera prune --older-than 90 --min-utility 0.2 --execute

# View statistics
tempera stats

# View trend analytics (helpfulness over time, domain growth, learning curve)
tempera trends
tempera trends --project myproject --bucket monthly

Data Storage

Tempera stores everything locally in ~/.tempera/ (shared across all projects):

~/.tempera/
├── config.toml              # Configuration (all RL params configurable)
├── episodes/                # Episode JSON files
│   └── 2026-01-25/
│       └── session-abc123.json
├── vectors/                 # Vector database (vectrust/RocksDB)
│   └── episodes/
└── models/                  # Embedding model cache (~128MB)
    └── models--Xenova--bge-small-en-v1.5/

All projects share the same memory database, enabling cross-project learning.

Configuration

All RL parameters are configurable via ~/.tempera/config.toml:

[retrieval]
similarity_weight = 0.3        # Weight for semantic similarity
utility_weight = 0.7           # Weight for learned utility
recency_weight = 0.0           # Weight for recency (0 = off, opt-in)
recency_halflife_days = 30.0   # Episodes score 0.5 at this age
mmr_lambda = 0.7               # MMR diversity (0=diverse, 1=relevant)
min_similarity = 0.5           # Filter threshold

[bellman]
gamma = 0.9                    # Discount factor for Bellman updates
alpha = 0.1                    # Learning rate
decay_rate = 0.01              # Utility decay per day (1%)
propagation_threshold = 0.5    # Min similarity for propagation
max_propagation_depth = 2      # Multi-hop depth (hops)
temporal_credit_window_hours = 1  # Lookback for temporal credit

[storage]
max_age_days = 180             # Max episode age for pruning
min_utility_threshold = 0.05   # Min utility to keep
min_retrievals = 2             # Min retrievals before pruning allowed
consolidation_threshold = 0.85 # BKM merge threshold
cluster_threshold = 0.85       # Duplicate clustering threshold
stale_age_days = 30            # Age threshold for stale detection
stale_utility_threshold = 0.2  # Utility threshold for stale detection

The RL Behind the Scenes

Multi-hop Bellman Propagation

Value from helpful episodes spreads through the similarity graph in multiple hops:

Hop 0: Source episodes (high helpfulness, ≥2 retrievals)
  │
  ▼  γ¹ discount
Hop 1: Similar episodes updated
  │
  ▼  γ² discount
Hop 2: Episodes similar to hop-1 updated
  │
  ▼  Converges when no updates occur

Session Chaining

Episodes captured within 2 hours of each other in the same project are automatically linked:

Session abc123:
  ├── Episode 1: "Investigated auth bug" (debug)
  ├── Episode 2: "Found root cause in token validation" (research)
  └── Episode 3: "Fixed token expiry check" (bugfix, success)
       ↓
  Temporal credit flows back to episodes 1 & 2
  Session-linked propagation boosts all 3

Scoring Formula

Retrieval ranking combines three signals with normalized weights:

score = (sim_w × similarity + util_w × utility + rec_w × recency) / (sim_w + util_w + rec_w)

Default: 30% similarity, 70% utility, 0% recency (recency is opt-in via config).

Maintenance

Run periodically to keep memory healthy:

# Weekly: Propagate utility values (now multi-hop with convergence)
tempera propagate --temporal

# Monthly: Clean up old/useless episodes
tempera prune --older-than 90 --min-utility 0.2 --execute

# As needed: Check trends
tempera trends

# As needed: Review and consolidate
# (via MCP) tempera_review(action: "consolidate")

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.

License

Apache 2.0

Contributing

Contributions welcome! Please open an issue or PR.