feat(mem0-plugin): plugin v0.2.1 — Tiers 1-8 + PostHog telemetry + review fixes (#5215)

2026-05-22 19:01:14 +05:30
parent 58696e4bd4
commit 0d61af60c2
58 changed files with 5293 additions and 172 deletions
@@ -0,0 +1,123 @@
+---
+name: mem0-digest
+description: >
+  Summarize recent memory activity for the current project. Shows new memories,
+  categories touched, and growth trends over the past 7 days.
+  TRIGGER: user runs /mem0:digest, or asks "weekly summary", "what's new in memory",
+  "mem0 digest", "memory recap".
+---
+
+# Mem0 Weekly Digest
+
+Summarize recent memory activity for the current project.
+
+## Execution
+
+### Step 1: Fetch recent memories
+
+Call `search_memories` in parallel with different time-scoped queries:
+
+1. `query="decisions made this week"`, `filters={"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}, {"created_at": {"gte": "<7 days ago YYYY-MM-DD>"}}]}`, `limit=20`
+2. `query="bugs errors fixes"`, same time filter, `limit=20`
+3. `query="patterns conventions learnings"`, same time filter, `limit=20`
+
+Also call `get_memories` with `user_id` + `app_id` to get the full count for comparison.
+
+### Step 2: Deduplicate and analyze
+
+Merge results by memory ID. For each memory, extract:
+- `created_at` date
+- `categories[0]` or `metadata.type`
+- First 100 chars of content
+
+Group into:
+- **New this week** (created in last 7 days)
+- **Older** (created before, but surfaced by search)
+
+Calculate:
+- Total memories in project
+- Memories added in last 7 days
+- Most active categories this week
+- Days with most activity
+
+### Step 3: Display
+
+```
+## mem0 Weekly Digest — <project_id>
+Period: <start_date> to <today>
+
+### New Memories This Week: <N>
+<category>: <count>
+  - <memory summary, 80 chars> (<date>)
+  - ...
+<category>: <count>
+  - ...
+
+### Activity Pattern
+Most active day: <day> (<N> memories)
+Categories touched: <list>
+
+### Project Totals
+Total memories: <N> (up <N> from last week)
+Top categories: <top 3 by count>
+
+### Highlights
+<2-3 sentence summary of the most important decisions, learnings, or patterns stored this week>
+```
+
+### Step 4: Write digest to file
+
+After displaying, write the digest to `~/.mem0/weekly-digest.md` for persistence
+and external consumption (email, Slack, etc.):
+
+```bash
+mkdir -p ~/.mem0
+```
+
+Write the full digest output (same markdown shown in terminal) to `~/.mem0/weekly-digest.md`
+using the Write tool. **Overwrite** the file each time — it always contains the latest digest.
+
+Also append a one-line summary to `~/.mem0/digest-history.log` for trend tracking:
+
+```bash
+echo "<YYYY-MM-DD> | <project_id> | +<new_count> memories | top: <top_category>" >> ~/.mem0/digest-history.log
+```
+
+Print at the end:
+```
+Digest saved to ~/.mem0/weekly-digest.md
+```
+
+### Step 5: Schedule recurring digests
+
+When invoked with `--schedule` (e.g., `/mem0:digest --schedule weekly`), register
+a cloud routine via Claude Code's `/schedule` command:
+
+```
+/schedule <frequency> /mem0:digest
+```
+
+For example:
+- `/schedule weekly on Monday 9am /mem0:digest` — digest every Monday morning
+- `/schedule daily at 8am /mem0:digest` — daily digest
+
+Print:
+```
+Digest scheduled: <frequency>
+Manage at: https://claude.ai/code/routines
+```
+
+If `/schedule` is unavailable, print a cron one-liner the user can install manually:
+```bash
+# macOS/Linux — weekly Monday 9am
+(crontab -l 2>/dev/null; echo "0 9 * * 1 cd PROJECT_DIR && claude -p '/mem0:digest' >> /tmp/mem0-digest.log 2>&1") | crontab -
+```
+
+### Step 6: Empty state
+
+If no memories in the last 7 days:
+```
+No new memories in the past week for <project_id>.
+Total project memories: <N>.
+Tip: mem0 captures learnings automatically as you work. Start coding!
+```
@@ -0,0 +1,344 @@
+---
+name: mem0-dream
+description: >
+  Memory consolidation pass. Fetches all project memories, finds near-duplicates,
+  merges them, flags contradictions, prunes stale entries per retention policy.
+  Outputs a diff for user approval before applying changes.
+  TRIGGER: user runs /mem0:dream, or asks "consolidate memories", "clean up memories",
+  "merge duplicate memories", "run dream".
+---
+
+# Mem0 Dream — Memory Consolidation
+
+This skill performs a memory consolidation pass: it fetches all project memories,
+identifies near-duplicates, flags contradictions, and prunes stale entries based on
+configured retention policies. All proposed changes are shown as a diff for user
+approval before anything is modified.
+
+---
+
+## Step 1: Load Retention Policies
+
+Determine the active retention policy by running the parser script. Use the
+appropriate `PLUGIN_ROOT` variable for the current platform (`${CLAUDE_PLUGIN_ROOT}`,
+`${CODEX_PLUGIN_ROOT}`, or `${CURSOR_PLUGIN_ROOT}`):
+
+```bash
+python3 "<PLUGIN_ROOT>/scripts/parse_mem0_config.py" "<cwd>"
+```
+
+Parse the JSON output (a dict of `category → days | null`). If the script fails
+or returns `{}`, fall back to these built-in defaults:
+
+| `metadata.type` | Default retention |
+|---|---|
+| `session_state` | 90 days |
+| `compact_summary` | 90 days |
+| all others | no pruning |
+
+Store the resolved policies for use in Step 3.
+
+---
+
+## Step 2: Fetch ALL Project Memories
+
+Call `get_memories` to retrieve every memory for the active project:
+
+```python
+get_memories(
+    user_id="<active_user_id>",
+    app_id="<active_project_id>",
+    page_size=200,
+)
+```
+
+If the response indicates more pages exist, paginate until all memories are fetched.
+Collect the full list before proceeding. If zero memories are found, print:
+
+```
+No memories found for project <project_id>. Nothing to consolidate.
+```
+
+…and stop.
+
+---
+
+## Step 3: Analyze — Find Issues
+
+Work entirely in-memory; do not modify anything yet.
+
+Group memories by `metadata.type` (use `"unknown"` when the field is absent).
+For each group, identify the following:
+
+### 3a. Near-duplicate pairs (merge candidates)
+
+Two memories are near-duplicates when they express the same fact or decision but
+phrased differently (e.g., "Use PostgreSQL for auth" and "Auth DB is PostgreSQL").
+
+Heuristics — two memories are near-duplicates if **all** of these hold:
+- Similarity threshold: estimated cosine similarity > 0.9 (use noun/keyword overlap as proxy — if >60% of significant nouns overlap, treat as >0.9 similarity).
+- Same `metadata.type`.
+- Neither memory is pinned (`metadata.pinned != true`).
+
+For each qualifying pair, draft a merged version that is more complete and specific
+than either original.
+
+### 3b. Contradictions
+
+Two memories contradict when they assert opposing facts about the same topic
+(e.g., "Deploy to ECS" vs. "Deploy to Vercel").
+
+Identify the likely winner: the more recent memory with higher confidence wins.
+Store both IDs and their content for user review.
+
+### 3c. Prune candidates
+
+A memory is a prune candidate when **any** of the following is true:
+
+1. Its `metadata.type` has a retention policy and the memory is older than the
+   configured number of days (compare `created_at` to today).
+2. Its confidence score is below 0.3 AND it contains no information unique to
+   this project (no file paths, identifiers, or domain-specific nouns).
+
+**Always skip memories where `metadata.pinned == true`**, regardless of age or
+confidence.
+
+---
+
+## Step 4: Print Diff Report (item 15)
+
+Print a structured diff to the terminal before making any changes. Use exactly
+this format:
+
+```
+## Dream — Memory Consolidation Report
+
+### Merge proposals (<N> pairs)
+MERGE [mem0:<id1>] + [mem0:<id2>] → NEW
+  - Original 1: "<content of memory 1, truncated to 120 chars>"
+  - Original 2: "<content of memory 2, truncated to 120 chars>"
+  - Merged:     "<drafted merged content>"
+
+### Contradictions (<N> pairs)
+CONFLICT [mem0:<idA>] vs [mem0:<idB>]
+  - A: "<content>" (<created_at date>, confidence: <score>)
+  - B: "<content>" (<created_at date>, confidence: <score>)
+  Which is current? [A/B/skip]
+
+### Prune candidates (<N> memories)
+PRUNE [mem0:<id>] — <metadata.type>, <age>d old (policy: <policy_days>d)
+
+---
+Proposed: <N> merges, <N> prunes, <N> conflicts
+Apply? [Y/n]
+```
+
+If there are zero items in any category, omit that section entirely.
+
+If there are zero total proposals (no merges, no prunes, no conflicts), print:
+
+```
+Dream complete. No duplicate, contradictory, or stale memories found.
+```
+
+…and stop.
+
+---
+
+## Step 5: Wait for User Input and Apply
+
+### 5a. Contradictions
+
+For each `CONFLICT` pair in the report, wait for the user to type `A`, `B`, or
+`skip` (case-insensitive). If they enter nothing (empty), treat as `skip`.
+
+Record the winner for each pair before proceeding to the final apply confirmation.
+
+### 5b. Final confirmation
+
+After all conflict resolutions are collected, prompt:
+
+```
+Apply? [Y/n]
+```
+
+If the user types `n` or `no` (case-insensitive), print `Cancelled. No changes made.`
+and stop.
+
+If the user confirms (`Y`, `yes`, or empty / Enter), apply all changes in this order:
+
+#### Merges
+
+For each approved merge pair:
+1. `delete_memory(<id1>)`
+2. `delete_memory(<id2>)`
+3. `add_memory` with:
+   - `messages=[{"role": "user", "content": "<merged content>"}]`
+   - `user_id=<active_user_id>`
+   - `app_id=<active_project_id>` (top-level, not in metadata)
+   - `metadata={"type": "<original type>", "branch": "<active_branch>", "confidence": <higher of the two original scores>, "source": "mem0-dream"}`
+   - `infer=False`
+
+#### Contradictions (resolved)
+
+For each resolved conflict where the user chose A or B:
+- Identify the loser (the non-chosen memory).
+- First call `get_memory(<loser_id>)` to read its current text content.
+- Then call `update_memory(<loser_id>, data=<original_text_content>)` to preserve the text while updating it.
+- **Important:** `update_memory` requires the `data` (text) parameter. A metadata-only call may error or wipe the content. Always read first, then update with the original text.
+
+Contradictions where the user chose `skip` are left untouched.
+
+#### Prunes
+
+For each prune candidate:
+- `delete_memory(<memory_id>)`
+
+---
+
+## Step 6: Print Summary
+
+After all changes are applied, print:
+
+```
+Dream complete.
+  Merged:  <N> pairs → <N> new memories
+  Pruned:  <N> memories deleted
+  Flagged: <N> contradictions resolved, <N> skipped
+```
+
+---
+
+## Auto mode
+
+When invoked with `--auto` (e.g., `/mem0:dream --auto`), run non-interactively:
+
+- **Merges**: applied automatically (no contradiction, both are compatible).
+- **Prunes**: applied automatically (age/confidence-based, no ambiguity).
+- **Contradictions**: skipped — they require human judgment.
+
+In auto mode:
+1. Load policies and fetch memories (Steps 1–3) as normal.
+2. Apply merges and prunes silently without printing the diff or prompting.
+3. Print a compact summary:
+   ```
+   [mem0-dream --auto] project=<id>  merged=<N>  pruned=<N>  conflicts_skipped=<N>
+   ```
+4. If contradictions were detected but skipped, store a reminder memory:
+   ```python
+   add_memory(
+       messages=[{"role": "user", "content": "mem0-dream detected <N> contradiction(s) requiring manual review. Run /mem0:dream to resolve them interactively."}],
+       user_id="<active_user_id>",
+       app_id="<active_project_id>",
+       metadata={"type": "task_learning", "source": "mem0-dream-auto", "branch": "<active_branch>"},
+       infer=False,
+   )
+   ```
+
+## Scheduling recurring dreams
+
+When invoked with `--schedule` (e.g., `/mem0:dream --schedule weekly`), register a
+cloud routine via Claude Code's built-in `/schedule` command so the dream runs
+automatically without any local cron or launchd setup.
+
+### Step S1: Parse schedule frequency
+
+Accept natural-language frequency after `--schedule`:
+
+| User input | Cron equivalent | Description |
+|---|---|---|
+| `weekly` or `--schedule weekly` | Every Sunday 3:00 AM local | Default weekly consolidation |
+| `daily` | Every day 3:00 AM local | For high-volume projects |
+| `biweekly` | Every other Sunday 3:00 AM local | Lower frequency option |
+| Custom (e.g., `"every Monday 9am"`) | Pass verbatim to `/schedule` | Let Claude Code resolve it |
+
+### Step S2: Create the routine
+
+Use Claude Code's `/schedule` command to create a cloud routine. The routine runs
+`/mem0:dream --auto` on the specified schedule against the current repository:
+
+```
+/schedule <frequency> /mem0:dream --auto
+```
+
+For example:
+- `/schedule weekly /mem0:dream --auto` — runs every week
+- `/schedule daily at 3am /mem0:dream --auto` — runs every day at 3 AM
+- `/schedule every Monday 9am /mem0:dream --auto` — runs every Monday at 9 AM
+
+The `/schedule` command handles all the cloud infrastructure: repository cloning,
+environment setup, and cron scheduling. The routine runs as a full Claude Code
+cloud session with access to the mem0 MCP tools.
+
+### Step S3: Confirm to user
+
+After the routine is created, print:
+
+```
+Dream scheduled: <frequency>
+Routine name: mem0-dream-<project_id>
+Next run: <next scheduled time>
+
+Manage at: https://claude.ai/code/routines
+Edit: /schedule list → /schedule update
+Cancel: /schedule list → delete the routine
+```
+
+### Managing scheduled dreams
+
+| Action | Command |
+|---|---|
+| List all routines | `/schedule list` |
+| Run dream now | `/schedule run` (select the dream routine) |
+| Change frequency | `/schedule update` (select the dream routine) |
+| Pause | Toggle off at claude.ai/code/routines |
+| Delete | Delete at claude.ai/code/routines or `/schedule update` |
+
+### Fallback for non-cloud users
+
+If `/schedule` is unavailable (API key auth, no claude.ai subscription), fall back
+to local options:
+
+1. **macOS launchd plist** — generate and install:
+   ```bash
+   cat > ~/Library/LaunchAgents/com.mem0.dream.plist << 'PLIST'
+   <?xml version="1.0" encoding="UTF-8"?>
+   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+   <plist version="1.0">
+   <dict>
+     <key>Label</key><string>com.mem0.dream</string>
+     <key>ProgramArguments</key>
+     <array>
+       <string>claude</string>
+       <string>-p</string>
+       <string>/mem0:dream --auto</string>
+       <string>--allowedTools</string>
+       <string>mcp__mem0__*</string>
+     </array>
+     <key>StartCalendarInterval</key>
+     <dict>
+       <key>Weekday</key><integer>0</integer>
+       <key>Hour</key><integer>3</integer>
+       <key>Minute</key><integer>0</integer>
+     </dict>
+     <key>StandardOutPath</key><string>/tmp/mem0-dream.log</string>
+     <key>StandardErrorPath</key><string>/tmp/mem0-dream.err</string>
+     <key>WorkingDirectory</key><string>PROJECT_DIR</string>
+   </dict>
+   </plist>
+   PLIST
+   launchctl load ~/Library/LaunchAgents/com.mem0.dream.plist
+   ```
+   Replace `PROJECT_DIR` with the actual project path.
+
+2. **Linux cron** — add entry:
+   ```bash
+   (crontab -l 2>/dev/null; echo "0 3 * * 0 cd PROJECT_DIR && claude -p '/mem0:dream --auto' >> /tmp/mem0-dream.log 2>&1") | crontab -
+   ```
+
+Print which method was used and how to verify:
+```
+Dream scheduled (local: launchd/cron): weekly Sundays 3am
+Verify: launchctl list | grep mem0   # macOS
+        crontab -l | grep mem0       # Linux
+```
@@ -0,0 +1,81 @@
+---
+name: mem0-export
+description: >
+  Export all memories for the current project to a local Markdown file.
+  Each memory is written as a YAML-frontmatter block that can be re-imported later.
+  TRIGGER: user runs /mem0:export, or asks "export memories", "backup memories",
+  "download my memories", "save memories to file".
+---
+
+# Mem0 Export
+
+Export all memories for the current project to a portable Markdown file.
+
+## Execution
+
+### Step 1: Resolve identity
+
+Determine the active identity:
+- `user_id` from `MEM0_USER_ID` env var, else `$USER`, else `"default"`
+- `project_id` (used as `app_id`) from `MEM0_PROJECT_ID` env var, or via the project resolver
+
+### Step 2: Fetch all memories
+
+Call `get_memories` with:
+- `user_id=<active_user_id>`
+- `app_id=<active_project_id>`
+- `page_size=200`
+
+If the response is paginated (i.e. the result contains a `next` cursor or the count equals `page_size`), continue fetching pages until all memories are retrieved.
+
+### Step 3: Format each memory as a YAML-frontmatter block
+
+For each memory record, produce a block in this exact format:
+
+```
+---
+id: <memory.id>
+created_at: <memory.created_at>
+type: <memory.metadata.type or "">
+confidence: <memory.metadata.confidence or "">
+branch: <memory.metadata.branch or "">
+files: <memory.metadata.files joined with ", " or "">
+categories: <memory.categories joined with ", " or "">
+---
+<memory.memory or memory content string>
+
+```
+
+Notes:
+- The `---` delimiters must be on their own lines with no extra whitespace.
+- `files` and `categories` are written as comma-separated values on a single line.
+- Leave a blank line after the content before the next `---` (for readability).
+- If a field is missing or null, write an empty string (not "null").
+
+### Step 4: Write the export file
+
+Determine the output filename:
+
+```
+mem0-export-<project_id>-<YYYY-MM-DD>.md
+```
+
+Where `<YYYY-MM-DD>` is today's date in UTC.
+
+Write all formatted blocks to this file using the Write tool (or equivalent). The file is written to the current working directory.
+
+### Step 5: Print summary
+
+```
+Exported <N> memories to <filename>
+```
+
+Where `<N>` is the total number of memory blocks written.
+
+## Error Handling
+
+- If `get_memories` returns an error or zero memories, print:
+  ```
+  No memories found for project <project_id>. Nothing exported.
+  ```
+- If the write fails, report the error to the user.
@@ -0,0 +1,76 @@
+---
+name: mem0-forget
+description: >
+  Delete memories by search query or memory ID. Shows matches for confirmation
+  before deleting. Safe — always confirms before destructive action.
+  TRIGGER: user runs /mem0:forget <query>, or says "forget this", "delete memory",
+  "remove that memory about X".
+---
+
+# Mem0 Forget
+
+Delete specific memories from mem0.
+
+## Execution
+
+### Step 1: Parse input
+
+The user provides either:
+- A search query: `/mem0:forget auth module decisions`
+- A memory ID: `/mem0:forget <memory_id>`
+
+If no argument, ask: "What should I forget? Provide a search query or memory ID."
+
+### Step 2: Find memories
+
+**If memory ID provided** (looks like a UUID or hex string):
+- Call `get_memory` with the ID to verify it exists.
+- Show: `Found: "<memory content first 120 chars>" (created <date>)`
+
+**If search query provided:**
+- Call `search_memories` with:
+  - `query=<user's query>`
+  - `user_id=<active_user_id>`
+  - `filters={"AND": [{"user_id": "<id>"}, {"app_id": "<project_id>"}]}`
+  - `limit=10`
+- Show numbered list:
+  ```
+  Found <N> memories matching "<query>":
+  1. <content, 120 chars> (type: <type>, created: <date>) [ID: <short_id>]
+  2. ...
+  ```
+
+### Step 3: Confirm
+
+Ask: "Delete which memories? Enter numbers (e.g., 1,3,5), 'all', or 'cancel'."
+
+For a single memory ID, ask: "Delete this memory? [y/N]"
+
+**Never delete without confirmation.** This is destructive.
+
+### Step 4: Delete
+
+For each confirmed memory, call `delete_memory` with the memory ID.
+
+### Step 5: Report
+
+```
+Deleted <N> memories.
+```
+
+If any deletions failed, report which ones and why.
+
+## Undo recent writes
+
+If the user says "undo last N memories" or "undo last write":
+
+1. Read session stats to get recently written memory IDs:
+   ```bash
+   SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}}/scripts"
+   python3 "$SCRIPT_DIR/session_stats.py" peek
+   ```
+2. Parse the `recent_ids` array from the JSON output. Each entry has `id`, `category`, `ts`.
+3. Show the last N entries (default 1) and ask for confirmation.
+4. Delete confirmed entries via `delete_memory`.
+
+If `recent_ids` is empty, tell the user: "No recent memory IDs tracked this session. Use a search query instead."
@@ -0,0 +1,171 @@
+---
+name: mem0-health
+description: >
+  Diagnostic health check for the mem0 plugin. Verifies API key, MCP server
+  connectivity, identity resolution, and memory read/write capability.
+  TRIGGER: user runs /mem0:health, or asks "is mem0 working", "mem0 health",
+  "check mem0 connection", "debug mem0".
+---
+
+# Mem0 Health Check
+
+Run a diagnostic check on the mem0 plugin. Useful for troubleshooting.
+
+## Execution
+
+Run ALL checks, then display a single summary. Do not stop on the first failure.
+
+### Check 1: API key
+
+```bash
+echo "${MEM0_API_KEY:-${CLAUDE_PLUGIN_OPTION_MEM0_API_KEY:-NOT_SET}}"
+```
+
+- If `NOT_SET`: FAIL — "No API key configured"
+- If set: PASS — show first 6 chars + `...` (never print the full key)
+
+### Check 2: Identity resolution
+
+Read the active identity from the SessionStart banner or resolve manually:
+- `user_id`: from `MEM0_RESOLVED_USER_ID` or `$USER`
+- `project_id`: from `MEM0_PROJECT_ID` or current directory name
+- `branch`: from `MEM0_BRANCH` or `git rev-parse --abbrev-ref HEAD`
+
+PASS if all three are non-empty. WARN if any falls back to defaults.
+
+### Check 3: MCP server connectivity
+
+Call `search_memories` with:
+- `query="health check"`, `user_id=<id>`, `limit=1`
+- `filters={"AND": [{"user_id": "<id>"}, {"app_id": "<project_id>"}]}`
+
+- If returns successfully (even empty): PASS
+- If errors: FAIL — show the error message
+
+### Check 4: Memory write capability
+
+Call `add_memory` with:
+- `messages=[{"role": "user", "content": "Health check probe — safe to delete."}]`
+- `user_id=<id>`, `app_id=<project_id>`
+- `metadata={"type": "health_check", "probe": true}`
+
+If it returns a memory ID: PASS — then immediately call `delete_memory` with that ID to clean up.
+If it errors: FAIL — show the error.
+
+### Check 5: Session stats tracker
+
+Check if the session stats file exists and is readable:
+
+```bash
+STATS_FILE="/tmp/mem0_session_stats_${USER}.json"
+if [ -f "$STATS_FILE" ] && python3 -c "import json; json.load(open('$STATS_FILE'))" 2>/dev/null; then
+  echo "OK"
+else
+  echo "FAIL"
+fi
+```
+
+This file is created by the SessionStart hook and updated by PostToolUse hooks throughout the session. If it doesn't exist, the session hooks may not have fired yet — try sending a message first, then recheck.
+
+### Display
+
+```
+## mem0 Health Check
+
+| Check              | Status | Detail                        |
+|--------------------|--------|-------------------------------|
+| API Key            | PASS   | m0-dVe...                     |
+| Identity           | PASS   | user=kartik, project=mem0     |
+| MCP Connectivity   | PASS   | 142ms round-trip              |
+| Memory Write/Read  | PASS   | write + delete OK             |
+| Session Tracker    | PASS   | stats file active             |
+
+All checks passed. mem0 is healthy.
+```
+
+If any check fails, add a `## Troubleshooting` section with specific fix steps for each failure.
+
+## Extended mode: Memory Quality Analysis
+
+When invoked with `--deep` (e.g., `/mem0:health --deep`) or `--fix` (e.g., `/mem0:health --fix`), run the standard 5 checks above **plus** a memory quality scan.
+
+`--fix` implies `--deep` and automatically applies safe fixes after showing the analysis (see bottom of this section).
+
+### Quality Check 1: Duplicates
+
+Call `get_memories` with `user_id`, `app_id`, `page_size=200`. Compare all pairs within the same `metadata.type` group for high textual overlap (shared nouns/keywords > 60%). Report:
+
+```
+Potential duplicates: <N> pairs
+  [mem0:<id1>] ≈ [mem0:<id2>] — both about "<shared topic>"
+```
+
+### Quality Check 2: Stale memories
+
+Flag memories where:
+- `metadata.type` is `session_state` or `compact_summary` AND older than 90 days
+- `metadata.confidence` < 0.3 AND older than 30 days
+
+```
+Stale candidates: <N>
+  [mem0:<id>] — session_state, 142d old
+```
+
+### Quality Check 2b: Low-confidence memories
+
+Flag memories where `metadata.confidence` < 0.5 (regardless of age). Report separately from stale:
+
+```
+Low-confidence memories: <N>
+  [mem0:<id>] — confidence=0.3, "<content preview>"
+```
+
+### Quality Check 3: Contradictions
+
+Within each `metadata.type` group, flag pairs that assert opposing facts about the same topic. Use semantic judgment — look for negation patterns, conflicting tool/framework choices, or reversed decisions.
+
+```
+Possible contradictions: <N>
+  [mem0:<idA>] vs [mem0:<idB>] — conflicting on "<topic>"
+```
+
+### Quality Check 4: Orphan memories
+
+Memories with no `metadata.type` set, or with `metadata.type` not in the 17 known coding categories. These were likely written without proper tagging.
+
+```
+Untagged/orphan memories: <N>
+```
+
+### Quality summary
+
+```
+## Memory Quality
+| Metric         | Count | Action                          |
+|----------------|-------|---------------------------------|
+| Duplicates     | <N>   | Run /mem0:dream to merge        |
+| Stale          | <N>   | Run /mem0:dream to prune        |
+| Contradictions | <N>   | Run /mem0:dream to resolve      |
+| Orphans        | <N>   | Consider retagging via MCP      |
+```
+
+If all counts are 0: `Memory quality: clean. No duplicates, stale entries, or contradictions found.`
+
+### Auto-fix mode (`--fix`)
+
+When `--fix` is passed, apply these safe fixes automatically after displaying the quality summary:
+
+1. **Orphans:** For each untagged memory, infer a `metadata.type` from content and call `update_memory` to set it. If inference is uncertain, skip.
+2. **Stale `session_state`/`compact_summary` > 90d:** Delete them via `delete_memory`. These are ephemeral by design.
+3. **Duplicates:** Do NOT auto-merge — print "Run `/mem0:dream` to merge duplicates" instead.
+4. **Contradictions:** Do NOT auto-resolve — print "Run `/mem0:dream` to resolve contradictions" instead.
+5. **Low-confidence < 0.3 AND > 30d old:** Delete them via `delete_memory`.
+
+Print a summary of actions taken:
+
+```
+## Auto-fix Results
+  Deleted: <N> stale, <N> low-confidence
+  Retagged: <N> orphans
+  Skipped: <N> duplicates (use /mem0:dream), <N> contradictions (use /mem0:dream)
+```
@@ -0,0 +1,106 @@
+---
+name: mem0-import-tools
+description: >
+  Import memories from competing AI tool configuration files into mem0.
+  Supports Cursor (.cursorrules), GitHub Copilot (.github/copilot-instructions.md),
+  Cline (memory-bank/), and Continue (.continue/rules.md).
+  TRIGGER: user runs /mem0:import-tools, or asks "import from cursor",
+  "import cursorrules", "import from cline", "import from copilot",
+  "import from continue", "migrate from cursor", "migrate memories".
+---
+
+# Mem0 Import from Competing Tools
+
+Import configuration and memory files from other AI coding tools into mem0.
+
+## Supported Tools
+
+| Tool | Default file/directory |
+|------|----------------------|
+| Cursor | `.cursorrules` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+| Cline | `memory-bank/` (directory of `.md` files) |
+| Continue | `.continue/rules.md` |
+
+## Execution
+
+### Step 1: Detect which tool files exist
+
+Check for the presence of each tool's file/directory in the current working directory:
+
+```bash
+# Check each location
+test -f .cursorrules && echo "cursor: .cursorrules"
+test -f .github/copilot-instructions.md && echo "copilot: .github/copilot-instructions.md"
+test -d memory-bank/ && echo "cline: memory-bank/"
+test -f .continue/rules.md && echo "continue: .continue/rules.md"
+```
+
+### Step 2: Report findings and ask user
+
+List all found files to the user. For example:
+
+```
+Found the following tool configuration files:
+  [1] Cursor rules: .cursorrules
+  [2] Cline memory bank: memory-bank/
+
+Which would you like to import? (enter numbers, comma-separated, or "all"):
+```
+
+If no files are found, print:
+```
+No competing tool configuration files found in the current directory.
+Checked: .cursorrules, .github/copilot-instructions.md, memory-bank/, .continue/rules.md
+```
+and stop.
+
+### Step 3: Run the import script for each selected tool
+
+Determine the plugin root. Use the appropriate variable for the current platform:
+- Claude Code: `${CLAUDE_PLUGIN_ROOT}`
+- Codex: `${CODEX_PLUGIN_ROOT}`
+- Cursor: `${CURSOR_PLUGIN_ROOT}`
+
+For each tool the user selected, run the corresponding sub-command:
+
+**Cursor (.cursorrules):**
+```bash
+python3 "<PLUGIN_ROOT>/scripts/import_competing_tools.py" cursorrules --path .cursorrules
+```
+
+**GitHub Copilot:**
+```bash
+python3 "<PLUGIN_ROOT>/scripts/import_competing_tools.py" copilot --path .github/copilot-instructions.md
+```
+
+**Cline:**
+```bash
+python3 "<PLUGIN_ROOT>/scripts/import_competing_tools.py" cline --path memory-bank/
+```
+
+**Continue:**
+```bash
+python3 "<PLUGIN_ROOT>/scripts/import_competing_tools.py" continue --path .continue/rules.md
+```
+
+### Step 4: Report results
+
+After each script runs, echo its output to the user. Then print a combined summary:
+
+```
+Import complete.
+  Cursor:  <N> memories
+  Copilot: <N> memories
+  Total:   <N> memories imported into project <project_id>
+```
+
+Adjust the summary to reflect only the tools that were actually imported.
+
+## Notes
+
+- Memories are imported with `infer=False` — no AI inference is applied, content is stored as-is.
+- Each section or file becomes a separate memory tagged with `metadata.source=<tool>-import` and `metadata.type=project_profile`.
+- Sections shorter than 50 characters are automatically skipped (too short to be useful).
+- Content longer than 10,000 characters is automatically truncated per chunk.
+- You can re-run this skill safely — duplicate content will be caught by mem0's deduplication.
@@ -0,0 +1,104 @@
+---
+name: mem0-import
+description: >
+  Import memories from a mem0 export file back into the current project.
+  Reads a YAML-frontmatter Markdown file produced by /mem0:export and
+  adds each memory block to mem0.
+  TRIGGER: user runs /mem0:import, or asks "import memories", "restore memories",
+  "load memories from file", "reimport backup".
+---
+
+# Mem0 Import
+
+Import memories from a mem0 export file into the current project.
+
+## Execution
+
+### Step 1: Determine the export file to import
+
+If the user provided a filename as an argument to `/mem0:import <filename>`, use that file.
+
+Otherwise, list `.md` files in the current directory whose names contain `mem0-export`:
+
+```bash
+ls -1 *.md 2>/dev/null | grep mem0-export || echo "No export files found"
+```
+
+If multiple files are found, ask the user which one to import. If none are found, print:
+```
+No mem0-export files found in the current directory.
+Run /mem0:export first, or provide the filename: /mem0:import <path-to-file>
+```
+
+### Step 2: Parse the export file
+
+Determine the plugin root. Use the appropriate variable for the current platform:
+- Claude Code: `${CLAUDE_PLUGIN_ROOT}`
+- Codex: `${CODEX_PLUGIN_ROOT}`
+- Cursor: `${CURSOR_PLUGIN_ROOT}`
+
+Run the parser script to extract memory records as JSON:
+
+```bash
+python3 "<PLUGIN_ROOT>/scripts/parse_export_file.py" "<path-to-export-file>"
+```
+
+This outputs a JSON array where each element has:
+- `id` — original memory ID (for reference only; a new ID will be assigned on import)
+- `type` — metadata type
+- `confidence` — metadata confidence value
+- `branch` — metadata branch
+- `files` — list of associated files
+- `categories` — list of categories
+- `content` — the memory text
+
+If the script fails or outputs `[]`, print:
+```
+Failed to parse <filename> or file contains no valid memory blocks.
+```
+and stop.
+
+### Step 3: Resolve identity
+
+Determine the active identity:
+- `user_id` from `MEM0_USER_ID` env var, else `$USER`, else `"default"`
+- `project_id` (used as `app_id`) from `MEM0_PROJECT_ID` env var, or via the project resolver
+
+### Step 4: Import each memory
+
+For each record in the parsed JSON array, call `add_memory` with:
+
+- `messages=[{"role": "user", "content": "<record.content>"}]`
+- `user_id=<active_user_id>`
+- `app_id=<active_project_id>`
+- `metadata={`
+  - `"type": "<record.type>"` (if non-empty)
+  - `"confidence": "<record.confidence>"` (if non-empty)
+  - `"branch": "<record.branch>"` (if non-empty)
+  - `"files": <record.files>` (the list, if non-empty)
+  - `"source": "import"`
+  - `}`
+- `infer=False`
+
+Notes:
+- Do NOT pass the original `id` — the platform assigns a new ID.
+- Skip records where `content` is empty (the parser already filters these, but be defensive).
+- Continue importing even if individual records fail; track the count of successes.
+
+### Step 5: Print results
+
+```
+Imported <N> memories into project <project_id>
+```
+
+Where `<N>` is the number of successfully imported memories.
+
+If any failed:
+```
+Imported <N>/<total> memories into project <project_id> (<failed> failed)
+```
+
+## Error Handling
+
+- If the parser script is not found at `<PLUGIN_ROOT>/scripts/parse_export_file.py`, print an error and stop.
+- If `add_memory` calls fail consistently (e.g. auth error), report the issue and stop early.
@@ -18,17 +18,16 @@ Decide whether persistent memory context would improve your response, then act a

 ## Project scoping

-Every memory operation MUST be scoped to the current project:
+Every memory operation MUST be scoped to the current project using `app_id` (entity-scoped memory):

- **On `add_memory`:** Always include `metadata.project_id` (the active project_id from SessionStart).
- **On `search_memories`:** Always include `{"metadata": {"project_id": "<your_project_id>"}}` in the AND filter.
- **Session-state memories:** Also include `metadata.branch` (the active branch from SessionStart).
+- **On `add_memory`:** Always pass `app_id=<active_project_id>` as a **top-level parameter** (not in metadata).
+- **On `search_memories`:** Always include `{"app_id": "<your_project_id>"}` in the AND filter.

 Full filter template:
 ```python
 filters={"AND": [
    {"user_id": "<your_user_id>"},
-    {"metadata": {"project_id": "<your_project_id>"}},
+    {"app_id": "<your_project_id>"},
    {"metadata": {"type": "decision"}}
 ]}
 ```
@@ -67,7 +66,7 @@ Two rules from the v2 filter spec:
 1. The root **must** be a logical operator (`AND` / `OR` / `NOT`) with an array. A bare `{"user_id": "..."}` won't work.
 2. Metadata uses a **nested** object, not a dotted key. `{"metadata": {"type": "decision"}}`, never `{"metadata.type": "decision"}`. Only top-level metadata keys are filterable.

-Combine `user_id` with one metadata clause per call:
+Combine `user_id` + `app_id` with one metadata clause per call:

 | `metadata.type` clause | Use for |
 |--------|---------|
@@ -76,9 +75,33 @@ Combine `user_id` with one metadata clause per call:
 | `{"metadata": {"type": "user_preference"}}` | tooling, stack, style — always include for code work |
 | `{"metadata": {"type": "convention"}}` | established patterns in this project |

+### Which categories to search by query intent
+
+When a query clearly maps to one of the platform's custom categories, fan-out to 2–3 parallel `search_memories` calls scoped to those categories so recall is precise without being noisy. Use the `metadata.type` filter as your primary discriminator; treat the category column below as the semantic lens to pick the right query nouns.
+
+| User intent / signal | Primary categories to search | Example query nouns |
+|---|---|---|
+| Design or architecture question | `architecture_decisions`, `api_contracts`, `data_model` | `"architecture decision"`, `"API schema"`, `"data model"` |
+| Something failed / debugging | `anti_patterns`, `bug_fixes`, `security_constraints` | `"bug root cause"`, `"failure pattern"`, `"security constraint"` |
+| How do we do X here? | `coding_conventions`, `team_norms`, `testing_patterns` | `"code convention"`, `"team norm"`, `"test strategy"` |
+| Which library / version to use | `dependency_decisions`, `tooling_setup`, `architecture_decisions` | `"dependency choice"`, `"library version"`, `"tooling setup"` |
+| Performance or scale concern | `performance_findings`, `architecture_decisions`, `data_model` | `"performance bottleneck"`, `"profiling result"`, `"optimisation"` |
+| Security / auth / compliance | `security_constraints`, `api_contracts`, `coding_conventions` | `"auth rule"`, `"security requirement"`, `"compliance"` |
+| Test strategy or coverage | `testing_patterns`, `coding_conventions`, `anti_patterns` | `"test framework"`, `"coverage target"`, `"fixture pattern"` |
+| Schema / DB / domain object | `data_model`, `api_contracts`, `domain_glossary` | `"schema"`, `"column"`, `"domain object"` |
+| API shape or versioning | `api_contracts`, `data_model`, `architecture_decisions` | `"endpoint"`, `"request schema"`, `"versioning"` |
+| How to deploy / release / rollback | `deployment_runbook`, `tooling_setup`, `team_norms` | `"deploy step"`, `"rollback"`, `"CI pipeline"` |
+| Team process / branching / PRs | `team_norms`, `coding_conventions`, `deployment_runbook` | `"branching strategy"`, `"PR review"`, `"working agreement"` |
+| What does this term mean? | `domain_glossary`, `data_model`, `api_contracts` | `"glossary"`, `"abbreviation"`, `"domain term"` |
+| Experiment / spike / A-B test | `experiment_results`, `performance_findings`, `anti_patterns` | `"experiment result"`, `"A/B test"`, `"spike outcome"` |
+| User's tool / language preferences | `user_preferences`, `tooling_setup`, `coding_conventions` | `"user preference"`, `"preferred tool"`, `"language choice"` |
+| Past task strategies that worked | `task_learnings`, `anti_patterns`, `coding_conventions` | `"task strategy"`, `"approach that worked"` |
+| Environment / setup question | `tooling_setup`, `deployment_runbook`, `dependency_decisions` | `"environment setup"`, `"build tool"`, `"install step"` |
+| Anything related to current state | `task_learnings`, `architecture_decisions`, `anti_patterns` | (combine with recency filter — see below) |
+
 Full filter (replace `<your_user_id>` and `<your_project_id>` with the active values from SessionStart):
 ```python
-filters={"AND": [{"user_id": "<your_user_id>"}, {"metadata": {"project_id": "<your_project_id>"}}, {"metadata": {"type": "decision"}}]}
+filters={"AND": [{"user_id": "<your_user_id>"}, {"app_id": "<your_project_id>"}, {"metadata": {"type": "decision"}}]}
 ```

 ### Worked example
@@ -91,16 +114,16 @@ search_memories(query="Refactor the auth module to use JWT")
 # Hits whatever shares words. Misses prior decisions and preferences.
 ```

-Do (parallel — substitute the active `user_id` and `project_id` for the placeholders):
+Do (parallel — substitute the active `user_id` and `app_id` for the placeholders):
 ```python
 search_memories(query="auth module decisions",
-                filters={"AND": [{"user_id": "<your_user_id>"}, {"metadata": {"project_id": "<your_project_id>"}}, {"metadata": {"type": "decision"}}]})
+                filters={"AND": [{"user_id": "<your_user_id>"}, {"app_id": "<your_project_id>"}, {"metadata": {"type": "decision"}}]})
 search_memories(query="JWT",
-                filters={"AND": [{"user_id": "<your_user_id>"}, {"metadata": {"project_id": "<your_project_id>"}}]})
+                filters={"AND": [{"user_id": "<your_user_id>"}, {"app_id": "<your_project_id>"}]})
 search_memories(query="auth refactor failures",
-                filters={"AND": [{"user_id": "<your_user_id>"}, {"metadata": {"project_id": "<your_project_id>"}}, {"metadata": {"type": "anti_pattern"}}]})
+                filters={"AND": [{"user_id": "<your_user_id>"}, {"app_id": "<your_project_id>"}, {"metadata": {"type": "anti_pattern"}}]})
 search_memories(query="auth",
-                filters={"AND": [{"user_id": "<your_user_id>"}, {"metadata": {"project_id": "<your_project_id>"}}, {"metadata": {"type": "user_preference"}}]})
+                filters={"AND": [{"user_id": "<your_user_id>"}, {"app_id": "<your_project_id>"}, {"metadata": {"type": "user_preference"}}]})
 ```

 ## After completing significant work
@@ -114,6 +137,8 @@ Extract key learnings and store them using the `add_memory` tool:
 - **Environment/setup discoveries** -> Include metadata `{"type": "environmental"}`
 - **Conventions established** -> Include metadata `{"type": "convention"}`

+Always include `"branch": "<active_branch>"` in the metadata object alongside `type`. The active branch is shown in the SessionStart banner. This enables branch-scoped filtering later (e.g., "what did we do on feature/auth-rewrite?").
+
 > `metadata.type` (which you set explicitly) and `categories` (which the platform auto-tags after the project's custom-category list — see `scripts/setup_coding_categories.py`) are complementary. Always set `metadata.type` for explicit filtering; the platform fills in `categories` on its own. Don't try to set `categories` on `add_memory` calls — per-request overrides aren't supported on the managed API.

 ### Expiration: high-churn vs durable
@@ -133,7 +158,7 @@ When the user is asking about *current* state ("where were we", "what's the acti

 ```python
 # Last 90 days only
