tempera

Tempera - Claude Code 的持久记忆

Tempera 为 Claude Code 提供可从经验中学习的持久记忆。Claude 无需每次会话都从头开始，而是可以回忆过去的解决方案、学习哪些方法有效，并随着时间推移变得更聪明。

为什么选择 Tempera？

问题：Claude Code 会忘记不同会话之间发生的一切。你会反复解决相同的问题，而 Claude 无法从过去的成功或失败中学习。

解决方案：Tempera 会将编码会话记录为“情节”，为其建立索引以进行语义搜索，并通过强化学习，在相关时呈现最有价值的记忆。

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

工作原理

学习循环

┌────────────────────────────────────────────────────────────────┐
│  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                        │
└────────────────────────────────────────────────────────────────┘

它如何实现“学习”

机制	作用
反馈	有帮助的情节会获得效用分数
多跳 Bellman 传播	价值会沿相似度图跨多个跳数传播
会话串联	多步骤任务中的相关情节会相互关联并彼此增益
时间信用分配	成功之前的情节也会获得信用（即使跨越会话边界）
近期内容加权	检索时可以提高新情节的权重（可选）
感知范围的衰减	项目相关的声明约 70 天后逐渐淡化；语言层面的事实可保留约 3 年；普遍真理永不衰减
验证状态	捕获的内容会经历 Untested → TestsPass → Merged → StableNoRevert；后续状态的权重更高
校准	按（任务、项目）统计已验证与已声明内容的比例，以揭示过度自信
梦境周期	每晚进行反思、模式检测、矛盾探查和模板提取
自我改进日志	跟踪纠正和遗漏的问题，并为下一次会话排队待澄清的问题
跨项目迁移	标记为语言／crate／领域／永久范围的声明可在多个项目中呈现

随着时间推移，经常带来帮助的知识会逐渐升至顶部，而过时或无用的记忆会逐渐淡去——系统本身也会逐步积累各个项目中容易出错之处的概况。

更丰富的功能面（v0.6 起）

除了基本的捕获/检索流程，Tempera 还提供了几种更高阶的功能面。每种功能都可选择启用，但都会通过同一组 MCP 工具运行——Claude 无需任何自定义客户端代码即可使用。

• 有依据的捕获（v0.6）：每条捕获的声明都带有 falsifiability 分数、category 和 ValidityScope（Forever / Language / Crate / Domain / Workaround / Project）。衰减速率按作用域区分——普遍真理永不过期，项目特定的约定会在数月内逐渐淡化，问题解决后，变通方案就会过期。
• 梦境周期（v0.7）：一条设有预算的夜间流水线，按顺序运行 verify_advance → decay → reflect → patterns → contradict → templates。反思会将高信号日整理成文字；模式会呈现反复出现的主题；矛盾探查会检查经常检索到的事件对是否存在事实分歧；模板会从成功的任务簇中提取可复用的步骤序列。
• 自我改进（v0.8）：校准会跟踪每种（任务、项目）组合下已声明成功与已验证成功的比例。错误日志会记录 Agent 做出的修正。“本应先询问”日志会记录 Agent 意识到自己本应先提出的问题。如果一次捕获以失败告终且意图含糊，系统本身会通过 Haiku 起草澄清问题，作为后续追问——并排入该项目下一次会话的队列。
• 简报功能面（v0.9）：只需一次 MCP 调用，就能结合 Agent 即将处理的文件集，汇总以上所有信息。tempera_brief(files, task_type?, domain?) 会返回待处理的追问、匹配的推理模板、这些文件最常见的修正类别、本应先询问的触发条件，以及在 Agent 处理此类任务的记录不佳时发出的校准警告。
• 跨项目学习（v0.10）：tempera_retrieve 和 tempera_brief 都接受 cross_project=true。可迁移的声明（任何非项目作用域的内容）会跨项目显示；项目作用域的知识则仅限于其代码库。旧版捕获在重新分类前，默认不可迁移。

安装

从源代码构建

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

从 crates.io 安装

cargo install tempera

首次运行 - 下载模型

首次使用时，Tempera 会下载用于语义搜索的 BGE-Small 嵌入模型（约 128MB）。此过程会自动进行，且只需执行一次：

