| name | total-recall:commands |
| description | Manage the total-recall memory system and govern automatic capture, retrieval, and compaction. Use when the user invokes /total-recall:commands, asks to search/store/forget memories, inspect tiers, manage the knowledge base, run eval, or configure total-recall. |
IMMEDIATE ACTION REQUIRED — before responding to the user's first message, call the total-recall session_start MCP tool. This syncs host imports and loads hot tier context. If session_start has already run server-side, the call returns cached results instantly.
If session_start is blocked by permissions (e.g., in TUI fullscreen / dontAsk mode), do NOT just report the error. Instead:
- 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
- Proceed without memory features for this session — memory unavailability is degraded mode, not fatal
total-recall
Memory and knowledge base management for total-recall.
Automatic Behavior
These behaviors run automatically throughout the session. Tool calls will be visible to the user.
Session Start
- Call the
session_start MCP tool to sync imports and assemble hot tier context (this may already be cached — call it regardless to receive the context)
- Announce startup using the returned data:
- Report tier summary: 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
- Keep it to 2-3 lines max. Example:
total-recall loaded — 3 hot, 12 warm, 5 cold, 2 KB collections. Storage: cortex. Last session: 2 hours ago.
Context: TODO list at docs/TODO.md; user prefers bundled PRs for refactors.
- Use
hints to inform your behavior throughout the session — they represent high-value memories like user corrections, preferences, and frequently accessed project context
- Incorporate the full
context field to inform your responses
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"
Do NOT ask permission — just store it.
Retrieve (continuous)
On each user message that is a question or task request:
- Call
memory_search with the message, searching warm tier
- If top score < 0.5, also search cold/knowledge tier
- Use results to inform your response
Session End
At session end, follow the directive in session-end.md — it is the single source of truth, injected verbatim by the SessionEnd hook (hooks/session-end/run.sh).
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.)
Commands
/total-recall:commands <subcommand> [args]
help
Print the command reference table below. Do not call any MCP tools.
| Command | Purpose |
|---|
help | Show this command reference |
setup | Auto-configure permissions for total-recall MCP tools |
status | Dashboard with tier sizes, session ID, DB stats |
search <query> | Semantic search across all tiers |
store <content> | Store a memory (--tier, --tags, --type) |
forget <query> | Find and delete memories (with confirmation) |
inspect <id> | Full details for a single entry |
promote <id> | Move an entry up one tier |
demote <id> | Move an entry down one tier |
history | Timeline of recent tier movements |
recent | List newest memories by timestamp (--limit, --tier, --type, --project, --order) |
lineage <id> | Compaction ancestry tree for an entry |
export | Export memories to JSON (--tiers, --types) |
import <path> | Import memories from a JSON file |
import-host | Import from host tools (Claude Code, etc.) |
ingest <path> | Ingest a file or directory into the knowledge base |
kb search <query> | Search the knowledge base |
kb list | List KB collections |
kb refresh <col> | Re-ingest a KB collection |
kb remove <id> | Remove a KB entry |
compact | Run hot-tier compaction now |
eval | Retrieval quality report (--benchmark, --compare, --snapshot) |
config [get|set] | View or update configuration |
update | Update the plugin to the latest version |
setup
Auto-configure Claude Code permissions so total-recall MCP tools are allowed (required for TUI fullscreen / dontAsk permission mode).
- Read
~/.claude/settings.json (create if it doesn't exist)
- Check if
permissions.allow already contains a rule matching mcp__plugin_total-recall_total-recall__* (exact or equivalent glob)
- If missing, add
"mcp__plugin_total-recall_total-recall__*" to the permissions.allow array
- Write the updated file back
- Report what changed and remind the user to restart the session for it to take effect
Important: Preserve all existing settings — only add to the allow array, never remove or overwrite other entries. If the file doesn't exist, create it with just the permissions block.
status
Call the status MCP tool. Format as a dashboard showing:
- Tier sizes (hot/warm/cold with counts for memories and knowledge)
- Session ID
- Total entry count
search
Call memory_search with the query, all tiers enabled, top_k=10. Format results grouped by tier, showing: content preview, similarity score, source, tags. Offer actions: /total-recall:commands promote <id> or /total-recall:commands forget <id>.
store
Call memory_store with the provided content. Optionally accept flags:
--tier hot|warm|cold (default: hot)
--tags tag1,tag2
--type correction|preference|decision
forget
- Call
memory_search with the query to find matching entries
- Present matches with: ID, content preview, tier, source, access count
- If source is from a host tool import, note the original file is NOT touched
- Ask user which entries to delete (by number or "all")
- Call
memory_delete for each selected entry
- Confirm deletion
Never auto-delete without user confirmation.
inspect
Call memory_inspect with the entry ID. Show full entry details including content, tier, source, tags, access count, decay score, creation/update timestamps, and compaction history.
promote [--tier hot|warm] [--type memory|knowledge]
Call memory_promote with the entry ID and target tier/type. Default target: one tier up, same content type.
demote [--tier warm|cold] [--type memory|knowledge]
Call memory_demote with the entry ID and target tier/type. Default target: one tier down, same content type.
history
Call memory_history. Show recent tier movements from the compaction log as a timeline.
recent [--limit N] [--tier hot|warm|cold] [--type ] [--project ] [--order created|updated|accessed]
Call memory_recent with the parsed flags (defaults: limit 20, all tiers, order created). Render the returned entries as a numbered list, newest first:
N. [<timestamp>] <tier> · <entry_type> · <project> — <preview>
The order field echoes which timestamp was used. Note that updated/accessed reflect activity (compaction bumps updated_at, retrieval bumps last_accessed_at), while created reflects authoring time. For full text of any entry, suggest /total-recall:commands inspect <id>; also offer promote <id> / forget <id> as follow-ups.
lineage
Call memory_lineage with the entry ID. Show the full compaction ancestry tree.
export
Call memory_export. Optionally accept --tiers hot,warm,cold and --types memory,knowledge to filter.
import
Call memory_import with the file path.
ingest
Determine if path is a file or directory:
- File: call
kb_ingest_file
- Directory: call
kb_ingest_dir
Report: collection name, document count, chunk count. Suggest a test query to verify.
kb search
Call kb_search with the query. Show results with content preview, score, collection, and source path.
If the response includes needsSummary: true, generate a 2-3 sentence summary of the collection's content based on the search results and call kb_summarize with the collection ID and summary. This improves future retrieval.
kb list
Call kb_list_collections. Show all collections with document and chunk counts.
kb refresh
Call kb_refresh with the collection ID. Report re-ingestion results.
kb remove
Call kb_remove with the entry ID. Ask for confirmation first.
compact
Call compact_now. Note: the response is informational only — real compaction is host-orchestrated via the Session End flow (session_context + memory_promote/memory_demote/memory_store/memory_delete). Surface the returned guidance and point the user at the Session End mechanism if they want to actually compact now.
eval [--benchmark] [--compare ] [--snapshot ]
- No flags: call
eval_report for live retrieval quality metrics (7-day rolling)
--benchmark: call eval_benchmark for synthetic benchmark results
--compare <name>: call eval_compare to compare against a saved baseline
--snapshot <name>: call eval_snapshot to save current config as a named baseline
config [get|set] [value]
get: call config_get with the key (or omit for full config)
set: call config_set with key and value
import-host [source]
Call import_host to detect and import memories from host tools (Claude Code, Copilot CLI). Optionally restrict to a specific source.
update
Update the plugin to the latest published version. The correct mechanism depends on how total-recall is installed:
-
Detect the install mode. Check whether the current plugin directory is a git checkout or a marketplace tarball snapshot:
if [ -n "$CLAUDE_PLUGIN_ROOT" ] && [ -d "$CLAUDE_PLUGIN_ROOT/.git" ]; then
echo "git-checkout"
else
echo "marketplace-tarball"
fi
-
If git-checkout: run cd "$CLAUDE_PLUGIN_ROOT" && git pull origin main and report what changed (files updated, new version).
-
If marketplace-tarball (the common case for users who installed via /plugin): do NOT attempt git pull — the cache directory has no .git and is managed by Claude Code. Instead, instruct the user to update it via Claude Code itself:
- Run
/plugin (or the equivalent plugin UI in their Claude Code version) and update total-recall from the strvmarv-total-recall-marketplace marketplace.
- After the update downloads, run
/reload-plugins to apply.
- Restart the session if an MCP server needs to re-initialize (e.g., to pick up a new bundled model).
Also report the latest published version so the user knows the target — check it with:
npm view @strvmarv/total-recall version
In both cases, end by reminding the user to run /reload-plugins after the update completes.