-{"AND": [{"user_id": "<id>"}, {"metadata": {"project_id": "<your_project_id>"}}, {"metadata": {"type": "session_state"}}, {"created_at": {"gte": "<90 days ago, YYYY-MM-DD>"}}]}
+{"AND": [{"user_id": "<id>"}, {"app_id": "<your_project_id>"}, {"metadata": {"type": "session_state"}}, {"created_at": {"gte": "<90 days ago, YYYY-MM-DD>"}}]}
 ```

 Skip the recency filter when the user is asking about durable facts ("what conventions does this project use", "have we hit this bug before") — those are timeless and recency would hide them.
@@ -148,7 +173,8 @@ When you've done the extraction work yourself — pre-compaction summaries, deci
 add_memory(
    messages=[{"role": "user", "content": "<your structured fact>"}],
    user_id="<active user_id>",
-    metadata={"type": "decision"},
+    app_id="<active project_id>",
+    metadata={"type": "decision", "branch": "<active branch>"},
    infer=False,
 )
 ```
@@ -180,8 +206,115 @@ If context is about to be compacted or the session is ending, store a comprehens

 Include metadata: `{"type": "session_state"}`

+## Inline citations
+
+When your response is informed by specific memories, cite them so the user can trace provenance. Use the memory ID returned by `search_memories`.
+
+Format: `[mem0:<short_id>]` where `<short_id>` is the first 8 characters of the memory ID.
+
+Example:
+> We chose Postgres over SQLite for production [mem0:a3f8b2c1] and the auth module uses JWT tokens [mem0:7e2d9f4a].
+
+Rules:
+- Only cite when the memory **directly informed** your answer. Don't cite for general knowledge.
+- Place citations inline, at the end of the relevant sentence.
+- If multiple memories support the same point, cite all: `[mem0:abc12345][mem0:def67890]`.
+- Don't cite `session_state` or `compact_summary` memories — those are internal bookkeeping.
+- Keep it subtle. One or two citations per response is typical. Don't over-cite.
+
 ## Memory hygiene

 - Do NOT write to MEMORY.md or any file-based memory. Use mem0 MCP tools exclusively.
 - Only store genuinely useful learnings. Skip trivial interactions.
 - Use specific, searchable language in memory content.
