Vaults for projects and teams

A Vault holds a set of memories. Your account can own several Vaults within its allowance. Each project can use its own Vault, while a team can use one shared Vault.

The Free plan includes two owned Vaults. Vaults shared with you do not use that allowance. See limits and sharing on Free before setting up several projects.

Your default Vault

Every new account starts with My vault, its default Vault. You can rename it; its ID stays the same.

A new API operation without a Vault header uses your account's default. The MCP connector uses that default when the project's Vault file is absent.

To change the default, open Vaults in the dashboard, select the settings icon beside another Vault you own, then choose Make default under Default Vault. A shared Vault cannot become your account default.

Changing the default does not move any memories or change a project's explicit selection.

Your current default cannot be deleted. Make another Vault you own the default first.

Choose a Vault for each project

Use different Vault IDs for projects whose memories must stay separate. Changing the selected Vault changes which memory the project uses; it does not copy or move existing records.

If your allowance has room, open Vaults, choose Create vault, enter a Vault name, then choose Create vault in the form. Names allow 1–100 characters after trimming, without control or bidirectional formatting characters.

You can also choose a Vault someone has shared with you. Use your own account key for it.

Find a Vault ID

• Dashboard: open Vaults. Select the settings icon beside the Vault. Use Copy Vault ID in the Vault ID section.
• MCP: ask your agent to call ragionex_memory_connection. It reports reachable Vaults, their names and IDs, effective permissions, the selected target and the project-file path.
• API: call GET /v1/memory/identity with your key. Choose a vault_id from its vaults array.

curl "https://api.ragionex.com/v1/memory/identity" \
  -H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

All example keys and IDs on this page are placeholders. Replace them with your own key and a reachable Vault ID. The identity call needs a valid key, but no particular record permission.

Select a Vault in MCP

1. In the project, ask your agent to call ragionex_memory_connection.
2. Choose a Vault from the report. Ask the agent to use that Vault for this project, or write the following file at the reported config_file path.
3. Call the connection tool again. Check target_vault_id, target_available and the selected Vault's permissions.

{
  "vault_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}

The connector reads this file on each request, so a project-file change needs no restart. Only the reported project folder is checked, not its parent folders.

Keep the key in the agent's MCP registration. The optional api_key field can override it for one project; add RAGIONEX_MEMORY.jsonc to .gitignore before putting a secret in that file. A bad file or unavailable selection stops the request instead of silently choosing another Vault.

A project selection directs requests; it does not restrict the account key to that one Vault. See the MCP setup guide for folder selection and pending-save behavior.

Select a Vault in the API

Send X-Ragionex-Vault-Id with record requests. Use exactly one lowercase, 32-character hexadecimal Vault ID. Keep that selection for follow-up reads, edits, status checks and deletion.

curl "https://api.ragionex.com/v1/memory/list?limit=50" \
  -H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Ragionex-Vault-Id: bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"

The ID belongs in the header, not in the JSON body or query string. The key must belong to an account that owns the Vault or is a member of it. A malformed or repeated header returns 422 validation_error; an unavailable or inaccessible Vault returns 404 vault_not_found.

For search, send one complete query. A later page sends the same query, dates and Vault header again with the returned cursor. Without a header or an account default, a new record operation returns 409 no_vault_bound.

Share a Vault with a friend or teammate

1. Ask the teammate which email address they sign in to Ragionex with. If they have no account yet, they can create one with that address later.
2. Sign in to Vaults as the owner. Select the settings icon beside the Vault.
3. In Members, choose Invite member. Enter their address in Email.
4. Under Permissions in this Vault, check what the teammate may do: Read, Create, Update and Delete. At least one must be selected.
5. Choose Invite. No email is sent. Tell the teammate the invitation is waiting; it expires after 7 days.
6. The teammate signs in with that address and opens Vaults. The invitation is at the top of the list, marked Invited. Accept adds the Vault to their list as Shared with the permissions you chose; they can then open it, copy its ID through the settings icon beside it, and select it in their project file or API requests. Decline removes the invitation.

An invitation gives no access until it is accepted. While it waits, it appears in your Members list and takes a place in the member limit; choose Withdraw invitation (the trash icon) to remove it. To change what you offered, or a member's access later, use Change access (the pencil icon) on their entry; an invitation keeps its original expiry. Each teammate uses their own account key; do not send them yours.

Any combination works. For example, Read and Create lets a teammate read and add memories without changing or deleting existing ones. These grants apply to records throughout the Vault, not just records the member created. Even all four permissions do not make someone a Vault owner.

How key and member permissions combine

In the signed-in dashboard, a member's grants control record access. API and MCP requests must also be allowed by the member's own key. Only permissions present in both sets apply.

A missing required grant returns HTTP 403 with no_access and the message This request does not have access to the selected Vault or operation. If membership has been removed, the Vault is no longer accessible and record requests return 404 vault_not_found.

In a Vault you own, API and MCP operations still obey the key's permissions. A read-only key cannot edit your own Vault. A read-before-update workflow needs both Read and Update.

Key permissions are fixed when the key is created. You can rename or revoke it; changing its grants requires a replacement key. The API permission table lists the grant for each operation.

Change or remove access

As the owner, open Vaults, select the settings icon beside the Vault and go to Members. Choose Change access (the pencil icon), adjust the permissions and choose Save access. To remove access, choose Remove member (the trash icon), then Remove member in the form.

Removing a member removes their access to this Vault. Their saved memories stay in the Vault. Their account and keys are not deleted, and their own Vaults are unaffected.

A member can leave a shared Vault at any time: select the settings icon beside it and choose Leave vault. The owner can invite them again later.

Only the owner can view or manage the member list, rename or delete the Vault, or make it their account default. Members cannot use those owner controls, even with all four record permissions.

Limits and sharing on Free

Account-specific allowances can differ. The Vault cap counts Vaults you own; shared Vaults do not use it. The member cap follows the Vault owner's plan.

Give each tool its own key with only the permissions it needs; the agent setup already creates one key per agent.

Creating a Vault beyond the allowance returns 409 vault_limit_reached. Creating a key beyond the allowance returns 409 key_limit_reached. Inviting beyond the allowance returns 409 member_limit_reached; pending invitations count toward it. Remove a member or withdraw an invitation first, or share another Vault.

Saves, updates, restores and search pages each count as one request for the account making the request, including in a shared Vault. New or changed text must fit the Vault owner's content limit. The usage and limits reference covers the 30-day request allowance, content size and operations that are not counted.

History, trash and deletion

Read permission includes retained versions and trash throughout the shared Vault. Update permission allows restoring them. Delete permission moves records to trash; it does not allow permanent deletion.

A replaced version is kept for 30 days after replacement. A trashed record can be restored for 30 days after deletion. Older versions keep their own deadlines. A restore creates a new revision, preserves the record ID and counts as one request.

Only the owner can permanently delete trashed records or empty the trash, through the dashboard. Deleting a Vault permanently removes its memories, history, trash and memberships. It does not revoke account keys. Deleting the owner's account also removes its owned Vaults and their data.

The owner's dashboard export includes current memories, retained trash and history from owned Vaults. An API export with Read permission includes only current live records in its selected Vault. See export and restore for the full contract.