> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memsync.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Store Memories

> Extract and store memories from conversation messages

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

<ParamField header="X-API-Key" type="string" required>
  API key for authentication
</ParamField>

## Request Body

<ParamField body="messages" type="array" required>
  Array of conversation messages between user and assistant

  <Expandable title="Message Object">
    <ParamField body="role" type="string" required>
      Role of the message sender: "user" or "assistant"
    </ParamField>

    <ParamField body="content" type="string" required>
      Content of the message
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="agent_id" type="string" required>
  Identifier for the agent or application storing the memories
</ParamField>

<ParamField body="thread_id" type="string" required>
  Unique identifier for the conversation thread
</ParamField>

<ParamField body="source" type="string" required>
  Source of the conversation data (e.g., "chat", "email", "sms")
</ParamField>

<ParamField body="metadata" type="object">
  Additional metadata about the conversation

  <Expandable title="Metadata Object">
    <ParamField body="timestamp" type="string">
      ISO 8601 timestamp of the conversation
    </ParamField>

    <ParamField body="platform" type="string">
      Platform where the conversation occurred
    </ParamField>

    <ParamField body="session_id" type="string">
      Session identifier for grouping related conversations
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the memory storage was successful
</ResponseField>

<ResponseField name="memories_created" type="number">
  Number of memories extracted and stored from the conversation
</ResponseField>

<ResponseField name="processing_time" type="string">
  Time taken to process the conversation (e.g., "1.2s")
</ResponseField>

<ResponseField name="categories_detected" type="array">
  Array of memory categories detected in the conversation
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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);
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "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"
      }
    ]
  }
  ```

  ```json Error Response theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

## 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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

<CardGroup cols={2}>
  <Card title="Search Memories" icon="magnifying-glass" href="/api-reference/endpoint/search-memories">
    Learn how to search for and retrieve stored memories
  </Card>

  <Card title="Get User Profile" icon="user" href="/api-reference/endpoint/get-profile">
    View how memories contribute to the user's profile
  </Card>

  <Card title="List Memories" icon="list" href="/api-reference/endpoint/get-memories">
    Browse all stored memories for the user
  </Card>

  <Card title="Memory Categories" icon="tags" href="/essentials/categories">
    Learn about memory categorization
  </Card>
</CardGroup>