@strvmarv/total-recall 0.6.8-beta.7 → 0.7.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "total-recall",
   "description": "Multi-tiered memory and knowledge base with semantic search, auto-compaction, and built-in evaluation. Works across Claude Code, Copilot CLI, OpenCode, Cline, and Cursor.",
-  "version": "0.6.8-beta.7",
+  "version": "0.7.1",
   "author": {
     "name": "strvmarv"
   },

package/CONTRIBUTING.md

@@ -271,11 +271,11 @@ npx vitest run src/importers/my-tool.test.ts
 Once the MCP server is running and connected to your coding assistant, use the eval commands:
 
 ```
-/total-recall eval                      # Live retrieval metrics for current session
-/total-recall eval --benchmark          # Run synthetic benchmark suite
-/total-recall eval --snapshot baseline  # Save current config as a named baseline
-/total-recall eval --compare baseline   # Compare current config against saved baseline
-/total-recall eval --grow               # Add real query misses to benchmark suite
+/total-recall:commands eval                      # Live retrieval metrics for current session
+/total-recall:commands eval --benchmark          # Run synthetic benchmark suite
+/total-recall:commands eval --snapshot baseline  # Save current config as a named baseline
+/total-recall:commands eval --compare baseline   # Compare current config against saved baseline
+/total-recall:commands eval --grow               # Add real query misses to benchmark suite
 ```
 
 A PR that changes retrieval logic, scoring, or compaction thresholds must include a `--benchmark` run showing no regression against the `baseline` snapshot.
@@ -289,7 +289,7 @@ Before opening a pull request:
 1. **Tests pass** — `npm test` exits 0 with no failures
 2. **Type checker clean** — `npm run typecheck` exits 0
 3. **Build succeeds** — `npm run build` exits 0
-4. **Benchmark does not regress** — run `/total-recall eval --compare baseline` and include the output in your PR description if you changed retrieval, scoring, or compaction logic
+4. **Benchmark does not regress** — run `/total-recall:commands eval --compare baseline` and include the output in your PR description if you changed retrieval, scoring, or compaction logic
 5. **New behavior is tested** — new importers, parsers, and content types all require corresponding test files
 
 If you're adding a new host tool importer, include the `detect()` logic rationale in your PR description — false positives will silently corrupt imports for users who don't have the tool installed.

package/README.md

@@ -165,44 +165,46 @@ All state lives in `~/.total-recall/total-recall.db`. The embedding model is bun
 
 ## Commands
 
-All commands use `/total-recall <subcommand>`:
+All commands are routed through the `/total-recall:commands` skill:
 
 | Command | MCP Tool | Description |
 |---|---|---|
-| `/total-recall help` | — | Show command reference table |
-| `/total-recall status` | `status` | Dashboard overview |
-| `/total-recall search <query>` | `memory_search` | Semantic search across all tiers |
-| `/total-recall store <content>` | `memory_store` | Manually store a memory |
+| `/total-recall:commands help` | — | Show command reference table |
+| `/total-recall:commands status` | `status` | Dashboard overview |
+| `/total-recall:commands search <query>` | `memory_search` | Semantic search across all tiers |
+| `/total-recall:commands store <content>` | `memory_store` | Manually store a memory |
 | — | `memory_get` | Retrieve a specific entry by ID |
 | — | `memory_update` | Update an existing entry's content, tags, or project |