+
+### Confidence scoring on every add_memory
+
+Every `add_memory` call MUST include a `confidence` field in its `metadata` object. This captures how certain the stored fact is, so downstream callers can filter out speculation.
+
+| `metadata.confidence` value | Meaning | When to use |
+|---|---|---|
+| `1.0` | User explicitly stated it | User said "we use Postgres", "always lint before commit", "never use floats for currency" |
+| `0.8` | Observed directly in code / config | You read it from a file, migration, or config — not inferred |
+| `0.5` | Inferred from context | You derived it from surrounding evidence but the user didn't confirm it |
+| `0.3` | Guessed / low-signal | Extrapolated from a single weak signal; treat as a tentative hypothesis |
+
+Example:
+
+```python
+add_memory(
+    messages=[{"role": "user", "content": "We always use Postgres — never SQLite in production."}],
+    user_id="<active user_id>",
+    app_id="<active project_id>",
+    metadata={"type": "architecture_decisions", "branch": "<active branch>", "confidence": 1.0},
+    infer=False,
+)
+```
+
+**Search guidance:** When recalling actionable facts (decisions, conventions, security constraints), optionally apply a confidence threshold of 0.6 or above to avoid surfacing low-confidence guesses. Only top-level metadata keys are filterable, so `confidence` filtering requires SDK-side post-filtering or a dedicated high-confidence write path — for now, include the confidence value in every write and document it in the memory content so it is searchable via text.
+
+### File path tagging on every add_memory
+
+Every `add_memory` call that is associated with specific files MUST include a `files` key in its `metadata` object. The value is an array of affected file paths relative to the project root.
+
+```python
+add_memory(
+    messages=[{"role": "user", "content": "The auth middleware lives in src/middleware/auth.ts and validates JWTs using the shared key in config/secrets.ts."}],
+    user_id="<active user_id>",
+    app_id="<active project_id>",
+    metadata={
+        "type": "architecture_decisions",
+        "branch": "<active branch>",
+        "confidence": 0.8,
+        "files": ["src/middleware/auth.ts", "config/secrets.ts"],
+    },
+    infer=False,
+)
+```
+
+**Filtering by files:** Use the `contains` operator to filter by `metadata.files` at search time:
+
+```python
+search_memories(
+    query="auth middleware",
+    filters={
+        "AND": [
+            {"user_id": "<id>"},
+            {"app_id": "<project_id>"},
+            {"metadata.files": {"contains": "src/middleware/auth.ts"}},
+        ]
+    },
+    limit=5,
+)
+```
+
+Also embed bare filenames in the memory content text as a fallback — the vector search will surface them even if the structured filter misses.
+
+### Access counter: track memory usage
+
+When you retrieve a memory via `search_memories` and **actually use it** in your response (i.e., it informed your answer or you cited it), increment its access counter and update the last-accessed timestamp by calling:
+
+```python
+# 1. Read current state
+mem = get_memory(memory_id=<id>)
+current_text = mem["content"]  # or mem["memory"], depending on response shape
+current_meta = mem.get("metadata", {})
+
+# 2. Bump access_count and set last_accessed
+import datetime
+current_meta["access_count"] = current_meta.get("access_count", 0) + 1
+current_meta["last_accessed"] = datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+# 3. Update with preserved content and bumped metadata
+update_memory(
+    memory_id=<id>,
+    data=current_text,  # preserve original text — required parameter
+    metadata=current_meta,  # pass updated access_count and last_accessed
+)
+```
+
+**Important:** `update_memory` requires the `data` (text) parameter. Always `get_memory` first to read the current content, then pass it back unchanged. A metadata-only update may error or wipe the content.
+
+**When to increment:** Only when you actually used the memory to answer. Don't bump on every search hit — that inflates counts for memories that were returned but irrelevant. Aim for 1-3 bumps per response at most.
+
+**Why:** `access_count` and `last_accessed` feed into `/mem0:dream` pruning decisions. Memories that are never accessed after creation are candidates for cleanup. Frequently accessed memories are protected from pruning regardless of age.
@@ -11,27 +11,31 @@ description: >

 Run this wizard to set up the mem0 plugin for the current project. Complete in ~30 seconds.

