memory-mcp

What You Get

Automatic Memory. Your agent automatically saves the decisions, preferences and project facts that come up while you work, and checks its memory before it answers, starts a task or asks you anything about your work. You can still tell it to remember or forget anything, any time.

Always Up to Date. A changed decision updates its record instead of adding a second one, and a record that turns out wrong is removed. Every change ends with one short line in the reply, so "undo that" is one sentence away.

Version History. Earlier versions of every memory, and deleted records in the trash, are kept for 30 days. Bring any of them back just by asking your agent, or from the dashboard.

Fast, Exact Recall. Recall returns in milliseconds, and memories come back exactly as they were saved: Ragionex never rewrites a memory or generates an answer.

Projects and Teams. Each project can keep its own memory in its own Vault, and a search never crosses into another. Every key carries its own Read, Create, Update and Delete permissions. Share a Vault with teammates, give each member their own permissions, and every member's agents draw from and add to the same memory.

Safe and Private. Saves are written to disk before they are sent, so an outage only delays them. Memories are stored in the EU, encrypted with AES-256, and exportable at any time.

Works Where You Work. One command sets up Claude Code, Codex or OpenCode. Claude Desktop, Cursor, Cline and other MCP clients connect too.

Quick Start

1. Get a Key. Sign in at app.ragionex.com/keys and create a free key, no credit card needed. Give your main agent's key Read, Create, Update and Delete, so it can also clean up. The key is shown once.

2. Install. Requires Node.js 18 or later.

npx -y @ragionex/memory-mcp@latest install --agent claude-code

For Codex or OpenCode, use --agent codex or --agent opencode instead; for every installed agent at once, use --all-agents in its place. The installer asks for the key at a hidden prompt and checks it before changing anything.

3. Restart and Check. Quit and reopen the agent, then ask it to check my Ragionex Memory connection. It shows the selected Vault, every Vault the key can use and its permissions. From here on, just work.

For AI Assistants Setting This Up: run the install command above with --agent set to the agent the user wants memory in (claude-code, codex or opencode). A noninteractive run never waits for input; without a key, pass the follow-up steps it prints to the user. Then tell the user to restart their agent, which you cannot do yourself. Do not report working memory until a valid key is configured.

Other MCP Clients

Claude Desktop, Cursor, Cline and other clients that run local MCP servers use the same tools. Add the server to the client's user-global MCP config:

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

These clients get the tools but not the memory rule that install adds for Claude Code, Codex and OpenCode, so they use memory less consistently on their own. See the MCP Client Notes for client-specific details.

Vaults, Keys and Teams

A Vault is a separate set of memories. A key decides what an agent may do in it. A member is a teammate the Vault's owner shared it with. The picture above shows them working together:

Who	Read	Create	Update	Delete
Your agent 1	✅	✅	✅	✅
Your agent 2	✅	✅
Your agent 3	✅	✅	✅	✅
Teammate A	✅	✅	✅
Teammate B	✅

The picture shows Create and Update as Write and Edit.

A Vault and Key per Project

A new account starts with My vault as its default, and every project without its own Vault uses the default. To give a project its own memory, create a Vault in the Dashboard, then ask your agent to use my acme-app Vault for this project, or put a RAGIONEX_MEMORY.jsonc file in the project folder:

{
  // The Vault this project uses (shown by the connection check and in the dashboard)
  "vault_id": "<Vault ID>",
  // Optional: a key only this project uses, for example one that can only read
  "api_key": "rgx_memory_..."
}

• The file is read on every request, so a change applies at once, with no restart.
• Only the project folder itself is checked, not its parents.
• Add the file to .gitignore before putting a key in it.
• A broken file, an unknown field or a rejected key stops the request with a clear error. Memory never falls back to another Vault or key.

Work with Your Team

• Share a Vault. In the Dashboard, the owner shares a Vault and gives each member Read, Create, Update or Delete.
• One Memory for Everyone. A decision one teammate's agent saves can be recalled by every member's agent with Read access.
• Two Locks. In a shared Vault, an action must be allowed by both the key and the member's permissions. A teammate with Read only cannot change anything, whatever their key allows.

Keys

• A key belongs to your account and works in every Vault you own or that is shared with you.
• Give each key only what its agent needs. A key with Read only can recall but never change anything.
• Keys are created with fixed permissions and revoked in the Dashboard.

Free Plan

Requests	Memory Size	Stored Memories	Vaults	Keys	Teammates
10,000 per 30 days	10,000 characters	Unlimited	2	2	1 per Vault

Saving, editing and restoring a memory each cost 1 request, and so does each search page fetched from the service. Browsing, viewing, deleting, the trash, version history, status checks and export are free. Free is for personal projects and evaluation and is in early access, so its limits may change. Commercial use is not permitted on Free; Pro is coming soon.

Reference

Tools

