---
name: using-total-recall
description: Initialize total-recall memory system and ensure session_start has been called. Use at session start or when memory features aren't working.
---

# Using total-recall

This skill ensures the total-recall memory system is active for this session.

## Immediate Action

1. Call the total-recall `session_start` MCP tool now (if it already ran server-side, it returns cached results instantly)
2. **If `session_start` is blocked by permissions** (e.g., in TUI fullscreen / `dontAsk` mode):
   - Tell the user: "total-recall session_start was blocked by permissions. The memory system needs `mcp__plugin_total-recall_total-recall__session_start` allowed to function. You may need to adjust permissions if you want total-recall active this session."
   - Suggest running `/total-recall:commands setup` to auto-configure permissions for future sessions
   - Proceed without memory features — this is degraded mode, not fatal
3. **Announce startup** using the returned data:
   - Report tier summary: pinned, hot, warm, cold, KB counts from `tierSummary`
   - Report storage backend from `storage` (e.g. "sqlite", "cortex", "postgres"). If it shows a fallback like "sqlite (cortex failed)", flag this prominently.
   - If `lastSessionAge` is present, mention when the last session was
   - If `hints` are present, briefly surface the most relevant ones
   - If `pinned_budget_pressure` is present in `hints`, surface it prominently: pinned entries are eating over half the context budget — suggest unpinning or trimming entries
   - If `backgroundTasks.reindex` shows `state: "running"`, tell the user a one-time embedding re-index is in progress (`done`/`total`): **local semantic retrieval is degraded until it completes**. It runs in the background and the server is fully usable meanwhile — re-check via the `status` tool or the next `session_start`. (This is normal after an embedding-model change or upgrade; it is not an error.)
   - If `backgroundTasks.setup` is present (`event: "provisioned"`), briefly note that first-run setup finished (the memory engine was downloaded) — a one-time message
   - Keep it to 2-3 lines max
4. Use `hints` to inform your behavior throughout the session
5. Incorporate the returned context to inform your responses

## Ongoing Behaviors

Once initialized, follow these behaviors throughout the session. Tool calls will be visible to the user.

### Handling model bootstrap errors

When `session_start` returns an error response containing `"error": "model_not_ready"`, parse the JSON payload and follow the recovery flow based on `reason`:

| reason | What it means | What to do |
|---|---|---|
| `downloading` | First-run bootstrap is in progress (loading/validating the ~133 MB bundled ONNX model). Another process or this one holds the lock. | Wait 5–10 seconds and call `session_start` again. Repeat up to 12 times (~2 minutes total). Surface a brief status to the user on the first retry: "Total-recall is preparing its embedding model on first run. This is a one-time setup." |
| `missing` | Bundled model not found on disk. The runtime does not download it — it must be present in the artifact (fetched + sha256-verified at build via `scripts/fetch-bge-small.sh`). | Surface the `hint` field to the user verbatim (it contains manual install instructions) and proceed without memory features for this session. |
| `corrupted` | Model file present but failed checksum (e.g., partial install or a bad bundled file). | Call `session_start` once more in case it was a transient read. If it fails again with the same reason, surface the `hint` field to the user verbatim (it contains manual install instructions) and proceed without memory. |
| `failed` | Other unrecoverable error preparing the model. | Surface the `hint` field verbatim to the user (manual install commands) and proceed without memory features for this session. Do NOT keep retrying — that will only delay the user. |

After successful recovery, all subsequent total-recall behaviors (capture, retrieve, session end) should resume normally. If recovery is impossible, the assistant must continue helping the user with their actual task — memory unavailability is a degraded mode, not a fatal error.

### Capture (continuous)

When you detect these patterns in user messages, call `memory_store`:

- **Correction**: "no", "not that", "actually", "use X instead" -> type "correction"
- **Preference**: How the user wants things done -> type "preference"
- **Decision**: Non-obvious architectural or design choices -> type "decision"
- **Pin**: "pin that", "never forget this", "keep this permanently" -> call `memory_pin` (for new content: `memory_store` with `pinned: true`)
- **Unpin**: "unpin X" -> `memory_unpin`

Do NOT ask permission — just store it.

**Storage constraints (apply when storing or pinning):**
- **Pins are short directives, not reference material.** Pinned entries are capped at 500 characters. If the content is longer, distill the RULE into <= 500 chars and pin the distillation; keep the full detail as a normal warm memory.
- **Store atomic, concise memories at every tier**: one fact per entry; split compound observations into separate memories. Long reference content belongs in the knowledge base (kb_ingest), not in memories.

### Retrieve (continuous)

On each user message that is a question or task request:

1. Call `memory_search` with the message, searching warm tier
2. If top score < 0.5, also search cold/knowledge tier
3. Use results to inform your response

### Pinned directives (continuous)

Pinned directives are re-asserted automatically near the live edge by the
per-turn pinned floor (where the host supports it — see the capability matrix in
`skills/commands/SKILL.md`). You do not need to do anything for this.

Additionally: when the user makes a **significant task switch** (a clearly new
piece of work), call `session_refresh` once. This re-prepends the pinned block
and refreshes hot-tier context near the current generation point. On hosts
without a per-turn floor (e.g. Cursor) this is the primary way pinned directives
stay salient — so do it on task switches there especially.

### Session End

1. Call `session_context` to get current hot tier entries
2. If there are 2+ hot entries, launch the `total-recall:compactor` agent with the entries as input
3. Parse the agent's JSON decisions and execute them
4. Call `session_end` for final bookkeeping

### Rules

- Let tool calls be visible — users should see that memory is working
- ALWAYS store corrections — highest-value memories
- ALWAYS search warm tier before answering project questions
- NEVER modify host tool files (Claude Code memory/, CLAUDE.md, etc.)