-## Step 1: Verify API key
+## Step 0: Ensure mem0ai SDK is installed

-Check if `MEM0_API_KEY` is set in the current environment:
+The plugin installs the `mem0ai` Python SDK automatically on session start via a venv in `${CLAUDE_PLUGIN_DATA}/venv`. If Step 4 (categories) fails with an import error, run:

 ```bash
-echo "${MEM0_API_KEY:+SET}" || echo "NOT_SET"
+"${CLAUDE_PLUGIN_ROOT}/scripts/ensure_deps.sh"
 ```

- If **NOT set**:
-  1. Ask the user: "No MEM0_API_KEY found. Do you have one, or need to create one?"
-  2. If they need one, provide two options:
-     - **Browser**: Go to https://app.mem0.ai/dashboard/api-keys and copy the key
-     - **CLI**: Run `pip install mem0-cli && mem0 init --agent --json` to mint a key without email
-  3. Once they have the key, tell them to run: `export MEM0_API_KEY="m0-..."` in their terminal, then restart this Claude Code session (the env var must be set before Claude Code starts).
-  4. **STOP here.** Do not proceed until the key is confirmed set.
- If **SET**: Proceed to Step 2.
+This is silent and idempotent — safe to run anytime.
+
+## Step 1: Verify API key and MCP connection
+
+Check that mem0 MCP tools are available. Use ToolSearch with query `"mem0 search_memories"` — the exact tool name varies by install method (may be `mcp__mem0__search_memories` or `mcp__plugin_mem0_mem0__search_memories`).
+
+- If **any mem0 search tool found**: Proceed to Step 2. The API key is working.
+- If **NOT found**: The MCP server failed to connect. Tell the user:
+  1. "MCP server not connected. Make sure `MEM0_API_KEY` is exported in your shell."
+  2. Show: `export MEM0_API_KEY="m0-your-key-here"` then restart Claude Code.
+  3. If they need a key: https://app.mem0.ai/dashboard/api-keys or `mem0 init --agent --json`
+  4. **STOP here.** Do not proceed — all other steps need MCP tools.

 ## Step 2: Show identity

 Report the active identity to the user:
