Tempera

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 — and the system itself accumulates a per-project picture of where it tends to be wrong.

The bigger surfaces (v0.6 onward)

Beyond the basic capture/retrieve loop, Tempera ships several higher-order surfaces. Each is opt-in but all flow through the same MCP tools — Claude can use them without any custom client code.

• Grounded capture (v0.6): Every captured claim carries a falsifiability score, a category, and a ValidityScope (Forever / Language / Crate / Domain / Workaround / Project). Decay rates are per-scope — universal truths never expire, project-specific conventions fade in months, workarounds expire when the underlying issue closes.
• Dream cycle (v0.7): A budgeted nightly pipeline that runs verify_advance → decay → reflect → patterns → contradict → templates. Reflections turn high-signal days into prose; patterns surface themes that keep recurring; contradict probes pairs of frequently-retrieved episodes for factual disagreements; templates extract reusable step sequences from successful task clusters.
• Self-improvement (v0.8): Calibration tracks the ratio of declared vs. verified successes per (task, project). Mistakes log records corrections the agent made. Should-have-asked log records questions it realized it should have asked first. Ask-backs are clarifying questions the *system itself* drafts via Haiku when a capture ends in failure with vague intent — queued for the next session in that project.
• Brief surface (v0.9): One MCP call joins all of the above against the file set the agent is about to touch. tempera_brief(files, task_type?, domain?) returns pending ask-backs, the matching reasoning template, top correction categories for those files, should-have-asked triggers, and a calibration warning if the agent's track record on this kind of task is shaky.
• Cross-project learning (v0.10): tempera_retrieve and tempera_brief both accept cross_project=true. Transferable claims (anything not project-scoped) surface across projects; Project-scoped knowledge stays bound to its codebase. Legacy captures default to non-transferable until reclassified.

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 12 tools.

MCP Tools

Once connected, Claude has access to these 12 tools, grouped by purpose:

Session warmup (call at task start)

During task

End of task

Diagnostics + maintenance

Standard warmup pattern

tempera_session_start          # is anything queued from last session?

tempera_brief(files, ...) # what does tempera know about this exact change? tempera_retrieve(query) # then deep-dive into specific episodes

Key Lifecycle Behaviors

Start of session: Call tempera_session_start first to consume any pending ask-back, then tempera_brief once the file set is known.

End of task: Capture successful sessions with tempera_capture — don't wait to be asked. Capture also drafts an ask-back via Haiku if the outcome was Failure/Partial with vague intent, so the next session in this project sees the gap.

Session chaining: Episodes captured within 2 hours of each other in the same project are automatically linked. Multi-step tasks share utility and context.

Cross-project routing: New captures get a ValidityScope suggestion from the intent-extraction LLM (v0.10.3). Project-scoped claims stay bound to one codebase; Language / Crate / Domain / Workaround / Forever claims surface across projects when retrieval opts in.

tempera_retrieve Modes

Search:           tempera_retrieve(query: "authentication bug")

List all: tempera_retrieve(all: true) Show details: tempera_retrieve(query: "abc12345") # episode ID Cross-project: tempera_retrieve(query: "sqlx ordering", scope: "cross-project")

Example Conversation

User: Fix the login redirect vulnerability

Claude: [Calls tempera_session_start()] No pending ask-back — proceeding.

[Calls tempera_brief(files: ["src/auth.rs", "src/router.rs"], task_type: "bugfix", domain: "auth-middleware")]

🔴 PENDING ASK-BACK Ask the user first: "Should auth run before o