Memory API - Ragionex Docs

Memory Write

POST /v1/memory/write

Store a new memory. New content is processed in the background before it becomes searchable. Use the /v1/memory/status/{id} endpoint to check when it is ready.

https://api.ragionex.com/v1/memory/write

Request Body

Parameter	Type	Required	Description
content	string	required	The memory content to store (maximum length depends on your plan)
project	string	required	Organizational label for the memory. Lowercase letters, digits, hyphens only. 1-50 characters. Pattern: `^[a-z0-9-]+$`. New project names are created automatically on first write.

Example Request

   Python   JavaScript   curl  
 import requests

response = requests.post(
    "https://api.ragionex.com/v1/memory/write",
    headers={"X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "content": "User prefers TypeScript over JavaScript. Always use strict mode and explicit types.",
        "project": "acme-app"
    }
)
data = response.json()
print(f"Memory ID: {data['id']} (project: {data['project']})") 
 const res = await fetch("https://api.ragionex.com/v1/memory/write", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  body: JSON.stringify({
    content: "User prefers TypeScript over JavaScript. Always use strict mode and explicit types.",
    project: "acme-app"
  })
});
const data = await res.json(); 
 curl -X POST https://api.ragionex.com/v1/memory/write \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "content": "User prefers TypeScript over JavaScript. Always use strict mode and explicit types.",
    "project": "acme-app"
  }' 

Response

{
  "success": true,
  "id": "mem_K7X2P9Q4R1",
  "status": "processing",
  "project": "acme-app"
}

{
  "success": false,
  "error": "Invalid project name. Allowed: lowercase letters, digits, hyphens; 1-50 chars."
}

{
  "success": false,
  "error": "Memory limit reached (X total memories). Upgrade your plan for higher limits. See https://ragionex.com/pricing for more info."
}

Async Processing

The memory is processed in the background. The status field stays "processing" until it is searchable, then changes to "ready".

Memory Search

POST /v1/memory/search

Search your memories with 1-5 semantic questions in one call. Only memories with status: "ready" are included in search results.

https://api.ragionex.com/v1/memory/search

Request Body

Parameter	Type	Required	Description
queries	string[]	required	1-5 natural-language questions, each 5-512 characters. One question = a one-element array; each item is searched independently and results are merged. Each item counts as one search request against your quota.
results	integer	optional	Number of results to return (1-50) Default: 10
project	string	optional	Filter results to a specific project. Omit to search across all projects (cross-project search).
start_date	string	optional	Lower bound (inclusive) for memory creation date. ISO 8601 string: `YYYY-MM-DD` (= start-of-day UTC) or `YYYY-MM-DDTHH:MM:SSZ`. Accepted range: 1970-01-01 to 2200-01-01. Omit for no lower bound.
end_date	string	optional	Upper bound (inclusive). ISO 8601 string: `YYYY-MM-DD` (= end-of-day UTC) or `YYYY-MM-DDTHH:MM:SSZ`. Must be on or after `start_date` when both are provided. Omit for no upper bound.

Example Request - Scoped to One Project

   Python   JavaScript   curl  
 import requests

response = requests.post(
    "https://api.ragionex.com/v1/memory/search",
    headers={"X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "queries": ["What programming language does the user prefer?"],
        "results": 5,
        "project": "acme-app"
    }
)
data = response.json() 
 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({
    queries: ["What programming language does the user prefer?"],
    results: 5,
    project: "acme-app"
  })
});
const data = await res.json(); 
 curl -X POST https://api.ragionex.com/v1/memory/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "queries": ["What programming language does the user prefer?"],
    "results": 5,
    "project": "acme-app"
  }' 

Example Request - Cross-Project Search

   Python   JavaScript   curl  
 import requests

response = requests.post(
    "https://api.ragionex.com/v1/memory/search",
    headers={"X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "queries": ["What programming language does the user prefer?"]
    }
)
data = response.json() 
 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({
    queries: ["What programming language does the user prefer?"]
  })
});
const data = await res.json(); 
 curl -X POST https://api.ragionex.com/v1/memory/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "queries": ["What programming language does the user prefer?"]
  }' 

Response

{
  "success": true,
  "results": [
    {
      "id": "mem_K7X2P9Q4R1",
      "content": "User prefers TypeScript over JavaScript. Always use strict mode and explicit types.",
      "project": "acme-app"
    }
  ]
}