# Initialize and trigger model download
tempera init

# Output:
# 🔄 Loading embedding model (this may download the model on first run)...
# ✅ Embedding model loaded

模型会缓存在全局目录 ~/.tempera/models/ 中，并由所有项目共享。

在 Claude Code 中设置

1. 添加 MCP 服务

claude mcp add tempera --scope user -- /path/to/Tempera/target/release/tempera-mcp

--scope user 标志会使其在你的所有项目中均可用。

2. 重启 Claude Code

退出并重启 Claude Code，以加载新的 MCP 服务。

3. 验证

在 Claude Code 中运行 /mcp。你应该会看到包含 12 个工具的 tempera。

MCP 工具

连接后，Claude 即可使用以下 12 个工具，按用途分组：

会话预热（在任务开始时调用）

工具	使用时机
tempera_session_start	在最开始时调用一次。返回 tempera 在此项目上一次失败或未完成的会话后起草的任何澄清问题。
tempera_brief	确定文件集后调用。它会将待处理的追问、推理模板、这些文件最常见的修正类别、本应先询问的触发条件，以及校准警告整合到一条响应中。传入 task_type + domain 可获得更丰富的输出。设置 cross_project=true 可补充其他项目中的记录。
tempera_retrieve	搜索类似的过往事件。设置 scope="cross-project" 可包含其他项目中可迁移的声明。
tempera_template	获取为一对 (task_type, domain) 保存的推理模板，即过往成功案例遵循的步骤序列。

任务期间

工具	使用时机
tempera_log_correction	用户纠正某个假设、决策或代码片段时。会记录分类日志；简要概览会使用该日志。
tempera_log_should_have_asked	任务中途意识到本应事先提出问题时。记录触发情境、问题和最终答案。

任务结束时

工具	使用时机
tempera_capture	将会话保存为一个情节。自动检测会话链接并运行传播。意图提取大模型调用还会为跨项目路由建议一个 ValidityScope。
tempera_feedback	标记检索到的情节是否有帮助。推动效用学习循环。

诊断 + 维护

工具	使用时机
tempera_status	按项目查看记忆健康状况快照。
tempera_stats	统计数据 + 趋势分析（帮助程度随时间的变化、领域增长、学习曲线）。
tempera_propagate	带收敛跟踪的多跳 Bellman 传播。用于定期维护。
tempera_review	整合相似的 BKM，进行清理。相关任务系列结束后运行。

标准预热模式

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

关键生命周期行为

会话开始时：先调用 tempera_session_start 处理任何待处理的反问，然后在确定文件集后调用一次 tempera_brief。

任务结束时：使用 tempera_capture 保存成功的会话——不要等别人要求。若结果为 Failure/Partial 且意图模糊，Capture 还会通过 Haiku 起草一个反问，以便该项目的下一次会话了解其中的缺漏。

会话串联：同一项目中，在 2 小时内捕获的情节会自动关联。多步骤任务会共享效用和上下文。

跨项目路由：新的捕获内容会由意图提取大模型建议一个 ValidityScope（v0.10.3）。项目范围的声明仅限于一个代码库；若检索时选择启用，Language / Crate / Domain / Workaround / Forever 声明则会跨项目呈现。

tempera_retrieve 模式

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")

对话示例

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 or after request logging?"

        📋 REASONING TEMPLATE (bugfix / auth-middleware)
          url-redirect validation
            1. Find every redirect target read from request input
            2. Validate against allow-list or treat as untrusted
            3. Add regression test with adversarial input

        ⚠️  TOP CORRECTION CATEGORIES for these files
          - validation_skipped (3×)
          - host_header_trust (2×)

        Tempera says I've been wrong here before in specific ways.
        Let me ask: should auth run before or after logging?

User: Before — we need an auth'd subject for log lines.

Claude: [Implements with URL allow-list, following the template steps]

        Done. [Calls tempera_capture(
          summary: "Fixed login redirect by validating return URL against allow-list",
          outcome: "success",
          validity_scope: "domain:auth-middleware"
        )]
        ✅ Episode saved. (Cross-project — this is an auth-middleware pattern.)

User: That memory was helpful!

Claude: [Calls tempera_feedback(helpful: true, episodes: ["..."])]
        Marked helpful — future retrievals for similar tasks will rank this higher.

