前提条件
- 拥有 MemoryLake 账户和 API 密钥(参见认证)
- 已安装
curl(或任意 HTTP 客户端)
所有示例使用基础 URL
https://app.memorylake.cn/openapi/memorylake。请在每个请求中将 YOUR_API_KEY 替换为您的实际 API 密钥。端到端演练
1
获取 API 密钥
登录 MemoryLake 控制台,在账户设置中生成 API 密钥。您将在所有 API 调用的
Authorization 请求头中使用此密钥。export MEMORYLAKE_API_KEY="YOUR_API_KEY"
2
创建工作空间
工作空间是所有数据的顶层容器。创建一个工作空间即可开始。保存工作空间的
curl -X POST https://app.memorylake.cn/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"
}
}
id——后续步骤中会用到。3
创建 Actor
Actor 代表会话中的参与者。为需要追踪记忆的人类用户创建一个 Actor。
curl -X POST https://app.memorylake.cn/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"
}
}
将 Actor 绑定到工作空间,以便 MemoryLake 在该工作空间的所有项目中将事实与此 Actor 关联。详见绑定 Actor。
4
创建项目
项目是工作空间中的知识容器,用于存放文档、会话及从中提取的事实。
curl -X POST https://app.memorylake.cn/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"
}
}
5
创建会话并追加消息
向工作空间提交一段会话。首先创建会话,然后逐条添加消息。MemoryLake 会自动从消息中提取结构化事实。创建会话:追加第一条消息(用户):追加第二条消息(助手):
curl -X POST https://app.memorylake.cn/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"
}
}
curl -X POST https://app.memorylake.cn/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."
}
]
}'
curl -X POST https://app.memorylake.cn/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?"
}
]
}'
提交消息后,MemoryLake 会异步处理。事实通常在几秒钟内即可使用。
6
搜索记忆
在工作空间中搜索 MemoryLake 从会话中提取的事实。MemoryLake 自动从会话中提取了结构化事实,并将其关联到 Jane 的 Actor。这些事实会持久保存,并可在整个工作空间内搜索。
curl -X POST https://app.memorylake.cn/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"
}
]
}
}
完整 Python 示例
以下是将完整流程整合在一个 Python 脚本中的示例:quickstart.py
import requests
import time
BASE_URL = "https://app.memorylake.cn/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']})")
完成内容
仅需几分钟,您已经:- 创建了一个工作空间来隔离数据
- 创建了一个Actor来代表人类用户
- 创建了一个项目来存放知识
- 提交了一段带有消息的会话
- 搜索并检索了自动提取的事实
下一步
工作空间与项目
了解何时使用多个工作空间与多个项目
Actor 与记忆
了解跨项目的每用户记忆如何工作
记忆管道
深入了解会话如何转化为结构化事实
API 参考
探索工作空间、Actor、项目和搜索的完整 API