[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6MQYH1XW206FSVGDQ3X6Y14":3,"skill-same:01M6MQYH1XW206FSVGDQ3X6Y14":72},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":39,"linkOnly":40,"markdownContent":41,"markdownBody":42,"frontMatter":43,"refName":44,"commitSha":45,"skillDirectory":46,"forksCount":47,"repositoryHtmlUrl":48,"repositoryHomepageUrl":6,"ownerHtmlUrl":49,"ownerBlogUrl":50,"ownerDescription":6,"updatedAt":51,"install":52,"resources":65},"01M6MQYH1XW206FSVGDQ3X6Y14","total-recall:commands",null,"Manage the total-recall memory system and govern automatic capture, retrieval, and compaction. Use when the user invokes \u002Ftotal-recall:commands, asks to search\u002Fstore\u002Fforget memories, inspect tiers, manage the knowledge base, run eval, or configure total-recall.","strvmarv\u002Ftotal-recall","strvmarv","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F458890?v=4","01M6MQY600CFX0YA5F9HQVCATP","Paul M","01M6MQY63Q75G0301CZVX76AQV",15,"MIT","https:\u002F\u002Fgithub.com\u002Fstrvmarv\u002Ftotal-recall\u002Fblob\u002Fmain\u002Fskills\u002Fcommands\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38],"total recall:commands","recall","commands","store","use","system","manage","memories","compaction","automatic","run","knowledge base","configure","knowledge","memory system","eval","search","inspect","memory","recall memory","2026-11-10 10:12:30",false,"---\nname: total-recall:commands\ndescription: Manage the total-recall memory system and govern automatic capture, retrieval, and compaction. Use when the user invokes \u002Ftotal-recall:commands, asks to search\u002Fstore\u002Fforget memories, inspect tiers, manage the knowledge base, run eval, or configure total-recall.\n---\n\n**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.**\n\n**If `session_start` is blocked by permissions** (e.g., in TUI fullscreen \u002F `dontAsk` mode), do NOT just report the error. Instead:\n1. Tell the user: \"total-recall session_start was blocked by permissions. Your host's tool-permission settings need to allow total-recall's MCP tools to function (the exact tool name depends on how your host namespaces MCP tools). You may need to adjust permissions if you want total-recall active this session.\"\n2. On Claude Code, suggest running `\u002Ftotal-recall:commands setup` to auto-configure permissions; other hosts don't have an automated fix yet — point the user at their host's own MCP tool-permission config.\n3. Proceed without memory features for this session — memory unavailability is degraded mode, not fatal\n\n# total-recall\n\nMemory and knowledge base management for total-recall.\n\n## Automatic Behavior\n\nThese behaviors run automatically throughout the session. Tool calls will be visible to the user.\n\n### Session Start\n\n1. 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)\n2. **Announce startup** using the returned data:\n   - Report tier summary: pinned, hot, warm, cold, KB counts from `tierSummary`\n   - Report storage backend from `storage` (e.g. \"sqlite\", \"cortex\", \"postgres\"). If it shows a fallback like \"sqlite (cortex failed)\", flag this prominently.\n   - If `lastSessionAge` is present, mention when the last session was\n   - If `hints` are present, briefly surface the most relevant ones\n   - 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\n   - Keep it to 2-3 lines max. Example:\n     > total-recall loaded — 2 pinned, 3 hot, 12 warm, 5 cold, 2 KB collections. Storage: cortex. Last session: 2 hours ago.\n     > Context: TODO list at docs\u002FTODO.md; user prefers bundled PRs for refactors.\n3. Use `hints` to inform your behavior throughout the session — they represent high-value memories like user corrections, preferences, and frequently accessed project context\n4. Incorporate the full `context` field to inform your responses\n\n### Capture (continuous)\n\nWhen you detect these patterns in user messages, call `memory_store`:\n\n- **Correction**: \"no\", \"not that\", \"actually\", \"use X instead\" -> type \"correction\"\n- **Preference**: How the user wants things done -> type \"preference\"\n- **Decision**: Non-obvious architectural or design choices -> type \"decision\"\n\nDo NOT ask permission — just store it.\n\n### Retrieve (continuous)\n\nOn each user message that is a question or task request:\n\n1. Call `memory_search` with the message, searching warm tier\n2. If top score \u003C 0.5, also search cold\u002Fknowledge tier\n3. Use results to inform your response\n\n### Feedback (continuous)\n\n`memory_search` and `kb_search` now return a `retrievalId` alongside `results`.\nAfter you use retrieved memories in your work, call `memory_feedback`:\n\n- Used it → `memory_feedback({ retrievalId, used: true })`\n- Searched and nothing was relevant → `memory_feedback({ retrievalId, used: false })`\n\nReport once per search, as soon as you know the outcome. Skip the call only when\n`retrievalId` is empty. Do NOT ask permission — just report it. This is what makes\nthe Dashboard \"Retrieval quality\" metric real.\n\n### Pinned directives (continuous)\n\nPinned directives are re-asserted automatically near the live edge by the\nper-turn pinned floor (where the host supports it — see the capability matrix\nunder \"Pinned directive floor\" below). You do not need to do anything for this.\n\nAdditionally: when the user makes a **significant task switch** (a clearly new\npiece of work), call `session_refresh` once. This re-prepends the pinned block\nand refreshes hot-tier context near the current generation point.\n\n### Session End\n\nAt session end, total-recall surfaces a hint suggesting you run `\u002Ftotal-recall:commands compact` to promote hot entries before the session closes. Compaction is user-triggered — run the command when the hint appears or whenever you want to compact manually. Also call the `session_end` MCP tool for final bookkeeping.\n\n### Rules\n\n- Let tool calls be visible — users should see that memory is working\n- ALWAYS store corrections — highest-value memories\n- ALWAYS search warm tier before answering project questions\n- NEVER modify host tool files (Claude Code memory\u002F, CLAUDE.md, etc.)\n\n## Pinned directive floor\n\nA `UserPromptSubmit` hook re-injects the pinned block on an adaptive throttle\n(config: `[tiers.pinned] floor_enabled \u002F floor_every_n_turns \u002F floor_growth_tokens`)\nso pinned directives keep being followed in long sessions. It re-asserts when\neither trigger trips since the last injection: N turns elapsed, or ~`growth_tokens`\nof transcript growth (where the host exposes a transcript). Set `floor_enabled = false` to disable.\n\n| Host | Per-turn floor | Mechanism |\n|------|----------------|-----------|\n| Claude Code | Active | `UserPromptSubmit` → `additionalContext` |\n| Copilot CLI | Active (turn-count trigger only) | `userPromptSubmitted` hook (`copilot\u002Fhook.js`) → `additionalContext` |\n| Cursor | Active on tool-using turns (turn-count trigger only) | `postToolUse` hook (`cursor\u002Fhook.js`) → `additional_context` |\n| Kiro | Active | `UserPromptSubmit` command hook → pinned-floor (plain-text STDOUT); `SessionStart` agent hook → `session_start` tool; `Stop` agent hook → capture; `always` steering → persistent `session_start` instruction |\n| Gemini CLI | Active | `BeforeAgent` hook → `hookSpecificOutput.additionalContext`; `GEMINI.md` → persistent `session_start` instruction |\n| pi | Active (turn-count trigger only) | pi extension: `before_agent_start` → hidden context message; `\u002Ftotal-recall` command |\n| Codex CLI | Active (turn-count trigger only) | `UserPromptSubmit` hook (`codex\u002Fhook.js`) → `additionalContext` |\n| Cline | MCP tools only | No hooks; `cline_mcp_settings.json` via postinstall |\n| Windsurf | MCP tools only | No hooks; `mcp_config.json` + rules file via postinstall |\n| Zed | MCP tools only | No hooks; `context_servers` in `settings.json` via postinstall |\n| VS Code | MCP tools only | No hooks; `mcp.json` (`servers` key) via postinstall |\n\n---\n\n## Commands\n\n`\u002Ftotal-recall:commands \u003Csubcommand> [args]`\n\n### help\n\nPrint the command reference table below. Do not call any MCP tools.\n\n| Command | Purpose |\n|---|---|\n| `help` | Show this command reference |\n| `setup` | Auto-configure permissions for total-recall MCP tools |\n| `status` | Dashboard with tier sizes, session ID, DB stats |\n| `search \u003Cquery>` | Semantic search across all tiers |\n| `store \u003Ccontent>` | Store a memory (`--tier`, `--tags`, `--type`) |\n| `forget \u003Cquery>` | Find and delete memories (with confirmation) |\n| `inspect \u003Cid>` | Full details for a single entry |\n| `promote \u003Cid>` | Move an entry up one tier |\n| `demote \u003Cid>` | Move an entry down one tier |\n| `pin \u003Cid>` | Pin an entry to the pinned tier (always injected, never decays) |\n| `unpin \u003Cid>` | Release a pinned entry back to the warm tier |\n| `history` | Timeline of recent tier movements |\n| `recent` | List newest memories by timestamp (`--limit`, `--tier`, `--type`, `--project`, `--order`); `--tier pinned` supported |\n| `lineage \u003Cid>` | Compaction ancestry tree for an entry |\n| `export` | Export memories to JSON (`--tiers`, `--types`) |\n| `import \u003Cpath>` | Import memories from a JSON file |\n| `import-host` | Import from host tools (Claude Code, etc.) |\n| `ingest \u003Cpath>` | Ingest a file or directory into the knowledge base |\n| `kb search \u003Cquery>` | Search the knowledge base |\n| `kb list` | List KB collections |\n| `kb refresh \u003Ccol>` | Re-ingest a KB collection |\n| `kb remove \u003Cid>` | Remove a KB entry |\n| `compact [--fast]` | Compact hot tier now (default: model-driven; `--fast`: heuristic sweep) |\n| `eval` | Retrieval quality report (`--benchmark`, `--compare`, `--snapshot`) |\n| `config [get\\|set]` | View or update configuration |\n| `update` | Update the plugin to the latest version |\n| `ui` | Open the built-in web management UI in the browser (`total-recall ui`) |\n\n### setup\n\nAuto-configure Claude Code permissions so total-recall MCP tools are allowed (required for TUI fullscreen \u002F `dontAsk` permission mode). **This subcommand is Claude Code-specific** — it automates `~\u002F.claude\u002Fsettings.json`. On other hosts, there is no known automatic fix yet: report that to the user and point them at their host's own MCP tool-permission mechanism instead of attempting these steps.\n\n1. Read `~\u002F.claude\u002Fsettings.json` (create if it doesn't exist)\n2. Check if `permissions.allow` already contains a rule matching `mcp__plugin_total-recall_total-recall__*` (exact or equivalent glob)\n3. If missing, add `\"mcp__plugin_total-recall_total-recall__*\"` to the `permissions.allow` array\n4. Write the updated file back\n5. Report what changed and remind the user to restart the session for it to take effect\n\n**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.\n\n### status\n\nCall the `status` MCP tool. Format as a dashboard showing:\n- Tier sizes (pinned\u002Fhot\u002Fwarm\u002Fcold with counts for memories and knowledge)\n- Session ID\n- Total entry count\n\n### search \u003Cquery>\n\nCall `memory_search` with the query, all tiers enabled, top_k=10. Format results grouped by tier, showing: content preview, similarity score, source, tags. Valid tier filter values: `hot`, `warm`, `cold`, `pinned`. Offer actions: `\u002Ftotal-recall:commands promote \u003Cid>`, `\u002Ftotal-recall:commands pin \u003Cid>`, or `\u002Ftotal-recall:commands forget \u003Cid>`.\n\n### store \u003Ccontent>\n\nCall `memory_store` with the provided content. Optionally accept flags:\n- `--tier hot|warm|cold` (default: warm)\n- `--tags tag1,tag2`\n- `--type correction|preference|decision`\n- `--pinned` is not a tier value — to store-and-pin new content use `memory_store` with `pinned: true` (see `### pin`).\n\n### forget \u003Cquery>\n\n1. Call `memory_search` with the query to find matching entries\n2. Present matches with: ID, content preview, tier, source, access count\n3. If source is from a host tool import, note the original file is NOT touched\n4. Ask user which entries to delete (by number or \"all\")\n5. Call `memory_delete` for each selected entry\n6. Confirm deletion\n\nNever auto-delete without user confirmation.\n\n### inspect \u003Cid>\n\nCall `memory_inspect` with the entry ID. Show full entry details including content, tier, source, tags, access count, decay score, creation\u002Fupdate timestamps, and compaction history.\n\n### promote \u003Cid> [--tier hot|warm] [--type memory|knowledge]\n\nCall `memory_promote` with the entry ID and target tier\u002Ftype. Default target: one tier up, same content type.\n\n### demote \u003Cid> [--tier warm|cold] [--type memory|knowledge]\n\nCall `memory_demote` with the entry ID and target tier\u002Ftype. Default target: one tier down, same content type.\n\n### pin \u003Cid> [--scope project|global] [--project \u003Cname>] [--type memory|knowledge]\n\nCall `memory_pin` with the entry ID and optional scope\u002Fproject\u002Ftype. Pin a memory so it is ALWAYS injected at session start and never decays or compacts. The only way out is `unpin`.\n\n- MCP: `memory_pin { id, scope?: \"project\"|\"global\", project?, type? }`\n- CLI: `total-recall memory pin \u003Cid> [--scope project|global] [--project \u003Cname>] [--type memory|knowledge]`\n- `scope: \"global\"` makes the pin visible in every project; `scope: \"project\"` scopes it to the given (or existing) project; omitted keeps the entry's current project.\n- Pinning an already-pinned entry is a no-op success (scope still applied).\n- Pinned entries are capped at 500 characters (config: `tiers.pinned.max_content_chars`, default 500) — pins are directives, not reference material. Oversized content is rejected, never truncated or auto-summarized: distill the rule and pin the distillation; keep the full detail as a normal warm memory.\n- For NEW content, `memory_store` with `pinned: true` stores-and-pins in one call (no pre-existing id required).\n\n### unpin \u003Cid> [--type memory|knowledge]\n\nCall `memory_unpin` with the entry ID. Release a pinned entry back to the warm tier, where the normal decay\u002Fcompaction lifecycle resumes.\n\n- MCP: `memory_unpin { id, type? }`\n- CLI: `total-recall memory unpin \u003Cid> [--type memory|knowledge]`\n- Errors if the entry is not pinned (reports its actual tier).\n\n### history\n\nCall `memory_history`. Show recent tier movements from the compaction log as a timeline.\n\n### recent [--limit N] [--tier hot|warm|cold|pinned] [--type \u003CentryType>] [--project \u003Cname>] [--order created|updated|accessed]\n\nCall `memory_recent` with the parsed flags (defaults: limit 20, all tiers, order `created`). Render the returned `entries` as a numbered list, newest first:\n\n`N. [\u003Ctimestamp>] \u003Ctier> · \u003Centry_type> · \u003Cproject> — \u003Cpreview>`\n\nThe `order` field echoes which timestamp was used. Note that `updated`\u002F`accessed` reflect activity (compaction bumps `updated_at`, retrieval bumps `last_accessed_at`), while `created` reflects authoring time. For full text of any entry, suggest `\u002Ftotal-recall:commands inspect \u003Cid>`; also offer `promote \u003Cid>` \u002F `forget \u003Cid>` as follow-ups.\n\n### lineage \u003Cid>\n\nCall `memory_lineage` with the entry ID. Show the full compaction ancestry tree.\n\n### export\n\nCall `memory_export`. Optionally accept `--tiers hot,warm,cold,pinned` and `--types memory,knowledge` to filter.\n\n### import \u003Cpath>\n\nCall `memory_import` with the file path.\n\n### ingest \u003Cpath>\n\nDetermine if path is a file or directory:\n- File: call `kb_ingest_file`\n- Directory: call `kb_ingest_dir`\n\nReport: collection name, document count, chunk count. Suggest a test query to verify.\n\n### kb search \u003Cquery>\n\nCall `kb_search` with the query. Show results with content preview, score, collection, and source path.\n\nIf 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.\n\n### kb list\n\nCall `kb_list_collections`. Show all collections with document and chunk counts.\n\n### kb refresh \u003Ccollection>\n\nCall `kb_refresh` with the collection ID. Report re-ingestion results.\n\n### kb remove \u003Cid>\n\nCall `kb_remove` with the entry ID. Ask for confirmation first.\n\n### compact [--fast]\n\nRun hot-tier compaction now. Compaction is user-triggered; hints appear at session start, mid-session, and session end to remind you. Two modes:\n\n- **Default (model-driven):** Launches the `total-recall:compactor` agent against current hot tier entries (via `session_context`), then executes its decisions — carry forward, promote with summary, or discard. Reports a one-line summary of what was promoted\u002Fdiscarded. On hosts without the compactor agent (pi), use `--fast` or make the same carry-forward \u002F promote \u002F discard calls yourself from `session_context`.\n- **`--fast` (heuristic):** Runs `total-recall compact --run` — a deterministic decay-based sweep that promotes hot entries whose decay score falls below `compaction.warm_threshold`. No LLM, fast and cheap.\n\nSee the full command body in [`compact.md`](compact.md).\n\n### eval [--benchmark] [--compare \u003Cname>] [--snapshot \u003Cname>]\n\n- No flags: call `eval_report` for live retrieval quality metrics (7-day rolling)\n- `--benchmark`: call `eval_benchmark` for synthetic benchmark results\n- `--compare \u003Cname>`: call `eval_compare` to compare against a saved baseline\n- `--snapshot \u003Cname>`: call `eval_snapshot` to save current config as a named baseline\n\n### config [get|set] \u003Ckey> [value]\n\n- `get`: call `config_get` with the key (or omit for full config)\n- `set`: call `config_set` with key and value\n\n### ui [--port N] [--no-open] [--host H] [--smoke]\n\nLaunch the built-in web management UI. This is a CLI command, not an MCP tool — instruct the user to run:\n\n```bash\ntotal-recall ui\n```\n\nOptionally pass flags: `--port N` (default 5577), `--no-open` (skip browser auto-open), `--host H` (bind address, default `localhost`), `--smoke` (CI probe: start, check `\u002Fapi\u002Fhealth`, exit 0\u002F1). The UI provides six sections: Dashboard · Memory · Knowledge Base · Usage · Insights · Config. The access token is embedded in the served page — no manual credential setup needed.\n\n### import-host [source]\n\nCall `import_host` to detect and import memories from host tools (Claude Code, Copilot CLI). Optionally restrict to a specific source.\n\n### update\n\nUpdate the plugin to the latest published version. The correct mechanism depends on how total-recall is installed:\n\n1. **Detect the install mode.** Check whether the current plugin directory is a git checkout or a marketplace tarball snapshot:\n\n   ```bash\n   if [ -n \"$CLAUDE_PLUGIN_ROOT\" ] && [ -d \"$CLAUDE_PLUGIN_ROOT\u002F.git\" ]; then\n     echo \"git-checkout\"\n   else\n     echo \"marketplace-tarball\"\n   fi\n   ```\n\n2. **If `git-checkout`:** run `cd \"$CLAUDE_PLUGIN_ROOT\" && git pull origin main` and report what changed (files updated, new version).\n\n3. **If `marketplace-tarball`** (the common case for users who installed via `\u002Fplugin`): 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:\n   - Run `\u002Fplugin` (or the equivalent plugin UI in their Claude Code version) and update `total-recall` from the `strvmarv-total-recall-marketplace` marketplace.\n   - After the update downloads, run `\u002Freload-plugins` to apply.\n   - Restart the session if an MCP server needs to re-initialize (e.g., to pick up a new bundled model).\n\n   Also report the latest published version so the user knows the target — check it with:\n   ```bash\n   npm view @strvmarv\u002Ftotal-recall version\n   ```\n\nIn both cases, end by reminding the user to run `\u002Freload-plugins` after the update completes.\n","**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.**\n\n**If `session_start` is blocked by permissions** (e.g., in TUI fullscreen \u002F `dontAsk` mode), do NOT just report the error. Instead:\n1. Tell the user: \"total-recall session_start was blocked by permissions. Your host's tool-permission settings need to allow total-recall's MCP tools to function (the exact tool name depends on how your host namespaces MCP tools). You may need to adjust permissions if you want total-recall active this session.\"\n2. On Claude Code, suggest running `\u002Ftotal-recall:commands setup` to auto-configure permissions; other hosts don't have an automated fix yet — point the user at their host's own MCP tool-permission config.\n3. Proceed without memory features for this session — memory unavailability is degraded mode, not fatal\n\n# total-recall\n\nMemory and knowledge base management for total-recall.\n\n## Automatic Behavior\n\nThese behaviors run automatically throughout the session. Tool calls will be visible to the user.\n\n### Session Start\n\n1. 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)\n2. **Announce startup** using the returned data:\n   - Report tier summary: pinned, hot, warm, cold, KB counts from `tierSummary`\n   - Report storage backend from `storage` (e.g. \"sqlite\", \"cortex\", \"postgres\"). If it shows a fallback like \"sqlite (cortex failed)\", flag this prominently.\n   - If `lastSessionAge` is present, mention when the last session was\n   - If `hints` are present, briefly surface the most relevant ones\n   - 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\n   - Keep it to 2-3 lines max. Example:\n     > total-recall loaded — 2 pinned, 3 hot, 12 warm, 5 cold, 2 KB collections. Storage: cortex. Last session: 2 hours ago.\n     > Context: TODO list at docs\u002FTODO.md; user prefers bundled PRs for refactors.\n3. Use `hints` to inform your behavior throughout the session — they represent high-value memories like user corrections, preferences, and frequently accessed project context\n4. Incorporate the full `context` field to inform your responses\n\n### Capture (continuous)\n\nWhen you detect these patterns in user messages, call `memory_store`:\n\n- **Correction**: \"no\", \"not that\", \"actually\", \"use X instead\" -> type \"correction\"\n- **Preference**: How the user wants things done -> type \"preference\"\n- **Decision**: Non-obvious architectural or design choices -> type \"decision\"\n\nDo NOT ask permission — just store it.\n\n### Retrieve (continuous)\n\nOn each user message that is a question or task request:\n\n1. Call `memory_search` with the message, searching warm tier\n2. If top score \u003C 0.5, also search cold\u002Fknowledge tier\n3. Use results to inform your response\n\n### Feedback (continuous)\n\n`memory_search` and `kb_search` now return a `retrievalId` alongside `results`.\nAfter you use retrieved memories in your work, call `memory_feedback`:\n\n- Used it → `memory_feedback({ retrievalId, used: true })`\n- Searched and nothing was relevant → `memory_feedback({ retrievalId, used: false })`\n\nReport once per search, as soon as you know the outcome. Skip the call only when\n`retrievalId` is empty. Do NOT ask permission — just report it. This is what makes\nthe Dashboard \"Retrieval quality\" metric real.\n\n### Pinned directives (continuous)\n\nPinned directives are re-asserted automatically near the live edge by the\nper-turn pinned floor (where the host supports it — see the capability matrix\nunder \"Pinned directive floor\" below). You do not need to do anything for this.\n\nAdditionally: when the user makes a **significant task switch** (a clearly new\npiece of work), call `session_refresh` once. This re-prepends the pinned block\nand refreshes hot-tier context near the current generation point.\n\n### Session End\n\nAt session end, total-recall surfaces a hint suggesting you run `\u002Ftotal-recall:commands compact` to promote hot entries before the session closes. Compaction is user-triggered — run the command when the hint appears or whenever you want to compact manually. Also call the `session_end` MCP tool for final bookkeeping.\n\n### Rules\n\n- Let tool calls be visible — users should see that memory is working\n- ALWAYS store corrections — highest-value memories\n- ALWAYS search warm tier before answering project questions\n- NEVER modify host tool files (Claude Code memory\u002F, CLAUDE.md, etc.)\n\n## Pinned directive floor\n\nA `UserPromptSubmit` hook re-injects the pinned block on an adaptive throttle\n(config: `[tiers.pinned] floor_enabled \u002F floor_every_n_turns \u002F floor_growth_tokens`)\nso pinned directives keep being followed in long sessions. It re-asserts when\neither trigger trips since the last injection: N turns elapsed, or ~`growth_tokens`\nof transcript growth (where the host exposes a transcript). Set `floor_enabled = false` to disable.\n\n| Host | Per-turn floor | Mechanism |\n|------|----------------|-----------|\n| Claude Code | Active | `UserPromptSubmit` → `additionalContext` |\n| Copilot CLI | Active (turn-count trigger only) | `userPromptSubmitted` hook (`copilot\u002Fhook.js`) → `additionalContext` |\n| Cursor | Active on tool-using turns (turn-count trigger only) | `postToolUse` hook (`cursor\u002Fhook.js`) → `additional_context` |\n| Kiro | Active | `UserPromptSubmit` command hook → pinned-floor (plain-text STDOUT); `SessionStart` agent hook → `session_start` tool; `Stop` agent hook → capture; `always` steering → persistent `session_start` instruction |\n| Gemini CLI | Active | `BeforeAgent` hook → `hookSpecificOutput.additionalContext`; `GEMINI.md` → persistent `session_start` instruction |\n| pi | Active (turn-count trigger only) | pi extension: `before_agent_start` → hidden context message; `\u002Ftotal-recall` command |\n| Codex CLI | Active (turn-count trigger only) | `UserPromptSubmit` hook (`codex\u002Fhook.js`) → `additionalContext` |\n| Cline | MCP tools only | No hooks; `cline_mcp_settings.json` via postinstall |\n| Windsurf | MCP tools only | No hooks; `mcp_config.json` + rules file via postinstall |\n| Zed | MCP tools only | No hooks; `context_servers` in `settings.json` via postinstall |\n| VS Code | MCP tools only | No hooks; `mcp.json` (`servers` key) via postinstall |\n\n---\n\n## Commands\n\n`\u002Ftotal-recall:commands \u003Csubcommand> [args]`\n\n### help\n\nPrint the command reference table below. Do not call any MCP tools.\n\n| Command | Purpose |\n|---|---|\n| `help` | Show this command reference |\n| `setup` | Auto-configure permissions for total-recall MCP tools |\n| `status` | Dashboard with tier sizes, session ID, DB stats |\n| `search \u003Cquery>` | Semantic search across all tiers |\n| `store \u003Ccontent>` | Store a memory (`--tier`, `--tags`, `--type`) |\n| `forget \u003Cquery>` | Find and delete memories (with confirmation) |\n| `inspect \u003Cid>` | Full details for a single entry |\n| `promote \u003Cid>` | Move an entry up one tier |\n| `demote \u003Cid>` | Move an entry down one tier |\n| `pin \u003Cid>` | Pin an entry to the pinned tier (always injected, never decays) |\n| `unpin \u003Cid>` | Release a pinned entry back to the warm tier |\n| `history` | Timeline of recent tier movements |\n| `recent` | List newest memories by timestamp (`--limit`, `--tier`, `--type`, `--project`, `--order`); `--tier pinned` supported |\n| `lineage \u003Cid>` | Compaction ancestry tree for an entry |\n| `export` | Export memories to JSON (`--tiers`, `--types`) |\n| `import \u003Cpath>` | Import memories from a JSON file |\n| `import-host` | Import from host tools (Claude Code, etc.) |\n| `ingest \u003Cpath>` | Ingest a file or directory into the knowledge base |\n| `kb search \u003Cquery>` | Search the knowledge base |\n| `kb list` | List KB collections |\n| `kb refresh \u003Ccol>` | Re-ingest a KB collection |\n| `kb remove \u003Cid>` | Remove a KB entry |\n| `compact [--fast]` | Compact hot tier now (default: model-driven; `--fast`: heuristic sweep) |\n| `eval` | Retrieval quality report (`--benchmark`, `--compare`, `--snapshot`) |\n| `config [get\\|set]` | View or update configuration |\n| `update` | Update the plugin to the latest version |\n| `ui` | Open the built-in web management UI in the browser (`total-recall ui`) |\n\n### setup\n\nAuto-configure Claude Code permissions so total-recall MCP tools are allowed (required for TUI fullscreen \u002F `dontAsk` permission mode). **This subcommand is Claude Code-specific** — it automates `~\u002F.claude\u002Fsettings.json`. On other hosts, there is no known automatic fix yet: report that to the user and point them at their host's own MCP tool-permission mechanism instead of attempting these steps.\n\n1. Read `~\u002F.claude\u002Fsettings.json` (create if it doesn't exist)\n2. Check if `permissions.allow` already contains a rule matching `mcp__plugin_total-recall_total-recall__*` (exact or equivalent glob)\n3. If missing, add `\"mcp__plugin_total-recall_total-recall__*\"` to the `permissions.allow` array\n4. Write the updated file back\n5. Report what changed and remind the user to restart the session for it to take effect\n\n**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.\n\n### status\n\nCall the `status` MCP tool. Format as a dashboard showing:\n- Tier sizes (pinned\u002Fhot\u002Fwarm\u002Fcold with counts for memories and knowledge)\n- Session ID\n- Total entry count\n\n### search \u003Cquery>\n\nCall `memory_search` with the query, all tiers enabled, top_k=10. Format results grouped by tier, showing: content preview, similarity score, source, tags. Valid tier filter values: `hot`, `warm`, `cold`, `pinned`. Offer actions: `\u002Ftotal-recall:commands promote \u003Cid>`, `\u002Ftotal-recall:commands pin \u003Cid>`, or `\u002Ftotal-recall:commands forget \u003Cid>`.\n\n### store \u003Ccontent>\n\nCall `memory_store` with the provided content. Optionally accept flags:\n- `--tier hot|warm|cold` (default: warm)\n- `--tags tag1,tag2`\n- `--type correction|preference|decision`\n- `--pinned` is not a tier value — to store-and-pin new content use `memory_store` with `pinned: true` (see `### pin`).\n\n### forget \u003Cquery>\n\n1. Call `memory_search` with the query to find matching entries\n2. Present matches with: ID, content preview, tier, source, access count\n3. If source is from a host tool import, note the original file is NOT touched\n4. Ask user which entries to delete (by number or \"all\")\n5. Call `memory_delete` for each selected entry\n6. Confirm deletion\n\nNever auto-delete without user confirmation.\n\n### inspect \u003Cid>\n\nCall `memory_inspect` with the entry ID. Show full entry details including content, tier, source, tags, access count, decay score, creation\u002Fupdate timestamps, and compaction history.\n\n### promote \u003Cid> [--tier hot|warm] [--type memory|knowledge]\n\nCall `memory_promote` with the entry ID and target tier\u002Ftype. Default target: one tier up, same content type.\n\n### demote \u003Cid> [--tier warm|cold] [--type memory|knowledge]\n\nCall `memory_demote` with the entry ID and target tier\u002Ftype. Default target: one tier down, same content type.\n\n### pin \u003Cid> [--scope project|global] [--project \u003Cname>] [--type memory|knowledge]\n\nCall `memory_pin` with the entry ID and optional scope\u002Fproject\u002Ftype. Pin a memory so it is ALWAYS injected at session start and never decays or compacts. The only way out is `unpin`.\n\n- MCP: `memory_pin { id, scope?: \"project\"|\"global\", project?, type? }`\n- CLI: `total-recall memory pin \u003Cid> [--scope project|global] [--project \u003Cname>] [--type memory|knowledge]`\n- `scope: \"global\"` makes the pin visible in every project; `scope: \"project\"` scopes it to the given (or existing) project; omitted keeps the entry's current project.\n- Pinning an already-pinned entry is a no-op success (scope still applied).\n- Pinned entries are capped at 500 characters (config: `tiers.pinned.max_content_chars`, default 500) — pins are directives, not reference material. Oversized content is rejected, never truncated or auto-summarized: distill the rule and pin the distillation; keep the full detail as a normal warm memory.\n- For NEW content, `memory_store` with `pinned: true` stores-and-pins in one call (no pre-existing id required).\n\n### unpin \u003Cid> [--type memory|knowledge]\n\nCall `memory_unpin` with the entry ID. Release a pinned entry back to the warm tier, where the normal decay\u002Fcompaction lifecycle resumes.\n\n- MCP: `memory_unpin { id, type? }`\n- CLI: `total-recall memory unpin \u003Cid> [--type memory|knowledge]`\n- Errors if the entry is not pinned (reports its actual tier).\n\n### history\n\nCall `memory_history`. Show recent tier movements from the compaction log as a timeline.\n\n### recent [--limit N] [--tier hot|warm|cold|pinned] [--type \u003CentryType>] [--project \u003Cname>] [--order created|updated|accessed]\n\nCall `memory_recent` with the parsed flags (defaults: limit 20, all tiers, order `created`). Render the returned `entries` as a numbered list, newest first:\n\n`N. [\u003Ctimestamp>] \u003Ctier> · \u003Centry_type> · \u003Cproject> — \u003Cpreview>`\n\nThe `order` field echoes which timestamp was used. Note that `updated`\u002F`accessed` reflect activity (compaction bumps `updated_at`, retrieval bumps `last_accessed_at`), while `created` reflects authoring time. For full text of any entry, suggest `\u002Ftotal-recall:commands inspect \u003Cid>`; also offer `promote \u003Cid>` \u002F `forget \u003Cid>` as follow-ups.\n\n### lineage \u003Cid>\n\nCall `memory_lineage` with the entry ID. Show the full compaction ancestry tree.\n\n### export\n\nCall `memory_export`. Optionally accept `--tiers hot,warm,cold,pinned` and `--types memory,knowledge` to filter.\n\n### import \u003Cpath>\n\nCall `memory_import` with the file path.\n\n### ingest \u003Cpath>\n\nDetermine if path is a file or directory:\n- File: call `kb_ingest_file`\n- Directory: call `kb_ingest_dir`\n\nReport: collection name, document count, chunk count. Suggest a test query to verify.\n\n### kb search \u003Cquery>\n\nCall `kb_search` with the query. Show results with content preview, score, collection, and source path.\n\nIf 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.\n\n### kb list\n\nCall `kb_list_collections`. Show all collections with document and chunk counts.\n\n### kb refresh \u003Ccollection>\n\nCall `kb_refresh` with the collection ID. Report re-ingestion results.\n\n### kb remove \u003Cid>\n\nCall `kb_remove` with the entry ID. Ask for confirmation first.\n\n### compact [--fast]\n\nRun hot-tier compaction now. Compaction is user-triggered; hints appear at session start, mid-session, and session end to remind you. Two modes:\n\n- **Default (model-driven):** Launches the `total-recall:compactor` agent against current hot tier entries (via `session_context`), then executes its decisions — carry forward, promote with summary, or discard. Reports a one-line summary of what was promoted\u002Fdiscarded. On hosts without the compactor agent (pi), use `--fast` or make the same carry-forward \u002F promote \u002F discard calls yourself from `session_context`.\n- **`--fast` (heuristic):** Runs `total-recall compact --run` — a deterministic decay-based sweep that promotes hot entries whose decay score falls below `compaction.warm_threshold`. No LLM, fast and cheap.\n\nSee the full command body in [`compact.md`](compact.md).\n\n### eval [--benchmark] [--compare \u003Cname>] [--snapshot \u003Cname>]\n\n- No flags: call `eval_report` for live retrieval quality metrics (7-day rolling)\n- `--benchmark`: call `eval_benchmark` for synthetic benchmark results\n- `--compare \u003Cname>`: call `eval_compare` to compare against a saved baseline\n- `--snapshot \u003Cname>`: call `eval_snapshot` to save current config as a named baseline\n\n### config [get|set] \u003Ckey> [value]\n\n- `get`: call `config_get` with the key (or omit for full config)\n- `set`: call `config_set` with key and value\n\n### ui [--port N] [--no-open] [--host H] [--smoke]\n\nLaunch the built-in web management UI. This is a CLI command, not an MCP tool — instruct the user to run:\n\n```bash\ntotal-recall ui\n```\n\nOptionally pass flags: `--port N` (default 5577), `--no-open` (skip browser auto-open), `--host H` (bind address, default `localhost`), `--smoke` (CI probe: start, check `\u002Fapi\u002Fhealth`, exit 0\u002F1). The UI provides six sections: Dashboard · Memory · Knowledge Base · Usage · Insights · Config. The access token is embedded in the served page — no manual credential setup needed.\n\n### import-host [source]\n\nCall `import_host` to detect and import memories from host tools (Claude Code, Copilot CLI). Optionally restrict to a specific source.\n\n### update\n\nUpdate the plugin to the latest published version. The correct mechanism depends on how total-recall is installed:\n\n1. **Detect the install mode.** Check whether the current plugin directory is a git checkout or a marketplace tarball snapshot:\n\n   ```bash\n   if [ -n \"$CLAUDE_PLUGIN_ROOT\" ] && [ -d \"$CLAUDE_PLUGIN_ROOT\u002F.git\" ]; then\n     echo \"git-checkout\"\n   else\n     echo \"marketplace-tarball\"\n   fi\n   ```\n\n2. **If `git-checkout`:** run `cd \"$CLAUDE_PLUGIN_ROOT\" && git pull origin main` and report what changed (files updated, new version).\n\n3. **If `marketplace-tarball`** (the common case for users who installed via `\u002Fplugin`): 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:\n   - Run `\u002Fplugin` (or the equivalent plugin UI in their Claude Code version) and update `total-recall` from the `strvmarv-total-recall-marketplace` marketplace.\n   - After the update downloads, run `\u002Freload-plugins` to apply.\n   - Restart the session if an MCP server needs to re-initialize (e.g., to pick up a new bundled model).\n\n   Also report the latest published version so the user knows the target — check it with:\n   ```bash\n   npm view @strvmarv\u002Ftotal-recall version\n   ```\n\nIn both cases, end by reminding the user to run `\u002Freload-plugins` after the update completes.\n",{"name":5,"description":7},"main","672198f67413640b006a8e0ae33620b6590859a6","skills\u002Fcommands",5,"https:\u002F\u002Fgithub.com\u002Fstrvmarv\u002Ftotal-recall","https:\u002F\u002Fgithub.com\u002Fstrvmarv","www.linkedin.com\u002Fin\u002Fpaulmarvin","2026-11-12 10:39:33",{"source":8,"skillName":5,"commands":53,"prompt":63,"zipAvailable":64},[54,57,60],{"tool":55,"command":56},"npx","npx skills add strvmarv\u002Ftotal-recall --skill \"total-recall:commands\"",{"tool":58,"command":59},"bunx","bunx skills add strvmarv\u002Ftotal-recall --skill \"total-recall:commands\"",{"tool":61,"command":62},"pnpm","pnpm dlx skills add strvmarv\u002Ftotal-recall --skill \"total-recall:commands\"","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fstrvmarv\u002Ftotal-recall\u002Fblob\u002Fmain\u002Fskills\u002Fcommands\u002FSKILL.md",true,[66],{"path":67,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":70,"sourceHtmlUrl":71},"compact.md","REFERENCE","参考文档",1062,"https:\u002F\u002Fgithub.com\u002Fstrvmarv\u002Ftotal-recall\u002Fblob\u002Fmain\u002Fskills\u002Fcommands\u002Fcompact.md",[73,86,96,110],{"skillNo":74,"name":75,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":83,"publishedAt":39},"01M6MQZ4AH2W1VGD6F8Q931M0S","malformed-skill","https:\u002F\u002Fgithub.com\u002Fstrvmarv\u002Ftotal-recall\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Fmalformed-skill\u002FSKILL.md",[78],{"categoryNo":79,"categoryName":80,"taxonomyType":81,"taxonomyTypeDesc":82},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[84,85],"malformed skill","malformed",{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":93,"publishedAt":39},"01M6MQYZZGBCVGRPEQKM6ZZD97","ignored-skill","Tests .skillignore honoring.","https:\u002F\u002Fgithub.com\u002Fstrvmarv\u002Ftotal-recall\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Fignored-skill\u002FSKILL.md",[92],{"categoryNo":79,"categoryName":80,"taxonomyType":81,"taxonomyTypeDesc":82},[94,95],"ignored skill","tests",{"skillNo":97,"name":98,"nameZh":6,"description":99,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":103,"publishedAt":39},"01M6MQYV98Z2J1WYZP5Q1Z7FQC","bundle-skill","Multi-file bundled skill.","https:\u002F\u002Fgithub.com\u002Fstrvmarv\u002Ftotal-recall\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Fbundle-skill\u002FSKILL.md",[102],{"categoryNo":79,"categoryName":80,"taxonomyType":81,"taxonomyTypeDesc":82},[104,105,106,107,108,109],"bundle","bundle skill","file","brainstorm","testing","multi",{"skillNo":111,"name":112,"nameZh":6,"description":113,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":114,"categories":115,"keywords":116,"publishedAt":39},"01M6MQYP88VJ6EC560MJQACN4B","using-total-recall","Initialize total-recall memory system and ensure session_start has been called. Use at session start or when memory features aren't working.","https:\u002F\u002Fgithub.com\u002Fstrvmarv\u002Ftotal-recall\u002Fblob\u002Fmain\u002Fskills\u002Fusing-total-recall\u002FSKILL.md",[],[117,20,118,38,119,24,37,120,121,122,23,33,123],"using total recall","session start","initialize","start","features","at","session"]