{
  "success": false,
  "error": "Project 'acme-ap' does not exist for this user.",
  "available_projects": ["acme-app", "blog-backend", "mobile-app"]
}

AI Self-Correction

When an invalid project name is passed, the response includes an available_projects array. Your agent can read this list and retry with the correct name - no extra API call required.

Memory List

GET /v1/memory/list

List all memories for the authenticated user, ordered by creation date (newest first). Returns a preview of each memory (first 200 characters).

https://api.ragionex.com/v1/memory/list

Query Parameters

Parameter	Type	Required	Description
project	string	optional	Filter to one project. Omit to list memories across all projects.
start_date	string	optional	Lower bound (inclusive) for memory creation date. ISO 8601 string: `YYYY-MM-DD` (= start-of-day UTC) or `YYYY-MM-DDTHH:MM:SSZ`. Accepted range: 1970-01-01 to 2200-01-01. Omit for no lower bound.
end_date	string	optional	Upper bound (inclusive). ISO 8601 string: `YYYY-MM-DD` (= end-of-day UTC) or `YYYY-MM-DDTHH:MM:SSZ`. Must be on or after `start_date` when both are provided. Omit for no upper bound.

Example Request

   Python   JavaScript   curl  
 import requests

response = requests.get(
    "https://api.ragionex.com/v1/memory/list",
    headers={"X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    params={"project": "acme-app"}
)
data = response.json() 
 const res = await fetch("https://api.ragionex.com/v1/memory/list?project=acme-app", {
  headers: {
    "X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
});
const data = await res.json(); 
 curl -X GET "https://api.ragionex.com/v1/memory/list?project=acme-app" \
  -H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" 

Response

{
  "success": true,
  "memories": [
    {
      "id": "mem_K7X2P9Q4R1",
      "preview": "User prefers TypeScript over JavaScript. Always use strict mode...",
      "status": "ready",
      "project": "acme-app",
      "created_at": 1712880000
    },
    {
      "id": "mem_A1B2C3D4E5",
      "preview": "Project uses PostgreSQL for the main database...",
      "status": "processing",
      "project": "acme-app",
      "created_at": 1712876400
    }
  ]
}

Memory View

POST /v1/memory/view

Retrieve the full content of specific memories by their IDs. Non-owned IDs are silently ignored.

https://api.ragionex.com/v1/memory/view

Request Body

Parameter	Type	Required	Description
ids	array	required	Array of memory IDs to retrieve (1-50 IDs)

Example Request

   Python   JavaScript   curl  
 import requests

response = requests.post(
    "https://api.ragionex.com/v1/memory/view",
    headers={"X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "ids": ["mem_K7X2P9Q4R1", "mem_A1B2C3D4E5"]
    }
)
data = response.json() 
 const res = await fetch("https://api.ragionex.com/v1/memory/view", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  body: JSON.stringify({
    ids: ["mem_K7X2P9Q4R1", "mem_A1B2C3D4E5"]
  })
});
const data = await res.json(); 
 curl -X POST https://api.ragionex.com/v1/memory/view \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "ids": ["mem_K7X2P9Q4R1", "mem_A1B2C3D4E5"]
  }' 

Response

{
  "success": true,
  "memories": [
    {
      "id": "mem_K7X2P9Q4R1",
      "content": "User prefers TypeScript over JavaScript. Always use strict mode and explicit types.",
      "status": "ready",
      "project": "acme-app",
      "created_at": 1712880000
    }
  ]
}

Memory Export

GET /v1/memory/export

Export every memory you have stored, with full content, as a single JSON document. It takes no parameters - it always returns everything. The response streams, so even a large export never buffers fully in memory.

https://api.ragionex.com/v1/memory/export

Example Request

   Python   JavaScript   curl  
 import requests

