feat(mem0-plugin): improve auto-triggering — pre-fetch, dedup, skill enforcement v0.2.3 (#5237)
This commit is contained in:
Kartik
@@ -0,0 +1,50 @@
|
||||
---
|
||||
name: context-loader
|
||||
description: Pre-load relevant memories for current task
|
||||
---
|
||||
|
||||
# Context Loader
|
||||
|
||||
Pre-fetches relevant memories to prime context before working on a task.
|
||||
|
||||
## When to use
|
||||
|
||||
- Session start (auto-triggered by `on_session_start.sh` for onboarded projects)
|
||||
- User starts work on a specific feature or file set
|
||||
- Complex multi-step task begins
|
||||
- User says "what do we know about X" or "context for X"
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Extract topics** from current message/task. Identify: file paths, module names, feature areas, error patterns.
|
||||
|
||||
2. **Run 2-4 parallel `search_memories` calls** with different angles:
|
||||
|
||||
| Query angle | Filter | Purpose |
|
||||
|---|---|---|
|
||||
| Feature/module name | `{"metadata": {"type": "decision"}}` | Architecture decisions |
|
||||
| File paths mentioned | `{"metadata": {"type": "convention"}}` | Coding patterns |
|
||||
| Error keywords (if any) | `{"metadata": {"type": "anti_pattern"}}` | Known pitfalls |
|
||||
| Broad project context | no metadata filter | Catch-all |
|
||||
|
||||
All calls must include `user_id` and `app_id` filters.
|
||||
|
||||
3. **Deduplicate** results by memory ID across all search responses.
|
||||
|
||||
4. **Output compact context block** (max 10 memories):
|
||||
|
||||
```
|
||||
context-loader: loaded <N> memories for "<task summary>"
|
||||
- [decision] <content> [mem0:<short_id>]
|
||||
- [convention] <content> [mem0:<short_id>]
|
||||
- [anti_pattern] <content> [mem0:<short_id>]
|
||||
```
|
||||
|
||||
5. If **zero results**: output nothing. Don't announce empty context.
|
||||
|
||||
## Constraints
|
||||
|
||||
- **Read-only** — never modify or delete memories
|
||||
- **Max 10 memories** returned (most relevant only)
|
||||
- **Silent on empty** — only surfaces findings if relevant context exists
|
||||
- Skip memories already visible in current session context
|
||||
@@ -0,0 +1,224 @@
|
||||
---
|
||||
name: dream
|
||||
description: Consolidate memories — merge duplicates, resolve contradictions, prune stale
|
||||
---
|
||||
|
||||
# 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(
|
||||
filters={"AND": [{"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 — consolidation report
|
||||
|
||||
Merges (<N>):
|
||||
[mem0:<id1>] + [mem0:<id2>] → "<merged content, 100 chars>"
|
||||
|
||||
Conflicts (<N>):
|
||||
[mem0:<idA>] vs [mem0:<idB>] — "<topic>" [A/B/skip]
|
||||
|
||||
Prune (<N>):
|
||||
[mem0:<id>] — <type>, <age>d old
|
||||
|
||||
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>, text=<original_text_content>)` to preserve the text while updating it.
|
||||
- **Important:** `update_memory` requires the `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>, pruned: <N>, conflicts resolved: <N>, skipped: <N>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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,
|
||||
)
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- `/mem0:forget` — targeted deletion of specific memories (search + confirm + delete)
|
||||
- `/mem0:health --deep` — quick quality scan without applying changes
|
||||
@@ -1,10 +1,6 @@
|
||||
---
|
||||
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".
|
||||
name: export
|
||||
description: Export project memories to a portable Markdown file
|
||||
---
|
||||
|
||||
# Mem0 Export
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
name: forget
|
||||
description: Delete memories by search or ID — confirms before deleting
|
||||
---
|
||||
|
||||
# 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>`
|
||||
- `filters={"AND": [{"user_id": "<active_user_id>"}, {"app_id": "<project_id>"}]}`
|
||||
- `top_k=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. Try `/mem0:tour` to browse recent memories, or `/mem0:forget <search query>` to find specific ones."
|
||||
@@ -1,10 +1,6 @@
|
||||
---
|
||||
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".
|
||||
name: health
|
||||
description: Diagnose mem0 connection, API key, and memory read/write
|
||||
---
|
||||
|
||||
# Mem0 Health Check
|
||||
@@ -70,26 +66,22 @@ This file is created by the SessionStart hook and updated by PostToolUse hooks t
|
||||
### Display
|
||||
|
||||
```
|
||||
## mem0 Health Check
|
||||
## mem0 health
|
||||
|
||||
| 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 |
|
||||
PASS API Key m0-dVe...
|
||||
PASS Identity user=kartik, project=mem0, branch=main
|
||||
PASS MCP Connection 142ms
|
||||
PASS Write/Read write + delete OK
|
||||
PASS Session Tracker stats file active
|
||||
|
||||
All checks passed. mem0 is healthy.
|
||||
All checks passed.
|
||||
```
|
||||
|
||||
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).
|
||||
When invoked with `--deep` (e.g., `/mem0:health --deep`), run the standard 5 checks above **plus** a memory quality scan.
|
||||
|
||||
### Quality Check 1: Duplicates
|
||||
|
||||
@@ -141,31 +133,11 @@ Untagged/orphan memories: <N>
|
||||
|
||||
```
|
||||
## 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 |
|
||||
|
||||
Duplicates: <N> · Stale: <N> · Contradictions: <N> · Orphans: <N>
|
||||
```
|
||||
|
||||
If all counts are 0: `Memory quality: clean. No duplicates, stale entries, or contradictions found.`
|
||||
If all counts are 0: `Memory quality: clean.`
|
||||
If any non-zero: append `Run /mem0:dream to fix.`
|
||||
|
||||
### 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)
|
||||
```
|
||||
To fix issues found by `--deep`, run `/mem0:dream` for automated consolidation (merges, prunes, conflict resolution).
|
||||
@@ -1,11 +1,6 @@
|
||||
---
|
||||
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".
|
||||
name: import
|
||||
description: Import memories from an export file into this project
|
||||
---
|
||||
|
||||
# Mem0 Import
|
||||
@@ -142,10 +137,7 @@ Tools: `cursorrules`, `copilot`, `cline`, `continue`.
|
||||
### T4: Report
|
||||
|
||||
```
|
||||
Import complete.
|
||||
Cursor: <N> memories
|
||||
Copilot: <N> memories
|
||||
Total: <N> memories imported into project <project_id>
|
||||
Imported <N> memories into <project_id> (cursor: <N>, copilot: <N>)
|
||||
```
|
||||
|
||||
Notes: `infer=False`, tagged `metadata.source=<tool>-import`, sections <50 chars
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
name: list-projects
|
||||
description: List all projects that have stored memories
|
||||
---
|
||||
|
||||
# Mem0 List Projects
|
||||
|
||||
Show all known project scopes for the current user.
|
||||
|
||||
## Execution
|
||||
|
||||
### Step 1: Fetch memories to discover app_ids
|
||||
|
||||
There is no dedicated "list projects" API endpoint. Discover projects by fetching
|
||||
the user's memories and extracting distinct `app_id` values.
|
||||
|
||||
Call `get_memories` with:
|
||||
- `filters={"user_id": "<active_user_id>"}`
|
||||
- `page_size=200`
|
||||
|
||||
Do NOT pass `app_id` — we want memories across ALL projects.
|
||||
|
||||
If the response indicates more pages, paginate until all are fetched (up to 1000
|
||||
memories max to avoid excessive API calls).
|
||||
|
||||
### Step 2: Extract distinct projects
|
||||
|
||||
For each memory, read the `app_id` field (may also appear as `metadata.app_id`
|
||||
on older memories). Collect distinct values.
|
||||
|
||||
For each project, count:
|
||||
- Total memories
|
||||
- Most recent `created_at` date
|
||||
- Top 3 `metadata.type` values by frequency
|
||||
|
||||
### Step 3: Display
|
||||
|
||||
```
|
||||
## mem0 projects
|
||||
|
||||
<app_id_1> <count> memories (last: <date>) ← current
|
||||
<app_id_2> <count> memories (last: <date>)
|
||||
|
||||
<N> projects, <M> total memories
|
||||
```
|
||||
|
||||
Mark current project with `← current`. Sort by memory count descending.
|
||||
|
||||
### Step 4: Empty state
|
||||
|
||||
If zero memories found:
|
||||
```
|
||||
No projects found. Run /mem0:onboard to get started.
|
||||
```
|
||||
@@ -1,396 +0,0 @@
|
||||
---
|
||||
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,
|
||||
)
|
||||
```
|
||||
|
||||
## Forget mode (targeted deletion)
|
||||
|
||||
When invoked with `--forget` (e.g., `/mem0:dream --forget auth module decisions`
|
||||
or `/mem0:dream --forget <memory_id>`), skip consolidation and go straight to
|
||||
search-confirm-delete:
|
||||
|
||||
### F1: Parse input
|
||||
|
||||
The argument after `--forget` is either:
|
||||
- A search query: `/mem0:dream --forget auth module decisions`
|
||||
- A memory ID: `/mem0:dream --forget <memory_id>`
|
||||
|
||||
If no argument after `--forget`, ask: "What should I forget? Provide a search query or memory ID."
|
||||
|
||||
### F2: 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>`
|
||||
- `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. ...
|
||||
```
|
||||
|
||||
### F3: Confirm
|
||||
|
||||
Ask: "Delete which memories? Enter numbers (e.g., 1,3,5), 'all', or 'cancel'."
|
||||
For a single memory ID: "Delete this memory? [y/N]"
|
||||
|
||||
**Never delete without confirmation.**
|
||||
|
||||
### F4: Delete and report
|
||||
|
||||
Call `delete_memory` for each confirmed entry. Report: `Deleted <N> memories.`
|
||||
|
||||
### Undo recent writes
|
||||
|
||||
If the user says "undo last N memories" or "undo last write":
|
||||
1. Run `python3 "$SCRIPT_DIR/session_stats.py" peek` to get `recent_ids`.
|
||||
2. Show last N entries, ask for confirmation.
|
||||
3. Delete confirmed entries via `delete_memory`.
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
```
|
||||
@@ -1,71 +0,0 @@
|
||||
---
|
||||
name: mem0-list-projects
|
||||
description: >
|
||||
List all project scopes (app_ids) that have stored memories for the current
|
||||
user. Essential for /mem0:switch-project discoverability and cross-project
|
||||
workflows.
|
||||
TRIGGER: user runs /mem0:list-projects, or asks "what projects does mem0 know",
|
||||
"list my mem0 projects", "show all projects", "which app_ids exist".
|
||||
---
|
||||
|
||||
# Mem0 List Projects
|
||||
|
||||
Show all known project scopes for the current user.
|
||||
|
||||
## Execution
|
||||
|
||||
### Step 1: Fetch memories to discover app_ids
|
||||
|
||||
There is no dedicated "list projects" API endpoint. Discover projects by fetching
|
||||
the user's memories and extracting distinct `app_id` values.
|
||||
|
||||
Call `get_memories` with:
|
||||
- `user_id=<active_user_id>`
|
||||
- `page_size=200`
|
||||
|
||||
Do NOT pass `app_id` — we want memories across ALL projects.
|
||||
|
||||
If the response indicates more pages, paginate until all are fetched (up to 1000
|
||||
memories max to avoid excessive API calls).
|
||||
|
||||
### Step 2: Extract distinct projects
|
||||
|
||||
For each memory, read the `app_id` field (may also appear as `metadata.app_id`
|
||||
on older memories). Collect distinct values.
|
||||
|
||||
For each project, count:
|
||||
- Total memories
|
||||
- Most recent `created_at` date
|
||||
- Top 3 `metadata.type` values by frequency
|
||||
|
||||
### Step 3: Display
|
||||
|
||||
```
|
||||
## mem0 Projects for <user_id>
|
||||
|
||||
| Project | Memories | Last Active | Top Categories |
|
||||
|---------|----------|-------------|---------------|
|
||||
| <app_id_1> | <count> | <date> | decision, convention, anti_pattern |
|
||||
| <app_id_2> | <count> | <date> | task_learning, environmental |
|
||||
| ... | | | |
|
||||
|
||||
Active project: <current_project_id> ← (current)
|
||||
Total: <N> projects, <M> total memories
|
||||
```
|
||||
|
||||
Mark the current project with `← (current)`.
|
||||
|
||||
### Step 4: Empty state
|
||||
|
||||
If zero memories found:
|
||||
```
|
||||
No projects found for user <user_id>.
|
||||
Run /mem0:onboard in a project directory to get started.
|
||||
```
|
||||
|
||||
### Step 5: Suggest next actions
|
||||
|
||||
```
|
||||
Switch project: /mem0:switch-project <name>
|
||||
Search across all: /mem0:tour --all-projects
|
||||
```
|
||||
@@ -1,108 +0,0 @@
|
||||
---
|
||||
name: mem0-onboard
|
||||
description: >
|
||||
Post-install onboarding wizard for the mem0 plugin.
|
||||
Detects CLAUDE.md, AGENTS.md, .cursorrules, .windsurfrules, mem0.md
|
||||
and offers to import them. Installs coding categories. Shows active identity.
|
||||
TRIGGER: user runs /mem0:onboard, or mentions "setup mem0", "configure mem0 plugin".
|
||||
---
|
||||
|
||||
# Mem0 Onboarding Wizard
|
||||
|
||||
Run this wizard to set up the mem0 plugin for the current project. Complete in ~30 seconds.
|
||||
|
||||
## Step 0: Ensure mem0ai SDK is installed
|
||||
|
||||
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
|
||||
"${CLAUDE_PLUGIN_ROOT}/scripts/ensure_deps.sh"
|
||||
```
|
||||
|
||||
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>"}, {"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.
|
||||
|
||||
## Step 3: Detect and import project files
|
||||
|
||||
Check for these files in the project root:
|
||||
1. `CLAUDE.md`
|
||||
2. `AGENTS.md`
|
||||
3. `.cursorrules`
|
||||
4. `.windsurfrules`
|
||||
5. `mem0.md`
|
||||
|
||||
For each file found, ask the user: "Found `<filename>` (<size> bytes). Import into mem0? [Y/n]"
|
||||
|
||||
If user says yes (or default):
|
||||
- Read the file content
|
||||
- Call `add_memory` with:
|
||||
- `messages=[{"role": "user", "content": "## Project Profile: <filename>\n\nProject: <project_id>\n\n<file_content>"}]`
|
||||
- `user_id=<active_user_id>`
|
||||
- `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 setup script using the plugin's venv python:
|
||||
|
||||
```bash
|
||||
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 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: Mark project as onboarded
|
||||
|
||||
The marker file is already created by `on_session_start.sh` on first display of the onboard prompt. Touch it here for idempotency:
|
||||
|
||||
```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> (app_id)
|
||||
imported: <N> files
|
||||
categories: <installed or skipped>
|
||||
|
||||
Memory is now active for this project. Start working — mem0 will
|
||||
automatically search relevant context and capture learnings.
|
||||
|
||||
Run /mem0:tour to see what mem0 already knows about this project.
|
||||
```
|
||||
@@ -1,97 +0,0 @@
|
||||
---
|
||||
name: mem0-pin
|
||||
description: >
|
||||
Pin important memories so they surface prominently and are protected from
|
||||
consolidation. New pins use immutable: true (SDK v2.1.33+) to prevent
|
||||
deduplication from modifying or removing the memory. Existing memories get
|
||||
metadata.pinned: true as a search-time filter; full consolidation protection
|
||||
requires delete + re-add. 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
|
||||
|
||||
There are two sub-cases depending on whether the user wants to pin an **existing** memory or create a **new** pinned memory from scratch.
|
||||
|
||||
#### 3a: Pinning a new memory (preferred path for full protection)
|
||||
|
||||
Use `add_memory` with `immutable: true` as a top-level parameter. The `immutable` flag is a first-class platform parameter (added in SDK v2.1.33) that prevents the memory from being modified or removed by consolidation/deduplication. `metadata.pinned: true` is also included as a search-time filter aid.
|
||||
|
||||
```python
|
||||
add_memory(
|
||||
messages=[{"role": "user", "content": "<text to pin>"}],
|
||||
user_id=<user_id>,
|
||||
immutable=True,
|
||||
metadata={"pinned": True},
|
||||
)
|
||||
```
|
||||
|
||||
#### 3b: Pinning an existing memory
|
||||
|
||||
Call `update_memory` with:
|
||||
- `memory_id=<selected_id>`
|
||||
- `data=<original_text>` (preserve the existing content)
|
||||
- `metadata=` merge `original_metadata` with `{"pinned": true}`
|
||||
|
||||
```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.
|
||||
|
||||
**Consolidation-protection limitation:** `update_memory` cannot set the `immutable` flag on an existing memory. If the user needs full consolidation protection for an existing memory, they must delete it and re-add it using `add_memory` with `immutable: true` (path 3a above). In the confirm step (Step 4), note this limitation if the user pinned an existing memory via `update_memory`.
|
||||
|
||||
### Step 4: Confirm
|
||||
|
||||
For new pins created via `add_memory` with `immutable: true`:
|
||||
```
|
||||
Pinned: "<memory content, first 80 chars>..."
|
||||
Memory ID: <id>
|
||||
Pinned with consolidation protection (immutable). This memory will not be modified or removed by deduplication.
|
||||
```
|
||||
|
||||
For existing memories pinned via `update_memory`:
|
||||
```
|
||||
Pinned: "<memory content, first 80 chars>..."
|
||||
Memory ID: <id>
|
||||
Pinned memories surface first when relevant to a search.
|
||||
Note: consolidation protection (immutable flag) requires delete + re-add. Say "re-pin this with full protection" to do that.
|
||||
```
|
||||
|
||||
### 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>..."`
|
||||
@@ -1,149 +0,0 @@
|
||||
---
|
||||
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.
|
||||
|
||||
## Weekly digest mode
|
||||
|
||||
When invoked with `--weekly` (e.g., `/mem0:stats --weekly`), append a weekly
|
||||
activity digest after the standard stats dashboard:
|
||||
|
||||
### W1: Fetch recent memories
|
||||
|
||||
Call `search_memories` in parallel with 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`
|
||||
|
||||
### W2: Analyze
|
||||
|
||||
Merge by ID. Group into "New this week" by `categories[0]` or `metadata.type`.
|
||||
Calculate: memories added last 7 days, most active categories, most active day.
|
||||
|
||||
### W3: Display
|
||||
|
||||
Append after the standard stats:
|
||||
|
||||
```
|
||||
### Weekly Digest (<start_date> to <today>)
|
||||
|
||||
New Memories This Week: <N>
|
||||
<category>: <count>
|
||||
- <memory summary, 80 chars> (<date>)
|
||||
- ...
|
||||
|
||||
Activity Pattern
|
||||
Most active day: <day> (<N> memories)
|
||||
Categories touched: <list>
|
||||
|
||||
Highlights
|
||||
<2-3 sentence summary of most important decisions/learnings this week>
|
||||
```
|
||||
|
||||
### W4: Write digest file
|
||||
|
||||
Write to `~/.mem0/weekly-digest.md` (overwrite). Append one-line to
|
||||
`~/.mem0/digest-history.log`:
|
||||
```
|
||||
<YYYY-MM-DD> | <project_id> | +<new_count> memories | top: <top_category>
|
||||
```
|
||||
|
||||
### W5: Empty state
|
||||
|
||||
If no new memories in 7 days:
|
||||
```
|
||||
No new memories in the past week for <project_id>.
|
||||
Total project memories: <N>.
|
||||
```
|
||||
@@ -1,17 +1,6 @@
|
||||
---
|
||||
name: mem0
|
||||
description: >
|
||||
Mem0 Platform SDK for adding persistent memory to AI applications.
|
||||
TRIGGER when: user mentions "mem0", "MemoryClient", "memory layer",
|
||||
"remember user preferences", "persistent context", "personalization",
|
||||
or needs to add long-term memory to chatbots, agents, or AI apps.
|
||||
Covers Python SDK (mem0ai), TypeScript SDK (mem0ai), and framework integrations
|
||||
(LangChain, CrewAI, OpenAI Agents SDK, Pipecat, LlamaIndex, AutoGen, LangGraph).
|
||||
Also covers the open-source self-hosted Memory class.
|
||||
This is the DEFAULT mem0 skill for ambiguous queries.
|
||||
DO NOT TRIGGER when: user asks about CLI commands, terminal usage, or shell
|
||||
scripts (use mem0-cli), or Vercel AI SDK / @mem0/vercel-ai-provider / createMem0
|
||||
(use mem0-vercel-ai-sdk).
|
||||
description: Mem0 SDK reference — Python, TypeScript, and integrations
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
author: mem0ai
|
||||
@@ -25,7 +14,6 @@ compatibility: Requires Python 3.10+ or Node.js 18+, pip install mem0ai or npm i
|
||||
|
||||
> **Skill Graph:** This skill is part of the Mem0 skill graph:
|
||||
> - **mem0** (this skill) -- Platform Client SDK + OSS (Python + TypeScript)
|
||||
> - **[mem0-cli](https://github.com/mem0ai/mem0/tree/main/skills/mem0-cli)** -- Command-line interface
|
||||
> - **[mem0-vercel-ai-sdk](https://github.com/mem0ai/mem0/tree/main/skills/mem0-vercel-ai-sdk)** -- Vercel AI SDK provider
|
||||
|
||||
Mem0 is a managed memory layer for AI applications. It stores, retrieves, and manages user memories via API — no infrastructure to deploy. For self-hosted usage, see the OSS section in the client references below.
|
||||
@@ -46,7 +34,7 @@ export MEM0_API_KEY="m0-your-api-key"
|
||||
|
||||
Get an API key at: https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=mem0-plugin-skill
|
||||
|
||||
> **Don't have a `MEM0_API_KEY`?** Run `mem0 init --agent --json` (after `pip install mem0-cli` or `npm install -g @mem0/cli`) to mint an evaluation key without email or dashboard. The human can claim later with `mem0 init --email <your-email>`.
|
||||
> **Don't have a `MEM0_API_KEY`?** Sign up at https://app.mem0.ai and create one from the dashboard. Keys start with `m0-`.
|
||||
|
||||
## Step 2: Initialize the client
|
||||
|
||||
@@ -134,20 +122,27 @@ def chat(user_input: str, user_id: str) -> str:
|
||||
|
||||
## Common edge cases
|
||||
|
||||
- **Search returns empty:** Memories process asynchronously. Wait 2-3s after `add()` before searching. Also verify `user_id` matches exactly (case-sensitive) and use `filters={"user_id": "..."}` syntax.
|
||||
- **AND filter with user_id + agent_id returns empty:** Entities are stored separately. Use `OR` instead, or query separately.
|
||||
- **Duplicate memories:** Don't mix `infer=True` (default) and `infer=False` for the same data. Stick to one mode.
|
||||
- **Wrong import:** Always use `from mem0 import MemoryClient` (or `AsyncMemoryClient` for async). Do not use `from mem0 import Memory`.
|
||||
- **v3 defaults:** `top_k=20`, `threshold=0.1`, `rerank=False`. Adjust as needed for your use case.
|
||||
- **Search returns empty:** v3 processes `add()` asynchronously — returns an event ID immediately. Wait 2-3s before searching. Also verify `user_id` matches exactly (case-sensitive) and use `filters={"user_id": "..."}` syntax.
|
||||
- **AND filter with user_id + agent_id returns empty:** Entities are stored separately. `{"AND": [{"user_id": "alice"}, {"agent_id": "bot"}]}` returns nothing. Use `OR` instead, or query each separately.
|
||||
- **Duplicate memories:** Don't mix `infer=True` (default) and `infer=False` for the same data. `infer=True` extracts facts via LLM with dedup. `infer=False` stores raw — same text can be stored twice.
|
||||
- **Implicit null scoping:** `filters={"user_id": "alice"}` only returns memories where `agent_id`, `app_id`, `run_id` are ALL null. Wrap in `{"OR": [...]}` to include memories with non-null scoping fields.
|
||||
- **Platform vs OSS imports:** Platform: `from mem0 import MemoryClient`. OSS: `from mem0 import Memory`. Don't mix them — `MemoryClient` talks to `api.mem0.ai`, `Memory` runs locally.
|
||||
- **v3 defaults:** `top_k=20`, `threshold=0.1`, `rerank=False`. Adjust as needed.
|
||||
|
||||
## v2 Compatibility
|
||||
## v3 API (Current)
|
||||
|
||||
If you're using SDK v2.x, note these differences:
|
||||
- **Entity IDs:** Pass `user_id` as top-level kwarg to `search()` instead of inside `filters`
|
||||
- **Defaults:** `top_k=100`, no threshold, `rerank=True`
|
||||
- **Graph memory:** Available via `enable_graph=True`
|
||||
Mem0 v3 uses single-pass extraction, entity linking, and multi-signal retrieval.
|
||||
|
||||
See the [migration guide](https://docs.mem0.ai/migration/oss-v2-to-v3) for details.
|
||||
**Key v3 changes from v2:**
|
||||
- **Endpoints:** `POST /v3/memories/add/`, `POST /v3/memories/search/`, `POST /v3/memories/` (paginated list)
|
||||
- **Extraction:** Single ADD-only pass — no more UPDATE/DELETE operations during extraction. Memories accumulate rather than consolidate.
|
||||
- **Entity linking:** Replaces graph memory. Auto-extracted during `add()`, no config needed. Remove `enable_graph` and `graph_store` from any old config.
|
||||
- **Defaults:** `top_k=20`, `threshold=0.1`, `rerank=False`
|
||||
- **Removed params:** `org_id`, `project_id`, `enable_graph` — all removed from SDK
|
||||
- **TypeScript:** Exclusively camelCase (`userId`, `agentId`, `appId`, `topK`)
|
||||
- **Add response:** Async — returns event ID immediately, poll via `GET /v1/event/{event_id}/`
|
||||
|
||||
See the [migration guide](https://docs.mem0.ai/migration/platform-v2-to-v3) for details.
|
||||
|
||||
## Live documentation search
|
||||
|
||||
@@ -189,5 +184,4 @@ Load these on demand for deeper detail:
|
||||
|
||||
| Skill | When to use | Link |
|
||||
|-------|-------------|------|
|
||||
| mem0-cli | Terminal commands, scripting, CI/CD, agent tool loops | [GitHub](https://github.com/mem0ai/mem0/tree/main/skills/mem0-cli) |
|
||||
| mem0-vercel-ai-sdk | Vercel AI SDK provider with automatic memory | [GitHub](https://github.com/mem0ai/mem0/tree/main/skills/mem0-vercel-ai-sdk) |
|
||||
|
||||
@@ -69,7 +69,7 @@ If you were using `enable_graph=True` in v2:
|
||||
- Remove `graph_store` from OSS configuration
|
||||
- Entity relationships are now consumed through retrieval ranking, not exposed as a separate `relations` array
|
||||
|
||||
See the [v2 to v3 migration guide](https://docs.mem0.ai/migration/oss-v2-to-v3) for details.
|
||||
See the [v2 to v3 migration guide](https://docs.mem0.ai/migration/platform-v2-to-v3) for details.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
name: memory-reviewer
|
||||
description: Review memory quality — duplicates, contradictions, stale entries
|
||||
---
|
||||
|
||||
# Memory Reviewer
|
||||
|
||||
Audits memory quality for the active project. Finds duplicates, contradictions, and low-confidence entries.
|
||||
|
||||
## When to use
|
||||
|
||||
- User asks "check my memories", "memory quality", "any duplicates?"
|
||||
- User runs `/mem0:memory-reviewer` directly
|
||||
- After a session with 5+ memory writes (suggest proactively)
|
||||
- After `/mem0:health --deep` identifies issues
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Fetch all memories** for active project via `get_memories` with `user_id` and `app_id`. Paginate if needed — cap at 200 memories.
|
||||
|
||||
2. **Group by `metadata.type`**. Common types: `decision`, `convention`, `anti_pattern`, `task_learning`, `project_profile`, `user_preference`, `session_state`.
|
||||
|
||||
3. **Scan each group for issues:**
|
||||
|
||||
| Issue | Detection method |
|
||||
|---|---|
|
||||
| **Near-duplicates** | >60% noun overlap within same type. Compare memory text after stripping stop words. |
|
||||
| **Contradictions** | Opposing facts about same topic (e.g., "use PostgreSQL" vs "use MySQL" for same component) |
|
||||
| **Low-confidence** | `metadata.confidence < 0.3` |
|
||||
| **Missing type** | No `metadata.type` set |
|
||||
| **Stale** | `created_at` older than 180 days with no updates |
|
||||
|
||||
4. **Output compact summary:**
|
||||
|
||||
```
|
||||
memory-reviewer: project=<id> total=<N>
|
||||
duplicates: <N> found
|
||||
contradictions: <N> found
|
||||
low_confidence: <N> found
|
||||
untagged: <N> found
|
||||
stale: <N> found
|
||||
```
|
||||
|
||||
5. **If issues found**, list them with memory IDs:
|
||||
|
||||
```
|
||||
Issues:
|
||||
[duplicate] "<memory_a>" ≈ "<memory_b>" [mem0:<id_a>, mem0:<id_b>]
|
||||
[contradiction] "<memory_x>" vs "<memory_y>" [mem0:<id_x>, mem0:<id_y>]
|
||||
[low_conf] "<memory_z>" (confidence: 0.1) [mem0:<id_z>]
|
||||
```
|
||||
|
||||
6. **Suggest action**: "Run `/mem0:dream` to consolidate duplicates and resolve contradictions."
|
||||
|
||||
## Constraints
|
||||
|
||||
- **Read-only** — never modify or delete memories (that's `/mem0:dream`'s job)
|
||||
- **Max 200 memories** per scan
|
||||
- Report findings, let user decide on action
|
||||
@@ -0,0 +1,156 @@
|
||||
---
|
||||
name: onboard
|
||||
description: Set up mem0 for this project — API key setup, config, categories, identity
|
||||
---
|
||||
|
||||
# Mem0 Onboarding Wizard
|
||||
|
||||
Run this wizard to set up the mem0 plugin for the current project. Complete in ~60 seconds.
|
||||
|
||||
## Step 0: Ensure mem0ai SDK is installed
|
||||
|
||||
The plugin installs the `mem0ai` Python SDK automatically on session start via a venv in `${CLAUDE_PLUGIN_DATA}/venv`. If Step 5 (categories) fails with an import error, run:
|
||||
|
||||
```bash
|
||||
"${CLAUDE_PLUGIN_ROOT}/scripts/ensure_deps.sh"
|
||||
```
|
||||
|
||||
This is silent and idempotent — safe to run anytime.
|
||||
|
||||
## Step 1: Set up API key
|
||||
|
||||
Check if `MEM0_API_KEY` is already set by running:
|
||||
|
||||
```bash
|
||||
echo $MEM0_API_KEY
|
||||
```
|
||||
|
||||
### If API key IS set (non-empty output)
|
||||
|
||||
Print: `- API key found.` and proceed to Step 2.
|
||||
|
||||
### If API key is NOT set (empty output)
|
||||
|
||||
Guide the user through API key setup. Show this message and walk them through it:
|
||||
|
||||
```
|
||||
Step 1: Setting up API key.
|
||||
|
||||
- MEM0_API_KEY not found. Let's set it up.
|
||||
|
||||
1. Get your API key from https://app.mem0.ai/dashboard/api-keys
|
||||
(or run: mem0 init --agent --json)
|
||||
|
||||
2. Add to shell profile:
|
||||
echo 'export MEM0_API_KEY="m0-your-key-here"' >> ~/.zshrc
|
||||
source ~/.zshrc
|
||||
|
||||
3. Verify:
|
||||
echo $MEM0_API_KEY
|
||||
# Should print your key
|
||||
```
|
||||
|
||||
After the user confirms they've set the key, verify it by running `echo $MEM0_API_KEY`. If still empty, repeat the instructions. If set, proceed to Step 2.
|
||||
|
||||
## Step 2: MCP OAuth login
|
||||
|
||||
Now authenticate the MCP server connection. Tell the user:
|
||||
|
||||
```
|
||||
Step 2: MCP OAuth login.
|
||||
|
||||
1. Type /mcp in Claude Code
|
||||
2. A browser window will open for authentication at mcp.mem0.ai
|
||||
3. Log in with your mem0 account
|
||||
4. Return here after authenticating in your browser
|
||||
```
|
||||
|
||||
After the user completes OAuth, verify MCP tools are available using 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 MCP tools found: Print `- MCP connected.` and proceed to Step 3.
|
||||
- If NOT found: Troubleshoot before giving up:
|
||||
1. Check plugin is installed: run `/plugins` and confirm `mem0` appears
|
||||
2. Ask if the browser auth completed successfully
|
||||
3. Look for `mcp.mem0.ai` in the MCP server list via `/mcp`
|
||||
4. If all checks fail: "Restart Claude Code and run `/mem0:onboard` again."
|
||||
**STOP here** — do not proceed without MCP tools.
|
||||
|
||||
## Step 3: Verify connectivity and show identity
|
||||
|
||||
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 and MCP connection.
|
||||
|
||||
## Step 4: Detect and import project files
|
||||
|
||||
Check for these files in the project root:
|
||||
1. `CLAUDE.md`
|
||||
2. `AGENTS.md`
|
||||
3. `.cursorrules`
|
||||
4. `.windsurfrules`
|
||||
5. `mem0.md`
|
||||
|
||||
For each file found, ask the user: "Found `<filename>` (<size> bytes). Import into mem0? [Y/n]"
|
||||
|
||||
If user says yes (or default):
|
||||
- Read the file content
|
||||
- Call `add_memory` with:
|
||||
- `messages=[{"role": "user", "content": "## Project Profile: <filename>\n\nProject: <project_id>\n\n<file_content>"}]`
|
||||
- `user_id=<active_user_id>`
|
||||
- `app_id=<active_project_id>`
|
||||
- `metadata={"type": "project_profile", "file": "<filename>", "source": "onboard", "branch": "<active_branch>"}`
|
||||
- `infer=False`
|
||||
|
||||
## Step 5: Install coding categories
|
||||
|
||||
Ask: "Install coding categories optimized for development workflows? [Y/n]"
|
||||
|
||||
If yes, run the setup script using the plugin's venv python:
|
||||
|
||||
```bash
|
||||
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 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 6: Mark project as onboarded
|
||||
|
||||
```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 7: Summary
|
||||
|
||||
Print a summary:
|
||||
```
|
||||
- Onboarding complete.
|
||||
user_id: <user_id>
|
||||
project_id: <project_id> (app_id)
|
||||
imported: <N> files
|
||||
categories: <installed or skipped>
|
||||
|
||||
Memory is now active for this project. Start working — mem0 will
|
||||
automatically search relevant context and capture learnings.
|
||||
|
||||
Run /mem0:tour to see what mem0 already knows about this project.
|
||||
```
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
name: peek
|
||||
description: Quick search memories — compact one-liner results
|
||||
---
|
||||
|
||||
# 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>"}]}`, `top_k=10`
|
||||
2. Targeted: `query=<user's query>`, `filters={"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}, {"metadata": {"type": "decision"}}]}`, `top_k=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,75 @@
|
||||
---
|
||||
name: pin
|
||||
description: Pin a memory to protect it from consolidation
|
||||
---
|
||||
|
||||
# Mem0 Pin
|
||||
|
||||
Pin a memory to mark it as high-priority and protect from pruning.
|
||||
|
||||
## 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, `filters={"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}]}`, `top_k=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 text content
|
||||
- `original_metadata` — the existing `metadata` dict
|
||||
|
||||
### Step 3: Pin it
|
||||
|
||||
#### 3a: Pinning a new memory (full protection)
|
||||
|
||||
Use `add_memory` with `immutable: true`:
|
||||
|
||||
```python
|
||||
add_memory(
|
||||
messages=[{"role": "user", "content": "<text to pin>"}],
|
||||
user_id=<user_id>,
|
||||
immutable=True,
|
||||
metadata={"pinned": True},
|
||||
)
|
||||
```
|
||||
|
||||
#### 3b: Pinning an existing memory
|
||||
|
||||
Call `update_memory` with:
|
||||
- `memory_id=<selected_id>`
|
||||
- `text=<original_text>` (preserve existing content)
|
||||
- `metadata=` merge `original_metadata` with `{"pinned": true}`
|
||||
|
||||
```python
|
||||
updated_meta = {**original_metadata, "pinned": True}
|
||||
update_memory(memory_id=<selected_id>, text=<original_text>, metadata=updated_meta)
|
||||
```
|
||||
|
||||
**Important:** `update_memory` requires the `text` parameter. Passing only metadata may error or wipe content.
|
||||
|
||||
### Step 4: Confirm
|
||||
|
||||
```
|
||||
Pinned: "<memory content, first 80 chars>..."
|
||||
Memory ID: <id>
|
||||
```
|
||||
|
||||
### Unpin
|
||||
|
||||
If the user says "unpin":
|
||||
1. Call `get_memory` to read current content and metadata.
|
||||
2. Set `metadata.pinned = false`:
|
||||
```python
|
||||
updated_meta = {**original_metadata, "pinned": False}
|
||||
update_memory(memory_id=<id>, text=<original_text>, metadata=updated_meta)
|
||||
```
|
||||
3. Print: `Unpinned: "<content>..."`
|
||||
@@ -1,17 +1,36 @@
|
||||
---
|
||||
name: mem0-mcp
|
||||
description: >
|
||||
Mem0 memory protocol for agents using the mem0 MCP tools (Claude Code, Cursor,
|
||||
Codex, and any other MCP-aware runtime). Decide deliberately when memory context
|
||||
would help, run targeted searches with metadata filters when it would, and store
|
||||
key learnings as work completes. Use the mem0 MCP tools (add_memory,
|
||||
search_memories, get_memories, etc.) for all memory operations.
|
||||
name: protocol
|
||||
description: Memory protocol — when to search, how to filter, what to store
|
||||
---
|
||||
|
||||
# Mem0 MCP Memory Protocol
|
||||
|
||||
You have access to persistent memory via the mem0 MCP tools. Follow this protocol to maintain context across sessions.
|
||||
|
||||
## Natural language → skill routing
|
||||
|
||||
When a user says something in natural language, route to the right mem0 skill automatically:
|
||||
|
||||
| User says | Invoke |
|
||||
|---|---|
|
||||
| "remember this", "save this", "store this fact" | `/mem0:remember` |
|
||||
| "forget this", "delete memory about X", "remove that memory", "undo last write" | `/mem0:forget` |
|
||||
| "what do we know about X", "quick search", "peek at memories", "context for X" | `/mem0:peek` |
|
||||
| "show my memories", "browse memories", "memory tour", "list all memories" | `/mem0:tour` |
|
||||
| "clean up memories", "consolidate", "merge duplicates", "prune" | `/mem0:dream` |
|
||||
| "export memories", "backup memories", "download memories" | `/mem0:export` |
|
||||
| "import memories", "load memories from file" | `/mem0:import` |
|
||||
| "check mem0 health", "is mem0 working", "diagnose mem0" | `/mem0:health` |
|
||||
| "memory stats", "how many memories", "weekly digest" | `/mem0:stats` |
|
||||
| "set up mem0", "initialize mem0", "configure mem0" | `/mem0:onboard` |
|
||||
| "switch project", "change mem0 project" | `/mem0:switch-project` |
|
||||
| "list projects", "show all projects" | `/mem0:list-projects` |
|
||||
| "pin this memory", "protect this memory" | `/mem0:pin` |
|
||||
| "unpin this memory", "unprotect this memory" | `/mem0:pin` |
|
||||
| "check memory quality", "any duplicates?", "review memories" | `/mem0:memory-reviewer` |
|
||||
|
||||
If unsure, use the MCP tools directly (search/add/delete) without invoking a skill.
|
||||
|
||||
## On every new task
|
||||
|
||||
Decide whether persistent memory context would improve your response, then act accordingly. Don't search by default — search deliberately.
|
||||
@@ -56,7 +75,7 @@ After receiving search results, scan for contradictions before using them:
|
||||
1. If 2+ results address the **same topic** (same `metadata.type`, overlapping file paths or entity names) but assert **opposing facts**, surface BOTH to the user instead of silently picking one.
|
||||
2. Format:
|
||||
```
|
||||
⚠️ Conflicting memories found:
|
||||
Conflicting memories:
|
||||
- [mem0:<id1>] "<content1>" (confidence: <score1>, <date1>)
|
||||
- [mem0:<id2>] "<content2>" (confidence: <score2>, <date2>)
|
||||
Which is current?
|
||||
@@ -76,9 +95,9 @@ When you do search, run **2–4 parallel** `search_memories` calls at different
|
||||
|
||||
**Metadata filters** match the same `type` values written under "After completing significant work" below.
|
||||
|
||||
Two rules from the v2 filter spec:
|
||||
Filter rules:
|
||||
|
||||
1. The root **must** be a logical operator (`AND` / `OR` / `NOT`) with an array. A bare `{"user_id": "..."}` won't work.
|
||||
1. Prefer `AND` / `OR` / `NOT` operators at the root. A bare `{"user_id": "..."}` works as shorthand but cannot combine multiple fields.
|
||||
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` + `app_id` with one metadata clause per call:
|
||||
@@ -324,7 +343,7 @@ search_memories(
|
||||
{"metadata.files": {"contains": "src/middleware/auth.ts"}},
|
||||
]
|
||||
},
|
||||
limit=5,
|
||||
top_k=5,
|
||||
)
|
||||
```
|
||||
|
||||
@@ -348,12 +367,12 @@ current_meta["last_accessed"] = datetime.datetime.now(datetime.timezone.utc).iso
|
||||
# 3. Update with preserved content and bumped metadata
|
||||
update_memory(
|
||||
memory_id=<id>,
|
||||
data=current_text, # preserve original text — required parameter
|
||||
text=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.
|
||||
**Important:** `update_memory` requires the `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.
|
||||
|
||||
@@ -1,9 +1,6 @@
|
||||
---
|
||||
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".
|
||||
name: remember
|
||||
description: Save a memory verbatim from your input
|
||||
---
|
||||
|
||||
# Mem0 Remember
|
||||
@@ -48,6 +45,8 @@ Call `add_memory` with:
|
||||
|
||||
Print:
|
||||
```
|
||||
Remembered as <type>: "<first 80 chars of content>..."
|
||||
Remembered as <type>: "<content, first 80 chars>"
|
||||
Memory ID: <id>
|
||||
```
|
||||
|
||||
Append `...` only if content was truncated (longer than 80 chars).
|
||||
@@ -0,0 +1,121 @@
|
||||
---
|
||||
name: stats
|
||||
description: Show memory usage stats for this session and project
|
||||
---
|
||||
|
||||
# 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 minimal dashboard. No ASCII bar charts — use a clean table layout:
|
||||
|
||||
```
|
||||
## mem0 stats
|
||||
|
||||
**Session** — 3 written, 5 searches, categories: decision, convention
|
||||
|
||||
**Project: my-project** — 55 memories, API: 84ms
|
||||
|
||||
| Category | Count |
|
||||
|----------------------|-------|
|
||||
| decision | 24 |
|
||||
| convention | 15 |
|
||||
| anti_pattern | 6 |
|
||||
| task_learning | 5 |
|
||||
| user_preference | 3 |
|
||||
| session_state | 2 |
|
||||
|
||||
**Age** — oldest: 2026-02-15, newest: 2026-05-23
|
||||
< 7 days: 5 · 7–30d: 12 · 30–90d: 10 · > 90d: 8
|
||||
|
||||
**Identity** — user: kartik · project: my-project · branch: main
|
||||
```
|
||||
|
||||
**Display rules:**
|
||||
- Category table: sort by count descending, omit categories with 0 memories
|
||||
- Age: single line with dot-separated buckets, computed from `created_at`
|
||||
- Session line: skip if no session data available
|
||||
- If only 1-2 total memories, skip the category table — just show the count
|
||||
- Keep everything compact — no decorative borders or filler
|
||||
|
||||
## Weekly digest mode
|
||||
|
||||
When invoked with `--weekly` (e.g., `/mem0:stats --weekly`), append a weekly
|
||||
activity digest after the standard stats dashboard:
|
||||
|
||||
### W1: Fetch recent memories
|
||||
|
||||
Call `search_memories` in parallel with 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`
|
||||
|
||||
### W2: Analyze
|
||||
|
||||
Merge by ID. Group into "New this week" by `categories[0]` or `metadata.type`.
|
||||
Calculate: memories added last 7 days, most active categories, most active day.
|
||||
|
||||
### W3: Display
|
||||
|
||||
Append after the standard stats:
|
||||
|
||||
```
|
||||
### This week (May 16 – May 23)
|
||||
|
||||
+12 memories — most active: Wednesday (5)
|
||||
|
||||
| Category | New |
|
||||
|---------------|-----|
|
||||
| decision | 5 |
|
||||
| task_learning | 4 |
|
||||
| bug_fix | 3 |
|
||||
|
||||
**Highlights**
|
||||
- <2-3 sentence summary of most important decisions/learnings this week>
|
||||
```
|
||||
|
||||
### W4: Write digest file
|
||||
|
||||
Write to `~/.mem0/weekly-digest.md` (overwrite). Append one-line to
|
||||
`~/.mem0/digest-history.log`:
|
||||
```
|
||||
<YYYY-MM-DD> | <project_id> | +<new_count> memories | top: <top_category>
|
||||
```
|
||||
|
||||
### W5: Empty state
|
||||
|
||||
If no new memories in 7 days:
|
||||
```
|
||||
No new memories in the past week. Total: <N> memories in <project_id>.
|
||||
```
|
||||
+2
-6
@@ -1,10 +1,6 @@
|
||||
---
|
||||
name: mem0-switch-project
|
||||
description: >
|
||||
Manually override project_id for the current directory.
|
||||
Useful for monorepos, nested git dirs, or non-git directories.
|
||||
TRIGGER: user runs /mem0:switch-project <name>, or asks "switch mem0 project",
|
||||
"change project scope", "override project_id".
|
||||
name: switch-project
|
||||
description: Override the auto-detected project scope
|
||||
---
|
||||
|
||||
# Mem0 Switch Project
|
||||
@@ -1,10 +1,6 @@
|
||||
---
|
||||
name: mem0-tour
|
||||
description: >
|
||||
Show what mem0 knows about the current project. Dumps top memories
|
||||
grouped by category. Power-user-friendly proof of value.
|
||||
TRIGGER: user runs /mem0:tour, or asks "what do you know about this project",
|
||||
"show me my memories", "what has mem0 stored".
|
||||
name: tour
|
||||
description: Browse stored memories grouped by category
|
||||
---
|
||||
|
||||
# Mem0 Project Tour
|
||||
@@ -22,18 +18,14 @@ When invoked with `--all-projects` (e.g., `/mem0:tour --all-projects` or
|
||||
3. Group results by `app_id` first, then by category within each project.
|
||||
4. Display:
|
||||
```
|
||||
## Cross-Project Tour for <user_id>
|
||||
|
||||
### <app_id_1> (<N> memories)
|
||||
#### Architecture Decisions
|
||||
- <memory content>
|
||||
## <app_id_1> (<N> memories) ← current
|
||||
**Architecture Decisions** — <memory content>
|
||||
...
|
||||
|
||||
### <app_id_2> (<N> memories)
|
||||
## <app_id_2> (<N> memories)
|
||||
...
|
||||
|
||||
---
|
||||
Total: <N> memories across <M> projects
|
||||
<N> memories across <M> projects
|
||||
```
|
||||
5. Mark the current project with `← (current)` in the heading.
|
||||
|
||||
@@ -126,9 +118,7 @@ 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>
|
||||
<N> memories across <M> categories — project: <project_id>, branch: <active_branch>
|
||||
```
|
||||
|
||||
### Step 6: Empty state
|
||||
Reference in New Issue
Block a user