为你的编码代理提供你专属的记忆

Hugging Face Blog 工具

摘要

Funes 是一个为编码代理设计的持久记忆层,它允许回忆过去的会话痕迹,本地运行并与 Hugging Face 数据集集成。

暂无内容
查看原文
查看缓存全文

缓存时间: 2026/09/03 11:49

为你的编码代理赋予自主记忆

来源:https://huggingface.co/blog/funes
我在多台设备上工作,并会根据任务切换不同的编码代理。每个代理都视我的项目为陌生领域。“上周二的推理“会在会话结束后消失。每台主机上的每个新代理都从零开始。

今年早些时候的《软件遗忘:代理痕迹即记忆》(https://huggingface.co/blog/huggingface/agent-traces-as-memory) 一文曾论证:编码代理本身就在产生我们不断丢失的记录。当它们搜索代码库、尝试方法、遭遇错误、查阅文档并调整方向时,留下的详细记录不仅包含“做了什么“,更记录了“为什么这样做“。

虽然诊断准确,但痕迹仅是潜在的记忆。代理的会话日志仍只是档案库。你无法通过grep在十万条记录中找到“我们为什么放弃流解析器“的原因。要让代理在工作时利用这些痕迹,必须进行索引、检索、排序并明确溯源。

这正是funes (https://github.com/huggingface/funes) 提供的功能。它为你的代理(Claude Code、Codex、pi和Hermes)构建持久记忆层。它基于设备上已有的会话构建,通过一条命令即可本地运行并融入代理的常规工作流。当你需要时,它还能同步到你拥有的Hugging Face数据集(默认为私有)。

将记忆融入现有代理

funes是一个独立二进制文件。其默认推理后端无机器学习运行时依赖,嵌入和重排序都在你的设备上执行。安装方法:

curl -fsSL https://huggingface.co/buckets/huggingface/funes/resolve/install.sh | sh

然后将其添加到代理:

funes add claude    # 或:codex、pi、hermes

这一条add命令将构建首个索引,为代理提供recall和get工具,并安装自动索引已完成轮次的机制。索引采用增量方式,新运行只添加新轮次而非重新嵌入整个历史记录。更早更深层的内容可通过有限步骤进行回填。

之后你只需正常工作。当任务涉及过往决策、依据或发现时,代理可主动调用recall。你无需记忆旧会话或将其上下文粘贴到新会话中。

编码代理自主调取funes,回忆早期决策,并基于检索到的会话(https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/funes/recall.gif)给出答案。

添加funes后,回忆发生在对话内部。代理自主调取记忆并注明答案来源的会话。

recall返回原始文本而非摘要,并精确显示来源(代理、时间戳、会话和轮次)。每个结果都包含get命令,可打开完整轮次及其上下文。

底层通过一个确定性流水线,将所有支持的痕迹解析为统一的轮次-块结构,进行分块,使用固定的本地模型生成嵌入,并写入本地Lance数据集。查询时结合向量搜索和BM25搜索,融合排序结果,使用交叉编码器对候选项重排序,根据时效性重新加权,并附加相邻数据块。

这种设计赋予funes三个重要特性:

  • 跨代理统一记忆:Claude Code、Codex、pi和Hermes都写入相同结构。recall可跨越它们的历史记录,每次命中都标明来源代理。
  • 原始证据保持完整:写入时不会提炼为事实。结果总可追溯至产生它的轮次。
  • recall默认本地运行:无需账户或Hub仓库。托管模型不处理你的会话进行索引;嵌入和重排序在设备上运行,由你的编码代理进行推理。

单设备上的“代理作为陌生人“问题已解决。但当下一个代理在其他设备运行时,记忆将变得更有用。

记忆是数据集,不是服务

要让记忆跟随你的工作,在添加funes到代理时绑定一个记忆:

funes add codex acme/funes-memory

绑定会将当前记忆发布到指定位置。funes随后会保持同步,在本地索引每个轮次并在会话边界时发布。代理在整个过程中都会从中回忆。在另一台设备运行相同命令,记忆将随之迁移。

底层原理是:本地记忆是Lance数据集,共享记忆则是你拥有的Hugging Face数据集(默认为私有)。

在数据到达Hub前,凭证在索引阶段已被删除。发布时会再次扫描每个数据块,排除任何疑似密钥的内容。背后的扫描器文档见SECURITY.md (https://github.com/huggingface/funes/blob/main/SECURITY.md),包含其覆盖范围说明。

当代理读取远程记忆时,funes会在本地缓存数据集文件,因此热查询可恢复本地速度。Hub提供其已为其他数据集支持的所有权、访问控制、版本管理和分发功能。你的记忆不会变成独立记忆服务中的账户,也无需通过API租回使用。

先查询,后集成

recall专为代理设计。当你想亲自向记忆提问时,使用ask。它默认读取本地记忆:

funes ask claude "我们当时对流解析器做了什么决定"

或将其指向共享记忆。我们发布了funes开发过程的记忆(https://huggingface.co/datasets/huggingface/funes-memory),因此你可以询问funes为何如此设计而无需创建自己的记忆:

funes ask claude "为什么funes采用追加模式" --memory huggingface/funes-memory

向发布的funes记忆询问其追加模式原因;funes检索相关会话,编码代理据此回答(https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/funes/ask.gif)

funes ask是funes add的只读单问版本。它检索相关段落,交由编码代理处理,并返回注明来源的可靠答案。不会安装集成组件或改变代理的持久化设置。

检索未命中时不会掩饰。如果段落不支持答案,代理会明确说明。你可以重新表述问题,或将funes添加到代理,使其能在正常工作中迭代搜索记忆。

切换代理不丢失线索

共享记忆不依赖于创建它的代理或模型。本周在Claude Code中开始任务,下周在Codex中继续,第二个代理能回忆起第一个代理的推理。使用pi的本地模型或Hugging Face路由器提供的模型,然后返回Claude。

Claude Code选择嵌入模型,随后Codex在独立会话中回忆该决定(https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/funes/cross-agents.gif)

Claude做出决定;钩子索引它;Codex在另一会话中回忆。演示中较早的命中记录是同一实验的更早录制:追加模式记忆也记住了排练过程。

这在多个层面都很重要:

  • 跨设备:将每个代理绑定到一个记忆,从任意主机回忆历史记录。
  • 跨团队:新队友的代理第一天就能检索数月来的决策,包括从未进入拉取请求的死胡同和依据。
  • 伴随开源项目:维护者可以发布版本背后的会话,在推送时注明名称。可将其视为可搜索的CLAUDE.md,记录项目演变历程,而非需要不断重写的页面。任何人都可通过\-\-memory读取公开记忆。

发布的记忆带有数据集卡片和funes标签,使其在Hub上(https://huggingface.co/datasets?other=funes)易于识别和发现。Hub已托管开源权重和数据集。funes增加了开源工作记忆。它保存项目背后的决策、失败方法和依据,可供其他代理查询并追溯至产生它们的会话。

逃离长会话的最经济方式

长时间的调查会膨胀会话,以至于每轮携带上下文的成本超过实际工作成本。常规方案是让代理压缩并继续,或编写交接文档重新开始。回忆是第三种方案,因此我们在交接与回忆基准测试(https://huggingface.co/datasets/dacorvo/funes-handoff-recall-benchmark/blob/main/results/README.md)中对它们进行了对比:两个任务的答案若无先前会话知识则无法重构。

压缩是大多数代理的默认方案,也是三者中唯一结果分化的:在一个任务成功,另一个从未成功。失败时,其摘要扁平化了重要发现。回忆返回原始段落,因此发现无需经受摘要考验。

回忆在两项任务上都是最经济的方案,其中一项比书写交接文档便宜8倍,另一项便宜4倍。

两项任务中五个通道的成功任务加权令牌数,回忆均为最短柱形(https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/funes/handoff-recall-cost.jpg)

每根柱形的浅色部分是准备通道的一次性费用(交接或压缩),在首个问题提出前支付且仅计算一次。叉号表示从未成功的通道,因此无每成功成本。

停止从零开始

“思考即是遗忘差异、归纳概括、形成抽象。” —— 豪尔赫·路易斯·博尔赫斯,《博闻强记的富内斯》

你的代理已写下记录。funes位于github.com/huggingface/funes (https://github.com/huggingface/funes),只需一条命令即可将这份记录转化为下一个代理可读的记忆,无论你正在使用哪台设备。

基于开源构建

funes并未创新太多。它依赖足够本地运行的开源嵌入模型、Lance (https://github.com/lancedb/lance)支持廉价增量写入的追加模式数据集,以及Hub的数据集缓存与内容去重机制。其工作在于将这些技术整合为代理真正可用的记忆。

funes同样是开源的。提交issue (https://github.com/huggingface/funes/issues) 反馈从安装问题到召回失败,或希望支持的任何代理。

相似文章

rohitg00/agentmemory

GitHub Trending (daily)

agentmemory 是一个开源的持久化记忆层,专为 AI 编程智能体(Claude Code、Cursor、Gemini CLI、Codex CLI 等)设计。它通过知识图谱、置信度评分和混合搜索技术,借助 MCP、Hooks 或 REST API,为智能体提供跨会话的长期记忆能力。该项目基于 iii 引擎构建,无需外部数据库,提供 51 个 MCP 工具。