CLI 命令

CLI 与 MCP 工具界面一致，因此你可以在 shell 中驱动 Claude 完成的所有操作。

基础

# Initialize Tempera
tempera init

# Capture an episode (from a session transcript or interactively)
tempera capture --session /path/to/transcript.md

# Index episodes for semantic search (or re-index)
tempera index [--reindex]

# Search memories — project-scoped by default
tempera retrieve "database connection issues"
tempera retrieve "sqlx pattern" --cross-project       # v0.10.1 — pull from other projects

# Provide feedback
tempera feedback helpful --episodes abc123,def456

简要概览界面（v0.9）

# Joint summary of every self-improvement signal for these files
tempera brief --files src/auth.rs,src/router.rs \
              --task-type bugfix --domain auth-middleware

# Include rows from other projects (foreign rows are tagged [from <project>])
tempera brief --files src/store.rs --cross-project

会话预热（v0.8.5）

# Show + clear the pending ask-back for this project (if any)
tempera session-start

# History of system-drafted clarifying questions
tempera ask-backs [--pending] [--project P]

自我改进界面（v0.8）

# Log a correction the user made
tempera log-correction --category "lifetime annotations" \
                       --description "I assumed &str when &'a str was needed" \
                       --correction "use named lifetime to match trait"

# View the correction log
tempera mistakes [--top 5]              # top categories
tempera mistakes --project tempera      # raw list filtered

# Log a question you should have asked up front
tempera log-should-have-asked --trigger "edit auth middleware" \
                              --question "Which auth provider is wired up?" \
                              --answer "No auth — internal-only service."

# View the should-have-asked log
tempera asks --top 5

推理模板（v0.8.3）

# List stored templates
tempera templates list

# Fetch a specific template
tempera templates get --task-type bugfix --domain async-rust

# Manually trigger extraction (otherwise runs in dream cycle)
tempera templates extract --max-usd 0.20

校准（v0.8.1）

# Per-(task_type, project) verified vs declared rates
tempera calibration --project tempera --task-type bugfix

梦境循环（v0.7）

# Run the full cycle with a budget cap (default $0.50)
tempera dream --max-usd 0.50

# Run one phase, or list available phases
tempera dream --phase reflect
tempera dream --list

# Plan only — show what would happen without making LLM calls
tempera dream --dry-run

# Author yesterday's reflection (Haiku triage + Sonnet authorship if score >= 0.5)
tempera reflect [--date 2026-05-26] [--dry-run]

# Surface active factual contradictions found during dream
tempera contradict --list

验证（v0.6.1）

# Move an episode forward in the verification chain
tempera advance-verification --episode abc123 --to tests_pass --run-id <id>
tempera advance-verification --episode abc123 --to merged --commit <sha>
tempera advance-verification --episode abc123 --to stable_no_revert --days 30

维护 + 分析

# Multi-hop Bellman propagation (run weekly)
tempera propagate --temporal

# Prune old / low-value episodes
tempera prune --older-than 90 --min-utility 0.2 --execute

# Stats + trends
tempera stats
tempera trends --project tempera --bucket weekly

# Health check + remediation
tempera doctor [--remediate --yes --target-score 90]

# Eval harness (P@5, R@5, MRR, nDCG@5 against a fixture)
tempera eval run --fixture evals/fixtures/real.jsonl --mode hybrid

# Snapshot / restore the data dir
tempera backup
tempera backup --list
tempera backup --restore 20260524T123456Z

数据存储

Tempera 将所有内容本地存储在 ~/.tempera/ 中（所有项目共享）。所有项目共用一个记忆池；项目筛选在查询时应用。

~/.tempera/
├── config.toml              # Configuration (all RL params configurable)
├── episodes/                # Canonical episode JSON
│   └── 2026-01-25/
│       └── <id>.json
├── jobs.sqlite              # SQLite for everything indexable (see below)
├── vectors/                 # Vector index (vectrust embeddings)
├── models/                  # BGE-Small embedding model (~128MB)
├── reflections/             # Daily reflection markdown (v0.7.3)
├── patterns/                # Cross-day pattern pages (v0.7.4)
└── templates/               # Reasoning templates (v0.8.3)

