长期记忆 / LTM

Turing LTM 将已接受的对话 Event 异步派生为 Profile、Facts 和 Summary，并通过 Browser、Search、Context 与 Reflection 提供不同粒度的读取能力。Developer Platform 的“长期记忆”工作区用于完成项目级记忆的配置、调试与接入。

把 LTM 想成一条“事件 → 派生 → 读取”流水线：应用不需要自己维护向量库和摘要任务，但仍然决定哪些事件值得写入、在哪个 Space 内共享，以及何时把结果交给模型。

Space 是硬边界

每次 Event、读取和 Managed Chat 请求都必须绑定一个 Space。数据、模型、策略和 Owner 范围不会跨越所选 Space。同一项目的 USER 或 CLIENT_ADMIN 均可使用工作区；删除 Space 等破坏性控制操作仍需 CLIENT_ADMIN。

选择接入方式

场景	接入面	数据边界
应用或项目需要 Actor / 共享记忆	Developer Platform 的项目 LTM 工作区；使用 Public LTM API，或接入 Managed Chat	当前项目、Environment 和 Space
Codex、Claude Code、OpenClaw 等本地 Agent 共享个人记忆	Agent Memory + Turing CLI Memory	每位 Portal 用户独立的 Personal Space

Agent Memory 是个人场景的实验性接入，不是项目 LTM 的 Host Adapter。两者复用相同的底层 Public LTM 能力，但只有显式绑定同一个 space_id 时才会读写同一份记忆。

完成第一个闭环

1. 在 Developer Platform 中进入目标项目的“长期记忆”，创建或选择一个 Space。
2. 配置 Embedding、默认 LLM、Profile / Facts / Summary 策略，并按需启用 Reflection。
3. 在 Event Playground 提交一条 Actor 或 Space Event。Accepted 只表示已进入异步处理队列，不代表派生记忆已经可读。
4. 在 Memory Explorer 用 Browser 查看记录，用 Search 验证语义召回，用 Context 验证可注入模型的有界上下文，并按需读取或生成 Reflection。
5. 根据应用控制边界，选择直接调用 Public LTM，或让 Chat Completions 托管 Recall、Evidence 注入与终态 Capture。

用 API 在 5 分钟内跑通

下面的顺序对应工作区里的 Spaces → Event Playground → Memory Explorer。先把环境变量换成当前项目的地址和 API Key；TURING_BASE_URL 应包含 /api/v1。

1. 发现模型并创建 Space

先读取当前环境发布的 LLM 家族，再把返回的稳定 family 别名填入 model_profile.default。Embedding 模型是创建时绑定的不可变配置。

export TURING_BASE_URL="https://live-turing.cn.llm.tcljd.com/api/v1"
export TURING_API_KEY="<your-api-key>"

curl "$TURING_BASE_URL/ltm/families" \
  -H "Authorization: Bearer $TURING_API_KEY"

curl "$TURING_BASE_URL/ltm/spaces" \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support",
    "description": "Support conversations for the customer-facing assistant",
    "embedding_model": "<embedding-model-from-your-environment>",
    "model_profile": {"default": "<llm-family-from-ltm-families>"}
  }'

创建响应里的 data.space_id 是后续请求的唯一边界。不要把 Space ID 写死在客户端配置之外，也不要在不同项目或环境之间复用它。

2. 写入一条 Event

Event 是 V1 唯一的公共写入入口。每次请求只提交新增的消息，不要重复发送完整历史；相同 session_id 表示同一段会话。

export SPACE_ID="<space-id>"
export ACTOR_ID="user-123"

curl "$TURING_BASE_URL/ltm/spaces/$SPACE_ID/events" \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: support-session-20260912-01" \
  -d '{
    "owner_type": "actor",
    "actor_id": "user-123",
    "session_id": "support-session-20260912",
    "messages": [
      {"role": "user", "content": "我偏好用中文，并且每周一要收到项目摘要。"},
      {"role": "assistant", "content": "记住了。"}
    ],
    "metadata": {"channel": "web"}
  }'

成功返回 HTTP 202 和 data.status = "accepted"，只表示 Event 已进入异步派生队列。不要用 accepted 当作“记忆已生成”；稍后用 Browser 或 Context/Search 验证结果。

3. 读取并注入记忆

按用途选择读取原语：

你要解决的问题	API	适合的调用时机	是否调用 LLM
检查到底生成了哪些记录	List memories	调试、管理后台、分页浏览	否
找与当前问题最相关的记忆	Search memories	每轮回答前按问题检索	否；只生成一次查询向量
一次拿到有界的可注入上下文	Get context	新会话初始化或模型上下文组装	否
让平台托管 Recall 与 Capture	Chat Completions 的 turing_options.memory	不想自己维护 Agent loop	由主 Chat 请求调用一次主 LLM

