Quickstart: Memory
Save one fact in your Vault, check when it is ready, then retrieve it. The same saved context can be used in later sessions and other tools connected to that Vault.
Get your API key
Sign in at app.ragionex.com/keys and create a named API key. New accounts start with My vault, their default Vault. For this walkthrough, keep only Read and Create selected. Copy the secret when it appears; it cannot be shown again.
Keep the key server-side. Do not expose it in client-side code or public repositories.
These examples use your account's default Vault. To use another owned or shared Vault, send X-Ragionex-Vault-Id on the write, status and search requests. Find its ID through identity; see the Vault-selection rules. If the default changes after a save, use the reply's vault_id in that header for later operations.
For separate project memories or a shared team Vault, follow Vaults: projects and sharing.
Write a memory
Send a POST to /v1/memory/write with only content in the JSON body. Replace the example API key with yours. The example Idempotency-Key identifies one operation: keep it for retries of that save, and use a fresh token for a different save.
Python
import requests
response = requests.post(
"https://api.ragionex.com/v1/memory/write",
headers={
"X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Idempotency-Key": "quickstart-preference-001"
},
json={
"content": "User prefers TypeScript over JavaScript. Always use strict mode."
}
)
response.raise_for_status()
data = response.json()
print(f"Memory ID: {data['id']}")JavaScript
const res = await fetch("https://api.ragionex.com/v1/memory/write", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Idempotency-Key": "quickstart-preference-001"
},
body: JSON.stringify({
content: "User prefers TypeScript over JavaScript. Always use strict mode."
})
});
if (!res.ok) throw new Error(await res.text());
const data = await res.json();curl
curl -X POST https://api.ragionex.com/v1/memory/write \
-H "Content-Type: application/json" \
-H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: quickstart-preference-001" \
-d '{
"content": "User prefers TypeScript over JavaScript. Always use strict mode."
}'A new save returns HTTP 200 with the record's ID and status processing. A duplicate save or a matching retry returns the existing record's metadata, which may already be ready.
{
"success": true,
"id": "mem_K7X2P9Q4R1",
"vault_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"created_at": "2024-04-12T00:00:00Z",
"updated_at": "2024-04-12T00:00:00Z",
"status": "processing",
"revision": 1,
"created_by": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"updated_by": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}Wait until it is ready
Replace the example ID in the status URL with the ID returned by your save. Check /v1/memory/status/{id} again later while the response says processing, staying within the minute limit. Stop when it says ready or failed. Only ready records appear in search. If it fails, read the message; changing its content starts another attempt, while resending identical content does not. A content change requires update permission.
Python
import requests
response = requests.get(
"https://api.ragionex.com/v1/memory/status/mem_K7X2P9Q4R1",
headers={"X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}
)
response.raise_for_status()
data = response.json()
print(data["status"], data["message"])JavaScript
const res = await fetch("https://api.ragionex.com/v1/memory/status/mem_K7X2P9Q4R1", {
headers: { "X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
});
const data = await res.json();curl
curl -X GET https://api.ragionex.com/v1/memory/status/mem_K7X2P9Q4R1 \
-H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"{
"success": true,
"id": "mem_K7X2P9Q4R1",
"vault_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"status": "ready",
"revision": 1,
"updated_at": "2024-04-12T00:00:00Z",
"created_by": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"updated_by": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"message": "This memory is processed and searchable."
}Search it back
Send one complete question as query to /v1/memory/search. It must contain 5–512 characters after trimming. Each request returns up to 10 ready records from the selected Vault and counts as one request. If next_cursor is a string, send the same question again with it as cursor for the next page. Null means the search is complete; a search has at most 10 pages.
Python
import requests
response = requests.post(
"https://api.ragionex.com/v1/memory/search",
headers={"X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
json={"query": "What programming language does the user prefer?"}
)
response.raise_for_status()
data = response.json()JavaScript
const res = await fetch("https://api.ragionex.com/v1/memory/search", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
body: JSON.stringify({query: "What programming language does the user prefer?"})
});
if (!res.ok) throw new Error(await res.text());
const data = await res.json();curl
curl -X POST https://api.ragionex.com/v1/memory/search \
-H "Content-Type: application/json" \
-H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-d '{"query": "What programming language does the user prefer?"}'{
"success": true,
"results": [
{
"id": "mem_K7X2P9Q4R1",
"vault_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"content": "User prefers TypeScript over JavaScript. Always use strict mode.",
"created_at": "2024-04-12T00:00:00Z",
"updated_at": "2024-04-12T00:00:00Z",
"status": "ready",
"revision": 1,
"created_by": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"updated_by": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
],
"next_cursor": null
}