-| `/total-recall forget <query>` | `memory_search` + `memory_delete` | Find and delete entries |
-| `/total-recall inspect <id>` | `memory_inspect` | Deep dive on single entry with compaction history |
-| `/total-recall promote <id>` | `memory_promote` | Move entry to higher tier |
-| `/total-recall demote <id>` | `memory_demote` | Move entry to lower tier |
-| `/total-recall history` | `memory_history` | Show recent tier movements |
-| `/total-recall lineage <id>` | `memory_lineage` | Show compaction ancestry |
-| `/total-recall export` | `memory_export` | Export to portable JSON format |
-| `/total-recall import <file>` | `memory_import` | Import from export file |
-| `/total-recall ingest <path>` | `kb_ingest_file` / `kb_ingest_dir` | Add files/dirs to knowledge base |
-| `/total-recall kb search <query>` | `kb_search` | Search knowledge base |
-| `/total-recall kb list` | `kb_list_collections` | List KB collections |
-| `/total-recall kb refresh <id>` | `kb_refresh` | Re-ingest a collection |
-| `/total-recall kb remove <id>` | `kb_remove` | Remove KB entry |
+| `/total-recall:commands forget <query>` | `memory_search` + `memory_delete` | Find and delete entries |
+| `/total-recall:commands inspect <id>` | `memory_inspect` | Deep dive on single entry with compaction history |
+| `/total-recall:commands promote <id>` | `memory_promote` | Move entry to higher tier |
+| `/total-recall:commands demote <id>` | `memory_demote` | Move entry to lower tier |
+| `/total-recall:commands history` | `memory_history` | Show recent tier movements |
+| `/total-recall:commands lineage <id>` | `memory_lineage` | Show compaction ancestry |
+| `/total-recall:commands export` | `memory_export` | Export to portable JSON format |
+| `/total-recall:commands import <file>` | `memory_import` | Import from export file |
+| `/total-recall:commands ingest <path>` | `kb_ingest_file` / `kb_ingest_dir` | Add files/dirs to knowledge base |
+| `/total-recall:commands kb search <query>` | `kb_search` | Search knowledge base |
+| `/total-recall:commands kb list` | `kb_list_collections` | List KB collections |
+| `/total-recall:commands kb refresh <id>` | `kb_refresh` | Re-ingest a collection |
+| `/total-recall:commands kb remove <id>` | `kb_remove` | Remove KB entry |
 | — | `kb_summarize` | Generate summary for a KB collection |
-| `/total-recall compact` | `compact_now` | Force compaction |
+| `/total-recall:commands compact` | `compact_now` | Force compaction |
 | — | `session_start` | Initialize session: sync imports, assemble hot tier |
 | — | `session_end` | End session: run compaction |
 | — | `session_context` | Get current hot tier entries as context |
-| `/total-recall eval` | `eval_report` | Retrieval quality metrics (filterable by config snapshot) |
-| `/total-recall eval --benchmark` | `eval_benchmark` | Run synthetic benchmark |
-| `/total-recall eval --compare <name>` | `eval_compare` | Compare metrics between two config snapshots |
-| `/total-recall eval --snapshot <name>` | `eval_snapshot` | Manually create a named config snapshot |
-| `/total-recall eval --grow` | `eval_grow` | Review and accept/reject benchmark candidates from retrieval misses |
-| `/total-recall config get <key>` | `config_get` | Read config value |
-| `/total-recall config set <key> <val>` | `config_set` | Update config |
-| `/total-recall import-host` | `import_host` | Import from host tools |
+| `/total-recall:commands eval` | `eval_report` | Retrieval quality metrics (filterable by config snapshot) |
+| `/total-recall:commands eval --benchmark` | `eval_benchmark` | Run synthetic benchmark |
+| `/total-recall:commands eval --compare <name>` | `eval_compare` | Compare metrics between two config snapshots |
+| `/total-recall:commands eval --snapshot <name>` | `eval_snapshot` | Manually create a named config snapshot |
+| `/total-recall:commands eval --grow` | `eval_grow` | Review and accept/reject benchmark candidates from retrieval misses |
+| `/total-recall:commands config get <key>` | `config_get` | Read config value |
+| `/total-recall:commands config set <key> <val>` | `config_set` | Update config |
+| `/total-recall:commands import-host` | `import_host` | Import from host tools |
 
