MCP client notes and known limitations

This connector runs as a local stdio MCP server. Its setup connects almost any AI agent. Other clients need their own supported local-server configuration; a client that only accepts remote MCP URLs cannot use this package as a hosted endpoint.

Start with the setup guide. Do not copy one client's configuration format into another client without checking that it accepts the format.

Installed but tools are missing

Quit and reopen the agent after installation. Confirm that the client has a server registration named ragionex-memory-mcp and can start npx with Node.js 18 or later.

Hermes Agent starts new connections in the background: wait about 2 minutes after the setup, then start a new session with /new.

For Codex and OpenCode, the installer itself uses these registration checks:

codex mcp list
opencode mcp list

Run the command for your client. A registration alone does not prove that the API key is usable. When tools are visible, use ragionex_memory_connection to check the selected Vault ID, effective permissions, selection source and config_file path.

The connector writes diagnostics to stderr, which appears in the client's MCP server logs. A missing key allows the local server to start but prevents working Memory calls.

Tools are visible but the agent does not use them

Installation adds a priority rule for the selected supported agent. A server started from a configuration added by hand does not create a missing rule at startup. Use the setup for a listed agent, or manual setup for any other agent with a global instructions file, then restart the agent.

A recognized client, or an agent connected through manual setup, can refresh an existing rule after connecting. Other clients skip this refresh. See How the config rule works for markers, backups and removal.

Rule-file loading and tool discovery are controlled by each client.

A call fails or a save is still pending

• Invalid or revoked key: check whether the selected key comes from the agent's MCP registration or the project's api_key. Replace it in that source. Restart after changing the MCP registration; a project-file change applies on the next request.
• Permission denied: check both the key's grants and the owner's grants to your account in a shared Vault. Read, create, update and delete are separate permissions.
• Wrong Vault: check the selected ID and config_file in ragionex_memory_connection; change the project's RAGIONEX_MEMORY.jsonc if needed.
• Project-folder error: if the client reports workspace roots, it must report exactly one valid local folder. Open one project folder and retry the connection check. An empty, multiple, invalid or failed roots response returns config_error without choosing another folder. See project Vault setup.
• Invalid project file or unavailable Vault: fix the reported file or selection. The connector does not fall back to another Vault or key.
• Plan or minute limit: follow the returned guidance. A save may be retained locally; inspect it before submitting anything again.
• Local save pending: use ragionex_memory_connection, not record-status polling. Changing the key does not move pending saves.
• Accepted record processing: use ragionex_memory_status with the record ID. Stop polling if it reports ready or failed.
• Revision conflict: follow the returned guidance to read the current revision and reconsider the change.
• Tool timeout: allow more than the connector's 120-second HTTP deadline so the connector can return its result or retry guidance.

A failed recall is an error, not proof that no matching memory exists. The setup guide explains pending and recovery files.

Platform notes

On Windows, the installer registers every supported agent's MCP server with a cmd /c wrapper.