response = requests.get(
    "https://api.ragionex.com/v1/memory/export",
    headers={"X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}
)
data = response.json() 
 const res = await fetch("https://api.ragionex.com/v1/memory/export", {
  headers: {
    "X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
});
const data = await res.json(); 
 curl -X GET "https://api.ragionex.com/v1/memory/export" \
  -H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" 

Response

{
  "generated_at": 1712880000,
  "count": 2,
  "memories": [
    {
      "id": "mem_K7X2P9Q4R1",
      "content": "User prefers TypeScript over JavaScript. Always use strict mode and explicit types.",
      "status": "ready",
      "project": "acme-app",
      "created_at": 1712880000
    },
    {
      "id": "mem_A1B2C3D4E5",
      "content": "Project uses PostgreSQL for the main database with connection pooling.",
      "status": "ready",
      "project": "acme-app",
      "created_at": 1712876400
    }
  ],
  "complete": true
}

The trailing "complete": true marks a finished export. If it is absent - or the JSON does not parse - the export was truncated and should be retried. This endpoint is rate limited to 3 requests per minute.

Memory Update

PUT /v1/memory/update

Update an existing memory. Supports partial updates: you can change the content only, the project only, or both. Content changes reprocess the memory before it is searchable again; project-only changes update metadata in place, instantly.

https://api.ragionex.com/v1/memory/update

Request Body

Parameter	Type	Required	Description
id	string	required	The memory ID to update
content	string	optional	New memory content (maximum length depends on your plan). The memory returns to processing until the new content is searchable.
project	string	optional	Move the memory to a different project. Instant - only metadata is updated.

At least one required

You must provide content, project, or both. Providing only id returns a 400 error.

Example - Content Only (returns to processing)

   Python   JavaScript   curl  
 import requests

response = requests.put(
    "https://api.ragionex.com/v1/memory/update",
    headers={"X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "id": "mem_K7X2P9Q4R1",
        "content": "User now prefers Python over TypeScript for data science projects."
    }
)
data = response.json() 
 const res = await fetch("https://api.ragionex.com/v1/memory/update", {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  body: JSON.stringify({
    id: "mem_K7X2P9Q4R1",
    content: "User now prefers Python over TypeScript for data science projects."
  })
});
const data = await res.json(); 
 curl -X PUT https://api.ragionex.com/v1/memory/update \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "id": "mem_K7X2P9Q4R1",
    "content": "User now prefers Python over TypeScript for data science projects."
  }' 

Example - Project Only (instant, stays ready)

   Python   JavaScript   curl  
 import requests

response = requests.put(
    "https://api.ragionex.com/v1/memory/update",
    headers={"X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "id": "mem_K7X2P9Q4R1",
        "project": "acme-mobile"
    }
)
data = response.json() 
 const res = await fetch("https://api.ragionex.com/v1/memory/update", {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  body: JSON.stringify({
    id: "mem_K7X2P9Q4R1",
    project: "acme-mobile"
  })
});
const data = await res.json(); 
 curl -X PUT https://api.ragionex.com/v1/memory/update \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "id": "mem_K7X2P9Q4R1",
    "project": "acme-mobile"
  }' 

Example - Both

   Python   JavaScript   curl  
 import requests

response = requests.put(
    "https://api.ragionex.com/v1/memory/update",
    headers={"X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "id": "mem_K7X2P9Q4R1",
        "content": "Updated content for the mobile project context.",
        "project": "acme-mobile"
    }
)
data = response.json() 
 const res = await fetch("https://api.ragionex.com/v1/memory/update", {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  body: JSON.stringify({
    id: "mem_K7X2P9Q4R1",
    content: "Updated content for the mobile project context.",
    project: "acme-mobile"
  })
});
const data = await res.json(); 
 curl -X PUT https://api.ragionex.com/v1/memory/update \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "id": "mem_K7X2P9Q4R1",
    "content": "Updated content for the mobile project context.",
    "project": "acme-mobile"
  }' 

Response - Content Changed

{
  "success": true,
  "id": "mem_K7X2P9Q4R1",
  "status": "processing",
  "project": "acme-app"
}

Response - Project Only

{
  "success": true,
  "id": "mem_K7X2P9Q4R1",
  "status": "ready",
  "project": "acme-mobile"
}

{
  "success": false,
  "error": "Monthly write limit reached (X writes). Resets on 2026-05-01. Upgrade your plan for higher limits. See https://ragionex.com/pricing for more info."
}

Writes Counter

A content update counts as one write (same cost as a fresh write). A project-only update does NOT count toward the writes-per-month quota.

Memory Delete

DELETE /v1/memory/delete

Delete one or more memories permanently. This action cannot be undone.

https://api.ragionex.com/v1/memory/delete

Request Body

Parameter	Type	Required	Description
ids	array	required	Array of memory IDs to delete (1-50 IDs)

Example Request

   Python   JavaScript   curl  
 import requests

