TMCRA MEMORY API / v0.2.0

面向生产级 AI Agent 的持久记忆 API。

把有序对话事件转化为租户隔离、具备时间结构、可直接供模型使用的证据。TMCRA 负责记忆，你的应用继续掌控 Agent Runtime 和最终回答模型。

生产基地址https://api.tmcra.com在线 Schema

协议: HTTPS / JSON
鉴权: Bearer token
写入模型: 异步任务
召回输出: 证据，不代答

快速接入

完成一次写入，再以读己之写方式召回。

1
只在服务端保存凭据
Root Key 只用于可信基础设施；外部集成使用 Scoped Token。
2
选择稳定的 Scope
把租户用户、Persona 或 Workspace 映射到长期稳定且不透明的 scope_name。
3
幂等写入
使用稳定 Message ID 和 Idempotency-Key 提交有序消息。
4
在模型调用前召回
把 prompt_evidence.content 与近期对话上下文一起交给回答模型。

curl -X POST "$TMCRA_BASE_URL/v1/scopes/user_123/ingest" \
  -H "Authorization: Bearer $TMCRA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ingest-session-42-v1" \
  -d '{
    "session_id": "session_42",
    "consistency": "read_your_writes",
    "slow_policy": "auto",
    "messages": [{
      "message_id": "msg_001",
      "role": "user",
      "content": "I prefer concise answers.",
      "timestamp": "2026-07-16T08:00:00Z"
    }]
  }'

身份与隔离

Tenant、Scope 与 Session 是三种不同边界。

tenant

由 Root API Key 标识的计费、凭据和管理边界。

scope_name

面向一个用户、Persona 或 Workspace 的持久记忆隔离边界。

session_id

Scope 内的一段有序对话，不从消息正文推断。

一致性

成功消息只提交一次，后续阶段可以独立恢复。

模式	适用场景	行为
`eventual`	下一轮不依赖本次写入。	立即返回异步 Job。
`read_your_writes`	下一次召回必须包含本次提交。	等待 Job 完成，再把 wait_for_job_id 传给召回。

消息成功提交后，不会因为慢图演化、索引、Webhook 投递或调用方回答阶段随后失败而被重复写入。

Webhooks

带签名、且不暴露记忆正文的生命周期通知。

Webhook 采用至少一次投递。请验证 HMAC-SHA256 签名、按 Event ID 去重并快速返回成功响应。Payload 只包含脱敏 Job 与 Scope 元数据，不包含 Prompt、消息、证据或凭据。

job.succeededjob.failedjob.cancelledingest.completedconsolidation.completedindex.completedexport.readyscope.deleted

错误与重试

根据操作语义重试，而不是只看状态码。

状态码	调用方处理
`400 / 422`	修正参数校验或请求语义后再重试。
`401 / 403`	更换或调整凭据权限，不要原样重试。
`404`	资源不存在，或超出当前凭据边界。
`409`	检查生命周期、幂等或一致性冲突详情。
`429`	遵守 Retry-After，并复用相同幂等键。
`5xx`	仅对 GET 和幂等写入进行有界退避重试。

SDK 与适配器

直接使用稳定 API 合同，并按发布状态评估各接入包。

Python SDKPREVIEW · tmcra-client

供试用评估的类型化同步与异步客户端。

TypeScript SDKPREVIEW · @tmcra/typescript

可测试的 Fetch 客户端，软件包接口仍可能调整。

MCP ServerPREVIEW · stdio

面向获批测试部署的本地兼容层。

LangGraphPILOT SOURCE · TMCRALangGraphMemory

已验证的源码适配器，不代表已有公开发行包。

OpenAI Agents SDKPILOT SOURCE · TMCRAAgentsMemory

已验证的源码适配器，仅通过获批试用提供。

Vercel AI SDKPILOT SOURCE · LanguageModelV3Middleware

已验证的源码中间件，仅通过获批试用提供。

Microsoft Agent FrameworkPILOT SOURCE · TmcraAIContextProvider

已验证的源码 Provider，仅通过获批试用提供。

查看平台适配指南

API 参考

32 个已记录的 API 操作。

访问凭据

签发、查看和撤销最小权限访问令牌。

GET/v1/session获取当前认证会话

返回当前 Token 对应的租户、凭据身份、权限和允许访问的记忆 Scope。

面向生产级 AI Agent 的持久记忆 API。

完成一次写入，再以读己之写方式召回。

只在服务端保存凭据

选择稳定的 Scope

幂等写入

在模型调用前召回

Tenant、Scope 与 Session 是三种不同边界。

成功消息只提交一次，后续阶段可以独立恢复。

带签名、且不暴露记忆正文的生命周期通知。

根据操作语义重试，而不是只看状态码。

直接使用稳定 API 合同，并按发布状态评估各接入包。

32 个已记录的 API 操作。

访问凭据

记忆读写

异步任务

记忆图谱

治理与生命周期

Webhook

用量