everme-memory · diff
v0.1.0 to git:20260803.9e60f97
51 added, 30 removed. Audit A to A.
---
name: everme-memory
- description: Real-time access to EverMe cloud memory from AI Agents (Claude Code, OpenClaw, …)
- version: 0.1.0
+ 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` | `{ query }` | markdown context block (profile + episodes) |
- | `mem_search` | `{ query, topK? }` | markdown search results |
- | `mem_save_fact` | `{ fact \| messages, sessionKey?, flush? }` | `{ saved, status, extracted, … }` |
- | `mem_save_turn` | `{ role, text \| messages, sessionKey?, toolCallId?, flush? }` | `{ saved, status, messageCount, flushed }` |
+ | 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.
- ## At the start of a session — `mem_context`
+ **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.
- Call `mem_context` once with the user's first message as the `query`,
- before answering it. Splice the returned markdown into your reasoning
- context. The server already returns a trimmed, relevance-ranked block,
- so call it **once per session**, not on every turn.
+ ## At the start of a session — `mem_context`
- ```ts
- const context = await tools.mem_context({ query: userPrompt });
- if (context) systemAddition += "\n" + 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 or
- decisions ("what did we say about X", "remember when…", "like last
- time"). **Keep `query` short** — a few keywords or one short phrase
- naming the topic; do NOT paste in the whole conversation or the full
- user message, a long query searches worse and bloats the request. Rely
- on the default `topK` of 5; only raise it if a first search genuinely
- missed.
+ 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, or decision), call
- `mem_save_fact` so it lands in their long-term profile. Only
- `extracted: true` confirms the fact reached the profile.
+ 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 trajectory. It writes synchronously through `/mem/agent-memory` and
- does not create `/mem/sources`. `sessionKey` becomes the conversation
- id; use a stable value for the whole chat.
+ 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.