total-recall:commands

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:

1. 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."
2. Suggest running /total-recall:commands setup to auto-configure permissions
3. 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

1. 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)
2. 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.

3. Use hints to inform your behavior throughout the session — they represent high-value memories like user corrections, preferences, and frequently accessed project context
4. 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:

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

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

1. Read ~/.claude/settings.json (create if it doesn't exist)
2. Check if permissions.allow already contains a rule matching mcp__plugin_total-recall_total-recall__* (exact or equivalent glob)
3. If missing, add "mcp__plugin_total-recall_total-recall__*" to the permissions.allow array
4. Write the updated file back
5. 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

1. Call memory_search with the query to find matching entries
2. Present matches with: ID, content preview, tier, source, access count
3. If source is from a host tool import, note the original file is NOT touched
4. Ask user which entries to delete (by number or "all")
5. Call memory_delete for each selected entry
6. 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:

1. 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
   

2. If git-checkout: run cd "$CLAUDE_PLUGIN_ROOT" && git pull origin main and report what changed (files updated, new version).

3. 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.