everme-memory

# 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 conversations run`; you don't need to re-upload it from inside the agent.