# 会话简报：适合在新会话开始时预加载
curl "$TURING_BASE_URL/ltm/spaces/$SPACE_ID/context?actor_id=$ACTOR_ID&include_shared=true&token_budget=4000" \
  -H "Authorization: Bearer $TURING_API_KEY"

# 按当前问题做语义召回：适合每轮回答前调用
curl "$TURING_BASE_URL/ltm/spaces/$SPACE_ID/memories/search" \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "这个用户对通知频率有什么偏好？",
    "actor_id": "user-123",
    "include_shared": true,
    "top_k": 5
  }'

所有公共 LTM 响应都沿用 Turing 的 code / message / data 外层。Context 的 data.rendered 是带边界标记的 Markdown 参考材料，应该作为模型输入中的不可信上下文，而不是系统或开发者指令。

4. 不想维护 Agent loop？使用 Managed Chat

curl "$TURING_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "turing/gpt-5.4-mini",
    "messages": [{"role": "user", "content": "帮我总结这个项目的通知偏好"}],
    "turing_options": {
      "memory": {
        "enabled": true,
        "space_id": "<space-id>",
        "owner_type": "actor",
        "actor_id": "user-123",
        "include_shared": true,
        "session_id": "support-session-20260912"
      }
    }
  }'

Managed Chat 会在合格的终态回答后自动 Capture；工具调用中间态不会提前写入。若模型发生 fallback，整次 Memory 旁路，不会产生 LTM、Embedding 或 Capture 成本。

工作区能力

工作区	用途	关键边界
Spaces	创建、选择和配置 Space、模型、策略与 Reflection	Embedding 模型创建后不可修改；首次 Actor Event 后 Profile Schema 永久冻结；删除 Space 是需要 CLIENT_ADMIN 的破坏性操作
Event Playground	提交带 session_id 和消息序列的 Actor / Space Event，并预览准确请求	可选 idempotency key、时间戳和标量 metadata；处理是异步的
Memory Explorer	Browser、Search、Context 和 Reflections	每次读取都显式选择 Owner 范围；Reflection 必须先在 Space 中启用
Managed Chat	构造并执行带 Memory Binding 的真实 Chat Completions 请求	仅托管请求级记忆，不改变调用方的对话协议或返回 Evidence

Space 设置控制提取与召回行为。派生后的记忆记录通过 Event 与 Browser 流程管理，不在 Space 设置中直接编辑。

Owner 与读取范围

• Actor only 读取：Browser、Search 与 Context 发送 actor_id，并省略 include_shared 或将其设为 false，读取该 Actor 的 Profile、Facts 与 Summary。
• Actor + shared 读取：同时发送 actor_id 与 include_shared: true，在 Actor 记忆中加入 Space 共享 Facts。
• Shared only 读取：完全省略 actor_id，并发送 include_shared: true；共享范围只支持 Facts。
• Reflections：Actor Portrait 与 Activity Insights 都是 Actor 级能力，不支持 shared-only 范围。

owner_type 不属于 Browser、Search 或 Context 的读取 scope。Event 与 Managed Chat Binding 才显式使用 owner_type: "actor" 或 owner_type: "space"；Space Owner 请求必须省略 actor_id。

Browser 适合分页检查已派生记录；Search 适合语义检索；Context 按 token budget 组装可直接注入模型的有界上下文；Reflections 用于按需生成或读取 Actor 报告。

Managed Chat 边界

当应用希望继续调用 /chat/completions，但不自行组装 Prompt 或维护 Capture 时，在请求中增加 Memory Binding：

{
  "turing_options": {
    "memory": {
      "enabled": true,
      "space_id": "ltmspace_...",
      "owner_type": "actor",
      "actor_id": "user-123",
      "include_shared": true,
      "session_id": "session-2026-08-24"
    }
  }
}

• 终态回答：一次 Recall、一次主 LLM 调用，然后提交一个 Event Capture。
• Caller tool call：一次 Recall 和一次主 LLM 调用；在终态 continuation 前跳过 Capture。
• 任意 fallback topology：Memory 整体旁路，即 0 LTM、0 Embedding、0 Capture。
• 鉴权：只接受认证后的 Turing Bearer JWT 或 Turing API Key；其他鉴权方式会在 LTM、Embedding 和主 LLM 产生费用前被拒绝。

Evidence 不会返回给调用方。Developer Platform 会展示公共 Chat 响应、Memory outcome headers 与 Trace，便于判断 Recall 和 Capture 的结果。应用自己控制 Prompt 组装或 Agent loop 时，应直接使用 Context、Search 和 Event，而不是 Managed Chat。

V1 接口范围

核心 Public LTM 端点和 turing_options.memory 已进入本 API 文档的 OpenAPI 参考；typed SDK schema 仍在后续版本中补齐。Developer Platform 的 Managed Chat Builder 仍提供准确 JSON、cURL 和真实请求诊断，不要依赖尚未发布的 SDK 生成类型。

See also

• Chat Completions
• Agent Memory
• Turing CLI Memory