---
name: everme-memory
description: |
  Use EverMe cloud 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 the host already injected a non-empty
  <everme_recall> block this turn.
---

# What it gives you

When this plugin is loaded, the host has these MCP tools available:

| tool            | input                                                          | output (markdown / JSON)                                    |
|-----------------|----------------------------------------------------------------|-------------------------------------------------------------|
| `mem_context`   | `{ forceRefresh? }` (`query` deprecated/ignored)               | markdown Profile snapshot — Profile ONLY, never a search    |
| `mem_search`    | `{ query, topK? }`                                             | markdown search results across all memory buckets           |
| `mem_save_fact` | `{ fact \| messages, sessionKey?, flush? }`                   | `{ saved, accepted, status, extracted, profileUpdated, … }` |
| `mem_save_turn` | `{ role, text \| messages, sessionKey?, toolCallId?, flush? }` | `{ saved, accepted, status, messageCount, flushed, profileStatus, profileUpdated }` |

# Recommended usage

**Call these tools autonomously — the moment a trigger fires, not only
when the user explicitly asks you to "remember" or "recall".** Each
tool's MCP `description` also carries its trigger, so hosts that don't
surface the server `instructions` still get the same guidance.

**Dedupe with native injection first.** Some hosts inject
`<everme_profile>` at session start and `<everme_recall>` before each
prompt via native hooks. When a non-empty, relevant block is already in
your context, do not fetch the same data again through these tools; when
the block is missing or clearly unrelated and the task depends on
history, call the tools proactively.

## At the start of a session — `mem_context`

If no `<everme_profile>` block was injected, call `mem_context` once
before answering the first user message. It returns the user's durable
Profile ONLY — no semantic search, no episodes, no raw transcript. Call
it **once per session**; pass `forceRefresh: true` only when the user
explicitly asks to refresh. Never use it as a fallback for recalling
past decisions or task context — that is `mem_search`'s job.

## When the user references prior context — `mem_search`

Call `mem_search` when the user points back at earlier conversations,
decisions, conventions, or previously solved problems ("what did we say
about X", "remember when…", "like last time", "did we fix this
before"). **Keep `query` short** — a few keywords or one short phrase
naming the topic; do NOT paste in the whole conversation. Rely on the
default `topK` of 10; only raise it if a first search genuinely missed.
Do not repeat an identical query within the same turn.

Results cover episodic memories, profile entries, agent cases/skills,
and the recent raw transcript. Rows under "Recent unextracted
transcript" are provisional — not yet extracted — never quote them as
established facts or confirmed decisions.

## When the user states a durable fact — `mem_save_fact`

When the user says something true about themselves that should outlive
this conversation (a preference, habit, trait, long-term goal, or
decision), call `mem_save_fact` — without waiting to be asked. Only
`extracted: true` / `profileUpdated: true` confirms the fact reached
the profile; on `status: "no_extraction"` the profile did NOT update —
say so plainly, do not auto-retry, and do not claim success.

## To capture how a task was solved — `mem_save_turn`

When a task is solved in a way worth reusing, call `mem_save_turn` with
the complete trajectory (user → assistant tool calls → tool results →
final answer). It feeds episodic / agent_case / agent_skill extraction.
On chat-dual-write backends, the derived user/assistant transcript may also
update the user's Profile; check `profileUpdated` for that verdict.
`sessionKey` becomes the conversation id; use a stable value for the whole
chat. Use `mem_save_fact` for a deliberate durable fact rather than relying
on the derived chat write. If your host's native hooks already saved the turn,
do not save it again.

# Error handling

Tools return `isError: true` with `content[0].text` carrying a short
description on failure. Common shapes:

- `auth` — emk/evt revoked or expired. Re-run `evercli auth login`
  and `evercli plugin install <agent>` to refresh.
- `network` — backend unreachable; retry with backoff.
- `upstream` — backend returned non-zero status. The error message
  includes the requestId for support correlation.

Cold-start memory (everything the user already had) is loaded by
`evercli import run`; you don't need to re-upload it from inside the
agent.