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

# Quick Start

> Get started with MemoryLake in 5 minutes -- create a workspace, submit a conversation, and search your memories

This guide walks you through the core MemoryLake workflow using the API. By the end, you will have created a workspace, submitted a conversation, and searched the extracted memories.

## Prerequisites

* A MemoryLake account with an API key (see [Authentication](/authentication))
* `curl` installed (or any HTTP client)

<Note>
  All examples use the base URL `https://app.memorylake.ai/openapi/memorylake`. Replace `YOUR_API_KEY` with your actual API key in every request.
</Note>

## End-to-End Walkthrough

<Steps>
  <Step title="Get your API key">
    Log in to the [MemoryLake Console](https://app.memorylake.ai) and generate an API key from your account settings. You will use this key in the `Authorization` header for all API calls.

    ```bash theme={null}
    export MEMORYLAKE_API_KEY="YOUR_API_KEY"
    ```
  </Step>

  <Step title="Create a workspace">
    A workspace is the top-level container for all your data. Create one to get started.

    ```bash theme={null}
    curl -X POST https://app.memorylake.ai/openapi/memorylake/api/v3/workspaces \
      -H "Authorization: Bearer $MEMORYLAKE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "custom_id": "ws-quickstart-001",
        "name": "My First Workspace",
        "description": "Testing MemoryLake memory extraction"
      }'
    ```

    ```json Response theme={null}
    {
      "success": true,
      "data": {
        "id": "ws_abc123",
        "custom_id": "ws-quickstart-001",
        "name": "My First Workspace",
        "description": "Testing MemoryLake memory extraction",
        "created_at": "2026-07-09T10:00:00Z"
      }
    }
    ```

    Save the workspace `id` -- you will need it in subsequent steps.
  </Step>

  <Step title="Create an actor">
    An actor represents a participant in conversations. Create one for the human user whose memory you want to track.

    ```bash theme={null}
    curl -X POST https://app.memorylake.ai/openapi/memorylake/api/v3/actors \
      -H "Authorization: Bearer $MEMORYLAKE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "custom_id": "jane-001",
        "display_name": "Jane",
        "actor_type": "HUMAN"
      }'
    ```

    ```json Response theme={null}
    {
      "success": true,
      "data": {
        "id": "act_jane456",
        "custom_id": "jane-001",
        "display_name": "Jane",
        "actor_type": "HUMAN",
        "created_at": "2026-07-09T10:01:00Z"
      }
    }
    ```

    <Tip>
      Bind the actor to your workspace so MemoryLake can associate facts with this actor across all projects in the workspace. See [Bind Actor](/features/memorylake/api-reference/actors/bind-actor) for details.
    </Tip>
  </Step>

  <Step title="Create a project">
    A project is a knowledge container within a workspace. It holds documents, conversations, and the facts extracted from them.

    ```bash theme={null}
    curl -X POST https://app.memorylake.ai/openapi/memorylake/api/v3/workspaces/ws_abc123/projects \
      -H "Authorization: Bearer $MEMORYLAKE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "custom_id": "proj-support-001",
        "name": "Customer Support Bot",
        "description": "Knowledge base for our support assistant"
      }'
    ```

    ```json Response theme={null}
    {
      "success": true,
      "data": {
        "id": "proj_def789",
        "custom_id": "proj-support-001",
        "name": "Customer Support Bot",
        "description": "Knowledge base for our support assistant",
        "workspace_id": "ws_abc123",
        "created_at": "2026-07-09T10:02:00Z"
      }
    }
    ```
  </Step>

  <Step title="Create a conversation and append messages">
    Submit a conversation to the workspace. First, create the conversation, then add messages one at a time. MemoryLake automatically extracts structured facts from the messages.

    **Create the conversation:**

    ```bash theme={null}
    curl -X POST https://app.memorylake.ai/openapi/memorylake/api/v3/workspaces/ws_abc123/memories/conversations \
      -H "Authorization: Bearer $MEMORYLAKE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "custom_id": "conv-onboarding-001",
        "kind": "DIRECT",
        "rw_project_ids": ["proj_def789"],
        "name": "Onboarding chat with Jane"
      }'
    ```

    ```json Response theme={null}
    {
      "success": true,
      "data": {
        "id": "conv_ghi012",
        "custom_id": "conv-onboarding-001",
        "kind": "DIRECT",
        "rw_project_ids": ["proj_def789"],
        "name": "Onboarding chat with Jane",
        "created_at": "2026-07-09T10:03:00Z"
      }
    }
    ```

    **Append the first message (user):**

    ```bash theme={null}
    curl -X POST https://app.memorylake.ai/openapi/memorylake/api/v3/conversations/conv_ghi012/messages \
      -H "Authorization: Bearer $MEMORYLAKE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "custom_id": "msg-001",
        "actor_id": "act_jane456",
        "content": [
          {
            "block_type": "TEXT",
            "text": "Hi, I am Jane. I work at Acme Corp as a product manager. I prefer concise answers and I use dark mode in all my apps."
          }
        ]
      }'
    ```

    **Append the second message (assistant):**

    ```bash theme={null}
    curl -X POST https://app.memorylake.ai/openapi/memorylake/api/v3/conversations/conv_ghi012/messages \
      -H "Authorization: Bearer $MEMORYLAKE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "custom_id": "msg-002",
        "actor_id": "act_jane456",
        "content": [
          {
            "block_type": "TEXT",
            "text": "Welcome Jane! I have noted your preferences. How can I help you today?"
          }
        ]
      }'
    ```

    <Note>
      After you submit messages, MemoryLake processes them asynchronously. Facts are typically available within a few seconds.
    </Note>
  </Step>

  <Step title="Search your memories">
    Search across the workspace to find the facts that MemoryLake extracted from the conversation.

    ```bash theme={null}
    curl -X POST https://app.memorylake.ai/openapi/memorylake/api/v3/workspaces/ws_abc123/memories/search \
      -H "Authorization: Bearer $MEMORYLAKE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "query": "What are Jane preferences?"
      }'
    ```

    ```json Response theme={null}
    {
      "success": true,
      "data": {
        "documents": [],
        "facts": [
          {
            "id": "fact_001",
            "fact": "Jane prefers concise answers",
            "score": 0.95,
            "metadata": {},
            "created_at": "2026-07-09T10:03:05Z",
            "updated_at": "2026-07-09T10:03:05Z"
          },
          {
            "id": "fact_002",
            "fact": "Jane uses dark mode in all her apps",
            "score": 0.92,
            "metadata": {},
            "created_at": "2026-07-09T10:03:05Z",
            "updated_at": "2026-07-09T10:03:05Z"
          },
          {
            "id": "fact_003",
            "fact": "Jane works at Acme Corp as a product manager",
            "score": 0.85,
            "metadata": {},
            "created_at": "2026-07-09T10:03:05Z",
            "updated_at": "2026-07-09T10:03:05Z"
          }
        ]
      }
    }
    ```

    MemoryLake automatically extracted structured facts from the conversation and associated them with Jane's actor. These facts persist and are searchable across the workspace.
  </Step>
</Steps>

## Complete Python Example

Here is the full flow in a single Python script:

```python quickstart.py theme={null}
import requests
import time

BASE_URL = "https://app.memorylake.ai/openapi/memorylake/api/v3"
API_KEY = "YOUR_API_KEY"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# 1. Create a workspace
workspace = requests.post(
    f"{BASE_URL}/workspaces",
    headers=headers,
    json={
        "custom_id": "ws-quickstart-001",
        "name": "My First Workspace",
        "description": "Testing MemoryLake memory extraction",
    },
).json()
workspace_id = workspace["data"]["id"]
print(f"Workspace created: {workspace_id}")

# 2. Create an actor
actor = requests.post(
    f"{BASE_URL}/actors",
    headers=headers,
    json={
        "custom_id": "jane-001",
        "display_name": "Jane",
        "actor_type": "HUMAN",
    },
).json()
actor_id = actor["data"]["id"]
print(f"Actor created: {actor_id}")

# 3. Create a project
project = requests.post(
    f"{BASE_URL}/workspaces/{workspace_id}/projects",
    headers=headers,
    json={
        "custom_id": "proj-support-001",
        "name": "Customer Support Bot",
        "description": "Knowledge base for our support assistant",
    },
).json()
project_id = project["data"]["id"]
print(f"Project created: {project_id}")

# 4. Create a conversation
conversation = requests.post(
    f"{BASE_URL}/workspaces/{workspace_id}/memories/conversations",
    headers=headers,
    json={
        "custom_id": "conv-onboarding-001",
        "kind": "DIRECT",
        "rw_project_ids": [project_id],
        "name": "Onboarding chat with Jane",
    },
).json()
conversation_id = conversation["data"]["id"]
print(f"Conversation created: {conversation_id}")

# 5. Append messages (one at a time)
requests.post(
    f"{BASE_URL}/conversations/{conversation_id}/messages",
    headers=headers,
    json={
        "custom_id": "msg-001",
        "actor_id": actor_id,
        "content": [
            {
                "block_type": "TEXT",
                "text": "Hi, I am Jane. I work at Acme Corp as a product manager. I prefer concise answers.",
            }
        ],
    },
)

requests.post(
    f"{BASE_URL}/conversations/{conversation_id}/messages",
    headers=headers,
    json={
        "custom_id": "msg-002",
        "actor_id": actor_id,
        "content": [
            {
                "block_type": "TEXT",
                "text": "Welcome Jane! I have noted your preferences. How can I help you today?",
            }
        ],
    },
)
print("Messages submitted")

# 6. Wait for fact extraction
print("Waiting for fact extraction...")
time.sleep(5)

# 7. Search memories
results = requests.post(
    f"{BASE_URL}/workspaces/{workspace_id}/memories/search",
    headers=headers,
    json={"query": "What are Jane preferences?"},
).json()

print("\nExtracted memories:")
for fact in results.get("data", {}).get("facts", []):
    print(f"  - {fact['fact']} (score: {fact['score']})")
```

## What You Built

In just a few minutes, you:

1. Created a **workspace** to isolate your data
2. Created an **actor** to represent a human user
3. Created a **project** to hold your knowledge
4. Submitted a **conversation** with messages
5. **Searched** and retrieved the automatically extracted facts

MemoryLake handled the hard part -- parsing the conversation, identifying facts, associating them with the right actor, and indexing everything for search.

## Next Steps

<CardGroup cols={2}>
  <Card title="Workspaces & Projects" icon="layer-group" href="/features/memorylake/core-concepts/workspaces-and-projects">
    Learn when to use multiple workspaces vs. multiple projects
  </Card>

  <Card title="Actors & Memory" icon="user" href="/features/memorylake/core-concepts/actors-and-memory">
    Understand how per-user memory works across projects
  </Card>

  <Card title="Memory Pipeline" icon="diagram-project" href="/features/memorylake/core-concepts/memory-pipeline">
    Dive deeper into how conversations become structured facts
  </Card>

  <Card title="API Reference" icon="code" href="/features/memorylake/api-reference/overview">
    Explore the full API for workspaces, actors, projects, and search
  </Card>
</CardGroup>