Skip to content

armgit / mem0

Public Imported from GitHub
0

The Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.

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.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 <<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.
+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 `<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.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.