MnemoverseDocs

Appearance

Make Your Agent Use Memory ​

Connecting Mnemoverse gives your agent the memory tools. It does not guarantee the agent uses them. This page is the difference between "I installed it and nothing happened" and an agent that calls memory_read and memory_write without being reminded each time.

First, confirm the tools work ​

Everything after this section assumes the memory tools are loaded and your key or sign-in is accepted. Several setup faults look exactly like an agent that ignores memory, and no instruction fixes them. Rule them out first.

Ask the agent: "Call the memory_stats tool and show me exactly what it returns." (A ChatGPT Custom GPT names this action getMemoryStats.)

  • It returns counts. The connection works. Zero is normal on a new account. Go on to set up your agent.
  • It has no such tool, or the call returns an error. Fix the connection before you add any instruction.

A tool list alone does not prove the connection works. The local server starts and lists its tools even when the key is missing or wrong. A rejected key shows up only as one line on the server's stderr at startup and as an error on every tool call. The usual silent failures:

What you seeUsual causeWhat to do
The tools are listed, but every call is refusedThe config still holds the placeholder mk_live_YOUR_KEY, or a key the server rejectsPut your own key in the client config and restart the client.
The tools were there before and are now goneThe OAuth connector was dropped after you signed out, switched accounts, or the host app signed you in again. Your memories are untouched.Sign in to the connector again. See what an account switch does to your connection.
memory_stats works but reports none of the memories you savedThe key comes from a different console account than the one that stored them. That account's store is empty, and nothing reports an error.Use a key from the account you saved with. See memories or rooms are gone.
Reads work, memory_write does notThe connector's token has only memory:read, which can recall but not write: the client did not ask for memory:write, and the consent screen grants only what the client asks forReconnect, and check that the consent screen lists Store and update your memories (Remote MCP Server troubleshooting). In ChatGPT, also read the plan notes on ChatGPT.
VS Code: the chat never calls a memory toolThe Mnemoverse tools are deselected in the tool listCheck that the Mnemoverse tools are selected (see below). Also check that the agent picker is on Agent. That is the first step of VS Code's tools guide for a request that uses tools.

Where to see what the client actually loaded:

  • Claude Code: claude mcp list shows each server's health, such as ✔ Connected or ! Needs authentication, and /mcp lets you re-authenticate. For the local server, connected means the process started, not that the key was accepted.
  • Claude Desktop and claude.ai: a connector can be switched off for a single conversation, from the + button in the chat input, then Connectors. Make sure Mnemoverse is on. Setup is on Claude Desktop, Web & Mobile.
  • VS Code: MCP: List Servers in the Command Palette lists each server; select one and choose Show Output for its log. Which tools the chat may use depends on the harness: with the Local harness, the Configure Tools button in the chat input; with the Copilot harness, the Tools tab of the Agent Customizations editor (Chat: Open Customizations).
  • ChatGPT (custom MCP server): the plugin has to be installed. OpenAI's Plugins in ChatGPT article says "ChatGPT automatically uses your installed plugins when they're relevant to your request", and you can also pick it yourself: the Add custom MCP server guide says "In the prompt box, type @ and select your installed plugin." (both read 2026-10-24). Setup is on ChatGPT.
  • Cursor: see Cursor.
  • Devin Desktop (formerly Windsurf): Open customizations, in the new-tab menu of an agent space, lists the MCP servers a Devin Local session loaded (Devin Desktop).

If memory_stats works but recall still comes back empty, work through the checks under Try It on the MCP Server page. Once the key works, the checks left are two different keys across your tools, missing memory rules, and the read itself: an unscoped read does not search shared rooms, and memory_read ranks by meaning, so a complete recent list needs memory_list_recent.

Why your agent ignores memory ​

When you connect Mnemoverse (via the VS Code extension, Claude Code, or an MCP config), your agent gains 11 tools: the core memory tools (memory_read, memory_write and the rest), the Beta shared-room tools, and vault_list. The MCP server page lists them all.

But a tool being available is not the same as the agent calling it. On every message the model decides, on its own, whether a tool is relevant — and it decides from the tool's name and description. If nothing in the conversation strongly signals "use memory now," the model often just answers, or uses its own short-term context, and your Mnemoverse memory sits untouched.

The result: in a new session you ask about something you settled last week, and the agent answers from scratch without calling memory_read. The tools work; the habit is missing. The server does not supply it: its instructions and tool descriptions say what each tool does and when it applies, not that the agent should use memory without being asked. When the agent reaches for memory is your decision, and the memory rules below are how you give it.

Set up your agent: add the memory rules ​

You could ask for memory in every chat: "check memory first", "save this". A request like that lasts for one chat. Rules in your agent's instructions do not need repeating: the host loads them at the start of every session, as your own instructions.