- Call `search_memories` with `query="project setup"`, `user_id=<active_user_id>`, `filters={"AND": [{"user_id": "<active_user_id>"}, {"metadata": {"project_id": "<active_project_id>"}}]}`, `limit=1` to verify connectivity.
+- Call `search_memories` with `query="project setup"`, `user_id=<active_user_id>`, `filters={"AND": [{"user_id": "<active_user_id>"}, {"app_id": "<active_project_id>"}]}`, `limit=1` to verify connectivity.
 - Print: `Connected. user=<user_id>, project=<project_id>, branch=<branch>`
 - If the search fails, troubleshoot the API key.

@@ -51,34 +55,49 @@ If user says yes (or default):
 - Call `add_memory` with:
  - `messages=[{"role": "user", "content": "## Project Profile: <filename>\n\nProject: <project_id>\n\n<file_content>"}]`
  - `user_id=<active_user_id>`
-  - `metadata={"type": "project_profile", "file": "<filename>", "project_id": "<active_project_id>", "source": "onboard"}`
+  - `app_id=<active_project_id>`
+  - `metadata={"type": "project_profile", "file": "<filename>", "source": "onboard", "branch": "<active_branch>"}`
  - `infer=False`

 ## Step 4: Install coding categories

 Ask: "Install coding categories optimized for development workflows? [Y/n]"