-Memory capture, retrieval, and compaction run automatically in the background — see the "Automatic Behavior" section of the `/total-recall` skill.
+Memory capture, retrieval, and compaction run automatically in the background — see the "Automatic Behavior" section of the `/total-recall:commands` skill.
+
+> **Note:** `/total-recall:commands` is implemented as a Claude Code skill (at `skills/commands/SKILL.md`), not as a slash-command file under `commands/`. The skill handles all `<subcommand>` arguments internally.
 
 ---
 
@@ -214,7 +216,7 @@ Memory capture, retrieval, and compaction run automatically in the background
 | Copilot CLI | Full | Auto-import from existing Copilot memory files |
 | OpenCode | MCP | Configure MCP server in opencode config |
 | Cline | MCP | Configure MCP server in Cline settings |
-| Cursor | Full | MCP server + `.cursor-plugin/` wrapper |
+| Cursor | Full | MCP server + `.cursor-plugin/` wrapper (SessionStart only; run `/total-recall:commands compact` manually — Cursor has no SessionEnd hook) |
 | Hermes | Full | Auto-import from Hermes memory files |
 
 ---

package/hooks/hooks-cursor.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/session-start/run.sh\"",
+            "command": "bash \"$CURSOR_PLUGIN_ROOT/hooks/session-start/run.sh\"",
             "async": false
           }
         ]

package/hooks/session-end/run.sh

@@ -1,9 +1,31 @@
 #!/usr/bin/env bash
 # total-recall SessionEnd hook
