The Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.
Python agentic-memoryagentic-memory-systemagentsaiai-agentschatgptgenaillmlong-term-memorymemorymemory-managementpythonragstate-management
refactor(plugin): hand mem0 search decisions to the agent (#4992)
Gabriel Stein58304fc939d1
diff --git a/mem0-plugin/hooks/codex-hooks.json b/mem0-plugin/hooks/codex-hooks.jsonindex 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.jsonindex 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.shindex 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 pipefailINPUT=$(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 contextif [ ${#PROMPT} -lt 20 ]; thenexit 0fi-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:-}" ]; thenexit 0fiUSER_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 <<EOF+## Memory check-# Search mem0 for memories relevant to this prompt-RESPONSE=$(curl -s --max-time 3 \- -X POST "https://api.mem0.ai/v2/memories/search/" \- -H "Authorization: Token $API_KEY" \- -H "Content-Type: application/json" \- -d "$BODY" \- 2>/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 "")--if [ -n "$MEMORIES" ]; then- echo "$MEMORIES"-fi+**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 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.+EOFexit 0diff --git a/mem0-plugin/skills/mem0-codex/SKILL.md b/mem0-plugin/skills/mem0-codex/SKILL.mddeleted file mode 100644index 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.mdnew file mode 100644index 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 `<your_user_id>` with the active user_id from your runtime):+```python+filters={"AND": [{"user_id": "<your_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 `<your_user_id>`):+```python+search_memories(query="auth module decisions",+ filters={"AND": [{"user_id": "<your_user_id>"}, {"metadata": {"type": "decision"}}]})+search_memories(query="JWT",+ filters={"AND": [{"user_id": "<your_user_id>"}]})+search_memories(query="auth refactor failures",+ filters={"AND": [{"user_id": "<your_user_id>"}, {"metadata": {"type": "anti_pattern"}}]})+search_memories(query="auth",+ filters={"AND": [{"user_id": "<your_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.tomlindex 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.