## Memory with the MCP bridge

Save, search, read, update and delete memories through the Decoy MCP bridge. It encrypts and decrypts memory values inside your trusted runtime.

Run `npx -y decoy-mcp-server@1.3.0` in a trusted Node.js 20+ runtime and connect a Streamable HTTP
MCP client to `http://localhost:3001/mcp`. Inspect actual `tools/list` before using this walkthrough.
For direct HTTP, use the [memory contract](https://www.decoys.me/docs/memory.md) and public helper;
the same save/read/update lifecycle applies. Run the bridge inside the environment that hosts
your MCP client, so that client can reach its local endpoint.

On first run, the bridge prints the approval link to https://decoys.me/connect. The person opens it in Decoy, reviews the access and approves. It stores its connection and key under `~/.decoy/` for reuse; a hosted runtime with no lasting disk supplies them as environment variables instead ([the MCP bridge: files, environment and recovery](https://www.decoys.me/agent-recipes.md#the-mcp-bridge-connection)). Without a browser, `--no-browser` returns the pairing link as JSON on stdout; `DECOY_MCP_PORT` changes the local port. Reuse the stored connection and key on subsequent runs.

The default memory tools are `add_memory`, `search_memories`, `get_memories`, `get_memory`, `update_memory`, `delete_memory`, and the topic tools `list_topics`, `read_topic`, `list_duplicate_topics`, `connect_topics`, `disconnect_topics`, `set_topic_parent` and `move_memories` (linking or moving a topic takes `memory.edit` on every topic it touches, removing a link `memory.delete`). Check the actual `tools/list` schema. The bridge handles encryption and keeps one user-owned store. Save directly into this memory store. Saving needs `memory.save`, which the bridge asks for when it connects; while you hold it, reading and correcting what this connection saved need nothing more. Deleting needs `memory.delete`. Other memories need `memory.read` by category or topic, or `acctmem.read` on an account.

Use `add_memory` for text/messages, `categories`, `topic` (with `topic_type` and `topic_link` when the topic is new), metadata and labeling fields. Call `list_topics` first and reuse a topic that fits. `topic_link` is the new topic's [connection](https://www.decoys.me/agent-memories.md#connections) on the person's Map: give the relation that is true for this person and this subject, and `to` an existing topic when the new one is part of it; the default is only for when nothing more specific is true. `update_memory` changes a memory's text, categories or topic in place and takes `expected_rev`.

`add_memory` can retain several categories; a matching category grant on any of them reaches the memory.

### Save and use a memory

These are MCP arguments. The sentences below illustrate the shape; use grounded information the person has authorized you to save. Treat later recall, correction and deletion as actions to take when applicable, not a required setup test:

1. `add_memory({"text":"Memory walkthrough: prefers short answers.","categories":["user_preferences"],"topic":"Communication preferences","topic_link":{"relation":"asks agents to follow"}})`; retain the returned ID, or the existing duplicate ID. The relation fits this sentence; write the one that fits yours.
2. `get_memory({"memory_id":"<returned ID>"})`; verify the sentence from stored content.
3. In a later session, start the bridge with the same credentials and key and call `get_memory` again. Use the retrieved content for recall.
4. When correcting that preference, use `update_memory({"memory_id":"<returned ID>","text":"Memory walkthrough: prefers short answers with examples.","expected_rev":<rev from step 2>})`; read the same ID independently again. The ID, topic and categories stay; if the memory changed since your read, nothing is written and the error says to re-read.
5. When the person asks to forget it, use `delete_memory({"memory_id":"<returned ID>"})` (it needs `memory.delete`) and confirm the requested deletion. Keep unrelated memories.

For account labeling, supply `app_id` with a known account name/ID. A match labels the memory; an unknown name remains a hint and does not prevent saving.

Invite the person to review or edit their saved memories in Decoy. Editing someone else's memory needs `memory.edit`; deleting any memory needs `memory.delete`. A read-only connection must not report a refused mutation as successful.

Use `request_access({"permissions":["memory.read"],"datatypes":["travel"],"reason":"Use your saved travel preferences for this trip"})` only when the agreed task needs other travel memories. `about` selects topics instead (a topic name works); no selection means all memories. Do not request personal info to unlock memories.

The optional graph tools and `memory://knowledge-graph` expose the same store; enable `DECOY_MEMORY_GRAPH=true` for clients requiring the MCP Memory graph contract. Graph delete results use `structuredContent: {success, message}`; a completed call can still contain a refusal, so inspect the message and read back. The default tools have their own documented results; do not assume that graph shape for them.

Keep the user's experience simple: save established preferences quietly, search relevant memories before helping, correct outdated facts, and respect edits/removals. Decoy cannot read encrypted memory values; the agent/provider can. Revocation stops future serving, not cached copies.

[Memory guide](https://www.decoys.me/docs/memory.md) · [Access](https://www.decoys.me/docs/access.md) · [Sync](https://www.decoys.me/docs/sync.md)
