Skip to Content
FacetX

记忆系统

💾

记忆让 FacetX 在多个会话中保留有用信息。Agent 记住用户偏好、项目背景和反复出现的事实，这样它可以在不每次从零开始的情况下给出更好的响应。

记忆是 FacetX Harness 的一个运行时功能。它不是简单的对话日志，而是跨多个独立会话持久化、在未来对话中影响 Agent 行为的结构化事实和上下文摘要存储。

记忆存储什么

记忆存储包含几类信息：

  • 工作上下文：用户正在进行的项目摘要、目标和反复出现的话题。
  • 个人上下文：Agent 学到的偏好、沟通风格和其他用户特定细节。
  • 近期关注：最近的关注领域和活跃任务。
  • 历史：近几个月的上下文、早期背景和长期事实。
  • 事实：Agent 从对话中提取的离散具体事实（例如偏好的工具、团队名称、项目约束）。

每个类别随着 Agent 从持续对话中学习而随时间更新。

工作原理

记忆支持两种运行模式：

  1. 两种模式都会注入：每次对话开始时，Agent 当前记忆以受控的 token 预算（max_injection_tokens）注入到系统提示中。
  2. 中间件模式（默认）：MemoryMiddleware 在每次 Lead Agent 轮次结束后运行，过滤对话、排队后台更新并自动提取新事实。更新通过 debounce_seconds 防抖以批量处理快速变化。
  3. 工具模式（实验性）：FacetX 注册 memory_search、memory_add、memory_update、memory_delete 四个工具，并跳过 MemoryMiddleware。模型自行决定何时搜索或写入记忆，因此效果取决于模型的工具调用行为。这些显式 CRUD 工具不是被动的陈旧性复核路径；启用工具模式意味着运营方选择由模型主动更新/删除记忆，而不是依赖中间件的陈旧性保护栏。
  4. 按 Agent 记忆：当自定义 Agent 激活时，其记忆独立于全局记忆存储。这保持不同 Agent 的知识隔离。

在工具模式中，四个 memory_* 工具名是保留名。如果 MCP 服务或自定义工具已经使用 memory_search、memory_add、memory_update 或 memory_delete，已有工具会保留该名称，冲突的记忆工具会被跳过并记录告警。

配置

memory:
  enabled: true
 
  # 运行模式：
  #   middleware - 默认；每轮结束后被动后台提取
  #   tool - 实验性；模型直接调用 memory_* 工具
  mode: middleware
 
  # 全局记忆文件的存储路径。
  # 默认：{base_dir}/memory.json（解析为 backend/.facetx/memory.json）
  # 绝对路径按原样使用，相对路径相对于 base_dir 解析。
  storage_path: memory.json
 
  # 存储类（默认：基于文件的 JSON 存储）
  storage_class: FacetX.agents.memory.storage.FileMemoryStorage
 
  # 处理排队记忆更新前等待的秒数（防抖）
  debounce_seconds: 30
 
  # 记忆更新提取使用的模型（null = 使用默认模型）
  model_name: null
 
  # 要存储的最大事实数
  max_facts: 100
 
  # 存储事实所需的最低置信度分数（0.0–1.0）
  fact_confidence_threshold: 0.7
 
  # 是否将记忆注入到系统提示中
  injection_enabled: true
 
  # 注入到系统提示的最大 token 数
  max_injection_tokens: 2000

全局记忆与按 Agent 记忆

FacetX 支持两级记忆：

  • 全局记忆：存储在 {base_dir}/memory.json。在没有特定 Agent 激活或 Agent 没有按 Agent 记忆文件时使用。
  • 按 Agent 记忆：存储在 {base_dir}/agents/{agent_name}/memory.json。当自定义 Agent 激活时使用，使该 Agent 学到的知识保持独立。

MemoryMiddleware 根据请求配置中的活跃 agent_name 自动选择正确的记忆文件。

用于记忆存储的 Agent 名称通过 AGENT_NAME_PATTERN 验证，以确保文件系统安全。

存储位置

默认情况下，记忆文件存储在后端基础目录下：

  • 基础目录：backend/.facetx/
  • 全局记忆：backend/.facetx/memory.json
  • 按 Agent 记忆：backend/.facetx/agents/{agent_name}/memory.json

你可以用 storage_path 字段更改存储路径。相对路径相对于基础目录解析；使用绝对路径可以将记忆存储在自定义位置。

自定义存储后端

storage_class 字段允许你用自定义实现替换默认的基于文件的存储。任何继承 MemoryStorage 并实现 load()、reload() 和 save() 方法的类都可以使用：

memory:
  storage_class: mypackage.storage.RedisMemoryStorage

如果配置的类无法加载，系统回退到默认的 FileMemoryStorage 并记录错误。

禁用记忆

完全禁用记忆：

memory:
  enabled: false

保留记忆存储但阻止注入到系统提示：

memory:
  enabled: true
  injection_enabled: false
配置中间件
简介