Editor rule files need one more step. Cursor includes a rule file on every message only when its frontmatter sets alwaysApply: true, and of the trigger values Devin Desktop (formerly Windsurf) accepts, only always_on is documented as active in every session with no user action. See Editor rule files need frontmatter.

These are the memory rules. Copy them as they are into the place the table below names for your tool:

markdown
## Memory (Mnemoverse)
- Before answering something that may depend on an earlier session (my preferences, past decisions, project setup, people), search memory with memory_read.
- When I state a lasting preference or make a decision, or you learn a durable fact about this project, save it with memory_write as one self-contained statement. You do not need to ask me first.
- When a message also carries a durable fact (who now owns or does what, a lesson learned, a new convention), save that fact with memory_write before doing the rest of the task.
- After acting on recalled memories, rate them with memory_feedback: helpful or not. For a shared room's memories, pass the room's address as domain; a read-only member cannot rate them.
- Never store passwords, API keys, payment data, MFA codes, government IDs, or health records.

Each line covers one moment: reading before an answer that may depend on an earlier session, saving a lasting preference, decision or project fact, saving a fact that arrives together with a task, and rating what was recalled. Ratings re-rank what comes back next. The last line keeps secrets out of memory. The setup_memory prompt produces this same text.

One habit the rules leave to the client that builds the prompt: do not recall what the conversation already holds. An entry already in the context window is not read again, and when a later turn needs a fresh recall, the memory block in the prompt is replaced, not appended, so the model never sees two copies of the same entry. The hosted connector cannot do this for you: by protocol it is stateless and does not know what your conversation contains.

Get the rules from the setup_memory prompt ​

The Mnemoverse MCP server carries a prompt, setup_memory, that produces the rules on demand. Run it, and your agent shows the rules, says where they go for your tool, and offers to add them for you.

  • Claude Code: run /mcp__mnemoverse__setup_memory. To get only the Claude Code place, add the host: /mcp__mnemoverse__setup_memory claude-code. The command carries the server's name, mnemoverse when you added it with claude mcp add. If the server came from the Mnemoverse plugin or from a connector you added on claude.ai, its name is different, so type / and pick the setup_memory entry marked (MCP). Claude Code's MCP documentation describes both forms.
  • Other clients: pick setup_memory from the list where the client shows a server's prompts.

The optional host argument takes claude-code, claude-ai, cursor or codex. Without it, you get every place in the table's first four rows. The MCP Server page lists the server's other prompts.

Where to put it ​

Put the rules into whichever file or settings field your tool reads as standing instructions. The first four rows are the places the setup_memory prompt names. If several apply to your setup, the cross-tool AGENTS.md is the most portable home; the tool-specific files take priority where a tool supports both.

ToolWhereNotes
Claude CodeCLAUDE.md in the project root, or ~/.claude/CLAUDE.md for every projectLoaded into context every session.
Claude on the web, desktop or mobileSettings, under Instructions for Claude (all chats), or a Project's instructions (chats in that project)No file. Paste the rules as text. Anthropic: personalization features.
Cursor.cursor/rules/mnemoverse-memory.mdcNeeds alwaysApply: true in the frontmatter (below). Without it, and with no description or globs, Cursor includes the rule only when you @-mention it. A root AGENTS.md or CLAUDE.md needs no frontmatter. .cursorrules is legacy.
Codex, and other agents that read AGENTS.mdAGENTS.md in the project rootThe cross-tool file; read by a growing set of agents.
GitHub Copilot (VS Code).github/copilot-instructions.mdRepo-level custom instructions. VS Code applies them to all chat requests in the workspace (custom instructions).
Devin Desktop (formerly Windsurf).devin/rules/mnemoverse.md (older setups: .windsurf/rules/)Set trigger: always_on in the frontmatter (below). A root AGENTS.md needs no frontmatter.
ChatGPT (Custom GPT)The GPT's Instructions fieldUse the prompt in ChatGPT setup, step 4 instead of these rules: a Custom GPT calls actions named readMemory and writeMemory, not the MCP tool names.
ChatGPT (custom MCP server)Settings → Personalization → Custom Instructions, and a Project's instructions for chats in that projectOpenAI's custom instructions article describes them as anything "you'd like ChatGPT to consider in its response", applied to all chats. Inside a Project they give way: "Project instructions apply only within that project and override your global custom instructions" (Projects in ChatGPT), so put the rules in the Project's instructions as well. The rules work on top of OpenAI's own behaviour: "ChatGPT automatically uses your installed plugins when they're relevant to your request" (Plugins in ChatGPT), and the app's permission setting decides when ChatGPT asks you first. Permission settings "determine when ChatGPT asks before reading information or taking an action", and Allow read actions is one of the options (Connected apps in ChatGPT). The Add custom MCP server guide also suggests naming the app and the tool in your prompt, for example "Be explicit: Use the "Acme CRM" app's "update_record" tool to …" (all read 2026-10-24).

