Quick Start

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)
curl installed (or any HTTP client)

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

End-to-End Walkthrough

Get your API key

Log in to the MemoryLake Console and generate an API key from your account settings. You will use this key in the Authorization header for all API calls.

export MEMORYLAKE_API_KEY="YOUR_API_KEY"

Create a workspace

A workspace is the top-level container for all your data. Create one to get started.

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"
  }'

Response

{
  "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.

Create an actor

An actor represents a participant in conversations. Create one for the human user whose memory you want to track.

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"
  }'

Response

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

Bind the actor to your workspace so MemoryLake can associate facts with this actor across all projects in the workspace. See Bind Actor for details.

Create a project

A project is a knowledge container within a workspace. It holds documents, conversations, and the facts extracted from them.

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"
  }'

Response

{
  "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"
  }
}

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:

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"
  }'

Response

{
  "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):

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):

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?"
      }
    ]
  }'

After you submit messages, MemoryLake processes them asynchronously. Facts are typically available within a few seconds.

Search your memories

Search across the workspace to find the facts that MemoryLake extracted from the conversation.

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?"
  }'

Response

{
  "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.

Complete Python Example

Here is the full flow in a single Python script:

quickstart.py

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:

Created a workspace to isolate your data
Created an actor to represent a human user
Created a project to hold your knowledge
Submitted a conversation with messages
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

Workspaces & Projects

Learn when to use multiple workspaces vs. multiple projects

Actors & Memory

Understand how per-user memory works across projects

Memory Pipeline

Dive deeper into how conversations become structured facts

API Reference

Explore the full API for workspaces, actors, projects, and search

Getting started

Scenarios

Memory Router

Model Router

MemoryLake

Team collaboration

Prerequisites

End-to-End Walkthrough

Complete Python Example

What You Built

Next Steps

Workspaces & Projects

Actors & Memory

Memory Pipeline

API Reference

​Prerequisites

​End-to-End Walkthrough

​Complete Python Example

​What You Built

​Next Steps

Workspaces & Projects

Actors & Memory

Memory Pipeline

API Reference

Prerequisites

End-to-End Walkthrough

Complete Python Example

What You Built

Next Steps