---
name: mercury-memory
description: Long-term memory for the user through Mercury. Use it to recall what the user told you in earlier sessions (preferences, people, projects, decisions, past facts, "what did I say about…") before answering, to remember new facts, preferences, plans and corrections the user states, and to forget things when the user asks. Use the Mercury MCP tools when connected, or the Mercury REST API with MERCURY_API_KEY otherwise.
---

# Mercury memory

Mercury is the user's long-term memory across conversations and tools. It keeps what the user says verbatim, works out what is worth remembering, records when a fact was replaced (and whether it was an update or a correction), keeps outside sources apart from the user's own word, and forgets for real on request. Server: https://34-13-60-151.sslip.io

## When to use it

**Recall before answering** when the answer could depend on anything the user said before:
- their preferences, setup, tools, people, projects, plans, past decisions;
- questions like "what did I say about…", "when did I…", "which X do I use";
- any task where knowing their context would change what you do: write code their way, use their stack, respect their constraints.

Skip recall for self-contained questions (general knowledge, a file already open in front of you).

**Remember** whenever the user states something worth keeping beyond this conversation:
- a fact about themselves or their work ("I'm moving to Leeds in May", "our API is in Go");
- a preference or standing instruction ("always use pnpm", "keep PRs under 300 lines");
- a decision, plan or correction ("actually the deadline is Friday").

Store the user's own words, one message per call. Do not paraphrase, summarise or add your own inferences: Mercury decides what to keep. Do not store pleasantries, secrets (passwords, keys, card numbers) or anything the user asks you not to keep.

**Forget** when the user asks ("forget where I live", "delete what you know about my job"): pass their request as they said it.

## With the MCP tools (preferred)

| Tool | Use |
|---|---|
| `recall(question)` | Before answering. Read the whole sheet. |
| `remember(text, source="user")` | The user's words, verbatim. Returns an event id. |
| `remember(text, source="web" or "email" or "tool")` | Outside content worth keeping. It is labelled and never overrides the user. |
| `forget(request="…")` or `forget(event_ids=[…])` | On request. Confirm to the user afterwards. |
| `history(query)` / `as_of(date)` | "When did that change?" / "what was true in March?" |
| `open_questions()` → ask the user → `answer_question(id, yes)` | When Mercury is unsure. |
| `start_task(id, goal)` … `end_task(id, outcome)` | Multi-step work, so lessons are kept for next time. |

## Reading the memory sheet

The sheet groups items. Trust them in this order:
1. **What the user has said (still current).** Treat it as true. Each line says since when.
2. **Earlier information that has since been replaced.** Do not present it as current. Use it only for questions about the past.
3. **Things asked about, considered or denied.** Not established. "Should I move to Oslo?" does not mean they live in Oslo.
4. **Outside sources (not confirmed by the user).** Mention them as what a source said, never as fact.
5. **Open questions (ask the user rather than guess).** If one bears on the answer, ask it.

If the sheet has nothing relevant, say you don't have that information rather than guessing. Never invent memories.

## Without the MCP tools (REST fallback)

Use this when the MCP server isn't connected but `MERCURY_API_KEY` is set in the environment. The space defaults to `me`.

```bash
SPACE=${MERCURY_SPACE:-me}
# recall
curl -s https://34-13-60-151.sslip.io/v1/spaces/$SPACE/recall -H "Authorization: Bearer $MERCURY_API_KEY" \
  -H "content-type: application/json" -d '{"question": "Which package manager do I use?"}' | python3 -c "import sys,json; print(json.load(sys.stdin)['text'])"
# remember (the user's own words)
curl -s https://34-13-60-151.sslip.io/v1/spaces/$SPACE/events -H "Authorization: Bearer $MERCURY_API_KEY" \
  -H "content-type: application/json" -d '{"events": [{"text": "I prefer pnpm over npm", "role": "user", "source": "user"}]}'
# forget, in the user's words
curl -s https://34-13-60-151.sslip.io/v1/spaces/$SPACE/events -H "Authorization: Bearer $MERCURY_API_KEY" \
  -H "content-type: application/json" -d '{"events": [{"text": "Please forget where I live", "role": "user", "source": "user"}]}'
```

Build the JSON safely (for example with `python3 -c 'import json,sys; print(json.dumps(...))'`) when the text contains quotes. Never print or log the API key.

## Good habits

- Recall once per topic, not before every message.
- When you use a remembered fact, you can say so briefly ("you mentioned you use pnpm").
- If the user corrects a remembered fact, store the correction in their words; Mercury replaces the old fact.
- If a recall fails (no key, network, quota used up), carry on without memory and tell the user once.

Docs: https://34-13-60-151.sslip.io/docs