{
  "markdown": "# Tempera - Persistent Memory for Claude Code\n\nTempera 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.\n\n## Why Tempera?\n\n**The Problem**: Claude Code forgets everything between sessions. You solve the same problems repeatedly, and Claude can't learn from past successes or failures.\n\n**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.\n\n```\nWithout Tempera:                    With Tempera:\n┌─────────────┐                  ┌─────────────┐\n│  Session 1  │ ──forgotten──>   │  Session 1  │ ──captured──┐\n└─────────────┘                  └─────────────┘             │\n┌─────────────┐                  ┌─────────────┐             ▼\n│  Session 2  │ ──forgotten──>   │  Session 2  │ ◄──recalls──┤\n└─────────────┘                  └─────────────┘             │\n┌─────────────┐                  ┌─────────────┐             │\n│  Session 3  │ ──forgotten──>   │  Session 3  │ ◄──recalls──┘\n└─────────────┘                  └─────────────┘\n     │                                 │\n     ▼                                 ▼\n  No learning                    Continuous improvement\n```\n\n## How It Works\n\n### The Learning Loop\n\n```\n┌────────────────────────────────────────────────────────────────┐\n│  1. START TASK                                                 │\n│     User: \"Fix the login redirect bug\"                         │\n└────────────────────────────────────────────────────────────────┘\n                              │\n                              ▼\n┌────────────────────────────────────────────────────────────────┐\n│  2. RETRIEVE MEMORIES                                          │\n│     Claude searches: \"login redirect bug\"                      │\n│     Finds: \"Fixed similar issue by sanitizing return URLs\"     │\n│     + Session context: related episodes from the same task     │\n└────────────────────────────────────────────────────────────────┘\n                              │\n                              ▼\n┌────────────────────────────────────────────────────────────────┐\n│  3. SOLVE FASTER                                               │\n│     Claude uses past experience to solve the problem           │\n└────────────────────────────────────────────────────────────────┘\n                              │\n                              ▼\n┌────────────────────────────────────────────────────────────────┐\n│  4. CAPTURE SESSION                                            │\n│     Claude saves: what was done, what worked, what failed      │\n│     Auto-links to current session for multi-step tasks         │\n└────────────────────────────────────────────────────────────────┘\n                              │\n                              ▼\n┌────────────────────────────────────────────────────────────────┐\n│  5. LEARN FROM FEEDBACK                                        │\n│     User: \"That memory was helpful!\"                           │\n│     → Episode utility increases                                │\n│     → Multi-hop Bellman propagation spreads value               │\n│     → Session-linked episodes get boosted                      │\n│     → Unhelpful memories fade over time                        │\n└────────────────────────────────────────────────────────────────┘\n```\n\n### What Makes It \"Learn\"\n\n| Mechanism | What It Does |\n|-----------|--------------|\n| **Feedback** | Helpful episodes gain utility score |\n| **Multi-hop Bellman Propagation** | Value spreads through the similarity graph across multiple hops |\n| **Session Chaining** | Related episodes in multi-step tasks are linked and boost each other |\n| **Temporal Credit** | Episodes before successes get credit (even across session boundaries) |\n| **Recency Boost** | Fresh episodes can be weighted higher in retrieval (opt-in) |\n| **Scope-aware Decay** | Project-bound claims fade in ~70 days; language-level facts last ~3 years; universal truths never decay |\n| **Verification State** | Captures advance from `Untested` → `TestsPass` → `Merged` → `StableNoRevert`; later states weigh more |\n| **Calibration** | Per-(task, project) verified vs. declared ratio surfaces overconfidence |\n| **Dream Cycle** | Nightly reflection, pattern detection, contradiction probing, and template extraction |\n| **Self-Improvement Log** | Tracks corrections, missed questions, and queues clarifying questions for next session |\n| **Cross-Project Transfer** | Claims marked language / crate / domain / forever-scoped surface across projects |\n\nOver 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.\n\n### The bigger surfaces (v0.6 onward)\n\nBeyond 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.\n\n- **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.\n- **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.\n- **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.\n- **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.\n- **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.\n\n## Installation\n\n### Build from Source\n\n```bash\n# Clone and build\ngit clone https://github.com/anvanster/tempera.git\ncd tempera\ncargo build --release\n\n# Two binaries are created:\n# - target/release/tempera      (CLI tool)\n# - target/release/tempera-mcp  (MCP server for Claude Code)\n```\n\n### Install from crates.io\n\n```bash\ncargo install tempera\n```\n\n### First Run - Model Download\n\nOn first use, Tempera downloads the BGE-Small embedding model (~128MB) for semantic search. This happens automatically and only once:\n\n```bash\n# Initialize and trigger model download\ntempera init\n\n# Output:\n# 🔄 Loading embedding model (this may download the model on first run)...\n# ✅ Embedding model loaded\n```\n\nThe model is cached globally at `~/.tempera/models/` and shared across all projects.\n\n## Setup with Claude Code\n\n### 1. Add the MCP Server\n\n```bash\nclaude mcp add tempera --scope user -- /path/to/Tempera/target/release/tempera-mcp\n```\n\nThe `--scope user` flag makes it available across all your projects.\n\n### 2. Restart Claude Code\n\nExit and restart Claude Code to load the new MCP server.\n\n### 3. Verify\n\nRun `/mcp` in Claude Code. You should see `tempera` with 12 tools.\n\n## MCP Tools\n\nOnce connected, Claude has access to these 12 tools, grouped by purpose:\n\n### Session warmup (call at task start)\n\n| Tool | When to Use |\n|------|-------------|\n| `tempera_session_start` | Call ONCE at the very start. Returns any clarifying question tempera drafted after a previous failed/partial session in this project. |\n| `tempera_brief` | Call once the file set is known. Joins pending ask-back, reasoning template, top correction categories for these files, should-have-asked triggers, and calibration warning into one response. Pass `task_type` + `domain` for richer output. Set `cross_project=true` to supplement with rows from other projects. |\n| `tempera_retrieve` | Search for similar past episodes. Set `scope=\"cross-project\"` to include transferable claims from other projects. |\n| `tempera_template` | Pull the reasoning template stored for a `(task_type, domain)` pair. The step sequence past wins followed. |\n\n### During task\n\n| Tool | When to Use |\n|------|-------------|\n| `tempera_log_correction` | When the user corrects an assumption / decision / piece of code. Categorized log; the brief surface uses it. |\n| `tempera_log_should_have_asked` | When you realize mid-task you should have asked a question up front. Records the trigger context, the question, and the eventual answer. |\n\n### End of task\n\n| Tool | When to Use |\n|------|-------------|\n| `tempera_capture` | Save session as an episode. Auto-detects session links and runs propagation. The intent-extraction LLM call also suggests a `ValidityScope` for cross-project routing. |\n| `tempera_feedback` | Mark retrieved episodes as helpful or not. Drives the utility-learning loop. |\n\n### Diagnostics + maintenance\n\n| Tool | When to Use |\n|------|-------------|\n| `tempera_status` | Per-project memory health snapshot. |\n| `tempera_stats` | Statistics + trend analytics (helpfulness over time, domain growth, learning curve). |\n| `tempera_propagate` | Multi-hop Bellman propagation with convergence tracking. Periodic maintenance. |\n| `tempera_review` | Consolidate similar BKMs, cleanup. Run after related task series. |\n\n### Standard warmup pattern\n\n```\ntempera_session_start          # is anything queued from last session?\ntempera_brief(files, ...)      # what does tempera know about this exact change?\ntempera_retrieve(query)        # then deep-dive into specific episodes\n```\n\n### Key Lifecycle Behaviors\n\n**Start of session**: Call `tempera_session_start` first to consume any pending ask-back, then `tempera_brief` once the file set is known.\n\n**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.\n\n**Session chaining**: Episodes captured within 2 hours of each other in the same project are automatically linked. Multi-step tasks share utility and context.\n\n**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.\n\n### tempera_retrieve Modes\n\n```\nSearch:           tempera_retrieve(query: \"authentication bug\")\nList all:         tempera_retrieve(all: true)\nShow details:     tempera_retrieve(query: \"abc12345\")        # episode ID\nCross-project:    tempera_retrieve(query: \"sqlx ordering\", scope: \"cross-project\")\n```\n\n## Example Conversation\n\n```\nUser: Fix the login redirect vulnerability\n\nClaude: [Calls tempera_session_start()]\n        No pending ask-back — proceeding.\n\n        [Calls tempera_brief(files: [\"src/auth.rs\", \"src/router.rs\"],\n                             task_type: \"bugfix\", domain: \"auth-middleware\")]\n\n        🔴 PENDING ASK-BACK\n          Ask the user first: \"Should auth run before or after request logging?\"\n\n        📋 REASONING TEMPLATE (bugfix / auth-middleware)\n          url-redirect validation\n            1. Find every redirect target read from request input\n            2. Validate against allow-list or treat as untrusted\n            3. Add regression test with adversarial input\n\n        ⚠️  TOP CORRECTION CATEGORIES for these files\n          - validation_skipped (3×)\n          - host_header_trust (2×)\n\n        Tempera says I've been wrong here before in specific ways.\n        Let me ask: should auth run before or after logging?\n\nUser: Before — we need an auth'd subject for log lines.\n\nClaude: [Implements with URL allow-list, following the template steps]\n\n        Done. [Calls tempera_capture(\n          summary: \"Fixed login redirect by validating return URL against allow-list\",\n          outcome: \"success\",\n          validity_scope: \"domain:auth-middleware\"\n        )]\n        ✅ Episode saved. (Cross-project — this is an auth-middleware pattern.)\n\nUser: That memory was helpful!\n\nClaude: [Calls tempera_feedback(helpful: true, episodes: [\"...\"])]\n        Marked helpful — future retrievals for similar tasks will rank this higher.\n```\n\n## CLI Commands\n\nThe CLI mirrors the MCP tool surface so you can drive everything Claude does from a shell.\n\n### Basics\n\n```bash\n# Initialize Tempera\ntempera init\n\n# Capture an episode (from a session transcript or interactively)\ntempera capture --session /path/to/transcript.md\n\n# Index episodes for semantic search (or re-index)\ntempera index [--reindex]\n\n# Search memories — project-scoped by default\ntempera retrieve \"database connection issues\"\ntempera retrieve \"sqlx pattern\" --cross-project       # v0.10.1 — pull from other projects\n\n# Provide feedback\ntempera feedback helpful --episodes abc123,def456\n```\n\n### The brief surface (v0.9)\n\n```bash\n# Joint summary of every self-improvement signal for these files\ntempera brief --files src/auth.rs,src/router.rs \\\n              --task-type bugfix --domain auth-middleware\n\n# Include rows from other projects (foreign rows are tagged [from <project>])\ntempera brief --files src/store.rs --cross-project\n```\n\n### Session warmup (v0.8.5)\n\n```bash\n# Show + clear the pending ask-back for this project (if any)\ntempera session-start\n\n# History of system-drafted clarifying questions\ntempera ask-backs [--pending] [--project P]\n```\n\n### Self-improvement surfaces (v0.8)\n\n```bash\n# Log a correction the user made\ntempera log-correction --category \"lifetime annotations\" \\\n                       --description \"I assumed &str when &'a str was needed\" \\\n                       --correction \"use named lifetime to match trait\"\n\n# View the correction log\ntempera mistakes [--top 5]              # top categories\ntempera mistakes --project tempera      # raw list filtered\n\n# Log a question you should have asked up front\ntempera log-should-have-asked --trigger \"edit auth middleware\" \\\n                              --question \"Which auth provider is wired up?\" \\\n                              --answer \"No auth — internal-only service.\"\n\n# View the should-have-asked log\ntempera asks --top 5\n```\n\n### Reasoning templates (v0.8.3)\n\n```bash\n# List stored templates\ntempera templates list\n\n# Fetch a specific template\ntempera templates get --task-type bugfix --domain async-rust\n\n# Manually trigger extraction (otherwise runs in dream cycle)\ntempera templates extract --max-usd 0.20\n```\n\n### Calibration (v0.8.1)\n\n```bash\n# Per-(task_type, project) verified vs declared rates\ntempera calibration --project tempera --task-type bugfix\n```\n\n### Dream cycle (v0.7)\n\n```bash\n# Run the full cycle with a budget cap (default $0.50)\ntempera dream --max-usd 0.50\n\n# Run one phase, or list available phases\ntempera dream --phase reflect\ntempera dream --list\n\n# Plan only — show what would happen without making LLM calls\ntempera dream --dry-run\n\n# Author yesterday's reflection (Haiku triage + Sonnet authorship if score >= 0.5)\ntempera reflect [--date 2026-05-26] [--dry-run]\n\n# Surface active factual contradictions found during dream\ntempera contradict --list\n```\n\n### Verification (v0.6.1)\n\n```bash\n# Move an episode forward in the verification chain\ntempera advance-verification --episode abc123 --to tests_pass --run-id <id>\ntempera advance-verification --episode abc123 --to merged --commit <sha>\ntempera advance-verification --episode abc123 --to stable_no_revert --days 30\n```\n\n### Maintenance + analytics\n\n```bash\n# Multi-hop Bellman propagation (run weekly)\ntempera propagate --temporal\n\n# Prune old / low-value episodes\ntempera prune --older-than 90 --min-utility 0.2 --execute\n\n# Stats + trends\ntempera stats\ntempera trends --project tempera --bucket weekly\n\n# Health check + remediation\ntempera doctor [--remediate --yes --target-score 90]\n\n# Eval harness (P@5, R@5, MRR, nDCG@5 against a fixture)\ntempera eval run --fixture evals/fixtures/real.jsonl --mode hybrid\n\n# Snapshot / restore the data dir\ntempera backup\ntempera backup --list\ntempera backup --restore 20260524T123456Z\n```\n\n## Data Storage\n\nTempera stores everything locally in `~/.tempera/` (shared across all projects). One memory pool serves every project; the project filter is applied at query time.\n\n```\n~/.tempera/\n├── config.toml              # Configuration (all RL params configurable)\n├── episodes/                # Canonical episode JSON\n│   └── 2026-01-25/\n│       └── <id>.json\n├── jobs.sqlite              # SQLite for everything indexable (see below)\n├── vectors/                 # Vector index (vectrust embeddings)\n├── models/                  # BGE-Small embedding model (~128MB)\n├── reflections/             # Daily reflection markdown (v0.7.3)\n├── patterns/                # Cross-day pattern pages (v0.7.4)\n└── templates/               # Reasoning templates (v0.8.3)\n```\n\n### SQLite tables (in `jobs.sqlite`)\n\nEverything that needs SQL lives here. Each store opens the DB on first use and runs its migration; migrations are in `migrations/` and run in order.\n\n| Migration | Table | Purpose |\n|-----------|-------|---------|\n| 0001 | `jobs` | Background job queue with lease semantics |\n| 0002 | `error_fingerprints` | blake3-hashed normalized error text |\n| 0003 | `dream_verdicts` | Day-level Haiku triage cache |\n| 0004 | `reflections` | Daily reflection records |\n| 0005 | `patterns` | Cross-day theme clusters |\n| 0006 | `contradictions` | Episode-pair disagreements + Wilson CI |\n| 0007 | `calibration_buckets` | (task_type, project) declared vs verified counts |\n| 0008 | `mistakes` | Anchored correction log |\n| 0009 | `reasoning_templates` | Extracted reasoning step sequences |\n| 0010 | `should_have_asked` | Questions the agent should have asked up front |\n| 0011 | `ask_backs` | System-drafted clarifying questions for next session |\n\nAll projects share the same pool. Cross-project routing is controlled by each episode's `ValidityScope` (see below) — not by separate storage.\n\n## Configuration\n\nAll knobs live in `~/.tempera/config.toml`. The defaults are tuned to be useful out of the box; you only need to touch this if you want to change retrieval ranking, dream-cycle behavior, or per-phase budgets.\n\n### Retrieval + ranking\n\n```toml\n[retrieval]\nmode = \"hybrid\"                  # vector | keyword | hybrid (BM25 + vector fusion)\nsimilarity_weight = 0.3          # Weight for semantic similarity (project mode)\nutility_weight = 0.7             # Weight for learned utility (project mode)\nhybrid_similarity_weight = 0.85  # RRF-normalized retrieval (hybrid mode)\nhybrid_utility_weight = 0.15\nrecency_weight = 0.0             # Recency (0 = off, opt-in)\nrecency_halflife_days = 30.0\nmmr_lambda = 0.7                 # MMR diversity (0=diverse, 1=relevant)\nmin_similarity = 0.5             # Filter threshold\n\n[bellman]\ngamma = 0.9                      # Discount factor for Bellman updates\nalpha = 0.1                      # Learning rate\npropagation_threshold = 0.5      # Min similarity for propagation\nmax_propagation_depth = 2        # Multi-hop depth (hops)\ntemporal_credit_window_hours = 1\n```\n\n### Capture + verification\n\n```toml\n[capture]\nauto_capture = true\nextract_intent_llm = true        # Use LLM to extract intent + claim + scope\ncapture_diffs = true\nask_back_on_failure = true       # Draft a clarifying question on Failure/Partial captures (v0.8.5)\n```\n\n### Dream cycle (v0.7)\n\n```toml\n[dream]\ndefault_max_usd = 0.50           # Per-cycle budget cap\nstable_threshold_days = 30       # Days before Merged → StableNoRevert\ntriage_model = \"claude-haiku-4-5-20251001\"\nreflect_model = \"claude-sonnet-4-6\"\n\n# Patterns phase\npatterns_lookback_days = 30\npatterns_min_evidence = 3\npatterns_cluster_threshold = 0.75\n\n# Contradict phase\ncontradict_top_n = 50\ncontradict_min_similarity = 0.6\ncontradict_max_similarity = 0.95\ncontradict_max_pairs = 30\ncontradict_min_confidence = 0.7\n\n# Templates phase (v0.8.3)\ntemplates_min_evidence = 3\ntemplates_min_verification_weight = 0.30  # 0.30 = Untested (lenient); 0.60 = Merged\n```\n\n### Storage + maintenance\n\n```toml\n[storage]\nmax_age_days = 180               # Max episode age for pruning\nmin_utility_threshold = 0.05     # Min utility to keep\nmin_retrievals = 2               # Min retrievals before pruning allowed\nconsolidation_threshold = 0.85   # BKM merge threshold\ncluster_threshold = 0.85\nstale_age_days = 30\nstale_utility_threshold = 0.2\n```\n\nDecay rates are **scope-aware** (per the `ValidityScope` on each episode's claim):\n\n| Scope | Decay/day | Half-life |\n|-------|-----------|-----------|\n| `Forever` | 0.000 | ∞ |\n| `Language { name }` | 0.001 | ~3 years |\n| `Domain { tag }` | 0.005 | ~140 days |\n| `Project { name }` | 0.010 | ~70 days |\n| `Crate { name, version }` | 0.020 | ~35 days |\n| `Workaround { ref, expires }` | 0.050 | ~14 days |\n| (no scope set, legacy) | 0.010 | ~70 days |\n\n## Under the Hood\n\n### Multi-hop Bellman Propagation\n\nValue from helpful episodes spreads through the similarity graph in multiple hops:\n\n```\nHop 0: Source episodes (high helpfulness, ≥2 retrievals)\n  │\n  ▼  γ¹ discount\nHop 1: Similar episodes updated\n  │\n  ▼  γ² discount\nHop 2: Episodes similar to hop-1 updated\n  │\n  ▼  Converges when no updates occur\n```\n\n### Session Chaining\n\nEpisodes captured within 2 hours of each other in the same project are automatically linked:\n\n```\nSession abc123:\n  ├── Episode 1: \"Investigated auth bug\" (debug)\n  ├── Episode 2: \"Found root cause in token validation\" (research)\n  └── Episode 3: \"Fixed token expiry check\" (bugfix, success)\n       ↓\n  Temporal credit flows back to episodes 1 & 2\n  Session-linked propagation boosts all 3\n```\n\n### The Dream Cycle (v0.7)\n\nA budgeted background pipeline that runs nightly (or on demand). Each phase shares a `CostBudget`; free phases ignore it, paid phases check `try_spend()` before each LLM call.\n\n```\nverify_advance  →  decay  →  reflect  →  patterns  →  contradict  →  templates\n   (free)         (free)   (Sonnet)    (Sonnet)    (Haiku)        (Sonnet)\n                          ↓             ↓            ↓             ↓\n                  reflections/  patterns/   contradictions  templates/\n```\n\n- **verify_advance**: bumps episodes from `Merged` to `StableNoRevert` after `stable_threshold_days`.\n- **decay**: scope-aware utility decay (see table above).\n- **reflect**: Haiku triage gates Sonnet authorship; high-signal days get a reflection page.\n- **patterns**: agglomerative clustering on reflection embeddings → cross-day themes.\n- **contradict**: pairs frequently-retrieved BKM episodes and asks Haiku whether they disagree on a factual claim; surfaces a Wilson 95% CI on the contradiction rate.\n- **templates**: groups successful verified episodes by `(task_type, domain)`, extracts reusable step sequences via Sonnet.\n\nWorst case per full cycle: roughly $0.50 with default settings.\n\n### Scoring Formula\n\nRetrieval ranking combines three signals with normalized weights:\n\n```\nscore = (sim_w × similarity + util_w × utility + rec_w × recency) / (sim_w + util_w + rec_w)\n```\n\nDefault in hybrid mode: 85% similarity (RRF-normalized over vector + BM25), 15% utility, 0% recency. The `VerificationState` of each episode multiplies into salience — well-verified successes weigh more.\n\n### Cross-project routing (v0.10)\n\nEvery claim carries a `ValidityScope` that determines:\n\n- **Decay rate** (table above).\n- **Transferability**: `is_transferable()` returns true for everything except `Project { name }`. The retrieve and brief surfaces use this to decide what surfaces when the agent opts into `cross_project=true`.\n\nLegacy episodes captured before v0.6.4 don't have a scope set, so they stay project-bound by default. New captures (v0.10.3+) get a scope suggested automatically by the intent-extraction LLM call — using a colon-encoded format like `language:rust`, `crate:sqlx@0.8`, `domain:async-rust`, `workaround:repo#123`, or `project`. The default when in doubt is `project`, keeping the system conservative.\n\n## Maintenance\n\nRun periodically to keep memory healthy:\n\n```bash\n# Nightly: dream cycle (verify_advance + decay + reflect + patterns + contradict + templates)\ntempera dream --max-usd 0.50\n\n# Weekly: Propagate utility values (multi-hop with convergence)\ntempera propagate --temporal\n\n# Monthly: Clean up old/useless episodes\ntempera prune --older-than 90 --min-utility 0.2 --execute\n\n# As needed: Check trends\ntempera trends\n\n# As needed: Review and consolidate\n# (via MCP) tempera_review(action: \"consolidate\")\n\n# As needed: health check + auto-remediate\ntempera doctor --remediate --yes\n```\n\nThe dream cycle is the load-bearing piece for long-running memory hygiene. It uses Haiku for cheap gating and Sonnet for authorship — the default $0.50 cap is the worst case across every phase.\n\n## Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `ANTHROPIC_API_KEY` | For LLM-based intent extraction (`--extract-intent`) |\n| `TEMPERA_DATA_DIR` | Override default data directory |\n| `FASTEMBED_CACHE_DIR` | Override embedding model cache location |\n\n## Troubleshooting\n\n### MCP server not loading\n1. Check path: `ls /path/to/tempera-mcp`\n2. Check config: `cat ~/.claude.json`\n3. Restart Claude Code completely\n4. Run `/mcp` to verify\n\n### Embeddings slow on first run\nThe 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.\n\n### Vector search not finding anything\nRun `tempera index` to create/update the vector database.\n\n### Model download fails\nIf behind a firewall or proxy, ensure access to `huggingface.co`. The model files are downloaded via HTTPS.\n\n### `tempera_brief` returns \"nothing to surface\"\nThis is normal early on — the brief joins against signal data (mistakes, asks, templates, calibration) that accrues over time. Specifically:\n- The mistakes / should-have-asked sections only fire when the **files** you pass overlap with previously-logged rows.\n- The template section only fires when at least 3 successful verified episodes share the `(task_type, domain)` pair (templates accrue during the dream cycle).\n- The calibration warning needs ≥5 declared-success captures in the bucket before it surfaces.\n\nFall back to `tempera_retrieve` for episode-level recall.\n\n### `tempera retrieve --cross-project` finds nothing\nEpisodes captured before v0.6.4 don't have a `ValidityScope` set, and v0.10's cross-project filter treats unscoped claims as project-bound (conservative default). Either (a) capture new episodes with v0.10.3+, which auto-suggests a scope, or (b) manually classify legacy episodes via the MCP `validity_scope` parameter on capture.\n\n## License\n\nApache 2.0\n\n## Contributing\n\nContributions welcome! Please open an issue or PR.\n",
  "bytes": 27690,
  "sha": "b3cd0d32633ce206a610576a14df6b742a812ab40d479ef5f6350785f76da025",
  "repo_slug": "anvanster/tempera",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_anvanster_tempera_f9ab0f79/readme"
}