SQLite 表（位于 jobs.sqlite 中）

所有需要 SQL 的内容都存储在这里。每个存储在首次使用时打开数据库并运行迁移；迁移文件位于 migrations/ 中，并按顺序运行。

迁移	表	用途
0001	jobs	采用租约语义的后台作业队列
0002	error_fingerprints	经过 blake3 哈希处理的规范化错误文本
0003	dream_verdicts	按天划分的 Haiku 分类缓存
0004	reflections	每日反思记录
0005	patterns	跨日主题聚类
0006	contradictions	情节对之间的分歧 + Wilson CI
0007	calibration_buckets	（task_type, project）声明与验证计数
0008	mistakes	锚定式纠正日志
0009	reasoning_templates	提取出的推理步骤序列
0010	should_have_asked	Agent 本应事先提出的问题
0011	ask_backs	系统为下一次会话起草的澄清问题

所有项目共用同一个记忆池。跨项目路由由每个情节的 ValidityScope 控制（见下文），而不是通过分开存储实现。

配置

所有配置项都位于 ~/.tempera/config.toml。默认值经过调整，开箱即用；只有在想更改检索排序、梦境周期行为或各阶段预算时，才需要修改此文件。

检索 + 排序

[retrieval]
mode = "hybrid"                  # vector | keyword | hybrid (BM25 + vector fusion)
similarity_weight = 0.3          # Weight for semantic similarity (project mode)
utility_weight = 0.7             # Weight for learned utility (project mode)
hybrid_similarity_weight = 0.85  # RRF-normalized retrieval (hybrid mode)
hybrid_utility_weight = 0.15
recency_weight = 0.0             # Recency (0 = off, opt-in)
recency_halflife_days = 30.0
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
propagation_threshold = 0.5      # Min similarity for propagation
max_propagation_depth = 2        # Multi-hop depth (hops)
temporal_credit_window_hours = 1

捕获 + 验证

[capture]
auto_capture = true
extract_intent_llm = true        # Use LLM to extract intent + claim + scope
capture_diffs = true
ask_back_on_failure = true       # Draft a clarifying question on Failure/Partial captures (v0.8.5)

梦境周期（v0.7）

[dream]
default_max_usd = 0.50           # Per-cycle budget cap
stable_threshold_days = 30       # Days before Merged → StableNoRevert
triage_model = "claude-haiku-4-5-20251001"
reflect_model = "claude-sonnet-4-6"

# Patterns phase
patterns_lookback_days = 30
patterns_min_evidence = 3
patterns_cluster_threshold = 0.75

# Contradict phase
contradict_top_n = 50
contradict_min_similarity = 0.6
contradict_max_similarity = 0.95
contradict_max_pairs = 30
contradict_min_confidence = 0.7

# Templates phase (v0.8.3)
templates_min_evidence = 3
templates_min_verification_weight = 0.30  # 0.30 = Untested (lenient); 0.60 = Merged

存储 + 维护

