Skip to main content

​
Memory API

The Memory API enables storage and retrieval of contextual information to personalize AI interactions and maintain context across conversations.

​
Memory Object

​
id
string
Unique memory identifier
​
content
string
Memory content/text
​
metadata
object
Optional metadata (tags, categories, source, etc.)
​
created_at
string
ISO 8601 creation timestamp
​
updated_at
string
ISO 8601 last update timestamp

​
Endpoints

​
Get All Memories

Retrieve all memories for the current user. 
GET /api/v1/memory
Response
{
  "memories": [
    {
      "id": "mem_123",
      "content": "User prefers concise communication style",
      "metadata": {
        "category": "communication_preference",
        "source": "conversation"
      },
      "created_at": "2026-02-15T10:00:00Z",
      "updated_at": "2026-02-15T10:00:00Z"
    },
    {
      "id": "mem_456",
      "content": "Working on machine learning project using PyTorch",
      "metadata": {
        "category": "current_projects",
        "tags": ["ml", "pytorch"]
      },
      "created_at": "2026-02-18T14:30:00Z",
      "updated_at": "2026-02-18T14:30:00Z"
    }
  ],
  "total": 2
}

​
Create Memory

Store a new memory. 
POST /api/v1/memory
Request
{
  "content": "User is learning Spanish and practices daily at 7 AM",
  "metadata": {
    "category": "habits",
    "tags": ["language", "routine"],
    "source": "user_input"
  }
}
Response
{
  "success": true,
  "memory_id": "mem_789",
  "message": "Memory created successfully"
}
​
content
string
required
Memory content to store
​
metadata
object
Optional metadata for categorization and filteringCommon fields:
  • category - Memory category (preferences, habits, projects, etc.)
  • tags - Array of tags for easy filtering
  • source - Where the memory came from (conversation, user_input, etc.)
  • importance - Importance level (high, medium, low)

​
Delete Memory

Delete a specific memory. 
DELETE /api/v1/memory/{memory_id}
Response
{
  "success": true,
  "message": "Memory deleted successfully"
}

​
Clear All Memories

Delete all memories for the current user. 
DELETE /api/v1/memory
This operation is irreversible. All memories will be permanently deleted.
Response
{
  "success": true,
  "message": "All memories cleared successfully"
}

​
How Memories Work

​
Automatic Memory Creation

GAIA can automatically create memories during conversations when it learns new information about you:
  • User preferences (communication style, working hours, etc.)
  • Current projects and goals
  • Important contacts and relationships
  • Habits and routines
  • Technical preferences (programming languages, tools, etc.)

​
Memory Retrieval

Memories are automatically retrieved and used to:
  • Personalize AI responses
  • Provide relevant context in conversations
  • Suggest proactive actions
  • Improve recommendation quality
Memories are stored with embeddings for semantic search, allowing GAIA to find relevant memories even when exact keywords don’t match. Example:
  • Query: “What programming language am I using?”
  • Matched Memory: “Working on machine learning project using PyTorch”

​
Use Cases

​
Personal Preferences

{
  "content": "Prefers morning meetings between 9-11 AM",
  "metadata": {
    "category": "scheduling_preferences"
  }
}

​
Project Context

{
  "content": "Building e-commerce platform with Next.js and Stripe",
  "metadata": {
    "category": "current_projects",
    "tags": ["nextjs", "stripe", "ecommerce"]
  }
}

​
Communication Style

{
  "content": "Appreciates direct, concise responses without excessive pleasantries",
  "metadata": {
    "category": "communication_preference"
  }
}

​
Important Dates

{
  "content": "Product launch scheduled for March 15, 2026",
  "metadata": {
    "category": "important_dates",
    "tags": ["deadline", "product_launch"]
  }
}

​
Rate Limiting

Memory operations are subject to rate limits:
  • Free: 50 operations/hour
  • Pro: 500 operations/hour
  • Team: 2000 operations/hour
See Rate Limits for details.

​
Best Practices

Focus on storing information that helps personalize future interactions:✅ Good: “Prefers TypeScript over JavaScript for new projects”❌ Poor: “User clicked a button”
Add categories and tags to make memories searchable:
{
  "content": "Uses VS Code with Vim keybindings",
  "metadata": {
    "category": "development_tools",
    "tags": ["vscode", "vim", "editor"]
  }
}
Delete or update memories when information becomes outdated:
# Delete old memory
DELETE /api/v1/memory/mem_old_project

# Create updated memory
POST /api/v1/memory
{
  "content": "Now working with React Native instead of Flutter"
}
Store specific, actionable information rather than vague statements:✅ “Holds 1:1 meetings with direct reports every other Friday at 2 PM”❌ “Likes meetings”

​
Privacy & Security

  • Memories are encrypted at rest and in transit
  • Only the authenticated user can access their memories
  • Memories are not shared with other users
  • Deleting your account permanently deletes all memories

​
Next Steps

Chat API

Use memories in conversations

Integrations

Connect third-party services

Build docs developers (and LLMs) love

Get started for freeTalk to us