-# Triggers compaction and session cleanup via MCP tools
+# Injects the session-end directive fragment as additionalContext.
+#
+# The directive lives in skills/commands/session-end.md so it stays
+# in one place — the same file can be referenced by the SKILL.md and is
+# not duplicated in this shell script. If the fragment is missing we
+# exit 0 silently rather than blocking session end.
+#
+# Payload is plain text (no <IMPORTANT>/XML wrappers) — it is already
+# injected inside a system-reminder block by the host, and nested markup
+# is redundant / inconsistently handled across hosts. Tool references in
+# the fragment use functional names (e.g. "session_context MCP tool")
+# instead of hardcoded mcp__ prefixes, because each host namespaces
+# plugin MCP tools differently.
 
 set -euo pipefail
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+FRAGMENT_FILE="$PLUGIN_ROOT/skills/commands/session-end.md"
+
+if [ ! -f "$FRAGMENT_FILE" ]; then
+  exit 0
+fi
+
+FRAGMENT_CONTENT=$(cat "$FRAGMENT_FILE")
+
 # Escape string for JSON embedding using bash parameter substitution
 escape_for_json() {
     local s="$1"
@@ -15,9 +37,14 @@ escape_for_json() {
     printf '%s' "$s"
 }
 
-session_context="<IMPORTANT>\n**IMMEDIATE ACTION REQUIRED — SESSION ENDING:**\n\n1. Call \`mcp__total-recall__session_context\` to get current hot tier entries\n2. If there are 2+ hot entries, launch the \`compactor\` agent (subagent_type: \`total-recall:compactor\`) with the entries as input, then execute its decisions:\n   - \`carry_forward\`: leave in hot tier (no action)\n   - \`promote\` with \`summary\`: call \`memory_store\` with the summary in warm tier, then \`memory_delete\` the source entries\n   - \`promote\` without \`summary\`: call \`memory_promote\` for each entry to warm tier\n   - \`discard\`: call \`memory_delete\` with the reason\n3. Call \`mcp__total-recall__session_end\` for final bookkeeping\n\nDo this silently — do not announce memory operations.\n</IMPORTANT>"
+session_context=$(escape_for_json "$FRAGMENT_CONTENT")
 
-# Platform-aware JSON output
+# Platform-aware JSON output:
+# - Cursor: additional_context (snake_case) — note: Cursor 1.7 has no
+#   SessionEnd hook, so this branch is unreachable today but kept for
+#   forward compatibility
+# - Claude Code: hookSpecificOutput.additionalContext (nested)
+# - Copilot CLI / others: additionalContext (top-level, SDK standard)
 if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
   printf '{\n  "additional_context": "%s"\n}\n' "$session_context"
 elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then

package/hooks/session-start/run.sh

@@ -6,7 +6,7 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PLUGIN_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-SKILL_FILE="$PLUGIN_ROOT/skills/total-recall/SKILL.md"
+SKILL_FILE="$PLUGIN_ROOT/skills/commands/SKILL.md"
 
 if [ ! -f "$SKILL_FILE" ]; then
   exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strvmarv/total-recall",
-  "version": "0.6.8-beta.7",
+  "version": "0.7.1",
   "description": "Multi-tiered memory and knowledge base plugin for TUI coding assistants",
   "type": "module",
   "main": "dist/index.js",

package/skills/{total-recall → commands}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: total-recall
-description: Manage total-recall memory system. Subcommands: help, status, search, store, forget, inspect, promote, demote, history, lineage, export, import, ingest, kb, compact, eval, config. Also governs automatic memory capture, retrieval, and compaction.
+name: 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 `mcp__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.**
+**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.**
 
 # total-recall
 
@@ -46,14 +46,7 @@ On each user message that is a question or task request:
 
 ### Session End
 
-1. Call `session_context` to get current hot tier entries
-2. If there are 2+ hot entries, launch the `compactor` agent with the entries as input
-3. Parse the agent's JSON decisions and execute them:
-   - `carry_forward`: leave in hot tier (no action needed)
-   - `promote` with `summary`: call `memory_store` with the summary in warm tier, then `memory_delete` the source entries
-   - `promote` without `summary`: call `memory_promote` for each entry to warm tier
-   - `discard`: call `memory_delete` with the reason
-4. Call `session_end` for final bookkeeping
+At session end, follow the directive in [`session-end.md`](session-end.md) — it is the single source of truth, injected verbatim by the SessionEnd hook (`hooks/session-end/run.sh`).
 
 ### Rules
 
@@ -66,7 +59,7 @@ On each user message that is a question or task request:
 
 ## Commands
 
-`/total-recall <subcommand> [args]`
+`/total-recall:commands <subcommand> [args]`
 
 ### help
 
@@ -106,7 +99,7 @@ Call the `status` MCP tool. Format as a dashboard showing:
 
 ### search <query>
 
-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 promote <id>` or `/total-recall forget <id>`.
+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 <content>
 

package/skills/commands/session-end.md

@@ -0,0 +1,11 @@
+**IMMEDIATE ACTION REQUIRED — SESSION ENDING:**
+
+1. Call the total-recall `session_context` MCP tool to get current hot tier entries
+2. If there are 2+ hot entries, launch the `total-recall:compactor` agent with the entries as input, then execute its decisions:
+   - `carry_forward`: leave in hot tier (no action)
+   - `promote` with `summary`: call `memory_store` with the summary in warm tier, then `memory_delete` the source entries
+   - `promote` without `summary`: call `memory_promote` for each entry to warm tier
+   - `discard`: call `memory_delete` with the reason
+3. Call the total-recall `session_end` MCP tool for final bookkeeping
+
+Do this silently — do not announce memory operations.

package/skills/using-total-recall/SKILL.md

@@ -9,7 +9,7 @@ This skill ensures the total-recall memory system is active for this session.
 
 ## Immediate Action
 
-1. Call the `mcp__total-recall__session_start` MCP tool now (if it already ran server-side, it returns cached results instantly)
+1. Call the total-recall `session_start` MCP tool now (if it already ran server-side, it returns cached results instantly)
 2. **Announce startup** using the returned data:
    - Report tier summary: hot, warm, cold, KB counts from `tierSummary`
    - If `lastSessionAge` is present, mention when the last session was
@@ -56,7 +56,7 @@ On each user message that is a question or task request:
 ### Session End
 
 1. Call `session_context` to get current hot tier entries
-2. If there are 2+ hot entries, launch the `compactor` agent with the entries as input
+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