-If yes, run the script directly (no external dependencies required — uses stdlib only).
-
-The script lives at `scripts/setup_coding_categories.py` relative to the plugin root. Use the appropriate plugin root variable for the current platform:
- Claude Code: `${CLAUDE_PLUGIN_ROOT}`
- Codex: `${CODEX_PLUGIN_ROOT}`
- Cursor: `${CURSOR_PLUGIN_ROOT}`
+If yes, run the setup script using the plugin's venv python:

 ```bash
-python3 "<PLUGIN_ROOT>/scripts/setup_coding_categories.py" --apply
+VENV_PY="${CLAUDE_PLUGIN_DATA}/venv/bin/python3"
+if [ -x "${VENV_PY}" ]; then
+  "${VENV_PY}" "${CLAUDE_PLUGIN_ROOT}/scripts/setup_coding_categories.py" --apply
+else
+  python3 "${CLAUDE_PLUGIN_ROOT}/scripts/setup_coding_categories.py" --apply
+fi
 ```

-If the script reports an error, show the error message and suggest checking the API key.
+If the script fails with "mem0ai SDK not found", run the dependency installer first:
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/ensure_deps.sh"
+```
+Then retry the categories script.

-## Step 5: Summary
+## Step 5: Mark project as onboarded
+
+Create a marker file so SessionStart won't re-trigger onboarding next session:
+
+```bash
+_SAFE_PID=$(printf '%s' "<active_project_id>" | tr '/:' '--')
+mkdir -p ~/.mem0 && touch ~/.mem0/.onboarded_${_SAFE_PID}
+```
+
+This is silent — no user-facing output needed.
+
+## Step 6: Summary

 Print a summary:
 ```
 Onboarding complete.
  user_id:    <user_id>
