# Variables API

Variables API 是用于临时状态的快速键值存储。与记忆（被索引、可搜索、结构化）不同，变量针对快速读写做了优化 — 非常适合计数器、标志位和会话状态。

## 端点

### POST /var

设置或更新变量。

```bash
curl -X POST https://synapse.schaefer.zone/var \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "last_session_at", "value": "2026-06-27T14:00:00Z"}'
```

### GET /var/:key

获取单个变量。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/var/last_session_at
```

响应：

```json
{ "key": "last_session_at", "value": "2026-06-27T14:00:00Z", "updated_at": "..." }
```

### GET /var

列出所有变量。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/var
```

### DELETE /var/:key

删除变量。

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/var/last_session_at
```

## 何时使用变量、何时使用记忆

| 用例 | 使用 |
|----------|-----|
| 用户名、偏好 | Memory（可搜索、结构化） |
| 上次会话时间戳 | Variable（临时状态） |
| 计数器（例如已发送消息数） | Variable（频繁更新） |
| 工作流状态（“5 步中已完成 3 步”） | Variable（短暂状态） |
| 长篇项目笔记 | Memory（全文索引） |
| 可复用脚本 | Script 存储（命名、版本化） |

## 常见模式

### 跟踪上次会话

```bash
# 会话结束时
curl -X POST .../var -d '{"key": "last_session_at", "value": "'$(date -Iseconds)'"}'

# 会话开始时
LAST=$(curl .../var/last_session_at | jq -r .value)
curl .../memory/diff?since=$(date -d "$LAST" +%s)
```

### 计数器模式

```bash
# 自增
N=$(curl .../var/api_calls | jq -r .value)
curl -X POST .../var -d "{\"key\": \"api_calls\", \"value\": $((N+1))}"
```

### 功能开关

```bash
curl -X POST .../var -d '{"key": "feature_x_enabled", "value": "true"}'

# 检查
ENABLED=$(curl .../var/feature_x_enabled | jq -r .value)
if [ "$ENABLED" = "true" ]; then ... fi
```

## 下一步

- [Memory API](/docs/api/memory) — 用于结构化、可搜索的数据
- [Cron 与调度器](/docs/api/cron)