@everme/claude-code 0.4.0 → 0.4.2

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "everme",
       "source": "./",
       "description": "Automatic memory recall for Claude Code through the EverMe gateway. Saves and recalls per-session context using your EverMe account credentials.",
-      "version": "0.4.0",
+      "version": "0.4.2",
       "homepage": "https://everme.evermind.ai",
       "license": "Apache-2.0"
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "everme",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "EverMe — automatic memory recall for Claude Code. Recalls relevant context from past sessions before each prompt and saves new turns through the EverMe gateway.",
   "author": {
     "name": "EverMind AI",

package/README.md

@@ -11,7 +11,7 @@ Automatic memory recall + persistence for Claude Code, backed by the EverMe gate
 
 Plus:
 
-- **MCP server** exposing `everme_search` + `everme_context` tools for explicit recall.
+- **MCP server** exposing the canonical `mem_search` / `mem_context` / `mem_save_fact` / `mem_save_turn` tools for explicit recall and saves.
 - **Slash commands** `/recall <q>` and `/everme-help`.
 - **Skill** (`memory-tools`) that tells Claude when/how to use the search tool.
 
@@ -76,7 +76,7 @@ In a new Claude Code session:
 /recall the postgres composite index decision
 ```
 
-…should call `everme_search`, summarise hits, and cite memory subjects.
+…should call `mem_search`, summarise hits, and cite memory subjects.
 
 ## Files
 
@@ -89,7 +89,7 @@ hooks/scripts/inject-memories.js     UserPromptSubmit handler
 hooks/scripts/store-memories.js      Stop handler
 hooks/scripts/session-start.js       SessionStart handler
 hooks/scripts/session-summary.js     SessionEnd handler
-hooks/scripts/mcp-server.js          MCP server (everme_search / everme_context tools)
+hooks/scripts/mcp-server.js          MCP server (canonical mem_* tools)
 hooks/scripts/lib/adapter.js         Claude Code stdin/transcript/stdout adapter
 hooks/scripts/lib/run-hook.js        thin shared-runtime entry helper
 hooks/scripts/lib/config.js          Env-var resolution (emk vs evt)

package/commands/everme-help.md

@@ -14,7 +14,7 @@ Auth:      EVERME_API_KEY  (account emk_*) — recall-only mode
 Gateway:   EVERME_API_BASE — defaults to https://api.everme.evermind.ai
 
 Hooks:
-  SessionStart      → loads recent context from past sessions
+  SessionStart      → loads the durable Profile snapshot
   UserPromptSubmit  → recalls relevant memories before each prompt
   Stop              → saves the last raw turn through /mem/agent-memory
   SessionEnd        → no persistence; Stop owns runtime writes
@@ -24,6 +24,8 @@ Slash:
   /everme-help      — this card
 
 MCP tools:
-  everme_search     — ranked search
-  everme_context    — server-rendered context block
+  mem_search        — hybrid search across all memory buckets
+  mem_context       — durable Profile snapshot only
+  mem_save_fact     — save a durable user fact to the Profile path
+  mem_save_turn     — save a reusable task trajectory
 ```

package/commands/recall.md

@@ -8,10 +8,10 @@ arguments:
 
 # EverMe · recall
 
-You have access to two MCP tools backed by the EverMe gateway:
+Use the canonical EverMe MCP tools:
 
-- `everme_search` — ranked search with subject + summary + score.
-- `everme_context` — server-rendered context block (profile + recent episodes).
+- `mem_search` — hybrid search across episodic memories, profile entries, agent cases/skills, and the recent raw transcript.
+- `mem_context` — durable Profile snapshot only; it does not search past conversations and is not needed for this command.
 
 ## Query
 
@@ -19,8 +19,9 @@ You have access to two MCP tools backed by the EverMe gateway:
 
 ## Instructions
 
-1. Call `everme_search` with the query. Start with `topK: 10`.
-2. If the top results are clearly relevant (score ≥ 0.3), summarize the matched memories briefly and use them to answer or guide the next action.
+1. Call `mem_search` with a short version of the query. Start with `topK: 10`.
+2. If the returned memories are clearly relevant, summarize them briefly and use them to answer or guide the next action.
 3. If results are weak or empty, retry once with broader keywords. If still nothing useful, say so explicitly — do not fabricate context.
-4. When citing a memory, mention its subject (or session id) so the user can trace it back via `evercli` or the EverMe Web UI.
-5. NEVER paste the entire raw memory body verbatim if it's long; quote the salient parts only.
+4. Treat rows under "Recent unextracted transcript" as provisional, not as established facts or confirmed decisions.
+5. When citing a memory, mention its subject or session id when available so the user can trace it through `evercli` or the EverMe Web UI.
+6. NEVER paste an entire long memory body verbatim; quote only the salient parts.

package/hooks/scripts/mcp-server.js

@@ -1,19 +1,17 @@
 #!/usr/bin/env node
 /**
- * MCP server bundled with the Claude Code plugin. Exposes the
- * EverMe gateway's search + context endpoints as MCP tools so users
- * can ALSO recall memory manually via natural language ("search my
- * memory for the Postgres index thing"), even when the
- * UserPromptSubmit hook has already done implicit recall.
+ * MCP server bundled with the Claude Code plugin. Exposes the canonical
+ * EverMe four-tool catalogue (mem_search / mem_context / mem_save_turn /
+ * mem_save_fact — the same public ABI as @everme/memory-mcp and the Go
+ * hosted /mcp surface).
  *
  * Wire format: MCP stdio transport (JSON-RPC 2.0 framed by line).
  * We hand-roll the tiny subset Claude Code uses rather than pulling
  * in @modelcontextprotocol/sdk — keeps the install fast (no npm
- * install required) and the dependency surface minimal.
- *
- * Tools:
- *   everme_search   — POST /api/v1/mem/search
- *   everme_context  — POST /api/v1/mem/context (server-rendered prompt block)
+ * install required) and the dependency surface minimal. The canonical
+ * tools are a thin adapter over @everme/agent-sdk helpers — this
+ * package must NOT import @everme/memory-mcp (host packages depend on
+ * agent-sdk only).
  */
 
 import { createInterface } from "readline";
@@ -21,8 +19,11 @@ import { createRequire } from "node:module";
 import {
   buildMemoryPrompt,
   createClient,
+  getContext,
   searchMemory,
-  renderProfileBlock,
+  saveAgentMemory,
+  savePersonalMemory,
+  AGENT_MEMORY_ROLES,
   redactError,
   EvermeError,
 } from "@everme/agent-sdk";
@@ -52,29 +53,229 @@ function getClient() {
   return client;
 }
 
+// Instructions returned on initialize — Claude Code splices them into the
+// system prompt. Mirrors @everme/memory-mcp's EVERME_MCP_INSTRUCTIONS with
+// the Claude-Code-specific note that native hooks already inject
+// <everme_profile> / <everme_recall> and save turns automatically.
+const INSTRUCTIONS = [
+  "EverMe memory is connected. This plugin's native hooks already inject a",
+  "<everme_profile> block at session start and a <everme_recall> block before",
+  "each prompt, and they save the conversation automatically — so the tools",
+  "below are for the cases the hooks do not cover. Call them AUTONOMOUSLY when",
+  "a trigger fires; never wait for the user to say \"remember\" or \"recall\".",
+  "1. The <everme_recall> block is missing, empty, or clearly irrelevant AND the user references earlier conversations, decisions, conventions, or previously solved problems — call `mem_search` with a SHORT query. Do not repeat an identical query in the same turn.",
+  "2. The user states a durable fact about themselves (a preference, habit, trait, long-term goal, or decision) — call `mem_save_fact` immediately. Only `extracted:true` / `profileUpdated:true` means the profile really updated; on `no_extraction` do NOT tell the user the fact was remembered, and do not auto-retry.",
+  "3. A task was solved in a way worth reusing and the trajectory is NOT already captured by the hooks — call `mem_save_turn` with the COMPLETE trajectory. It feeds episodic / case / skill extraction; chat-dual-write backends may also update the Profile, reported by profileUpdated.",
+  "4. No <everme_profile> block was injected this session — call `mem_context` once. It returns the durable Profile ONLY (no search, no episodes).",
+].join("\n");
+
 const TOOLS = [
   {
-    name: "everme_search",
+    name: "mem_search",
     description:
-      "Search EverMe memories from past sessions. Returns ranked memory items with subject, summary, and relevance score. Use when the user asks about previous work, decisions, or context. Params: query (required), topK (default 10, max 25).",
+      "Search EverMe memory for entries relevant to a free-text query. " +
+      "Returns the top-K matching entries (episodic, profile, agent " +
+      "cases/skills, recent raw transcript) rendered as markdown; rows " +
+      "under the provisional transcript header are not yet extracted and " +
+      "must not be quoted as established facts.\n\n" +
+      "Call this proactively — without being asked — whenever the user " +
+      "references prior conversations, earlier decisions, project " +
+      "conventions, or previously solved problems (\"what did we say " +
+      "about X\", \"remember when…\", \"like last time\", \"did we fix " +
+      "this before\", \"continue where we left off\").\n\n" +
+      "Skip the call when the host already injected a non-empty, relevant " +
+      "<everme_recall> block this turn, and do not repeat an identical " +
+      "query within the same turn.\n\n" +
+      "`query` is KEYWORDS ONLY — the topic, not the conversation. Two to " +
+      "eight words, under ~100 characters, no sentences copied from the " +
+      "transcript. Never pass the user's whole message, a file, a log, a " +
+      "diff, or your own reasoning: the search embeds whatever you send, " +
+      "so boilerplate crowds out the topic and the results get worse. " +
+      "Good: \"oauth token rotation\". Bad: the last three turns pasted " +
+      "in. Rely on the default topK of 10; only raise it if a first " +
+      "search genuinely missed.",
     inputSchema: {
       type: "object",
       properties: {
-        query: { type: "string", description: "Search query — keywords or a question" },
-        topK: { type: "number", description: "Max results (default 10, max 25)" },
+        query: {
+          type: "string",
+          description:
+            "Keywords naming the topic to recall — two to eight words, " +
+            "under ~100 characters. Not a sentence from the transcript, " +
+            "not the user's whole message, not a pasted file or log.",
+        },
+        topK: { type: "integer", description: "Max entries to return", default: 10 },
       },
       required: ["query"],
     },
   },
   {
-    name: "everme_context",
+    name: "mem_context",
+    description:
+      "Read the current user's durable Profile snapshot ONLY. This tool " +
+      "never performs semantic search and never returns episodic memories, " +
+      "raw messages, agent cases, or agent skills.\n\n" +
+      "Call it ONCE at the start of a session, and only when no " +
+      "<everme_profile> block was injected. Do NOT use it as a fallback for " +
+      "recalling past decisions, old sessions, or task context — that is " +
+      "mem_search's job.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description:
+            "Deprecated and ignored — mem_context never performs semantic " +
+            "search. Kept for backwards compatibility only.",
+        },
+        forceRefresh: {
+          type: "boolean",
+          default: false,
+          description: "Bypass the server-side profile cache and re-read the upstream profile.",
+        },
+      },
+    },
+  },
+  {
+    name: "mem_save_turn",
+    description:
+      "Persist a conversation trajectory in realtime via /mem/agent-memory. " +
+      "Use sessionKey as conversationId.\n\n" +
+      "Call this when a task was solved in a way worth reusing AND the " +
+      "trajectory is not already captured by the plugin's automatic " +
+      "transcript save. Pass the COMPLETE round-trip — messages: [{role, " +
+      "content, timestamp?, toolCalls?, toolCallId?}] — EverOS only " +
+      "extracts agent_case / agent_skill from trajectories carrying the " +
+      "full tool round-trip.\n\n" +
+      "By default flush=true: extraction into episodic / agent_case / " +
+      "agent_skill runs right away. Pass flush=false for append-only " +
+      "accumulation. The primary trajectory path extracts episodic / case / " +
+      "skill memory; chat-dual-write backends may also update the user's " +
+      "Profile. Check profileUpdated for the derived profile verdict, and " +
+      "use mem_save_fact for deliberate durable user facts.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        role: {
+          type: "string",
+          enum: ["user", "assistant", "tool"],
+          description: "Role for the single-message form. Ignored when messages[] is set.",
+        },
+        text: { type: "string", description: "Content for the single-message form. Ignored when messages[] is set." },
+        timestamp: { type: "integer", description: "Unix milliseconds; defaults to now. Single-message form only." },
+        toolCallId: { type: "string", description: "Required when role=tool. Single-message form only." },
+        toolCalls: {
+          type: "array",
+          description:
+            "Tool invocations made by an assistant message. Required when " +
+            "the assistant called tools — without this the tool round-trip " +
+            "can never be reconstructed downstream and EverOS will not " +
+            "produce agent_case / agent_skill from the turn.",
+          items: {
+            type: "object",
+            properties: {
+              id: { type: "string" },
+              name: { type: "string" },
+              arguments: { type: "string", description: "JSON-encoded tool arguments (stringified, not an object)." },
+            },
+            required: ["id", "name", "arguments"],
+          },
+        },
+        messages: {
+          type: "array",
+          description:
+            "Multi-message trajectory. Preferred for recording a complete " +
+            "user → assistant{tool_use} → tool{tool_result} → assistant cycle.",
+          items: {
+            type: "object",
+            properties: {
+              role: { type: "string", enum: ["user", "assistant", "tool"] },
+              content: { description: "String text, or array of content items (text / image / doc)." },
+              timestamp: { type: "integer" },
+              toolCallId: { type: "string", description: "Required when role=tool." },
+              toolCalls: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    id: { type: "string" },
+                    name: { type: "string" },
+                    arguments: { type: "string" },
+                  },
+                  required: ["id", "name", "arguments"],
+                },
+              },
+            },
+            required: ["role"],
+          },
+        },
+        sessionKey: { type: "string", description: "Session id; defaults to 'default'." },
+        flush: {
+          type: "boolean",
+          default: true,
+          description:
+            "true (default) = trigger EverOS extraction into " +
+            "episodic_memory / agent_case / agent_skill after writing; " +
+            "false = append-only, messages are searchable as raw_messages " +
+            "only and extraction is deferred until a later flush. The " +
+            "default flipped from false to true because callers rarely " +
+            "issued an explicit follow-up flush, leaving trajectories " +
+            "permanently stuck as raw_messages with zero case/skill.",
+        },
+      },
+    },
+  },
+  {
+    name: "mem_save_fact",
     description:
-      "Fetch the server-rendered context block (profile + recent episodes) the gateway uses for prompt injection. Useful when you want a single ready-to-paste summary. Params: query (optional), topK (default 10).",
+      "Persist a durable fact about the USER (a preference, habit, trait, " +
+      "or decision) via the long-term PROFILE write path — the block loaded " +
+      "at the start of every session.\n\n" +
+      "Call this proactively, without being asked, the moment the user " +
+      "states something true about themselves that should outlive this " +
+      "conversation (\"I love summer\", \"sign my docs as Alice\").\n\n" +
+      "This is the direct profile-producing sibling of mem_save_turn — " +
+      "mem_save_turn primarily records trajectories, though chat-dual-write " +
+      "backends may derive a profile update. With flush=true (default) " +
+      "the call runs the synchronous materialise path and returns the real " +
+      "EverOS verdict: only `extracted:true` / `profileUpdated:true` " +
+      "confirms the fact reached the profile. `status:\"no_extraction\"` " +
+      "means the profile did NOT update — never claim the fact was " +
+      "remembered in that case, and do not auto-retry.",
     inputSchema: {
       type: "object",
       properties: {
-        query: { type: "string", description: "Optional query for relevance-biased context" },
-        topK: { type: "number", description: "Max items to include (default 10)" },
+        fact: {
+          type: "string",
+          description:
+            "A single user-stated fact, recorded as one user-role message. " +
+            "Ignored when messages[] is set.",
+        },
+        messages: {
+          type: "array",
+          description:
+            "Explicit user/assistant turns. Tool roles are not accepted on " +
+            "this path. Preferred when you want to capture both the user's " +
+            "statement and your acknowledgement.",
+          items: {
+            type: "object",
+            properties: {
+              role: { type: "string", enum: ["user", "assistant"] },
+              content: { description: "String text, or array of content items." },
+              timestamp: { type: "integer", description: "Unix milliseconds; defaults to now." },
+            },
+            required: ["role"],
+          },
+        },
+        sessionKey: { type: "string", description: "Session id; defaults to 'default'." },
+        flush: {
+          type: "boolean",
+          default: true,
+          description:
+            "true (default) = issue EverOS flush and return its verdict; " +
+            "false = skip extraction entirely (fact accepted but not in the " +
+            "profile block).",
+        },
       },
     },
   },