[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
stale_age_days = 30
stale_utility_threshold = 0.2

衰减速率会根据范围调整（依据每个片段声明上的 ValidityScope）：

范围	每日衰减	半衰期
Forever	0.000	∞
Language { name }	0.001	~3 年
Domain { tag }	0.005	~140 天
Project { name }	0.010	~70 天
Crate { name, version }	0.020	~35 天
Workaround { ref, expires }	0.050	~14 天
（未设置范围，旧版）	0.010	~70 天

底层机制

多跳 Bellman 传播

有用片段的价值会沿相似度图进行多跳传播：

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

会话链式关联

同一项目中，彼此间隔不超过 2 小时捕获的片段会自动关联：

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

梦境周期（v0.7）

一个设定了预算的后台流水线，每晚运行（或按需运行）。每个阶段共用一个 CostBudget；免费阶段会忽略它，付费阶段则会在每次调用大模型前检查 try_spend()。

verify_advance  →  decay  →  reflect  →  patterns  →  contradict  →  templates
   (free)         (free)   (Sonnet)    (Sonnet)    (Haiku)        (Sonnet)
                          ↓             ↓            ↓             ↓
                  reflections/  patterns/   contradictions  templates/

• verify_advance：经过 stable_threshold_days 后，将片段从 Merged 推进到 StableNoRevert。
• decay：根据范围调整效用衰减（见上表）。
• reflect：Haiku 负责分流，由 Sonnet 负责撰写；高信号日会生成一页反思记录。
• patterns：对反思记录的嵌入向量进行凝聚聚类 → 提取跨日主题。
• contradict：将频繁检索到的 BKM 片段配对，询问 Haiku 它们是否在事实声明上存在分歧；并给出矛盾率的 Wilson 95% CI。
• templates：按 (task_type, domain) 对成功且已验证的片段分组，通过 Sonnet 提取可复用的步骤序列。

完整周期的最坏情况下成本约为 $0.50（使用默认设置）。

评分公式

检索排序结合三种信号，并使用归一化权重：

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

混合模式下的默认值：85% 相似度（对向量 + BM25 使用 RRF 归一化）、15% 效用、0% 新近度。每个片段的 VerificationState 会乘入显著性权重——验证充分的成功片段权重更高。

跨项目路由（v0.10）

每条声明都带有一个 ValidityScope，用于确定：

• 衰减速率（见上表）。
• 可迁移性：对于 Project { name } 以外的所有情况，is_transferable() 均返回 true。Agent 启用 cross_project=true 时，retrieve 和 brief 接口会利用此属性决定显示哪些内容。

在 v0.6.4 之前捕获的旧版片段没有设置范围，因此默认仍限定于项目。新捕获的内容（v0.10.3+）会通过意图提取大模型调用自动获得建议范围，使用冒号编码格式，例如 language:rust、crate:[email protected]、domain:async-rust、workaround:repo#123 或 project。无法确定时默认使用 project，以保持系统的保守性。

维护

定期运行以下命令，保持记忆健康：

# Nightly: dream cycle (verify_advance + decay + reflect + patterns + contradict + templates)
tempera dream --max-usd 0.50

# Weekly: Propagate utility values (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")

# As needed: health check + auto-remediate
tempera doctor --remediate --yes

梦境周期是长期记忆卫生维护的关键环节。它使用 Haiku 进行低成本分流，并使用 Sonnet 撰写——默认的 $0.50 上限是所有阶段合计的最坏情况成本。

环境变量

变量	描述
ANTHROPIC_API_KEY	用于基于大模型的意图提取（--extract-intent）
TEMPERA_DATA_DIR	覆盖默认数据目录
FASTEMBED_CACHE_DIR	覆盖嵌入模型缓存位置

故障排除

MCP 服务未加载

1. 检查路径：ls /path/to/tempera-mcp
2. 检查配置：cat ~/.claude.json
3. 完全重启 Claude Code
4. 运行 /mcp 进行验证

首次运行时嵌入处理速度较慢

首次使用时，会从 HuggingFace 下载 BGE-Small 模型（约 128MB）。这需要互联网连接。下载后，模型会缓存在 ~/.tempera/models/，并可离线使用。

向量搜索没有找到任何内容

运行 tempera index 以创建或更新向量数据库。

模型下载失败

如果处于防火墙或代理之后，请确保可以访问 huggingface.co。模型文件通过 HTTPS 下载。

tempera_brief 返回“nothing to surface”

在使用初期，这属于正常现象——简报会关联随时间累积的信号数据（错误、请求、模板、校准）。具体来说：

• 只有当你传入的文件与之前记录的行有重合时，错误／本应询问的部分才会显示。
• 只有当至少 3 个成功且已验证的情节共享 (task_type, domain) 组合时，模板部分才会显示（模板会在梦境周期中累积）。
• 只有当该分组中至少有 5 条声明成功的捕获记录时，校准警告才会显示。

可改用 tempera_retrieve 按情节级别进行回忆。

tempera retrieve --cross-project 没有找到任何内容

在 v0.6.4 之前捕获的情节没有设置 ValidityScope，而 v0.10 的跨项目筛选器会将未指定范围的声明视为限定于项目（保守的默认设置）。你可以：(a) 使用 v0.10.3+ 捕获新情节，系统会自动建议一个范围；或 (b) 在捕获时通过 MCP validity_scope 参数手动为旧情节分类。

许可证

Apache 2.0

贡献

欢迎贡献！请提交 issue 或 PR。