Memories API
Store and retrieve user memories
The Memories API allows you to store and retrieve persistent context for your users across conversations.
Free Usage
The Memories API is free with unlimited usage for all users.
Encrypted Storage
All memories are encrypted at rest using AES-256 encryption.
How It Works
- Create: Store memories with a unique user ID
- Search: Find relevant memories using semantic search
- List: Retrieve all memories for a user
- Delete: Remove memories when no longer needed
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/memories | Create a memory |
| GET | /api/v1/memories | List user memories |
| POST | /api/v1/memories/search | Search memories |
| DELETE | /api/v1/memories/:id | Delete a memory |
Create Memory (POST)
POST https://axerity.com/api/v1/memoriesRequest Body
Prop
Type
Example
curl -X POST https://axerity.com/api/v1/memories \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"user_id": "user_123",
"content": "User prefers dark mode and uses TypeScript",
"metadata": {
"category": "preferences"
}
}'Response
{
"id": "mem_abc123",
"user_id": "user_123",
"content": "User prefers dark mode and uses TypeScript",
"metadata": {
"category": "preferences"
},
"created_at": "2025-01-15T10:30:00Z"
}List Memories (GET)
GET https://axerity.com/api/v1/memoriesQuery Parameters
Prop
Type
Example
curl "https://axerity.com/api/v1/memories?user_id=user_123&limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"Response
{
"memories": [
{
"id": "mem_abc123",
"user_id": "user_123",
"content": "User prefers dark mode and uses TypeScript",
"metadata": { "category": "preferences" },
"created_at": "2025-01-15T10:30:00Z"
}
],
"total": 1,
"limit": 10,
"offset": 0
}Search Memories (POST)
POST https://axerity.com/api/v1/memories/searchRequest Body
Prop
Type
Example
curl -X POST https://axerity.com/api/v1/memories/search \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"user_id": "user_123",
"query": "programming preferences",
"limit": 5
}'Response
{
"memories": [
{
"id": "mem_abc123",
"user_id": "user_123",
"content": "User prefers dark mode and uses TypeScript",
"metadata": { "category": "preferences" },
"created_at": "2025-01-15T10:30:00Z",
"score": 0.92
}
],
"total": 1
}Delete Memory (DELETE)
DELETE https://axerity.com/api/v1/memories/:idExample
curl -X DELETE https://axerity.com/api/v1/memories/mem_abc123 \
-H "Authorization: Bearer YOUR_API_KEY"Response
{
"deleted": true
}Best Practices
Structure Your Memories
Store memories in a consistent format for better search results:
{
"content": "User preference: dark mode theme",
"metadata": {
"category": "preferences",
"type": "ui"
}
}Use Meaningful Categories
| Category | Example Content |
|---|---|
preferences | UI settings, language, timezone |
context | Project details, tech stack |
history | Past interactions, completed tasks |
personal | Name, role, communication style |
Search Before Creating
Avoid duplicate memories by searching first:
// Check if similar memory exists
const existing = await searchMemories({
user_id: "user_123",
query: "dark mode preference",
});
if (existing.memories.length === 0) {
await createMemory({
user_id: "user_123",
content: "User prefers dark mode",
});
}Pricing
| Operation | Cost |
|---|---|
| Create | Free |
| List | Free |
| Search | Free |
| Delete | Free |
Standalone Service
The Memories API is a standalone service. Use a unique user_id to store and
retrieve memories independently from Chat API conversations.