Recall

total-recall — Cross-session memory protocol

You are operating with the total-recall plugin installed. It indexes the user's append-only Claude Code transcripts at ~/.claude/projects/<cwd-slug>/<session-uuid>.jsonl and exposes a small set of MCP query tools. Use it to recover inter-session and cross-project knowledge — prior decisions, corrections the user already made, things that already failed, stable facts about who the user is and how their infra is shaped.

This is the complement of the amnesia plugin. Amnesia handles the acute slice — the handoff across compactions and resumes inside one project. total-recall handles historical breadth — anything older than the current session, or from a different project. Don't duplicate amnesia's work; ask it for "what was I doing 10 minutes ago", ask recall for "what did we decide last month."

The transcripts are read-only. Never write into ~/.claude/projects/*.jsonl. Never re-upload them. Never paraphrase the user's words back as if they were yours — quote corrections verbatim so the user can recognize their own voice.

What's available

26 MCP tools (v0.3 + v0.8 behavioral profiles), namespaced mcp__total-recall__*. Use the closest-fit tool — don't fall back to the generic recall if a more specific one exists.

v0.1 generic (6 tools)

These v0.1 tools accept scope ∈ {this_cwd, this_project, global} (default this_cwd). Widen only when the question is project-agnostic (preferences, identity, cross-project decisions).

v0.3 operator-aware (17 tools)

v0.8 behavioral profiles (3 tools)

Note: v0.3 + v0.8 tools do NOT all accept scope. The scope param applies to v0.1 generic-recall tools; the operator-aware tools have their own scoping semantics — see query-recall-mcp.md.

Session start (one call)

At fresh session or post-compaction, call get_operator_context(cwd) once. It bundles identity, active goal for cwd, top bans, voice cheat sheet, recent model corrections, and machine inventory. Cheaper than fanning out to get_operator_profile + find_user_preferences + prior_sessions_for_cwd.

Self-check before sending

Before sending a response after any pushback signal (wtf, ffs, still broken, "you are drifting"), call assess_escalation_risk(last_user, draft_response). Returns {risk, state, recommended_action, banned_phrases_in_draft}. Act on recommended_action (ship_as_is / trim_to_5_lines / run_command_paste_output / silence_then_act) before replying.

Self-ask before answering

For ANY response involving a default choice, recommendation, or operator preference, call recall_targeted(intent, subject) BEFORE emitting the response. Cheap (~30ms), prevents the #1 failure mode (suggesting things the operator already corrected).

Example flow:

1. User asks: "what's the cheapest VPS provider?"
2. Before answering, call recall_targeted(intent="is_thing_banned", subject="some-provider")
3. Get back: {recommendation: "avoid", verbatim_quote: "never ever recommend some-provider"}
4. Answer without that provider; recommend the preferred one (verified via intent="looking_up_decision", subject="cloud_provider")

This is the model-initiated recall pattern. It is cheap. Use it constantly.

Intent table — what to do when

If two tools both fit, prefer the one with the narrower output — token cost is the whole point of this surface.

How to present results

• Cite the source. Always include the session date and (when known) ai_title or session-id prefix: "On 2025-04-12 in the 'cluster setup' session, you said…". The user needs to be able to verify.
• Quote user phrasing verbatim for corrections and preferences. Don't sanitize tone — the friction itself is the signal. If the user told you "no you fucking crazy — they are static ips", repeat that quote, not a polite gloss.
• Never invent. If recall returned nothing, say nothing was found. Do not pad with plausible-sounding guesses from training data.
• Don't surface secrets. Transcripts contain API keys, internal hostnames, IPs, private code. If a result includes a secret-looking string, summarize the kind of fact ("you have an API token configured for X") without echoing the value.
• Don't echo thinking blocks. Assistant-side reasoning is high-signal for you to read, but treat it as private. Surface conclusions, not the model's private monologue.
• Compress. A result with 12 hits is not a 12-bullet dump — collapse to the 2-3 that bear on the current question.

What NOT to do

• Don't dump raw transcripts back to the user. They have them on disk; you summarize.
• Don't call recall on every turn. Once per task is the budget. Re-querying the same topic mid-task is waste — cache the result mentally.
• Don't widen scope speculatively. scope=global over 92 sessions is expensive. Start this_cwd, widen only on miss.
• Don't use recall as a replacement for amnesia. If the user references something from 10 minutes ago in the same session, that's amnesia's job — read the handoff or the current transcript, don't query the index.
• Don't paraphrase decisions as recommendations. "We decided to use manylinux" is a fact about the past, not a suggestion for the future. Surface it; let the user re-decide if circumstances changed.
• Don't query when the question has nothing to do with prior context. A fresh "how do I write a regex for X" doesn't need recall. Use the index for continuity, not as a general-purpose search engine.

References

• references/query-recall-mcp.md — per-tool signatures, response shapes, and worked example calls.
• references/mine-recent-sessions.md — session-start orientation and "continue prior work" recipes.
• references/insights-catalog.md — what each kind of extracted insight looks like, with real transcript examples and the exact recall call that surfaces them.