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

# 快速开始

> 从运行中的 Memorose 节点到完成一次真实写入和检索往返的最短路径。

# 快速开始

本页直接对应当前 `memorose-server` API。

## 准备工作

* 运行在 `http://127.0.0.1:3000` 的 Memorose 服务
* 仪表盘凭据
* `jq`
* `uuidgen`

<Note>
  在当前单节点默认配置中，Memorose 启动时会自动初始化 Raft。除非你刻意关闭 `raft.auto_initialize`，否则在发送写请求前不需要调用 `/v1/cluster/initialize`。
</Note>

## 最短路径

1. 登录并拿到 bearer token。
2. 创建一个 stream ID。
3. 写入一个事件。
4. 针对该 stream 做检索。
5. 检查 consolidation backlog 是否清空。

## 1. 设置基础变量

```bash theme={null}
export BASE_URL="http://127.0.0.1:3000"
export USER_ID="dylan"
export ORG_ID="default"
```

## 2. 登录并获取 token

当前 `/v1` 路由支持 dashboard JWT bearer token 或 API key。本地开发最快的方式仍然是 dashboard 登录。

```bash theme={null}
TOKEN=$(curl -s -X POST "$BASE_URL/v1/dashboard/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin"
  }' | jq -r '.token')
```

## 3. 创建 stream ID

```bash theme={null}
STREAM_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
```

## 4. 写入一个事件

```bash theme={null}
curl -s -X POST "$BASE_URL/v1/users/$USER_ID/streams/$STREAM_ID/events" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "default",
    "content": "Dylan prefers Rust for systems work and wants concise status updates.",
    "content_type": "text"
  }'
```

预期响应格式：

```json theme={null}
{
  "status": "accepted",
  "event_id": "..."
}
```

## 5. 检索记忆

```bash theme={null}
curl -s -X POST "$BASE_URL/v1/users/$USER_ID/streams/$STREAM_ID/retrieve" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "default",
    "query": "What does Dylan prefer for systems work?",
    "limit": 5,
    "graph_depth": 1
  }'
```

预期响应格式：

```json theme={null}
{
  "stream_id": "...",
  "query": "What does Dylan prefer for systems work?",
  "results": [
    {
      "unit": {
        "id": "...",
        "memory_type": "factual",
        "content": "...",
        "keywords": ["rust", "systems"],
        "level": 1
      },
      "score": 0.9
    }
  ],
  "query_time_ms": 12
}
```

关键响应字段：

* `results[].unit.level`：命中的记忆位于哪一层
* `results[].unit.memory_type`：`factual` 或 `procedural`
* `score`：检索融合后的最终排序分数
* `query_time_ms`：服务端观测到的检索耗时

## 6. 检查 consolidation backlog

```bash theme={null}
curl -s "$BASE_URL/v1/status/pending" \
  -H "Authorization: Bearer $TOKEN"
```

当 `"ready": true` 时，当前待处理事件积压已经清空。

## 下一步

* [配置](/zh/getting-started/configuration)
* [基本操作](/zh/guides/basic-operations)
* [集群 API](/zh/api/cluster)
* [任务与目标](/zh/guides/tasks-and-goals)
* [REST API](/zh/api/rest-api)