Set up Ragionex Memory

Connect almost any AI agent to Ragionex Memory. Paste the setup prompt into your agent, or run the setup yourself in a terminal.

With your agent

To have your AI agent set it up, click this button and paste the prompt into your agent.

Your agent gives you a link. Open it, sign in, and paste the one-time code from that page into the chat.

Set it up yourself

With Node.js 18 or later, run this in a terminal:

npx.cmd -y @ragionex/memory-mcp@latest install

npx -y @ragionex/memory-mcp@latest install

1. Choose your agent, or manual setup if it is not listed.
2. Open the link on any device and sign in. A new account is free.
3. Copy the code the page shows and paste it into the terminal.
4. Follow the last step the setup shows, usually quitting your agent completely and opening it again in a new session.

Run the setup once for each agent you use. Running it again shows a new link and gives the agent a new key. Earlier keys stay listed in the dashboard, where you can revoke them.

Using another MCP client? See Other local stdio clients.

Restart and check the connection

After the restart, your agent uses Ragionex Memory on its own. To check, ask: Check my Ragionex Memory connection. It answers with your Vaults and what this agent may do in each.

For a test save, provide one fact worth keeping. A confirmed save returns a record ID. Check ragionex_memory_status with that ID until it is ready or failed. A locally queued operation has a different operation ID and must be checked through ragionex_memory_connection.

What the setup changes

The setup makes two changes on your computer, for the agent you choose:

• Its MCP settings get a ragionex-memory-mcp entry with an API key made for this agent alone. The key can read, create, update and delete memories. It is never shown.
• Its global instructions file gets a marked Ragionex Memory block, for example ~/.claude/CLAUDE.md for Claude Code. Text outside the block stays as it is. If the file already has text, the setup backs it up first, next to the file.

While your agent works, Ragionex Memory keeps unsent saves and search progress in ~/.ragionex/. See Saves kept locally.

Why the setup works this way

The block tells your agent when to recall and when to save. To save context, agents such as Claude Code load MCP tool descriptions only when they need them, and cut long ones short. So guidance kept in the tools alone can go unseen. The global instructions file is read at the start of every session, so the block there is always in view.

Each time your agent starts, Ragionex Memory brings the block up to date, so fixes and improvements reach you without a new setup.

To keep the block as it is now, change its begin marker. Ragionex Memory then leaves it alone. If you delete the block, it stays deleted until you run the setup again. To remove both changes, run the uninstall command. See How the config rule works.

Troubleshooting

For other problems, see MCP client notes.

Manual setup

Any other AI agent with a global instructions file and a global MCP settings file connects with --manual. You can also use --manual if automatic setup stops.

Add this entry to the agent's global MCP settings file, in the format that file uses. Use the example for your operating system.

"ragionex-memory-mcp": {
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@ragionex/memory-mcp@latest"],
  "env": {
    "RAGIONEX_MEMORY_API_KEY": "SETUP_FILLS_KEY",
    "RAGIONEX_MEMORY_INSTRUCTIONS_FILE": "SETUP_FILLS_PATH"
  }
}

"ragionex-memory-mcp": {
  "command": "npx",
  "args": ["-y", "@ragionex/memory-mcp@latest"],
  "env": {
    "RAGIONEX_MEMORY_API_KEY": "SETUP_FILLS_KEY",
    "RAGIONEX_MEMORY_INSTRUCTIONS_FILE": "SETUP_FILLS_PATH"
  }
}

Leave both placeholders as they are. Run the setup with the full paths of your two files, replacing the example paths below:

npx.cmd -y @ragionex/memory-mcp@latest install --manual --instructions-file C:\Users\user\.myagent\AGENTS.md --mcp-config C:\Users\user\.myagent\mcp.json

npx -y @ragionex/memory-mcp@latest install --manual --instructions-file /home/user/.myagent/AGENTS.md --mcp-config /home/user/.myagent/mcp.json