-  project_id: <project_id>
-  branch:     <branch>
+  project_id: <project_id> (app_id)
  imported:   <N> files
  categories: <installed or skipped>

@@ -0,0 +1,46 @@
+---
+name: mem0-peek
+description: >
+  Quick search — compact one-liner results. Faster and lighter than /mem0:tour.
+  Takes a search query as argument.
+  TRIGGER: user runs /mem0:peek <query>, or says "quick search mem0",
+  "what do we know about X", "peek at memories about Y".
+---
+
+# Mem0 Peek
+
+Quick search with compact output. Lighter than `/mem0:tour`.
+
+## Execution
+
+### Step 1: Parse query
+
+The user provides a search query: `/mem0:peek auth middleware`
+
+If no query provided, ask: "What should I search for?"
+
+### Step 2: Search
+
+Run 2 parallel `search_memories` calls:
+
+1. Broad: `query=<user's query>`, `filters={"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}]}`, `limit=10`
+2. Targeted: `query=<user's query>`, `filters={"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}, {"metadata": {"type": "decision"}}]}`, `limit=5`
+
+### Step 3: Display
+
+Deduplicate by ID, then show compact results:
+
+```
+## mem0 peek: "<query>" (<N> results)
+
+1. [decision] Auth module uses JWT with RS256 keys (2025-05-15) [mem0:a3f8b2c1]
+2. [anti_pattern] Don't use symmetric HS256 — leaked in env (2025-05-10) [mem0:7e2d9f4a]
+3. [convention] All middleware in src/middleware/ (2025-05-08) [mem0:c4d5e6f7]
+```
+
+Format: `<number>. [<type>] <content, 80 chars> (<date>) [mem0:<short_id>]`
+
+If no results:
+```
+No memories matching "<query>" for project <project_id>.
+```
@@ -0,0 +1,68 @@
+---
+name: mem0-pin
+description: >
+  Pin important memories so they surface prominently. Updates metadata to mark
+  a memory as pinned. Pinned memories should be prioritized during search.
+  TRIGGER: user runs /mem0:pin <query or ID>, or says "pin this memory",
+  "mark as important", "always remember this".
+---
+
+# Mem0 Pin
+
+Pin a memory to mark it as high-priority.
+
+## Execution
+
+### Step 1: Find the memory
+
+The user provides either a search query or memory ID.
+
+**If memory ID:**
+- Call `get_memory` with the ID.
+
+**If search query:**
+- Call `search_memories` with the query, `user_id`, `app_id`, `limit=5`.
+- Show numbered list with content previews.
+- Ask: "Which memory to pin? Enter a number."
+
+### Step 2: Read current content
+
+Call `get_memory` with the selected memory ID. Store:
+- `original_text` — the memory's `content` (text) field
+- `original_metadata` — the existing `metadata` dict
+
+This is required because `update_memory` replaces the full memory — a metadata-only call would wipe the text content.
+
+### Step 3: Pin it
+
+Call `update_memory` with:
+- `memory_id=<selected_id>`
+- `data=<original_text>` (preserve the existing content)
+- `metadata=` merge `original_metadata` with `{"pinned": true}`
+
+Example:
+```python
+updated_meta = {**original_metadata, "pinned": True}
+update_memory(memory_id=<selected_id>, data=<original_text>, metadata=updated_meta)
+```
+
+**Important:** `update_memory` requires the `data` (text) parameter. Passing only metadata may error or wipe content. Always read first, then update with the full text and explicit metadata.
+
+### Step 4: Confirm
+
+```
+Pinned: "<memory content, first 80 chars>..."
+Memory ID: <id>
+Pinned memories surface first when relevant to a search.
+```
+
+### Unpin
+
+If the user says "unpin" or `/mem0:unpin`:
+1. Call `get_memory` to read current content and metadata.
+2. Set `metadata.pinned = false` explicitly:
+   ```python
+   updated_meta = {**original_metadata, "pinned": False}
+   update_memory(memory_id=<id>, data=<original_text>, metadata=updated_meta)
+   ```
+3. Print: `Unpinned: "<content>..."`
@@ -0,0 +1,53 @@
+---
+name: mem0-remember
+description: >
+  Quick-add a memory from the user's input. No extraction pass — stores verbatim.
+  TRIGGER: user runs /mem0:remember <text>, or says "remember this", "save this",
+  "store this fact", "don't forget that".
+---
+
+# Mem0 Remember
+
+Store a fact or learning directly into mem0.
+
+## Execution
+
+### Step 1: Extract the content
+
+The user provides the content as an argument: `/mem0:remember <text>`
+
+If no text was provided, ask: "What should I remember?"
+
+### Step 2: Classify the memory
+
+Based on the content, pick the best `metadata.type`:
+
+| Content signal | Type |
+|---|---|
+| "we decided...", "always use...", "never..." | `decision` |
+| "X doesn't work because...", "don't try..." | `anti_pattern` |
+| "I prefer...", "use X instead of Y" | `user_preference` |
+| "the convention is...", "we always..." | `convention` |
+| "learned that...", "figured out..." | `task_learning` |
+| setup, env, tooling, config | `environmental` |
+| anything else | `task_learning` |
+
+### Step 3: Store
+
+Call `add_memory` with:
+- `messages=[{"role": "user", "content": "<the user's text>"}]`
+- `user_id=<active_user_id>`
+- `app_id=<active_project_id>`
+- `metadata={"type": "<classified_type>", "branch": "<active_branch>", "confidence": 1.0, "source": "remember_command"}`
+- `infer=False`
+
+`infer=False` because the user stated the fact explicitly — no extraction needed.
+`confidence=1.0` because the user explicitly asked to store this.
+
+### Step 4: Confirm
+
+Print:
+```
+Remembered as <type>: "<first 80 chars of content>..."
+Memory ID: <id>
+```
@@ -0,0 +1,96 @@
+---
+name: mem0-stats
+description: >
+  Show memory statistics for the current session and project lifetime.
+  Combines local session counters with API-fetched totals.
+  TRIGGER: user runs /mem0:stats, or asks "how many memories", "mem0 stats",
+  "memory usage", "show memory count".
+---
+
+# Mem0 Stats
+
+Show session and lifetime memory statistics.
+
+## Execution
+
+### Step 1: Gather session stats
+
+Run the session stats reporter:
+
+```bash
+SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}}/scripts"
+python3 "$SCRIPT_DIR/session_stats.py" peek 2>/dev/null || echo "{}"
+```
+
+The `peek` command returns JSON without clearing the stats file (unlike `report`).
+
+If the script returns empty or errors, note "No session data available" and continue.
+
+### Step 2: Fetch lifetime stats from API
+
+Call `get_memories` with:
+- `user_id=<active_user_id>`
+- `app_id=<active_project_id>`
+- `page_size=100`
+
+Count the returned memories. Group them by:
+1. `categories[0]` (platform-assigned) — primary grouping
+2. `metadata.type` (agent-assigned) — secondary if no categories
+3. `created_at` date — for age analysis
+
+Also run a `search_memories` call with `query="project"`, `limit=1` to measure round-trip latency (time the call).
+
+### Step 3: Display
+
+Print a compact dashboard with an ASCII histogram for category distribution:
+
+```
+## mem0 Stats
+
+### This Session
+  Memories written:  <N>
+  Searches run:      <N>
+  Categories touched: <list>
+
+### Project Lifetime (<project_id>)
+  Total memories:    <N>
+
+  By category:
+    decision          ████████████████ 24
+    convention        ██████████░░░░░░ 15
+    anti_pattern      ████░░░░░░░░░░░░  6
+    task_learning     ███░░░░░░░░░░░░░  5
+    user_preference   ██░░░░░░░░░░░░░░  3
+    session_state     █░░░░░░░░░░░░░░░  2
+
+  By age:
+    < 7 days          ████████████████  5
+    7–30 days         ██████████░░░░░░ 12
+    30–90 days        ████░░░░░░░░░░░░ 10
+    > 90 days         ██░░░░░░░░░░░░░░  8
+
+  By access count:
+    Never accessed    ████████████████ 18
+    1–5 accesses      ████████░░░░░░░░ 10
+    6–20 accesses     ████░░░░░░░░░░░░  4
+    20+ accesses      █░░░░░░░░░░░░░░░  3
+
+  Oldest memory:     <date>
+  Newest memory:     <date>
+
+### Health
+  API latency:       <N>ms
+  User:              <user_id>
+  Project:           <project_id>
+  Branch:            <branch>
+```
+
+**Histogram rules:**
+- Max bar width: 16 characters. Scale all bars relative to the highest count.
+- Use `█` for filled and `░` for empty. Right-align the count number.
+- Sort categories by count descending. Omit categories with 0 memories.
+- If only 1-2 categories exist, still show the histogram — it provides visual context.
+- **Age buckets:** Compute from `created_at`. Buckets: <7d, 7–30d, 30–90d, >90d.
+- **Access count buckets:** Read `metadata.access_count` (default 0 if absent). Buckets: 0, 1–5, 6–20, 20+.
+
+Skip any section with zero data.
@@ -40,7 +40,7 @@ The user provides a project name as an argument: `/mem0:switch-project <project-
   (Replace `<PROJECT_NAME>` with the user's chosen project name.)

 3. Verify by searching for existing memories:
-   - Call `search_memories` with `query="project"`, `filters={"AND": [{"user_id": "<id>"}, {"metadata": {"project_id": "<PROJECT_NAME>"}}]}`, `limit=1`
+   - Call `search_memories` with `query="project"`, `filters={"AND": [{"user_id": "<id>"}, {"app_id": "<PROJECT_NAME>"}]}`, `limit=1`

 4. Print:
   ```
