fix(agent-plugins): match memo prompts and tool descriptions, release 0.3.3 (#7420)

Co-authored-by: Claude <noreply@anthropic.com>
2026-09-23 19:35:25 +05:30
parent f8082a7345
commit 8c02c425a5
56 changed files with 262 additions and 249 deletions
@@ -12,7 +12,7 @@
      "name": "mem0",
      "source": "./integrations/claude-code-plugin",
      "description": "Cross-session memory and token savings for coding agents.",
-      "version": "0.3.2"
+      "version": "0.3.3"
    }
  ]
 }
@@ -12,7 +12,7 @@
      "name": "mem0",
      "source": "./integrations/cursor-plugin",
      "description": "Cross-session memory and token savings for coding agents.",
-      "version": "0.3.2"
+      "version": "0.3.3"
    }
  ]
 }
@@ -5,7 +5,7 @@
    {
      "id": "mem0",
      "displayName": "Mem0",
-      "version": "0.3.2",
+      "version": "0.3.3",
      "description": "Cross-session memory and token savings for coding agents.",
      "homepage": "https://mem0.ai",
      "keywords": ["memory", "personalization", "mcp", "semantic-search"],
@@ -2394,6 +2394,17 @@ Initial release of the Mem0 plugin for Claude Code and Cursor, followed by Codex
 <Tab title="Claude Code">
 <Update label="2026-09-23" description="Claude Code plugin v0.3.3">
 **Improvements:**
 - **Search:** The `search_memories` tool description no longer tells the agent to call it before answering anything that could depend on prior context. It now asks for a search before repeating investigation or when earlier decisions, fixes, commands, or results may help, which reduces unnecessary searches ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Sidekick:** Sidekick searches memories when earlier sessions could help, instead of before every answer ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Extraction:** Repository memory instructions are shorter. They no longer ask for a dedicated memory for each command that failed and was then fixed, and no longer carry separate rules against saving personal preferences or memories that only name the repository, branch, or directory ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Search skill:** `/search` no longer describes categories as best-effort labels or asks for a retry without the category ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Packaging:** `PLUGIN_VERSION` bumped to `0.3.3`, so the `mem0-plugin/<version>` wire header and `plugin_version` telemetry field identify builds with these prompts ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 </Update>
 <Update label="2026-09-18" description="Claude Code plugin v0.3.2">
 **Improvements:**
@@ -2424,6 +2435,16 @@ Initial release of the Mem0 plugin for Claude Code and Cursor, followed by Codex
 <Tab title="Cursor">
 <Update label="2026-09-23" description="Cursor plugin v0.3.3">
 **Improvements:**
 - **Search:** The `search_memories` tool description no longer tells the agent to call it before answering anything that could depend on prior context. It now asks for a search before repeating investigation or when earlier decisions, fixes, commands, or results may help, which reduces unnecessary searches ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Extraction:** Repository memory instructions are shorter. They no longer ask for a dedicated memory for each command that failed and was then fixed, and no longer carry separate rules against saving personal preferences or memories that only name the repository, branch, or directory ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Search skill:** `/search` no longer describes categories as best-effort labels or asks for a retry without the category ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Packaging:** `PLUGIN_VERSION` bumped to `0.3.3`, so the `mem0-plugin/<version>` wire header and `plugin_version` telemetry field identify builds with these prompts ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 </Update>
 <Update label="2026-09-18" description="Cursor plugin v0.3.2">
 **Improvements:**
@@ -2454,6 +2475,16 @@ Initial release of the Mem0 plugin for Claude Code and Cursor, followed by Codex
 <Tab title="Codex">
 <Update label="2026-09-23" description="Codex plugin v0.3.3">
 **Improvements:**
 - **Search:** The `search_memories` tool description no longer tells the agent to call it before answering anything that could depend on prior context. It now asks for a search before repeating investigation or when earlier decisions, fixes, commands, or results may help, which reduces unnecessary searches ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Extraction:** Repository memory instructions are shorter. They no longer ask for a dedicated memory for each command that failed and was then fixed, and no longer carry separate rules against saving personal preferences or memories that only name the repository, branch, or directory ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Search skill:** `/search` no longer describes categories as best-effort labels or asks for a retry without the category ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Packaging:** `PLUGIN_VERSION` bumped to `0.3.3`, so the `mem0-plugin/<version>` wire header and `plugin_version` telemetry field identify builds with these prompts ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 </Update>
 <Update label="2026-09-18" description="Codex plugin v0.3.2">
 **Improvements:**
@@ -2483,6 +2514,15 @@ Initial release of the Mem0 plugin for Claude Code and Cursor, followed by Codex
 <Tab title="OpenCode">
 <Update label="2026-09-23" description="OpenCode plugin v0.4.1">
 **Improvements:**
 - **Search:** The `search_memories` tool description no longer asks the agent to search proactively or to run several searches for multi-part questions. It now asks for a search before repeating investigation or when earlier decisions, fixes, commands, or results may help, the same wording as the other coding-agent plugins ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Session context:** Removed two system-context lines that told the agent to run 2 parallel searches before responding and 2-4 parallel searches for non-trivial tasks ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Skills:** `/mem0-search` and `/mem0-context-loader` make one `search_memories` call instead of 2 and 2-4 parallel calls. `/mem0-context-loader` now uses the search skill description from the other coding-agent plugins instead of asking to load at every new task or context switch ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 </Update>
 <Update label="2026-09-18" description="OpenCode plugin v0.4.0">
 **Changes:**
@@ -2589,6 +2629,16 @@ Initial release of the Mem0 plugin for Claude Code and Cursor, followed by Codex
 <Tab title="Antigravity">
 <Update label="2026-09-23" description="Antigravity plugin v0.3.3">
 **Improvements:**
 - **Search:** The `search_memories` tool description no longer tells the agent to call it before answering anything that could depend on prior context. It now asks for a search before repeating investigation or when earlier decisions, fixes, commands, or results may help, which reduces unnecessary searches ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Extraction:** Repository memory instructions are shorter. They no longer ask for a dedicated memory for each command that failed and was then fixed, and no longer carry separate rules against saving personal preferences or memories that only name the repository, branch, or directory ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Search skill:** `/search` no longer describes categories as best-effort labels or asks for a retry without the category ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Packaging:** `PLUGIN_VERSION` bumped to `0.3.3`, so the `mem0-plugin/<version>` wire header and `plugin_version` telemetry field identify builds with these prompts ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 </Update>
 <Update label="2026-09-18" description="Antigravity plugin v0.3.2">
 **Improvements:**
@@ -2692,6 +2742,16 @@ Existing memories written by the previous versions are not rewritten. If your me
 <Tab title="Kimi">
 <Update label="2026-09-23" description="Kimi Code plugin v0.3.3">
 **Improvements:**
 - **Search:** The `search_memories` tool description no longer tells the agent to call it before answering anything that could depend on prior context. It now asks for a search before repeating investigation or when earlier decisions, fixes, commands, or results may help, which reduces unnecessary searches ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Extraction:** Repository memory instructions are shorter. They no longer ask for a dedicated memory for each command that failed and was then fixed, and no longer carry separate rules against saving personal preferences or memories that only name the repository, branch, or directory ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Search skill:** `/search` no longer describes categories as best-effort labels or asks for a retry without the category ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Packaging:** `PLUGIN_VERSION` bumped to `0.3.3`, so the `mem0-plugin/<version>` wire header and `plugin_version` telemetry field identify builds with these prompts ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 </Update>
 <Update label="2026-09-18" description="Kimi Code plugin v0.3.2">
 **Improvements:**
@@ -2737,6 +2797,13 @@ Existing memories written by the previous versions are not rewritten. If your me
 <Tab title="OpenClaw">
 <Update label="2026-09-23" description="openclaw-mem0 v1.2.1">
 **Improvements:**
 - **Search:** The `memory_search` tool description no longer asks the agent to search proactively or to run several searches for multi-part questions. It now asks for a search before repeating investigation or when earlier decisions, fixes, commands, or results may help. Recall strategies (`smart`, `always`, `manual`) are unchanged ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 </Update>
 <Update label="2026-09-18" description="openclaw-mem0 v1.2.0">
 **Changes:**
@@ -3033,6 +3100,15 @@ Existing memories written by the previous versions are not rewritten. If your me
 <Tab title="Pi Agent">
 <Update label="2026-09-23" description="Pi Agent plugin v0.3.2">
 **Improvements:**
 - **Search:** The memory policy, `mem0_memory` tool description, and prompt guidelines no longer ask the agent to search before answering anything that may depend on earlier context or to run several searches per question. They now ask for a search before repeating investigation or when earlier decisions, fixes, commands, or results may help ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Skills:** `context-loader` makes one search instead of 2-4 parallel searches, and uses the search skill description from the other coding-agent plugins ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Automatic recall:** Injected memories are introduced as "Mem0 found these relevant memories from earlier work in this repository:", the same heading as the Python plugins. The old heading called them a shallow first pass and told the agent to search again ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 </Update>
 <Update label="2026-09-18" description="Pi Agent plugin v0.3.1">
 **Improvements:**
@@ -3153,6 +3229,14 @@ Existing memories written by the previous versions are not rewritten. If your me
 <Tab title="DeepSeek Harness">
 <Update label="2026-09-23" description="deepseek-plugin v0.3.2">
 **Improvements:**
 - **Search:** The `search_memory` tool description no longer asks the agent to search proactively before answering anything that may depend on earlier context. It now asks for a search before repeating investigation or when earlier decisions, fixes, commands, or results may help ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 - **Automatic recall:** Injected memories are introduced as "Mem0 found these relevant memories from earlier work:". The old heading called them a shallow first pass and told the agent to search again with `mem0_memory`, a tool DeepSeek does not have ([#7420](https://github.com/mem0ai/mem0/pull/7420))
 </Update>
 <Update label="2026-09-18" description="deepseek-plugin v0.3.1">
 **Improvements:**
@@ -8,7 +8,7 @@ This directory is the single source of shared memory behavior for Mem0 coding-ag
 integrations/
 ├── agent-plugin-core/       # Shared source; never installed as a plugin
 │   ├── python/              # Claude-derived capture, recall, MCP, scoping, and telemetry
-│   ├── typescript/          # Shared lifecycle, formatting, identity, scoping, and telemetry
+│   ├── typescript/          # Shared lifecycle, search prompts, formatting, identity, scoping, and telemetry
 │   ├── skills/              # The only source for the six generated memory skills
 │   ├── build/               # Bundle builder, schemas, and validation
 │   ├── conformance/         # One offline/live verification entry point
@@ -45,7 +45,7 @@ New Git repository writes use a hashed remote identity for shared `agent_id`. Se
 Captured prompts and responses preserve their full text after secret redaction. Python extraction splits oversized input across requests without dropping message text. The session-end worker flushes the conversation already collected by hooks without adding the final answer again. Search queries, retrieved context, and tool evidence have separate limits.
-TypeScript hosts reuse redaction and lifecycle utilities but retain their own tools, scopes, and capture events. They do not inherit the Python `repo`/`dir`/`mine` contract or its background batching. OpenCode captures selected user prompts; Pi and DeepSeek capture completed conversation turns; OpenClaw selects recent messages and earlier summaries, then filters noise. Removing message-length truncation does not turn these integrations into complete transcript archives.
+TypeScript hosts reuse redaction, lifecycle utilities, and the search prompts in `typescript/src/prompts.ts`, which a test keeps identical to the Python core. They retain their own tools, scopes, and capture events. They do not inherit the Python `repo`/`dir`/`mine` contract or its background batching. OpenCode captures selected user prompts; Pi and DeepSeek capture completed conversation turns; OpenClaw selects recent messages and earlier summaries, then filters noise. Removing message-length truncation does not turn these integrations into complete transcript archives.
 For installation, follow the host guides: [Claude Code](../../docs/integrations/claude-code.mdx), [Cursor](../../docs/integrations/cursor.mdx), [Codex](../../docs/integrations/codex.mdx), [Kimi](../../docs/integrations/kimi.mdx), and [Antigravity](../../docs/integrations/antigravity.mdx).
@@ -21,16 +21,9 @@ from memory_core import (
 PROTOCOL_VERSION = "2024-11-05"
 TOOL_NAME = "search_memories"
 TOOL_DESCRIPTION = (
-    "Search memories from earlier work in this repository. ALWAYS call this "
+    "Search memories from earlier work in this repository. Use it before "
-    "tool before answering anything that could depend on prior context: the "
+    "repeating investigation or when earlier decisions, fixes, commands, or "
-    "user's preferences, facts about this codebase, history, people, projects, "
+    "results may help."
    "or earlier decisions. Do not rely on the chat window alone. The "
    "repository's memory is shared by everyone who works in it and includes "
    "what it took to run, test, or build here, so search before assuming an "
    "invocation works. The scope argument changes what is searched: 'repo' "
    "(default) is the whole repository's shared memory plus your own "
    "preferences, 'dir' narrows the shared part to the directory you are "
    "working in, and 'mine' is your preferences alone."
 )
 TOOL_SCHEMA = {
    "type": "object",
@@ -29,7 +29,7 @@ from typing import Any, Iterable
 import telemetry
 DEFAULT_API_URL = "https://api.mem0.ai"
-PLUGIN_VERSION = "0.3.2"
+PLUGIN_VERSION = "0.3.3"
 _harness_name: str = "generic"
 _harness_env_prefix: str = "MEM0_PLUGIN"
@@ -71,15 +71,13 @@ MAX_FLUSH_ATTEMPTS = 5
 FORGET_PAGE_SIZE = 100
 FORGET_MAX_PAGES = 50
-PROJECT_MEMORY_INSTRUCTIONS = """Save concise repository facts that will help anyone with future coding work in this repository.
+PROJECT_MEMORY_INSTRUCTIONS = """Save concise repository facts that will help with future coding work.
 A completed change should produce one memory explaining the resulting behavior, where it is implemented when useful, and any important constraints or reasoning. Exploration or accepted decisions may produce separate memories only when they are independently useful.
-A command that failed and was then made to work should produce one memory naming the failing invocation, the error it returned, and the invocation that succeeded. Do not save one-off errors caused by an edit still in progress, transient network failures, or anything a rerun would fix on its own.
+Use the coding agent's final response for conclusions about current repository behavior. Do not save proposed or recommended changes unless the user accepted them or the coding agent completed them. Treat subagent responses as supporting repository evidence, not as decisions.
-Use the current coding agent's final response for conclusions about current repository behavior. Do not save proposed or recommended changes unless the user accepted them or the coding agent completed them. Treat subagent responses as supporting repository evidence, not as decisions.
+Write about the repository, not the user, assistant, session, or task. Do not include test results, documentation updates, release notes, or temporary state.
 Write about the repository, not the user, assistant, session, or task. Do not save personal preferences. Do not save a memory that only states which repository, branch, or directory the session worked in. Do not include test results, documentation updates, release notes, or temporary state.
 If nothing useful was established, return no memories."""
@@ -12,11 +12,9 @@ Call `search_memories` with the user's question. Treat `--top-k`, `--category`,
 query.
 Omit `top_k` to use Mem0's configured default. Omit `category` to search every
-category; a category is a best-effort label Mem0 assigned when it saved the
+category. Omit `scope` to use the configured default, normally `repo`: this
-memory, so if a category search misses, repeat it without the category. Omit
+repository's shared memory, which everyone who works in it contributes to,
-`scope` to use the configured default, normally `repo`: this repository's
+plus your own preferences.
 shared memory, which everyone who works in it contributes to, plus your own
 preferences.
 Pass `scope` when the question needs something else: `dir` to narrow the
 shared memory to the directory you are working in (a package inside a
@@ -1,5 +1,6 @@
 import type { MemoryLike } from "./formatting.ts";
 import { formatMemoryCompact } from "./formatting.ts";
 import { RECALL_HEADING } from "./prompts.ts";
 const MAX_RECALL_QUERY_CHARS = 6_000;
 export const DEFAULT_MAX_CONTEXT_CHARS = 4_000;
@@ -70,12 +71,14 @@ export function extractConversation(
 }
 interface RecallOptions {
  heading?: string;
  maxChars?: number;
  seenIds?: Set<string>;
  timeoutMs?: number;
 }
 interface MemoryLifecycleOptions {
  recallHeading?: string;
  maxContextChars?: number;
  recallTimeoutMs?: number;
 }
@@ -109,6 +112,7 @@ class MemoryLifecycle {
    search: (query: string) => Promise<{ results?: unknown[] }>,
  ): Promise<string> {
    return buildRecallContext(prompt, enabled, search, {
      heading: this.#options.recallHeading,
      maxChars: this.#options.maxContextChars,
      seenIds: this.#seenMemoryIds,
      timeoutMs: this.#options.recallTimeoutMs,
@@ -148,8 +152,7 @@ export async function buildRecallContext(
    const unseen = memories.filter((memory) => !options.seenIds?.has(memory.id));
    if (!unseen.length) return "";
-    const prefix =
+    const prefix = `<mem0-relevant-memories>\n${options.heading ?? RECALL_HEADING}\n`;
      "<mem0-relevant-memories>\nRetrieved automatically for the current request. This is a shallow first pass — search mem0_memory for more if you need it.\n";
    const suffix = "\n</mem0-relevant-memories>";
    const maxChars = options.maxChars ?? DEFAULT_MAX_CONTEXT_CHARS;
    const lines: string[] = [];
@@ -0,0 +1,10 @@
 export const SEARCH_WHEN =
  "before repeating investigation or when earlier decisions, fixes, commands, or results may help";
 export const SEARCH_TOOL_DESCRIPTION = `Search memories from earlier work in this repository. Use it ${SEARCH_WHEN}.`;
 export const SEARCH_QUERY_DESCRIPTION = "A direct question about earlier work in this repository.";
 export const RECALL_HEADING = "Mem0 found these relevant memories from earlier work in this repository:";
 export const USER_SEARCH_TOOL_DESCRIPTION = `Search memories from earlier work. Use it ${SEARCH_WHEN}.`;
 export const USER_SEARCH_QUERY_DESCRIPTION = "A direct question about earlier work.";
 export const USER_RECALL_HEADING = "Mem0 found these relevant memories from earlier work:";
@@ -0,0 +1,31 @@
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import test from "node:test";
 import { buildRecallContext } from "../src/lifecycle.ts";
 import {
  RECALL_HEADING,
  SEARCH_QUERY_DESCRIPTION,
  SEARCH_TOOL_DESCRIPTION,
  USER_RECALL_HEADING,
 } from "../src/prompts.ts";
 const pythonSource = (name: string) =>
  readFileSync(new URL(`../../python/${name}`, import.meta.url), "utf8").replace(/"\s*\n\s*"/g, "");
 test("search prompts match the Python core", () => {
  assert.ok(pythonSource("mcp_server.py").includes(SEARCH_TOOL_DESCRIPTION));
  assert.ok(pythonSource("mcp_server.py").includes(SEARCH_QUERY_DESCRIPTION));
  assert.ok(pythonSource("hook_runner.py").includes(RECALL_HEADING));
 });
 test("recall context uses the repository heading unless the host overrides it", async () => {
  const search = async () => ({ results: [{ id: "m1", memory: "Use pnpm" }] });
  assert.ok((await buildRecallContext("package manager", true, search)).includes(RECALL_HEADING));
  assert.ok(
    (await buildRecallContext("package manager", true, search, { heading: USER_RECALL_HEADING })).includes(
      USER_RECALL_HEADING,
    ),
  );
 });
@@ -21,16 +21,9 @@ from memory_core import (
 PROTOCOL_VERSION = "2024-11-05"
 TOOL_NAME = "search_memories"
 TOOL_DESCRIPTION = (
-    "Search memories from earlier work in this repository. ALWAYS call this "
+    "Search memories from earlier work in this repository. Use it before "
-    "tool before answering anything that could depend on prior context: the "
+    "repeating investigation or when earlier decisions, fixes, commands, or "
-    "user's preferences, facts about this codebase, history, people, projects, "
+    "results may help."
    "or earlier decisions. Do not rely on the chat window alone. The "
    "repository's memory is shared by everyone who works in it and includes "
    "what it took to run, test, or build here, so search before assuming an "
    "invocation works. The scope argument changes what is searched: 'repo' "
    "(default) is the whole repository's shared memory plus your own "
    "preferences, 'dir' narrows the shared part to the directory you are "
    "working in, and 'mine' is your preferences alone."
 )
 TOOL_SCHEMA = {
    "type": "object",
@@ -29,7 +29,7 @@ from typing import Any, Iterable
 import telemetry
 DEFAULT_API_URL = "https://api.mem0.ai"
-PLUGIN_VERSION = "0.3.2"
+PLUGIN_VERSION = "0.3.3"
 _harness_name: str = "generic"
 _harness_env_prefix: str = "MEM0_PLUGIN"
@@ -71,15 +71,13 @@ MAX_FLUSH_ATTEMPTS = 5
 FORGET_PAGE_SIZE = 100
 FORGET_MAX_PAGES = 50
-PROJECT_MEMORY_INSTRUCTIONS = """Save concise repository facts that will help anyone with future coding work in this repository.
+PROJECT_MEMORY_INSTRUCTIONS = """Save concise repository facts that will help with future coding work.
 A completed change should produce one memory explaining the resulting behavior, where it is implemented when useful, and any important constraints or reasoning. Exploration or accepted decisions may produce separate memories only when they are independently useful.
-A command that failed and was then made to work should produce one memory naming the failing invocation, the error it returned, and the invocation that succeeded. Do not save one-off errors caused by an edit still in progress, transient network failures, or anything a rerun would fix on its own.
+Use the coding agent's final response for conclusions about current repository behavior. Do not save proposed or recommended changes unless the user accepted them or the coding agent completed them. Treat subagent responses as supporting repository evidence, not as decisions.
-Use the current coding agent's final response for conclusions about current repository behavior. Do not save proposed or recommended changes unless the user accepted them or the coding agent completed them. Treat subagent responses as supporting repository evidence, not as decisions.
+Write about the repository, not the user, assistant, session, or task. Do not include test results, documentation updates, release notes, or temporary state.
 Write about the repository, not the user, assistant, session, or task. Do not save personal preferences. Do not save a memory that only states which repository, branch, or directory the session worked in. Do not include test results, documentation updates, release notes, or temporary state.
 If nothing useful was established, return no memories."""
@@ -1,6 +1,6 @@
 {
  "id": "mem0",
-  "version": "0.3.2",
+  "version": "0.3.3",
  "homepage": "https://docs.mem0.ai/integrations/antigravity",
  "native": {
    "pluginRoot": "${ANTIGRAVITY_PLUGIN_ROOT}",
@@ -12,11 +12,9 @@ Call `search_memories` with the user's question. Treat `--top-k`, `--category`,
 query.
 Omit `top_k` to use Mem0's configured default. Omit `category` to search every
-category; a category is a best-effort label Mem0 assigned when it saved the
+category. Omit `scope` to use the configured default, normally `repo`: this
-memory, so if a category search misses, repeat it without the category. Omit
+repository's shared memory, which everyone who works in it contributes to,
-`scope` to use the configured default, normally `repo`: this repository's
+plus your own preferences.
 shared memory, which everyone who works in it contributes to, plus your own
 preferences.
 Pass `scope` when the question needs something else: `dir` to narrow the
 shared memory to the directory you are working in (a package inside a
@@ -1,6 +1,6 @@
 {
  "name": "mem0",
-  "version": "0.3.2",
+  "version": "0.3.3",
  "description": "Cross-session memory and token savings for coding agents.",
  "author": {
    "name": "Mem0"
@@ -12,11 +12,8 @@ You are Mem0's Sonnet coding agent. Complete the work the main agent gives you.
 Work in the separate Git worktree Claude Code created for you. Return a tested
 result that the main agent can review without doing the same work again.
-ALWAYS call `search_memories` before answering anything that could depend on
+When memories from earlier sessions could help, call `search_memories` with a
-prior context (the user's preferences, facts about this codebase, history,
+focused question before searching the repository again.
 people, projects, or earlier decisions). Do not rely on the chat window or
 assume you know enough from the current conversation. Search with a focused
 question before investigating the repository.
 Inspect the relevant code and repository rules. Reproduce the problem when that
 helps. Decide the implementation details, edit files when asked, and test the
@@ -21,16 +21,9 @@ from memory_core import (
 PROTOCOL_VERSION = "2024-11-05"
 TOOL_NAME = "search_memories"
 TOOL_DESCRIPTION = (
-    "Search memories from earlier work in this repository. ALWAYS call this "
+    "Search memories from earlier work in this repository. Use it before "
-    "tool before answering anything that could depend on prior context: the "
+    "repeating investigation or when earlier decisions, fixes, commands, or "
-    "user's preferences, facts about this codebase, history, people, projects, "
+    "results may help."
    "or earlier decisions. Do not rely on the chat window alone. The "
    "repository's memory is shared by everyone who works in it and includes "
    "what it took to run, test, or build here, so search before assuming an "
    "invocation works. The scope argument changes what is searched: 'repo' "
    "(default) is the whole repository's shared memory plus your own "
    "preferences, 'dir' narrows the shared part to the directory you are "
    "working in, and 'mine' is your preferences alone."
 )
 TOOL_SCHEMA = {
    "type": "object",
@@ -29,7 +29,7 @@ from typing import Any, Iterable
 import telemetry
 DEFAULT_API_URL = "https://api.mem0.ai"
-PLUGIN_VERSION = "0.3.2"
+PLUGIN_VERSION = "0.3.3"
 _harness_name: str = "generic"
 _harness_env_prefix: str = "MEM0_PLUGIN"
@@ -71,15 +71,13 @@ MAX_FLUSH_ATTEMPTS = 5
 FORGET_PAGE_SIZE = 100
 FORGET_MAX_PAGES = 50
-PROJECT_MEMORY_INSTRUCTIONS = """Save concise repository facts that will help anyone with future coding work in this repository.
+PROJECT_MEMORY_INSTRUCTIONS = """Save concise repository facts that will help with future coding work.
 A completed change should produce one memory explaining the resulting behavior, where it is implemented when useful, and any important constraints or reasoning. Exploration or accepted decisions may produce separate memories only when they are independently useful.
-A command that failed and was then made to work should produce one memory naming the failing invocation, the error it returned, and the invocation that succeeded. Do not save one-off errors caused by an edit still in progress, transient network failures, or anything a rerun would fix on its own.
+Use the coding agent's final response for conclusions about current repository behavior. Do not save proposed or recommended changes unless the user accepted them or the coding agent completed them. Treat subagent responses as supporting repository evidence, not as decisions.
-Use the current coding agent's final response for conclusions about current repository behavior. Do not save proposed or recommended changes unless the user accepted them or the coding agent completed them. Treat subagent responses as supporting repository evidence, not as decisions.
+Write about the repository, not the user, assistant, session, or task. Do not include test results, documentation updates, release notes, or temporary state.
 Write about the repository, not the user, assistant, session, or task. Do not save personal preferences. Do not save a memory that only states which repository, branch, or directory the session worked in. Do not include test results, documentation updates, release notes, or temporary state.
 If nothing useful was established, return no memories."""
@@ -1,6 +1,6 @@
 {
  "id": "mem0",
-  "version": "0.3.2",
+  "version": "0.3.3",
  "homepage": "https://docs.mem0.ai/integrations/claude-code",
  "native": {
    "pluginRoot": "${CLAUDE_PLUGIN_ROOT}",
@@ -12,11 +12,9 @@ Call `search_memories` with the user's question. Treat `--top-k`, `--category`,
 query.
 Omit `top_k` to use Mem0's configured default. Omit `category` to search every
-category; a category is a best-effort label Mem0 assigned when it saved the
+category. Omit `scope` to use the configured default, normally `repo`: this
-memory, so if a category search misses, repeat it without the category. Omit
+repository's shared memory, which everyone who works in it contributes to,
-`scope` to use the configured default, normally `repo`: this repository's
+plus your own preferences.
 shared memory, which everyone who works in it contributes to, plus your own
 preferences.
 Pass `scope` when the question needs something else: `dir` to narrow the
 shared memory to the directory you are working in (a package inside a
@@ -1,8 +1,8 @@
 from __future__ import annotations
 import json
 import re
 import os
 import re
 import sqlite3
 import subprocess
 import sys
@@ -2307,8 +2307,8 @@ def test_sidekick_instructions_reject_unrequested_related_changes():
    prompt = (PLUGIN_ROOT / "agents" / "sidekick.md").read_text()
    normalized = " ".join(prompt.split())
    assert "Skill" in prompt.split("---", 2)[1]
-    assert "ALWAYS call `search_memories` before answering anything" in normalized
+    assert "call `search_memories` with a" in normalized
-    assert "Do not rely on the chat window" in normalized
+    assert "focused question before searching the repository again" in normalized
    assert "Complete only the work the main agent assigned" in normalized
    assert "Do not make related improvements" in normalized
    assert "report them separately" in normalized
@@ -4333,7 +4333,7 @@ def test_flush_sends_unified_body_with_both_agent_and_user_id(isolated_env, monk
    assert sent_body["run_id"] == "s1"
    assert "lane" not in sent_body["metadata"]
    assert "Save concise repository facts" in sent_body["agent_custom_instructions"]
-    assert "invocation that succeeded" in sent_body["agent_custom_instructions"]
+    assert "Write about the repository, not the user" in sent_body["agent_custom_instructions"]
    assert "Do not save repository facts" in sent_body["custom_instructions"]
    assert sent_body["custom_categories"] == memory_core.CODING_MEMORY_CATEGORIES
    store.close()
@@ -1,6 +1,6 @@
 {
  "name": "mem0",
-  "version": "0.3.2",
+  "version": "0.3.3",
  "description": "Cross-session memory and token savings for coding agents.",
  "author": { "name": "Mem0", "email": "support@mem0.ai" },
  "homepage": "https://docs.mem0.ai/integrations/codex",
@@ -21,16 +21,9 @@ from memory_core import (
 PROTOCOL_VERSION = "2024-11-05"
 TOOL_NAME = "search_memories"
 TOOL_DESCRIPTION = (
-    "Search memories from earlier work in this repository. ALWAYS call this "
+    "Search memories from earlier work in this repository. Use it before "
-    "tool before answering anything that could depend on prior context: the "
+    "repeating investigation or when earlier decisions, fixes, commands, or "
-    "user's preferences, facts about this codebase, history, people, projects, "
+    "results may help."
    "or earlier decisions. Do not rely on the chat window alone. The "
    "repository's memory is shared by everyone who works in it and includes "
    "what it took to run, test, or build here, so search before assuming an "
    "invocation works. The scope argument changes what is searched: 'repo' "
    "(default) is the whole repository's shared memory plus your own "
    "preferences, 'dir' narrows the shared part to the directory you are "
    "working in, and 'mine' is your preferences alone."
 )
 TOOL_SCHEMA = {
    "type": "object",
@@ -29,7 +29,7 @@ from typing import Any, Iterable
 import telemetry
 DEFAULT_API_URL = "https://api.mem0.ai"
-PLUGIN_VERSION = "0.3.2"
+PLUGIN_VERSION = "0.3.3"
 _harness_name: str = "generic"
 _harness_env_prefix: str = "MEM0_PLUGIN"
@@ -71,15 +71,13 @@ MAX_FLUSH_ATTEMPTS = 5
 FORGET_PAGE_SIZE = 100
 FORGET_MAX_PAGES = 50
-PROJECT_MEMORY_INSTRUCTIONS = """Save concise repository facts that will help anyone with future coding work in this repository.
+PROJECT_MEMORY_INSTRUCTIONS = """Save concise repository facts that will help with future coding work.
 A completed change should produce one memory explaining the resulting behavior, where it is implemented when useful, and any important constraints or reasoning. Exploration or accepted decisions may produce separate memories only when they are independently useful.
-A command that failed and was then made to work should produce one memory naming the failing invocation, the error it returned, and the invocation that succeeded. Do not save one-off errors caused by an edit still in progress, transient network failures, or anything a rerun would fix on its own.
+Use the coding agent's final response for conclusions about current repository behavior. Do not save proposed or recommended changes unless the user accepted them or the coding agent completed them. Treat subagent responses as supporting repository evidence, not as decisions.
-Use the current coding agent's final response for conclusions about current repository behavior. Do not save proposed or recommended changes unless the user accepted them or the coding agent completed them. Treat subagent responses as supporting repository evidence, not as decisions.
+Write about the repository, not the user, assistant, session, or task. Do not include test results, documentation updates, release notes, or temporary state.
 Write about the repository, not the user, assistant, session, or task. Do not save personal preferences. Do not save a memory that only states which repository, branch, or directory the session worked in. Do not include test results, documentation updates, release notes, or temporary state.
 If nothing useful was established, return no memories."""
@@ -1,6 +1,6 @@
 {
  "id": "mem0",
-  "version": "0.3.2",
+  "version": "0.3.3",
  "homepage": "https://docs.mem0.ai/integrations/codex",
  "native": {
    "pluginRoot": "${PLUGIN_ROOT}",
@@ -12,11 +12,9 @@ Call `search_memories` with the user's question. Treat `--top-k`, `--category`,
 query.
 Omit `top_k` to use Mem0's configured default. Omit `category` to search every
-category; a category is a best-effort label Mem0 assigned when it saved the
+category. Omit `scope` to use the configured default, normally `repo`: this
-memory, so if a category search misses, repeat it without the category. Omit
+repository's shared memory, which everyone who works in it contributes to,
-`scope` to use the configured default, normally `repo`: this repository's
+plus your own preferences.
 shared memory, which everyone who works in it contributes to, plus your own
 preferences.
 Pass `scope` when the question needs something else: `dir` to narrow the
 shared memory to the directory you are working in (a package inside a
@@ -1,6 +1,6 @@
 {
  "name": "mem0",
-  "version": "0.3.2",
+  "version": "0.3.3",
  "description": "Cross-session memory and token savings for coding agents.",
  "author": { "name": "Mem0", "email": "support@mem0.ai" },
  "homepage": "https://docs.mem0.ai/integrations/cursor",
@@ -21,16 +21,9 @@ from memory_core import (
 PROTOCOL_VERSION = "2024-11-05"
 TOOL_NAME = "search_memories"
 TOOL_DESCRIPTION = (
-    "Search memories from earlier work in this repository. ALWAYS call this "
+    "Search memories from earlier work in this repository. Use it before "
-    "tool before answering anything that could depend on prior context: the "
+    "repeating investigation or when earlier decisions, fixes, commands, or "
-    "user's preferences, facts about this codebase, history, people, projects, "
+    "results may help."
    "or earlier decisions. Do not rely on the chat window alone. The "
    "repository's memory is shared by everyone who works in it and includes "
    "what it took to run, test, or build here, so search before assuming an "
    "invocation works. The scope argument changes what is searched: 'repo' "
    "(default) is the whole repository's shared memory plus your own "
    "preferences, 'dir' narrows the shared part to the directory you are "
    "working in, and 'mine' is your preferences alone."
 )
 TOOL_SCHEMA = {
    "type": "object",
@@ -29,7 +29,7 @@ from typing import Any, Iterable
 import telemetry
 DEFAULT_API_URL = "https://api.mem0.ai"
-PLUGIN_VERSION = "0.3.2"
+PLUGIN_VERSION = "0.3.3"
 _harness_name: str = "generic"
 _harness_env_prefix: str = "MEM0_PLUGIN"
@@ -71,15 +71,13 @@ MAX_FLUSH_ATTEMPTS = 5
 FORGET_PAGE_SIZE = 100
 FORGET_MAX_PAGES = 50
-PROJECT_MEMORY_INSTRUCTIONS = """Save concise repository facts that will help anyone with future coding work in this repository.
+PROJECT_MEMORY_INSTRUCTIONS = """Save concise repository facts that will help with future coding work.
 A completed change should produce one memory explaining the resulting behavior, where it is implemented when useful, and any important constraints or reasoning. Exploration or accepted decisions may produce separate memories only when they are independently useful.
-A command that failed and was then made to work should produce one memory naming the failing invocation, the error it returned, and the invocation that succeeded. Do not save one-off errors caused by an edit still in progress, transient network failures, or anything a rerun would fix on its own.
+Use the coding agent's final response for conclusions about current repository behavior. Do not save proposed or recommended changes unless the user accepted them or the coding agent completed them. Treat subagent responses as supporting repository evidence, not as decisions.
-Use the current coding agent's final response for conclusions about current repository behavior. Do not save proposed or recommended changes unless the user accepted them or the coding agent completed them. Treat subagent responses as supporting repository evidence, not as decisions.
+Write about the repository, not the user, assistant, session, or task. Do not include test results, documentation updates, release notes, or temporary state.
 Write about the repository, not the user, assistant, session, or task. Do not save personal preferences. Do not save a memory that only states which repository, branch, or directory the session worked in. Do not include test results, documentation updates, release notes, or temporary state.
 If nothing useful was established, return no memories."""
@@ -1,6 +1,6 @@
 {
  "id": "mem0",
-  "version": "0.3.2",
+  "version": "0.3.3",
  "homepage": "https://docs.mem0.ai/integrations/cursor",
  "native": {
    "pluginRoot": "${CURSOR_PLUGIN_ROOT}",
@@ -12,11 +12,9 @@ Call `search_memories` with the user's question. Treat `--top-k`, `--category`,
 query.
 Omit `top_k` to use Mem0's configured default. Omit `category` to search every
-category; a category is a best-effort label Mem0 assigned when it saved the
+category. Omit `scope` to use the configured default, normally `repo`: this
-memory, so if a category search misses, repeat it without the category. Omit
+repository's shared memory, which everyone who works in it contributes to,
-`scope` to use the configured default, normally `repo`: this repository's
+plus your own preferences.
 shared memory, which everyone who works in it contributes to, plus your own
 preferences.
 Pass `scope` when the question needs something else: `dir` to narrow the
 shared memory to the directory you are working in (a package inside a
@@ -1,6 +1,6 @@
 {
  "name": "@mem0/deepseek-plugin",
-  "version": "0.3.1",
+  "version": "0.3.2",
  "description": "Mem0 long-term memory as a native DeepSeek Harness (Cordis) plugin.",
  "type": "module",
  "license": "Apache-2.0",
@@ -21,6 +21,11 @@ import { truncateOutput } from "./output.ts";
 import { resolveSearchFilters, resolveAddParams } from "./scoping.ts";
 import { captureEvent, errorKind } from "./telemetry.ts";
 import { createMemoryLifecycle } from "../../agent-plugin-core/typescript/src/lifecycle.ts";
 import {
  USER_RECALL_HEADING,
  USER_SEARCH_QUERY_DESCRIPTION,
  USER_SEARCH_TOOL_DESCRIPTION,
 } from "../../agent-plugin-core/typescript/src/prompts.ts";
 export const name = "mem0";
 export const inject = ["tools", "systemPrompt"];
@@ -107,7 +112,7 @@ export function apply(ctx: Context, config: Config): void {
  const stateFor = (session: object): SessionState => {
    let state = sessionStates.get(session);
    if (!state) {
-      const lifecycle = createMemoryLifecycle();
+      const lifecycle = createMemoryLifecycle({ recallHeading: USER_RECALL_HEADING });
      lifecycle.beginSession();
      state = { lifecycle, messages: [] };
      sessionStates.set(session, state);
@@ -197,10 +202,9 @@ export function apply(ctx: Context, config: Config): void {
  ctx.tools.register(
    defineTool({
      name: "search_memory",
-      description:
+      description: USER_SEARCH_TOOL_DESCRIPTION,
        "Search the user's long-term Mem0 memory for facts relevant to a query. Use proactively before answering anything that may depend on what the user told you earlier.",
      parameters: {
-        query: { type: "string", description: "What to recall.", required: true },
+        query: { type: "string", description: USER_SEARCH_QUERY_DESCRIPTION, required: true },
        limit: {
          type: "integer",
          description: `Max results to return (default ${DEFAULT_SEARCH_LIMIT}).`,
@@ -21,16 +21,9 @@ from memory_core import (
 PROTOCOL_VERSION = "2024-11-05"
 TOOL_NAME = "search_memories"
 TOOL_DESCRIPTION = (
-    "Search memories from earlier work in this repository. ALWAYS call this "
+    "Search memories from earlier work in this repository. Use it before "
-    "tool before answering anything that could depend on prior context: the "
+    "repeating investigation or when earlier decisions, fixes, commands, or "
-    "user's preferences, facts about this codebase, history, people, projects, "
+    "results may help."
    "or earlier decisions. Do not rely on the chat window alone. The "
    "repository's memory is shared by everyone who works in it and includes "
    "what it took to run, test, or build here, so search before assuming an "
    "invocation works. The scope argument changes what is searched: 'repo' "
    "(default) is the whole repository's shared memory plus your own "
    "preferences, 'dir' narrows the shared part to the directory you are "
    "working in, and 'mine' is your preferences alone."
 )
 TOOL_SCHEMA = {
    "type": "object",
@@ -29,7 +29,7 @@ from typing import Any, Iterable
 import telemetry
 DEFAULT_API_URL = "https://api.mem0.ai"
-PLUGIN_VERSION = "0.3.2"
+PLUGIN_VERSION = "0.3.3"
 _harness_name: str = "generic"
 _harness_env_prefix: str = "MEM0_PLUGIN"
@@ -71,15 +71,13 @@ MAX_FLUSH_ATTEMPTS = 5
 FORGET_PAGE_SIZE = 100
 FORGET_MAX_PAGES = 50
-PROJECT_MEMORY_INSTRUCTIONS = """Save concise repository facts that will help anyone with future coding work in this repository.
+PROJECT_MEMORY_INSTRUCTIONS = """Save concise repository facts that will help with future coding work.
 A completed change should produce one memory explaining the resulting behavior, where it is implemented when useful, and any important constraints or reasoning. Exploration or accepted decisions may produce separate memories only when they are independently useful.
-A command that failed and was then made to work should produce one memory naming the failing invocation, the error it returned, and the invocation that succeeded. Do not save one-off errors caused by an edit still in progress, transient network failures, or anything a rerun would fix on its own.
+Use the coding agent's final response for conclusions about current repository behavior. Do not save proposed or recommended changes unless the user accepted them or the coding agent completed them. Treat subagent responses as supporting repository evidence, not as decisions.
-Use the current coding agent's final response for conclusions about current repository behavior. Do not save proposed or recommended changes unless the user accepted them or the coding agent completed them. Treat subagent responses as supporting repository evidence, not as decisions.
+Write about the repository, not the user, assistant, session, or task. Do not include test results, documentation updates, release notes, or temporary state.
 Write about the repository, not the user, assistant, session, or task. Do not save personal preferences. Do not save a memory that only states which repository, branch, or directory the session worked in. Do not include test results, documentation updates, release notes, or temporary state.
 If nothing useful was established, return no memories."""
@@ -1,6 +1,6 @@
 {
  "name": "mem0",
-  "version": "0.3.2",
+  "version": "0.3.3",
  "description": "Cross-session memory and token savings for coding agents.",
  "keywords": ["memory", "coding-agents", "continual-learning", "token-efficiency"],
  "author": { "name": "Mem0", "email": "support@mem0.ai" },
@@ -1,6 +1,6 @@
 {
  "id": "mem0",
-  "version": "0.3.2",
+  "version": "0.3.3",
  "homepage": "https://docs.mem0.ai/integrations/kimi",
  "native": {
    "pluginRoot": "${KIMI_PLUGIN_ROOT}",
@@ -12,11 +12,9 @@ Call `search_memories` with the user's question. Treat `--top-k`, `--category`,
 query.
 Omit `top_k` to use Mem0's configured default. Omit `category` to search every
-category; a category is a best-effort label Mem0 assigned when it saved the
+category. Omit `scope` to use the configured default, normally `repo`: this
-memory, so if a category search misses, repeat it without the category. Omit
+repository's shared memory, which everyone who works in it contributes to,
-`scope` to use the configured default, normally `repo`: this repository's
+plus your own preferences.
 shared memory, which everyone who works in it contributes to, plus your own
 preferences.
 Pass `scope` when the question needs something else: `dir` to narrow the
 shared memory to the directory you are working in (a package inside a
@@ -21,16 +21,9 @@ from memory_core import (
 PROTOCOL_VERSION = "2024-11-05"
 TOOL_NAME = "search_memories"
 TOOL_DESCRIPTION = (
-    "Search memories from earlier work in this repository. ALWAYS call this "
+    "Search memories from earlier work in this repository. Use it before "
-    "tool before answering anything that could depend on prior context: the "
+    "repeating investigation or when earlier decisions, fixes, commands, or "
-    "user's preferences, facts about this codebase, history, people, projects, "
+    "results may help."
    "or earlier decisions. Do not rely on the chat window alone. The "
    "repository's memory is shared by everyone who works in it and includes "
    "what it took to run, test, or build here, so search before assuming an "
    "invocation works. The scope argument changes what is searched: 'repo' "
    "(default) is the whole repository's shared memory plus your own "
    "preferences, 'dir' narrows the shared part to the directory you are "
    "working in, and 'mine' is your preferences alone."
 )
 TOOL_SCHEMA = {
    "type": "object",
@@ -29,7 +29,7 @@ from typing import Any, Iterable
 import telemetry
 DEFAULT_API_URL = "https://api.mem0.ai"
-PLUGIN_VERSION = "0.3.2"
+PLUGIN_VERSION = "0.3.3"
 _harness_name: str = "generic"
 _harness_env_prefix: str = "MEM0_PLUGIN"
@@ -71,15 +71,13 @@ MAX_FLUSH_ATTEMPTS = 5
 FORGET_PAGE_SIZE = 100
 FORGET_MAX_PAGES = 50
-PROJECT_MEMORY_INSTRUCTIONS = """Save concise repository facts that will help anyone with future coding work in this repository.
+PROJECT_MEMORY_INSTRUCTIONS = """Save concise repository facts that will help with future coding work.
 A completed change should produce one memory explaining the resulting behavior, where it is implemented when useful, and any important constraints or reasoning. Exploration or accepted decisions may produce separate memories only when they are independently useful.
-A command that failed and was then made to work should produce one memory naming the failing invocation, the error it returned, and the invocation that succeeded. Do not save one-off errors caused by an edit still in progress, transient network failures, or anything a rerun would fix on its own.
+Use the coding agent's final response for conclusions about current repository behavior. Do not save proposed or recommended changes unless the user accepted them or the coding agent completed them. Treat subagent responses as supporting repository evidence, not as decisions.
-Use the current coding agent's final response for conclusions about current repository behavior. Do not save proposed or recommended changes unless the user accepted them or the coding agent completed them. Treat subagent responses as supporting repository evidence, not as decisions.
+Write about the repository, not the user, assistant, session, or task. Do not include test results, documentation updates, release notes, or temporary state.
 Write about the repository, not the user, assistant, session, or task. Do not save personal preferences. Do not save a memory that only states which repository, branch, or directory the session worked in. Do not include test results, documentation updates, release notes, or temporary state.
 If nothing useful was established, return no memories."""
@@ -1,7 +1,7 @@
 {
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "mem0",
-  "version": "0.3.2",
+  "version": "0.3.3",
  "description": "Cross-session memory and token savings for coding agents.",
  "author": {
    "name": "Mem0",
@@ -10,11 +10,9 @@ Call `search_memories` with the user's question. Treat `--top-k`, `--category`,
 query.
 Omit `top_k` to use Mem0's configured default. Omit `category` to search every
-category; a category is a best-effort label Mem0 assigned when it saved the
+category. Omit `scope` to use the configured default, normally `repo`: this
-memory, so if a category search misses, repeat it without the category. Omit
+repository's shared memory, which everyone who works in it contributes to,
-`scope` to use the configured default, normally `repo`: this repository's
+plus your own preferences.
 shared memory, which everyone who works in it contributes to, plus your own
 preferences.
 Pass `scope` when the question needs something else: `dir` to narrow the
 shared memory to the directory you are working in (a package inside a
@@ -2,7 +2,7 @@
  "id": "openclaw-mem0",
  "name": "Memory (Mem0)",
  "description": "Mem0 memory backend for OpenClaw — platform (mem0.ai cloud) or self-hosted open-source. Auto-recall and auto-capture are opt-in (disabled by default). Supports OpenAI, Anthropic, Ollama (fully local), Qdrant, and PGVector providers.",
-  "version": "1.2.0",
+  "version": "1.2.1",
  "kind": "memory",
  "skills": ["skills"],
  "commandAliases": [
@@ -1,6 +1,6 @@
 {
  "name": "@mem0/openclaw-mem0",
-  "version": "1.2.0",
+  "version": "1.2.1",
  "type": "module",
  "description": "Mem0 memory backend for OpenClaw — platform or self-hosted open-source",
  "license": "Apache-2.0",
@@ -1,4 +1,5 @@
 import { Type } from "@sinclair/typebox";
 import { USER_SEARCH_QUERY_DESCRIPTION, USER_SEARCH_TOOL_DESCRIPTION } from "../../agent-plugin-core/typescript/src/prompts.ts";
 import type { MemoryItem, SearchOptions } from "../types.ts";
 import type { ToolDeps } from "./index.ts";
@@ -8,9 +9,9 @@ export function createMemorySearchTool(deps: ToolDeps) {
  return {
    name: "memory_search",
    label: "Memory Search",
-    description: "Search long-term memories stored in Mem0 by semantic meaning. Use this proactively before answering when the request may depend on the user's past work, preferences, or decisions -- relevant memories are not always already in context. For multi-part or comparative questions, run several searches with different phrasings and combine the results rather than stopping after one (multi-hop).",
+    description: USER_SEARCH_TOOL_DESCRIPTION,
    parameters: Type.Object({
-      query: Type.String({ description: "Search query" }),
+      query: Type.String({ description: USER_SEARCH_QUERY_DESCRIPTION }),
      limit: Type.Optional(Type.Number({ description: `Max results (default: ${cfg.topK})` })),
      userId: Type.Optional(Type.String({ description: "User ID to scope search" })),
      agentId: Type.Optional(Type.String({ description: "Agent ID to search a specific agent's memories" })),
@@ -18,6 +18,7 @@ import {asScope, scopeSearchFilters, scopeWriteParams, resolveDefaultScope, SCOP
 import {parseProjectFromRemote} from "./project";
 import {resolveApiKey} from "./api-key";
 import {createMemoryLifecycle} from "../agent-plugin-core/typescript/src/lifecycle.ts";
 import {SEARCH_QUERY_DESCRIPTION, SEARCH_TOOL_DESCRIPTION} from "../agent-plugin-core/typescript/src/prompts.ts";
 async function getUserId(): Promise<string> {
  if (process.env.MEM0_USER_ID) return process.env.MEM0_USER_ID;
@@ -424,9 +425,9 @@ Identity context (resolved at plugin startup):
      }),
      search_memories: tool({
-        description: "Search stored memories by semantic meaning. Use this proactively before answering when the request may depend on the user's past work, preferences, decisions, or environment -- relevant memories are not always auto-injected. For multi-part or comparative questions, run several searches with different phrasings and combine the results rather than stopping after one (multi-hop).",
+        description: SEARCH_TOOL_DESCRIPTION,
        args: {
-          query: tool.schema.string().describe("Search query"),
+          query: tool.schema.string().describe(SEARCH_QUERY_DESCRIPTION),
          user_id: tool.schema.string().optional().describe("User ID"),
          app_id: tool.schema.string().optional().describe("App/Project ID"),
          agent_id: tool.schema.string().optional().describe("Agent ID"),
@@ -636,9 +637,6 @@ Identity context (resolved at plugin startup):
        }
        if (memoryCount > 0) {
          systemContext.push(
            "Search mem0 for recent decisions and task learnings before responding. Run 2 parallel searches: one for decision type, one for task_learning type.",
          );
          try {
            const res = await mem0.search(
              "recent session state decisions and learnings",
@@ -659,9 +657,6 @@ Identity context (resolved at plugin startup):
          }
        }
        systemContext.push(
          "Mem0 searches apply when user references past work, decision questions, errors, or non-trivial tasks. Queries use noun-phrases, 2-4 parallel calls with different metadata.type filters, and include user_id + app_id.",
        );
        systemContext.push(SCOPE_GUIDANCE);
        const activeScope = loadDefaultScope();
        if (activeScope !== "project") {
@@ -1,35 +1,19 @@
 ---
 name: mem0-context-loader
-description: Searches and injects relevant memories into context before starting work on a task. Use when beginning a new task, switching context, or when project history, past decisions, or coding conventions need to be loaded.
+description: Search memories from earlier OpenCode sessions in this repository. Use it when earlier work may already explain the code, error, decision, or command you need, so you can avoid repeating file reads, searches, or experiments.
 ---
 # Context Loader
 Pre-fetches relevant memories to prime context before working on a task.
 ## When to use
 - Session start (invoke manually or auto-triggered by skill description matching)
 - 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:
+2. **Call `search_memories` once** with a focused question about the task: `filters={"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}]}`, `top_k=10`.
-   | Query angle | Filter | Purpose |
+3. **Output compact context block** (max 10 memories):
   |---|---|---|
   | Feature/module name | `{"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}, {"metadata": {"type": "decision"}}]}` | Architecture decisions |
   | File paths mentioned | `{"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}, {"metadata": {"type": "convention"}}]}` | Coding patterns |
   | Error keywords (if any) | `{"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}, {"metadata": {"type": "anti_pattern"}}]}` | Known pitfalls |
   | Broad project context | `{"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}]}` | Catch-all |
 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>"
@@ -38,7 +22,7 @@ context-loader: loaded <N> memories for "<task summary>"
  - [anti_pattern] <content> [mem0:<short_id>]
 ```
-5. If **zero results**: output nothing. Don't announce empty context.
+4. If **zero results**: output nothing. Don't announce empty context.
 ## Constraints
@@ -27,14 +27,11 @@ When an ID is detected:
 ### Step 2: Search
-Run 2 parallel `search_memories` calls:
+Call `search_memories` once with the user's question: `query=<user's query>`, `filters={"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}]}`, `top_k=10`.
 1. Broad: `query=<user's query>`, `filters={"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}]}`, `top_k=10`, `rerank=true`
 2. Targeted: `query=<user's query>`, `filters={"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}, {"metadata": {"type": "decision"}}]}`, `top_k=5`, `rerank=true`
 ### Step 3: Display
-Deduplicate by ID, then show compact results:
+Show compact results:
 ```
 ## mem0 search: "<query>" (<N> results)
@@ -1,6 +1,6 @@
 {
  "name": "@mem0/opencode-plugin",
-  "version": "0.4.0",
+  "version": "0.4.1",
  "type": "module",
  "description": "Mem0 persistent memory plugin for OpenCode — add, search, and manage memories across sessions",
  "main": "dist/index.js",
@@ -71,7 +71,7 @@ The plugin includes 6 skills that guide the agent on how to use each capability:
 | Skill | Purpose |
 |-------|---------|
-| `context-loader` | Pre-fetch relevant memories at session start |
+| `context-loader` | Search memories when earlier work may already explain the task |
 | `remember` | Store facts with category classification |
 | `search` | Quick semantic search with compact results |
 | `forget` | Delete memories with confirmation |
@@ -1,6 +1,6 @@
 {
  "name": "@mem0/pi-agent-plugin",
-  "version": "0.3.1",
+  "version": "0.3.2",
  "type": "module",
  "description": "Mem0 memory extension for Pi Agent persistent, scoped, semantic memory across sessions and projects",
  "license": "Apache-2.0",
@@ -1,34 +1,19 @@
 ---
 name: context-loader
-description: Searches and injects relevant memories into context before starting work on a task or topic. Use when beginning a new task, switching context, or when past decisions, preferences, or knowledge need to be loaded.
+description: Search memories from earlier Pi sessions in this repository. Use it when earlier work may already explain the code, error, decision, or command you need, so you can avoid repeating file reads, searches, or experiments.
 ---
 # Context Loader
 Pre-fetches relevant memories to prime context before working on a task or topic.
 ## When to use
 - Session start (auto-triggered by the extension's `before_agent_start` event)
 - User starts work on a specific topic or area
 - User says "what do we know about X" or "context for X"
 ## Steps
 1. **Extract topics** from current message/task. Identify: subject areas, people mentioned, project names, goal references.
-2. **Run 2-4 parallel searches** using `mem0_memory` tool with `action="search"` and different query angles:
+2. **Call `mem0_memory` once** with `action="search"` and a focused question about the task.
-   | Query angle | Purpose |
+3. **Output compact context block** (max 10 memories):
   |---|---|
   | Topic/subject name | Relevant decisions and preferences |
   | People mentioned | Relationship context |
   | Project/goal references | Progress and background |
   | Broad context | Catch-all for anything relevant |
 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>"
@@ -37,7 +22,7 @@ context-loader: loaded <N> memories for "<task summary>"
  - [lessons] <content> [mem0:<short_id>]
 ```
-5. If **zero results**: output nothing. Don't announce empty context.
+4. If **zero results**: output nothing. Don't announce empty context.
 ## Constraints
@@ -1,4 +1,5 @@
 import { resolveToolScope } from "../../../agent-plugin-core/typescript/src/scoping.ts";
 import { SEARCH_QUERY_DESCRIPTION, SEARCH_WHEN } from "../../../agent-plugin-core/typescript/src/prompts.ts";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { StringEnum } from "@earendil-works/pi-ai";
@@ -144,11 +145,10 @@ export function registerMemoryTool(
    name: "mem0_memory",
    label: "Mem0 Memory",
    description:
-      "Search, add, update, and manage persistent semantic memories powered by Mem0. Memories persist across sessions and devices. Use action \"search\" proactively -- before answering anything that may depend on what the user told you earlier -- and run multiple searches with different phrasings for multi-part questions. Output is truncated to 200 lines / 50KB.",
+      `Search, add, update, and manage persistent semantic memories powered by Mem0. Memories persist across sessions and devices. Use action "search" ${SEARCH_WHEN}. Output is truncated to 200 lines / 50KB.`,
    promptSnippet: "Semantic memory search and storage via Mem0",
    promptGuidelines: [
-      'Use mem0_memory with action "search" proactively whenever the request may depend on the user\'s past work, preferences, decisions, or environment -- not only when they explicitly mention the past',
+      `Use mem0_memory with action "search" ${SEARCH_WHEN}`,
      'For multi-part or comparative questions, run several searches with different phrasings and combine the results before answering -- one search is rarely enough',
      'Use mem0_memory with action "add" to save important facts, preferences, goals, decisions, or lessons the user shares',
      'Use mem0_memory with action "update" to modify an existing memory — requires memory_id and content. Preserves the memory ID',
      "Always use the default project scope unless the user EXPLICITLY asks to search across all projects — only after the user selects /mem0-scope global use scope \"global\"",
@@ -166,13 +166,13 @@ export function registerMemoryTool(
        ] as const,
        {
          description:
-            "Memory operation to run: \"search\" (semantic recall -- use proactively before answering; run several with different phrasings for multi-part questions), \"add\" (save a new fact/preference/decision), \"get_all\" (list everything in scope, no query needed), \"update\" (replace an existing memory's text by id), \"delete\" (remove one memory by id), \"delete_all\" (wipe every memory in the scope -- destructive, only on explicit request).",
+            "Memory operation to run: \"search\" (semantic recall of earlier work in this repository), \"add\" (save a new fact/preference/decision), \"get_all\" (list everything in scope, no query needed), \"update\" (replace an existing memory's text by id), \"delete\" (remove one memory by id), \"delete_all\" (wipe every memory in the scope -- destructive, only on explicit request).",
        },
      ),
      query: Type.Optional(
        Type.String({
          description:
-            "Search text -- required for action \"search\". Use a focused noun-phrase; for multi-part questions run several searches with different phrasings.",
+            `Search text -- required for action "search". ${SEARCH_QUERY_DESCRIPTION}`,
        }),
      ),
      content: Type.Optional(
@@ -1,10 +1,9 @@
-export const MEMORY_POLICY = `<mem0-memory-policy>
+import { SEARCH_WHEN } from "../../agent-plugin-core/typescript/src/prompts.ts";
 You have persistent semantic memory via the mem0_memory tool, powered by Mem0. Relevant memories may be auto-injected under <mem0-relevant-memories>, but that retrieval is shallow — treat it as a starting point, not the full picture.
-Be proactive about retrieval:
+export const MEMORY_POLICY = `<mem0-memory-policy>
- Search memory BEFORE answering whenever the request could depend on the user's past work, preferences, decisions, environment, or anything they told you earlier — don't wait to be asked.
+You have persistent semantic memory via the mem0_memory tool, powered by Mem0. Relevant memories may be auto-injected under <mem0-relevant-memories>.
- Check memory before asking the user something they may have already told you.
+
- For multi-part, comparative, or "how did we…" questions, run SEVERAL searches with different phrasings and combine the results. One search is rarely enough — keep going until you have what you need (multi-hop).
+Use mem0_memory with action "search" ${SEARCH_WHEN}.
 Be proactive about saving:
 - Save important facts, preferences, goals, decisions, lessons learned, identity, relationships, and routines the user shares.
@@ -13,7 +13,7 @@
      },
      "category": "Productivity",
      "description": "Cross-session memory and token savings for coding agents.",
-      "version": "0.3.2"
+      "version": "0.3.3"
    }
  ]
 }