From 58304fc939d1c720040b95ea9dafef75a56e53f1 Mon Sep 17 00:00:00 2001 From: Gabriel Stein Date: Thu, 7 May 2026 08:11:39 -0700 Subject: [PATCH] refactor(plugin): hand mem0 search decisions to the agent (#4992) Co-authored-by: Mgeeeek Co-authored-by: Claude Opus 4.7 (1M context) --- mem0-plugin/hooks/codex-hooks.json | 2 +- mem0-plugin/hooks/hooks.json | 2 +- mem0-plugin/scripts/on_user_prompt.sh | 76 +++++++------- mem0-plugin/skills/mem0-codex/SKILL.md | 62 ------------ mem0-plugin/skills/mem0-mcp/SKILL.md | 131 +++++++++++++++++++++++++ pyproject.toml | 1 + 6 files changed, 174 insertions(+), 100 deletions(-) delete mode 100644 mem0-plugin/skills/mem0-codex/SKILL.md create mode 100644 mem0-plugin/skills/mem0-mcp/SKILL.md diff --git a/mem0-plugin/hooks/codex-hooks.json b/mem0-plugin/hooks/codex-hooks.json index 0676308a9..23e6dbd32 100644 --- a/mem0-plugin/hooks/codex-hooks.json +++ b/mem0-plugin/hooks/codex-hooks.json @@ -18,7 +18,7 @@ { "type": "command", "command": "${CODEX_PLUGIN_ROOT}/scripts/on_user_prompt.sh", - "statusMessage": "Searching mem0 memories...", + "statusMessage": "Checking memory relevance...", "timeout": 5 } ] diff --git a/mem0-plugin/hooks/hooks.json b/mem0-plugin/hooks/hooks.json index d5b907427..897a978d9 100644 --- a/mem0-plugin/hooks/hooks.json +++ b/mem0-plugin/hooks/hooks.json @@ -57,7 +57,7 @@ { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/scripts/on_user_prompt.sh", - "statusMessage": "Searching mem0 memories...", + "statusMessage": "Checking memory relevance...", "timeout": 5 } ] diff --git a/mem0-plugin/scripts/on_user_prompt.sh b/mem0-plugin/scripts/on_user_prompt.sh index 398ec7456..70f8eaa44 100755 --- a/mem0-plugin/scripts/on_user_prompt.sh +++ b/mem0-plugin/scripts/on_user_prompt.sh @@ -1,61 +1,65 @@ #!/usr/bin/env bash # Hook: UserPromptSubmit # -# Fires on every user message. Searches mem0 for relevant memories -# and injects them into Claude's context before processing. +# Fires on every user message. Instead of pre-searching mem0 with the +# raw prompt, this injects a decision rubric telling the agent when +# and how to search itself. The agent has more context than this +# script does -- let it decide. # -# Input: JSON on stdin with prompt, session_id, cwd, transcript_path -# Output: Matching memories as context text (exit 0) -# -# Skips search for very short prompts (< 20 chars) and when -# MEM0_API_KEY is not set. Uses a 3s timeout to minimize latency. +# Input: JSON on stdin (prompt, session_id, cwd, transcript_path) +# Output: Decision rubric injected into Claude's context (exit 0) -# Intentionally omit -e so the script always exits 0 even if -# curl or jq fail — must never block the user's prompt. +# Intentionally omit -e so the script always exits 0 even if jq fails -- +# must never block the user's prompt. set -uo pipefail INPUT=$(cat) PROMPT=$(echo "$INPUT" | jq -r '.prompt // ""' 2>/dev/null || echo "") -# Skip trivial prompts — not worth a network call +# Acknowledgements and short replies don't warrant memory context if [ ${#PROMPT} -lt 20 ]; then exit 0 fi -API_KEY="${MEM0_API_KEY:-}" -if [ -z "$API_KEY" ]; then +# No API key means the agent can't search anyway +if [ -z "${MEM0_API_KEY:-}" ]; then exit 0 fi USER_ID="${MEM0_USER_ID:-${USER:-default}}" -# Build request body safely via jq to avoid injection -BODY=$(jq -n --arg query "$PROMPT" --arg user_id "$USER_ID" \ - '{query: $query, filters: {user_id: $user_id}, top_k: 5}') +cat </dev/null || echo "") +Before responding, decide whether persistent memory context from mem0 would +improve your answer. The agent -- not this hook -- owns this decision. -if [ -z "$RESPONSE" ]; then - exit 0 -fi +**Search WHEN** the user: +- references past work, decisions, or things "we" built +- asks "how should we...", "best way to...", or any decision-style question +- hits an error, bug, or asks for debugging help +- requests work that touches their stack, tools, conventions, or preferences +- starts a non-trivial task in a known project -# Extract memories from response (API returns a flat array) -MEMORIES=$(echo "$RESPONSE" | jq -r ' - if type == "array" then . else .results // [] end | - if length == 0 then empty else - "## Relevant memories from mem0\n\n" + - (map(select(.memory != null) | "- " + .memory) | join("\n")) - end -' 2>/dev/null || echo "") +**Skip WHEN:** +- the prompt is an acknowledgement or continuation +- the user is *stating* new info -- that's a write trigger (\`add_memory\`), not a search +- it's a pure syntax / factual question answerable from general knowledge +- you already searched this scope earlier in the turn -if [ -n "$MEMORIES" ]; then - echo "$MEMORIES" -fi +**If searching, do it well:** +- Run **2-4 parallel** \`search_memories\` calls with different angles, not one + query that echoes the user's prompt. +- Phrase queries as **nouns** ("auth module decisions"), not full sentences. +- Filter shape: the root must be a logical operator (\`AND\` / \`OR\` / \`NOT\`) + with an array, and metadata uses a **nested** object (not dotted keys). + Combine \`user_id\` with one \`metadata.type\` clause per call: + - \`{"AND": [{"user_id": "$USER_ID"}, {"metadata": {"type": "decision"}}]}\` -- design / architecture + - \`{"AND": [{"user_id": "$USER_ID"}, {"metadata": {"type": "anti_pattern"}}]}\` -- debugging, error handling + - \`{"AND": [{"user_id": "$USER_ID"}, {"metadata": {"type": "user_preference"}}]}\` -- tooling, stack, style + - \`{"AND": [{"user_id": "$USER_ID"}, {"metadata": {"type": "convention"}}]}\` -- established patterns +- Or scope with just \`{"AND": [{"user_id": "$USER_ID"}]}\` when no metadata filter fits. +- Empty results are normal -- proceed without context. +EOF exit 0 diff --git a/mem0-plugin/skills/mem0-codex/SKILL.md b/mem0-plugin/skills/mem0-codex/SKILL.md deleted file mode 100644 index 036f1a242..000000000 --- a/mem0-plugin/skills/mem0-codex/SKILL.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -name: mem0-codex -description: > - Mem0 persistent memory integration for Codex. Automatically retrieve relevant - memories at the start of each task, store key learnings when tasks complete, - and capture session state before context is lost. Use the mem0 MCP tools - (add_memory, search_memories, get_memories, etc.) for all memory operations. ---- - -# Mem0 Memory Protocol for Codex - -You have access to persistent memory via the mem0 MCP tools. Follow this protocol to maintain context across sessions. - -## On every new task - -1. Call `search_memories` with a query related to the current task or project to load relevant context. -2. Review returned memories to understand what has been learned in prior sessions. -3. If appropriate, call `get_memories` to browse all stored memories for this user. - -## After completing significant work - -Extract key learnings and store them using the `add_memory` tool: - -- **Decisions made** -> Include metadata `{"type": "decision"}` -- **Strategies that worked** -> Include metadata `{"type": "task_learning"}` -- **Failed approaches** -> Include metadata `{"type": "anti_pattern"}` -- **User preferences observed** -> Include metadata `{"type": "user_preference"}` -- **Environment/setup discoveries** -> Include metadata `{"type": "environmental"}` -- **Conventions established** -> Include metadata `{"type": "convention"}` - -Memories can be as detailed as needed -- include full context, reasoning, code snippets, file paths, and examples. Longer, searchable memories are more valuable than vague one-liners. - -## Before losing context - -If context is about to be compacted or the session is ending, store a comprehensive session summary: - -``` -## Session Summary - -### User's Goal -[What the user originally asked for] - -### What Was Accomplished -[Numbered list of tasks completed] - -### Key Decisions Made -[Architectural choices, trade-offs discussed] - -### Files Created or Modified -[Important file paths with what changed] - -### Current State -[What is in progress, pending items, next steps] -``` - -Include metadata: `{"type": "session_state"}` - -## 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. diff --git a/mem0-plugin/skills/mem0-mcp/SKILL.md b/mem0-plugin/skills/mem0-mcp/SKILL.md new file mode 100644 index 000000000..11331f19a --- /dev/null +++ b/mem0-plugin/skills/mem0-mcp/SKILL.md @@ -0,0 +1,131 @@ +--- +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. +--- + +# Mem0 MCP Memory Protocol + +You have access to persistent memory via the mem0 MCP tools. Follow this protocol to maintain context across sessions. + +## On every new task + +Decide whether persistent memory context would improve your response, then act accordingly. Don't search by default — search deliberately. + +### Decide: search or skip? + +**Search WHEN** the user: +- references past work, decisions, or things "we" built +- asks "how should we...", "best way to...", or any decision-style question +- hits an error, bug, or asks for debugging help +- requests work that touches their stack, tools, conventions, or preferences +- starts a non-trivial task in a known project + +**Skip WHEN:** +- the prompt is an acknowledgement or continuation ("ok", "thanks", "continue") +- the user is *stating* new info — that's a write trigger (`add_memory`), not a search +- it's a pure syntax / factual question answerable from general knowledge +- you already searched this scope earlier in the turn + +Empty results are normal. Proceed without context — they don't mean the system is broken. + +### How to search well + +When you do search, run **2–4 parallel** `search_memories` calls at different angles instead of one query echoing the user's prompt. + +**Query phrasing:** +- Use **nouns**, not sentences. `"auth module decisions"` beats `"what did we decide about auth"`. +- Strip conversational filler. *"remember when we picked Postgres?"* → search `"Postgres choice"`. +- Use entity names, not pronouns. Resolve "that thing" from recent context first. +- Don't search on meta-questions ("what was that?") — use recent context or `get_memories` ordered by `created_at`. + +**Metadata filters** match the same `type` values written under "After completing significant work" below. + +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: + +| `metadata.type` clause | Use for | +|--------|---------| +| `{"metadata": {"type": "decision"}}` | design / architecture / "how should we" questions | +| `{"metadata": {"type": "anti_pattern"}}` | debugging, error handling, things that failed before | +| `{"metadata": {"type": "user_preference"}}` | tooling, stack, style — always include for code work | +| `{"metadata": {"type": "convention"}}` | established patterns in this project | + +Full filter (replace `` with the active user_id from your runtime): +```python +filters={"AND": [{"user_id": ""}, {"metadata": {"type": "decision"}}]} +``` + +### Worked example + +User asks: *"Refactor the auth module to use JWT."* + +Don't: +```python +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` for ``): +```python +search_memories(query="auth module decisions", + filters={"AND": [{"user_id": ""}, {"metadata": {"type": "decision"}}]}) +search_memories(query="JWT", + filters={"AND": [{"user_id": ""}]}) +search_memories(query="auth refactor failures", + filters={"AND": [{"user_id": ""}, {"metadata": {"type": "anti_pattern"}}]}) +search_memories(query="auth", + filters={"AND": [{"user_id": ""}, {"metadata": {"type": "user_preference"}}]}) +``` + +## After completing significant work + +Extract key learnings and store them using the `add_memory` tool: + +- **Decisions made** -> Include metadata `{"type": "decision"}` +- **Strategies that worked** -> Include metadata `{"type": "task_learning"}` +- **Failed approaches** -> Include metadata `{"type": "anti_pattern"}` +- **User preferences observed** -> Include metadata `{"type": "user_preference"}` +- **Environment/setup discoveries** -> Include metadata `{"type": "environmental"}` +- **Conventions established** -> Include metadata `{"type": "convention"}` + +Memories can be as detailed as needed -- include full context, reasoning, code snippets, file paths, and examples. Longer, searchable memories are more valuable than vague one-liners. + +## Before losing context + +If context is about to be compacted or the session is ending, store a comprehensive session summary: + +``` +## Session Summary + +### User's Goal +[What the user originally asked for] + +### What Was Accomplished +[Numbered list of tasks completed] + +### Key Decisions Made +[Architectural choices, trade-offs discussed] + +### Files Created or Modified +[Important file paths with what changed] + +### Current State +[What is in progress, pending items, next steps] +``` + +Include metadata: `{"type": "session_state"}` + +## 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. diff --git a/pyproject.toml b/pyproject.toml index 94bdf4e1a..c5bf151c4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -153,3 +153,4 @@ known-first-party = ["mem0", "mem0_cli"] [tool.isort] profile = "black" known_first_party = ["mem0", "mem0_cli"] +# isort scope kept aligned with [tool.ruff.lint.isort] above.