response = requests.delete(
    "https://api.ragionex.com/v1/memory/delete",
    headers={"X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "ids": ["mem_K7X2P9Q4R1"]
    }
)
data = response.json() 
 const res = await fetch("https://api.ragionex.com/v1/memory/delete", {
  method: "DELETE",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  body: JSON.stringify({
    ids: ["mem_K7X2P9Q4R1"]
  })
});
const data = await res.json(); 
 curl -X DELETE https://api.ragionex.com/v1/memory/delete \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "ids": ["mem_K7X2P9Q4R1"]
  }' 

Response

{
  "success": true,
  "deleted": 1
}

Memory Status

GET /v1/memory/status/{memory_id}

Check the processing status of a specific memory.

https://api.ragionex.com/v1/memory/status/{memory_id}

Path Parameters

Parameter	Type	Required	Description
memory_id	string	required	The memory ID to check

Example Request

   Python   JavaScript   curl  
 import requests

response = requests.get(
    "https://api.ragionex.com/v1/memory/status/mem_K7X2P9Q4R1",
    headers={"X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}
)
data = response.json() 
 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 -X GET https://api.ragionex.com/v1/memory/status/mem_K7X2P9Q4R1 \
  -H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" 

Response

{
  "success": true,
  "id": "mem_K7X2P9Q4R1",
  "status": "ready"
}

Status Values

Status	Description
processing	Memory is processing. Not yet searchable.
ready	Memory is ready and searchable.
failed	Processing failed. Contact support.

Memory Projects

GET /v1/memory/projects

List all distinct projects for the authenticated user, including the memory count for each project. Useful for AI agents to self-discover available project names before writing or searching.

https://api.ragionex.com/v1/memory/projects

Example Request

   Python   JavaScript   curl  
 import requests

response = requests.get(
    "https://api.ragionex.com/v1/memory/projects",
    headers={"X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}
)
data = response.json() 
 const res = await fetch("https://api.ragionex.com/v1/memory/projects", {
  headers: {
    "X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
});
const data = await res.json(); 
 curl -X GET https://api.ragionex.com/v1/memory/projects \
  -H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" 

Response

{
  "success": true,
  "projects": [
    { "name": "acme-app", "memory_count": 45 },
    { "name": "blog-backend", "memory_count": 12 },
    { "name": "mobile-app", "memory_count": 8 }
  ]
}

Rename Project

PATCH /v1/memory/projects/{name}

Bulk-rename a project. Every memory updates atomically. Fast even at thousands of entries.

https://api.ragionex.com/v1/memory/projects/{name}

Path Parameters

Parameter	Type	Required	Description
name	string	required	Current project name (the one being renamed)

Request Body

Parameter	Type	Required	Description
new_name	string	required	New project name. Same format as project field (lowercase alphanumeric + hyphen, 1-50 chars).

Example Request

   Python   JavaScript   curl  
 import requests

response = requests.patch(
    "https://api.ragionex.com/v1/memory/projects/acme-app",
    headers={"X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "new_name": "acme-mobile"
    }
)
data = response.json() 
 const res = await fetch("https://api.ragionex.com/v1/memory/projects/acme-app", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  body: JSON.stringify({
    new_name: "acme-mobile"
  })
});
const data = await res.json(); 
 curl -X PATCH https://api.ragionex.com/v1/memory/projects/acme-app \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "new_name": "acme-mobile"
  }' 

Response

{
  "success": true,
  "renamed": 45,
  "from": "acme-app",
  "to": "acme-mobile"
}

{
  "success": false,
  "error": "Project 'acme-app' does not exist for this user"
}

Delete Project

DELETE /v1/memory/projects/{name}

Delete a project and all its memories. This removes every memory with the given project name and every memory it contains. This action cannot be undone.

https://api.ragionex.com/v1/memory/projects/{name}

Destructive operation

This endpoint permanently deletes all memories in the project. Agents should confirm with the user before calling it.

Path Parameters

Parameter	Type	Required	Description
name	string	required	Project name to delete

Example Request

   Python   JavaScript   curl  
 import requests

response = requests.delete(
    "https://api.ragionex.com/v1/memory/projects/acme-app",
    headers={"X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}
)
data = response.json() 
 const res = await fetch("https://api.ragionex.com/v1/memory/projects/acme-app", {
  method: "DELETE",
  headers: {
    "X-API-Key": "rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
});
const data = await res.json(); 
 curl -X DELETE https://api.ragionex.com/v1/memory/projects/acme-app \
  -H "X-API-Key: rgx_memory_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" 

Response

{
  "success": true,
  "deleted": 45
}

{
  "success": false,
  "error": "Project 'acme-app' does not exist for this user"
}