@@ -90,6 +291,7 @@ const handlers = {
       protocolVersion,
       capabilities: { tools: { listChanged: false } },
       serverInfo: { name: "everme", version: PKG_VERSION },
+      instructions: INSTRUCTIONS,
     };
   },
   "tools/list": () => ({ tools: TOOLS }),
@@ -101,14 +303,8 @@ const handlers = {
     }
     try {
       switch (name) {
-        case "everme_search": {
-          // Render the SDK bundle through buildMemoryPrompt — same
-          // path inject-memories.js uses for the auto-recall hook,
-          // and the same shape @everme/memory-mcp's mem_search tool
-          // returns. Earlier `JSON.stringify(res, null, 2)` forced the
-          // host LLM to peel a JSON envelope and decode escaped
-          // newlines before any of the section bullets were readable.
-          const topK = Math.min(Number(args.topK) || 10, 25);
+        case "mem_search": {
+          const topK = Math.min(Number(args.topK) || 10, 50);
           const res = await searchMemory(getClient(), { query: String(args.query || ""), topK });
           const body = buildMemoryPrompt(res, { wrapInCodeBlock: false });
           const header = `## EverMe search results for "${String(args.query || "")}"`;
@@ -118,23 +314,86 @@ const handlers = {
             : `${header}\n\n_(no matching memories)_`;
           return ok(redactError(text));
         }
-        case "everme_context": {
-          // getContext returns the gateway's raw shape
-          // {profile, cachedAt, generatedAt} — the markdown lives in
-          // res.profile as a structured object, NOT a string. Render
-          // via renderProfileBlock (same renderer session-start.js
-          // uses for the SessionStart hook injection) so the Tools
-          // path matches what users already see in the injected
-          // <everme_profile> block.
-          const res = await getClient().request("POST", "/mem/context", {});
-          // renderProfileBlock returns "" when profile exists but has no
-          // facts/traits yet (new account). Check the rendered output, not
-          // just the wrapper object, so the empty case yields a fallback
-          // message instead of an empty tool result.
-          const rendered = res?.profile ? renderProfileBlock(res.profile) : "";
-          const text = rendered || "_(no profile available — your EverMe account has no extracted memories yet)_";
+        case "mem_context": {
+          // Profile-only: `query` is accepted for compat but ignored.
+          const ctx = await getContext(
+            getClient(),
+            "",
+            { forceRefresh: args.forceRefresh === true },
+          );
+          const text = ctx?.context || "_(no profile available — your EverMe account has no extracted memories yet)_";
           return ok(redactError(text));
         }
+        case "mem_save_turn": {
+          let messages;
+          if (Array.isArray(args.messages) && args.messages.length) {
+            messages = args.messages.map(normaliseTurnMessage);
+          } else {
+            messages = [normaliseTurnMessage({
+              role: args.role || AGENT_MEMORY_ROLES.USER,
+              content: args.text,
+              timestamp: args.timestamp,
+              toolCallId: args.toolCallId,
+              toolCalls: args.toolCalls,
+            })];
+          }
+          const res = await saveAgentMemory(getClient(), {
+            conversationId: args.sessionKey || "default",
+            messages,
+            flush: args.flush !== false,
+          });
+          return okJson({
+            saved: !!res,
+            accepted: !!res,
+            status: res?.status || null,
+            messageCount: res?.messageCount || 0,
+            flushed: !!res?.flushed,
+            profileStatus: res?.personalStatus || null,
+            profileUpdated: !!res?.personalExtracted,
+          });
+        }
+        case "mem_save_fact": {
+          let messages;
+          if (Array.isArray(args.messages) && args.messages.length) {
+            const bad = args.messages.find(
+              (m) => m?.role !== AGENT_MEMORY_ROLES.USER && m?.role !== AGENT_MEMORY_ROLES.ASSISTANT,
+            );
+            if (bad) {
+              return errResp(
+                `mem_save_fact accepts only 'user' or 'assistant' roles; got ${JSON.stringify(bad?.role)}. ` +
+                  "The personal-memory path does not record tool turns — use mem_save_turn for trajectories.",
+              );
+            }
+            messages = args.messages.map((m) => ({
+              role: m?.role,
+              content: m?.content !== undefined ? m.content : m?.text,
+              timestamp: Number(m?.timestamp) || Date.now(),
+            }));
+          } else if (typeof args.fact === "string" && args.fact.trim()) {
+            messages = [{ role: AGENT_MEMORY_ROLES.USER, content: args.fact, timestamp: Date.now() }];
+          } else {
+            return errResp("mem_save_fact requires either `fact` or a non-empty `messages` array");
+          }
+          const res = await savePersonalMemory(getClient(), {
+            conversationId: args.sessionKey || "default",
+            messages,
+            flush: args.flush !== false,
+          });
+          if (!res) {
+            return errResp("mem_save_fact wrote nothing — every message had empty content after normalization");
+          }
+          return okJson({
+            saved: true,
+            accepted: true,
+            status: res?.status || null,
+            messageCount: res?.messageCount || 0,
+            flushed: !!res?.flushed,
+            extracted: !!res?.extracted,
+            // profileUpdated aliases extracted — the only signal that the
+            // fact really materialised into the profile.
+            profileUpdated: !!res?.extracted,
+          });
+        }
         default:
           return errResp(`unknown tool: ${name}`);
       }
@@ -148,10 +407,30 @@ const handlers = {
 function ok(text) {
   return { content: [{ type: "text", text: String(text ?? "") }] };
 }
+function okJson(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data ?? {}, null, 2) }] };
+}
 function errResp(msg) {
   return { isError: true, content: [{ type: "text", text: `error: ${msg}` }] };
 }
 
+// normaliseTurnMessage coerces an LLM-provided message into the SDK
+// agent-memory shape — accepts both legacy {role, text} and canonical
+// {role, content, toolCalls, toolCallId} forms. Mirrors the equivalent
+// helper in @everme/memory-mcp (kept local: host packages must not
+// import each other).
+function normaliseTurnMessage(m) {
+  const role = m?.role || AGENT_MEMORY_ROLES.USER;
+  const out = { role, timestamp: Number(m?.timestamp) || Date.now() };
+  if (m?.content !== undefined) out.content = m.content;
+  else if (m?.text !== undefined) out.content = String(m.text);
+  if (Array.isArray(m?.toolCalls) && m.toolCalls.length) out.toolCalls = m.toolCalls;
+  if (role === AGENT_MEMORY_ROLES.TOOL && (m?.toolCallId || m?.tool_call_id)) {
+    out.toolCallId = String(m.toolCallId || m.tool_call_id);
+  }
+  return out;
+}
+
 const rl = createInterface({ input: process.stdin, terminal: false });
 rl.on("line", async (line) => {
   let req;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everme/claude-code",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "type": "module",
   "description": "EverMe native plugin for Claude Code — automatic memory recall via SessionStart/UserPromptSubmit/Stop/SessionEnd hooks, plus /recall slash + bundled MCP server.",
   "license": "Apache-2.0",
@@ -8,7 +8,7 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "test": "node --test tests/redact.test.js tests/config.test.js tests/transcript.test.js tests/hooks.test.js tests/mcp-server.test.js"
+    "test": "node --test tests/redact.test.js tests/config.test.js tests/transcript.test.js tests/hooks.test.js tests/mcp-server.test.js tests/skills.test.js"
   },
   "files": [
     ".claude-plugin/",
@@ -21,7 +21,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@everme/agent-sdk": "^0.4.0"
+    "@everme/agent-sdk": "^0.4.2"
   },
   "keywords": [
     "evermind",

package/skills/memory-tools.md

@@ -1,30 +1,32 @@
 ---
-description: How and when to use EverMe memory tools to bring past-session context into the current Claude Code conversation.
+description: Use EverMe memory proactively when the user refers to previous conversations, earlier decisions, "last time", "remember when", existing project conventions, or previously solved errors, and save durable user preferences, habits, and decisions the moment they are stated. Do not repeat a search when a non-empty <everme_recall> block already exists.
 alwaysInclude: true
 ---
 
 # EverMe Memory Tools
 
-You have two MCP tools that surface memory persisted by EverMe across past Claude Code sessions:
+You have four canonical MCP tools for memory EverMe persists across past Claude Code sessions:
 
-- `everme_search` — semantic + keyword hybrid search over the user's memory store. Returns ranked items with subject, summary, score.
-- `everme_context` — fetch a server-rendered context block (profile + recent episodes) ready to inject into the current turn.
+Recall:
+- `mem_search` — semantic + keyword hybrid search over the user's memory store (episodic, profile, agent cases/skills, recent raw transcript). Rows under "Recent unextracted transcript" are provisional, not established facts.
+- `mem_context` — the user's durable Profile snapshot ONLY. It never searches and never returns episodes; do not use it to recall past decisions or task context.
 
-The plugin's UserPromptSubmit hook already injects relevant memory automatically before each prompt. You usually do NOT need to call these tools manually — they're for cases the auto-recall missed.
+Write:
+- `mem_save_fact` — save a durable user fact (preference, habit, trait, long-term decision). Call it proactively the moment the user states one ("以后文档签名用 Alice", "I hate Friday meetings") — do NOT wait for the user to say "remember this".
+- `mem_save_turn` — persist a complete task trajectory worth reusing. Chat-dual-write backends may also update the user's Profile; check `profileUpdated`. Use `mem_save_fact` for a deliberate durable fact.
 
-## When to use these tools
+## Dedupe protocol (hooks come first)
 
-**Do call** when:
-- The user references something they discussed before ("last time", "remember when", "we decided to use X")
-- The user asks about a project pattern, decision, or convention you have no inline context for
-- You're debugging an error message that may have been seen + resolved before
-- The auto-recall block (`<everme_recall>...</everme_recall>` in your context) is empty or clearly unrelated to the current task
-- The user explicitly asks you to "search my memory" / "recall" / "look up"
+The plugin's native hooks already inject `<everme_profile>` at session start and `<everme_recall>` before each prompt, and they save the conversation automatically. So:
 
-**Do NOT call** when:
-- The current message is self-contained and you can answer from inline context
-- You already searched in the current turn (don't duplicate)
-- It's a general-knowledge question with no project history component
+- If this turn already carries a non-empty, relevant `<everme_recall>` block — do NOT call `mem_search` for the same topic.
+- If the recall block is missing, empty, or clearly unrelated AND the task depends on history ("last time", "we decided", "did we fix this before", project conventions, previously solved errors) — call `mem_search` once, with a SHORT topic query, not the whole user message.
+- Never repeat an identical query within the same turn.
+- Call `mem_context` only when no `<everme_profile>` block was injected this session.
+
+## Save honesty
+
+`mem_save_fact` returns the real extraction verdict. Only `extracted: true` / `profileUpdated: true` means the profile updated — then you may tell the user the fact is remembered. On `status: "no_extraction"` the profile did NOT update: say so plainly, do not auto-retry, and do not claim success.
 
 ## Best practices