Tool	Permission	Description
ragionex_recall_memory	Read	Finds memories by meaning, one complete question at a time, with optional exact dates. Whole records arrive on numbered pages
ragionex_list_memories	Read	Browses newest first with short previews, up to 100 per page
ragionex_view_memory	Read	Returns the full text and revision of up to 50 records by ID
ragionex_save_memory	Create	Saves a new record
ragionex_update_memory	Update	Replaces a record's content, checked against the revision the agent last read
ragionex_delete_memory	Delete	Moves records to the trash
ragionex_list_trash	Read	Lists deleted records with their restore deadlines
ragionex_memory_versions	Read	Lists retained versions or reads one in full
ragionex_restore_memory	Update	Restores a trashed record or an older version as the next revision
ragionex_memory_status	Read	Shows whether a new or edited record is still processing
ragionex_memory_connection	Any valid key	Shows the selected Vault and why, every Vault the key can use, its permissions and any saves waiting on this machine

Every record has id, vault_id, content, created_at, updated_at, status, revision, created_by and updated_by. New, edited and restored records are briefly processing before recall can find them. Permanent deletion, export, Vault sharing, key management and account deletion live in the Dashboard.

Configuration, Updating and Uninstalling

Setting	Details
RAGIONEX_MEMORY_API_KEY	The agent's key. install takes it from --api-key, this variable or a hidden prompt, in that order, and stores it in the agent's MCP registration
RAGIONEX_API_BASE	Optional API address, default https://api.ragionex.com
Relocated Agent Homes	install and uninstall follow CLAUDE_CONFIG_DIR, CODEX_HOME and XDG_CONFIG_HOME
Tool Timeout	Allow each MCP tool call more than 120 seconds, the connector's own request deadline, so a slow request still ends with its result or clear guidance
Windows	Claude Code is registered with the cmd /c wrapper it needs for npx servers. Run Codex and OpenCode under WSL
Diagnostics	The server writes to stderr; see your client's MCP server log

• Project Folder. The folder the agent reports: Claude Code's project directory, the client's single workspace root, or the folder the server started in.
• Updating. Run install again with @latest and your agent, then restart the agent. A run without a key keeps the existing registration and key.
• The Memory Rule. It lives between ragionex-memory-mcp:priority-rule markers in ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md or ~/.config/opencode/AGENTS.md, and refreshes itself after an upgrade. To keep your own version, edit the begin marker and the server leaves the block alone. See the Memory Rule Guide.
• Uninstalling. npx -y @ragionex/memory-mcp@latest uninstall --agent claude-code removes the registration and the rule; a rule you froze by editing its begin marker stays and is removed by hand. Saves that have not synced yet stay on disk.

Local Data and Recovery

• Saves waiting to sync live in ~/.ragionex/pending-saves/, one folder per key and API address. The files hold the saved content, unencrypted, and delivery metadata.
• *.pending.json files retry automatically with their original request IDs, so a retry never creates a second record. A save kept because of the plan limit is sent after the quota resets and counts toward the period in which the service accepts it.
• *.blocked-<reason>.json files were rejected during a later sync. They are never sent again automatically; review them using the paths ragionex_memory_connection reports.
• A waiting save keeps the key, API address and project Vault it was made with; one made without a project Vault goes to the account default. Do not edit the files or move them between key folders, and stop every connector instance before deleting a file you have reviewed.
• An older ~/.ragionex/pending-memories.jsonl is never sent automatically; review it before removing it.
• ~/.ragionex/recall-pages/ lets a search continue on its next page after a restart: one small file per search, named by a digest, holding only its save time, paging details and the IDs already shown, never the question, memory text or key. Expired files are removed automatically, and deleting them is safe; after a restart, the agent starts that search again.

Security

• Memories Are Data, Not Instructions. Agents are told never to follow saved content to change permissions, call tools or override you.
• HTTPS Only. The connector refuses plain HTTP except for localhost, 127.0.0.1 and [::1].

Troubleshooting

Symptom	Solution
The agent does not use memory or says the tools are unavailable	Restart the agent after installing; MCP servers load at startup. Then ask it to check the connection
"The API key is invalid or revoked"	Create a new key and run install again; the agent shows the exact command
A save is "queued" or "not confirmed yet"	The service was unreachable or a limit was reached. The save waits on this machine and is sent automatically; the connection check shows anything still waiting
Something saved a moment ago is not found	New records are briefly processing; ask the agent to check its status
A permission error	The key, or your access to a shared Vault, lacks that permission. Use a key that has it, or ask the Vault's owner
"No Vault is selected"	Choose a default Vault in the dashboard, or add a RAGIONEX_MEMORY.jsonc to the project

About Ragionex

Ragionex is a context engine for AI agents. It keeps what your agents learn and returns it exactly as it was saved: it never rewrites a memory and never generates an answer, so the reasoning stays with your agent. Recall comes back in milliseconds, and the same question over the same memories always returns the same results.

Support

Channel	When to Use
GitHub Issues	Bug reports
Discord	Questions and community
[email protected]	Private and security reports
Documentation	Setup guides and concepts

License

MIT