Store Memories

Extract and store memories from conversation messages

POST /v1/memories

cURL

curl -X POST "https://api.memchat.io/v1/memories" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "I just got promoted to Senior Software Engineer at Google! I'll be working on their ML infrastructure team."
      },
      {
        "role": "assistant", 
        "content": "Congratulations on your promotion! That's a significant achievement. Working on ML infrastructure at Google must be exciting."
      },
      {
        "role": "user",
        "content": "Thanks! I'm really excited. I'll be leading a team of 5 engineers and working on scaling their recommendation systems."
      }
    ],
    "agent_id": "career-advisor-bot",
    "thread_id": "conversation-2024-001", 
    "source": "chat",
    "metadata": {
      "timestamp": "2024-03-20T10:00:00Z",
      "platform": "web-app",
      "session_id": "session-abc123"
    }
  }'

import requests

headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "messages": [
        {
            "role": "user",
            "content": "I just got promoted to Senior Software Engineer at Google! I'll be working on their ML infrastructure team."
        },
        {
            "role": "assistant",
            "content": "Congratulations on your promotion! That's a significant achievement. Working on ML infrastructure at Google must be exciting."
        },
        {
            "role": "user", 
            "content": "Thanks! I'm really excited. I'll be leading a team of 5 engineers and working on scaling their recommendation systems."
        }
    ],
    "agent_id": "career-advisor-bot",
    "thread_id": "conversation-2024-001",
    "source": "chat",
    "metadata": {
        "timestamp": "2024-03-20T10:00:00Z",
        "platform": "web-app",
        "session_id": "session-abc123"
    }
}

response = requests.post("https://api.memchat.io/v1/memories", 
                        headers=headers, json=data)
print(response.json())

const response = await fetch('https://api.memchat.io/v1/memories', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    messages: [
      {
        role: 'user',
        content: "I just got promoted to Senior Software Engineer at Google! I'll be working on their ML infrastructure team."
      },
      {
        role: 'assistant',
        content: "Congratulations on your promotion! That's a significant achievement. Working on ML infrastructure at Google must be exciting."
      },
      {
        role: 'user',
        content: "Thanks! I'm really excited. I'll be leading a team of 5 engineers and working on scaling their recommendation systems."
      }
    ],
    agent_id: 'career-advisor-bot',
    thread_id: 'conversation-2024-001',
    source: 'chat',
    metadata: {
      timestamp: '2024-03-20T10:00:00Z',
      platform: 'web-app',
      session_id: 'session-abc123'
    }
  })
});

const result = await response.json();
console.log(result);

Success Response

{
  "success": true,
  "memories_created": 3,
  "processing_time": "1.8s",
  "categories_detected": ["career", "identity"],
  "memories": [
    {
      "id": "mem_789abc",
      "memory": "Recently promoted to Senior Software Engineer at Google",
      "categories": ["career"],
      "type": "episodic",
      "created_at": "2024-03-20T10:00:15Z"
    },
    {
      "id": "mem_456def", 
      "memory": "Works on ML infrastructure team at Google",
      "categories": ["career"],
      "type": "semantic",
      "created_at": "2024-03-20T10:00:15Z"
    },
    {
      "id": "mem_123ghi",
      "memory": "Leads a team of 5 engineers working on recommendation systems",
      "categories": ["career"],
      "type": "episodic", 
      "created_at": "2024-03-20T10:00:15Z"
    }
  ]
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request format",
    "details": {
      "field": "messages",
      "reason": "At least one message is required"
    }
  },
  "status": "error",
  "timestamp": "2024-03-20T10:00:00Z"
}

Store and process conversation messages to extract meaningful memories. MemSync will automatically analyze the conversation, extract facts, categorize them, and store them as searchable memories.

Authentication

X-API-Key · string · required

API key for authentication

Request Body

messages · array · required

Array of conversation messages between user and assistant

Show Message Object

role · string · required

Role of the message sender: “user” or “assistant”

content · string · required

Content of the message

agent_id · string · required

Identifier for the agent or application storing the memories

thread_id · string · required

Unique identifier for the conversation thread

source · string · required

Source of the conversation data (e.g., “chat”, “email”, “sms”)

metadata · object

Additional metadata about the conversation

Show Metadata Object

timestamp · string

ISO 8601 timestamp of the conversation

platform · string

Platform where the conversation occurred

session_id · string

Session identifier for grouping related conversations

Response

success · boolean

Indicates if the memory storage was successful

memories_created · number

Number of memories extracted and stored from the conversation

processing_time · string

Time taken to process the conversation (e.g., “1.2s”)

categories_detected · array

Array of memory categories detected in the conversation

cURL

curl -X POST "https://api.memchat.io/v1/memories" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "I just got promoted to Senior Software Engineer at Google! I'll be working on their ML infrastructure team."
      },
      {
        "role": "assistant", 
        "content": "Congratulations on your promotion! That's a significant achievement. Working on ML infrastructure at Google must be exciting."
      },
      {
        "role": "user",
        "content": "Thanks! I'm really excited. I'll be leading a team of 5 engineers and working on scaling their recommendation systems."
      }
    ],
    "agent_id": "career-advisor-bot",
    "thread_id": "conversation-2024-001", 
    "source": "chat",
    "metadata": {
      "timestamp": "2024-03-20T10:00:00Z",
      "platform": "web-app",
      "session_id": "session-abc123"
    }
  }'