Where the target is a file, commit it so the rules travel with the repo and every teammate's agent inherits the habit. The settings-based rows (the Claude apps and both ChatGPT paths) hold per account, so each teammate sets those up once for themselves.

Editor rule files need frontmatter ​

In Cursor and Devin Desktop the file name is not enough. Put the frontmatter lines shown for your editor above the rules.

Cursor, .cursor/rules/mnemoverse-memory.mdc:

markdown
---
alwaysApply: true
---

(paste the memory rules here)

Cursor's rules documentation says a rule with alwaysApply: true is "Always included. Globs and description are ignored." A rule with alwaysApply: false and no description or globs is "Included only when you @-mention the rule in chat." The extension matters too: Cursor ignores a plain .md file in .cursor/rules. To check, open Customize in the sidebar and go to Rules, which lists every rule and its status.

Devin Desktop (formerly Windsurf), .devin/rules/mnemoverse.md:

markdown
---
trigger: always_on
---

(paste the memory rules here)

Devin Local, the agent Devin Desktop ships in Cascade's place since version 3.9.19, reads rules the way Devin CLI does. The Devin CLI rules page (read 2026-10-04) says .devin/rules/*.md files use the same frontmatter as .windsurf/rules/*.md, "so the trigger values always_on, manual, model_decision, agent, and glob all apply", and describes an always-on rule as "Active in every session, no user action needed". It does not say which mode a rule without trigger gets, so set it explicitly.

Check the current path

Agent-config conventions move fast. If a path above doesn't match your tool's latest docs, follow your tool's "custom instructions" or "rules" documentation and paste the same rules there. The wording of the rules carries over, but a tool that also asks for a file extension or an activation setting, as Cursor and Devin Desktop do, needs those as well.

Keep each project's memories in its own domain ​

The memory rules above name no domain for saving or searching, so an agent that follows them saves without one, and every memory goes to general, the default domain. A read without a domain searches all of your own domains. If you use one Mnemoverse account in several repositories, a fact saved in one of them, such as "this project uses pnpm", can come back in a session in another.

To keep them apart, give each repository a domain of its own and name it in that repository's instructions file: the project CLAUDE.md, AGENTS.md or Cursor rule, not ~/.claude/CLAUDE.md, which applies to every project. Add this line under the memory rules, with your repository's name in place of acme-api:

markdown
- This repository's memory domain is "project:acme-api". Pass domain "project:acme-api" to memory_write when you save a fact about this project, and to memory_read and memory_list_recent when you look one up. Save preferences that hold in every project without a domain.

The setup_memory prompt does not add this line; it is yours to add. What the tools do with it, checked against the server and connector code on 2026-10-11:

  • memory_write stores the memory in the domain you pass, and in general when you pass none.
  • memory_read and memory_list_recent with a domain return only that domain. Without one they cover all of your own domains: this project's, other projects', and general, so a question about a preference you hold everywhere still finds it. Neither covers a shared room unless you pass its address; from 0.16.0 the local server's answer names the rooms it skipped, with their addresses.
  • Names match exactly, including case and spaces: project:acme-api and project:Acme-API are two separate stores. memory_stats lists the domains you have, so the agent can reuse the exact name.
  • Read results show where each memory came from. The local server prints @"project:acme-api" after a memory from that domain and leaves general unmarked; the hosted connector prints a Domain: line for every result.
  • Neither the local server nor the connector has a default-domain setting. The domain reaches each call from this line in your instructions.
  • Memories saved before you add the line stay in general. A read scoped to the project does not return them; a read without a domain does.

A domain separates memories inside one account. To share a project's memory with teammates who sign in with their own accounts, use a room.

No config file? Use the phrases ​

If you'd rather not add a file, you can trigger the tools by hand:

  • To save: "Save this to Mnemoverse memory: …" or "Remember in Mnemoverse that …"
  • To recall: "Check your Mnemoverse memory — what do you know about …?"

This works, but it relies on you remembering to ask. The memory rules tell the agent to make those calls without being asked.

Verify it's working ​

  1. Add the rules (or use a phrase), then tell the agent something durable: "Remember that this project uses pnpm, never npm."
    • It should call memory_write. Ask it to confirm what it stored.
  2. Start a new session and ask: "What package manager does this project use?"
    • It should call memory_read and answer pnpm — without you re-explaining.

If it answers correctly across a fresh session, the habit is in place. If it never calls a memory tool at all, go back to First, confirm the tools work. If it calls the tools sometimes but still guesses, check that your tool loads the rules on every message in Cursor, or in every session in Devin Desktop (the frontmatter above) and move them higher in the file.