MCP client notes and known limitations

The @ragionex/memory-mcp server speaks the Model Context Protocol, so it works across every MCP client. A few clients have their own behaviors that affect how the always-on memory-routing rule loads - none of them stop Memory from working, but it is worth knowing what to expect. This page covers the three you are most likely to notice.

If you have not connected the server yet, start with Add Memory to your AI agent over MCP. For the full story on the routing rule itself, see How the config rule works.

Claude Code: hidden and clipped tool guidance

What you might see. The server’s tools are available, but guidance packed into the tools themselves can be hidden until the model goes looking for it, and longer guidance gets clipped.

Why it happens. Claude Code loads MCP tools lazily - a tool’s full description often stays hidden until the model searches for it - caps how much text a single tool description can carry, and trims client-level server instructions once a few MCP servers are installed.

How it is handled. You do not need to do anything. On every startup the server writes one short priority rule into your agent’s always-loaded rules file (CLAUDE.md, AGENTS.md, and the like), so the memory-routing guidance is never hidden, clipped, or truncated. The block is clearly marked, your file is backed up before it first lands, your own content is never touched, and it is fully reversible. See How the config rule works for the details and the controls.

Codex: tools reported as unavailable on some setups

What you might see. With some non-default model setups, Codex can report the ragionex_* tools as unavailable even though the server is connected and enabled (codex mcp list shows it).

Why it happens. Codex defers MCP server tools behind its own tool-search step, and on certain non-default setups that step can miss the deferred tools. This is a client-side limitation, not specific to this server, and it does not affect Codex’s default models.

What to do. If the tools do not surface, switch to one of Codex’s default model setups, where the deferral behaves as expected. This is tracked upstream by the Codex team - see openai/codex#19871 and openai/codex#21503.

Windsurf: the priority rule is not auto-installed

What you might see. Memory’s tools work in Windsurf, but the always-on memory-routing rule is not applied automatically the way it is in other clients.

Why it happens. Windsurf caps each rule file at 6,000 characters (12,000 total across all active rules) and silently drops rules over that budget. The server’s priority rule is larger than the per-file cap, so the installer leaves it out rather than have it silently dropped.

What to do. Nothing is broken - the MCP tools still work, and you can still ask your agent to save and recall memories directly. You just will not get the always-on routing rule that nudges the agent to reach for Memory first. Reference: Windsurf rules character limits.