SurfSense 多智能体团队记忆机制update_memory 工具与共享长期记忆文档的设计与实践【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense导读SurfSense 的开源仓库中多智能体聊天系统multi_agent_chat为主 Agent 配备了一套记忆工具体系其中update_memory负责把对话中浮现的团队级长期事实决策、约定、架构笔记、流程、关键事实固化到工作区共享记忆文档中。本文以该工具在团队场景team下的提示词示例与描述文档为骨架结合仓库中工具实现与记忆服务源码完整讲解团队记忆的触发时机、文档格式规范、更新参数约定、容量预算与校验流程并给出可直接套用的示例与实操建议。读完你将掌握如何正确构造updated_memory全文替换参数、如何遵守仅追加不合并之外的编辑纪律、团队记忆与个人记忆的边界以及该机制在后端的完整落库链路。一、update_memory团队记忆工具概述在 update_memory/team/description.md 中该工具被定义为update_memory— Curate the teams shared long-term memory document for this workspace.它的职责是整理Curate当前工作区Workspace的团队共享长期记忆文档而非简单的记笔记。关键约束如下当前已有的记忆若有会出现在系统提示的team_memory中并附带**使用量与上限usage vs limit**信息供 Agent 管理预算触发时机团队成员明确要求记住/忘记某事或者对话中浮现出持久的团队决策、约定、架构笔记、流程、关键事实明确禁止绝不允许把个人记忆写入团队记忆如个人履历、个人偏好、仅面向单个用户的常驻指令需要过滤跳过一次性的聊天噪音一次性问答、问候语、会话临时事务如我们等会再聊。该工具的工厂函数实现在 main_agent/tools/update_memory.py 中def create_update_team_memory_tool( workspace_id: int, db_session: AsyncSession, llm: Any | None None, ): Factory for the team-memory update tool. del db_session tool async def update_memory(updated_memory: str) - dict[str, Any]: Update the teams shared memory document for this workspace. The current team memory is shown in team_memory. Pass the FULL updated markdown document, not a diff. try: async with async_session_maker() as db_session: result await save_memory( scopeMemoryScope.TEAM, target_idworkspace_id, contentupdated_memory, sessiondb_session, llmllm, ) return result.to_dict() except Exception as e: logger.exception(Failed to update team memory: %s, e) return { status: error, message: fFailed to update team memory: {e}, }从源码结构可以看出三个要点作用域Scope由枚举MemoryScope区分MemoryScope.USER个人记忆与MemoryScope.TEAM团队记忆定义于 app/services/memory/service.py团队记忆的落库目标是工作区target_idworkspace_id即记忆绑定在Workspace实体上团队成员共享同一份文档每次调用使用独立的短生命周期数据库会话async_session_maker()新建会话注释明确说明这是为了避免编译后的 Agent 缓存持有过期的请求级会话。二、核心示例解析团队记忆的两则黄金范例团队场景的示例文档 update_memory/team/example.md 提供了两则经典调用范式它们共同演示了团队记忆的完整写入模式示例一团队流程决策example user: Lets remember that we decided to do weekly standup meetings on Mondays → update_memory(updated_memory...\n\n## Product Decisions\n- 2025-03-15: Weekly standup meetings happen on Mondays\n...) /example要点拆解用户显式要求记住Lets remember that...这是最直接的触发信号归入## Product Decisions标题产品决策类条目格式为- YYYY-MM-DD: text即日期冒号内容的列表项前面带有...省略标记表示这是对完整文档的合并写入——updated_memory参数必须是包含既有内容的全文替换而非仅新增一行。示例二团队关键事实example user: Our office is in downtown Seattle, 5th floor → update_memory(updated_memory...\n\n## Project Facts\n- 2025-03-15: Office location is downtown Seattle, 5th floor\n...) /example要点拆解用户并非显式说记住但办公室地址属于团队关键事实durable key factAgent 应主动判断并写入归入## Project Facts标题项目事实类内容规范化把口语化的 Our office is in downtown Seattle 提炼为事实陈述 Office location is downtown Seattle, 5th floor。这两则示例的共同模式可以抽象为1识别持久信息 →2归入恰当##标题 →3以- YYYY-MM-DD: 规范化文本格式追加 →4返回合并了旧内容的完整 markdown。三、触发时机协议何时调用update_memory工具描述之外系统提示中还内置了一份独立的记忆协议memory protocol来约束调用时机。团队场景协议见 memory_protocol/team.mdAfter understanding each user message, check: does it reveal durable facts about the team — decisions, conventions, architecture notes, processes, or key facts? If yes, callupdate_memoryalongsideyour normal response — dont defer it to a later turn. Skip ephemeral chat noise (one-off Q/A, greetings, session logistics). Stay within the budget shown inteam_memory.协议的核心纪律有两点即时调用alongside识别到持久事实后必须与正常回复同轮调用update_memory不允许推迟到后续轮次——避免跨轮次丢失上下文噪音过滤skip一次性问答one-off Q/A、问候greetings、会话临时事务session logistics如我们待会 3 点开会这类时效性信息一律不写入。对应的个人记忆协议见 memory_protocol/private.md判断维度是用户角色、兴趣、偏好、项目、背景或常驻指令。两份协议一人一队边界清晰。四、团队记忆的文档格式规范4.1 标题体系四个推荐##分区根据 update_memory/team/description.md团队记忆推荐使用以下标题组织推荐标题适用内容## Product Decisions产品层面的决策如例会安排、功能取舍、排期规则## Engineering Conventions工程约定代码规范、CI/CD 约定、架构选择## Project Facts项目关键事实办公地点、技术栈、外部依赖、人员角色## Open Questions悬而未决的问题待确认、待决策事项条目统一采用- YYYY-MM-DD: text格式。示例文档中两则调用分别使用了## Product Decisions与## Project Facts正好覆盖决策与事实两类最常见的团队记忆。4.2 禁止的个人化标题团队记忆严禁创建个人化标题description.md 明确列出Do not create personal headings such as## Preferences,## Instructions,## Personal Notes, or## Personal Instructions.这一约束不仅在提示词层面生效还下沉到了服务端硬校验。在 app/services/memory/validation.py 中定义了禁止标题集合_FORBIDDEN_TEAM_HEADINGS { preferences, instructions, personal notes, personal instructions, }validate_memory_scope()会检查待写入内容一旦出现这些标题即返回错误从机制上杜绝个人记忆混入团队记忆。4.3 传统格式迁移description.md 特别注明如果既有记忆使用了传统(YYYY-MM-DD) [fact]标记格式新写入时应保留信息内容但整篇文档改用新格式heading-based markdown。这与记忆协议中的要求一致——它说明团队记忆存在格式演进历史Agent 需要对旧文档做一次格式归一化而不是新旧格式混用。五、updated_memory参数约定全文替换而非追加两则示例中updated_memory...\n\n## ...\n...的...标记指向一个至关重要的参数约定Args:updated_memory— FULL replacement markdown (merge and curate, dont only append).也就是说updated_memory是整个记忆文档的完整 markdown 内容Agent 必须读取team_memory中的当前全文将新条目合并进对应标题分区整理curate——必要时合并重复条目、精简过时内容使其保持在容量预算内把合并后的完整文档作为updated_memory传入。工具函数main_agent/tools/update_memory.py的 docstring 也再次强调Pass the FULL updated markdown document, not a diff.传入完整文档而不是差异补丁。这与以 diff 方式增量写入的设计形成鲜明对比全文替换让记忆文档始终处于整理后的稳定状态服务端无需处理复杂的增量合并语义也方便在保存时进行整体校验。六、动态上下文注入team_memory从哪来描述文档中反复提到team_memory内含 usage vs limit它的注入机制在 dynamic_context/team.md 中有说明team_memorycarries the durable shared context this team has built up — decisions, conventions, architecture notes, processes, key facts. It also reports current character usage versus the hard limit so you can manage the budget. Treat it as background colour for your answer, not as the task itself.三点设计意图值得注意权威性team_memory是运行时每轮动态插入的系统消息仅对当轮有效authoritative for this turn only预算透明除了记忆正文还报告当前字符用量 vs 硬上限Agent 据此决定是否裁剪背景而非任务记忆是回答的背景底色不应喧宾夺主——回答仍应以对话本身为主线。仓库中还有专门的内存中间件 main_agent/middleware/memory/middleware.py 负责装配这类动态上下文感兴趣可进一步阅读。七、后端落库链路从工具调用到持久化update_memory团队工具最终调用的是记忆服务的统一入口save_memory()app/services/memory/service.py完整流程如下归一化作用域_normalize_scope将MemoryScope.TEAM归一为字符串team定位目标_load_target按workspace_id查询Workspace实体service.py#L88-L103读取旧记忆_get_memory从Workspace.shared_memory_md字段读取当前内容团队记忆存储字段为shared_memory_md与个人记忆的memory_md区分见 service.py#L106-L116剥离前导废话strip_preamble_to_first_heading丢弃模型在第一个##标题前的多余前言validation.py#L29-L35无更新哨兵若内容命中NO_UPDATE/NO UPDATE/NO_CHANGE/NO CHANGE哨兵值直接返回statusno_opservice.py#L32-L39容量兜底重写若超过硬上限且提供了llm触发forced_rewrite让模型压缩重写逐项校验依次执行validate_memory_size硬上限校验、validate_heading_sanity无标题长文拦截、validate_memory_scope团队/个人标题边界校验规范化渲染render_memory_document(parse_memory_document(...))重新渲染为规范 markdown持久化写入Workspace.shared_memory_md并提交事务结果诊断返回SaveResult包含statussaved/error/no_op、memory_md、以及warnings、diff_warnings、format_warnings、notice等诊断字段供上层决策service.py#L47-L73。7.1 容量预算软上限与硬上限容量约束在 app/services/memory/validation.py 中定义MEMORY_SOFT_LIMIT 18_000 MEMORY_HARD_LIMIT 25_000软上限 18,000 字符超过后保存仍成功但会附加soft_limit_warning提示需要整理硬上限 25,000 字符validate_memory_size直接拒绝保存错误消息会引导模型合并相关条目、移除过时内容、缩短描述。这正是team_memory中 usage vs limit 的来源Agent 必须始终把文档控制在 25,000 字符内并尽量在 18,000 字符内运行。7.2 裁剪优先级description.md 明确了空间不足时的裁剪顺序When trimming, prioritise: decisions/conventions key facts current priorities.即决策/约定 关键事实 当前优先事项。决策与约定是团队最稳定、最有长期价值的资产优先保留当前优先事项时效性最强最先被裁剪。八、团队记忆 vs 个人记忆边界与互补同一工具名update_memory存在两个可见性变体update_memory/init.py 注释为 private and team visibility variants二者边界如下维度团队记忆team个人记忆private存储目标Workspace.shared_memory_mdUser.memory_md作用域枚举MemoryScope.TEAMMemoryScope.USER推荐标题## Product Decisions、## Engineering Conventions、## Project Facts、## Open Questions## Facts、## Preferences、## Instructions条目格式- YYYY-MM-DD: text- YYYY-MM-DD: text称呼约定团队视角无个人名称要求使用user_name中的名字如 Alex prefers…且禁止单独存储名字禁止项禁止## Preferences、## Instructions等个人化标题无团队标题限制个人记忆的示例文档 update_memory/private/example.md 还演示了事实更新的处理方式user: I actually moved to Tokyo last month → update_memory(updated_memory...\n\n## Facts\n- 2025-03-15: Alex lives in Tokyo (previously London)\n...)注意它保留旧信息上下文previously London并让日期反映本次记录时间——这与团队记忆的 curate 理念一脉相承更新不是覆盖而是保留演化的整理。九、实操速查团队记忆正确写法 Checklist综合示例文档、描述文档与源码约束编写团队记忆时可对照以下清单只写团队级信息决策、约定、架构笔记、流程、关键事实绝不写入个人偏好或用户专属指令过滤噪音一次性问答、问候、会话临时事务不写全文替换updated_memory必须是包含旧内容的完整 markdown禁止只传新增行归类标题优先使用## Product Decisions、## Engineering Conventions、## Project Facts、## Open Questions四个推荐分区条目格式- YYYY-MM-DD: text日期为实际记录日遵守预算控制在 18,000 字符软以内绝不突破 25,000 字符硬整理而非堆砌合并重复、删除过时、按决策/约定 关键事实 当前优先事项顺序裁剪格式归一遇到传统(YYYY-MM-DD) [fact]标记时保留信息、整篇改写为新格式即时调用识别到持久事实后与回复同轮调用不推迟。十、小结update_memory团队变体是 SurfSense 多智能体系统实现团队级长期记忆的关键工具它以全文替换式 markdown 文档为载体通过##分区标题 日期条目的结构化格式、18k/25k 字符预算、服务端标题/容量/格式三层校验见 app/services/memory/validation.py保证了共享记忆的质量与可控性。本文所解析的两则示例team/example.md代表了团队决策与团队事实两类最典型的记忆写入场景配合工具描述文档team/description.md与后端实现main_agent/tools/update_memory.py、app/services/memory/service.py即可完整理解并复现这一记忆机制的调用规范与底层原理。【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考