import requests

headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "messages": [
        {
            "role": "user",
            "content": "I just got promoted to Senior Software Engineer at Google! I'll be working on their ML infrastructure team."
        },
        {
            "role": "assistant",
            "content": "Congratulations on your promotion! That's a significant achievement. Working on ML infrastructure at Google must be exciting."
        },
        {
            "role": "user", 
            "content": "Thanks! I'm really excited. I'll be leading a team of 5 engineers and working on scaling their recommendation systems."
        }
    ],
    "agent_id": "career-advisor-bot",
    "thread_id": "conversation-2024-001",
    "source": "chat",
    "metadata": {
        "timestamp": "2024-03-20T10:00:00Z",
        "platform": "web-app",
        "session_id": "session-abc123"
    }
}

response = requests.post("https://api.memchat.io/v1/memories", 
                        headers=headers, json=data)
print(response.json())

const response = await fetch('https://api.memchat.io/v1/memories', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    messages: [
      {
        role: 'user',
        content: "I just got promoted to Senior Software Engineer at Google! I'll be working on their ML infrastructure team."
      },
      {
        role: 'assistant',
        content: "Congratulations on your promotion! That's a significant achievement. Working on ML infrastructure at Google must be exciting."
      },
      {
        role: 'user',
        content: "Thanks! I'm really excited. I'll be leading a team of 5 engineers and working on scaling their recommendation systems."
      }
    ],
    agent_id: 'career-advisor-bot',
    thread_id: 'conversation-2024-001',
    source: 'chat',
    metadata: {
      timestamp: '2024-03-20T10:00:00Z',
      platform: 'web-app',
      session_id: 'session-abc123'
    }
  })
});

const result = await response.json();
console.log(result);

Success Response

{
  "success": true,
  "memories_created": 3,
  "processing_time": "1.8s",
  "categories_detected": ["career", "identity"],
  "memories": [
    {
      "id": "mem_789abc",
      "memory": "Recently promoted to Senior Software Engineer at Google",
      "categories": ["career"],
      "type": "episodic",
      "created_at": "2024-03-20T10:00:15Z"
    },
    {
      "id": "mem_456def", 
      "memory": "Works on ML infrastructure team at Google",
      "categories": ["career"],
      "type": "semantic",
      "created_at": "2024-03-20T10:00:15Z"
    },
    {
      "id": "mem_123ghi",
      "memory": "Leads a team of 5 engineers working on recommendation systems",
      "categories": ["career"],
      "type": "episodic", 
      "created_at": "2024-03-20T10:00:15Z"
    }
  ]
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request format",
    "details": {
      "field": "messages",
      "reason": "At least one message is required"
    }
  },
  "status": "error",
  "timestamp": "2024-03-20T10:00:00Z"
}

How Memory Extraction Works

When you store a conversation, MemSync performs several steps:

1. Context Analysis: Analyzes the full conversation to understand context and meaning
2. Fact Extraction: Identifies meaningful facts and information about the user
3. Memory Classification: Categorizes memories as semantic (lasting facts) or episodic (time-bound events)
4. Category Assignment: Assigns memories to relevant categories (career, interests, etc.)
5. Storage: Stores memories with vector embeddings for semantic search

Best Practices

Message Quality

• Include sufficient context in conversations for better memory extraction
• Use natural language rather than fragmented responses
• Include follow-up questions and clarifications when relevant

Conversation Structure

{
  "messages": [
    {
      "role": "user",
      "content": "I'm a software engineer who loves hiking and photography"
    },
    {
      "role": "assistant", 
      "content": "That's a great combination! Do you have any favorite hiking spots where you like to take photos?"
    },
    {
      "role": "user",
      "content": "Yes! I love going to Yosemite National Park. I've been there 5 times in the past 2 years."
    }
  ]
}

Metadata Usage

Include relevant metadata to enhance memory context:

{
  "metadata": {
    "timestamp": "2024-03-20T10:00:00Z",
    "platform": "mobile-app",
    "session_id": "session-xyz789",
    "conversation_type": "onboarding",
    "user_initiated": true
  }
}

Rate Limiting

This endpoint has standard rate limiting:

• 100 requests per minute per authenticated user
• Bulk processing may take longer for large conversations
• Consider implementing retry logic for high-volume applications

Error Codes

Error Code	Description
VALIDATION_ERROR	Invalid request format or missing required fields
AUTHENTICATION_ERROR	Invalid or missing API key
RATE_LIMIT_EXCEEDED	Too many requests in the time window
PROCESSING_ERROR	Error occurred during memory extraction

Next Steps

After storing memories, you can:

Search Memories

Learn how to search for and retrieve stored memories

Get User Profile

View how memories contribute to the user’s profile

List Memories

Browse all stored memories for the user

Memory Categories

Learn about memory categorization