记忆与上下文

Clouisle 用两层机制解决对话的连续性与成本问题：

1. 对话内上下文（消息分支 + 单次上下文摘要）：会话进行时的实时历史。当组装好的请求超过预算时，系统把较早的历史压缩成一条摘要，只保留最近一段原文，避免模型窗口溢出。
2. 跨会话记忆图谱（Memory Graph）：跨越不同会话的持久知识网络，以实体和有向关系沉淀用户偏好、项目背景与核心事实。

启用跨会话记忆

1. 打开 Agent 编排 > 记忆。
2. 开启启用记忆（enable_memory，默认关闭）。
3. 设置每次检索的最大记忆数，范围 1-50，默认 10。
4. 按需开启自动提取记忆（默认开启）。
5. 保存并发布 Agent。用户在不同会话中对话时，Agent 会自动召回此前记录的事实。

Agent 的记忆配置（memory_config）：

记忆图谱（Memory Graph）

持久记忆不是扁平文本，而是由**实体（Entities）与关系（Relations）**构成的有向知识拓扑网络。

可在个人菜单 > 我的记忆（/app/memories）或管理后台（/memories）中可视化探索和管理。

实体类型（Entity Types）

系统预定义了 10 种实体类型：

关系类型（Relation Types）

实体间可建立 9 种有向关系，用于图遍历（Subgraph Traversal）：

图谱管理功能

• 多布局可视化：支持网格布局（Grid）、层次布局（Hierarchical）与径向布局（Radial），并支持放大、缩小与适应视图（Fit View）。
• 实体检索与过滤：可按关键词搜索实体名称与描述，或按实体类型进行单选/多选过滤。
• 关系详情抽屉：点击实体查看其出向关系（Outgoing Relations）与入向关系（Incoming Relations），可直接编辑属性字典（JSON Properties）或删除特定单向关系。
• 批量与安全删除：支持框选模式（Select Mode）批量删除废弃或敏感记忆实体；删除实体会自动级联清理其关联的所有出入向关系及向量嵌入。

记忆检索与时间衰减（Decay）

当 Agent 发起记忆检索时，系统综合向量语义相似度与时间衰减计算加权综合得分：

综合得分 = (1 - w) × 向量相似度 + w × 时间得分

• 时间衰减计算：采用半衰期指数衰减模型（exp(-ln2 / 半衰期 × 天数)），默认半衰期为 30 天（30 天前更新且再未变动的记忆，其时间得分减半）。
• 权重配置：时间衰减权重 w 默认为 0.15，语义相似度占 0.85，兼顾语义相关性与近期新鲜度。
• 时间窗口过滤：检索时支持指定 time_window_days，只召回近 $N$ 天内创建或更新的记忆事实。
• 子图拓展（Subgraph）：在获得命中实体后，支持以实体为中心沿关系边向外拓展 1-3 层子图（max_depth，默认 1；种子实体最多 5 个；方向 incoming / outgoing / both），为 LLM 提供结构化的网状背景信息。

管理后台自动提取

管理员可在站点设置 > 记忆（/site-settings/memory）配置待处理用户轮次的后台记忆提取：

长对话如何压缩

上下文压缩默认开启（context_compression_config.enabled = true），只有一种动作：把较早的历史交给模型生成一条摘要（策略名 preflight_summary），用它替换掉那段历史，并保留最近一段原文轮次。

预算计算

压缩按模型上下文窗口计算可用输入预算：

输入预算 = 上下文窗口 − 输出预留 − 安全余量

• 上下文窗口：取模型自身配置；缺省时回退到 32000。
• 输出预留：默认 4000，并取 min(4000, 模型最大输出, 上下文窗口 ÷ 3)。
• 安全余量：固定 1000。

触发条件

当组装好的请求 token 数超过触发预算时生成摘要：

触发预算 = min(上下文窗口 − max(窗口 × 15%, 输出预留), 输入预算)

以默认 32,000 窗口为例：输出预留 4,000、安全余量 1,000、输入预算 27,000，触发预算 min(32000 − 4800, 27000) = 27000，即约窗口的 84%。SSE 事件里上报的 trigger_ratio 常量固定为 0.9，但真正决定何时触发的是上面的触发预算。

保留与生成

• 保留最近原文：保留尾部最多 20000 个 token 的原文；该上限还会被压到「系统提示 + 摘要 + 当前轮 + 输出预留」都能装下的范围。最新一轮永远保留；工具调用尚未闭合的轮次不会被切开。
• 摘要长度：默认 1000 token（summary_max_tokens，范围 128-8000），并会截断到预算允许的长度。
• 摘要生成失败重试：最多 3 次尝试，每次间隔 2 秒，单次超时 180 秒；全部失败则返回 context_summarization_failed。
• 摘要持久化：摘要文本与水印（已覆盖的最后一条消息）保存在会话上（context_summary_text / context_summary_watermark_id），后续轮次复用同一条摘要并增量更新，不会无限叠加。
• 压缩后仍超预算：抛出 ContextLengthError（retryable: false，原因 context_summary_did_not_fit），不会无限重试。

流式 API 在 emit_sse_events 为真（默认）时发送 compression_start 与 compression_end，用于解释本轮为何整理历史；compression_end 携带 before_tokens、after_tokens、input_budget、summary_saved_tokens 等字段。

API 端点

# 列出记忆实体（支持按 entity_type 过滤与分页）
GET /api/v1/memories/entities?page=1&page_size=20&entity_type=preference

# 创建 / 更新 / 删除实体
POST   /api/v1/memories/entities
GET    /api/v1/memories/entities/{entity_id}
PUT    /api/v1/memories/entities/{entity_id}
DELETE /api/v1/memories/entities/{entity_id}

# 列出 / 创建 / 删除关系
GET    /api/v1/memories/relations?entity_id={entity_id}&relation_type=uses
POST   /api/v1/memories/relations
DELETE /api/v1/memories/relations/{relation_id}

# 获取完整或局部记忆图谱
GET /api/v1/memories/graph?entity_ids={id1}&entity_ids={id2}&max_depth=2

排查

• 未记住偏好：确认 Agent 已启用记忆、信息达到重要性阈值，并使用同一已登录用户。
• 回复忽略很早的细节：长会话可能已把早期历史压缩成摘要；把关键约束重新陈述，或开启新会话。
• 压缩频繁：检查模型上下文长度、输出预留和工具结果体积；工具返回的大段内容会更快撑满预算。
• 记忆图谱存在错误事实：前往 /app/memories，通过搜索定位错误实体，点击编辑修正描述，或直接删除。