长期记忆（Agent Memory）

Mem0 API 兼容性

已使用 Mem0 的项目可以直接切换到 Context0，不需要改代码。Context0 完全兼容 Mem0 v1 全部 7 个端点（/v1/memories 的增删改查、搜索与清空）。唯一差异：DELETE /v1/memories 对应 DELETE /v1/memories/clear。

Context0 还提供 V3 增强端点，兼容 Mem0 v1.1 SDK：

三层记忆模型

对话写入后，Context0 自动完成三层蒸馏。可以类比为：L2 是录音笔（完整录下全部内容），L1 是笔记本（提取关键信息），L0 是人物档案（一页纸了解一个人）。

三层蒸馏的数据流向如下：

对话写入 ──► L2 原始对话 ──LLM 抽取──► L1 原子事实 ──实体识别──► L0 实体画像
           （不可变，溯源）         （单条事实，带时效）        （结构化实体卡）

Token 经济性：一个用户累计 1000 句对话（约 30K token），经两次蒸馏后压缩至约 0.75K token 的 L0 画像，信息密度远高于散落的原始对话。

记忆作用域

每条记忆都归属一个作用域，作用域决定记忆的可见范围与生命周期：

记忆生命周期

一条记忆从写入到演化，经历以下阶段：

写入 → 异步蒸馏(L2→L1→L0) → 检索召回 → 热度衰减/失效标记 → Dream 夜间演化

写入记忆

curl -X POST "$HOST/v1/context/ingest" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_001",
    "user_id": "user_001",
    "messages": [
      {"role": "user", "content": "项目偏好 TypeScript，ORM 选 Prisma"},
      {"role": "assistant", "content": "好的，已记下技术栈选型"}
    ]
  }'

curl -X POST "$HOST/v1/memories" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "鉴权方案选 NextAuth"}
    ],
    "user_id": "user_001",
    "metadata": {"source": "manual"}
  }'

{
  "results": [
    {
      "id": "mem_124",
      "memory": "鉴权方案选 NextAuth",
      "subject": "鉴权",
      "validity": "durable",
      "event": "ADD"
    }
  ]
}

检索记忆

• 语义搜索：POST /v1/memories/search（V1、V2、V3 三个版本可选）。

  curl -X POST "$HOST/v2/memories/search" \
    -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
    -d '{
      "query": "技术栈选型",
      "user_id": "user_001",
      "limit": 10
    }'

  参数	必填	说明
  query	是	查询文本，按语义匹配相关记忆
  user_id	否	限定用户；User Key 自动绑定自身
  limit	否	返回条数 [1,200]，默认 10（别名 top_k 亦可）
  cosine_threshold	否	相似度下限 [0,1]，V1/V2 默认 0.2，V3 默认 0.1
  vector_only	否	true 时仅向量召回，关闭 BM25
  filters	否	时间范围等附加过滤

  三个版本的区别：

  路径	L1 事实	L2 源文本	响应格式
  POST /v1/memories/search	返回	不返回	裸 JSON 数组
  POST /v2/memories/search	返回	返回（默认开启）	裸 JSON 数组
  POST /v3/memories/search	返回	返回	{"results": [...]} 信封

  说明

  V3 端点与 Mem0 v1.1 SDK 对齐，user_id 等实体参数推荐放在 filters map 内传递。

• 获取单条记忆：GET /v1/memories/{id}。

  curl "$HOST/v1/memories/mem_123" -H "X-API-Key: $API_KEY"

在对话中使用记忆

curl -X POST "$HOST/v1/context/assemble" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_002",
    "user_id": "user_001",
    "query": "如何部署应用？",
    "token_budget": 4000,
    "include_memories": true,
    "recall": {"top_k": 8}
  }'

{
  "code": 0,
  "data": {
    "prompt_blocks": [
      {
        "role": "system",
        "tag": "user_profile",
        "content": "用户偏好 TypeScript + Prisma，鉴权选 NextAuth",
        "tokens": 30,
        "sources": []
      },
      {
        "role": "system",
        "tag": "knowledge",
        "content": "部署流程：1. 准备 .env ...",
        "tokens": 120,
        "sources": ["runbook.pdf"]
      }
    ]
  }
}

# 1. 搜索相关记忆
curl -X POST "$HOST/v1/memories/search" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "技术栈偏好", "user_id": "user_001", "limit": 5}'

# 2. 将返回的记忆内容拼入 system prompt，发送给 LLM

管理记忆

记忆的查看、修改、置顶、失效标记与统计由以下端点提供：

• 置顶记忆示例：

  curl -X POST "$HOST/v1/memories/mem_123/pin" -H "X-API-Key: $API_KEY"

• 标记失效示例：

  curl -X POST "$HOST/v3/memories/mem_123/invalidate" -H "X-API-Key: $API_KEY"

• 编辑 L0 实体卡示例：

  curl -X POST "$HOST/v3/entity_cards/card_1_2_alice/edit" \
    -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
    -d '{
      "role": "资深后端工程师",
      "preferences": ["Java", "Spring Boot"],
      "attributes": {"domain": "分布式数据库"}
    }'

Dashboard 操作入口

除 API 外，您也可以在 Dashboard 中完成记忆的浏览、编辑与检索：

• 在 Dashboard 的记忆页面选择实体页签，可浏览所有 L0 实体卡并编辑 role、preferences、attributes 等字段。

• 在 Dashboard 的记忆页面选择搜索页签，输入查询文本后结果按相似度排序，支持时间范围筛选和反馈（赞或踩）。

自定义蒸馏规则

蒸馏规则控制「从对话中提取什么、怎么提取」。您可以定义让 Context0 重点关注的内容类型。优先级链：ingest 请求的 custom_instructions > member 级规则 > workspace 默认规则 > 内置默认。

• API参考

  • 设置成员级规则（数据面，User Key）：

    curl -X PUT "$HOST/v1/memories/distill-prompt" \
      -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
      -d '{
        "custom_prompt": "重点提取技术栈选型和架构决策，忽略闲聊内容",
        "enabled": true
      }'

  • 设置 workspace 级规则（管理面，Owner Key）：

    curl -X PUT "$OPS_HOST/ops/distill-prompt" \
      -H "X-API-Key: $OWNER_KEY" -H "Content-Type: application/json" \
      -d '{
        "custom_prompt": "提取技术决策、项目约定和团队规范",
        "enabled": true
      }'

• Dashboard操作

  在 Dashboard 的记忆页面选择蒸馏规则页签，可选择成员、编辑提示词、查看生效状态。

Dream 夜间演化

Dream 是 Context0 的后台演化引擎，定期自动执行以下任务：

• 偏好衰减：长期未被召回的偏好自动降权。

• 矛盾检测：发现同一主题的冲突记忆并标记。

• 实体归纳：从 L1 事实聚合生成或更新 L0 实体画像。

手动触发 Dream（Owner Key）示例：

curl -X POST "$HOST/v1/dream/run" \
  -H "X-API-Key: $OWNER_KEY" -H "Content-Type: application/json" \
  -d '{}'

记忆晋升知识库

记忆晋升将同一主题下的高价值记忆（L1 事实）聚合为一篇知识库文档。生成的文档经人工审核后入库，之后像普通文档一样被检索和引用。端到端的场景化实践请参见让您的 Agent 越用越懂您的业务。