@@ -13,34 +13,79 @@ Show the user what mem0 has stored for the current project.

 ## Execution

-1. Run the following `search_memories` calls in parallel (all with the active `user_id` and `metadata.project_id`):
+### Step 1: Fetch ALL memories for this project

-   - `query="architecture decisions"`, `filters={"AND": [{"user_id": "<id>"}, {"metadata": {"project_id": "<pid>"}}, {"metadata": {"type": "decision"}}]}`, `limit=5`
-   - `query="anti patterns failures"`, `filters={"AND": [{"user_id": "<id>"}, {"metadata": {"project_id": "<pid>"}}, {"metadata": {"type": "anti_pattern"}}]}`, `limit=5`
-   - `query="task learnings strategies"`, `filters={"AND": [{"user_id": "<id>"}, {"metadata": {"project_id": "<pid>"}}, {"metadata": {"type": "task_learning"}}]}`, `limit=5`
-   - `query="coding conventions"`, `filters={"AND": [{"user_id": "<id>"}, {"metadata": {"project_id": "<pid>"}}, {"metadata": {"type": "convention"}}]}`, `limit=5`
-   - `query="user preferences"`, `filters={"AND": [{"user_id": "<id>"}, {"metadata": {"project_id": "<pid>"}}, {"metadata": {"type": "user_preference"}}]}`, `limit=5`
-   - `query="project profile"`, `filters={"AND": [{"user_id": "<id>"}, {"metadata": {"project_id": "<pid>"}}, {"metadata": {"type": "project_profile"}}]}`, `limit=5`
-   - `query="tooling setup environment"`, `filters={"AND": [{"user_id": "<id>"}, {"metadata": {"project_id": "<pid>"}}, {"metadata": {"type": "environmental"}}]}`, `limit=5`
+Call `get_memories` with:
+- `user_id=<active_user_id>`
+- `app_id=<active_project_id>`

-2. Group results by category. For each category with results, print:
+This returns every memory scoped to the project — no semantic filtering, no missed results.

-   ```
-   ## <category_name> (<count> memories)
-   - <memory_content_truncated_to_100_chars> (score: <similarity_score>)
-   - ...
-   ```
+If `get_memories` doesn't support `app_id` as a direct parameter, use:
+- `filters={"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}]}`

-3. For categories with zero results, print: `<category_name>: (empty)`
+Pass `page_size=100` (or the maximum allowed) to get a full picture.

-4. Print totals at the end:
-   ```
-   ---
-   Total: <N> memories across <M> categories for project <project_id>
-   ```
+### Step 2: Run supplementary semantic searches

-5. If ALL categories are empty, print:
-   ```
-   No memories stored yet for project <project_id>.
-   Run /mem0:onboard to import project files, or start working — mem0 captures learnings automatically.
-   ```
+In parallel, run these `search_memories` calls to get relevance-ranked results for key topics:
+
+- `query="architecture decisions design choices"`, `filters={"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}]}`, `limit=10`
+- `query="bugs errors failures anti-patterns"`, `filters={"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}]}`, `limit=10`
+- `query="project setup tooling conventions preferences"`, `filters={"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}]}`, `limit=10`
+
+**Do NOT filter by `metadata.type` in these calls.** The platform auto-assigns `categories` — filtering on `metadata.type` misses memories that were auto-categorized but don't have an explicit `metadata.type`.
+
+### Step 3: Merge and group
+
+Merge all results by memory ID (deduplicate). For each memory, determine its group using this priority:
+
+1. **Platform `categories` field** (array on each memory, auto-assigned by Mem0). Use the first category value.
+2. **`metadata.type` field** (if present, set explicitly by hooks/agent). Use as fallback if no `categories`.
+3. **"other"** bucket for memories with neither.
+
+Map category names to display names:
+
+| Platform category / metadata.type | Display name |
+|---|---|
+| `architecture decisions`, `architecture_decisions`, `decision` | Architecture Decisions |
+| `anti patterns`, `anti_patterns`, `anti_pattern` | Anti-Patterns |
+| `task learnings`, `task_learnings`, `task_learning` | Task Learnings |
+| `coding conventions`, `coding_conventions`, `convention` | Coding Conventions |
+| `user preferences`, `user_preferences`, `user_preference` | User Preferences |
+| `project profile`, `project_profile` | Project Profile |
+| `tooling setup`, `tooling_setup`, `environmental` | Tooling & Setup |
+| `technology`, `professional_details` | Tooling & Setup |
+| `session_state` | Session State |
+| `compact_summary` | Compact Summaries |
+| anything else | Other |
+
+### Step 4: Display results
+
+For each group that has results, print:
+
+```
+## <display_name> (<count> memories)
+- <full_memory_content> (score: <similarity_score_if_available>)
+- ...
+```
+
+Show the **full memory text** for each entry — do NOT truncate. If a group has more than 10 entries, show top 10 by recency (or similarity score if from a search call) and note `... and <N> more`.
+
+For groups with zero results, skip them entirely — don't print empty groups.
+
+### Step 5: Print totals
+
+```
+---
+Total: <N> unique memories across <M> categories for project <project_id>
+Branch: <active_branch>
+```
+
+### Step 6: Empty state
+
+If zero memories found for this project, print:
+```
+No memories stored yet for project <project_id>.
+Run /mem0:onboard to import project files, or start working — mem0 captures learnings automatically.
+```