Each placeholder must appear once in the MCP settings file. The setup fills in both placeholders and adds the priority rule to your instructions file.

Other local stdio clients

For a client that accepts the following user-global MCP configuration shape, create a key at app.ragionex.com/keys and add:

{
  "mcpServers": {
    "ragionex-memory-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@ragionex/memory-mcp@latest"],
      "env": {
        "RAGIONEX_MEMORY_API_KEY": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

{
  "mcpServers": {
    "ragionex-memory-mcp": {
      "command": "npx",
      "args": ["-y", "@ragionex/memory-mcp@latest"],
      "env": {
        "RAGIONEX_MEMORY_API_KEY": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Client configuration formats differ; this JSON is not a universal format. For an agent with a global instructions file, use the setup instead, so the key and the priority rule are handled together.

This package starts a local stdio server. It does not provide a hosted MCP URL or a remote HTTP MCP endpoint.

Configuration

The API address must use HTTPS, except that plain HTTP is accepted for localhost, 127.0.0.1 and [::1]. Credentials, query strings and fragments are not allowed in that address. Automatic setup copies RAGIONEX_API_BASE into the server registration when it is set. With manual setup, add a custom API address to the entry's environment yourself.

The installer follows the relocated homes above. It also registers CLAUDE_CONFIG_DIR and CODEX_HOME with their respective server entries when those variables are set. Restart the agent after changes to its MCP registration.

Vault per project

For default Vaults, separate projects and the dashboard sharing steps, see Vaults: projects and sharing.

Without a project file, requests use your account's default Vault. To choose another owned or shared Vault for one project, put RAGIONEX_MEMORY.jsonc in that project's folder:

{
  "vault_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}

Replace the example ID with one shown by ragionex_memory_connection or the dashboard. You can also ask your agent to use a named Vault for this project; it writes the file at the config_file path reported by the connection check.

• The file is read on every request. A change takes effect without restarting the agent.
• The folder is Claude Code's reported project directory, the client's single workspace root, or the server's working folder. Only that folder is checked, not its parents.
• If the client reports workspace roots, it must report exactly one valid local folder. An empty, multiple, invalid or failed roots response stops the request with config_error; it does not fall back to the server's working folder.
• vault_id is required. Optional api_key replaces the agent's configured key for this project. Add the file to .gitignore before putting a secret in it.
• A broken file, an unknown field, an invalid selection or a rejected project key stops the request. The connector does not silently try another Vault or key.
• Use a shared Vault ID with your own account key. The operation must be allowed by both the key and the owner's membership grants.

Tools

Save and update content must be nonempty; the service also rejects whitespace-only content. Save has no metadata arguments. Update replaces the full content and requires a positive JavaScript safe-integer revision from a recent read. After a conflict, reread and reconsider the edit; the connector does not automatically retry the update.

Trash and old versions are restorable for 30 days. Restore requires the current record revision, not the old version number. Supply revision for a live record; omit it or pass null to restore the last content of a trashed record. A restore advances the revision, keeps other retained versions and counts as one request. Restore is never queued offline. A lost response requires a history read before another attempt. Restored records enter processing and become searchable when processing succeeds.

Trash pages use the same page-size range as list. History pages default to 25, up to 100; a cursor is at most 16 characters. Optional limit, cursor and revision arguments accept null. Only the Vault owner can permanently delete trashed records or empty the trash, through the dashboard. The API-key export contains only current live records; the owner's dashboard export also includes retained trash and version history, with full text.

Recall begins with one complete query of 5–512 characters after trimming, optionally with start_date and end_date. For the next page, send the same query and dates with page set to the next page number. The search service returns up to 10 records per page and at most 10 pages per search; each service page counts as one request. List's page size remains 1–100, default 50, and its cursor is at most 128 characters. View and delete take 1–50 IDs. Record IDs contain 1–14 ASCII letters, digits or underscores. A missing ID rejects the whole view or delete batch.

The connector asks agents to use English content and full English questions. This is guidance; the service stores content unchanged. MCP date arguments are optional strings of at most 40 characters. Null omits a bound; empty strings and integers are rejected. Use YYYY-MM-DD or a datetime with a T separator, seconds, and optional fractional seconds and timezone offset. The service applies the creation-time bounds in the API reference and requires end_date to be on or after start_date. A bare start date includes the start of its UTC day and a bare end date includes the end of that day. Prefer explicit UTC timestamps for datetimes. See the date rules.

Tool replies are text for the agent, not the REST envelopes. Full records retain id, vault_id, content, created_at, updated_at, status, revision, created_by and updated_by; the actor fields are account IDs. Save, update and restore replies omit content. Recall returns whole records across pages; use the next page number it provides. If a multi-record view lists omitted IDs, view each omitted ID separately to read its full content.

The tools use the Vault selected by the project file or account default; their arguments do not select or manage Vaults or keys. Create and share Vaults, choose an owned default Vault and manage account keys in the dashboard. Export is available through the API and dashboard.

Saves kept locally

Every save is written to local storage before the connector sends it. Saves waiting for confirmation live under ~/.ragionex/pending-saves/, separately for each key and API address. The files contain the saved text, delivery metadata and the explicit Vault ID, if one was selected. Changing the project file does not retarget a pending save that already has a Vault ID. A save queued without an explicit Vault ID uses the account default at its first acceptance; after acceptance, its request token remains bound to that Vault.

• If the service is unreachable, times out, returns a server error or returns an unusable save confirmation, the save remains local with its original request ID.
• HTTP 402 plan refusals and HTTP 429 rate limits also keep the save locally. A quota-refused save is not yet searchable and has not been accepted by the service.
• Pending saves retry automatically while the connector is running and respect any delay requested by the service. Quota-blocked saves can be accepted once allowance is available.
• A queued reply is not a confirmed save. A timed-out request may already have reached the service. Do not submit it again: replay uses the same request ID to avoid a second accepted write.
• A save counts toward the usage period in which the service accepts it, not the period in which it was queued. The connection check itself is not counted, but each save it delivers in the background counts as one request.
• The connector checks a 100-entry pending-save limit per connection before staging another save. If full, the new save is refused explicitly.
• Update, restore, delete, recall and list failures are not stored as offline operations.

A direct save rejected for invalid credentials, insufficient permission, invalid input or an unavailable Vault reports the error and removes its newly staged copy if possible. Background delivery can pause or mark a save as blocked. Blocked saves stay on disk for review and are not retried automatically; use ragionex_memory_connection to see the reason.

Use ragionex_memory_connection to check pending and blocked saves, retry times, storage errors and recovery paths. It also starts a background sync when possible. A pending operation ID is not a record ID.

If local storage needs recovery, inspect the reported paths before trying the save again. Recovery-required files stay unchanged and are never sent automatically. Do not edit their payloads or request IDs, and do not move them between key folders. Changing the key or API address does not transfer pending saves. Stop all connector instances before deleting a reviewed file you no longer need.

Update or uninstall

The registration starts @ragionex/memory-mcp@latest, so the agent loads the newest version each time it starts, and the managed rule refreshes itself. In a manual configuration, use @ragionex/memory-mcp@latest in args and retain the environment settings. Registry access is needed to obtain an update; an already-running process keeps its loaded version.

To remove the registration and managed rule from a selected agent:

npx.cmd -y @ragionex/memory-mcp@latest uninstall --agent codex

npx -y @ragionex/memory-mcp@latest uninstall --agent codex

Without --agent, a terminal run shows the agent menu. After manual setup, run uninstall --manual --instructions-file <path>: it removes the rule, and the ragionex-memory-mcp entry is deleted from the agent's MCP settings file by the agent or by hand.

Uninstall keeps pending and blocked save files. The agent's key stays in your account; revoke it in the dashboard if you do not plan to reconnect. Pending saves can resume when the connector runs again with the same key and API address. Modified rule markers are left for manual review. See How the config rule works.